nautilus_cli/opt.rs
1// -------------------------------------------------------------------------------------------------
2// Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3// https://nautechsystems.io
4//
5// Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6// You may not use this file except in compliance with the License.
7// You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use clap::Parser;
17
18/// Command-line interface for NautilusTrader.
19#[derive(Debug, Parser)]
20#[clap(version, about, author)]
21pub struct NautilusCli {
22 #[clap(subcommand)]
23 pub command: Commands,
24}
25
26/// Available top-level commands for the NautilusTrader CLI.
27#[derive(Parser, Debug)]
28pub enum Commands {
29 Database(DatabaseOpt),
30 #[cfg(feature = "defi")]
31 Blockchain(BlockchainOpt),
32}
33
34/// Database management options and subcommands.
35#[derive(Parser, Debug)]
36#[command(about = "Postgres database operations", long_about = None)]
37pub struct DatabaseOpt {
38 #[clap(subcommand)]
39 pub command: DatabaseCommand,
40}
41
42/// Configuration parameters for database connection and operations.
43#[derive(Parser, Debug, Clone)]
44pub struct DatabaseConfig {
45 /// Hostname or IP address of the database server.
46 #[arg(long)]
47 pub host: Option<String>,
48 /// Port number of the database server.
49 #[arg(long)]
50 pub port: Option<u16>,
51 /// Username for connecting to the database.
52 #[arg(long)]
53 pub username: Option<String>,
54 /// Name of the database.
55 #[arg(long)]
56 pub database: Option<String>,
57 /// Password for connecting to the database.
58 #[arg(long)]
59 pub password: Option<String>,
60 /// Directory path to the schema files.
61 #[arg(long)]
62 pub schema: Option<String>,
63}
64
65/// Available database management commands.
66#[derive(Parser, Debug, Clone)]
67#[command(about = "Postgres database operations", long_about = None)]
68pub enum DatabaseCommand {
69 /// Initializes a new Postgres database with the latest schema.
70 Init(DatabaseConfig),
71 /// Drops roles, privileges and deletes all data from the database.
72 Drop(DatabaseConfig),
73}
74
75#[cfg(feature = "defi")]
76/// Blockchain management options and subcommands.
77#[derive(Parser, Debug)]
78#[command(about = "Blockchain operations", long_about = None)]
79pub struct BlockchainOpt {
80 #[clap(subcommand)]
81 pub command: BlockchainCommand,
82}
83
84#[cfg(feature = "defi")]
85/// Available blockchain management commands.
86#[derive(Parser, Debug, Clone)]
87#[command(about = "Blockchain operations", long_about = None)]
88pub enum BlockchainCommand {
89 /// Syncs blockchain blocks.
90 SyncBlocks {
91 /// The blockchain chain name (case-insensitive). Examples: ethereum, arbitrum, base, polygon, bsc
92 #[arg(long)]
93 chain: String,
94 /// Starting block number to sync from (optional)
95 #[arg(long)]
96 from_block: Option<u64>,
97 /// Ending block number to sync to (optional, defaults to current chain head)
98 #[arg(long)]
99 to_block: Option<u64>,
100 /// Database configuration options
101 #[clap(flatten)]
102 database: DatabaseConfig,
103 },
104 /// Sync DEX pools.
105 SyncDex {
106 /// The blockchain chain name (case-insensitive). Supported chains are listed below.
107 #[arg(long)]
108 chain: String,
109 /// The DEX name (case-insensitive). Supported DEX names are listed below.
110 #[arg(long)]
111 dex: String,
112 /// RPC HTTP URL for blockchain calls (optional, falls back to `RPC_HTTP_URL` env var)
113 #[arg(long)]
114 rpc_url: Option<String>,
115 /// Reset sync progress and start from the beginning, ignoring last synced block
116 #[arg(long)]
117 reset: bool,
118 /// Maximum number of Multicall calls per RPC request (optional, defaults to 200)
119 #[arg(long)]
120 multicall_calls_per_rpc_request: Option<u32>,
121 /// Database configuration options
122 #[clap(flatten)]
123 database: DatabaseConfig,
124 },
125 /// Analyze a specific DEX pool.
126 AnalyzePool {
127 /// The blockchain chain name (case-insensitive). Supported chains are listed below.
128 #[arg(long)]
129 chain: String,
130 /// The DEX name (case-insensitive). Supported DEX names are listed below.
131 #[arg(long)]
132 dex: String,
133 /// The pool contract address
134 #[arg(long)]
135 address: String,
136 /// Starting block number to sync from (optional)
137 #[arg(long)]
138 from_block: Option<u64>,
139 /// Ending block number to sync to (optional, defaults to current chain head)
140 #[arg(long)]
141 to_block: Option<u64>,
142 /// RPC HTTP URL for blockchain calls (optional, falls back to RPC_HTTP_URL env var)
143 #[expect(
144 clippy::doc_markdown,
145 reason = "clap renders doc comments as plain help text"
146 )]
147 #[arg(long)]
148 rpc_url: Option<String>,
149 /// Reset sync progress and start from the beginning, ignoring last synced block
150 #[arg(long)]
151 reset: bool,
152 /// Return needs_bootstrap for pools without a valid snapshot before the target block
153 #[expect(
154 clippy::doc_markdown,
155 reason = "clap renders doc comments as plain help text"
156 )]
157 #[arg(long)]
158 require_existing_snapshot: bool,
159 /// Checkpoint block numbers to snapshot in one pass (comma-separated, each at or below to-block)
160 #[arg(long, value_delimiter = ',')]
161 checkpoint_blocks: Vec<u64>,
162 /// Skip on-chain validation and persist replay-derived snapshots without the multicall compare
163 #[arg(long)]
164 skip_validation: bool,
165 /// Maximum number of Multicall calls per RPC request (optional, defaults to 200)
166 #[arg(long)]
167 multicall_calls_per_rpc_request: Option<u32>,
168 /// Database configuration options
169 #[clap(flatten)]
170 database: DatabaseConfig,
171 },
172 /// Analyze several DEX pools in one runtime.
173 AnalyzePools {
174 /// The blockchain chain name (case-insensitive). Supported chains are listed below.
175 #[arg(long)]
176 chain: String,
177 /// The DEX name (case-insensitive). Supported DEX names are listed below.
178 #[arg(long)]
179 dex: String,
180 /// Pool contract address. Can be repeated.
181 #[arg(long = "address")]
182 addresses: Vec<String>,
183 /// File containing one pool contract address per line. Empty lines and comment lines are ignored.
184 #[arg(long)]
185 addresses_file: Option<String>,
186 /// Starting block number to sync from (optional)
187 #[arg(long)]
188 from_block: Option<u64>,
189 /// Ending block number to sync to (optional, defaults to current chain head)
190 #[arg(long)]
191 to_block: Option<u64>,
192 /// RPC HTTP URL for blockchain calls (optional, falls back to RPC_HTTP_URL env var)
193 #[expect(
194 clippy::doc_markdown,
195 reason = "clap renders doc comments as plain help text"
196 )]
197 #[arg(long)]
198 rpc_url: Option<String>,
199 /// Reset sync progress and start from the beginning, ignoring last synced block
200 #[arg(long)]
201 reset: bool,
202 /// Return needs_bootstrap for pools without a valid snapshot before the target block
203 #[expect(
204 clippy::doc_markdown,
205 reason = "clap renders doc comments as plain help text"
206 )]
207 #[arg(long)]
208 require_existing_snapshot: bool,
209 /// Checkpoint block numbers to snapshot in one pass (comma-separated, each at or below to-block)
210 #[arg(long, value_delimiter = ',')]
211 checkpoint_blocks: Vec<u64>,
212 /// Skip on-chain validation and persist replay-derived snapshots without the multicall compare
213 #[arg(long)]
214 skip_validation: bool,
215 /// Maximum number of pools to analyze concurrently (optional, defaults to 4)
216 #[arg(long)]
217 concurrency: Option<usize>,
218 /// Maximum number of Multicall calls per RPC request (optional, defaults to 200)
219 #[arg(long)]
220 multicall_calls_per_rpc_request: Option<u32>,
221 /// Database configuration options
222 #[clap(flatten)]
223 database: DatabaseConfig,
224 },
225}
226
227#[cfg(all(test, feature = "defi"))]
228mod tests {
229 use clap::Parser;
230 use rstest::rstest;
231
232 use super::*;
233
234 #[rstest]
235 fn analyze_pools_cli_parses_repeated_addresses_file_and_shared_options() {
236 let cli = NautilusCli::try_parse_from([
237 "nautilus",
238 "blockchain",
239 "analyze-pools",
240 "--chain",
241 "ethereum",
242 "--dex",
243 "UniswapV3",
244 "--address",
245 "0x1111111111111111111111111111111111111111",
246 "--address",
247 "0x2222222222222222222222222222222222222222",
248 "--addresses-file",
249 "/tmp/pools.txt",
250 "--from-block",
251 "100",
252 "--to-block",
253 "200",
254 "--rpc-url",
255 "http://localhost:8545",
256 "--reset",
257 "--require-existing-snapshot",
258 "--multicall-calls-per-rpc-request",
259 "25",
260 "--host",
261 "localhost",
262 "--port",
263 "5433",
264 "--username",
265 "postgres",
266 "--database",
267 "nautilus",
268 "--password",
269 "secret",
270 ])
271 .unwrap();
272
273 match cli.command {
274 Commands::Blockchain(BlockchainOpt {
275 command:
276 BlockchainCommand::AnalyzePools {
277 chain,
278 dex,
279 addresses,
280 addresses_file,
281 from_block,
282 to_block,
283 rpc_url,
284 reset,
285 require_existing_snapshot,
286 checkpoint_blocks,
287 skip_validation,
288 concurrency,
289 multicall_calls_per_rpc_request,
290 database,
291 },
292 }) => {
293 assert_eq!(chain, "ethereum");
294 assert_eq!(dex, "UniswapV3");
295 assert_eq!(
296 addresses,
297 vec![
298 "0x1111111111111111111111111111111111111111".to_string(),
299 "0x2222222222222222222222222222222222222222".to_string(),
300 ]
301 );
302 assert_eq!(addresses_file.as_deref(), Some("/tmp/pools.txt"));
303 assert_eq!(from_block, Some(100));
304 assert_eq!(to_block, Some(200));
305 assert_eq!(rpc_url.as_deref(), Some("http://localhost:8545"));
306 assert!(reset);
307 assert!(require_existing_snapshot);
308 assert!(checkpoint_blocks.is_empty());
309 assert!(!skip_validation);
310 assert_eq!(concurrency, None);
311 assert_eq!(multicall_calls_per_rpc_request, Some(25));
312 assert_eq!(database.host.as_deref(), Some("localhost"));
313 assert_eq!(database.port, Some(5433));
314 assert_eq!(database.username.as_deref(), Some("postgres"));
315 assert_eq!(database.database.as_deref(), Some("nautilus"));
316 assert_eq!(database.password.as_deref(), Some("secret"));
317 assert_eq!(database.schema, None);
318 }
319 _ => panic!("Expected analyze-pools blockchain command"),
320 }
321 }
322
323 #[rstest]
324 #[case("analyze-pool")]
325 #[case("analyze-pools")]
326 fn blockchain_analysis_help_lists_capabilities_as_plain_text(#[case] subcommand: &str) {
327 let mut command = crate::cli_command();
328 let help = command
329 .find_subcommand_mut("blockchain")
330 .and_then(|command| command.find_subcommand_mut(subcommand))
331 .map(|command| command.render_long_help().to_string())
332 .unwrap();
333
334 // Snapshot-capable DEXes are listed; the registered-but-unsupported SushiSwapV2 is not.
335 assert!(help.contains("UniswapV3"));
336 assert!(help.contains("PancakeSwapV3"));
337 assert!(help.contains("AerodromeSlipstream"));
338 assert!(!help.contains("SushiSwapV2"));
339 assert!(help.contains("RPC_HTTP_URL"));
340 assert!(help.contains("needs_bootstrap"));
341 // Help is rendered as plain text, so doc-markdown backticks must not survive.
342 assert!(!help.contains("`UniswapV3`"));
343 assert!(!help.contains("`PancakeSwapV3`"));
344 assert!(!help.contains("`RPC_HTTP_URL`"));
345 assert!(!help.contains("`needs_bootstrap`"));
346 }
347
348 #[rstest]
349 fn blockchain_sync_dex_help_lists_discoverable_dexes() {
350 let mut command = crate::cli_command();
351 let help = command
352 .find_subcommand_mut("blockchain")
353 .and_then(|command| command.find_subcommand_mut("sync-dex"))
354 .map(|command| command.render_long_help().to_string())
355 .unwrap();
356
357 // sync-dex receives the discovery block, not the snapshot block.
358 assert!(help.contains("Discoverable DEXes"));
359 assert!(!help.contains("Snapshot-capable"));
360 // UniswapV2 is discovery-only, so it appears here but never in the snapshot listing.
361 assert!(help.contains("UniswapV2"));
362 }
363}