@@ -20,9 +20,41 @@ use node::{
2020
2121use openmina_node_native:: { archive:: config:: ArchiveStorageOptions , tracing, NodeBuilder } ;
2222
23- /// Openmina node
23+ /// OpenMina node configuration and runtime options
24+ ///
25+ /// This struct defines all available command-line parameters for running an OpenMina node.
26+ /// The node can operate in different modes (basic node, block producer, archive node)
27+ /// depending on the parameters provided.
28+ ///
29+ /// # Basic Usage
30+ ///
31+ /// ```bash
32+ /// # Run a basic node on devnet
33+ /// openmina node --network devnet
34+ ///
35+ /// # Run with custom ports and logging
36+ /// openmina node --network devnet --port 3001 --libp2p-port 8303 --verbosity debug
37+ /// ```
38+ ///
39+ /// # Block Producer Mode
40+ ///
41+ /// ```bash
42+ /// # Run as block producer
43+ /// openmina node --network devnet --producer-key /path/to/key --coinbase-receiver B62q...
44+ /// ```
45+ ///
46+ /// # Archive Node Mode
47+ ///
48+ /// ```bash
49+ /// # Run as archive node with local storage
50+ /// openmina node --network devnet --archive-local-storage
51+ /// ```
2452#[ derive( Debug , clap:: Args ) ]
2553pub struct Node {
54+ /// Working directory for node data, logs, and configuration files
55+ ///
56+ /// Can be set via OPENMINA_HOME environment variable.
57+ /// Defaults to ~/.openmina
2658#[ arg(
2759 long,
2860 short = 'd' ,
@@ -31,7 +63,10 @@ pub struct Node {
3163 ) ]
3264 pub work_dir : String ,
3365
34- /// Peer secret key
66+ /// P2P networking secret key for node identity
67+ ///
68+ /// If not provided, a new key will be generated automatically.
69+ /// Can be set via OPENMINA_P2P_SEC_KEY environment variable.
3570#[ arg( long, short = 's' , env = "OPENMINA_P2P_SEC_KEY" ) ]
3671 pub p2p_secret_key : Option < SecretKey > ,
3772
@@ -49,15 +84,28 @@ pub struct Node {
4984#[ arg( long) ]
5085 pub libp2p_external_ip : Vec < String > ,
5186
52- /// Http port to listen on
87+ /// HTTP server port for RPC API and web interface
88+ ///
89+ /// The node will serve its HTTP API and dashboard on this port.
90+ /// Default: 3000
5391#[ arg( long, short, env, default_value = "3000" ) ]
5492 pub port : u16 ,
5593
56- /// LibP2P port to listen on
94+ /// LibP2P networking port for peer-to-peer communication
95+ ///
96+ /// This port is used for connecting to other nodes in the network.
97+ /// Default: 8302
5798#[ arg( long, env, default_value = "8302" ) ]
5899 pub libp2p_port : u16 ,
59100
60- /// Verbosity level (options: trace, debug, info, warn, error)
101+ /// Logging verbosity level
102+ ///
103+ /// Controls the amount of logging output. Options in order of verbosity:
104+ /// - error: Only show errors
105+ /// - warn: Show warnings and errors
106+ /// - info: Show informational messages, warnings, and errors (default)
107+ /// - debug: Show debug information and all above
108+ /// - trace: Show all possible logging output
61109#[ arg( long, short, env, default_value = "info" ) ]
62110 pub verbosity : Level ,
63111
@@ -73,21 +121,71 @@ pub struct Node {
73121#[ arg( long, env = "OPENMINA_LOG_PATH" , default_value = "$OPENMINA_HOME" ) ]
74122 pub log_path : String ,
75123
124+ /// Initial peers to connect to on startup
125+ ///
126+ /// Specify peer multiaddresses to connect to when the node starts.
127+ /// Can be used multiple times to add multiple peers.
128+ ///
129+ /// # Multiaddr Format
130+ ///
131+ /// Multiaddresses follow the format: `/protocol/address/protocol/port/protocol/peer_id`
132+ ///
133+ /// **IPv4 Example:**
134+ /// ```
135+ /// /ip4/192.168.1.100/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
136+ /// ```
137+ ///
138+ /// **IPv6 Example:**
139+ /// ```
140+ /// /ip6/2001:db8::1/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
141+ /// ```
142+ ///
143+ /// **DNS Example:**
144+ /// ```
145+ /// /dns4/node.example.com/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
146+ /// ```
147+ ///
148+ /// Where:
149+ /// - `ip4/ip6/dns4` specifies the address type
150+ /// - IP address or hostname
151+ /// - `tcp` protocol with port number (typically 8302 for OpenMina)
152+ /// - `p2p` protocol with the peer's public key identifier
76153#[ arg( long, short = 'P' , alias = "peer" ) ]
77154 pub peers : Vec < P2pConnectionOutgoingInitOpts > ,
78155
79- /// File containing initial peers.
156+ /// File containing initial peers to connect to
80157///
81- /// Each line should contain peer's multiaddr.
158+ /// Each line should contain a peer's multiaddr following the format described above.
159+ ///
160+ /// **Example file content:**
161+ /// ```
162+ /// /ip4/192.168.1.100/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
163+ /// /ip4/10.0.0.50/tcp/8302/p2p/12D3KooWXYZ9876543210fedcba...
164+ /// /dns4/bootstrap.example.com/tcp/8302/p2p/12D3KooW123ABC...
165+ /// ```
166+ ///
167+ /// Empty lines and lines starting with `#` are ignored.
82168#[ arg( long, env) ]
83169 pub peer_list_file : Option < PathBuf > ,
84170
85- /// File containing initial peers.
171+ /// URL to fetch initial peers list from
86172///
87- /// Each line should contain peer's multiaddr.
173+ /// The URL should return a text file with one peer multiaddr per line,
174+ /// using the same format as described in `peer_list_file`.
175+ /// Useful for dynamic peer discovery from a central bootstrap service.
176+ ///
177+ /// **Example URL response:**
178+ /// ```
179+ /// /ip4/bootstrap1.example.com/tcp/8302/p2p/12D3KooW...
180+ /// /ip4/bootstrap2.example.com/tcp/8302/p2p/12D3KooX...
181+ /// ```
88182#[ arg( long, env) ]
89183 pub peer_list_url : Option < Url > ,
90184
185+ /// Maximum number of peer connections to maintain
186+ ///
187+ /// The node will attempt to maintain up to this many connections
188+ /// to other peers in the network. Default: 100
91189#[ arg( long, default_value = "100" ) ]
92190 pub max_peers : usize ,
93191
0 commit comments