cli/core: introduce doublezero-cli-core crate and solana_l1_rpc_url

CHANGELOG.md

@@ -30,6 +30,8 @@ All notable changes to this project will be documented in this file.
   - `geoprobe-target-sender` gains opt-in `--challenged` flag (default off). When set, the sender extracts the nonce from `Reply0.SinceLastRxNs`, writes it into `Probe1.Sec || Frac`, signs Probe 1 only after Reply 0 is parsed, and surfaces `Reply1.Challenged` on every per-pair log line (JSON `"challenged"`, text `Challenged Inbound:`). Default off preserves the existing pre-sign-both / fire-Probe-1-immediately fast path byte-for-byte. Trade-off: challenged mode inflates `Reply1.SinceLastRxNs` by the sender's Probe 1 signing latency ([#3738](https://github.com/malbeclabs/doublezero/pull/3738))
   - state-ingest no longer logs a spurious `server exited with error: use of closed network connection` at shutdown; the listener-closed race during graceful shutdown (`net.ErrClosed`) is now treated as a clean stop alongside `http.ErrServerClosed`
 - CLI
+  - Introduce `doublezero-cli-core` (`crates/doublezero-cli-core/`), the shared library crate that every `doublezero-<module>-cli` will reuse per RFC-20. Ships `CliContext` + `CliContextBuilder` (resolved configuration value carried into every verb), `RequirementCheck` bitflags aligned with the legacy `CHECK_ID_JSON | CHECK_BALANCE | CHECK_FOUNDATION_ALLOWLIST` bit values, the shared validator set (`validate_pubkey`, `validate_pubkey_or_code`, `validate_code`, `validate_parse_bandwidth`, `validate_parse_delay_ms`, `validate_parse_jitter_ms`, `validate_parse_delay_override_ms`), display formatters (`DisplayVec`, `stringify_vec`), a `tracing` + `tracing-subscriber` `init_logging(verbosity)` helper that writes to stderr, and a `testing` module with a `CliContext` builder for verb unit tests. Existing call sites in `smartcontract/cli` continue to compile unchanged: `smartcontract/cli/src/validators.rs` and `formatters.rs` are now thin `pub use` shims over the core crate.
+  - Add `solana_l1_rpc_url` to `doublezero-config::NetworkConfig`. Per RFC-20 §Environments: `mainnet-beta` resolves to `https://api.mainnet-beta.solana.com`, `testnet` to `https://api.testnet.solana.com`, `devnet` to `https://api.testnet.solana.com` (intentional asymmetry, see RFC), and `local` to `http://localhost:8899`. A new `DZ_SOLANA_RPC_URL` environment variable overrides the resolved value, mirroring the existing `DZ_LEDGER_RPC_URL` / `DZ_LEDGER_WS_RPC_URL` overrides.
   - Drop the activator-only pollers from `doublezero` (user and multicastgroup activation waits). The `--wait` flag on `user create`, `user create-subscribe`, `user subscribe`, `multicastgroup create`, and `multicastgroup update` now fetches the post-create state once instead of polling; creates are atomic to `Activated` post-RFC-11, so the wait loop was watching a transition that no longer happens ([#3614](https://github.com/malbeclabs/doublezero/issues/3614))
   - `doublezero geolocation` `probe ...` and `user ...` mirrors `doublezero-geolocation` versions; new `--geo-program-id` global flag, `config get/set` include Geolocation Program ID; new `-init-geolocation-config` for init of geolocation program
   - cli: `doublezero geolocation` `probe ...` and `user ...` mirrors `doublezero-geolocation` versions; new `--geo-program-id` global flag, `config get/set` include Geolocation Program ID.

Cargo.toml

@@ -12,6 +12,7 @@ members = [
     "smartcontract/programs/doublezero-geolocation",
     "smartcontract/programs/common",
     "e2e/docker/ledger/fork-accounts",
+    "crates/doublezero-cli-core",
     "crates/sentinel",
 ]
 default-members = []
@@ -103,6 +104,7 @@ tokio = { version = "1", default-features = false, features = [
     "rt-multi-thread",
     "signal",
 ] }
+doublezero-cli-core = { path = "crates/doublezero-cli-core" }
 doublezero-config = { path = "config" }
 doublezero-sentinel = { path = "crates/sentinel" }
 doublezero_cli = { path = "smartcontract/cli" }

config/src/constants.rs

@@ -15,6 +15,7 @@ pub const ENV_MAINNET_BETA_DOUBLEZERO_LEDGER_RPC_URL: &str =
     "https://doublezero-mainnet-beta.rpcpool.com/db336024-e7a8-46b1-80e5-352dd77060ab";
 pub const ENV_MAINNET_BETA_DOUBLEZERO_LEDGER_WS_RPC_URL: &str =
     "wss://doublezero-mainnet-beta.rpcpool.com/db336024-e7a8-46b1-80e5-352dd77060ab";
+pub const ENV_MAINNET_BETA_SOLANA_L1_RPC_URL: &str = "https://api.mainnet-beta.solana.com";
 pub const ENV_MAINNET_BETA_SERVICEABILITY_PUBKEY: Pubkey =
     Pubkey::from_str_const("ser2VaTMAcYTaauMrTSfSrxBaUDq7BLNs2xfUugTAGv");
 pub const ENV_MAINNET_BETA_TELEMETRY_PUBKEY: Pubkey =
@@ -29,6 +30,7 @@ pub const ENV_TESTNET_DOUBLEZERO_LEDGER_RPC_URL: &str =
     "https://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16";
 pub const ENV_TESTNET_DOUBLEZERO_LEDGER_WS_RPC_URL: &str =
     "wss://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16/whirligig";
+pub const ENV_TESTNET_SOLANA_L1_RPC_URL: &str = "https://api.testnet.solana.com";
 pub const ENV_TESTNET_SERVICEABILITY_PUBKEY: Pubkey =
     Pubkey::from_str_const("DZtnuQ839pSaDMFG5q1ad2V95G82S5EC4RrB3Ndw2Heb");
 pub const ENV_TESTNET_TELEMETRY_PUBKEY: Pubkey =
@@ -39,10 +41,14 @@ pub const ENV_TESTNET_GEOLOCATION_PUBKEY: Pubkey =
     Pubkey::from_str_const("3AG2BCA7gAm47Q6xZzPQcUUYvnBjxAvPKnPz919cxHF4");
 
 // Constants related to DoubleZero devnet configuration
+//
+// Devnet intentionally points at Solana testnet for L1 access, matching the
+// existing config-crate mapping documented in RFC-20 (§Environments).
 pub const ENV_DEVNET_DOUBLEZERO_LEDGER_RPC_URL: &str =
     "https://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16";
 pub const ENV_LEDGER_DOUBLEZERO_DEVNET_WS_RPC_URL: &str =
     "wss://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16/whirligig";
+pub const ENV_DEVNET_SOLANA_L1_RPC_URL: &str = "https://api.testnet.solana.com";
 pub const ENV_DEVNET_SERVICEABILITY_PUBKEY: Pubkey =
     Pubkey::from_str_const("GYhQDKuESrasNZGyhMJhGYFtbzNijYhcrN9poSqCQVah");
 pub const ENV_DEVNET_TELEMETRY_PUBKEY: Pubkey =
@@ -55,6 +61,7 @@ pub const ENV_DEVNET_GEOLOCATION_PUBKEY: Pubkey =
 // Constants related to DoubleZero localnet configuration
 pub const ENV_LOCAL_DOUBLEZERO_LEDGER_RPC_URL: &str = "http://localhost:8899";
 pub const ENV_LOCAL_DOUBLEZERO_LEDGER_WS_RPC_URL: &str = "ws://localhost:8899";
+pub const ENV_LOCAL_SOLANA_L1_RPC_URL: &str = "http://localhost:8899";
 pub const ENV_LOCAL_SERVICEABILITY_PUBKEY: Pubkey =
     Pubkey::from_str_const("7CTniUa88iJKUHTrCkB4TjAoG6TD7AMivhQeuqN2LPtX");
 pub const ENV_LOCAL_TELEMETRY_PUBKEY: Pubkey =

config/src/env.rs

@@ -62,6 +62,7 @@ impl Environment {
             Environment::MainnetBeta => NetworkConfig {
                 ledger_public_rpc_url: ENV_MAINNET_BETA_DOUBLEZERO_LEDGER_RPC_URL.to_string(),
                 ledger_public_ws_rpc_url: ENV_MAINNET_BETA_DOUBLEZERO_LEDGER_WS_RPC_URL.to_string(),
+                solana_l1_rpc_url: ENV_MAINNET_BETA_SOLANA_L1_RPC_URL.to_string(),
                 serviceability_program_id: ENV_MAINNET_BETA_SERVICEABILITY_PUBKEY,
                 telemetry_program_id: ENV_MAINNET_BETA_TELEMETRY_PUBKEY,
                 internet_latency_collector_pk: ENV_MAINNET_BETA_INTERNET_LATENCY_COLLECTOR_PUBKEY,
@@ -70,6 +71,7 @@ impl Environment {
             Environment::Testnet => NetworkConfig {
                 ledger_public_rpc_url: ENV_TESTNET_DOUBLEZERO_LEDGER_RPC_URL.to_string(),
                 ledger_public_ws_rpc_url: ENV_TESTNET_DOUBLEZERO_LEDGER_WS_RPC_URL.to_string(),
+                solana_l1_rpc_url: ENV_TESTNET_SOLANA_L1_RPC_URL.to_string(),
                 serviceability_program_id: ENV_TESTNET_SERVICEABILITY_PUBKEY,
                 telemetry_program_id: ENV_TESTNET_TELEMETRY_PUBKEY,
                 internet_latency_collector_pk: ENV_TESTNET_INTERNET_LATENCY_COLLECTOR_PUBKEY,
@@ -78,6 +80,7 @@ impl Environment {
             Environment::Devnet => NetworkConfig {
                 ledger_public_rpc_url: ENV_DEVNET_DOUBLEZERO_LEDGER_RPC_URL.to_string(),
                 ledger_public_ws_rpc_url: ENV_LEDGER_DOUBLEZERO_DEVNET_WS_RPC_URL.to_string(),
+                solana_l1_rpc_url: ENV_DEVNET_SOLANA_L1_RPC_URL.to_string(),
                 serviceability_program_id: ENV_DEVNET_SERVICEABILITY_PUBKEY,
                 telemetry_program_id: ENV_DEVNET_TELEMETRY_PUBKEY,
                 internet_latency_collector_pk: ENV_DEVNET_INTERNET_LATENCY_COLLECTOR_PUBKEY,
@@ -86,6 +89,7 @@ impl Environment {
             Environment::Local => NetworkConfig {
                 ledger_public_rpc_url: ENV_LOCAL_DOUBLEZERO_LEDGER_RPC_URL.to_string(),
                 ledger_public_ws_rpc_url: ENV_LOCAL_DOUBLEZERO_LEDGER_WS_RPC_URL.to_string(),
+                solana_l1_rpc_url: ENV_LOCAL_SOLANA_L1_RPC_URL.to_string(),
                 serviceability_program_id: ENV_LOCAL_SERVICEABILITY_PUBKEY,
                 telemetry_program_id: ENV_LOCAL_TELEMETRY_PUBKEY,
                 internet_latency_collector_pk: ENV_LOCAL_INTERNET_LATENCY_COLLECTOR_PUBKEY,
@@ -99,6 +103,9 @@ impl Environment {
         if std::env::var("DZ_LEDGER_WS_RPC_URL").is_ok() {
             config.ledger_public_ws_rpc_url = std::env::var("DZ_LEDGER_WS_RPC_URL").unwrap();
         }
+        if std::env::var("DZ_SOLANA_RPC_URL").is_ok() {
+            config.solana_l1_rpc_url = std::env::var("DZ_SOLANA_RPC_URL").unwrap();
+        }
 
         Ok(config)
     }
@@ -108,6 +115,10 @@ impl Environment {
 pub struct NetworkConfig {
     pub ledger_public_rpc_url: String,
     pub ledger_public_ws_rpc_url: String,
+    /// Solana L1 RPC URL. Distinct from the DZ ledger transport: per RFC-20
+    /// (§Backend client patterns), the DZ ledger and Solana L1 are separate
+    /// backends with separate override flags (`--url` vs `--solana-url`).
+    pub solana_l1_rpc_url: String,
     pub serviceability_program_id: Pubkey,
     pub telemetry_program_id: Pubkey,
     pub internet_latency_collector_pk: Pubkey,
@@ -250,6 +261,38 @@ mod tests {
         std::env::remove_var("DZ_LEDGER_WS_RPC_URL");
     }
 
+    #[test]
+    #[serial]
+    fn test_network_config_solana_l1_urls() {
+        assert_eq!(
+            Environment::MainnetBeta.config().unwrap().solana_l1_rpc_url,
+            "https://api.mainnet-beta.solana.com",
+        );
+        assert_eq!(
+            Environment::Testnet.config().unwrap().solana_l1_rpc_url,
+            "https://api.testnet.solana.com",
+        );
+        // Devnet intentionally points at Solana testnet, matching RFC-20
+        // §Environments.
+        assert_eq!(
+            Environment::Devnet.config().unwrap().solana_l1_rpc_url,
+            "https://api.testnet.solana.com",
+        );
+        assert_eq!(
+            Environment::Local.config().unwrap().solana_l1_rpc_url,
+            "http://localhost:8899",
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn test_network_config_solana_url_env_override() {
+        std::env::set_var("DZ_SOLANA_RPC_URL", "https://custom-solana.example/");
+        let config = Environment::MainnetBeta.config().unwrap();
+        assert_eq!(config.solana_l1_rpc_url, "https://custom-solana.example/");
+        std::env::remove_var("DZ_SOLANA_RPC_URL");
+    }
+
     #[test]
     #[serial]
     fn test_environment_match_environment() {

crates/doublezero-cli-core/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "doublezero-cli-core"
+
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+name = "doublezero_cli_core"
+
+[dependencies]
+bitflags.workspace = true
+clap.workspace = true
+eyre.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+solana-sdk.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+tracing-subscriber.workspace = true
+
+doublezero-config.workspace = true
+doublezero-program-common.workspace = true
+
+[dev-dependencies]
+serial_test.workspace = true
+tempfile.workspace = true