From 62e9eb2d25846a609e45ae8d455585cb0af17cb8 Mon Sep 17 00:00:00 2001 From: plebhash Date: Thu, 30 Apr 2026 12:46:33 -0300 Subject: [PATCH 1/3] allow implementations to use error codes for automated actions --- 03-Protocol-Overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index 62e1cbe..b63e30e 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -215,7 +215,7 @@ A device processing `SubmitSharesExtended` **MUST scan for TLV fields** matching ## 3.5 Error Codes The protocol uses string error codes. -The list of error codes can differ between implementations, and thus implementations MUST NOT take any automated action(s) on the basis of an error code. +Implementations MAY use error codes for automated actions. The list of error codes can differ between implementations, and therefore implementations MUST do a logging no-op for unknown error codes. Implementations/pools SHOULD provide documentation on the meaning of error codes and error codes SHOULD use printable ASCII where possible. Furthermore, error codes MUST NOT include control characters. From 9fead066cd52bbca247d34d0f765af91715f9546 Mon Sep 17 00:00:00 2001 From: plebhash Date: Wed, 13 May 2026 13:00:04 -0300 Subject: [PATCH 2/3] remove all error code suggestions --- 03-Protocol-Overview.md | 18 +---------------- 05-Mining-Protocol.md | 29 +++------------------------- 06-Job-Declaration-Protocol.md | 5 +---- 07-Template-Distribution-Protocol.md | 5 ----- 4 files changed, 5 insertions(+), 52 deletions(-) diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index b63e30e..eab40a9 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -219,16 +219,6 @@ Implementations MAY use error codes for automated actions. The list of error cod Implementations/pools SHOULD provide documentation on the meaning of error codes and error codes SHOULD use printable ASCII where possible. Furthermore, error codes MUST NOT include control characters. -To make interoperability simpler, the following error codes are provided which implementations SHOULD consider using for the given scenarios. -Individual error codes are also specified along with their respective error messages. - -- `unknown-user` -- `too-low-difficulty` -- `stale-share` -- `unsupported-feature-flags` -- `unsupported-protocol` -- `protocol-version-mismatch` - ## 3.6 Common Protocol Messages The following protocol messages are common across all of the protocols described in this BIP. @@ -277,13 +267,7 @@ If flags is 0, the error is a result of some condition aside from unsupported fl | Field Name | Data Type | Description | | ---------- | --------- | ----------------------------------------------------------- | | flags | U32 | Flags indicating features causing an error | -| error_code | STR0_255 | Human-readable error code(s), see Error Codes section below | - -Possible error codes: - -- `unsupported-feature-flags` -- `unsupported-protocol` -- `protocol-version-mismatch` +| error_code | STR0_255 | Human-readable error code(s) | ### 3.6.4 `ChannelEndpointChanged` (Server -> Client) diff --git a/05-Mining-Protocol.md b/05-Mining-Protocol.md index 6635ee7..c2e73a8 100644 --- a/05-Mining-Protocol.md +++ b/05-Mining-Protocol.md @@ -266,12 +266,7 @@ Sent as a response for opening an extended channel. | Field Name | Data Type | Description | | ---------- | --------- | ----------------------------------------------------------- | | request_id | U32 | Client-specified request ID from OpenMiningChannel message | -| error_code | STR0_255 | Human-readable error code(s), see Error Codes section below | - -Possible error codes: - -- `unknown-user` -- `max-target-out-of-range` +| error_code | STR0_255 | Human-readable error code(s) | ### 5.3.7 `UpdateChannel` (Client -> Server) @@ -294,12 +289,7 @@ Sent only when `UpdateChannel` message is invalid. When it is accepted by the se | Field Name | Data Type | Description | | ---------- | --------- | ----------------------------------------------------------- | | channel_id | U32 | Channel identification | -| error_code | STR0_255 | Human-readable error code(s), see Error Codes section below | - -Possible error codes: - -- `max-target-out-of-range` -- `invalid-channel-id` +| error_code | STR0_255 | Human-readable error code(s) | ### 5.3.9 `CloseChannel` (Client -> Server, Server -> Client) @@ -383,14 +373,7 @@ This delayed validation can occur when a miner gets faster updates about a new p | --------------- | --------- | ----------------------------------------------------------- | | channel_id | U32 | Channel identifier | | sequence_number | U32 | Submission sequence number for which this error is returned | -| error_code | STR0_255 | Human-readable error code(s), see Error Codes section below | - -Possible error codes: - -- `invalid-channel-id` -- `stale-share` -- `difficulty-too-low` -- `invalid-job-id` +| error_code | STR0_255 | Human-readable error code(s) | The illustration below also assumes a mining server that acknowledges every 10 successful submissions. @@ -539,12 +522,6 @@ After receiving it, the miner can start submitting shares for this job immediate | request_id | U32 | Client-specified identifier for pairing responses. Value from the request MUST be provided by upstream in the response message. | | error_code | STR0_255 | Reason why the custom job has been rejected | -Possible errors: - -- `invalid-channel-id` -- `invalid-mining-job-token` -- `invalid-job-param-value-{}` - `{}` is replaced by a particular field name from `SetCustomMiningJob` message - ### 5.3.21 `SetTarget` (Server -> Client) The server controls the submission rate by adjusting the difficulty target on a specified channel. diff --git a/06-Job-Declaration-Protocol.md b/06-Job-Declaration-Protocol.md index 877487e..dfe4a81 100644 --- a/06-Job-Declaration-Protocol.md +++ b/06-Job-Declaration-Protocol.md @@ -232,13 +232,10 @@ This should be a trigger for fallback into some other Pool+JDS or solo mining. | Field Name | Data Type | Description | | ------------- | --------- | ------------------------------------------------------ | | request_id | U32 | Identifier of the original request | -| error_code | STR0_255 | | +| error_code | STR0_255 | Human-readable error code(s) | | error_details | B0_64K | Optional data providing further details to given error | -Possible error codes: -- `invalid-mining-job-token` -- `invalid-job-param-value-{}` - `{}` is replaced by a particular field name from `DeclareMiningJob` message ### 6.4.7 `ProvideMissingTransactions` (Server->Client) diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index 1469d38..dfc8f3c 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -166,11 +166,6 @@ To work around the limitation of not being able to negotiate e.g. a transaction | template_id | U64 | The template_id corresponding to a NewTemplate/RequestTransactionData message | | error_code | STR0_255 | Reason why no transaction data has been provided | -Possible error codes: - -- `template-id-not-found` - used when the template being referenced is too old and no longer stored in the memory of the Template Provider -- `stale-template-id` - used when the prev_hash of the corresponding template is still in the Template Provider's memory, but it no longer points to the latest tip - ## 7.7 `SubmitSolution` (Client -> Server) Upon finding a coinbase transaction/nonce pair which double-SHA256 hashes at or below `SetNewPrevHash::target`, the client MUST immediately send this message, and the server MUST then immediately construct the corresponding full block and attempt to propagate it to the Bitcoin network. From 3c5d7bbad6034cf2d03a005d2c3ca36b9f5adaf2 Mon Sep 17 00:00:00 2001 From: plebhash Date: Fri, 15 May 2026 11:21:48 -0300 Subject: [PATCH 3/3] add extra sentence about error_code and fallback behavior --- 03-Protocol-Overview.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index eab40a9..66fb28e 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -216,7 +216,11 @@ A device processing `SubmitSharesExtended` **MUST scan for TLV fields** matching The protocol uses string error codes. Implementations MAY use error codes for automated actions. The list of error codes can differ between implementations, and therefore implementations MUST do a logging no-op for unknown error codes. + +Fallback or recovery behavior MUST be based on the overall protocol state, even when a peer sends an unknown, different, or unexpected error code. + Implementations/pools SHOULD provide documentation on the meaning of error codes and error codes SHOULD use printable ASCII where possible. + Furthermore, error codes MUST NOT include control characters. ## 3.6 Common Protocol Messages @@ -354,4 +358,4 @@ That's because the Template Distribution Server would not be able to propagate a On the Template Distribution Protocol's `NewTemplate` there is one field affected by BIP141: - `coinbase_tx_outputs` -In case of blocks containing SegWit transactions (and optionally blocks that don't as well), this field carries the `OP_RETURN` output with the witness commitment. The `witness reserved value` (Coinbase witness) used for calculating this witness commitment is assumed to be 32 bytes of `0x00`, as it currently holds no consensus-critical meaning. This [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). +In case of blocks containing SegWit transactions (and optionally blocks that don't as well), this field carries the `OP_RETURN` output with the witness commitment. The `witness reserved value` (coinbase witness) used for calculating this witness commitment is assumed to be 32 bytes of `0x00`, as it currently holds no consensus-critical meaning. This [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). \ No newline at end of file