soroban_cli/commands/
events.rs

1use clap::{arg, command, Parser};
2use std::io;
3
4use crate::xdr::{self, Limits, ReadXdr};
5
6use super::{global, NetworkRunnable};
7use crate::{
8    config::{self, locator, network},
9    rpc,
10};
11
12#[derive(Parser, Debug, Clone)]
13#[group(skip)]
14pub struct Cmd {
15    #[allow(clippy::doc_markdown)]
16    /// The first ledger sequence number in the range to pull events
17    /// https://developers.stellar.org/docs/learn/encyclopedia/network-configuration/ledger-headers#ledger-sequence
18    #[arg(long, conflicts_with = "cursor", required_unless_present = "cursor")]
19    start_ledger: Option<u32>,
20    /// The cursor corresponding to the start of the event range.
21    #[arg(
22        long,
23        conflicts_with = "start_ledger",
24        required_unless_present = "start_ledger"
25    )]
26    cursor: Option<String>,
27    /// Output formatting options for event stream
28    #[arg(long, value_enum, default_value = "pretty")]
29    output: OutputFormat,
30    /// The maximum number of events to display (defer to the server-defined limit).
31    #[arg(short, long, default_value = "10")]
32    count: usize,
33    /// A set of (up to 5) contract IDs to filter events on. This parameter can
34    /// be passed multiple times, e.g. `--id C123.. --id C456..`, or passed with
35    /// multiple parameters, e.g. `--id C123 C456`.
36    ///
37    /// Though the specification supports multiple filter objects (i.e.
38    /// combinations of type, IDs, and topics), only one set can be specified on
39    /// the command-line today, though that set can have multiple IDs/topics.
40    #[arg(
41        long = "id",
42        num_args = 1..=6,
43        help_heading = "FILTERS"
44    )]
45    contract_ids: Vec<config::UnresolvedContract>,
46    /// A set of (up to 4) topic filters to filter event topics on. A single
47    /// topic filter can contain 1-4 different segment filters, separated by
48    /// commas, with an asterisk (`*` character) indicating a wildcard segment.
49    ///
50    /// **Example:** topic filter with two segments: `--topic "AAAABQAAAAdDT1VOVEVSAA==,*"`
51    ///
52    /// **Example:** two topic filters with one and two segments each: `--topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'`
53    ///
54    /// Note that all of these topic filters are combined with the contract IDs
55    /// into a single filter (i.e. combination of type, IDs, and topics).
56    #[arg(
57        long = "topic",
58        num_args = 1..=5,
59        help_heading = "FILTERS"
60    )]
61    topic_filters: Vec<String>,
62    /// Specifies which type of contract events to display.
63    #[arg(
64        long = "type",
65        value_enum,
66        default_value = "all",
67        help_heading = "FILTERS"
68    )]
69    event_type: rpc::EventType,
70    #[command(flatten)]
71    locator: locator::Args,
72    #[command(flatten)]
73    network: network::Args,
74}
75
76#[derive(thiserror::Error, Debug)]
77pub enum Error {
78    #[error("cursor is not valid")]
79    InvalidCursor,
80    #[error("filepath does not exist: {path}")]
81    InvalidFile { path: String },
82    #[error("filepath ({path}) cannot be read: {error}")]
83    CannotReadFile { path: String, error: String },
84    #[error("cannot parse topic filter {topic} into 1-4 segments")]
85    InvalidTopicFilter { topic: String },
86    #[error("invalid segment ({segment}) in topic filter ({topic}): {error}")]
87    InvalidSegment {
88        topic: String,
89        segment: String,
90        error: xdr::Error,
91    },
92    #[error("cannot parse contract ID {contract_id}: {error}")]
93    InvalidContractId {
94        contract_id: String,
95        error: stellar_strkey::DecodeError,
96    },
97    #[error("invalid JSON string: {error} ({debug})")]
98    InvalidJson {
99        debug: String,
100        error: serde_json::Error,
101    },
102    #[error("invalid timestamp in event: {ts}")]
103    InvalidTimestamp { ts: String },
104    #[error("missing start_ledger and cursor")]
105    MissingStartLedgerAndCursor,
106    #[error("missing target")]
107    MissingTarget,
108    #[error(transparent)]
109    Rpc(#[from] rpc::Error),
110    #[error(transparent)]
111    Generic(#[from] Box<dyn std::error::Error>),
112    #[error(transparent)]
113    Io(#[from] io::Error),
114    #[error(transparent)]
115    Xdr(#[from] xdr::Error),
116    #[error(transparent)]
117    Serde(#[from] serde_json::Error),
118    #[error(transparent)]
119    Network(#[from] network::Error),
120    #[error(transparent)]
121    Locator(#[from] locator::Error),
122    #[error(transparent)]
123    Config(#[from] config::Error),
124}
125
126#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, clap::ValueEnum)]
127pub enum OutputFormat {
128    /// Colorful, human-oriented console output
129    Pretty,
130    /// Human-oriented console output without colors
131    Plain,
132    /// JSON formatted console output
133    Json,
134}
135
136impl Cmd {
137    pub async fn run(&mut self) -> Result<(), Error> {
138        // Validate that topics are made up of segments.
139        for topic in &self.topic_filters {
140            for (i, segment) in topic.split(',').enumerate() {
141                if i > 4 {
142                    return Err(Error::InvalidTopicFilter {
143                        topic: topic.to_string(),
144                    });
145                }
146
147                if segment != "*" {
148                    if let Err(e) = xdr::ScVal::from_xdr_base64(segment, Limits::none()) {
149                        return Err(Error::InvalidSegment {
150                            topic: topic.to_string(),
151                            segment: segment.to_string(),
152                            error: e,
153                        });
154                    }
155                }
156            }
157        }
158
159        let response = self.run_against_rpc_server(None, None).await?;
160
161        for event in &response.events {
162            match self.output {
163                // Should we pretty-print the JSON like we're doing here or just
164                // dump an event in raw JSON on each line? The latter is easier
165                // to consume programmatically.
166                OutputFormat::Json => {
167                    println!(
168                        "{}",
169                        serde_json::to_string_pretty(&event).map_err(|e| {
170                            Error::InvalidJson {
171                                debug: format!("{event:#?}"),
172                                error: e,
173                            }
174                        })?,
175                    );
176                }
177                OutputFormat::Plain => println!("{event}"),
178                OutputFormat::Pretty => event.pretty_print()?,
179            }
180        }
181        Ok(())
182    }
183
184    fn start(&self) -> Result<rpc::EventStart, Error> {
185        let start = match (self.start_ledger, self.cursor.clone()) {
186            (Some(start), _) => rpc::EventStart::Ledger(start),
187            (_, Some(c)) => rpc::EventStart::Cursor(c),
188            // should never happen because of required_unless_present flags
189            _ => return Err(Error::MissingStartLedgerAndCursor),
190        };
191        Ok(start)
192    }
193}
194
195#[async_trait::async_trait]
196impl NetworkRunnable for Cmd {
197    type Error = Error;
198    type Result = rpc::GetEventsResponse;
199
200    async fn run_against_rpc_server(
201        &self,
202        _args: Option<&global::Args>,
203        config: Option<&config::Args>,
204    ) -> Result<rpc::GetEventsResponse, Error> {
205        let start = self.start()?;
206        let network = if let Some(config) = config {
207            Ok(config.get_network()?)
208        } else {
209            self.network.get(&self.locator)
210        }?;
211
212        let client = network.rpc_client()?;
213        client
214            .verify_network_passphrase(Some(&network.network_passphrase))
215            .await?;
216
217        let contract_ids: Vec<String> = self
218            .contract_ids
219            .iter()
220            .map(|id| {
221                Ok(id
222                    .resolve_contract_id(&self.locator, &network.network_passphrase)?
223                    .to_string())
224            })
225            .collect::<Result<Vec<_>, Error>>()?;
226
227        Ok(client
228            .get_events(
229                start,
230                Some(self.event_type),
231                &contract_ids,
232                &self.topic_filters,
233                Some(self.count),
234            )
235            .await
236            .map_err(Error::Rpc)?)
237    }
238}
soroban_cli/commands/events.rs

soroban_cli/commands/
events.rs
