hdp_cli/commands.rs
1use alloy::{
2 primitives::{BlockNumber, ChainId, TxIndex},
3 transports::http::reqwest::Url,
4};
5use clap::{command, Parser, Subcommand};
6use hdp::primitives::{
7 aggregate_fn::{AggregationFunction, FunctionContext},
8 task::datalake::{
9 block_sampled::BlockSampledCollection,
10 transactions::{IncludedTypes, TransactionsCollection},
11 },
12};
13use std::path::PathBuf;
14
15#[derive(Debug, Parser)]
16#[command(name = "hdp")]
17#[command(version, about, long_about = None)]
18pub struct HDPCli {
19 #[command(subcommand)]
20 pub command: HDPCliCommands,
21}
22
23#[derive(Debug, Subcommand)]
24pub enum HDPCliCommands {
25 /// New to the HDP CLI? Start here!
26 Start,
27 /// Run single datalake compute
28 #[command(arg_required_else_help = true)]
29 RunDatalake {
30 /// The aggregate function id e.g. "sum", "min", "avg"
31 aggregate_fn_id: AggregationFunction,
32 /// Optional context for applying conditions on the aggregate function "count".
33 /// Format: "{operator}.{value}" (e.g., "eq.100" for equality, "gt.100" for greater-than).
34 /// Supported operators are in the [`Operator`] enum.
35 aggregate_fn_ctx: Option<FunctionContext>,
36
37 #[command(subcommand)]
38 datalake: DataLakeCommands,
39
40 /// The RPC URL to fetch the datalake
41 rpc_url: Option<Url>,
42
43 /// The chain id to fetch the datalake
44 chain_id: Option<ChainId>,
45
46 /// Path to save output file after pre-processing.
47 ///
48 /// This will trigger pre-processing step
49 #[arg(short, long)]
50 preprocessor_output_file: Option<PathBuf>,
51
52 /// hdp cairo compiled program. main entry point
53 #[arg(long)]
54 sound_run_cairo_file: Option<PathBuf>,
55
56 /// Path to save output file after process
57 ///
58 /// This will trigger processing(=pie generation) step
59 #[arg(short, long, requires("preprocessor_output_file"))]
60 output_file: Option<PathBuf>,
61
62 /// Path to save pie file
63 ///
64 /// This will trigger processing(=pie generation) step
65 #[arg(short, long, requires("preprocessor_output_file"))]
66 cairo_pie_file: Option<PathBuf>,
67 },
68
69 /// Run single module with either class hash deployed on starknet or local class path
70 #[command(arg_required_else_help = true)]
71 RunModule {
72 /// Input field elements for the module contract.
73 /// The input field elements should be separated by comma.
74 ///
75 /// e.g. "0x1234,0xabcd"
76 #[arg(long, required = true, use_value_delimiter = true)]
77 module_inputs: Vec<String>,
78
79 #[arg(long, group = "class_source")]
80 program_hash: Option<String>,
81
82 /// Local path of the contract class file.
83 /// Make sure to have structure match with [CasmContractClass](https://github.com/starkware-libs/cairo/blob/53f7a0d26d5c8a99a8ad6ba07207a762678f2931/crates/cairo-lang-starknet-classes/src/casm_contract_class.rs)
84 ///
85 /// (Note: either class_hash or local_class_path should be provided)
86 #[arg(long, group = "class_source")]
87 local_class_path: Option<PathBuf>,
88
89 /// optionally can save keys for module task to file
90 #[arg(long)]
91 save_fetch_keys_file: Option<PathBuf>,
92
93 /// The RPC URL to fetch the data.
94 ///
95 /// Can be overwritten by `RPC_URL` environment variable.
96 #[arg(long)]
97 rpc_url: Option<Url>,
98
99 /// The chain id to fetch the data.
100 ///
101 /// Can be overwritten by `CHAIN_ID` environment variable
102 #[arg(long)]
103 chain_id: Option<ChainId>,
104
105 /// dry run contract bootloader program.
106 /// only used for module task
107 #[arg(long)]
108 dry_run_cairo_file: Option<PathBuf>,
109
110 /// Path to save output file after pre-processing.
111 ///
112 /// This will trigger pre-processing step
113 #[arg(short, long)]
114 preprocessor_output_file: Option<PathBuf>,
115
116 /// hdp cairo compiled program. main entry point
117 #[arg(long)]
118 sound_run_cairo_file: Option<PathBuf>,
119
120 /// Path to save output file after process
121 ///
122 /// This will trigger processing(=pie generation) step
123 #[arg(short, long, requires("preprocessor_output_file"))]
124 output_file: Option<PathBuf>,
125
126 /// Path to save pie file
127 ///
128 /// This will trigger processing(=pie generation) step
129 #[arg(short, long, requires("preprocessor_output_file"))]
130 cairo_pie_file: Option<PathBuf>,
131 },
132 /// Run batch of tasks base on request json file
133 #[command(arg_required_else_help = true)]
134 Run {
135 /// Pass request as json file
136 #[arg(short, long)]
137 request_file: PathBuf,
138
139 /// The RPC URL to fetch the data.
140 ///
141 /// Can be overwritten by `RPC_URL` environment variable.
142 #[arg(long)]
143 rpc_url: Option<Url>,
144
145 /// dry run contract bootloader program.
146 /// only used for module task
147 #[arg(long)]
148 dry_run_cairo_file: Option<PathBuf>,
149
150 /// Path to save output file after pre-processing.
151 #[arg(short, long)]
152 preprocessor_output_file: PathBuf,
153
154 /// hdp cairo compiled program. main entry point
155 #[arg(long)]
156 sound_run_cairo_file: Option<PathBuf>,
157
158 /// Path to save output file after process
159 ///
160 /// This will trigger processing(=pie generation) step
161 #[arg(short, long, requires("preprocessor_output_file"))]
162 output_file: Option<PathBuf>,
163
164 /// Path to save pie file
165 ///
166 /// This will trigger processing(=pie generation) step
167 #[arg(short, long, requires("preprocessor_output_file"))]
168 cairo_pie_file: Option<PathBuf>,
169 },
170}
171
172#[derive(Subcommand, Clone, Debug, PartialEq, Eq)]
173pub enum DataLakeCommands {
174 #[command(arg_required_else_help = true)]
175 #[command(short_flag = 'b')]
176 BlockSampled {
177 /// Block number range start (inclusive)
178 block_range_start: BlockNumber,
179 /// Block number range end (inclusive)
180 block_range_end: BlockNumber,
181 /// Sampled property e.g. "header.number", "account.0xaccount.balance", "storage.0xcontract.0xstoragekey"
182 sampled_property: BlockSampledCollection,
183 /// Increment number of given range blocks
184 #[arg(default_value_t = 1)]
185 increment: u64,
186 },
187
188 #[command(arg_required_else_help = true)]
189 #[command(short_flag = 't')]
190 TransactionsInBlock {
191 /// Target block number
192 target_block: BlockNumber,
193 /// Sampled property
194 /// Fields from transaction: "chain_id", "gas_price"... etc
195 /// Fields from transaction receipt: "cumulative_gas_used".. etc
196 sampled_property: TransactionsCollection,
197 /// Start index of transactions range (inclusive)
198 start_index: TxIndex,
199 /// End index of transactions range (exclusive)
200 end_index: TxIndex,
201 /// Increment number of transaction indexes in the block
202 increment: u64,
203 /// Filter out the specific type of Txs
204 /// Each byte represents a type of transaction to be included in the datalake
205 /// e.g 1,0,1,0 -> include legacy, exclude eip2930, include eip1559, exclude eip4844
206 included_types: IncludedTypes,
207 },
208}