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": [],

See ChainSpec for a trait representation of the above.

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

Enums

Traits

  • BuildGenesisBlock
    Trait for building the genesis block.
  • ChainSpec
    Common interface of a chain specification.
  • Extension
    A collection of ChainSpec extensions.
  • Fork
    A ChainSpec extension fork definition.
  • GetExtension
    A subset if the Extension trait that only allows for quering extensions.
  • Group
    A ChainSpec extension.
  • RuntimeGenesis
    A set of traits for the runtime genesis config.

Functions

Type Definitions

  • NoExtension
    A type denoting empty extensions.
  • Properties
    Arbitrary properties defined in chain spec as a JSON object

Derive Macros