Skip to content

Pool, JDS, JDC, tProxy: fragmented patterns in config loading error #992

Open

Description

@plebhash

Pool, JDS, JDC, tProxy: report a configuration refused after loading as a configuration error

Affected applications and crates

  • Pool: PoolErrorKind::Configuration(String), displayed as Configuration error: ..., used by the post-load checks in pool_runtime.rs.
  • JDS: JDSErrorKind::InvalidConfig(String), its own name and message for the same thing.
  • JDC: no general kind. Post-load checks each have a typed kind (NoUpstreamConfig, InvalidBitcoinDataDir, InvalidCoinbaseOutput), and a check that fits none of them lands in whatever kind its caller has at hand; the Noise credentials check from noise_sv2: let a server present a pre-issued certificate stratum#2437 lands in NetworkHelpersError and is printed as Network error: ....
  • tProxy: no general kind and no post-load check today, so nothing is misreported yet; the first check added will face the same choice.
  • All four share the deserialization layer: BadConfigDeserialize(ConfigError) printed as Bad `config` TOML deserialize: ... (JDS inherits it through Pool). That layer is consistent and is not the subject here.
  • stratum-apps: owns the shared deserialization layer (config_helpers::load_config and the ConfigError all four wrap) and raises post-load refusals of its own, each as a separate type the applications wrap one by one: CoinbaseOutputError and PayoutModeError from config_helpers and payout, and InvalidResponderCredentials from network_helpers.

Problem

Once a configuration has deserialized, each application validates it further at startup (coinbase script, template provider settings, Noise credentials, upstream list) and refuses to start when a check fails. The four applications name and print that refusal four different ways, and one of them has no name for it at all, so the same operator mistake reads as a configuration error on a Pool and as a network error on a JDC.

Impact

An operator reading logs, or tooling matching on them, cannot tell configuration mistakes apart from runtime failures by the same rule across applications. Every new post-load check inherits the fragmentation: its author picks whatever kind is nearest, and the next application picks another.

Expected outcome

A configuration refused after deserialization is reported the same way by Pool, JDS, JDC and tProxy: the same error kind name and the same message shape, carrying the reason, and the same startup behaviour (refuse to start, exit non-zero). A log line for such a refusal is recognizable as a configuration error by the same rule in every application.

That shape is defined once, in stratum-apps, next to the deserialization layer the applications already share, and the refusals stratum-apps raises itself (coinbase output, payout mode, Noise credentials) come out in it. An application carries it rather than redefining it, so a new post-load check in any application or in stratum-apps has one way to report.

Loupe findings

None. Filed from a review of the stratum-mining/stratum#2437 companion, where the inconsistency showed up while wiring the same check into three applications.

Related sv2-apps issues and PRs

Intended PR grouping

One cross-application PR: a stratum-apps commit first, then separate commits per application. Adding or renaming a public enum variant is an incompatible change for these 0.x crates, so landing it in the same release window as the stratum#2437 companion lets it share the version bumps that PR already makes.

Activity

  1. changed the title [-]# Pool, JDS, JDC, tProxy: fragmented patterns in config loading error[/-] [+]Pool, JDS, JDC, tProxy: fragmented patterns in config loading error[/+] on Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions