chore: Move bind URLs to sockets

CHANGELOG.md

@@ -17,7 +17,9 @@
 - Added `StoreReplica` gRPC service with endpoints for streaming blocks and proofs ([#1987](https://github.com/0xMiden/node/pull/1987)).
 - Replaced the network monitor's JavaScript dashboard with a server-rendered Maud + HTMX frontend ([#2024](https://github.com/0xMiden/node/pull/2024)).
 - [BREAKING] Removed `CheckNullifiers` endpoint ([#2049](https://github.com/0xMiden/node/pull/2049)).
+- [BREAKING] Replaced binding URL env vars and CLI flags with listen socket addresses ([#2054](https://github.com/0xMiden/node/pull/2054)).
 - [BREAKING] `BlockRange.block_to` is now required for all RPC endpoints ([#2056](https://github.com/0xMiden/node/pull/2056)).
+- [BREAKING] Renamed `--url` CLI flags and `*_URL` env vars to `--listen` / `*_LISTEN` across all components.
 
 ## v0.14.10 (2026-05-29)
 

bin/node/.env

@@ -6,7 +6,7 @@ MIDEN_NODE_ENABLE_OTEL=true
 MIDEN_NODE_DATA_DIRECTORY=
 
 # Block Producer
-MIDEN_NODE_BLOCK_PRODUCER_URL=
+MIDEN_NODE_BLOCK_PRODUCER_LISTEN=
 MIDEN_NODE_BLOCK_PRODUCER_STORE_URL=
 MIDEN_NODE_BLOCK_PRODUCER_VALIDATOR_URL=
 MIDEN_NODE_BLOCK_PRODUCER_MAX_TXS_PER_BATCH=
@@ -15,27 +15,27 @@ MIDEN_NODE_BLOCK_PRODUCER_MEMPOOL_TX_CAPACITY=
 MIDEN_NODE_BLOCK_PRODUCER_BATCH_PROVER_URL=
 
 # Store
-MIDEN_NODE_STORE_RPC_URL=
+MIDEN_NODE_STORE_RPC_LISTEN=
 MIDEN_NODE_STORE_UPSTREAM_RPC_URL=
-MIDEN_NODE_STORE_NTX_BUILDER_URL=
-MIDEN_NODE_STORE_BLOCK_PRODUCER_URL=
+MIDEN_NODE_STORE_NTX_BUILDER_LISTEN=
+MIDEN_NODE_STORE_BLOCK_PRODUCER_LISTEN=
 MIDEN_NODE_STORE_BLOCK_PROVER_URL=
 
 # RPC
-MIDEN_NODE_RPC_URL=http://0.0.0.0:57291
+MIDEN_NODE_RPC_LISTEN=0.0.0.0:57291
 MIDEN_NODE_RPC_STORE_URL=
 MIDEN_NODE_RPC_BLOCK_PRODUCER_URL=
 MIDEN_NODE_RPC_VALIDATOR_URL=
 MIDEN_NODE_RPC_NTX_BUILDER_URL=
 
 # Validator
-MIDEN_NODE_VALIDATOR_URL=
+MIDEN_NODE_VALIDATOR_LISTEN=
 MIDEN_NODE_VALIDATOR_GENESIS_CONFIG_FILE=
 MIDEN_NODE_VALIDATOR_KEY=
 MIDEN_NODE_VALIDATOR_KMS_KEY_ID=
 
 # NTX Builder
-MIDEN_NODE_NTX_BUILDER_URL=
+MIDEN_NODE_NTX_BUILDER_LISTEN=
 MIDEN_NODE_NTX_BUILDER_STORE_URL=
 MIDEN_NODE_NTX_BUILDER_BLOCK_PRODUCER_URL=
 MIDEN_NODE_NTX_BUILDER_VALIDATOR_URL=

bin/node/src/commands/block_producer.rs

@@ -1,3 +1,4 @@
+use std::net::SocketAddr;
 use std::num::NonZeroUsize;
 use std::time::Duration;
 
@@ -10,12 +11,11 @@ use miden_node_block_producer::{
     DEFAULT_MAX_TXS_PER_BATCH,
 };
 use miden_node_utils::clap::{GrpcOptionsInternal, duration_to_human_readable_string};
-use miden_node_utils::grpc::UrlExt;
 use url::Url;
 
 use super::ENV_ENABLE_OTEL;
 
-const ENV_URL: &str = "MIDEN_NODE_BLOCK_PRODUCER_URL";
+const ENV_LISTEN: &str = "MIDEN_NODE_BLOCK_PRODUCER_LISTEN";
 const ENV_STORE_URL: &str = "MIDEN_NODE_BLOCK_PRODUCER_STORE_URL";
 const ENV_VALIDATOR_URL: &str = "MIDEN_NODE_BLOCK_PRODUCER_VALIDATOR_URL";
 const ENV_MAX_TXS_PER_BATCH: &str = "MIDEN_NODE_BLOCK_PRODUCER_MAX_TXS_PER_BATCH";
@@ -30,9 +30,9 @@ const ENV_BATCH_PROVER_URL: &str = "MIDEN_NODE_BLOCK_PRODUCER_BATCH_PROVER_URL";
 pub enum BlockProducerCommand {
     /// Starts the block-producer component.
     Start {
-        /// Url at which to serve the gRPC API.
-        #[arg(env = ENV_URL)]
-        url: Url,
+        /// Socket address at which to serve the gRPC API.
+        #[arg(long = "listen", env = ENV_LISTEN, value_name = "LISTEN")]
+        listen: SocketAddr,
 
         /// The store's block-producer service gRPC url.
         #[arg(long = "store.url", env = ENV_STORE_URL)]
@@ -60,16 +60,15 @@ pub enum BlockProducerCommand {
 impl BlockProducerCommand {
     pub async fn handle(self) -> anyhow::Result<()> {
         let Self::Start {
-            url,
+            listen,
             store_url,
             validator_url,
             block_producer,
             enable_otel: _,
             grpc_options,
         } = self;
 
-        let block_producer_address =
-            url.to_socket().context("Failed to extract socket address from store URL")?;
+        let block_producer_address = listen;
 
         // Runtime validation for protocol constraints
         if block_producer.max_batches_per_block > miden_protocol::MAX_BATCHES_PER_BLOCK {
@@ -123,7 +122,7 @@ mod tests {
     #[tokio::test]
     async fn rejects_too_large_max_batches_per_block() {
         let cmd = BlockProducerCommand::Start {
-            url: dummy_url(),
+            listen: "[::1]:0".parse().unwrap(),
             store_url: dummy_url(),
             validator_url: dummy_url(),
             block_producer: BlockProducerConfig {
@@ -146,7 +145,7 @@ mod tests {
     #[tokio::test]
     async fn rejects_too_large_max_txs_per_batch() {
         let cmd = BlockProducerCommand::Start {
-            url: dummy_url(),
+            listen: "[::1]:0".parse().unwrap(),
             store_url: dummy_url(),
             validator_url: dummy_url(),
             block_producer: BlockProducerConfig {

bin/node/src/commands/ntx_builder.rs

@@ -1,17 +1,17 @@
+use std::net::SocketAddr;
 use std::num::NonZeroUsize;
 use std::path::PathBuf;
 use std::time::Duration;
 
 use anyhow::Context;
 use miden_node_utils::clap::duration_to_human_readable_string;
-use miden_node_utils::grpc::UrlExt;
 use tokio::net::TcpListener;
 use url::Url;
 
 use super::ENV_ENABLE_OTEL;
 use crate::commands::ENV_DATA_DIRECTORY;
 
-const ENV_URL: &str = "MIDEN_NODE_NTX_BUILDER_URL";
+const ENV_LISTEN: &str = "MIDEN_NODE_NTX_BUILDER_LISTEN";
 const ENV_STORE_URL: &str = "MIDEN_NODE_NTX_BUILDER_STORE_URL";
 const ENV_BLOCK_PRODUCER_URL: &str = "MIDEN_NODE_NTX_BUILDER_BLOCK_PRODUCER_URL";
 const ENV_VALIDATOR_URL: &str = "MIDEN_NODE_NTX_BUILDER_VALIDATOR_URL";
@@ -27,9 +27,9 @@ const DEFAULT_MAX_CYCLES: u32 = 1 << 18;
 pub enum NtxBuilderCommand {
     /// Starts the network transaction builder component.
     Start {
-        /// Url at which to serve the ntx-builder's gRPC API.
-        #[arg(long = "url", env = ENV_URL, value_name = "URL")]
-        url: Option<Url>,
+        /// Socket address at which to serve the ntx-builder's gRPC API.
+        #[arg(long = "listen", env = ENV_LISTEN, value_name = "LISTEN")]
+        listen: SocketAddr,
 
         /// The store's ntx-builder service gRPC url.
         #[arg(long = "store.url", env = ENV_STORE_URL, value_name = "URL")]
@@ -105,7 +105,7 @@ pub enum NtxBuilderCommand {
 impl NtxBuilderCommand {
     pub async fn handle(self) -> anyhow::Result<()> {
         let Self::Start {
-            url,
+            listen,
             store_url,
             block_producer_url,
             validator_url,
@@ -118,18 +118,9 @@ impl NtxBuilderCommand {
             enable_otel: _,
         } = self;
 
-        let listener = if let Some(url) = url {
-            let addr = url
-                .to_socket()
-                .context("Failed to extract socket address from ntx-builder URL")?;
-            Some(
-                TcpListener::bind(addr)
-                    .await
-                    .context("Failed to bind to ntx-builder's gRPC URL")?,
-            )
-        } else {
-            None
-        };
+        let listener = TcpListener::bind(listen)
+            .await
+            .context("Failed to bind to ntx-builder's gRPC socket")?;
 
         let database_filepath = data_directory.join("ntx-builder.sqlite3");
 

bin/node/src/commands/rpc.rs

@@ -1,12 +1,13 @@
+use std::net::SocketAddr;
+
 use anyhow::Context;
 use miden_node_rpc::Rpc;
 use miden_node_utils::clap::GrpcOptionsExternal;
-use miden_node_utils::grpc::UrlExt;
 use url::Url;
 
 use super::ENV_ENABLE_OTEL;
 
-const ENV_URL: &str = "MIDEN_NODE_RPC_URL";
+const ENV_LISTEN: &str = "MIDEN_NODE_RPC_LISTEN";
 const ENV_STORE_URL: &str = "MIDEN_NODE_RPC_STORE_URL";
 const ENV_BLOCK_PRODUCER_URL: &str = "MIDEN_NODE_RPC_BLOCK_PRODUCER_URL";
 const ENV_VALIDATOR_URL: &str = "MIDEN_NODE_RPC_VALIDATOR_URL";
@@ -16,9 +17,9 @@ const ENV_NTX_BUILDER_URL: &str = "MIDEN_NODE_RPC_NTX_BUILDER_URL";
 pub enum RpcCommand {
     /// Starts the RPC component.
     Start {
-        /// Url at which to serve the gRPC API.
-        #[arg(long = "url", env = ENV_URL, value_name = "URL")]
-        url: Url,
+        /// Socket address at which to serve the gRPC API.
+        #[arg(long = "listen", env = ENV_LISTEN, value_name = "LISTEN")]
+        listen: SocketAddr,
 
         /// The store's RPC service gRPC url.
         #[arg(long = "store.url", env = ENV_STORE_URL, value_name = "URL")]
@@ -52,7 +53,7 @@ pub enum RpcCommand {
 impl RpcCommand {
     pub async fn handle(self) -> anyhow::Result<()> {
         let Self::Start {
-            url,
+            listen,
             store_url,
             block_producer_url,
             validator_url,
@@ -61,10 +62,9 @@ impl RpcCommand {
             grpc_options,
         } = self;
 
-        let listener = url.to_socket().context("Failed to extract socket address from RPC URL")?;
-        let listener = tokio::net::TcpListener::bind(listener)
+        let listener = tokio::net::TcpListener::bind(listen)
             .await
-            .context("Failed to bind to RPC's gRPC URL")?;
+            .context("Failed to bind to RPC's gRPC socket")?;
 
         Rpc {
             listener,