linera_service/cli/command.rs
1// Copyright (c) Zefchain Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use std::{borrow::Cow, num::NonZeroU16, path::PathBuf};
5
6use chrono::{DateTime, Utc};
7use linera_base::{
8 crypto::{AccountPublicKey, CryptoHash, ValidatorPublicKey},
9 data_types::{Amount, BlockHeight, Epoch},
10 identifiers::{Account, AccountOwner, ApplicationId, ChainId, ModuleId, StreamId},
11 time::Duration,
12 vm::VmRuntime,
13};
14use linera_client::{
15 chain_listener::ChainListenerConfig,
16 client_options::{
17 ApplicationPermissionsConfig, ChainOwnershipConfig, ResourceControlPolicyConfig,
18 },
19 util,
20};
21use linera_rpc::config::CrossChainConfig;
22
23use crate::{cli::validator, task_processor::parse_operator};
24
25const DEFAULT_TOKENS_PER_CHAIN: Amount = Amount::from_millis(100);
26const DEFAULT_TRANSACTIONS_PER_BLOCK: usize = 1;
27const DEFAULT_WRAP_UP_MAX_IN_FLIGHT: usize = 5;
28const DEFAULT_NUM_CHAINS: usize = 10;
29const DEFAULT_BPS: usize = 10;
30
31/// Specification for a validator to be added to the committee.
32#[derive(Clone, Debug)]
33pub struct ValidatorToAdd {
34 pub public_key: ValidatorPublicKey,
35 pub account_key: AccountPublicKey,
36 pub address: String,
37 pub votes: u64,
38}
39
40impl std::str::FromStr for ValidatorToAdd {
41 type Err = anyhow::Error;
42
43 fn from_str(s: &str) -> Result<Self, Self::Err> {
44 let parts: Vec<&str> = s.split(',').collect();
45 anyhow::ensure!(
46 parts.len() == 4,
47 "Validator spec must be in format: public_key,account_key,address,votes"
48 );
49
50 Ok(ValidatorToAdd {
51 public_key: parts[0].parse()?,
52 account_key: parts[1].parse()?,
53 address: parts[2].to_string(),
54 votes: parts[3].parse()?,
55 })
56 }
57}
58
59#[derive(Clone, clap::Args, serde::Serialize)]
60#[serde(rename_all = "kebab-case")]
61pub struct BenchmarkOptions {
62 /// How many chains to use.
63 #[arg(long, default_value_t = DEFAULT_NUM_CHAINS)]
64 pub num_chains: usize,
65
66 /// How many tokens to assign to each newly created chain.
67 /// These need to cover the transaction fees per chain for the benchmark.
68 #[arg(long, default_value_t = DEFAULT_TOKENS_PER_CHAIN)]
69 pub tokens_per_chain: Amount,
70
71 /// How many transactions to put in each block.
72 #[arg(long, default_value_t = DEFAULT_TRANSACTIONS_PER_BLOCK)]
73 pub transactions_per_block: usize,
74
75 /// The application ID of a fungible token on the wallet's default chain.
76 /// If none is specified, the benchmark uses the native token.
77 #[arg(long)]
78 pub fungible_application_id: Option<linera_base::identifiers::ApplicationId>,
79
80 /// The fixed BPS (Blocks Per Second) rate that block proposals will be sent at.
81 #[arg(long, default_value_t = DEFAULT_BPS)]
82 pub bps: usize,
83
84 /// If provided, will close the chains after the benchmark is finished. Keep in mind that
85 /// closing the chains might take a while, and will increase the validator latency while
86 /// they're being closed.
87 #[arg(long)]
88 pub close_chains: bool,
89
90 /// A comma-separated list of host:port pairs to query for health metrics.
91 /// If provided, the benchmark will check these endpoints for validator health
92 /// and terminate if any validator is unhealthy.
93 /// Example: "127.0.0.1:21100,validator-1.some-network.linera.net:21100"
94 #[arg(long)]
95 pub health_check_endpoints: Option<String>,
96
97 /// The maximum number of in-flight requests to validators when wrapping up the benchmark.
98 /// While wrapping up, this controls the concurrency level when processing inboxes and
99 /// closing chains.
100 #[arg(long, default_value_t = DEFAULT_WRAP_UP_MAX_IN_FLIGHT)]
101 pub wrap_up_max_in_flight: usize,
102
103 /// Confirm before starting the benchmark.
104 #[arg(long)]
105 pub confirm_before_start: bool,
106
107 /// How long to run the benchmark for. If not provided, the benchmark will run until
108 /// it is interrupted.
109 #[arg(long)]
110 pub runtime_in_seconds: Option<u64>,
111
112 /// The delay between chains, in milliseconds. For example, if set to 200ms, the first
113 /// chain will start, then the second will start 200 ms after the first one, the third
114 /// 200 ms after the second one, and so on.
115 /// This is used for slowly ramping up the TPS, so we don't pound the validators with the full
116 /// TPS all at once.
117 #[arg(long)]
118 pub delay_between_chains_ms: Option<u64>,
119
120 /// Path to YAML file containing chain IDs to send transfers to.
121 /// If not provided, only transfers between chains in the same wallet.
122 #[arg(long)]
123 pub config_path: Option<PathBuf>,
124
125 /// Transaction distribution mode. If false (default), distributes transactions evenly
126 /// across chains within each block. If true, sends all transactions in each block
127 /// to a single chain, rotating through chains for subsequent blocks.
128 #[arg(long)]
129 pub single_destination_per_block: bool,
130}
131
132impl Default for BenchmarkOptions {
133 fn default() -> Self {
134 Self {
135 num_chains: DEFAULT_NUM_CHAINS,
136 tokens_per_chain: DEFAULT_TOKENS_PER_CHAIN,
137 transactions_per_block: DEFAULT_TRANSACTIONS_PER_BLOCK,
138 wrap_up_max_in_flight: DEFAULT_WRAP_UP_MAX_IN_FLIGHT,
139 fungible_application_id: None,
140 bps: DEFAULT_BPS,
141 close_chains: false,
142 health_check_endpoints: None,
143 confirm_before_start: false,
144 runtime_in_seconds: None,
145 delay_between_chains_ms: None,
146 config_path: None,
147 single_destination_per_block: false,
148 }
149 }
150}
151
152#[derive(Clone, clap::Subcommand, serde::Serialize)]
153#[serde(rename_all = "kebab-case")]
154pub enum BenchmarkCommand {
155 /// Start a single benchmark process, maintaining a given TPS.
156 Single {
157 #[command(flatten)]
158 options: BenchmarkOptions,
159 },
160
161 /// Run multiple benchmark processes in parallel.
162 Multi {
163 #[command(flatten)]
164 options: BenchmarkOptions,
165
166 /// The number of benchmark processes to run in parallel.
167 #[arg(long, default_value = "1")]
168 processes: usize,
169
170 /// The faucet (which implicitly defines the network)
171 #[arg(long, env = "LINERA_FAUCET_URL")]
172 faucet: String,
173
174 /// If specified, a directory with a random name will be created in this directory, and the
175 /// client state will be stored there.
176 /// If not specified, a temporary directory will be used for each client.
177 #[arg(long)]
178 client_state_dir: Option<String>,
179
180 /// The delay between starting the benchmark processes, in seconds.
181 /// If --cross-wallet-transfers is true, this will be ignored.
182 #[arg(long, default_value = "10")]
183 delay_between_processes: u64,
184
185 /// Whether to send transfers between chains in different wallets.
186 #[arg(long)]
187 cross_wallet_transfers: bool,
188 },
189}
190
191impl BenchmarkCommand {
192 pub fn transactions_per_block(&self) -> usize {
193 match self {
194 Self::Single { options } => options.transactions_per_block,
195 Self::Multi { options, .. } => options.transactions_per_block,
196 }
197 }
198}
199
200#[cfg(feature = "kubernetes")]
201use crate::cli_wrappers::local_kubernetes_net::BuildMode;
202use crate::util::{
203 DEFAULT_PAUSE_AFTER_GQL_MUTATIONS_SECS, DEFAULT_PAUSE_AFTER_LINERA_SERVICE_SECS,
204};
205
206#[derive(Clone, clap::Subcommand)]
207pub enum ClientCommand {
208 /// Transfer funds
209 Transfer {
210 /// Sending chain ID (must be one of our chains)
211 #[arg(long = "from")]
212 sender: Account,
213
214 /// Recipient account
215 #[arg(long = "to")]
216 recipient: Account,
217
218 /// Amount to transfer
219 amount: Amount,
220 },
221
222 /// Open (i.e. activate) a new chain deriving the UID from an existing one.
223 OpenChain {
224 /// Chain ID (must be one of our chains).
225 #[arg(long = "from")]
226 chain_id: Option<ChainId>,
227
228 /// The new owner (otherwise create a key pair and remember it)
229 #[arg(long = "owner")]
230 owner: Option<AccountOwner>,
231
232 /// The initial balance of the new chain. This is subtracted from the parent chain's
233 /// balance.
234 #[arg(long = "initial-balance", default_value = "0")]
235 balance: Amount,
236
237 /// Whether to create a super owner for the new chain.
238 #[arg(long)]
239 super_owner: bool,
240 },
241
242 /// Open (i.e. activate) a new multi-owner chain deriving the UID from an existing one.
243 OpenMultiOwnerChain {
244 /// Chain ID (must be one of our chains).
245 #[arg(long = "from")]
246 chain_id: Option<ChainId>,
247
248 #[clap(flatten)]
249 ownership_config: ChainOwnershipConfig,
250
251 #[clap(flatten)]
252 application_permissions_config: ApplicationPermissionsConfig,
253
254 /// The initial balance of the new chain. This is subtracted from the parent chain's
255 /// balance.
256 #[arg(long = "initial-balance", default_value = "0")]
257 balance: Amount,
258 },
259
260 /// Display who owns the chain, and how the owners work together proposing blocks.
261 ShowOwnership {
262 /// The ID of the chain whose owners will be changed.
263 #[clap(long)]
264 chain_id: Option<ChainId>,
265 },
266
267 /// Change who owns the chain, and how the owners work together proposing blocks.
268 ///
269 /// Specify the complete set of new owners, by public key. Existing owners that are
270 /// not included will be removed.
271 ChangeOwnership {
272 /// The ID of the chain whose owners will be changed.
273 #[clap(long)]
274 chain_id: Option<ChainId>,
275
276 #[clap(flatten)]
277 ownership_config: ChainOwnershipConfig,
278 },
279
280 /// Change the preferred owner of a chain.
281 SetPreferredOwner {
282 /// The ID of the chain whose preferred owner will be changed.
283 #[clap(long)]
284 chain_id: Option<ChainId>,
285
286 /// The new preferred owner.
287 #[arg(long)]
288 owner: AccountOwner,
289 },
290
291 /// Changes the application permissions configuration.
292 ChangeApplicationPermissions {
293 /// The ID of the chain to which the new permissions will be applied.
294 #[arg(long)]
295 chain_id: Option<ChainId>,
296
297 #[clap(flatten)]
298 application_permissions_config: ApplicationPermissionsConfig,
299 },
300
301 /// Close an existing chain.
302 ///
303 /// A closed chain cannot execute operations or accept messages anymore.
304 /// It can still reject incoming messages, so they bounce back to the sender.
305 CloseChain {
306 /// Chain ID (must be one of our chains)
307 chain_id: ChainId,
308 },
309
310 /// Print out the network description.
311 ShowNetworkDescription,
312
313 /// Read the current native-token balance of the given account directly from the local
314 /// state.
315 ///
316 /// NOTE: The local balance does not reflect messages that are waiting to be picked in
317 /// the local inbox, or that have not been synchronized from validators yet. Use
318 /// `linera sync` then either `linera query-balance` or `linera process-inbox &&
319 /// linera local-balance` for a consolidated balance.
320 LocalBalance {
321 /// The account to read, written as `CHAIN-ID:OWNER` or simply `CHAIN-ID` for the
322 /// chain balance. By default, we read the chain balance of the default chain in
323 /// the wallet.
324 account: Option<Account>,
325 },
326
327 /// Simulate the execution of one block made of pending messages from the local inbox,
328 /// then read the native-token balance of the account from the local state.
329 ///
330 /// NOTE: The balance does not reflect messages that have not been synchronized from
331 /// validators yet. Call `linera sync` first to do so.
332 QueryBalance {
333 /// The account to query, written as `CHAIN-ID:OWNER` or simply `CHAIN-ID` for the
334 /// chain balance. By default, we read the chain balance of the default chain in
335 /// the wallet.
336 account: Option<Account>,
337 },
338
339 /// (DEPRECATED) Synchronize the local state of the chain with a quorum validators, then query the
340 /// local balance.
341 ///
342 /// This command is deprecated. Use `linera sync && linera query-balance` instead.
343 SyncBalance {
344 /// The account to query, written as `CHAIN-ID:OWNER` or simply `CHAIN-ID` for the
345 /// chain balance. By default, we read the chain balance of the default chain in
346 /// the wallet.
347 account: Option<Account>,
348 },
349
350 /// Synchronize the local state of the chain with a quorum validators.
351 Sync {
352 /// The chain to synchronize with validators. If omitted, synchronizes the
353 /// default chain of the wallet.
354 chain_id: Option<ChainId>,
355 },
356
357 /// Process all pending incoming messages from the inbox of the given chain by creating as many
358 /// blocks as needed to execute all (non-failing) messages. Failing messages will be
359 /// marked as rejected and may bounce to their sender depending on their configuration.
360 ProcessInbox {
361 /// The chain to process. If omitted, uses the default chain of the wallet.
362 chain_id: Option<ChainId>,
363 },
364
365 /// Query validators for shard information about a specific chain.
366 QueryShardInfo {
367 /// The chain to query shard information for.
368 chain_id: ChainId,
369 },
370
371 /// Deprecates all committees up to and including the specified one.
372 RevokeEpochs { epoch: Epoch },
373
374 /// View or update the resource control policy
375 ResourceControlPolicy {
376 /// Set the price per unit of Wasm fuel.
377 #[arg(long)]
378 wasm_fuel_unit: Option<Amount>,
379
380 /// Set the price per unit of EVM fuel.
381 #[arg(long)]
382 evm_fuel_unit: Option<Amount>,
383
384 /// Set the price per read operation.
385 #[arg(long)]
386 read_operation: Option<Amount>,
387
388 /// Set the price per write operation.
389 #[arg(long)]
390 write_operation: Option<Amount>,
391
392 /// Set the price per byte read from runtime.
393 #[arg(long)]
394 byte_runtime: Option<Amount>,
395
396 /// Set the price per byte read.
397 #[arg(long)]
398 byte_read: Option<Amount>,
399
400 /// Set the price per byte written.
401 #[arg(long)]
402 byte_written: Option<Amount>,
403
404 /// Set the base price to read a blob.
405 #[arg(long)]
406 blob_read: Option<Amount>,
407
408 /// Set the base price to publish a blob.
409 #[arg(long)]
410 blob_published: Option<Amount>,
411
412 /// Set the price to read a blob, per byte.
413 #[arg(long)]
414 blob_byte_read: Option<Amount>,
415
416 /// The price to publish a blob, per byte.
417 #[arg(long)]
418 blob_byte_published: Option<Amount>,
419
420 /// Set the price per byte stored.
421 #[arg(long)]
422 byte_stored: Option<Amount>,
423
424 /// Set the base price of sending an operation from a block..
425 #[arg(long)]
426 operation: Option<Amount>,
427
428 /// Set the additional price for each byte in the argument of a user operation.
429 #[arg(long)]
430 operation_byte: Option<Amount>,
431
432 /// Set the base price of sending a message from a block..
433 #[arg(long)]
434 message: Option<Amount>,
435
436 /// Set the additional price for each byte in the argument of a user message.
437 #[arg(long)]
438 message_byte: Option<Amount>,
439
440 /// Set the price per query to a service as an oracle.
441 #[arg(long)]
442 service_as_oracle_query: Option<Amount>,
443
444 /// Set the price for performing an HTTP request.
445 #[arg(long)]
446 http_request: Option<Amount>,
447
448 /// Set the maximum amount of Wasm fuel per block.
449 #[arg(long)]
450 maximum_wasm_fuel_per_block: Option<u64>,
451
452 /// Set the maximum amount of EVM fuel per block.
453 #[arg(long)]
454 maximum_evm_fuel_per_block: Option<u64>,
455
456 /// Set the maximum time in milliseconds that a block can spend executing services as oracles.
457 #[arg(long)]
458 maximum_service_oracle_execution_ms: Option<u64>,
459
460 /// Set the maximum size of a block, in bytes.
461 #[arg(long)]
462 maximum_block_size: Option<u64>,
463
464 /// Set the maximum size of data blobs, compressed bytecode and other binary blobs,
465 /// in bytes.
466 #[arg(long)]
467 maximum_blob_size: Option<u64>,
468
469 /// Set the maximum number of published blobs per block.
470 #[arg(long)]
471 maximum_published_blobs: Option<u64>,
472
473 /// Set the maximum size of decompressed contract or service bytecode, in bytes.
474 #[arg(long)]
475 maximum_bytecode_size: Option<u64>,
476
477 /// Set the maximum size of a block proposal, in bytes.
478 #[arg(long)]
479 maximum_block_proposal_size: Option<u64>,
480
481 /// Set the maximum read data per block.
482 #[arg(long)]
483 maximum_bytes_read_per_block: Option<u64>,
484
485 /// Set the maximum write data per block.
486 #[arg(long)]
487 maximum_bytes_written_per_block: Option<u64>,
488
489 /// Set the maximum size of oracle responses.
490 #[arg(long)]
491 maximum_oracle_response_bytes: Option<u64>,
492
493 /// Set the maximum size in bytes of a received HTTP response.
494 #[arg(long)]
495 maximum_http_response_bytes: Option<u64>,
496
497 /// Set the maximum amount of time allowed to wait for an HTTP response.
498 #[arg(long)]
499 http_request_timeout_ms: Option<u64>,
500
501 /// Set the list of hosts that contracts and services can send HTTP requests to.
502 #[arg(long)]
503 http_request_allow_list: Option<Vec<String>>,
504 },
505
506 /// Run benchmarks to test network performance.
507 #[command(subcommand)]
508 Benchmark(BenchmarkCommand),
509
510 /// Create genesis configuration for a Linera deployment.
511 /// Create initial user chains and print information to be used for initialization of validator setup.
512 /// This will also create an initial wallet for the owner of the initial "root" chains.
513 CreateGenesisConfig {
514 /// Sets the file describing the public configurations of all validators
515 #[arg(long = "committee")]
516 committee_config_path: PathBuf,
517
518 /// The output config path to be consumed by the server
519 #[arg(long = "genesis")]
520 genesis_config_path: PathBuf,
521
522 /// Known initial balance of the chain
523 #[arg(long, default_value = "0")]
524 initial_funding: Amount,
525
526 /// The start timestamp: no blocks can be created before this time.
527 #[arg(long)]
528 start_timestamp: Option<DateTime<Utc>>,
529
530 /// Number of initial (aka "root") chains to create in addition to the admin chain.
531 num_other_initial_chains: u32,
532
533 /// Configure the resource control policy (notably fees) according to pre-defined
534 /// settings.
535 #[arg(long, default_value = "no-fees")]
536 policy_config: ResourceControlPolicyConfig,
537
538 /// Set the price per unit of Wasm fuel.
539 /// (This will overwrite value from `--policy-config`)
540 #[arg(long)]
541 wasm_fuel_unit_price: Option<Amount>,
542
543 /// Set the price per unit of EVM fuel.
544 /// (This will overwrite value from `--policy-config`)
545 #[arg(long)]
546 evm_fuel_unit_price: Option<Amount>,
547
548 /// Set the price per read operation.
549 /// (This will overwrite value from `--policy-config`)
550 #[arg(long)]
551 read_operation_price: Option<Amount>,
552
553 /// Set the price per write operation.
554 /// (This will overwrite value from `--policy-config`)
555 #[arg(long)]
556 write_operation_price: Option<Amount>,
557
558 /// Set the price per byte read from runtime.
559 /// (This will overwrite value from `--policy-config`)
560 #[arg(long)]
561 byte_runtime_price: Option<Amount>,
562
563 /// Set the price per byte read.
564 /// (This will overwrite value from `--policy-config`)
565 #[arg(long)]
566 byte_read_price: Option<Amount>,
567
568 /// Set the price per byte written.
569 /// (This will overwrite value from `--policy-config`)
570 #[arg(long)]
571 byte_written_price: Option<Amount>,
572
573 /// Set the base price to read a blob.
574 /// (This will overwrite value from `--policy-config`)
575 #[arg(long)]
576 blob_read_price: Option<Amount>,
577
578 /// Set the base price to publish a blob.
579 /// (This will overwrite value from `--policy-config`)
580 #[arg(long)]
581 blob_published_price: Option<Amount>,
582
583 /// Set the price to read a blob, per byte.
584 /// (This will overwrite value from `--policy-config`)
585 #[arg(long)]
586 blob_byte_read_price: Option<Amount>,
587
588 /// Set the price to publish a blob, per byte.
589 /// (This will overwrite value from `--policy-config`)
590 #[arg(long)]
591 blob_byte_published_price: Option<Amount>,
592
593 /// Set the price per byte stored.
594 /// (This will overwrite value from `--policy-config`)
595 #[arg(long)]
596 byte_stored_price: Option<Amount>,
597
598 /// Set the base price of sending an operation from a block..
599 /// (This will overwrite value from `--policy-config`)
600 #[arg(long)]
601 operation_price: Option<Amount>,
602
603 /// Set the additional price for each byte in the argument of a user operation.
604 /// (This will overwrite value from `--policy-config`)
605 #[arg(long)]
606 operation_byte_price: Option<Amount>,
607
608 /// Set the base price of sending a message from a block..
609 /// (This will overwrite value from `--policy-config`)
610 #[arg(long)]
611 message_price: Option<Amount>,
612
613 /// Set the additional price for each byte in the argument of a user message.
614 /// (This will overwrite value from `--policy-config`)
615 #[arg(long)]
616 message_byte_price: Option<Amount>,
617
618 /// Set the price per query to a service as an oracle.
619 #[arg(long)]
620 service_as_oracle_query_price: Option<Amount>,
621
622 /// Set the price for performing an HTTP request.
623 #[arg(long)]
624 http_request_price: Option<Amount>,
625
626 /// Set the maximum amount of Wasm fuel per block.
627 /// (This will overwrite value from `--policy-config`)
628 #[arg(long)]
629 maximum_wasm_fuel_per_block: Option<u64>,
630
631 /// Set the maximum amount of EVM fuel per block.
632 /// (This will overwrite value from `--policy-config`)
633 #[arg(long)]
634 maximum_evm_fuel_per_block: Option<u64>,
635
636 /// Set the maximum time in milliseconds that a block can spend executing services as oracles.
637 #[arg(long)]
638 maximum_service_oracle_execution_ms: Option<u64>,
639
640 /// Set the maximum size of a block.
641 /// (This will overwrite value from `--policy-config`)
642 #[arg(long)]
643 maximum_block_size: Option<u64>,
644
645 /// Set the maximum size of decompressed contract or service bytecode, in bytes.
646 /// (This will overwrite value from `--policy-config`)
647 #[arg(long)]
648 maximum_bytecode_size: Option<u64>,
649
650 /// Set the maximum size of data blobs, compressed bytecode and other binary blobs,
651 /// in bytes.
652 /// (This will overwrite value from `--policy-config`)
653 #[arg(long)]
654 maximum_blob_size: Option<u64>,
655
656 /// Set the maximum number of published blobs per block.
657 /// (This will overwrite value from `--policy-config`)
658 #[arg(long)]
659 maximum_published_blobs: Option<u64>,
660
661 /// Set the maximum size of a block proposal, in bytes.
662 /// (This will overwrite value from `--policy-config`)
663 #[arg(long)]
664 maximum_block_proposal_size: Option<u64>,
665
666 /// Set the maximum read data per block.
667 /// (This will overwrite value from `--policy-config`)
668 #[arg(long)]
669 maximum_bytes_read_per_block: Option<u64>,
670
671 /// Set the maximum write data per block.
672 /// (This will overwrite value from `--policy-config`)
673 #[arg(long)]
674 maximum_bytes_written_per_block: Option<u64>,
675
676 /// Set the maximum size of oracle responses.
677 /// (This will overwrite value from `--policy-config`)
678 #[arg(long)]
679 maximum_oracle_response_bytes: Option<u64>,
680
681 /// Set the maximum size in bytes of a received HTTP response.
682 #[arg(long)]
683 maximum_http_response_bytes: Option<u64>,
684
685 /// Set the maximum amount of time allowed to wait for an HTTP response.
686 #[arg(long)]
687 http_request_timeout_ms: Option<u64>,
688
689 /// Set the list of hosts that contracts and services can send HTTP requests to.
690 #[arg(long)]
691 http_request_allow_list: Option<Vec<String>>,
692
693 /// Force this wallet to generate keys using a PRNG and a given seed. USE FOR
694 /// TESTING ONLY.
695 #[arg(long)]
696 testing_prng_seed: Option<u64>,
697
698 /// A unique name to identify this network.
699 #[arg(long)]
700 network_name: Option<String>,
701 },
702
703 /// Watch the network for notifications.
704 Watch {
705 /// The chain ID to watch.
706 chain_id: Option<ChainId>,
707
708 /// Show all notifications from all validators.
709 #[arg(long)]
710 raw: bool,
711 },
712
713 /// Run a GraphQL service to explore and extend the chains of the wallet.
714 Service {
715 #[command(flatten)]
716 config: ChainListenerConfig,
717
718 /// The port on which to run the server
719 #[arg(long)]
720 port: NonZeroU16,
721
722 /// The port to expose metrics on.
723 #[cfg(with_metrics)]
724 #[arg(long)]
725 metrics_port: NonZeroU16,
726
727 /// Application IDs of operator applications to watch.
728 /// When specified, a task processor is started alongside the node service.
729 #[arg(long = "operator-application-ids")]
730 operator_application_ids: Vec<ApplicationId>,
731
732 /// A controller to execute a dynamic set of applications running on a dynamic set of
733 /// chains.
734 #[arg(long = "controller-id")]
735 controller_application_id: Option<ApplicationId>,
736
737 /// Supported operators and their binary paths.
738 /// Format: `name=path` or just `name` (uses name as path).
739 /// Example: `--operators my-operator=/path/to/binary`
740 #[arg(long = "operators", value_parser = parse_operator)]
741 operators: Vec<(String, PathBuf)>,
742 },
743
744 /// Run a GraphQL service that exposes a faucet where users can claim tokens.
745 /// This gives away the chain's tokens, and is mainly intended for testing.
746 Faucet {
747 /// The chain that gives away its tokens.
748 chain_id: Option<ChainId>,
749
750 /// The port on which to run the server
751 #[arg(long, default_value = "8080")]
752 port: u16,
753
754 /// The port for prometheus to scrape.
755 #[cfg(with_metrics)]
756 #[arg(long, default_value = "9090")]
757 metrics_port: u16,
758
759 /// The number of tokens to send to each new chain.
760 #[arg(long)]
761 amount: Amount,
762
763 /// The end timestamp: The faucet will rate-limit the token supply so it runs out of money
764 /// no earlier than this.
765 #[arg(long)]
766 limit_rate_until: Option<DateTime<Utc>>,
767
768 /// Configuration for the faucet chain listener.
769 #[command(flatten)]
770 config: ChainListenerConfig,
771
772 /// Path to the persistent storage file for faucet mappings.
773 #[arg(long)]
774 storage_path: PathBuf,
775
776 /// Maximum number of operations to include in a single block (default: 100).
777 #[arg(long, default_value = "100")]
778 max_batch_size: usize,
779 },
780
781 /// Publish module.
782 PublishModule {
783 /// Path to the Wasm file for the application "contract" bytecode.
784 contract: PathBuf,
785
786 /// Path to the Wasm file for the application "service" bytecode.
787 service: PathBuf,
788
789 /// The virtual machine runtime to use.
790 #[arg(long, default_value = "wasm")]
791 vm_runtime: VmRuntime,
792
793 /// An optional chain ID to publish the module. The default chain of the wallet
794 /// is used otherwise.
795 publisher: Option<ChainId>,
796 },
797
798 /// Print events from a specific chain and stream from a specified index.
799 ListEventsFromIndex {
800 /// The chain to query. If omitted, query the default chain of the wallet.
801 chain_id: Option<ChainId>,
802
803 /// The stream being considered.
804 #[arg(long)]
805 stream_id: StreamId,
806
807 /// Index of the message to start with
808 #[arg(long, default_value = "0")]
809 start_index: u32,
810 },
811
812 /// Publish a data blob of binary data.
813 PublishDataBlob {
814 /// Path to data blob file to be published.
815 blob_path: PathBuf,
816 /// An optional chain ID to publish the blob. The default chain of the wallet
817 /// is used otherwise.
818 publisher: Option<ChainId>,
819 },
820
821 // TODO(#2490): Consider removing or renaming this.
822 /// Verify that a data blob is readable.
823 ReadDataBlob {
824 /// The hash of the content.
825 hash: CryptoHash,
826 /// An optional chain ID to verify the blob. The default chain of the wallet
827 /// is used otherwise.
828 reader: Option<ChainId>,
829 },
830
831 /// Create an application.
832 CreateApplication {
833 /// The module ID of the application to create.
834 module_id: ModuleId,
835
836 /// An optional chain ID to host the application. The default chain of the wallet
837 /// is used otherwise.
838 creator: Option<ChainId>,
839
840 /// The shared parameters as JSON string.
841 #[arg(long)]
842 json_parameters: Option<String>,
843
844 /// Path to a JSON file containing the shared parameters.
845 #[arg(long)]
846 json_parameters_path: Option<PathBuf>,
847
848 /// The instantiation argument as a JSON string.
849 #[arg(long)]
850 json_argument: Option<String>,
851
852 /// Path to a JSON file containing the instantiation argument.
853 #[arg(long)]
854 json_argument_path: Option<PathBuf>,
855
856 /// The list of required dependencies of application, if any.
857 #[arg(long, num_args(0..))]
858 required_application_ids: Option<Vec<ApplicationId>>,
859 },
860
861 /// Create an application, and publish the required module.
862 PublishAndCreate {
863 /// Path to the Wasm file for the application "contract" bytecode.
864 contract: PathBuf,
865
866 /// Path to the Wasm file for the application "service" bytecode.
867 service: PathBuf,
868
869 /// The virtual machine runtime to use.
870 #[arg(long, default_value = "wasm")]
871 vm_runtime: VmRuntime,
872
873 /// An optional chain ID to publish the module. The default chain of the wallet
874 /// is used otherwise.
875 publisher: Option<ChainId>,
876
877 /// The shared parameters as JSON string.
878 #[arg(long)]
879 json_parameters: Option<String>,
880
881 /// Path to a JSON file containing the shared parameters.
882 #[arg(long)]
883 json_parameters_path: Option<PathBuf>,
884
885 /// The instantiation argument as a JSON string.
886 #[arg(long)]
887 json_argument: Option<String>,
888
889 /// Path to a JSON file containing the instantiation argument.
890 #[arg(long)]
891 json_argument_path: Option<PathBuf>,
892
893 /// The list of required dependencies of application, if any.
894 #[arg(long, num_args(0..))]
895 required_application_ids: Option<Vec<ApplicationId>>,
896 },
897
898 /// Create an unassigned key pair.
899 Keygen,
900
901 /// Link the owner to the chain.
902 /// Expects that the caller has a private key corresponding to the `public_key`,
903 /// otherwise block proposals will fail when signing with it.
904 Assign {
905 /// The owner to assign.
906 #[arg(long)]
907 owner: AccountOwner,
908
909 /// The ID of the chain.
910 #[arg(long)]
911 chain_id: ChainId,
912 },
913
914 /// Retry a block we unsuccessfully tried to propose earlier.
915 ///
916 /// As long as a block is pending most other commands will fail, since it is unsafe to propose
917 /// multiple blocks at the same height.
918 RetryPendingBlock {
919 /// The chain with the pending block. If not specified, the wallet's default chain is used.
920 chain_id: Option<ChainId>,
921 },
922
923 /// Show the contents of the wallet.
924 #[command(subcommand)]
925 Wallet(WalletCommand),
926
927 /// Show the information about a chain.
928 #[command(subcommand)]
929 Chain(ChainCommand),
930
931 /// Manage Linera projects.
932 #[command(subcommand)]
933 Project(ProjectCommand),
934
935 /// Manage a local Linera Network.
936 #[command(subcommand)]
937 Net(NetCommand),
938
939 /// Manage validators in the committee.
940 #[command(subcommand)]
941 Validator(validator::Command),
942
943 /// Operation on the storage.
944 #[command(subcommand)]
945 Storage(DatabaseToolCommand),
946
947 /// Print CLI help in Markdown format, and exit.
948 #[command(hide = true)]
949 HelpMarkdown,
950
951 /// Extract a Bash and GraphQL script embedded in a markdown file and print it on
952 /// `stdout`.
953 #[command(hide = true)]
954 ExtractScriptFromMarkdown {
955 /// The source file
956 path: PathBuf,
957
958 /// Insert a pause of N seconds after calls to `linera service`.
959 #[arg(long, default_value = DEFAULT_PAUSE_AFTER_LINERA_SERVICE_SECS, value_parser = util::parse_secs)]
960 pause_after_linera_service: Duration,
961
962 /// Insert a pause of N seconds after GraphQL queries.
963 #[arg(long, default_value = DEFAULT_PAUSE_AFTER_GQL_MUTATIONS_SECS, value_parser = util::parse_secs)]
964 pause_after_gql_mutations: Duration,
965 },
966
967 /// Generate shell completion scripts
968 Completion {
969 /// The shell to generate completions for
970 #[arg(value_enum)]
971 shell: clap_complete::Shell,
972 },
973}
974
975impl ClientCommand {
976 /// Returns the log file name to use based on the [`ClientCommand`] that will run.
977 pub fn log_file_name(&self) -> Cow<'static, str> {
978 match self {
979 ClientCommand::Transfer { .. }
980 | ClientCommand::OpenChain { .. }
981 | ClientCommand::OpenMultiOwnerChain { .. }
982 | ClientCommand::ShowOwnership { .. }
983 | ClientCommand::ChangeOwnership { .. }
984 | ClientCommand::SetPreferredOwner { .. }
985 | ClientCommand::ChangeApplicationPermissions { .. }
986 | ClientCommand::CloseChain { .. }
987 | ClientCommand::ShowNetworkDescription
988 | ClientCommand::LocalBalance { .. }
989 | ClientCommand::QueryBalance { .. }
990 | ClientCommand::SyncBalance { .. }
991 | ClientCommand::Sync { .. }
992 | ClientCommand::ProcessInbox { .. }
993 | ClientCommand::QueryShardInfo { .. }
994 | ClientCommand::ResourceControlPolicy { .. }
995 | ClientCommand::RevokeEpochs { .. }
996 | ClientCommand::CreateGenesisConfig { .. }
997 | ClientCommand::PublishModule { .. }
998 | ClientCommand::ListEventsFromIndex { .. }
999 | ClientCommand::PublishDataBlob { .. }
1000 | ClientCommand::ReadDataBlob { .. }
1001 | ClientCommand::CreateApplication { .. }
1002 | ClientCommand::PublishAndCreate { .. }
1003 | ClientCommand::Keygen
1004 | ClientCommand::Assign { .. }
1005 | ClientCommand::Wallet { .. }
1006 | ClientCommand::Chain { .. }
1007 | ClientCommand::Validator { .. }
1008 | ClientCommand::RetryPendingBlock { .. } => "client".into(),
1009 ClientCommand::Benchmark(BenchmarkCommand::Single { .. }) => "single-benchmark".into(),
1010 ClientCommand::Benchmark(BenchmarkCommand::Multi { .. }) => "multi-benchmark".into(),
1011 ClientCommand::Net { .. } => "net".into(),
1012 ClientCommand::Project { .. } => "project".into(),
1013 ClientCommand::Watch { .. } => "watch".into(),
1014 ClientCommand::Storage { .. } => "storage".into(),
1015 ClientCommand::Service { port, .. } => format!("service-{port}").into(),
1016 ClientCommand::Faucet { .. } => "faucet".into(),
1017 ClientCommand::HelpMarkdown
1018 | ClientCommand::ExtractScriptFromMarkdown { .. }
1019 | ClientCommand::Completion { .. } => "tool".into(),
1020 }
1021 }
1022}
1023
1024#[derive(Clone, clap::Parser)]
1025pub enum DatabaseToolCommand {
1026 /// Delete all the namespaces in the database
1027 DeleteAll,
1028
1029 /// Delete a single namespace from the database
1030 DeleteNamespace,
1031
1032 /// Check existence of a namespace in the database
1033 CheckExistence,
1034
1035 /// Initialize a namespace in the database
1036 Initialize {
1037 #[arg(long = "genesis")]
1038 genesis_config_path: PathBuf,
1039 },
1040
1041 /// List the namespaces in the database
1042 ListNamespaces,
1043
1044 /// List the blob IDs in the database
1045 ListBlobIds,
1046
1047 /// List the chain IDs in the database
1048 ListChainIds,
1049
1050 /// List the event IDs in the database
1051 ListEventIds,
1052}
1053
1054#[allow(clippy::large_enum_variant)]
1055#[derive(Clone, clap::Parser)]
1056pub enum NetCommand {
1057 /// Start a Local Linera Network
1058 Up {
1059 /// The number of initial "root" chains created in the genesis config on top of
1060 /// the default "admin" chain. All initial chains belong to the first "admin"
1061 /// wallet. It is recommended to use at least one other initial chain for the
1062 /// faucet.
1063 #[arg(long, default_value = "2")]
1064 other_initial_chains: u32,
1065
1066 /// The initial amount of native tokens credited in the initial "root" chains,
1067 /// including the default "admin" chain.
1068 #[arg(long, default_value = "1000000")]
1069 initial_amount: u128,
1070
1071 /// The number of validators in the local test network.
1072 #[arg(long, default_value = "1")]
1073 validators: usize,
1074
1075 /// The number of proxies in the local test network.
1076 #[arg(long, default_value = "1")]
1077 proxies: usize,
1078
1079 /// The number of shards per validator in the local test network.
1080 #[arg(long, default_value = "1")]
1081 shards: usize,
1082
1083 /// Configure the resource control policy (notably fees) according to pre-defined
1084 /// settings.
1085 #[arg(long, default_value = "no-fees")]
1086 policy_config: ResourceControlPolicyConfig,
1087
1088 /// The configuration for cross-chain messages.
1089 #[clap(flatten)]
1090 cross_chain_config: CrossChainConfig,
1091
1092 /// Force this wallet to generate keys using a PRNG and a given seed. USE FOR
1093 /// TESTING ONLY.
1094 #[arg(long)]
1095 testing_prng_seed: Option<u64>,
1096
1097 /// Start the local network on a local Kubernetes deployment.
1098 #[cfg(feature = "kubernetes")]
1099 #[arg(long)]
1100 kubernetes: bool,
1101
1102 /// If this is not set, we'll build the binaries from within the Docker container
1103 /// If it's set, but with no directory path arg, we'll look for the binaries based on `current_binary_parent`
1104 /// If it's set, but with a directory path arg, we'll get the binaries from that path directory
1105 #[cfg(feature = "kubernetes")]
1106 #[arg(long, num_args=0..=1)]
1107 binaries: Option<Option<PathBuf>>,
1108
1109 /// Don't build docker image. This assumes that the image is already built.
1110 #[cfg(feature = "kubernetes")]
1111 #[arg(long, default_value = "false")]
1112 no_build: bool,
1113
1114 /// The name of the docker image to use.
1115 #[cfg(feature = "kubernetes")]
1116 #[arg(long, default_value = "linera:latest")]
1117 docker_image_name: String,
1118
1119 /// The build mode to use.
1120 #[cfg(feature = "kubernetes")]
1121 #[arg(long, default_value = "release")]
1122 build_mode: BuildMode,
1123
1124 /// Run with a specific path where the wallet and validator input files are.
1125 /// If none, then a temporary directory is created.
1126 #[arg(long)]
1127 path: Option<String>,
1128
1129 /// External protocol used, either `grpc` or `grpcs`.
1130 #[arg(long, default_value = "grpc")]
1131 external_protocol: String,
1132
1133 /// If present, a faucet is started using the chain provided by --faucet-chain, or
1134 /// the first non-admin chain if not provided.
1135 #[arg(long, default_value = "false")]
1136 with_faucet: bool,
1137
1138 /// When using --with-faucet, this specifies the chain on which the faucet will be started.
1139 /// If this is `n`, the `n`-th non-admin chain (lexicographically) in the wallet is selected.
1140 #[arg(long)]
1141 faucet_chain: Option<u32>,
1142
1143 /// The port on which to run the faucet server
1144 #[arg(long, default_value = "8080")]
1145 faucet_port: NonZeroU16,
1146
1147 /// The number of tokens to send to each new chain created by the faucet.
1148 #[arg(long, default_value = "1000")]
1149 faucet_amount: Amount,
1150
1151 /// Whether to start a block exporter for each validator.
1152 #[arg(long, default_value = "false")]
1153 with_block_exporter: bool,
1154
1155 /// The number of block exporters to start.
1156 #[arg(long, default_value = "1")]
1157 num_block_exporters: usize,
1158
1159 /// The address of the block exporter.
1160 #[arg(long, default_value = "localhost")]
1161 exporter_address: String,
1162
1163 /// The port on which to run the block exporter.
1164 #[arg(long, default_value = "8081")]
1165 exporter_port: NonZeroU16,
1166
1167 /// The name of the indexer docker image to use.
1168 #[cfg(feature = "kubernetes")]
1169 #[arg(long, default_value = "linera-indexer:latest")]
1170 indexer_image_name: String,
1171
1172 /// The name of the explorer docker image to use.
1173 #[cfg(feature = "kubernetes")]
1174 #[arg(long, default_value = "linera-explorer:latest")]
1175 explorer_image_name: String,
1176
1177 /// Use dual store (rocksdb and scylladb) instead of just scylladb. This is exclusive for
1178 /// kubernetes deployments.
1179 #[cfg(feature = "kubernetes")]
1180 #[arg(long, default_value = "false")]
1181 dual_store: bool,
1182 },
1183
1184 /// Print a bash helper script to make `linera net up` easier to use. The script is
1185 /// meant to be installed in `~/.bash_profile` or sourced when needed.
1186 Helper,
1187}
1188
1189#[derive(Clone, clap::Subcommand)]
1190pub enum WalletCommand {
1191 /// Show the contents of the wallet.
1192 Show {
1193 /// The chain to show the metadata.
1194 chain_id: Option<ChainId>,
1195 /// Only print a non-formatted list of the wallet's chain IDs.
1196 #[arg(long)]
1197 short: bool,
1198 /// Print only the chains that we have a key pair for.
1199 #[arg(long)]
1200 owned: bool,
1201 },
1202
1203 /// Change the wallet default chain.
1204 SetDefault { chain_id: ChainId },
1205
1206 /// Initialize a wallet from the genesis configuration.
1207 Init {
1208 /// The path to the genesis configuration for a Linera deployment. Either this or `--faucet`
1209 /// must be specified.
1210 ///
1211 /// Overrides `--faucet` if provided.
1212 #[arg(long = "genesis")]
1213 genesis_config_path: Option<PathBuf>,
1214
1215 /// The address of a faucet.
1216 #[arg(long, env = "LINERA_FAUCET_URL")]
1217 faucet: Option<String>,
1218
1219 /// Force this wallet to generate keys using a PRNG and a given seed. USE FOR
1220 /// TESTING ONLY.
1221 #[arg(long)]
1222 testing_prng_seed: Option<u64>,
1223 },
1224
1225 /// Request a new chain from a faucet and add it to the wallet.
1226 RequestChain {
1227 /// The address of a faucet.
1228 #[arg(long, env = "LINERA_FAUCET_URL")]
1229 faucet: String,
1230
1231 /// Whether this chain should become the default chain.
1232 #[arg(long)]
1233 set_default: bool,
1234 },
1235
1236 /// Add a new followed chain (i.e. a chain without keypair) to the wallet.
1237 FollowChain {
1238 /// The chain ID.
1239 chain_id: ChainId,
1240 /// Synchronize the new chain and download all its blocks from the validators.
1241 #[arg(long)]
1242 sync: bool,
1243 },
1244
1245 /// Forgets the specified chain's keys. The chain will still be followed by the
1246 /// wallet.
1247 ForgetKeys { chain_id: ChainId },
1248
1249 /// Forgets the specified chain, including the associated key pair.
1250 ForgetChain { chain_id: ChainId },
1251}
1252
1253#[derive(Clone, clap::Subcommand)]
1254pub enum ChainCommand {
1255 /// Show the contents of a block.
1256 ShowBlock {
1257 /// The height of the block.
1258 height: BlockHeight,
1259 /// The chain to show the block (if not specified, the default chain from the
1260 /// wallet is used).
1261 chain_id: Option<ChainId>,
1262 },
1263
1264 /// Show the chain description of a chain.
1265 ShowChainDescription {
1266 /// The chain ID to show (if not specified, the default chain from the wallet is
1267 /// used).
1268 chain_id: Option<ChainId>,
1269 },
1270}
1271
1272#[derive(Clone, clap::Parser)]
1273pub enum ProjectCommand {
1274 /// Create a new Linera project.
1275 New {
1276 /// The project name. A directory of the same name will be created in the current directory.
1277 name: String,
1278
1279 /// Use the given clone of the Linera repository instead of remote crates.
1280 #[arg(long)]
1281 linera_root: Option<PathBuf>,
1282 },
1283
1284 /// Test a Linera project.
1285 ///
1286 /// Equivalent to running `cargo test` with the appropriate test runner.
1287 Test { path: Option<PathBuf> },
1288
1289 /// Build and publish a Linera project.
1290 PublishAndCreate {
1291 /// The path of the root of the Linera project.
1292 /// Defaults to current working directory if unspecified.
1293 path: Option<PathBuf>,
1294
1295 /// Specify the name of the Linera project.
1296 /// This is used to locate the generated bytecode files. The generated bytecode files should
1297 /// be of the form `<name>_{contract,service}.wasm`.
1298 ///
1299 /// Defaults to the package name in Cargo.toml, with dashes replaced by
1300 /// underscores.
1301 name: Option<String>,
1302
1303 /// An optional chain ID to publish the module. The default chain of the wallet
1304 /// is used otherwise.
1305 publisher: Option<ChainId>,
1306
1307 /// The virtual machine runtime to use.
1308 #[arg(long, default_value = "wasm")]
1309 vm_runtime: VmRuntime,
1310
1311 /// The shared parameters as JSON string.
1312 #[arg(long)]
1313 json_parameters: Option<String>,
1314
1315 /// Path to a JSON file containing the shared parameters.
1316 #[arg(long)]
1317 json_parameters_path: Option<PathBuf>,
1318
1319 /// The instantiation argument as a JSON string.
1320 #[arg(long)]
1321 json_argument: Option<String>,
1322
1323 /// Path to a JSON file containing the instantiation argument.
1324 #[arg(long)]
1325 json_argument_path: Option<PathBuf>,
1326
1327 /// The list of required dependencies of application, if any.
1328 #[arg(long, num_args(0..))]
1329 required_application_ids: Option<Vec<ApplicationId>>,
1330 },
1331}