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 `OWNER@CHAIN-ID` 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 `OWNER@CHAIN-ID` 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 `OWNER@CHAIN-ID` 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        /// Run in read-only mode: disallow mutations and prevent queries from scheduling
744        /// operations. Use this when exposing the service to untrusted clients.
745        #[arg(long)]
746        read_only: bool,
747    },
748
749    /// Run a GraphQL service that exposes a faucet where users can claim tokens.
750    /// This gives away the chain's tokens, and is mainly intended for testing.
751    Faucet {
752        /// The chain that gives away its tokens.
753        chain_id: Option<ChainId>,
754
755        /// The port on which to run the server
756        #[arg(long, default_value = "8080")]
757        port: u16,
758
759        /// The port for prometheus to scrape.
760        #[cfg(with_metrics)]
761        #[arg(long, default_value = "9090")]
762        metrics_port: u16,
763
764        /// The number of tokens to send to each new chain.
765        #[arg(long)]
766        amount: Amount,
767
768        /// The end timestamp: The faucet will rate-limit the token supply so it runs out of money
769        /// no earlier than this.
770        #[arg(long)]
771        limit_rate_until: Option<DateTime<Utc>>,
772
773        /// Configuration for the faucet chain listener.
774        #[command(flatten)]
775        config: ChainListenerConfig,
776
777        /// Path to the persistent storage file for faucet mappings.
778        #[arg(long)]
779        storage_path: PathBuf,
780
781        /// Maximum number of operations to include in a single block (default: 100).
782        #[arg(long, default_value = "100")]
783        max_batch_size: usize,
784    },
785
786    /// Publish module.
787    PublishModule {
788        /// Path to the Wasm file for the application "contract" bytecode.
789        contract: PathBuf,
790
791        /// Path to the Wasm file for the application "service" bytecode.
792        service: PathBuf,
793
794        /// The virtual machine runtime to use.
795        #[arg(long, default_value = "wasm")]
796        vm_runtime: VmRuntime,
797
798        /// An optional chain ID to publish the module. The default chain of the wallet
799        /// is used otherwise.
800        publisher: Option<ChainId>,
801    },
802
803    /// Print events from a specific chain and stream from a specified index.
804    ListEventsFromIndex {
805        /// The chain to query. If omitted, query the default chain of the wallet.
806        chain_id: Option<ChainId>,
807
808        /// The stream being considered.
809        #[arg(long)]
810        stream_id: StreamId,
811
812        /// Index of the message to start with
813        #[arg(long, default_value = "0")]
814        start_index: u32,
815    },
816
817    /// Publish a data blob of binary data.
818    PublishDataBlob {
819        /// Path to data blob file to be published.
820        blob_path: PathBuf,
821        /// An optional chain ID to publish the blob. The default chain of the wallet
822        /// is used otherwise.
823        publisher: Option<ChainId>,
824    },
825
826    // TODO(#2490): Consider removing or renaming this.
827    /// Verify that a data blob is readable.
828    ReadDataBlob {
829        /// The hash of the content.
830        hash: CryptoHash,
831        /// An optional chain ID to verify the blob. The default chain of the wallet
832        /// is used otherwise.
833        reader: Option<ChainId>,
834    },
835
836    /// Create an application.
837    CreateApplication {
838        /// The module ID of the application to create.
839        module_id: ModuleId,
840
841        /// An optional chain ID to host the application. The default chain of the wallet
842        /// is used otherwise.
843        creator: Option<ChainId>,
844
845        /// The shared parameters as JSON string.
846        #[arg(long)]
847        json_parameters: Option<String>,
848
849        /// Path to a JSON file containing the shared parameters.
850        #[arg(long)]
851        json_parameters_path: Option<PathBuf>,
852
853        /// The instantiation argument as a JSON string.
854        #[arg(long)]
855        json_argument: Option<String>,
856
857        /// Path to a JSON file containing the instantiation argument.
858        #[arg(long)]
859        json_argument_path: Option<PathBuf>,
860
861        /// The list of required dependencies of application, if any.
862        #[arg(long, num_args(0..))]
863        required_application_ids: Option<Vec<ApplicationId>>,
864    },
865
866    /// Create an application, and publish the required module.
867    PublishAndCreate {
868        /// Path to the Wasm file for the application "contract" bytecode.
869        contract: PathBuf,
870
871        /// Path to the Wasm file for the application "service" bytecode.
872        service: PathBuf,
873
874        /// The virtual machine runtime to use.
875        #[arg(long, default_value = "wasm")]
876        vm_runtime: VmRuntime,
877
878        /// An optional chain ID to publish the module. The default chain of the wallet
879        /// is used otherwise.
880        publisher: Option<ChainId>,
881
882        /// The shared parameters as JSON string.
883        #[arg(long)]
884        json_parameters: Option<String>,
885
886        /// Path to a JSON file containing the shared parameters.
887        #[arg(long)]
888        json_parameters_path: Option<PathBuf>,
889
890        /// The instantiation argument as a JSON string.
891        #[arg(long)]
892        json_argument: Option<String>,
893
894        /// Path to a JSON file containing the instantiation argument.
895        #[arg(long)]
896        json_argument_path: Option<PathBuf>,
897
898        /// The list of required dependencies of application, if any.
899        #[arg(long, num_args(0..))]
900        required_application_ids: Option<Vec<ApplicationId>>,
901    },
902
903    /// Create an unassigned key pair.
904    Keygen,
905
906    /// Link the owner to the chain.
907    /// Expects that the caller has a private key corresponding to the `public_key`,
908    /// otherwise block proposals will fail when signing with it.
909    Assign {
910        /// The owner to assign.
911        #[arg(long)]
912        owner: AccountOwner,
913
914        /// The ID of the chain.
915        #[arg(long)]
916        chain_id: ChainId,
917    },
918
919    /// Retry a block we unsuccessfully tried to propose earlier.
920    ///
921    /// As long as a block is pending most other commands will fail, since it is unsafe to propose
922    /// multiple blocks at the same height.
923    RetryPendingBlock {
924        /// The chain with the pending block. If not specified, the wallet's default chain is used.
925        chain_id: Option<ChainId>,
926    },
927
928    /// Show the contents of the wallet.
929    #[command(subcommand)]
930    Wallet(WalletCommand),
931
932    /// Show the information about a chain.
933    #[command(subcommand)]
934    Chain(ChainCommand),
935
936    /// Manage Linera projects.
937    #[command(subcommand)]
938    Project(ProjectCommand),
939
940    /// Manage a local Linera Network.
941    #[command(subcommand)]
942    Net(NetCommand),
943
944    /// Manage validators in the committee.
945    #[command(subcommand)]
946    Validator(validator::Command),
947
948    /// Operation on the storage.
949    #[command(subcommand)]
950    Storage(DatabaseToolCommand),
951
952    /// Print CLI help in Markdown format, and exit.
953    #[command(hide = true)]
954    HelpMarkdown,
955
956    /// Extract a Bash and GraphQL script embedded in a markdown file and print it on
957    /// `stdout`.
958    #[command(hide = true)]
959    ExtractScriptFromMarkdown {
960        /// The source file
961        path: PathBuf,
962
963        /// Insert a pause of N seconds after calls to `linera service`.
964        #[arg(long, default_value = DEFAULT_PAUSE_AFTER_LINERA_SERVICE_SECS, value_parser = util::parse_secs)]
965        pause_after_linera_service: Duration,
966
967        /// Insert a pause of N seconds after GraphQL queries.
968        #[arg(long, default_value = DEFAULT_PAUSE_AFTER_GQL_MUTATIONS_SECS, value_parser = util::parse_secs)]
969        pause_after_gql_mutations: Duration,
970    },
971
972    /// Generate shell completion scripts
973    Completion {
974        /// The shell to generate completions for
975        #[arg(value_enum)]
976        shell: clap_complete::Shell,
977    },
978}
979
980impl ClientCommand {
981    /// Returns the log file name to use based on the [`ClientCommand`] that will run.
982    pub fn log_file_name(&self) -> Cow<'static, str> {
983        match self {
984            ClientCommand::Transfer { .. }
985            | ClientCommand::OpenChain { .. }
986            | ClientCommand::OpenMultiOwnerChain { .. }
987            | ClientCommand::ShowOwnership { .. }
988            | ClientCommand::ChangeOwnership { .. }
989            | ClientCommand::SetPreferredOwner { .. }
990            | ClientCommand::ChangeApplicationPermissions { .. }
991            | ClientCommand::CloseChain { .. }
992            | ClientCommand::ShowNetworkDescription
993            | ClientCommand::LocalBalance { .. }
994            | ClientCommand::QueryBalance { .. }
995            | ClientCommand::SyncBalance { .. }
996            | ClientCommand::Sync { .. }
997            | ClientCommand::ProcessInbox { .. }
998            | ClientCommand::QueryShardInfo { .. }
999            | ClientCommand::ResourceControlPolicy { .. }
1000            | ClientCommand::RevokeEpochs { .. }
1001            | ClientCommand::CreateGenesisConfig { .. }
1002            | ClientCommand::PublishModule { .. }
1003            | ClientCommand::ListEventsFromIndex { .. }
1004            | ClientCommand::PublishDataBlob { .. }
1005            | ClientCommand::ReadDataBlob { .. }
1006            | ClientCommand::CreateApplication { .. }
1007            | ClientCommand::PublishAndCreate { .. }
1008            | ClientCommand::Keygen
1009            | ClientCommand::Assign { .. }
1010            | ClientCommand::Wallet { .. }
1011            | ClientCommand::Chain { .. }
1012            | ClientCommand::Validator { .. }
1013            | ClientCommand::RetryPendingBlock { .. } => "client".into(),
1014            ClientCommand::Benchmark(BenchmarkCommand::Single { .. }) => "single-benchmark".into(),
1015            ClientCommand::Benchmark(BenchmarkCommand::Multi { .. }) => "multi-benchmark".into(),
1016            ClientCommand::Net { .. } => "net".into(),
1017            ClientCommand::Project { .. } => "project".into(),
1018            ClientCommand::Watch { .. } => "watch".into(),
1019            ClientCommand::Storage { .. } => "storage".into(),
1020            ClientCommand::Service { port, .. } => format!("service-{port}").into(),
1021            ClientCommand::Faucet { .. } => "faucet".into(),
1022            ClientCommand::HelpMarkdown
1023            | ClientCommand::ExtractScriptFromMarkdown { .. }
1024            | ClientCommand::Completion { .. } => "tool".into(),
1025        }
1026    }
1027}
1028
1029#[derive(Clone, clap::Parser)]
1030pub enum DatabaseToolCommand {
1031    /// Delete all the namespaces in the database
1032    DeleteAll,
1033
1034    /// Delete a single namespace from the database
1035    DeleteNamespace,
1036
1037    /// Check existence of a namespace in the database
1038    CheckExistence,
1039
1040    /// Initialize a namespace in the database
1041    Initialize {
1042        #[arg(long = "genesis")]
1043        genesis_config_path: PathBuf,
1044    },
1045
1046    /// List the namespaces in the database
1047    ListNamespaces,
1048
1049    /// List the blob IDs in the database
1050    ListBlobIds,
1051
1052    /// List the chain IDs in the database
1053    ListChainIds,
1054
1055    /// List the event IDs in the database
1056    ListEventIds,
1057}
1058
1059#[allow(clippy::large_enum_variant)]
1060#[derive(Clone, clap::Parser)]
1061pub enum NetCommand {
1062    /// Start a Local Linera Network
1063    Up {
1064        /// The number of initial "root" chains created in the genesis config on top of
1065        /// the default "admin" chain. All initial chains belong to the first "admin"
1066        /// wallet. It is recommended to use at least one other initial chain for the
1067        /// faucet.
1068        #[arg(long, default_value = "2")]
1069        other_initial_chains: u32,
1070
1071        /// The initial amount of native tokens credited in the initial "root" chains,
1072        /// including the default "admin" chain.
1073        #[arg(long, default_value = "1000000")]
1074        initial_amount: u128,
1075
1076        /// The number of validators in the local test network.
1077        #[arg(long, default_value = "1")]
1078        validators: usize,
1079
1080        /// The number of proxies in the local test network.
1081        #[arg(long, default_value = "1")]
1082        proxies: usize,
1083
1084        /// The number of shards per validator in the local test network.
1085        #[arg(long, default_value = "1")]
1086        shards: usize,
1087
1088        /// Configure the resource control policy (notably fees) according to pre-defined
1089        /// settings.
1090        #[arg(long, default_value = "no-fees")]
1091        policy_config: ResourceControlPolicyConfig,
1092
1093        /// The configuration for cross-chain messages.
1094        #[clap(flatten)]
1095        cross_chain_config: CrossChainConfig,
1096
1097        /// Force this wallet to generate keys using a PRNG and a given seed. USE FOR
1098        /// TESTING ONLY.
1099        #[arg(long)]
1100        testing_prng_seed: Option<u64>,
1101
1102        /// Start the local network on a local Kubernetes deployment.
1103        #[cfg(feature = "kubernetes")]
1104        #[arg(long)]
1105        kubernetes: bool,
1106
1107        /// If this is not set, we'll build the binaries from within the Docker container
1108        /// If it's set, but with no directory path arg, we'll look for the binaries based on `current_binary_parent`
1109        /// If it's set, but with a directory path arg, we'll get the binaries from that path directory
1110        #[cfg(feature = "kubernetes")]
1111        #[arg(long, num_args=0..=1)]
1112        binaries: Option<Option<PathBuf>>,
1113
1114        /// Don't build docker image. This assumes that the image is already built.
1115        #[cfg(feature = "kubernetes")]
1116        #[arg(long, default_value = "false")]
1117        no_build: bool,
1118
1119        /// The name of the docker image to use.
1120        #[cfg(feature = "kubernetes")]
1121        #[arg(long, default_value = "linera:latest")]
1122        docker_image_name: String,
1123
1124        /// The build mode to use.
1125        #[cfg(feature = "kubernetes")]
1126        #[arg(long, default_value = "release")]
1127        build_mode: BuildMode,
1128
1129        /// Run with a specific path where the wallet and validator input files are.
1130        /// If none, then a temporary directory is created.
1131        #[arg(long)]
1132        path: Option<String>,
1133
1134        /// External protocol used, either `grpc` or `grpcs`.
1135        #[arg(long, default_value = "grpc")]
1136        external_protocol: String,
1137
1138        /// If present, a faucet is started using the chain provided by --faucet-chain, or
1139        /// the first non-admin chain if not provided.
1140        #[arg(long, default_value = "false")]
1141        with_faucet: bool,
1142
1143        /// When using --with-faucet, this specifies the chain on which the faucet will be started.
1144        /// If this is `n`, the `n`-th non-admin chain (lexicographically) in the wallet is selected.
1145        #[arg(long)]
1146        faucet_chain: Option<u32>,
1147
1148        /// The port on which to run the faucet server
1149        #[arg(long, default_value = "8080")]
1150        faucet_port: NonZeroU16,
1151
1152        /// The number of tokens to send to each new chain created by the faucet.
1153        #[arg(long, default_value = "1000")]
1154        faucet_amount: Amount,
1155
1156        /// Whether to start a block exporter for each validator.
1157        #[arg(long, default_value = "false")]
1158        with_block_exporter: bool,
1159
1160        /// The number of block exporters to start.
1161        #[arg(long, default_value = "1")]
1162        num_block_exporters: usize,
1163
1164        /// The address of the block exporter.
1165        #[arg(long, default_value = "localhost")]
1166        exporter_address: String,
1167
1168        /// The port on which to run the block exporter.
1169        #[arg(long, default_value = "8081")]
1170        exporter_port: NonZeroU16,
1171
1172        /// The name of the indexer docker image to use.
1173        #[cfg(feature = "kubernetes")]
1174        #[arg(long, default_value = "linera-indexer:latest")]
1175        indexer_image_name: String,
1176
1177        /// The name of the explorer docker image to use.
1178        #[cfg(feature = "kubernetes")]
1179        #[arg(long, default_value = "linera-explorer:latest")]
1180        explorer_image_name: String,
1181
1182        /// Use dual store (rocksdb and scylladb) instead of just scylladb. This is exclusive for
1183        /// kubernetes deployments.
1184        #[cfg(feature = "kubernetes")]
1185        #[arg(long, default_value = "false")]
1186        dual_store: bool,
1187    },
1188
1189    /// Print a bash helper script to make `linera net up` easier to use. The script is
1190    /// meant to be installed in `~/.bash_profile` or sourced when needed.
1191    Helper,
1192}
1193
1194#[derive(Clone, clap::Subcommand)]
1195pub enum WalletCommand {
1196    /// Show the contents of the wallet.
1197    Show {
1198        /// The chain to show the metadata.
1199        chain_id: Option<ChainId>,
1200        /// Only print a non-formatted list of the wallet's chain IDs.
1201        #[arg(long)]
1202        short: bool,
1203        /// Print only the chains that we have a key pair for.
1204        #[arg(long)]
1205        owned: bool,
1206    },
1207
1208    /// Change the wallet default chain.
1209    SetDefault { chain_id: ChainId },
1210
1211    /// Initialize a wallet from the genesis configuration.
1212    Init {
1213        /// The path to the genesis configuration for a Linera deployment. Either this or `--faucet`
1214        /// must be specified.
1215        ///
1216        /// Overrides `--faucet` if provided.
1217        #[arg(long = "genesis")]
1218        genesis_config_path: Option<PathBuf>,
1219
1220        /// The address of a faucet.
1221        #[arg(long, env = "LINERA_FAUCET_URL")]
1222        faucet: Option<String>,
1223
1224        /// Force this wallet to generate keys using a PRNG and a given seed. USE FOR
1225        /// TESTING ONLY.
1226        #[arg(long)]
1227        testing_prng_seed: Option<u64>,
1228    },
1229
1230    /// Request a new chain from a faucet and add it to the wallet.
1231    RequestChain {
1232        /// The address of a faucet.
1233        #[arg(long, env = "LINERA_FAUCET_URL")]
1234        faucet: String,
1235
1236        /// Whether this chain should become the default chain.
1237        #[arg(long)]
1238        set_default: bool,
1239    },
1240
1241    /// Export the genesis configuration to a JSON file.
1242    ///
1243    /// By default, exports the genesis config from the current wallet. Alternatively,
1244    /// use `--faucet` to retrieve the genesis config directly from a faucet URL.
1245    ExportGenesis {
1246        /// Path to save the genesis configuration JSON file.
1247        output: PathBuf,
1248
1249        /// The address of a faucet to retrieve the genesis config from.
1250        /// If not specified, the genesis config is read from the current wallet.
1251        #[arg(long)]
1252        faucet: Option<String>,
1253    },
1254
1255    /// Add a new followed chain (i.e. a chain without keypair) to the wallet.
1256    FollowChain {
1257        /// The chain ID.
1258        chain_id: ChainId,
1259        /// Synchronize the new chain and download all its blocks from the validators.
1260        #[arg(long)]
1261        sync: bool,
1262    },
1263
1264    /// Forgets the specified chain's keys. The chain will still be followed by the
1265    /// wallet.
1266    ForgetKeys { chain_id: ChainId },
1267
1268    /// Forgets the specified chain, including the associated key pair.
1269    ForgetChain { chain_id: ChainId },
1270}
1271
1272#[derive(Clone, clap::Subcommand)]
1273pub enum ChainCommand {
1274    /// Show the contents of a block.
1275    ShowBlock {
1276        /// The height of the block.
1277        height: BlockHeight,
1278        /// The chain to show the block (if not specified, the default chain from the
1279        /// wallet is used).
1280        chain_id: Option<ChainId>,
1281    },
1282
1283    /// Show the chain description of a chain.
1284    ShowChainDescription {
1285        /// The chain ID to show (if not specified, the default chain from the wallet is
1286        /// used).
1287        chain_id: Option<ChainId>,
1288    },
1289}
1290
1291#[derive(Clone, clap::Parser)]
1292pub enum ProjectCommand {
1293    /// Create a new Linera project.
1294    New {
1295        /// The project name. A directory of the same name will be created in the current directory.
1296        name: String,
1297
1298        /// Use the given clone of the Linera repository instead of remote crates.
1299        #[arg(long)]
1300        linera_root: Option<PathBuf>,
1301    },
1302
1303    /// Test a Linera project.
1304    ///
1305    /// Equivalent to running `cargo test` with the appropriate test runner.
1306    Test { path: Option<PathBuf> },
1307
1308    /// Build and publish a Linera project.
1309    PublishAndCreate {
1310        /// The path of the root of the Linera project.
1311        /// Defaults to current working directory if unspecified.
1312        path: Option<PathBuf>,
1313
1314        /// Specify the name of the Linera project.
1315        /// This is used to locate the generated bytecode files. The generated bytecode files should
1316        /// be of the form `<name>_{contract,service}.wasm`.
1317        ///
1318        /// Defaults to the package name in Cargo.toml, with dashes replaced by
1319        /// underscores.
1320        name: Option<String>,
1321
1322        /// An optional chain ID to publish the module. The default chain of the wallet
1323        /// is used otherwise.
1324        publisher: Option<ChainId>,
1325
1326        /// The virtual machine runtime to use.
1327        #[arg(long, default_value = "wasm")]
1328        vm_runtime: VmRuntime,
1329
1330        /// The shared parameters as JSON string.
1331        #[arg(long)]
1332        json_parameters: Option<String>,
1333
1334        /// Path to a JSON file containing the shared parameters.
1335        #[arg(long)]
1336        json_parameters_path: Option<PathBuf>,
1337
1338        /// The instantiation argument as a JSON string.
1339        #[arg(long)]
1340        json_argument: Option<String>,
1341
1342        /// Path to a JSON file containing the instantiation argument.
1343        #[arg(long)]
1344        json_argument_path: Option<PathBuf>,
1345
1346        /// The list of required dependencies of application, if any.
1347        #[arg(long, num_args(0..))]
1348        required_application_ids: Option<Vec<ApplicationId>>,
1349    },
1350}
linera_service/cli/command.rs

linera_service/cli/
command.rs
