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 build-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.

Deprecation notice for CreateCmd's para-id flag

para-id flag is deprecated. 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 will be removed and nodes support for extracting the parachain id from the chain specification will stop from stable2512.

For reference, generating a chain specification with a para_id field can still be done until stable2512 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.

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.