# Chain Spec Builder

Bizinikiwi's chain spec builder utility.

A chain-spec is short for `chain-specification`. See the [`pezsc-chain-spec`](https://crates.io/docs.rs/pezsc-chain-spec/latest/sc_chain_spec)
for more information.

_Note:_ this binary is a more flexible alternative to the `build-spec` subcommand, contained in typical Bizinikiwi-based nodes.
This particular binary is capable of interacting with [`pezsp-genesis-builder`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/index.html)
implementation of any provided runtime allowing to build chain-spec JSON files.

See [`ChainSpecBuilderCmd`](https://docs.rs/pezstaging-chain-spec-builder/6.0.0/staging_chain_spec_builder/enum.ChainSpecBuilderCmd.html)
for a list of available commands.

## Installation

```bash
cargo install pezstaging-chain-spec-builder --locked
```

_Note:_ `chain-spec-builder` binary is published on [crates.io](https://crates.io) under
[`pezstaging-chain-spec-builder`](https://crates.io/crates/pezstaging-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

<!-- TODO: https://github.com/pezkuwichain/pezkuwi-sdk/issues/156 -->
Runtimes relying on generating the chain specification with this tool should
implement `cumulus_primitives_core::GetTeyrchainInfo` trait, a new runtime API
designed to provide the teyrchain ID from the `teyrchain-info`
pezpallet. The `para-id` flag can be used though if the runtime does not implement
the runtime API, and the teyrchain 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::GetTeyrchainInfo`.

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

```bash
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.

<!-- docify::embed!("tests/test.rs", cmd_create_default) -->

_Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
runtime function is called.

### Display the runtime's default `GenesisConfig`

<!-- docify::embed!("tests/test.rs", cmd_display_default_preset) -->

_Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
runtime function is called.

### Display the `GenesisConfig` preset with given name

<!-- docify::embed!("tests/test.rs", cmd_display_preset)-->

_Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
runtime function is called.

### List the names of `GenesisConfig` presets provided by runtime

<!-- docify::embed!("tests/test.rs", cmd_list_presets)-->

_Note:_ [`GenesisBuilder::preset_names`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.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:

<!-- docify::embed!("tests/test.rs", cmd_create_with_named_preset)-->

_Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.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:

<!-- docify::embed!("tests/test.rs", cmd_create_with_patch_raw)-->

Refer to [_patch file_](#patch-file) for some details on the patch file format.

_Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
and
[`GenesisBuilder::build_state`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.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:

<!-- docify::embed!("tests/test.rs", cmd_create_full_raw)-->

Refer to [_full config file_](#full-genesis-config-file) for some details on the full file format.

_Note_: [`GenesisBuilder::build_state`](https://docs.rs/pezsp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.build_state)
runtime function is called.

### Generate human readable chain spec using provided genesis config patch

<!-- docify::embed!("tests/test.rs", cmd_create_with_patch_plain)-->

Refer to [_patch file_](#patch-file) for some details on the patch file format.

### Generate human readable chain spec using provided full genesis config

<!-- docify::embed!("tests/test.rs", cmd_create_full_plain)-->

Refer to [_full config file_](#full-genesis-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:

```ignore
{
 "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`](https://docs.rs/pezstaging-chain-spec-builder/latest/staging_chain_spec_builder/struct.VerifyCmd.html),
[`ConvertToRawCmd`](https://docs.rs/pezstaging-chain-spec-builder/latest/staging_chain_spec_builder/struct.ConvertToRawCmd.html),
[`UpdateCodeCmd`](https://docs.rs/pezstaging-chain-spec-builder/latest/staging_chain_spec_builder/struct.UpdateCodeCmd.html).