feat: kind-based multi-remote configuration (#746)

Author: thlorenz

Cargo.lock

@@ -31,31 +31,47 @@
 # Env: MBV_LIFECYCLE
 lifecycle = "ephemeral"
 
-# Remote endpoints for syncing with the base chain.
-# You can specify multiple remotes of different types.
-# The first HTTP/HTTPS remote will be used for JSON-RPC calls.
-# Each WebSocket/gRPC remote creates a subscription client.
+# Remote connections for RPC, WebSocket, and gRPC.
+# You can define multiple remotes of different kinds.
+# The first RPC remote will be used for JSON-RPC calls.
+# Each WebSocket/gRPC remote will create a pubsub client.
 #
-# Supported URL schemes:
-# - "http", "https":  JSON-RPC HTTP connections
-# - "ws", "wss":      WebSocket connections for PubSub
-# - "grpc", "grpcs":  gRPC connections for streaming
+# Available kinds:
+# - "rpc":       JSON-RPC HTTP connection (typically port 8899)
+# - "websocket": WebSocket connection for PubSub (typically wss://)
+# - "grpc":      gRPC connection for streaming (typically port 50051)
 #
-# URL Aliases (resolved during parsing):
-# - "mainnet":   resolves to https://api.mainnet-beta.solana.com/
-# - "devnet":    resolves to https://api.devnet.solana.com/
-# - "testnet":   resolves to https://api.testnet.solana.com/
-# - "localhost": resolves to http://localhost:8899/ (only for http/https schemes)
+# URL Aliases (automatically resolved based on kind):
+# RPC aliases:       "mainnet", "devnet", "local"
+# WebSocket aliases: "mainnet", "devnet", "local"
 #
-# Examples:
-# remotes = ["devnet"]                                    # Single devnet HTTP endpoint
-# remotes = ["mainnet", "wss://mainnet-beta.solana.com"] # Mainnet with explicit WebSocket
-# remotes = ["http://localhost:8899", "ws://localhost:8900"] # Local endpoints
+# Example 1: Using aliases
+# [[remote]]
+# kind = "rpc"
+# url = "devnet"
 #
-# If no remotes are specified, defaults to ["devnet"] with an auto-added WebSocket endpoint.
-# Default: ["https://api.devnet.solana.com/"]
-# Env: Not supported (must be configured via TOML or CLI)
-remotes = ["devnet", "wss://devnet.solana.com", "grpcs://solana.helius.com"]
+# [[remote]]
+# kind = "websocket"
+# url = "devnet"
+#
+# Example 2: Using full URLs with optional API key
+# [[remote]]
+# kind = "rpc"
+# url = "https://api.devnet.solana.com"
+# api-key = "optional-key"
+#
+# [[remote]]
+# kind = "websocket"
+# url = "wss://api.devnet.solana.com"
+#
+# [[remote]]
+# kind = "grpc"
+# url = "http://grpc.example.com:50051"
+# api-key = "optional-key"
+
+[[remote]]
+kind = "rpc"
+url = "devnet"
 
 # Root directory for application storage (ledger, accountsdb, snapshots).
 # Default: "magicblock-test-storage" (created in current working directory)

config.example.toml

@@ -37,6 +37,8 @@ use magicblock_config::{
     config::{
         ChainOperationConfig, LedgerConfig, LifecycleMode, LoadableProgram,
     },
+    consts::DEFAULT_REMOTE,
+    types::{resolve_url, RemoteKind},
     ValidatorParams,
 };
 use magicblock_core::{
@@ -340,7 +342,7 @@ impl MagicValidator {
             config.validator.keypair.insecure_clone(),
             committor_persist_path,
             ChainConfig {
-                rpc_uri: config.rpc_url().to_owned(),
+                rpc_uri: config.rpc_url_or_default(),
                 commitment: CommitmentConfig::confirmed(),
                 compute_budget_config: ComputeBudgetConfig::new(
                     config.commit.compute_unit_price,
@@ -371,14 +373,22 @@ impl MagicValidator {
         faucet_pubkey: Pubkey,
     ) -> ApiResult<ChainlinkImpl> {
         use magicblock_chainlink::remote_account_provider::Endpoint;
-        let rpc_url = config.rpc_url().to_owned();
-        let endpoints = config
-            .websocket_urls()
-            .map(|pubsub_url| Endpoint {
+        let rpc_url = config.rpc_url_or_default();
+        let endpoints = if config.has_subscription_url() {
+            config
+                .websocket_urls()
+                .map(|pubsub_url| Endpoint {
+                    rpc_url: rpc_url.clone(),
+                    pubsub_url: pubsub_url.to_string(),
+                })
+                .collect::<Vec<_>>()
+        } else {
+            let ws_url = resolve_url(RemoteKind::Websocket, DEFAULT_REMOTE);
+            vec![Endpoint {
                 rpc_url: rpc_url.clone(),
-                pubsub_url: pubsub_url.to_string(),
-            })
-            .collect::<Vec<_>>();
+                pubsub_url: ws_url,
+            }]
+        };
 
         let cloner = ChainlinkCloner::new(
             committor_service,
@@ -530,7 +540,7 @@ impl MagicValidator {
         });
 
         DomainRegistryManager::handle_registration_static(
-            self.config.rpc_url(),
+            self.config.rpc_url_or_default(),
             &validator_keypair,
             validator_info,
         )
@@ -543,7 +553,7 @@ impl MagicValidator {
         let validator_keypair = validator_authority();
 
         DomainRegistryManager::handle_unregistration_static(
-            self.config.rpc_url(),
+            self.config.rpc_url_or_default(),
             &validator_keypair,
         )
         .map_err(|err| {
@@ -557,7 +567,7 @@ impl MagicValidator {
         const MIN_BALANCE_SOL: u64 = 5;
 
         let lamports = RpcClient::new_with_commitment(
-            self.config.rpc_url().to_owned(),
+            self.config.rpc_url_or_default(),
             CommitmentConfig::confirmed(),
         )
         .get_balance(&self.identity)
@@ -604,7 +614,7 @@ impl MagicValidator {
             .map(|co| co.claim_fees_frequency)
         {
             self.claim_fees_task
-                .start(frequency, self.config.rpc_url().to_owned());
+                .start(frequency, self.config.rpc_url_or_default());
         }
 
         self.slot_ticker = Some(init_slot_ticker(

magicblock-api/src/magic_validator.rs

@@ -5,7 +5,9 @@ use serde::Serialize;
 
 use crate::{
     config::LifecycleMode,
-    types::{network::Remote, BindAddress, SerdeKeypair},
+    types::{
+        remote::parse_remote_config, BindAddress, RemoteConfig, SerdeKeypair,
+    },
 };
 
 /// CLI Arguments mirroring the structure of ValidatorParams.
@@ -16,22 +18,13 @@ pub struct CliParams {
     /// Path to the TOML configuration file.
     pub config: Option<PathBuf>,
 
-    /// List of remote endpoints for syncing with the base chain.
-    /// Can be specified multiple times.
-    ///
-    /// SUPPORTED SCHEMES: http(s), ws(s), grpc(s)
-    ///
-    /// ALIASES: mainnet, devnet, testnet, localhost
-    ///
-    /// EXAMPLES:
-    /// - `--remote devnet`
-    /// - `--remote wss://devnet.solana.com`
-    /// - `--remote grpcs://grpc.example.com`
-    ///
-    /// DEFAULT: devnet (HTTP endpoint with auto-added WS endpoint)
-    #[arg(long)]
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub remotes: Option<Vec<Remote>>,
+    /// Remote Solana cluster connections. Can be specified multiple times.
+    /// Format: --remote <kind>:<url> or --remote <kind>:<alias>
+    /// Examples: --remote rpc:devnet --remote websocket:devnet --remote grpc:http://localhost:50051
+    /// Aliases: mainnet, devnet, local (resolved based on kind)
+    #[arg(long, short, value_parser = parse_remote_config)]
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub remote: Vec<RemoteConfig>,
 
     /// The application's operational mode.
     #[arg(long)]

magicblock-config/src/config/cli.rs

@@ -20,9 +20,15 @@ pub const DEFAULT_BASE_FEE: u64 = 0;
 /// Default compute unit price in microlamports
 pub const DEFAULT_COMPUTE_UNIT_PRICE: u64 = 1_000_000;
 
-/// Remote URL Aliases - Mainnet, Testnet, Devnet, and Localhost
-/// Solana mainnet-beta RPC endpoint
-pub const MAINNET_URL: &str = "https://api.mainnet-beta.solana.com/";
+// Remote URL Aliases - RPC
+pub const RPC_MAINNET: &str = "https://api.mainnet-beta.solana.com/";
+pub const RPC_DEVNET: &str = "https://api.devnet.solana.com/";
+pub const RPC_LOCAL: &str = "http://localhost:8899/";
+
+// Remote URL Aliases - WebSocket
+pub const WS_MAINNET: &str = "wss://api.mainnet-beta.solana.com/";
+pub const WS_DEVNET: &str = "wss://api.devnet.solana.com/";
+pub const WS_LOCAL: &str = "ws://localhost:8899/";
 
 /// Solana testnet RPC endpoint
 pub const TESTNET_URL: &str = "https://api.testnet.solana.com/";

magicblock-config/src/consts.rs

@@ -24,7 +24,7 @@ use crate::{
         CommittorConfig, LedgerConfig, LoadableProgram, TaskSchedulerConfig,
         ValidatorConfig,
     },
-    types::{network::Remote, BindAddress},
+    types::{resolve_url, BindAddress, RemoteConfig, RemoteKind},
 };
 
 /// Top-level configuration, assembled from multiple sources.
@@ -34,9 +34,10 @@ pub struct ValidatorParams {
     /// Path to the TOML configuration file (overrides CLI args).
     pub config: Option<PathBuf>,
 
-    /// Remote endpoints for syncing with the base chain.
-    /// Can include HTTP (for JSON-RPC), WebSocket (for PubSub), and gRPC (for streaming) connections.
-    pub remotes: Vec<Remote>,
+    /// Array-based remote configurations for RPC, WebSocket, and gRPC.
+    /// Configured via [[remote]] sections in TOML (array-of-tables syntax).
+    #[serde(default, rename = "remote")]
+    pub remotes: Vec<RemoteConfig>,
 
     /// The application's operational mode.
     pub lifecycle: LifecycleMode,
@@ -173,6 +174,44 @@ impl ValidatorParams {
             .filter(|r| matches!(r, Remote::Grpc(_)))
             .map(|r| r.url_str())
     }
+
+    /// Returns the first RPC remote URL as an Option.
+    pub fn rpc_url(&self) -> Option<&str> {
+        self.remotes
+            .iter()
+            .find(|r| r.kind == RemoteKind::Rpc)
+            .map(|r| r.url.as_str())
+    }
+
+    /// Returns an iterator over all WebSocket remote URLs.
+    pub fn websocket_urls(&self) -> impl Iterator<Item = &str> + '_ {
+        self.remotes
+            .iter()
+            .filter(|r| r.kind == RemoteKind::Websocket)
+            .map(|r| r.url.as_str())
+    }
+
+    /// Returns an iterator over all gRPC remote URLs.
+    pub fn grpc_urls(&self) -> impl Iterator<Item = &str> + '_ {
+        self.remotes
+            .iter()
+            .filter(|r| r.kind == RemoteKind::Grpc)
+            .map(|r| r.url.as_str())
+    }
+
+    pub fn has_subscription_url(&self) -> bool {
+        self.remotes.iter().any(|r| {
+            r.kind == RemoteKind::Websocket || r.kind == RemoteKind::Grpc
+        })
+    }
+
+    /// Returns the RPC URL, using DEFAULT_REMOTE as fallback if not
+    /// configured.
+    pub fn rpc_url_or_default(&self) -> String {
+        self.rpc_url().map(|s| s.to_string()).unwrap_or_else(|| {
+            resolve_url(RemoteKind::Rpc, consts::DEFAULT_REMOTE)
+        })
+    }
 }
 
 impl Display for ValidatorParams {