diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index 62e1cbe..66fb28e 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -215,19 +215,13 @@ 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/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. +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. -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. +Fallback or recovery behavior MUST be based on the overall protocol state, even when a peer sends an unknown, different, or unexpected error code. -- `unknown-user` -- `too-low-difficulty` -- `stale-share` -- `unsupported-feature-flags` -- `unsupported-protocol` -- `protocol-version-mismatch` +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 @@ -277,13 +271,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) @@ -370,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 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.