Skip to main content

tycho_client/
cli.rs

1use std::{path::Path, str::FromStr, time::Duration};
2
3use clap::Parser;
4use tracing::info;
5use tracing_appender::rolling;
6use tycho_common::{dto::TvlThresholdTier, models::Chain};
7
8use crate::{
9    feed::{component_tracker::ComponentFilter, dto::FeedMessage as FeedMessageDto},
10    stream::TychoStreamBuilder,
11};
12
13/// Tycho Client CLI - A tool for indexing and tracking blockchain protocol data
14///
15/// This CLI tool connects to a Tycho server and tracks various blockchain protocols,
16/// providing real-time updates about their state.
17#[derive(Parser, Debug, Clone, PartialEq)]
18#[clap(version = env!("CARGO_PKG_VERSION"))]
19#[expect(clippy::struct_excessive_bools, reason = "each bool is an independent CLI flag")]
20struct CliArgs {
21    /// Tycho server URL, without protocol. Example: localhost:4242
22    #[clap(long, default_value = "localhost:4242", env = "TYCHO_URL")]
23    tycho_url: String,
24
25    /// Tycho gateway API key, used as authentication for both websocket and http connections.
26    /// Can be set with TYCHO_AUTH_TOKEN env variable.
27    #[clap(short = 'k', long, env = "TYCHO_AUTH_TOKEN")]
28    auth_key: Option<String>,
29
30    /// If set, use unsecured transports: http and ws instead of https and wss.
31    #[clap(long)]
32    no_tls: bool,
33
34    /// The blockchain to index on
35    #[clap(short = 'c', long, default_value = "ethereum")]
36    chain: String,
37
38    /// Specifies exchanges. Optionally also supply a pool address in the format
39    /// {exchange}-{pool_address}
40    #[clap(short = 'e', long, number_of_values = 1)]
41    exchange: Vec<String>,
42
43    /// Specifies the minimum TVL to filter the components. Denoted in the native token.
44    /// Defaults to a chain-appropriate value targeting ~$20K USD equivalent.
45    /// Ignored if addresses or range tvl values are provided.
46    #[clap(long)]
47    min_tvl: Option<f64>,
48
49    /// Specifies the lower bound of the TVL threshold range. Denoted in the native token (e.g.
50    /// Mainnet -> ETH). Components below this TVL will be removed from tracking.
51    #[clap(long)]
52    remove_tvl_threshold: Option<f64>,
53
54    /// Specifies the upper bound of the TVL threshold range. Denoted in the native token (e.g.
55    /// Mainnet -> ETH). Components above this TVL will be added to tracking.
56    #[clap(long)]
57    add_tvl_threshold: Option<f64>,
58
59    /// Expected block time in seconds. Defaults to the canonical block time for the selected
60    /// chain (e.g. 12s for Ethereum, 2s for Base).
61    ///
62    /// Adjusting `block_time` helps balance efficiency and responsiveness:
63    /// - **Low values**: Increase sync frequency but may waste resources on retries.
64    /// - **High values**: Reduce sync frequency but may delay updates on faster chains.
65    #[clap(long)]
66    block_time: Option<u64>,
67
68    /// Maximum wait time in seconds beyond the block time. Useful for handling
69    /// chains with variable block intervals or network delays. Defaults to a chain-appropriate
70    /// value.
71    #[clap(long)]
72    timeout: Option<u64>,
73
74    /// Logging folder path.
75    #[clap(long, default_value = "logs")]
76    log_folder: String,
77
78    /// Run the example on a single block with UniswapV2 and UniswapV3.
79    #[clap(long)]
80    example: bool,
81
82    /// If set, only component and tokens are streamed, any snapshots or state updates
83    /// are omitted from the stream.
84    #[clap(long)]
85    no_state: bool,
86
87    /// Maximum amount of messages to process before exiting. Useful for debugging e.g.
88    /// to easily get a state sync messages for a fixture. Alternatively this may be
89    /// used to trigger a regular restart or resync.
90    #[clap(short='n', long, default_value=None)]
91    max_messages: Option<usize>,
92
93    /// Maximum blocks an exchange can be absent for before it is marked as stale. Used
94    /// in conjunction with block_time to calculate a timeout: block_time * max_missed_blocks.
95    /// Defaults to a chain-appropriate value.
96    #[clap(long)]
97    max_missed_blocks: Option<u64>,
98
99    /// If set, the synchronizer will include TVL in the messages.
100    /// Enabling this option will increase the number of network requests made during start-up,
101    /// which may result in increased start-up latency.
102    #[clap(long)]
103    include_tvl: bool,
104
105    /// If set, disable compression for WebSocket messages.
106    /// By default, messages are compressed using zstd.
107    #[clap(long)]
108    disable_compression: bool,
109
110    /// If set, enables receiving partial block updates (flashblocks).
111    /// This allows the client to receive incremental updates within a block, allowing for
112    /// lower latency.
113    #[clap(long)]
114    partial_blocks: bool,
115
116    /// Enable verbose logging. This will show more detailed information about the
117    /// synchronization process and any errors that occur.
118    #[clap(long)]
119    verbose: bool,
120
121    /// Maximum number of retry attempts for failed startups
122    #[clap(long, default_value = "32")]
123    max_retries: u64,
124
125    /// Maximum random delay in seconds before a restarted synchronizer requests a snapshot.
126    /// Spreads snapshot requests after a server or extractor restart. The first start has no
127    /// delay. The minimum is 5.
128    #[clap(long, default_value = "60", value_parser = clap::value_parser!(u64).range(5..))]
129    snapshot_jitter: u64,
130
131    /// Path to a TOML file containing component IDs to exclude from tracking.
132    #[clap(long)]
133    blocklist_config: Option<std::path::PathBuf>,
134}
135
136impl CliArgs {
137    fn validate(&self) -> Result<(), String> {
138        // TVL thresholds must be set together - either both or neither
139        match (self.remove_tvl_threshold, self.add_tvl_threshold) {
140            (Some(remove), Some(add)) if remove >= add => {
141                return Err("remove_tvl_threshold must be less than add_tvl_threshold".to_string());
142            }
143            (Some(_), None) | (None, Some(_)) => {
144                return Err(
145                    "Both remove_tvl_threshold and add_tvl_threshold must be set.".to_string()
146                );
147            }
148            _ => {}
149        }
150
151        Ok(())
152    }
153}
154
155#[derive(serde::Deserialize)]
156struct BlocklistFile {
157    ids: Vec<String>,
158}
159
160fn load_blocklist(path: &Path) -> Result<Vec<String>, String> {
161    let content = std::fs::read_to_string(path)
162        .map_err(|e| format!("Failed to read blocklist file {}: {e}", path.display()))?;
163    let file: BlocklistFile = toml::from_str(&content)
164        .map_err(|e| format!("Failed to parse blocklist file {}: {e}", path.display()))?;
165    Ok(file.ids)
166}
167
168pub async fn run_cli() -> Result<(), String> {
169    // Parse CLI Args
170    let args: CliArgs = CliArgs::parse();
171    args.validate()?;
172
173    // Setup Logging
174    let log_level = if args.verbose { "debug" } else { "info" };
175    let (non_blocking, _guard) =
176        tracing_appender::non_blocking(rolling::never(&args.log_folder, "dev_logs.log"));
177    let subscriber = tracing_subscriber::fmt()
178        .with_env_filter(
179            tracing_subscriber::EnvFilter::try_from_default_env()
180                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(log_level)),
181        )
182        .with_writer(non_blocking)
183        .finish();
184
185    tracing::subscriber::set_global_default(subscriber)
186        .map_err(|e| format!("Failed to set up logging subscriber: {e}"))?;
187
188    // Build the list of exchanges.  When --example is provided, we seed the list with a fixed
189    // pair of well-known pools, otherwise we parse user supplied values (either plain exchange
190    // names or exchange-pool pairs in the {exchange}-{pool_address} format).
191    let exchanges: Vec<(String, Option<String>)> = if args.example {
192        // You will need to port-forward tycho to run the example:
193        //
194        // ```bash
195        // kubectl port-forward -n dev-tycho deploy/tycho-indexer 8888:4242
196        // ```
197        vec![
198            (
199                "uniswap_v3".to_string(),
200                Some("0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640".to_string()),
201            ),
202            (
203                "uniswap_v2".to_string(),
204                Some("0xa478c2975ab1ea89e8196811f51a7b7ade33eb11".to_string()),
205            ),
206        ]
207    } else {
208        args.exchange
209            .iter()
210            .filter_map(|e| {
211                if e.contains('-') {
212                    let parts: Vec<&str> = e.split('-').collect();
213                    if parts.len() == 2 {
214                        Some((parts[0].to_string(), Some(parts[1].to_string())))
215                    } else {
216                        tracing::warn!("Ignoring invalid exchange format: {}", e);
217                        None
218                    }
219                } else {
220                    Some((e.to_string(), None))
221                }
222            })
223            .collect()
224    };
225
226    info!("Running with exchanges: {:?}", exchanges);
227
228    run(exchanges, args).await?;
229    Ok(())
230}
231
232async fn run(exchanges: Vec<(String, Option<String>)>, args: CliArgs) -> Result<(), String> {
233    let blocklist = match &args.blocklist_config {
234        Some(path) => load_blocklist(path)?,
235        None => Vec::new(),
236    };
237
238    let chain = Chain::from_str(&args.chain)
239        .map_err(|e| format!("Unknown chain: {chain}: {e}", chain = args.chain))?;
240
241    let mut builder = TychoStreamBuilder::new(&args.tycho_url, chain)
242        .auth_key(args.auth_key)
243        .no_tls(args.no_tls)
244        .no_state(args.no_state)
245        .include_tvl(args.include_tvl)
246        .max_retries(args.max_retries)
247        .snapshot_jitter(Duration::from_secs(args.snapshot_jitter))
248        .blocklisted_ids(blocklist);
249
250    if let Some(bt) = args.block_time {
251        builder = builder.block_time(bt);
252    }
253    if let Some(to) = args.timeout {
254        builder = builder.timeout(to);
255    }
256    if let Some(mmb) = args.max_missed_blocks {
257        builder = builder.max_missed_blocks(mmb);
258    }
259    if args.disable_compression {
260        builder = builder.disable_compression();
261    }
262    if args.partial_blocks {
263        builder = builder.enable_partial_blocks();
264    }
265    if let Some(n) = args.max_messages {
266        builder = builder.max_messages(n);
267    }
268    // Register exchanges
269    let builder = exchanges
270        .into_iter()
271        .fold(builder, |b, (name, address)| {
272            let filter = if let Some(addr) = address {
273                ComponentFilter::Ids(vec![addr])
274            } else if let (Some(remove_tvl), Some(add_tvl)) =
275                (args.remove_tvl_threshold, args.add_tvl_threshold)
276            {
277                ComponentFilter::with_tvl_range(remove_tvl, add_tvl)
278            } else {
279                let default_min_tvl = chain.default_tvl_threshold(TvlThresholdTier::Low);
280                let min_tvl = args.min_tvl.unwrap_or(default_min_tvl);
281                ComponentFilter::with_tvl_range(min_tvl, min_tvl)
282            };
283            b.exchange(&name, filter)
284        });
285
286    let (handle, mut rx) = builder
287        .build()
288        .await
289        .map_err(|e| e.to_string())?;
290
291    let msg_printer = tokio::spawn(async move {
292        while let Some(result) = rx.recv().await {
293            let msg =
294                result.map_err(|e| format!("Message printer received synchronizer error: {e}"))?;
295
296            let json = serde_json::to_string(&FeedMessageDto::from(msg))
297                .map_err(|e| format!("Message printer failed to serialize message: {e}"))?;
298            println!("{json}");
299        }
300
301        Ok::<(), String>(())
302    });
303
304    // Monitor the stream handle and message printer futures.
305    let (failed_task, shutdown_reason) = tokio::select! {
306        res = handle => (
307            "Stream",
308            res.err().map(|e| e.to_string())
309        ),
310        res = msg_printer => (
311            "MessagePrinter",
312            extract_nested_error(res)
313        ),
314    };
315
316    Err(format!(
317        "{failed_task} task terminated: {}",
318        shutdown_reason.unwrap_or_else(|| "unknown reason".to_string())
319    ))
320}
321
322#[inline]
323fn extract_nested_error<T, E1: ToString, E2: ToString>(
324    res: Result<Result<T, E1>, E2>,
325) -> Option<String> {
326    res.map_err(|e| e.to_string())
327        .and_then(|r| r.map_err(|e| e.to_string()))
328        .err()
329}
330
331#[cfg(test)]
332mod cli_tests {
333    use clap::Parser;
334
335    use super::CliArgs;
336
337    #[tokio::test]
338    async fn test_cli_args() {
339        let args = CliArgs::parse_from([
340            "tycho-client",
341            "--tycho-url",
342            "localhost:5000",
343            "--exchange",
344            "uniswap_v2",
345            "--min-tvl",
346            "3000",
347            "--block-time",
348            "50",
349            "--timeout",
350            "5",
351            "--log-folder",
352            "test_logs",
353            "--example",
354            "--max-messages",
355            "1",
356            "--blocklist-config",
357            "blocklist.toml",
358        ]);
359        let exchanges: Vec<String> = vec!["uniswap_v2".to_string()];
360        assert_eq!(args.tycho_url, "localhost:5000");
361        assert_eq!(args.exchange, exchanges);
362        assert_eq!(args.min_tvl, Some(3000.0));
363        assert_eq!(args.block_time, Some(50));
364        assert_eq!(args.timeout, Some(5));
365        assert_eq!(args.log_folder, "test_logs");
366        assert_eq!(args.max_messages, Some(1));
367        assert!(args.example);
368        assert_eq!(args.disable_compression, false);
369        assert_eq!(args.partial_blocks, false);
370        assert_eq!(args.snapshot_jitter, 60);
371        assert_eq!(args.blocklist_config, Some(std::path::PathBuf::from("blocklist.toml")));
372
373        let args = CliArgs::parse_from([
374            "tycho-client",
375            "--exchange",
376            "uniswap_v2",
377            "--snapshot-jitter",
378            "5",
379        ]);
380        assert_eq!(args.snapshot_jitter, 5);
381
382        let res = CliArgs::try_parse_from([
383            "tycho-client",
384            "--exchange",
385            "uniswap_v2",
386            "--snapshot-jitter",
387            "4",
388        ]);
389        assert!(res.is_err(), "A snapshot jitter below 5 should be rejected");
390    }
391}