Crate sc_chain_spec
source ·Expand description
Substrate chain configurations.
This crate contains structs and utilities to declare a runtime-specific configuration file (a.k.a chain spec).
Basic chain spec type containing all required parameters is
GenericChainSpec
. It can be extended with
additional options that contain configuration specific to your chain.
Usually the extension is going to be an amalgamate of types exposed
by Substrate core modules. To allow the core modules to retrieve
their configuration from your extension you should use ChainSpecExtension
macro exposed by this crate.
use std::collections::HashMap;
use sc_chain_spec::{GenericChainSpec, ChainSpecExtension};
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ChainSpecExtension)]
pub struct MyExtension {
pub known_blocks: HashMap<u64, String>,
}
pub type MyChainSpec<G> = GenericChainSpec<G, MyExtension>;
Some parameters may require different values depending on the
current blockchain height (a.k.a. forks). You can use ChainSpecGroup
macro and provided Forks
structure to put
such parameters to your chain spec.
This will allow to override a single parameter starting at specific
block number.
use sc_chain_spec::{Forks, ChainSpecGroup, ChainSpecExtension, GenericChainSpec};
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ChainSpecGroup)]
pub struct ClientParams {
max_block_size: usize,
max_extrinsic_size: usize,
}
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ChainSpecGroup)]
pub struct PoolParams {
max_transaction_size: usize,
}
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize, ChainSpecGroup, ChainSpecExtension)]
pub struct Extension {
pub client: ClientParams,
pub pool: PoolParams,
}
pub type BlockNumber = u64;
/// A chain spec supporting forkable `ClientParams`.
pub type MyChainSpec1<G> = GenericChainSpec<G, Forks<BlockNumber, ClientParams>>;
/// A chain spec supporting forkable `Extension`.
pub type MyChainSpec2<G> = GenericChainSpec<G, Forks<BlockNumber, Extension>>;
It’s also possible to have a set of parameters that is allowed to change
with block numbers (i.e. is forkable), and another set that is not subject to changes.
This is also possible by declaring an extension that contains Forks
within it.
use serde::{Serialize, Deserialize};
use sc_chain_spec::{Forks, GenericChainSpec, ChainSpecGroup, ChainSpecExtension};
#[derive(Clone, Debug, Serialize, Deserialize, ChainSpecGroup)]
pub struct ClientParams {
max_block_size: usize,
max_extrinsic_size: usize,
}
#[derive(Clone, Debug, Serialize, Deserialize, ChainSpecGroup)]
pub struct PoolParams {
max_transaction_size: usize,
}
#[derive(Clone, Debug, Serialize, Deserialize, ChainSpecExtension)]
pub struct Extension {
pub client: ClientParams,
#[forks]
pub pool: Forks<u64, PoolParams>,
}
pub type MyChainSpec<G> = GenericChainSpec<G, Extension>;
Substrate chain specification format
The Substrate chain specification is a json
file that describes the basics of a chain. Most
importantly it lays out the genesis storage which leads to the genesis hash. The default
Substrate chain specification format is the following:
// The human readable name of the chain.
"name": "Flaming Fir",
// The id of the chain.
"id": "flamingfir9",
// The chain type of this chain.
// Possible values are `Live`, `Development`, `Local`.
"chainType": "Live",
// A list of multi addresses that belong to boot nodes of the chain.
"bootNodes": [
"/dns/0.flamingfir.paritytech.net/tcp/30333/p2p/12D3KooWLK2gMLhWsYJzjW3q35zAs9FDDVqfqVfVuskiGZGRSMvR",
],
// Optional list of "multi address, verbosity" of telemetry endpoints.
// The verbosity goes from `0` to `9`. With `0` being the mode with the lowest verbosity.
"telemetryEndpoints": [
[
"/dns/telemetry.polkadot.io/tcp/443/x-parity-wss/%2Fsubmit%2F",
0
]
],
// Optional networking protocol id that identifies the chain.
"protocolId": "fir9",
// Optional fork id. Should most likely be left empty.
// Can be used to signal a fork on the network level when two chains have the
// same genesis hash.
"forkId": "random_fork",
// Custom properties.
"properties": {
"tokenDecimals": 15,
"tokenSymbol": "FIR"
},
// Deprecated field. Should be ignored.
"consensusEngine": null,
// The genesis declaration of the chain.
//
// `runtime`, `raw`, `stateRootHash` denote the type of the genesis declaration.
//
// These declarations are in the following formats:
// - `runtime` is a `json` object that can be parsed by a compatible `GenesisConfig`. This
// `GenesisConfig` is declared by a runtime and opaque to the node.
// - `raw` is a `json` object with two fields `top` and `children_default`. Each of these
// fields is a map of `key => value`. These key/value pairs represent the genesis storage.
// - `stateRootHash` is a single hex encoded hash that represents the genesis hash. The hash
// type depends on the hash used by the chain.
//
"genesis": { "runtime": {} },
/// Optional map of `block_number` to `wasm_code`.
///
/// The given `wasm_code` will be used to substitute the on-chain wasm code starting with the
/// given block number until the `spec_version` on-chain changes. The given `wasm_code` should
/// be as close as possible to the on-chain wasm code. A substitute should be used to fix a bug
/// that can not be fixed with a runtime upgrade, if for example the runtime is constantly
/// panicking. Introducing new runtime apis isn't supported, because the node
/// will read the runtime version from the on-chain wasm code. Use this functionality only when
/// there is no other way around it and only patch the problematic bug, the rest should be done
/// with a on-chain runtime upgrade.
"codeSubstitutes": [],
The chain spec can be extended with other fields that are opaque to the default chain spec. Specific node implementations will need to be able to deserialize these extensions.
Structs
- A configuration of a chain. Can be used to build a genesis block.
Enums
- The type of a chain.
Traits
- Common interface of a chain specification.
- A collection of
ChainSpec
extensions. - A
ChainSpec
extension fork definition. - A subset if the
Extension
trait that only allows for quering extensions. - A
ChainSpec
extension. - A set of traits for the runtime genesis config.
Functions
- Helper function that queries an extension by type from
GetExtension
trait object. - Helper function that queries an extension by type from
GetExtension
trait object.
Type Definitions
- A type denoting empty extensions.
- Arbitrary properties defined in chain spec as a JSON object