Skip to main content

cast/cmd/
logs.rs

1use super::MAX_CONCURRENT_RPC_REQUESTS;
2use crate::args::encode_event_topic;
3use alloy_consensus::BlockHeader;
4use alloy_dyn_abi::{EventExt, Specifier};
5use alloy_ens::NameOrAddress;
6use alloy_json_abi::Event;
7use alloy_json_rpc::RpcError;
8use alloy_network::{AnyNetwork, BlockResponse, Network};
9use alloy_primitives::{Address, B256, TxHash};
10use alloy_provider::Provider;
11use alloy_rpc_types::{BlockId, BlockNumberOrTag, Filter, FilterBlockOption, Log, Topic};
12use alloy_transport::TransportErrorKind;
13use clap::Parser;
14use eyre::Result;
15use foundry_cli::{
16    opts::RpcOpts,
17    utils::{self, LoadConfig},
18};
19use foundry_common::{
20    fmt::{UIfmt, format_token},
21    shell,
22};
23use futures::{FutureExt, Stream, StreamExt, TryStreamExt, future::Either};
24use std::{fmt::Write as _, str::FromStr};
25use tokio::signal::ctrl_c;
26
27/// CLI arguments for `cast logs`.
28#[derive(Debug, Parser)]
29pub struct LogsArgs {
30    #[command(flatten)]
31    query: LogQueryArgs,
32
33    /// If the RPC type and endpoints supports `eth_subscribe` stream logs instead of printing and
34    /// exiting. Will continue until interrupted or TO_BLOCK is reached.
35    #[arg(long)]
36    subscribe: bool,
37
38    #[command(flatten)]
39    rpc: RpcOpts,
40}
41
42/// Arguments shared by commands that query logs with `eth_getLogs`.
43#[derive(Debug, Parser)]
44pub struct LogQueryArgs {
45    /// The block height to start query at.
46    ///
47    /// Can also be the tags earliest, finalized, safe, latest, or pending.
48    #[arg(long)]
49    from_block: Option<BlockId>,
50
51    /// The block height to stop query at.
52    ///
53    /// Can also be the tags earliest, finalized, safe, latest, or pending.
54    #[arg(long)]
55    to_block: Option<BlockId>,
56
57    /// The contract address to filter on.
58    #[arg(long, value_parser = NameOrAddress::from_str)]
59    address: Option<Vec<NameOrAddress>>,
60
61    /// The signature of the event to filter logs by which will be converted to the first topic or
62    /// a topic to filter on.
63    #[arg(value_name = "SIG_OR_TOPIC")]
64    sig_or_topic: Option<String>,
65
66    /// If used with a signature, the indexed fields of the event to filter by. Otherwise, the
67    /// remaining topics of the filter.
68    #[arg(value_name = "TOPICS_OR_ARGS")]
69    topics_or_args: Vec<String>,
70
71    /// Split the query into chunks of this many blocks to work around provider range/result
72    /// limits.
73    ///
74    /// When omitted, the range is queried in a single request. Pass a value (e.g. `10000`) to
75    /// fetch the logs in `query-size`-block chunks instead.
76    #[arg(long, value_name = "BLOCKS")]
77    query_size: Option<u64>,
78}
79
80impl LogsArgs {
81    pub async fn run(self) -> Result<()> {
82        let Self { query, subscribe, rpc } = self;
83
84        let config = rpc.load_config()?;
85        let provider = utils::get_provider(&config)?;
86        let (filter, query_size, event) = query.resolve_with_event(&provider).await?;
87
88        if !subscribe {
89            let logs = match query_size {
90                Some(chunk_size) => format_logs(
91                    get_logs_chunked(&provider, &filter, chunk_size).await?,
92                    event.as_ref(),
93                )?,
94                None => format_logs(provider.get_logs(&filter).await?, event.as_ref())?,
95            };
96            sh_println!("{logs}")?;
97            return Ok(());
98        }
99
100        // JSON envelope intentionally unsupported for streaming: --subscribe emits NDJSON events
101        // continuously; a terminal JsonEnvelope is pointless.
102        // FIXME: this is a hotfix for <https://github.com/foundry-rs/foundry/issues/7682>
103        //  currently the alloy `eth_subscribe` impl does not work with all transports, so we use
104        // the builtin transport here for now
105        let url = config.get_rpc_url_or_localhost_http()?;
106        let provider = alloy_provider::ProviderBuilder::<_, _, AnyNetwork>::default()
107            .connect(url.as_ref())
108            .await?;
109        let subscription = provider.subscribe_logs(&filter).await?.into_stream();
110
111        // Subscribe to blocks when a `to_block` is set so the stream ends once it is passed.
112        let to_block = filter.get_to_block();
113        let blocks = match to_block {
114            Some(_) => Some(provider.subscribe_blocks().await?.into_stream()),
115            None => None,
116        };
117
118        // Break on the cancel signal so the JSON array is still closed.
119        stream_logs(
120            &mut std::io::stdout(),
121            subscription,
122            blocks,
123            to_block,
124            event.as_ref(),
125            ctrl_c(),
126        )
127        .await
128    }
129}
130
131/// Writes the logs of `logs` to `output` until the stream ends, `blocks` passes `to_block`, or
132/// `cancel` resolves.
133async fn stream_logs<H: BlockHeader>(
134    output: &mut impl std::io::Write,
135    mut logs: impl Stream<Item = Log> + Unpin,
136    mut blocks: Option<impl Stream<Item = H> + Unpin>,
137    to_block: Option<u64>,
138    event: Option<&Event>,
139    cancel: impl Future,
140) -> Result<()> {
141    let format_json = shell::is_json();
142    if format_json {
143        write!(output, "[")?;
144    }
145
146    let mut cancel = std::pin::pin!(cancel);
147    let mut first = true;
148    let mut warned_decode_failure = false;
149    loop {
150        tokio::select! {
151            block = match &mut blocks {
152                Some(bs) => Either::Left(bs.next().fuse()),
153                None => Either::Right(futures::future::pending()),
154            } => match (block, to_block) {
155                (Some(block), Some(to_block)) if block.number() > to_block => break,
156                (Some(_), _) => {}
157                // An ended stream yields at once, so polling it again would spin.
158                (None, _) => blocks = None,
159            },
160            log = logs.next() => {
161                let Some(log) = log else { break };
162                // Log subscriptions ignore the filter's block range, so a log past `to_block` can
163                // arrive before the block that passes it.
164                if let (Some(block), Some(to_block)) = (log.block_number, to_block)
165                    && block > to_block
166                {
167                    break;
168                }
169                if format_json {
170                    if !first {
171                        write!(output, ",")?;
172                    }
173                    first = false;
174                    write!(output, "{}", serde_json::to_string(&log).unwrap())?;
175                } else {
176                    let (formatted, decode_failed) = format_log(&log, event);
177                    if decode_failed && !warned_decode_failure {
178                        warned_decode_failure = true;
179                        sh_warn!(
180                            "failed to decode a log with the provided event signature; \
181                             make sure its indexed parameters match the log topics"
182                        )?;
183                    }
184                    writeln!(output, "{formatted}")?;
185                }
186            },
187            _ = &mut cancel => break,
188            else => break,
189        }
190    }
191
192    if format_json {
193        write!(output, "]")?;
194    }
195    Ok(())
196}
197
198impl LogQueryArgs {
199    /// Takes a lone positional transaction hash, if present.
200    pub(super) fn take_transaction_hash(&mut self) -> Option<TxHash> {
201        if self.from_block.is_none()
202            && self.to_block.is_none()
203            && self.address.is_none()
204            && self.topics_or_args.is_empty()
205            && self.query_size.is_none()
206            && let Some(tx_hash) = self.sig_or_topic.as_deref().and_then(|value| value.parse().ok())
207        {
208            self.sig_or_topic = None;
209            return Some(tx_hash);
210        }
211        None
212    }
213
214    /// Resolves names and block tags and builds the RPC filter.
215    pub async fn resolve<P: Provider<N>, N: Network>(
216        self,
217        provider: &P,
218    ) -> Result<(Filter, Option<u64>)> {
219        let (filter, query_size, _) = self.resolve_with_event(provider).await?;
220        Ok((filter, query_size))
221    }
222
223    async fn resolve_with_event<P: Provider<N>, N: Network>(
224        self,
225        provider: &P,
226    ) -> Result<(Filter, Option<u64>, Option<Event>)> {
227        let Self { from_block, to_block, address, sig_or_topic, topics_or_args, query_size } = self;
228
229        let addresses = match address {
230            Some(addresses) => Some(
231                futures::future::try_join_all(
232                    addresses.iter().map(|address| address.resolve(provider)),
233                )
234                .await?,
235            ),
236            None => None,
237        };
238
239        let from_block =
240            convert_block_number(&provider, Some(from_block.unwrap_or_else(BlockId::earliest)))
241                .await?;
242        let to_block =
243            convert_block_number(&provider, Some(to_block.unwrap_or_else(BlockId::latest))).await?;
244        let (filter, event) =
245            build_filter(from_block, to_block, addresses, sig_or_topic, topics_or_args)?;
246
247        Ok((filter, query_size, event))
248    }
249}
250
251/// Builds a Filter by first trying to parse the `sig_or_topic` as an event signature. If
252/// successful, `topics_or_args` is parsed as indexed inputs and converted to topics. Otherwise,
253/// `sig_or_topic` is prepended to `topics_or_args` and used as raw topics.
254fn build_filter(
255    from_block: Option<BlockNumberOrTag>,
256    to_block: Option<BlockNumberOrTag>,
257    address: Option<Vec<Address>>,
258    sig_or_topic: Option<String>,
259    topics_or_args: Vec<String>,
260) -> Result<(Filter, Option<Event>)> {
261    let (topics, event) = match sig_or_topic {
262        Some(sig_or_topic) => match foundry_common::abi::get_event(&sig_or_topic) {
263            Ok(parsed) => {
264                let topics = event_topics(&parsed, &topics_or_args)?;
265                (topics, Some(parsed))
266            }
267            Err(_) => (raw_topics([vec![sig_or_topic], topics_or_args].concat())?, None),
268        },
269        None => (Default::default(), None),
270    };
271
272    let mut filter = Filter {
273        block_option: FilterBlockOption::Range { from_block, to_block },
274        topics,
275        ..Default::default()
276    };
277    if let Some(address) = address {
278        filter = filter.address(address);
279    }
280    Ok((filter, event))
281}
282
283/// Encodes `args` as the indexed topics of `event`; empty arguments match any value. Anonymous
284/// events have no selector topic, so their indexed inputs start at the first topic.
285fn event_topics(event: &Event, args: &[String]) -> Result<[Topic; 4]> {
286    let mut topics = if event.anonymous { vec![] } else { vec![Topic::from(event.selector())] };
287    let indexed = event.inputs.iter().filter(|input| input.indexed);
288    let indexed_count = indexed.clone().count();
289    eyre::ensure!(
290        topics.len() + indexed_count <= 4,
291        "event `{}` has too many indexed inputs: a log has at most 4 topics",
292        event.name
293    );
294    // `zip` stops at the shorter side, so arguments past the last indexed input would be dropped
295    // without a word and the query would match more logs than the user asked for.
296    eyre::ensure!(
297        args.len() <= indexed_count,
298        "event `{}` has {indexed_count} indexed parameters, but {} filter arguments were provided",
299        event.name,
300        args.len()
301    );
302    for (input, arg) in indexed.zip(args) {
303        let kind = input.resolve()?;
304        topics.push(if arg.is_empty() {
305            Topic::default()
306        } else {
307            Topic::from(encode_event_topic(&kind.coerce_str(arg)?))
308        });
309    }
310    topics.resize(4, Topic::default());
311    Ok(topics.try_into().unwrap())
312}
313
314/// Parses raw topic hashes; empty topics match any value.
315fn raw_topics(topics: Vec<String>) -> Result<[Topic; 4]> {
316    // `resize` truncates, so topics past the fourth would be dropped without a word and the
317    // query would match more logs than the user asked for.
318    eyre::ensure!(
319        topics.len() <= 4,
320        "a log filter supports at most 4 topics, but {} were provided",
321        topics.len()
322    );
323    let mut topics = topics
324        .into_iter()
325        .map(|topic| {
326            Ok(if topic.is_empty() {
327                Topic::default()
328            } else {
329                Topic::from(B256::from_str(&topic)?)
330            })
331        })
332        .collect::<Result<Vec<_>>>()?;
333    topics.resize(4, Topic::default());
334    Ok(topics.try_into().unwrap())
335}
336
337/// Fetches logs for the inclusive `[from, to]` range, recursively bisecting on failure.
338fn get_logs_bisecting<'a, P: Provider<N>, N: Network>(
339    provider: &'a P,
340    filter: &'a Filter,
341    from: u64,
342    to: u64,
343) -> futures::future::BoxFuture<'a, Result<Vec<Log>>> {
344    Box::pin(async move {
345        let range_filter = filter.clone().from_block(from).to_block(to);
346        match provider.get_logs(&range_filter).await {
347            Ok(logs) => Ok(logs),
348            Err(e) => {
349                // Only bisect range-limit errors with room left to split; surface anything
350                // else immediately.
351                if from >= to || !is_range_limit_error(&e) {
352                    return Err(e.into());
353                }
354
355                // Bisect sequentially: this path is only reached after a provider failure, so
356                // fanning out concurrently here would risk amplifying rate-limit errors and
357                // would defeat the top-level concurrency cap.
358                let mid = from + (to - from) / 2;
359                let mut left = get_logs_bisecting(provider, filter, from, mid).await?;
360                let right = get_logs_bisecting(provider, filter, mid + 1, to).await?;
361                left.extend(right);
362                Ok(left)
363            }
364        }
365    })
366}
367
368/// Retrieves logs for the inclusive `[from, to]` range using concurrent chunked requests.
369async fn get_logs_chunked_concurrent<P: Provider<N>, N: Network>(
370    provider: &P,
371    filter: &Filter,
372    from: u64,
373    to: u64,
374    chunk_size: u64,
375) -> Result<Vec<Log>> {
376    let chunk_ranges = (from..=to)
377        .step_by(chunk_size as usize)
378        .map(|start| (start, start.saturating_add(chunk_size - 1).min(to)));
379
380    // `buffered` preserves input order, so results stay ordered by block. `try_collect` stops
381    // early and surfaces the error if any chunk ultimately fails.
382    let chunks: Vec<Vec<Log>> = futures::stream::iter(chunk_ranges)
383        .map(|(start, end)| get_logs_bisecting(provider, filter, start, end))
384        .buffered(MAX_CONCURRENT_RPC_REQUESTS)
385        .try_collect()
386        .await?;
387
388    Ok(chunks.into_iter().flatten().collect())
389}
390
391/// Resolves a [`BlockNumberOrTag`] to a concrete block number, querying the provider for tags.
392async fn resolve_block_tag<P: Provider<N>, N: Network>(
393    provider: &P,
394    tag: BlockNumberOrTag,
395) -> Result<u64> {
396    match tag {
397        BlockNumberOrTag::Number(number) => Ok(number),
398        BlockNumberOrTag::Earliest => Ok(0),
399        tag => {
400            let block = provider
401                .get_block(BlockId::Number(tag))
402                .await?
403                .ok_or_else(|| eyre::eyre!("could not resolve block tag `{tag}`"))?;
404            Ok(block.header().number())
405        }
406    }
407}
408
409/// Resolves the filter's block range to concrete block numbers.
410///
411/// Returns `None` when the filter does not target a block-number range (e.g. it filters by
412/// block hash), in which case chunking is not possible. Tags such as `latest` and `earliest`
413/// are resolved against the provider so that the common case (`--to-block` defaulting to
414/// `latest`) can still be chunked.
415async fn resolve_block_range<P: Provider<N>, N: Network>(
416    provider: &P,
417    filter: &Filter,
418) -> Result<Option<(u64, u64)>> {
419    let FilterBlockOption::Range { from_block, to_block } = &filter.block_option else {
420        return Ok(None);
421    };
422
423    let from_tag = from_block.unwrap_or(BlockNumberOrTag::Earliest);
424    let to_tag = to_block.unwrap_or(BlockNumberOrTag::Latest);
425
426    // `pending` is not a concrete canonical range boundary; don't chunk it, so the single
427    // request preserves the provider's native `pending` semantics.
428    if from_tag.is_pending() || to_tag.is_pending() {
429        return Ok(None);
430    }
431
432    let from = resolve_block_tag(provider, from_tag).await?;
433    // Resolve identical tags only once so a moving head (e.g. `latest`..`latest`) can't yield
434    // an inconsistent range.
435    let to = if from_tag == to_tag { from } else { resolve_block_tag(provider, to_tag).await? };
436    Ok(Some((from, to)))
437}
438
439/// Retrieves logs, splitting the request into fixed-size block chunks when needed.
440pub(super) async fn get_logs_chunked<P: Provider<N>, N: Network>(
441    provider: &P,
442    filter: &Filter,
443    chunk_size: u64,
444) -> Result<Vec<Log>> {
445    // Only chunk a finite block-number range larger than one chunk; `chunk_size == 0`
446    // disables chunking and falls back to a single request.
447    let Some((from, to)) = resolve_block_range(provider, filter).await? else {
448        return provider.get_logs(filter).await.map_err(Into::into);
449    };
450    // Inverted range yields no logs; warn instead of returning empty silently.
451    if from > to {
452        sh_warn!(
453            "requested block range is inverted (from-block {from} > to-block {to}); no logs to return"
454        )?;
455        return Ok(vec![]);
456    }
457    if chunk_size == 0 || to - from < chunk_size {
458        return provider.get_logs(filter).await.map_err(Into::into);
459    }
460
461    get_logs_chunked_concurrent(provider, filter, from, to, chunk_size).await
462}
463
464async fn convert_block_number<P: Provider<N>, N: Network>(
465    provider: &P,
466    block: Option<BlockId>,
467) -> Result<Option<BlockNumberOrTag>> {
468    match block {
469        Some(BlockId::Number(number)) => Ok(Some(number)),
470        Some(BlockId::Hash(hash)) => {
471            let block = provider
472                .get_block_by_hash(hash.block_hash)
473                .await?
474                .ok_or_else(|| eyre::eyre!("block {} not found", hash.block_hash))?;
475            Ok(Some(block.header().number().into()))
476        }
477        None => Ok(None),
478    }
479}
480
481fn format_logs(logs: Vec<Log>, event: Option<&Event>) -> Result<String> {
482    if shell::is_json() {
483        Ok(serde_json::to_string(&logs)?)
484    } else {
485        let total = logs.len();
486        let mut failed = 0;
487        let formatted = logs
488            .iter()
489            .map(|log| {
490                let (text, decode_failed) = format_log(log, event);
491                failed += usize::from(decode_failed);
492                text
493            })
494            .collect::<Vec<_>>()
495            .join("\n");
496        if failed > 0 {
497            sh_warn!(
498                "failed to decode {failed} of {total} logs with the provided event signature; \
499                 make sure its indexed parameters match the log topics"
500            )?;
501        }
502        Ok(formatted)
503    }
504}
505
506fn format_log(log: &Log, event: Option<&Event>) -> (String, bool) {
507    let mut pretty = log.pretty();
508    let mut decode_failed = false;
509    if let Some(event) = event {
510        match format_log_params(event, log) {
511            Some(decoded) => pretty.push_str(&decoded),
512            None => decode_failed = true,
513        }
514    }
515    (pretty.replacen('\n', "- ", 1).replace('\n', "\n  "), decode_failed)
516}
517
518/// Formats decoded event parameters in declaration order.
519fn format_log_params(event: &Event, log: &Log) -> Option<String> {
520    let decoded = event.decode_log(log.data()).ok()?;
521    let mut indexed = decoded.indexed.iter();
522    let mut body = decoded.body.iter();
523    let mut result = String::from("\ndecoded:");
524    for (i, input) in event.inputs.iter().enumerate() {
525        let value = if input.indexed { indexed.next() } else { body.next() }?;
526        let name = if input.name.is_empty() { format!("param{i}") } else { input.name.clone() };
527        write!(result, "\n\t{name}: {}", format_token(value)).ok()?;
528    }
529    Some(result)
530}
531
532/// Returns `true` if `err` is a provider range/result-size limit that retrying over a smaller
533/// range can fix. Network, auth, rate-limit, and malformed-response errors return `false`.
534fn is_range_limit_error(err: &RpcError<TransportErrorKind>) -> bool {
535    // Only HTTP 413 (payload too large) is fixable by a smaller range; other transport errors
536    // (network, auth 401/403, rate-limit 429) are not.
537    if let RpcError::Transport(kind) = err {
538        return kind.as_http_error().is_some_and(|http| http.status == 413);
539    }
540
541    // Range/result-size limits are reported as JSON-RPC server error responses; every other
542    // variant falls through to `false`.
543    let RpcError::ErrorResp(payload) = err else { return false };
544    let message = payload.message.to_ascii_lowercase();
545
546    // Phrases providers use for range/result-size limits, kept specific so rate-limit/quota
547    // wording (e.g. "no more than 10 requests per second") doesn't match.
548    const RANGE_LIMIT_HINTS: &[&str] = &[
549        "block range",
550        "blocks range",
551        "range is too",
552        "range too",
553        "returned more than",
554        "response size",
555        "result set",
556        "too many results",
557        "too many blocks",
558        "maximum block range",
559        "max block range",
560    ];
561    RANGE_LIMIT_HINTS.iter().any(|hint| message.contains(hint))
562}
563
564#[cfg(test)]
565mod tests {
566    use super::*;
567    use alloy_dyn_abi::DynSolValue;
568    use alloy_primitives::{Log as PrimitiveLog, U256, keccak256};
569
570    fn rpc_log(topics: Vec<B256>, data: Vec<u8>) -> Log {
571        Log {
572            inner: PrimitiveLog::new_unchecked(Address::ZERO, topics, data.into()),
573            ..Default::default()
574        }
575    }
576
577    #[test]
578    fn format_log_params_respects_signature_indexed_flags() {
579        let event = Event::parse("event Ev(bytes32 indexed a, address b)").unwrap();
580        let a = B256::repeat_byte(0x11);
581        let b = Address::repeat_byte(0x22);
582        let log = rpc_log(vec![event.selector(), a], DynSolValue::Address(b).abi_encode());
583
584        let params = format_log_params(&event, &log).unwrap();
585        assert_eq!(params, format!("\ndecoded:\n\ta: {a}\n\tb: {b}"));
586    }
587
588    #[test]
589    fn format_log_params_requires_explicit_indexed_flags() {
590        let event = Event::parse("event Ev(uint256 id, address owner)").unwrap();
591        let owner = Address::repeat_byte(0x22);
592        let log = rpc_log(
593            vec![event.selector(), B256::with_last_byte(7)],
594            DynSolValue::Address(owner).abi_encode(),
595        );
596
597        assert_eq!(format_log_params(&event, &log), None);
598    }
599
600    #[test]
601    fn format_log_params_preserves_declaration_order() {
602        let event =
603            Event::parse("event Ev(uint256 a, bytes32 indexed b, address c, bytes32 indexed d)")
604                .unwrap();
605        let b = B256::repeat_byte(0x11);
606        let c = Address::repeat_byte(0x22);
607        let d = B256::repeat_byte(0x33);
608        let data = DynSolValue::Tuple(vec![
609            DynSolValue::Uint(U256::from(7), 256),
610            DynSolValue::Address(c),
611        ])
612        .abi_encode_params();
613        let log = rpc_log(vec![event.selector(), b, d], data);
614
615        let params = format_log_params(&event, &log).unwrap();
616        assert_eq!(params, format!("\ndecoded:\n\ta: 7\n\tb: {b}\n\tc: {c}\n\td: {d}"));
617    }
618
619    #[test]
620    fn format_log_params_decodes_anonymous_event() {
621        let event = Event::parse("event Ev(bytes32 indexed key, uint256 value) anonymous").unwrap();
622        let key = B256::repeat_byte(0x44);
623        let log = rpc_log(vec![key], DynSolValue::Uint(U256::from(9), 256).abi_encode());
624
625        let params = format_log_params(&event, &log).unwrap();
626        assert_eq!(params, format!("\ndecoded:\n\tkey: {key}\n\tvalue: 9"));
627    }
628
629    #[test]
630    fn format_log_params_displays_dynamic_indexed_hash() {
631        let event = Event::parse("event Ev(string indexed key, uint256 value)").unwrap();
632        let key = keccak256("hello");
633        let log = rpc_log(
634            vec![event.selector(), key],
635            DynSolValue::Uint(U256::from(9), 256).abi_encode(),
636        );
637
638        let params = format_log_params(&event, &log).unwrap();
639        assert_eq!(params, format!("\ndecoded:\n\tkey: {key}\n\tvalue: 9"));
640    }
641
642    #[test]
643    fn format_log_params_mismatching_log() {
644        let event = Event::parse("event Ev(uint256 indexed a, uint256 b)").unwrap();
645        let log = rpc_log(vec![event.selector()], DynSolValue::Uint(U256::ONE, 256).abi_encode());
646        assert_eq!(format_log_params(&event, &log), None);
647    }
648
649    const ADDRESS: &str = "0x4D1A2e2bB4F88F0250f26Ffff098B0b30B26BF38";
650    const OTHER_ADDRESS: &str = "0x000000000000000000000000000000000000dead";
651    const TRANSFER_SIG: &str = "Transfer(address indexed,address indexed,uint256)";
652    const TRANSFER_TOPIC: &str =
653        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
654
655    fn filter(sig_or_topic: &str, args: &[&str]) -> Result<Filter> {
656        build_filter(
657            None,
658            None,
659            None,
660            Some(sig_or_topic.to_string()),
661            args.iter().map(|s| s.to_string()).collect(),
662        )
663        .map(|(filter, _)| filter)
664    }
665
666    fn topics(topics: [Topic; 4]) -> Filter {
667        Filter { topics, ..Default::default() }
668    }
669
670    #[test]
671    fn builds_filters() {
672        let transfer_topic = B256::from_str(TRANSFER_TOPIC).unwrap();
673        let addr: Address = ADDRESS.parse().unwrap();
674        let other_addr: Address = OTHER_ADDRESS.parse().unwrap();
675        let addr_topic = Topic::from(addr);
676        let any = Topic::default;
677
678        let from_block = Some(BlockNumberOrTag::from(1337));
679        let to_block = Some(BlockNumberOrTag::Latest);
680        let (basic, _) =
681            build_filter(from_block, to_block, Some(vec![addr]), None, vec![]).unwrap();
682        assert_eq!(
683            basic,
684            Filter {
685                block_option: FilterBlockOption::Range { from_block, to_block },
686                address: addr.into(),
687                topics: Default::default(),
688            }
689        );
690
691        let cases: [(&str, &[&str], [Topic; 4]); 10] = [
692            (TRANSFER_SIG, &[], [transfer_topic.into(), any(), any(), any()]),
693            (TRANSFER_SIG, &[ADDRESS], [transfer_topic.into(), addr_topic.clone(), any(), any()]),
694            (TRANSFER_SIG, &["", ADDRESS], [transfer_topic.into(), any(), addr_topic, any()]),
695            (
696                TRANSFER_TOPIC,
697                &[TRANSFER_TOPIC],
698                [transfer_topic.into(), transfer_topic.into(), any(), any()],
699            ),
700            (
701                TRANSFER_TOPIC,
702                &["", TRANSFER_TOPIC],
703                [transfer_topic.into(), any(), transfer_topic.into(), any()],
704            ),
705            (
706                "event Owned(uint256 value, address indexed owner)",
707                &[ADDRESS],
708                [
709                    Event::parse("event Owned(uint256 value, address indexed owner)")
710                        .unwrap()
711                        .selector()
712                        .into(),
713                    addr.into(),
714                    any(),
715                    any(),
716                ],
717            ),
718            (
719                "event Message(string indexed value)",
720                &["hello"],
721                [
722                    Event::parse("event Message(string indexed value)").unwrap().selector().into(),
723                    keccak256("hello").into(),
724                    any(),
725                    any(),
726                ],
727            ),
728            (
729                "Swap(address indexed from, address indexed to, uint256 value)",
730                &[],
731                [
732                    Event::parse(
733                        "event Swap(address indexed from, address indexed to, uint256 value)",
734                    )
735                    .unwrap()
736                    .selector()
737                    .into(),
738                    any(),
739                    any(),
740                    any(),
741                ],
742            ),
743            (
744                "event Anon(address indexed a, uint256 indexed b, uint256 c, address indexed d) anonymous",
745                &[ADDRESS, "7", ""],
746                [addr.into(), B256::with_last_byte(7).into(), any(), any()],
747            ),
748            (
749                "event Anon(address indexed a, uint256 indexed b, uint256 indexed c, address indexed d) anonymous",
750                &[ADDRESS, "7", "", OTHER_ADDRESS],
751                [addr.into(), B256::with_last_byte(7).into(), any(), other_addr.into()],
752            ),
753        ];
754        for (sig_or_topic, args, expected) in cases {
755            assert_eq!(filter(sig_or_topic, args).unwrap(), topics(expected), "{sig_or_topic}");
756        }
757
758        let too_many = filter(
759            "event Wide(address indexed a, uint256 indexed b, uint256 indexed c, uint256 indexed d)",
760            &[],
761        )
762        .unwrap_err();
763        assert!(too_many.to_string().contains("too many indexed inputs"), "{too_many}");
764
765        let (multiple, _) = build_filter(
766            None,
767            None,
768            Some(vec![Address::ZERO, addr]),
769            Some(TRANSFER_TOPIC.to_string()),
770            vec![],
771        )
772        .unwrap();
773        assert_eq!(
774            multiple,
775            Filter {
776                address: vec![Address::ZERO, addr].into(),
777                topics: [transfer_topic.into(), any(), any(), any()],
778                ..Default::default()
779            }
780        );
781    }
782
783    #[test]
784    fn rejects_excess_event_filter_arguments() {
785        // `Transfer` only indexes `from` and `to`; a third argument cannot be expressed as a topic
786        // and would otherwise be dropped without a word, running the query with fewer conditions
787        // than the user asked for.
788        let err = filter(TRANSFER_SIG, &[ADDRESS, OTHER_ADDRESS, "1234"]).unwrap_err();
789        assert!(err.to_string().contains("2 indexed parameters, but 3 filter arguments"), "{err}");
790    }
791
792    #[test]
793    fn rejects_more_than_four_raw_topics() {
794        // A log carries at most 4 topics; the fifth one would otherwise be truncated.
795        let err = filter(
796            TRANSFER_TOPIC,
797            &[TRANSFER_TOPIC, TRANSFER_TOPIC, TRANSFER_TOPIC, TRANSFER_TOPIC],
798        )
799        .unwrap_err();
800        assert!(err.to_string().contains("at most 4 topics"), "{err}");
801    }
802
803    #[test]
804    fn rejects_invalid_arguments_and_topics() {
805        let cases = [
806            (TRANSFER_SIG, &["1234"][..], "parser error:\n1234\n^\ninvalid string length"),
807            ("asdasdasd", &[], "odd number of digits"),
808            (ADDRESS, &[], "invalid string length"),
809            (TRANSFER_TOPIC, &["1234"], "invalid string length"),
810        ];
811        for (sig_or_topic, args, expected) in cases {
812            let err = filter(sig_or_topic, args).unwrap_err().to_string().to_lowercase();
813            assert_eq!(err, expected, "{sig_or_topic}");
814        }
815    }
816}
817
818#[cfg(test)]
819mod logs_bisecting {
820    use super::*;
821    use alloy_json_rpc::{RequestPacket, ResponsePacket, SerializedRequest};
822    use alloy_provider::ProviderBuilder;
823    use alloy_rpc_client::RpcClient;
824    use alloy_transport::{
825        TransportError, TransportFut,
826        mock::{Asserter, MockTransport},
827    };
828    use std::{
829        sync::{Arc, Mutex},
830        task::{Context, Poll},
831    };
832    use tower::Service;
833
834    fn log_at(block: u64) -> Log {
835        Log { block_number: Some(block), ..Default::default() }
836    }
837
838    /// Streams `logs` up to `to_block` while the block subscription stays silent.
839    async fn streamed(logs: Vec<Log>, to_block: u64) -> String {
840        let mut output = Vec::new();
841        let blocks = futures::stream::pending::<alloy_rpc_types::Header>();
842        stream_logs(
843            &mut output,
844            futures::stream::iter(logs),
845            Some(blocks),
846            Some(to_block),
847            None,
848            futures::future::pending::<()>(),
849        )
850        .await
851        .unwrap();
852        String::from_utf8(output).unwrap()
853    }
854
855    // An ended block subscription must not be polled again, or the loop spins until the next log.
856    #[tokio::test]
857    async fn ended_block_subscription_is_not_polled_again() {
858        let polls = Arc::new(Mutex::new(0usize));
859        let blocks = futures::stream::poll_fn({
860            let polls = polls.clone();
861            move |_| {
862                let mut polls = polls.lock().unwrap();
863                *polls += 1;
864                assert!(*polls < 1000, "the ended block subscription keeps being polled");
865                Poll::<Option<alloy_rpc_types::Header>>::Ready(None)
866            }
867        });
868        let logs = futures::stream::once(async {
869            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
870            log_at(1)
871        });
872        let mut output = Vec::new();
873        stream_logs(
874            &mut output,
875            logs.boxed(),
876            Some(blocks),
877            Some(1),
878            None,
879            futures::future::pending::<()>(),
880        )
881        .await
882        .unwrap();
883        assert_eq!(String::from_utf8(output).unwrap(), format_log(&log_at(1), None).0 + "\n");
884        assert_eq!(*polls.lock().unwrap(), 1);
885    }
886
887    // Log subscriptions ignore the filter's block range, so a log can arrive before the block that
888    // passes `to_block` does.
889    #[tokio::test]
890    async fn subscription_stops_at_first_log_past_to_block() {
891        let expected = [5, 6].map(|block| format_log(&log_at(block), None).0 + "\n").concat();
892        assert_eq!(streamed(vec![log_at(5), log_at(6), log_at(7), log_at(6)], 6).await, expected);
893    }
894
895    /// Mock transport that records the `eth_getLogs` `[fromBlock, toBlock]` ranges it is asked for
896    /// while delegating the actual responses to a FIFO [`Asserter`].
897    #[derive(Clone)]
898    struct RecordingTransport {
899        inner: MockTransport,
900        ranges: Arc<Mutex<Vec<(String, String)>>>,
901    }
902
903    impl RecordingTransport {
904        fn new(asserter: Asserter) -> Self {
905            Self { inner: MockTransport::new(asserter), ranges: Arc::new(Mutex::new(Vec::new())) }
906        }
907
908        fn record(&self, req: &SerializedRequest) {
909            if req.method() != "eth_getLogs" {
910                return;
911            }
912            let Some(params) = req.params() else { return };
913            let Ok(value) = serde_json::from_str::<serde_json::Value>(params.get()) else { return };
914            let Some(filter) = value.get(0) else { return };
915            let field =
916                |name| filter.get(name).and_then(|v| v.as_str()).unwrap_or_default().to_string();
917            self.ranges.lock().unwrap().push((field("fromBlock"), field("toBlock")));
918        }
919    }
920
921    impl Service<RequestPacket> for RecordingTransport {
922        type Response = ResponsePacket;
923        type Error = TransportError;
924        type Future = TransportFut<'static>;
925
926        fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
927            self.inner.poll_ready(cx)
928        }
929
930        fn call(&mut self, req: RequestPacket) -> Self::Future {
931            match &req {
932                RequestPacket::Single(req) => self.record(req),
933                RequestPacket::Batch(reqs) => reqs.iter().for_each(|req| self.record(req)),
934            }
935            self.inner.call(req)
936        }
937    }
938
939    // A range-limit failure splits depth-first into [0,1]/[2,3] and aggregates in range order.
940    #[tokio::test]
941    async fn bisects_failed_range_and_aggregates_in_order() {
942        let asserter = Asserter::new();
943        asserter.push_failure_msg("query returned more than 10000 results");
944        asserter.push_success(&vec![log_at(0)]);
945        asserter.push_success(&vec![log_at(2)]);
946
947        let transport = RecordingTransport::new(asserter);
948        let ranges = transport.ranges.clone();
949        let provider = ProviderBuilder::<_, _, AnyNetwork>::default()
950            .connect_client(RpcClient::new(transport, true));
951
952        let logs = get_logs_bisecting(&provider, &Filter::new(), 0, 3).await.unwrap();
953        let blocks: Vec<_> = logs.iter().map(|l| l.block_number).collect();
954        assert_eq!(blocks, vec![Some(0), Some(2)]);
955
956        // The original range fails, then bisection requests exactly the two halves in order.
957        let ranges = ranges.lock().unwrap();
958        assert_eq!(
959            *ranges,
960            vec![
961                ("0x0".to_string(), "0x3".to_string()),
962                ("0x0".to_string(), "0x1".to_string()),
963                ("0x2".to_string(), "0x3".to_string()),
964            ]
965        );
966    }
967
968    // A single-block failure can't be split, so the error is surfaced.
969    #[tokio::test]
970    async fn surfaces_single_block_failure() {
971        let asserter = Asserter::new();
972        asserter.push_failure_msg("query returned more than 10000 results");
973
974        let provider =
975            ProviderBuilder::<_, _, AnyNetwork>::default().connect_mocked_client(asserter);
976
977        let err = get_logs_bisecting(&provider, &Filter::new(), 5, 5).await.unwrap_err();
978        assert!(err.to_string().contains("more than 10000 results"), "got: {err}");
979    }
980
981    // A non-range error fails after one request instead of bisecting.
982    #[tokio::test]
983    async fn does_not_bisect_non_range_errors() {
984        let asserter = Asserter::new();
985        asserter.push_failure_msg("unauthorized: invalid api key");
986
987        let provider =
988            ProviderBuilder::<_, _, AnyNetwork>::default().connect_mocked_client(asserter);
989
990        let err = get_logs_bisecting(&provider, &Filter::new(), 0, 3).await.unwrap_err();
991        assert!(err.to_string().contains("unauthorized"), "got: {err}");
992    }
993}