Add network field to GlobalInfo (GET /api/v1/global)

[vnprc]

Summary

• Add network: Option<String> to GlobalInfo so the Bitcoin network is machine-readable from the monitoring REST API without inspecting config files or Prometheus metrics
• Pool populates it from its [pool] TOML config (network = "regtest")
• Translator propagates it by polling GET <upstream_monitoring_url>/api/v1/global every 60 seconds in a background task

Motivation

Downstream consumers of the monitoring API (dashboards, alerting tools, and same for translator proxy) need to know which Bitcoin network the pool is operating on. Today this requires reading config files out-of-band. Exposing it in GlobalInfo makes it a first-class, machine-readable API field.

Changes

stratum-apps

• GlobalInfo.network: Option<String> (serializes to null when not configured)
• ServerState.network: Arc<RwLock<Option<String>>> for runtime updates
• MonitoringServer::with_network() — builder method for static configuration
• MonitoringServer::network_handle() — returns an Arc clone for background tasks that need to update the field after run() consumes self

pool-apps/pool

• PoolConfig.network: Option<String> with #[serde(default)] (backward-compatible)
• Pool calls .with_network(config.network()) on startup

miner-apps/translator

• TranslatorConfig.upstream_monitoring_url: Option<String> with #[serde(default)]
• On startup, calls monitoring_server.network_handle() then spawns poll_network_from_pool(): fetches pool's /api/v1/global immediately, then every 60 seconds; exits cleanly on cancellation
• Applied to both the primary startup path and the fallback-restart path
• reqwest added as a dependency (default-features = false, features = ["json"])

integration-tests

• start_pool_with_network and start_sv2_translator_with_upstream_monitoring helpers added (existing helpers unchanged, delegate to new ones)
• global_info_exposes_network test: starts pool with network = "regtest", starts translator pointing at pool's monitoring server, asserts pool exposes "regtest" immediately and translator propagates it within 10 seconds

Network value convention

Values follow bitcoin-cli -getinfo / bitcoin-cli getblockchaininfo convention: "main", "test", "testnet4", "regtest", "signet". The field is null if not configured.

Test plan

• cargo clippy --manifest-path stratum-apps/Cargo.toml -- -D warnings -A dead-code — clean
• cargo test --manifest-path stratum-apps/Cargo.toml — 29/29 pass
• cargo fmt --manifest-path stratum-apps/Cargo.toml -- --check — clean
• Pool and translator build cleanly with reqwest added
• global_info_exposes_network integration test passes end-to-end
• Existing monitoring integration tests unaffected

[vnprc]

Thanks for the detailed review @Alkamal01!

I pushed three commits today and rebased onto current upstream main (95 commits, no conflicts). I believe this PR is ready for another look.

feat: wire network field through pool, translator, and integration test

• Pool infers Bitcoin network from sv2-tp port (tp_address in config) using well-known default ports; falls back to an explicit network override for non-standard setups
• Translator fetches network from pool once per upstream connection via upstream_monitoring_url

fix(monitoring): address PR review feedback

• network_from_tp_port returns bitcoin-cli names ("main", "test") matching getblockchaininfo; VALID_NETWORKS constant validates explicit overrides
• reqwest removed from translator; fetch logic moved into MonitoringServer using hyper (already compiled transitively via axum — no new Cargo.lock entries). This is a better design because the monitoring module now owns the logic for querying monitoring endpoints upstream, and no heavyweight dependencies.
• with_upstream_monitoring_url() replaces the old network_handle() so no internal Arc leaks into application code
• Integration test renamed to global_info_network_from_config_override; timeout bumped to 30s; new global_info_network_unreachable_upstream test added

feat: extend network inference to JDC; move tp_type utilities to stratum-apps

• network_from_tp_port, VALID_NETWORKS, BitcoinNetwork::as_network_str(), and TemplateProviderType::infer_network() promoted to public API in stratum-apps/src/tp_type.rs; pool config delegates to infer_network() instead of carrying its own private copy
• JobDeclaratorClientConfig gains effective_network(), with_network(), and a network override field — same pattern as pool. Sv2Tp uses port inference; BitcoinCoreIpc derives the network directly from its BitcoinNetwork enum value. The override covers non-standard port setups
• Both the initial startup and reconnect MonitoringServer paths in JDC call .with_network(config.effective_network())
• New start_jdc_with_network_override integration test helper and global_info_network_jdc_from_config_override test; unit tests added to tp_type, pool config, and JDC config

[GitGab19]

Can you please clarify the need for these changes?

Could you give a concrete example of when this is needed?

[vnprc]

Sv2 today does not provide a way to determine what blockchain you are mining on. This is the most basic piece of information I can think of, so that's where I started contributing to sv2-apps.

My mining dashboard displays this field and is running this code now (in my vendored sv2-apps repo, as you can see in this commit).

For the first iteration I just displayed a config file setting, but this is just a lie; it can and will be misconfigured eventually. I'm trying to build the plumbing to get this information from the source of truth: the template provider.

This iteration uses standard ports (thanks for the tip @Sjors!) and falls back to displaying a config setting. This is better because it pulls info from the source of truth (the tp) as long as you stick to standard ports. It's still a lie if you deviate from the standard ports, but at least this PR adds the plumbing that routes this information to the monitoring API.

The complete solution is to include this information in the template distribution protocol handshake message. I have opened an issue in the protocol repo here: stratum-mining/sv2-spec#190

Frankly, I am amazed that no one has considered this a problem before. It's not even in the protocol! We have so much work to do...

[vnprc]

@GitGab19 should i just write the spec and then open a new PR implementing it?

[GitGab19]

I'm not sure this is a problem tbh, but I have to think more about this.

When do you switch networks in production? Which is the specific use case?

[vnprc]

I switch networks between dev and prod environments. Dev runs regtest and prod runs testnet4.

My goal is to build pool software that runs on autopilot. We will never decentralize block producers if running a pool remains a specialized skillset only available to a select few. If a pleb miner is running hashpool I want to prevent them from missing out on a block because they didn't read the manual. When the SRI install base reaches the scale we need it to reach to decentralize bitcoin block production, the probability of a misconfiguration causing an invalid block approaches 1.

Remember when Marathon mined an invalid block? I do. The objective of this protocol change is to prevent this footgun in an automated fashion.

[GitGab19]

I'm not getting your point yet.

If you're running a Pool server (or a JDC) which gets block templates directly from Bitcoin Core (through IPC) or from a Template Provider, it will get templates related to the network where the node is running.

How can this flow ever lead to the error Mara experienced in your example?

[vnprc]

How does the node network value get displayed to the end user?

edit: How does your grandma know what network she is mining on? She's only computer literate enough to install a "pool-in-a-box" solution and click thru the install wizard. Is she supposed to grep the bitcoind logs? I think we can do better than that.

I guess a more specific answer is this: grandma clicks testnet on the bitcoin node install option and then she clicks mainnet on the pool software option. What happens? It sounds like today the pool software just blindly trusts the node. Why?

It's just not that hard to make sure that this information flows through the system to the end user UI display. Why would we not build this capability? Don't trust verify.

[vnprc]

How about a different example. The user is playing with the software and switches the node to testnet. They forget to update the SRI config file to also say testnet. Their mining dashboard says mainnet because they use non-standard ports and just entered "mainnet" in the SRI config file somewhere. The dashboard software just blindly presents this config value on the website but they are, in fact, mining on testnet. The user finishes testing their software and neglects to point the node back to mainnet. Now the UI says mainnet, but they are actually mining on testnet. How long before they realize their mistake?

It's just a basic software engineering principle to have a single source of truth. Violating this principle leads to bugs. We violate this principle for the most fundamental piece of data in the whole mining stack: what blockchain are we mining on? The fix is simple. So let's fix it.