partner_chains_cli/
lib.rs

1//! Provides wizard style CLI for Partner Chains setup and user operations.
2//! Interacts with Smart Contracts using [`partner_chains_cardano_offchain`] crate.
3#![deny(missing_docs)]
4
5mod cardano_key;
6mod cmd_traits;
7mod config;
8mod create_chain_spec;
9mod data_source;
10mod deregister;
11mod generate_keys;
12mod io;
13mod keystore;
14mod ogmios;
15mod permissioned_candidates;
16mod prepare_configuration;
17mod register;
18mod runtime_bindings;
19mod select_utxo;
20mod setup_main_chain_state;
21mod start_node;
22
23#[cfg(test)]
24mod tests;
25
26use clap::Parser;
27pub use create_chain_spec::CreateChainSpecConfig;
28pub use io::DefaultCmdRunContext;
29use io::*;
30pub use keystore::{AURA, CROSS_CHAIN, GRANDPA, KeyDefinition};
31use partner_chains_cardano_offchain::await_tx::FixedDelayRetries;
32pub use permissioned_candidates::ParsedPermissionedCandidatesKeys;
33pub use runtime_bindings::PartnerChainRuntime;
34use std::time::Duration;
35
36#[derive(Clone, Debug, clap::Parser)]
37#[command(author, version, about, long_about = None)]
38pub(crate) struct CommonArguments {
39	#[arg(default_value = "5", long)]
40	retry_delay_seconds: u64,
41	#[arg(default_value = "59", long)]
42	retry_count: usize,
43}
44
45impl CommonArguments {
46	pub(crate) fn retries(&self) -> FixedDelayRetries {
47		FixedDelayRetries::new(Duration::from_secs(self.retry_delay_seconds), self.retry_count)
48	}
49}
50
51#[derive(Clone, Debug, Parser)]
52#[command(
53    after_long_help = HELP_EXAMPLES,
54)]
55/// Partner Chains text "wizards" for setting up a chain.
56pub enum Command<T: PartnerChainRuntime + Send + Sync> {
57	/// This wizard generates the keys required for operating a partner-chains node, stores them in the keystore directory, and prints the public keys and keystore location.
58	GenerateKeys(generate_keys::GenerateKeysCmd<T>),
59	/// Wizard to obtain the configuration needed for the partner-chain governance authority. This configuration should be shared with chain participants and used to create the chain spec json file.
60	PrepareConfiguration(prepare_configuration::PrepareConfigurationCmd),
61	/// Wizard for setting D-parameter and Permissioned Candidates list on the main chain.
62	/// Uses 'chain config' obtained after running `prepare-configuration`.
63	SetupMainChainState(setup_main_chain_state::SetupMainChainStateCmd<T>),
64	/// Wizard for creating a chain spec json file based on the chain configuration (see `prepare-configuration`).
65	CreateChainSpec(create_chain_spec::CreateChainSpecCmd<T>),
66	/// Wizard for starting a substrate node in the environment set up by `generate-keys`,
67	/// `prepare-config`, and `create-chain-spec`. It also assists in setting the `resources configuration`.
68	StartNode(start_node::StartNodeCmd<T>),
69	/// The first step of registering as a committee candidate. Registration is split into three steps to allow the user to use their cold keys on a cold machine.
70	Register1(register::register1::Register1Cmd),
71	/// The second step of registering as a committee candidate, using cold keys.
72	Register2(register::register2::Register2Cmd),
73	/// The final step of registering as a committee candidate, not using cold keys.
74	Register3(register::register3::Register3Cmd),
75	/// Deregister from the candidates set. This command requires chain config file present in the running directory.
76	Deregister(deregister::DeregisterCmd),
77}
78
79impl<T: PartnerChainRuntime + Send + Sync> Command<T> {
80	/// Runs a Partner Chain wizard command.
81	pub fn run<C: IOContext>(&self, context: &C) -> anyhow::Result<()> {
82		match self {
83			Command::GenerateKeys(cmd) => cmd.run(context),
84			Command::PrepareConfiguration(cmd) => cmd.run(context),
85			Command::CreateChainSpec(cmd) => cmd.run(context),
86			Command::SetupMainChainState(cmd) => cmd.run(context),
87			Command::StartNode(cmd) => cmd.run(context),
88			Command::Register1(cmd) => cmd.run(context),
89			Command::Register2(cmd) => cmd.run(context),
90			Command::Register3(cmd) => cmd.run(context),
91			Command::Deregister(cmd) => cmd.run(context),
92		}
93	}
94}
95
96/// Trait representing a runnable command.
97pub trait CmdRun {
98	/// Runs command. The implemented command should do IO through the passed in `context` object.
99	fn run<C: IOContext>(&self, context: &C) -> anyhow::Result<()>;
100}
101
102const HELP_EXAMPLES: &str = r#"
103╔════════════════════════════════════════════════════════════════════════════════╗
104║                           Command groups by role                               ║
105╠════════════════════════════════════════════════════════════════════════════════╣
106║ The following sections outline the typical sequence of commands for each role. ║
107║ The numbering indicates the recommended order of execution. Please note that   ║
108║ this order may vary depending on specific deployment scenarios.                ║
109╟────────────────────────────────────────────────────────────────────────────────╢
110║ Governance Authority:                                                          ║
111║   1. generate-keys         : generate necessary cryptographic keys             ║
112║   2. prepare-configuration : set up the partner chain configuration            ║
113║   3. setup-main-chain-state: configure the main chain parameters               ║
114║   4. create-chain-spec     : create the chain specification file               ║
115║   5. start-node            : start the validator node                          ║
116╟────────────────────────────────────────────────────────────────────────────────╢
117║ Registered Validator:                                                          ║
118║   1. generate-keys         : generate validator keys                           ║
119║   2. register1             : initiate the registration process                 ║
120║   3. register2             : complete registration with cold keys              ║
121║   4. register3             : finalize registration                             ║
122║   5. start-node            : start the validator node                          ║
123║   6. deregister            : cancel registration                               ║
124║                                                                                ║
125║   Note: This sequence assumes that the chain-spec.json and                     ║
126║         pc-chain-config.json files have been obtained from                     ║
127║         the Governance Authority and are present in the working directory.     ║
128╟────────────────────────────────────────────────────────────────────────────────╢
129║ Permissioned Validator:                                                        ║
130║   1. generate-keys         : generate validator keys                           ║
131║   2. start-node            : start the validator node                          ║
132║                                                                                ║
133║   Note: After executing 'generate-keys', the generated keys must be shared     ║
134║         with the Governance Authority. The 'start-node' command can only be    ║
135║         executed after the Governance Authority has established the partner    ║
136║         chain on the main network. This sequence assumes that the              ║
137║         chain-spec.json and pc-chain-config.json files have                    ║
138║         been obtained from the Governance Authority and are present in the     ║
139║         working directory.                                                     ║
140╚════════════════════════════════════════════════════════════════════════════════╝
141"#;
partner_chains_cli/lib.rs

partner_chains_cli/
lib.rs
