allow implementations to use error codes for automated actions

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).

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.

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)
 

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.