add `error_code` constants by plebhash · Pull Request #2151 · stratum-mining/stratum

plebhash · 2026-05-12T20:02:51Z

GitGab19

I looked on the specs and reported almost on every "message" the error_code(s) that we have there, to simplify the review and being sure we're covering all we have on the specs.

That said, I think my initial understanding was to define the error codes (as constants) only for the ones which are explicitly defined in the current specs.

But reviewing this PR made me realize that probably your goal was to cover all the codes we have on the specs + everything we are already using at the application level (which very likely would be useful also for some adopters).

Is my understanding correct?

GitGab19 · 2026-05-13T07:37:36Z

+pub const ERROR_CODE_DECLARE_MINING_JOB_MISSING_TXS: &str = "missing-txs";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX: &str =
+    "invalid-job-param-value-coinbase-tx";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT: &str =
+    "invalid-job-param-value-coinbase-tx-input";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INTERNAL_ERROR: &str = "internal-error";
+pub const ERROR_CODE_DECLARE_MINING_JOB_STALE_CHAIN_TIP: &str = "stale-chain-tip";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB: &str = "invalid-job";


Where are these in the specs? I'm looking at the JD chapter, and I only see this sentence:

Possible error codes: - invalid-mining-job-token - invalid-job-param-value-{} - {} is replaced by a particular field name from DeclareMiningJob message

Aren't we missing invalid-job-param-value-version, invalid-job-param-value-wtxid_list, and invalid-job-param-value-excess-data here?

all invalid-job-param-value-* were changed into invalid-*

if a specific parameter is invalid, we write that in a straightforward way, no templates or patterns induced by spec

GitGab19 · 2026-05-13T07:45:40Z

+// Commonly used SetCustomMiningJobError error_code values.
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_JD_NOT_SUPPORTED: &str = "jd-not-supported";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_CHANNEL_ID: &str = "invalid-channel-id";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_MINING_JOB_TOKEN: &str =
+    "invalid-mining-job-token";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_JOB_NOT_YET_VALIDATED: &str = "job-not-yet-validated";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_PREV_HASH_LENGTH: &str =
+    "invalid-prev-hash-length";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_STALE_CHAIN_TIP: &str = "stale-chain-tip";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_NBITS: &str =
+    "invalid-job-param-value-nbits";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_VERSION: &str =
+    "invalid-job-param-value-version";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX: &str =
+    "invalid-job-param-value-coinbase-tx";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_VERSION: &str =
+    "invalid-job-param-value-coinbase-tx-version";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_PREFIX: &str =
+    "invalid-job-param-value-coinbase-prefix";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT_N_SEQUENCE:
+    &str = "invalid-job-param-value-coinbase-tx-input-n-sequence";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_OUTPUTS: &str =
+    "invalid-job-param-value-coinbase-tx-outputs";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_LOCKTIME: &str =
+    "invalid-job-param-value-coinbase-tx-locktime";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_MERKLE_PATH: &str =
+    "invalid-job-param-value-merkle-path";


On the specs we have:

Possible errors: - invalid-channel-id - invalid-mining-job-token - invalid-job-param-value-{} - {} is replaced by a particular field name from SetCustomMiningJob message

Aren't we missing invalid-job-param-value-min-ntime?

yes we are

I'm adding it to this PR (as invalid-min-ntime), and taking note of JDS validation gap stratum-mining/sv2-apps#500

plebhash · 2026-05-13T12:02:25Z

I looked on the specs and reported almost on every "message" the error_code(s) that we have there, to simplify the review and being sure we're covering all we have on the specs.

That said, I think my initial understanding was to define the error codes (as constants) only for the ones which are explicitly defined in the current specs.

But reviewing this PR made me realize that probably your goal was to cover all the codes we have on the specs + everything we are already using at the application level (which very likely would be useful also for some adopters).

Is my understanding correct?

as of today, SRI already implements error_codes that are not explicitly listed on the spec

this PR covers all error_codes from current SRI

I cannot say I introduced all error_codes that are not listed on spec, but I do remember introducing many

I've always treated the error_codes listed on the spec as merely suggestions, not a comprehensive list

so whenever I was faced with some edge case that the spec didn't explicitly list, I just established the error_code on SRI without going through the bureaucracy of proposing spec change (which would severely slow down whatever I was working on SRI)

GitGab19 · 2026-05-13T12:33:52Z

I see, and I guess it makes sense.

My question now is: should we have constants for all the error-codes which are currently listed on the specs? Even if they are not currently used by our implementation?

plebhash · 2026-05-13T12:52:21Z

should we have constants for all the error-codes which are currently listed on the specs? Even if they are not currently used by our implementation?

hmm makes sense, currently this PR is not covering 100% of the error_codes listed on the spec, and it should

changing

plebhash · 2026-05-13T13:31:47Z

ok now this PR covers 100% of the error_codes defined on spec, plus the ones defined on SRI

GitGab19 · 2026-05-13T13:37:06Z

Sign in to view

+pub const ERROR_CODE_SUBMIT_SHARES_INVALID_SHARE: &str = "invalid-share";
+pub const ERROR_CODE_SUBMIT_SHARES_STALE_SHARE: &str = "stale-share";
+pub const ERROR_CODE_SUBMIT_SHARES_INVALID_JOB_ID: &str = "invalid-job-id";
+pub const ERROR_CODE_SUBMIT_SHARES_DIFFICULTY_TOO_LOW: &str = "too-low-difficulty";


this should be difficulty-too-low (?)

yes, changed

GitGab19 · 2026-05-13T13:38:18Z

    /// - invalid-channel-id
    /// - stale-share
-    /// - difficulty-too-low
+    /// - too-low-difficulty


this should be difficulty-too-low (?)

yes, changed

GitGab19 · 2026-05-13T13:43:22Z

+// Commonly used SetCustomMiningJobError error_code values.
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_JD_NOT_SUPPORTED: &str = "jd-not-supported";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_CHANNEL_ID: &str = "invalid-channel-id";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_MINING_JOB_TOKEN: &str =
+    "invalid-mining-job-token";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_JOB_NOT_YET_VALIDATED: &str = "job-not-yet-validated";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_PREV_HASH_LENGTH: &str =
+    "invalid-prev-hash-length";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_STALE_CHAIN_TIP: &str = "stale-chain-tip";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_NBITS: &str =
+    "invalid-job-param-value-nbits";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_VERSION: &str =
+    "invalid-job-param-value-version";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX: &str =
+    "invalid-job-param-value-coinbase-tx";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_VERSION: &str =
+    "invalid-job-param-value-coinbase-tx-version";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_PREFIX: &str =
+    "invalid-job-param-value-coinbase-prefix";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT_N_SEQUENCE:
+    &str = "invalid-job-param-value-coinbase-tx-input-n-sequence";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_OUTPUTS: &str =
+    "invalid-job-param-value-coinbase-tx-outputs";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_LOCKTIME: &str =
+    "invalid-job-param-value-coinbase-tx-locktime";
+pub const ERROR_CODE_SET_CUSTOM_MINING_JOB_INVALID_JOB_PARAM_VALUE_MERKLE_PATH: &str =
+    "invalid-job-param-value-merkle-path";


Aren't we missing invalid-job-param-value-min-ntime?

GitGab19 · 2026-05-13T13:45:50Z

+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX: &str =
+    "invalid-job-param-value-coinbase-tx";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT: &str =
+    "invalid-job-param-value-coinbase-tx-input";


These should be coinbase-tx-prefix and coinbase-tx-suffix?

note: I removed the invalid-job-param-value- pattern, so the error messages on this comment are

invalid-coinbase-tx

as discussed on the call, this error comes up when BitcoinCoreIPCEngine::handle_declare_mining_job fails to deserialize the coinbase tx via rust-bitcoin APIs

it's kind of a generic error because rust-bitcoin APIs don't give us much information about it

invalid-coinbase-tx-input

after the coinbase tx has been deserialized on BitcoinCoreIPCEngine::handle_declare_mining_job, we check whether it only has 1 single input

otherwise, it's not an actual coinbase tx

overall, with regards to explicit references to coinbase-tx-prefix and coinbase-tx-suffix, since we're no longer following invalid-job-param-value- pattern, I think we don't need to cover those?

tbh, I wonder if it would even be possible to cover them

GitGab19 · 2026-05-13T13:46:40Z

+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT: &str =
+    "invalid-job-param-value-coinbase-tx-input";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INTERNAL_ERROR: &str = "internal-error";
+pub const ERROR_CODE_DECLARE_MINING_JOB_STALE_CHAIN_TIP: &str = "stale-chain-tip";


How can we have this error code if there's not chain-tip in the message?

this is an internal implementation detail of jd_server_sv2::job_declarator::job_validation::bitcoin_core_ipc + bitcoin_core_sv2::job_declaration_protocol::handlers

if there's a ProvideMissingTransactions round-trip, and the MempoolMirror context chain-tip drifts in the mean time, DeclareMiningJob failes with this error code

GitGab19 · 2026-05-13T13:48:33Z

+pub const ERROR_CODE_DECLARE_MINING_JOB_MISSING_TXS: &str = "missing-txs";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX: &str =
+    "invalid-job-param-value-coinbase-tx";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB_PARAM_VALUE_COINBASE_TX_INPUT: &str =
+    "invalid-job-param-value-coinbase-tx-input";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INTERNAL_ERROR: &str = "internal-error";
+pub const ERROR_CODE_DECLARE_MINING_JOB_STALE_CHAIN_TIP: &str = "stale-chain-tip";
+pub const ERROR_CODE_DECLARE_MINING_JOB_INVALID_JOB: &str = "invalid-job";


Aren't we missing invalid-job-param-value-version, invalid-job-param-value-wtxid_list, and invalid-job-param-value-excess-data here?

plebhash · 2026-05-13T18:20:58Z

@GitGab19 FYI since your last review I'm doing some additional changes here, which are already one step aligned with the vision described in #2149 (comment)

more specifically, with 582536f I'm making sure that error enums of channels_sv2 (e.g.: ExtendedChannelError, StandardChannelError, and most importantly ShareValidationError, all carry a (&'static str)

but not all error variants carry a (&'static str), so hopefully Rust Docs comments should make the pattern clear:

/// Variants carrying `&'static str` are intended to be used as `error_code` values in the response message.
/// 
/// Variants without `&'static str` SHOULD lead to a client disconnection or application
/// shutdown.
/// ...

This was referenced May 12, 2026

version bumps for v1.10.0 #2147

Open

use error_code constants stratum-mining/sv2-apps#495

Draft

plebhash marked this pull request as ready for review May 12, 2026 20:37

GitGab19 reviewed May 13, 2026

View reviewed changes

plebhash force-pushed the 2026-05-12-error-code-constants branch 2 times, most recently from 3393943 to 2f9f21e Compare May 13, 2026 13:29

GitGab19 reviewed May 13, 2026

View reviewed changes

plebhash commented May 13, 2026

View reviewed changes

Comment thread sv2/subprotocols/mining/src/lib.rs Outdated

plebhash force-pushed the 2026-05-12-error-code-constants branch 3 times, most recently from bcb75de to 4eaf07c Compare May 13, 2026 15:45

plebhash added 10 commits May 13, 2026 13:11

add error_code constants to common_messages_sv2

93a0c87

add error_code constants to template_distribution_sv2

3496e40

add error_code constants to job_declaration_sv2

2f0a33b

add error_code constants to mining_sv2

6311687

adapt channels_sv2 with error_code constants

582536f

bump channels_sv2

3589238

bump parsers_sv2 due to dependency version bumps

4c20c43

bump handlers_sv2 due to dependency version bumps

a4bbeff

bump stratum-translation due to dependency version bumps

1b9c986

bump stratum-core due to dependency version bumps

2296dd6

plebhash force-pushed the 2026-05-12-error-code-constants branch from 4eaf07c to 2296dd6 Compare May 13, 2026 18:19

Conversation

plebhash commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GitGab19 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

plebhash commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GitGab19 commented May 13, 2026

Uh oh!

plebhash commented May 13, 2026

Uh oh!

plebhash commented May 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

plebhash commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

plebhash commented May 12, 2026 •

edited

Loading

plebhash commented May 13, 2026 •

edited

Loading

plebhash commented May 13, 2026 •

edited

Loading