[Substrate.io] Chain Specification #27
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ## Declaring storage items for a runtime | ||
|
|
||
| In most cases, a runtime requires some storage items to be configured at genesis. | ||
| For example, if you are developing the runtime with FRAME, any storage item that is declared with the `Config` trait in the runtime requires configuration at genesis. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[Papermoon.Acronyms] Spell out 'FRAME', if it's unfamiliar to the audience.
|
|
||
| ## Declaring storage items for a runtime | ||
|
|
||
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` exists, or the account that has sudo permissions. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Spacing] 's. T' should have one space.
|
|
||
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` exists, or the account that has sudo permissions. | ||
|
|
||
| These storage values are configured in the genesis portion of the chain specification. You can either create a patch file for [`chain-spec-builder`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/chain_spec_genesis/index.html){target=_blank} to ingest, or if you're using `chain_spec.rs`, the pallet can be configured in the code. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Spacing] 'n. Y' should have one space.
| ### Using Node Binary | ||
|
|
||
|
|
||
| !!!warning "Be aware of the Omninode" |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Papermoon.CustomDictionary] Did you really mean 'Omninode'?
| ### Using Node Binary | ||
|
|
||
|
|
||
| !!!warning "Be aware of the Omninode" |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Omninode'?
|
|
||
|
|
||
| !!!warning "Be aware of the Omninode" | ||
| As mentioned, there are two methods for generating a chain specification. The preferred method is [`chain-spec-builder`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/chain_spec_genesis/index.html){target=_blank}, however the `build-spec` method can be utilized as well. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Google.Spacing] 'n. T' should have one space.
|
|
||
| A _chain specification_ is the collection of information that describes a Polkadot SDK-based network. When starting a node, a chain specification is a crucial parameter, providing the genesis configurations, bootnodes, and other parameters relating to that particular network. It identifies the network that a blockchain node connects to, the other nodes that it initially communicates with, and the initial state that nodes must agree on to produce blocks. | ||
|
|
||
| The chain specification is defined using the [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/struct.GenericChainSpec.html){target=_blank}. |
There was a problem hiding this comment.
nit: Maybe it would be better to describe a json that describes chain-spec?
Not sure if divin into rust structures makes sense.
But this depends on who is the target audience of this spec.
There is a description of fields here:
https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/index.html#intro-chain-specification
What reminds me that we need a json vaidation scheme for chain spec file (of course out of scope of this PR).
There was a problem hiding this comment.
+1. I think it is better to refer to the Polkadot SDK docs instead of the Rust struct
|
|
||
| The [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/parachain_template_node/chain_spec/type.ChainSpec.html){target=_blank} separates the information required for a chain into two parts: | ||
|
|
||
| - A client specification that contains information used by the _outer node_ to communicate with network participants and send data to telemetry endpoints. Many of these chain specification settings can be overridden by command-line options when starting a node or can be changed after the blockchain has started |
| - The account that controls the `sudo` key | ||
| - Any other genesis state for a pallet | ||
|
|
||
| Nodes also include the compiled WebAssembly for the runtime logic on the chain, so the initial runtime must also be supplied in the chain specification. |
There was a problem hiding this comment.
Suggested change
| Nodes also include the compiled WebAssembly for the runtime logic on the chain, so the initial runtime must also be supplied in the chain specification. | |
| Nodes also require the compiled WebAssembly for executing the runtime logic on the chain, so the initial runtime must also be supplied in the chain specification. |
Comment on lines
+35
to
+38
| - Initial account balances | ||
| - Accounts that are initially part of a governance council | ||
| - The account that controls the `sudo` key | ||
| - Any other genesis state for a pallet |
There was a problem hiding this comment.
I would mention that this customization is feasible for development. For production raw format is recommended.
|
|
||
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` exists, or the account that has sudo permissions. | ||
|
|
||
| These storage values are configured in the genesis portion of the chain specification. You can either create a [patch](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/index.html#chain-spec-formats){target=_blank} file for [`chain-spec-builder`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/chain_spec_genesis/index.html){target=_blank} to ingest, or if you're using `chain_spec.rs`, the pallet can be configured in the code. |
There was a problem hiding this comment.
I think link for chain-spec-builder is wrong.
But referring to the tutorial on genesis config (which is actually linked) may make sense.
|
|
||
|
|
||
| !!!warning "Be aware of the Omninode" | ||
| As mentioned, there are two methods for generating a chain specification. The preferred method is [`chain-spec-builder`](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/chain_spec_genesis/index.html){target=_blank}, however the `build-spec` method can be utilized as well. |
There was a problem hiding this comment.
The link to chain-spec-builder is: https://paritytech.github.io/polkadot-sdk/master/staging_chain_spec_builder/index.html
There was a problem hiding this comment.
And also why mention chain-spec-builder in Using node binary section? I'd remove it...
|
|
||
| In the JSON file, this key and its associated value are human-readable text. However, this information can't be stored in this format in the underlying storage structures that Substrate uses. Before you can use the chain specification to initialize the genesis storage for a node, the human-readable keys must be transformed into actual storage keys that allow the values to be stored in the storage trie. This transformation is straight-forward, but it requires that the chain specification to be encoded in a format that node runtime can read. | ||
|
|
||
| To enable a node with an upgraded runtime to synchronize with a chain from genesis, the human-readable chain specification is encoded in a **raw** format. |
There was a problem hiding this comment.
human-readable is often referred as plain (maybe worth using this phrasing too)
| To enable a node with an upgraded runtime to synchronize with a chain from genesis, the human-readable chain specification is encoded in a **raw** format. | ||
| The raw format enables you distribute chain specifications that all nodes can use to synchronize the chain even after runtime upgrades. | ||
|
|
||
| Nodes support the `--raw` command-line option to produce the raw chain specifications. |
There was a problem hiding this comment.
Also chain-spec-builder supports that by:
create --raw or dedicated convert-to-raw command.
0xLucca
requested changes
Oct 2, 2024
| @@ -0,0 +1,113 @@ | |||
| --- | |||
| title: Chain Specification | |||
| description: Describes the role of the chain specification in a network, how to specify the chain specification to use when starting a node, and how to customize and distribute chain specifications. | |||
There was a problem hiding this comment.
The description is too long. It has 185 characters. It should be between 120 and 160
|
|
||
| A _chain specification_ is the collection of information that describes a Polkadot SDK-based network. When starting a node, a chain specification is a crucial parameter, providing the genesis configurations, bootnodes, and other parameters relating to that particular network. It identifies the network that a blockchain node connects to, the other nodes that it initially communicates with, and the initial state that nodes must agree on to produce blocks. | ||
|
|
||
| The chain specification is defined using the [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/struct.GenericChainSpec.html){target=_blank}. |
There was a problem hiding this comment.
+1. I think it is better to refer to the Polkadot SDK docs instead of the Rust struct
|
|
||
| A _chain specification_ is the collection of information that describes a Polkadot SDK-based network. When starting a node, a chain specification is a crucial parameter, providing the genesis configurations, bootnodes, and other parameters relating to that particular network. It identifies the network that a blockchain node connects to, the other nodes that it initially communicates with, and the initial state that nodes must agree on to produce blocks. | ||
|
|
||
| The chain specification is defined using the [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/struct.GenericChainSpec.html){target=_blank}. |
There was a problem hiding this comment.
Suggested change
| The chain specification is defined using the [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/struct.GenericChainSpec.html){target=_blank}. | |
| The chain specification is defined using the [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/sc_chain_spec/struct.GenericChainSpec.html){target=\_blank}. |
|
|
||
| The [`ChainSpec` struct](https://paritytech.github.io/polkadot-sdk/master/parachain_template_node/chain_spec/type.ChainSpec.html){target=_blank} separates the information required for a chain into two parts: | ||
|
|
||
| - A client specification that contains information used by the _outer node_ to communicate with network participants and send data to telemetry endpoints. Many of these chain specification settings can be overridden by command-line options when starting a node or can be changed after the blockchain has started |
There was a problem hiding this comment.
Suggested change
| - A client specification that contains information used by the _outer node_ to communicate with network participants and send data to telemetry endpoints. Many of these chain specification settings can be overridden by command-line options when starting a node or can be changed after the blockchain has started | |
| - A client specification that contains information used by the _node_ to communicate with network participants and send data to telemetry endpoints. Many of these chain specification settings can be overridden by command-line options when starting a node or can be changed after the blockchain has started |
|
|
||
| - The initial **genesis state** that all nodes in the network agree on. The genesis state must be established when the blockchain is first started and it cannot be changed thereafter without starting an entirely new blockchain | ||
|
|
||
| ## Customizing Outer Node Settings |
There was a problem hiding this comment.
Suggested change
| ## Customizing Outer Node Settings | |
| ## Customizing Node Settings |
|
|
||
| ## Customizing Outer Node Settings | ||
|
|
||
| For the outer node, the chain specification controls information such as: |
There was a problem hiding this comment.
Replace other occurrences of outer node
|
|
||
| ## Declaring storage items for a runtime | ||
|
|
||
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` exists, or the account that has sudo permissions. |
There was a problem hiding this comment.
Suggested change
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` exists, or the account that has sudo permissions. | |
| In most cases, a runtime requires some storage items to be configured at genesis. This includes the initial state for pallets, for example, how much balance `Alice` or `Bob` has, or the account that has sudo permissions. |
|
|
||
| If you are creating a one-off network for development, testing, or demonstration purposes, you might want a fully customized chain specification. | ||
| To create a completely customized chain spec, you can export the default chain spec to JSON format, then edit the fields in the JSON file. | ||
| For example, you can use the `build-spec` sub-command to export the chain specification to a JSON file: |
There was a problem hiding this comment.
I would remove the entire line and then just have the two subsections
Suggested change
| For example, you can use the `build-spec` sub-command to export the chain specification to a JSON file: |
| ### Using Node Binary | ||
|
|
||
|
|
||
| !!!warning "Be aware of the Omninode" |
There was a problem hiding this comment.
Remove this. If chain spec builder is the preferred method, just put it first
|
|
||
| In the JSON file, this key and its associated value are human-readable text. However, this information can't be stored in this format in the underlying storage structures that Substrate uses. Before you can use the chain specification to initialize the genesis storage for a node, the human-readable keys must be transformed into actual storage keys that allow the values to be stored in the storage trie. This transformation is straight-forward, but it requires that the chain specification to be encoded in a format that node runtime can read. | ||
|
|
||
| To enable a node with an upgraded runtime to synchronize with a chain from genesis, the human-readable chain specification is encoded in a **raw** format. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The "Chain Specification" page was migrated from Substrate.io: https://docs.substrate.io/build/chain-spec/