Crate staging_chain_spec_builder 

Chain Spec Builder

Substrate’s chain spec builder utility.

A chain-spec is short for chain-specification. See the sc-chain-spec for more information.

Note: this binary is a more flexible alternative to the export-chain-spec subcommand, contained in typical Substrate-based nodes. This particular binary is capable of interacting with sp-genesis-builder implementation of any provided runtime allowing to build chain-spec JSON files.

See ChainSpecBuilderCmd for a list of available commands.

Installation

cargo install staging-chain-spec-builder --locked

Note: chain-spec-builder binary is published on crates.io under staging-chain-spec-builder due to a name conflict.

Usage

Please note that below usage is backed by integration tests. The commands’ examples are wrapped around by the bash!(...) macro calls.

Note for CreateCmd’s para-id flag

Runtimes relying on generating the chain specification with this tool should implement cumulus_primitives_core::GetParachainInfo trait, a new runtime API designed to provide the parachain ID from the parachain-info pallet. The para-id flag can be used though if the runtime does not implement the runtime API, and the parachain id will be fetched by the node from chain specification. This can be especially useful when syncing a node from a state where the runtime does not implement cumulus_primitives_core::GetParachainInfo.

For reference, generating a chain specification with a para_id field can be done like below:

chain-spec-builder -c "/dev/stdout" create --relay-chain "dev" --para-id 1000 -r $runtime_path named-preset "staging"

Generate chains-spec using default config from runtime

Query the default genesis config from the provided runtime WASM blob and use it in the chain spec.

bash!(
	chain-spec-builder -c "/dev/stdout" create -r $runtime_path default
)

Note: GenesisBuilder::get_preset runtime function is called.

Display the runtime’s default GenesisConfig

bash!(
	chain-spec-builder display-preset -r $runtime_path
)

Note: GenesisBuilder::get_preset runtime function is called.

Display the GenesisConfig preset with given name

fn cmd_display_preset(runtime_path: &str) -> String {
	bash!(
		chain-spec-builder display-preset -r $runtime_path -p "staging"
	)
}

Note: GenesisBuilder::get_preset runtime function is called.

List the names of GenesisConfig presets provided by runtime

bash!(
	chain-spec-builder list-presets -r $runtime_path
)

Note: GenesisBuilder::preset_names runtime function is called.

Generate chain spec using runtime provided genesis config preset

Patch the runtime’s default genesis config with the named preset provided by the runtime and generate the plain version of chain spec:

bash!(
	chain-spec-builder -c "/dev/stdout" create --relay-chain "dev" -r $runtime_path named-preset "staging"
)

Note: GenesisBuilder::get_preset runtime functions are called.

Generate raw storage chain spec using genesis config patch

Patch the runtime’s default genesis config with provided patch.json and generate raw storage (-s) version of chain spec:

bash!(
	chain-spec-builder -c "/dev/stdout" create -s -r $runtime_path patch "tests/input/patch.json"
)

Refer to patch file for some details on the patch file format.

Note: GenesisBuilder::get_preset and GenesisBuilder::build_state runtime functions are called.

Generate raw storage chain spec using full genesis config

Build the chain spec using provided full genesis config json file. No defaults will be used:

bash!(
	chain-spec-builder -c "/dev/stdout" create -s -r $runtime_path full "tests/input/full.json"
)

Refer to full config file for some details on the full file format.

Note: GenesisBuilder::build_state runtime function is called.

Generate human readable chain spec using provided genesis config patch

bash!(
	chain-spec-builder -c "/dev/stdout" create -r $runtime_path patch "tests/input/patch.json"
)

Refer to patch file for some details on the patch file format.

Generate human readable chain spec using provided full genesis config

bash!(
	chain-spec-builder -c "/dev/stdout" create -r $runtime_path full "tests/input/full.json"
)

Refer to full config file for some details on the full file format.

Manage the boot nodes of a chain spec

The bootnodes command group manages the boot nodes of an existing chain spec, through its add, remove and list subcommands. Plain and raw chain specs are both supported.

Append boot nodes to the chain spec. The addresses that are already stored are skipped, so the command can be safely repeated:

bash!(
	chain-spec-builder -c "/dev/stdout" bootnodes add $chain_spec_path "/dns/node-0.example.com/tcp/30333/p2p/12D3KooW9vw7UNUYQtPWK3RS8eyhjJgp4qBwbbiirYQcWLw5bCsf"
)

Remove boot nodes from the chain spec. The addresses that are not stored are ignored, and bootnodes remove <CHAIN_SPEC> --all removes all of them at once:

bash!(
	chain-spec-builder -c "/dev/stdout" bootnodes remove $chain_spec_path "/dns/node-0.example.com/tcp/30333/p2p/12D3KooW9vw7UNUYQtPWK3RS8eyhjJgp4qBwbbiirYQcWLw5bCsf"
)

List the boot nodes stored in a chain spec:

bash!(
	chain-spec-builder bootnodes list $chain_spec_path
)

The boot nodes of a newly created chain spec can be given with the --bootnodes argument of the create command.

Patch and full genesis config files

This section provides details on the files that can be used with create patch or create full subcommands.

Patch file

The patch file for genesis config contains the key-value pairs valid for given runtime, that needs to be customized, e.g:

{
 "balances": {
  "balances": [
   [
    "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
       1000000000000000
   ],
   [
    "5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y",
        1000000000000000
   ],
   [
    "5CcjiSgG2KLuKAsqkE2Nak1S2FbAcMr5SxRASUuwR3zSNV2b",
       5000000000000000
   ]
  ]
 },
 "sudo": {
  "key": "5Ff3iXP75ruzroPWRP2FYBHWnmGGBSb63857BgnzCoXNxfPo"
 }
}

The rest of genesis config keys will be initialized with default values.

Full genesis config file

The full genesis config file must contain values for all the keys present in the genesis config for given runtime. The format of the file is similar to patch format. Example is not provided here as it heavily depends on the runtime.

Extra tools

The chain-spec-builder provides also some extra utilities: VerifyCmd, ConvertToRawCmd, UpdateCodeCmd.

Structs

AddBootnodesCmd

Appends boot nodes to the provided input chain spec.

AddCodeSubstituteCmd

Add a code substitute in the chain spec.

ChainSpecBuilder

A utility to easily create a chain spec definition.

ConvertToRawCmd

Converts the given chain spec into the raw format.

CreateCmd

Create a new chain spec by interacting with the provided runtime wasm blob.

DisplayPresetCmd

Displays given preset

ListBootnodesCmd

Lists the boot nodes of the provided input chain spec.

ListPresetsCmd

Lists available presets

ParachainExtension

RemoveBootnodesCmd

Removes boot nodes from the provided input chain spec.

UpdateCodeCmd

Updates the code in the provided input chain spec.

VerifyCmd

Verifies the provided input chain spec.

Enums

BootnodesCmd

Manages the boot nodes stored in the bootNodes field of an existing chain spec.

ChainSpecBuilderCmd

Functions

generate_chain_spec_for_runtime

Processes CreateCmd and returns string representation of JSON version of ChainSpec.