chain-spec-builder: info about patch/full files added (#6373)

There was no good example of what is patch and full genesis config file. Some explanation and example were added to the `chain-spec-builder` doc. --------- Co-authored-by: GitHub Action <[email protected]> Co-authored-by: Iulian Barbu <[email protected]>
paritytech · Nov 5, 2024 · b667c27 · b667c27
1 parent c5444f3
commit b667c27
Show file tree

Hide file tree

Showing 3 changed files with 96 additions and 0 deletions.
diff --git a/prdoc/pr_6373.prdoc b/prdoc/pr_6373.prdoc
@@ -0,0 +1,8 @@
+title: '`chain-spec-builder`: info about patch/full files added'
+doc:
+- audience: Runtime User
+  description: There was no good example of what is patch and full genesis config
+    file. Some explanation and example were added to the `chain-spec-builder` doc.
+crates:
+- name: staging-chain-spec-builder
+  bump: patch
diff --git a/substrate/bin/utils/chain-spec-builder/README.docify.md b/substrate/bin/utils/chain-spec-builder/README.docify.md
@@ -73,6 +73,8 @@ 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/sp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
 and
 [`GenesisBuilder::build_state`](https://docs.rs/sp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.build_state)
@@ -84,17 +86,59 @@ Build the chain spec using provided full genesis config json file. No defaults w
 
 <!-- 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/sp-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/staging-chain-spec-builder/latest/staging_chain_spec_builder/struct.VerifyCmd.html),

diff --git a/substrate/bin/utils/chain-spec-builder/README.md b/substrate/bin/utils/chain-spec-builder/README.md
@@ -99,6 +99,8 @@ bash!(
 )
 ```
 
+Refer to [*patch file*](#patch-file) for some details on the patch file format.
+
 _Note:_ [`GenesisBuilder::get_preset`](https://docs.rs/sp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.get_preset)
 and
 [`GenesisBuilder::build_state`](https://docs.rs/sp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.build_state)
@@ -114,6 +116,8 @@ bash!(
 )
 ```
 
+Refer to [*full config file*](#full-genesis-config-file) for some details on the full file format.
+
 _Note_: [`GenesisBuilder::build_state`](https://docs.rs/sp-genesis-builder/latest/sp_genesis_builder/trait.GenesisBuilder.html#method.build_state)
 runtime function is called.
 
@@ -125,6 +129,8 @@ bash!(
 )
 ```
 
+Refer to [*patch file*](#patch-file) for some details on the patch file format.
+
 ### Generate human readable chain spec using provided full genesis config
 
 ```rust,ignore
@@ -133,6 +139,44 @@ bash!(
 )
 ```
 
+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/staging-chain-spec-builder/latest/staging_chain_spec_builder/struct.VerifyCmd.html),