From 099655b1ea6ad4e655192af1f69f596adf259d4c Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 13:54:41 +0200 Subject: [PATCH 01/25] chainSpec: Add initial clientSpec Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 92 ++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 src/api/chainSpec_unstable_spec.md diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md new file mode 100644 index 0000000..1e2df26 --- /dev/null +++ b/src/api/chainSpec_unstable_spec.md @@ -0,0 +1,92 @@ +# chainSpec_unstable_clientSpec + +**Parameters**: + +- `rawGenesis`: A boolean indicating whether the genesis block should be returned in raw format or not. + +**Return value**: A JSON object. + +The JSON object returned by this function has the following format: + +```json +{ + "name": "...", + + "id": "...", + + "chainType": "Live" | "Local" | "Development" | { "Custom": "..." }, + + "bootnodes": [ + "...", + ], + + "genesis": { + "stateRootHash": "0x...", + }, + + "telemetryEndpoints": [ + { + "address": "...", + "verbosity_level": 0, + } + ], +} +``` + +- `name` is a string containing the name of the chain, identical to the result of `chainSpec_v1_chainName`. +- `id` is a string containing the identifier of the chain. +- `chainType` is an object containing the type of the chain. +This information can be used by tools to display additional information to the user. +This fields can be one of the following values: + - `"Live"`: A string indicating the chain is a live chain. + - `"Local"`: A string indicating the chain is a local chain that runs on multiple nodes for testing purposes. + - `"Development"`: A string indicating the chain is a development chain that runs mainly on one node. + - `{ "Custom": "..." }`: A JSON object indicating the chain is a custom chain. The value of the `"Custom"` field is a string. +- `bootnodes` is an array of strings containing the [p2p multiaddr](https://github.com/libp2p/specs/blob/master/addressing/README.md#the-p2p-multiaddr) of the bootnodes of the chain. +For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU"` is a valid p2p multiaddr, where `12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU` represents the peer ID of the bootnode. +To establish a connection to the chain at least one bootnode is needed. +The servers are encouraged to provide at least one trusted bootnode. +- `genesis` is an object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. + - If `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: + + ```json + { + "raw": { + "top": { + "0x..": "0x..", + ... + }, + } + ... + } + ``` + + The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. + Both the keys and the values are hexadecimal-encoded strings. + The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. + For example, the wasm code of the runtime is stored under the key `b":code"`. + + - If `rawGenesis` is `false`, then the `genesis` field is a JSON object containing the Merkle value of the genesis block. + The object has the following format: + + ```json + { + "stateRootHash": "0x...", + } + ``` + + The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. + +- `telemetryEndpoints` is an array of objects containing the telemetry endpoints of the chain. +Each object has the following format: + + ```json + { + "address": "...", + "verbosity_level": 0, + } + ``` + + The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multiaddr format. + The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. + From 66d4f58db31ce0353e79d1392984c917e4a01fba Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 13:59:53 +0200 Subject: [PATCH 02/25] chainSpec: Add spaces between fields Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 1e2df26..0aa02b9 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -34,7 +34,9 @@ The JSON object returned by this function has the following format: ``` - `name` is a string containing the name of the chain, identical to the result of `chainSpec_v1_chainName`. + - `id` is a string containing the identifier of the chain. + - `chainType` is an object containing the type of the chain. This information can be used by tools to display additional information to the user. This fields can be one of the following values: @@ -42,10 +44,12 @@ This fields can be one of the following values: - `"Local"`: A string indicating the chain is a local chain that runs on multiple nodes for testing purposes. - `"Development"`: A string indicating the chain is a development chain that runs mainly on one node. - `{ "Custom": "..." }`: A JSON object indicating the chain is a custom chain. The value of the `"Custom"` field is a string. + - `bootnodes` is an array of strings containing the [p2p multiaddr](https://github.com/libp2p/specs/blob/master/addressing/README.md#the-p2p-multiaddr) of the bootnodes of the chain. For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU"` is a valid p2p multiaddr, where `12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU` represents the peer ID of the bootnode. To establish a connection to the chain at least one bootnode is needed. The servers are encouraged to provide at least one trusted bootnode. + - `genesis` is an object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. - If `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: @@ -89,4 +93,3 @@ Each object has the following format: The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multiaddr format. The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. - From e0cf5ef3fe682d3420732a41b466c9ede015e5aa Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:09:08 +0200 Subject: [PATCH 03/25] chainSpec: Add `properties` field Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 0aa02b9..e8fa596 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -30,6 +30,12 @@ The JSON object returned by this function has the following format: "verbosity_level": 0, } ], + + "properties": { + "ss58Format": 0, + "tokenDecimals": 0, + "tokenSymbol": "...", + } } ``` @@ -93,3 +99,8 @@ Each object has the following format: The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multiaddr format. The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. + +- `properties` is an object containing the properties of the chain. + The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). + The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. + The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. From 9152f758b0fc8278b6a9b0314de0a102a37a2531 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:11:49 +0200 Subject: [PATCH 04/25] chainSpec: Adjust multiaddress Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index e8fa596..5e5aa3e 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -51,7 +51,7 @@ This fields can be one of the following values: - `"Development"`: A string indicating the chain is a development chain that runs mainly on one node. - `{ "Custom": "..." }`: A JSON object indicating the chain is a custom chain. The value of the `"Custom"` field is a string. -- `bootnodes` is an array of strings containing the [p2p multiaddr](https://github.com/libp2p/specs/blob/master/addressing/README.md#the-p2p-multiaddr) of the bootnodes of the chain. +- `bootnodes` is an array of strings containing the [multi adresss format](https://github.com/multiformats/multiaddr) of the bootnodes of the chain. For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU"` is a valid p2p multiaddr, where `12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU` represents the peer ID of the bootnode. To establish a connection to the chain at least one bootnode is needed. The servers are encouraged to provide at least one trusted bootnode. @@ -97,7 +97,7 @@ Each object has the following format: } ``` - The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multiaddr format. + The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. - `properties` is an object containing the properties of the chain. From f348ca3ca939d151c6113a1d98927e24f20f0b92 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:12:39 +0200 Subject: [PATCH 05/25] chainSpec: Make telemetryEndpoints optional and add verbosity ranges Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 5e5aa3e..db1aa10 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -87,7 +87,7 @@ The servers are encouraged to provide at least one trusted bootnode. The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. -- `telemetryEndpoints` is an array of objects containing the telemetry endpoints of the chain. +- `telemetryEndpoints` is an _optional_ array of objects containing the telemetry endpoints of the chain. Each object has the following format: ```json @@ -98,7 +98,7 @@ Each object has the following format: ``` The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. - The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. + The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. - `properties` is an object containing the properties of the chain. The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). From 4ba70a72f82f0d1ff2564854b414f6311e72654e Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:15:16 +0200 Subject: [PATCH 06/25] chainSpec: Add optional protocolId Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index db1aa10..bb4da60 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -14,6 +14,8 @@ The JSON object returned by this function has the following format: "id": "...", + "protocolId": "...", + "chainType": "Live" | "Local" | "Development" | { "Custom": "..." }, "bootnodes": [ @@ -43,6 +45,8 @@ The JSON object returned by this function has the following format: - `id` is a string containing the identifier of the chain. +- `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. + - `chainType` is an object containing the type of the chain. This information can be used by tools to display additional information to the user. This fields can be one of the following values: From 1dd9bb817ea21ef8bf3a677d4d062aefd36c59a3 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:19:06 +0200 Subject: [PATCH 07/25] chainSpec: Group optional fields Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index bb4da60..adefed5 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -14,8 +14,6 @@ The JSON object returned by this function has the following format: "id": "...", - "protocolId": "...", - "chainType": "Live" | "Local" | "Development" | { "Custom": "..." }, "bootnodes": [ @@ -26,6 +24,8 @@ The JSON object returned by this function has the following format: "stateRootHash": "0x...", }, + // Optional fields: + "telemetryEndpoints": [ { "address": "...", @@ -37,7 +37,9 @@ The JSON object returned by this function has the following format: "ss58Format": 0, "tokenDecimals": 0, "tokenSymbol": "...", - } + }, + + "protocolId": "..." } ``` @@ -45,8 +47,6 @@ The JSON object returned by this function has the following format: - `id` is a string containing the identifier of the chain. -- `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. - - `chainType` is an object containing the type of the chain. This information can be used by tools to display additional information to the user. This fields can be one of the following values: @@ -108,3 +108,5 @@ Each object has the following format: The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. + +- `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. From 3ab3a3d8336e6e30dde8106da1ee929d979cb117 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:21:14 +0200 Subject: [PATCH 08/25] chainSpec: Add forkId field Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index adefed5..85f8a1d 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -39,7 +39,9 @@ The JSON object returned by this function has the following format: "tokenSymbol": "...", }, - "protocolId": "..." + "protocolId": "...", + + "forkId": "...", } ``` @@ -104,9 +106,11 @@ Each object has the following format: The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. -- `properties` is an object containing the properties of the chain. +- `properties` is an _optional_ object containing the properties of the chain. The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. + +- `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. From b42dc4cc25a603810e167ee41769bc78ea9a2b30 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:24:22 +0200 Subject: [PATCH 09/25] chainSpec: Properties as required Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 85f8a1d..0f290de 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -24,6 +24,10 @@ The JSON object returned by this function has the following format: "stateRootHash": "0x...", }, + "properties": { + ... + }, + // Optional fields: "telemetryEndpoints": [ @@ -33,12 +37,6 @@ The JSON object returned by this function has the following format: } ], - "properties": { - "ss58Format": 0, - "tokenDecimals": 0, - "tokenSymbol": "...", - }, - "protocolId": "...", "forkId": "...", @@ -93,6 +91,13 @@ The servers are encouraged to provide at least one trusted bootnode. The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. + +- `properties` is a JSON object containing a key-value map of properties of the chain. + The following are examples of possible properties, although implementations are free to diverge from this list: + The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). + The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. + The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. + - `telemetryEndpoints` is an _optional_ array of objects containing the telemetry endpoints of the chain. Each object has the following format: @@ -106,11 +111,6 @@ Each object has the following format: The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. -- `properties` is an _optional_ object containing the properties of the chain. - The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). - The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. - The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. - - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. - `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. From a394a83eaf017826cc0a4dab5bea6c2f21cbf6e8 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:33:32 +0200 Subject: [PATCH 10/25] chainSpec: Add codeSubstitutes Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 0f290de..0a55ccd 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -30,6 +30,10 @@ The JSON object returned by this function has the following format: // Optional fields: + "codeSubstitutes": { + "...": "0x...", + }, + "telemetryEndpoints": [ { "address": "...", @@ -60,7 +64,7 @@ For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz To establish a connection to the chain at least one bootnode is needed. The servers are encouraged to provide at least one trusted bootnode. -- `genesis` is an object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. +- `genesis` is a JSON object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. - If `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: ```json @@ -71,7 +75,6 @@ The servers are encouraged to provide at least one trusted bootnode. ... }, } - ... } ``` @@ -91,13 +94,16 @@ The servers are encouraged to provide at least one trusted bootnode. The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. - - `properties` is a JSON object containing a key-value map of properties of the chain. The following are examples of possible properties, although implementations are free to diverge from this list: The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. +- `codeSubstitutes` is an _optional_ JSON object containing a key-value map of code substitutes of the chain. The key is an unsigned integer represented as string indicating the block number at which the code substitute is applied. The value is a hexadecimal-encoded string representing the wasm runtime code, which is normally found under `b:code:` key. +The given wasm runtime code is used to substitute the runtime code starting from the provided block number and until the spec-version of the chain changes. +A substitute should be used when runtime upgrades cannot fix an underlying issue. For example, when the runtime upgrade panics. + - `telemetryEndpoints` is an _optional_ array of objects containing the telemetry endpoints of the chain. Each object has the following format: From 013453d8de3328d53852ad05ee3972ff8abcb332 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 14:58:19 +0200 Subject: [PATCH 11/25] chainSpec: Add checkpoint with trusted blocks Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 0a55ccd..604c418 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -44,6 +44,15 @@ The JSON object returned by this function has the following format: "protocolId": "...", "forkId": "...", + + "checkpoint": { + "trustedBlocks": [ + { + "blockNumber": "...", + "blockHash": "0x...", + } + ] + } } ``` @@ -120,3 +129,18 @@ Each object has the following format: - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. - `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. + +- `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. +The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. + + ```json + "trustedBlocks": [ + { + "blockNumber": "...", + "blockHash": "0x...", + } + ] + ``` + + The `"blockNumber"` is an unsigned integer represented as string indicating the block number. + The `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. From 43e250b10bd5282eb26d54bb95c26f6e586ce941 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 15:03:02 +0200 Subject: [PATCH 12/25] chainSpec: Extend checkpoint with badBlocks Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 604c418..1415261 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -51,7 +51,10 @@ The JSON object returned by this function has the following format: "blockNumber": "...", "blockHash": "0x...", } - ] + ], + "badBlocks": [ + "0x...", + ], } } ``` @@ -142,5 +145,7 @@ The `"trustedBlocks"` field is an array of JSON objects representing the expecte ] ``` - The `"blockNumber"` is an unsigned integer represented as string indicating the block number. - The `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. + - The `"blockNumber"` is an unsigned integer represented as string indicating the block number. + - The `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. + +The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. From d9582ae847106ac5e10030441dbef5d2f0e8b2f2 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 15:15:39 +0200 Subject: [PATCH 13/25] chainSpec: Group protocolId and forkId under networkProperties Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 1415261..6c88280 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -41,9 +41,10 @@ The JSON object returned by this function has the following format: } ], - "protocolId": "...", - - "forkId": "...", + "networkProperties": { + "protocolId": "...", + "forkId": "...", + }, "checkpoint": { "trustedBlocks": [ @@ -126,12 +127,20 @@ Each object has the following format: } ``` - The `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. - The `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. + - `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. + - `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. -- `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. +- `networkProperties` is an _optional_ JSON object containing the network properties of the chain. The object has the following format: + + ```json + { + "protocolId": "...", + "forkId": "...", + } + ``` -- `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. + - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. + - `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. - `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. @@ -145,7 +154,7 @@ The `"trustedBlocks"` field is an array of JSON objects representing the expecte ] ``` - - The `"blockNumber"` is an unsigned integer represented as string indicating the block number. - - The `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. + - `"blockNumber"` is an unsigned integer represented as string indicating the block number. + - `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. -The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. + The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. From b22cc64b7237a8396f13653e487eab1b5225b0ba Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 17 Jan 2024 15:18:47 +0200 Subject: [PATCH 14/25] chainSpec: Add parachain field containing the old para_id and relay_chain Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 6c88280..b040d4b 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -46,6 +46,11 @@ The JSON object returned by this function has the following format: "forkId": "...", }, + "parachain": { + "id": 0, + "relayChain": "..." + }, + "checkpoint": { "trustedBlocks": [ { @@ -142,6 +147,18 @@ Each object has the following format: - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. - `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. +- `parachain` is an _optional_ JSON object containing the parachain information. This fields is present only if the client spec describes a parachain. The object has the following format: + + ```json + { + "id": 0, + "relayChain": "..." + } + ``` + + - `id` is an unsigned integer indicating the id of the parachain. + - `relayChain` is a string containing the identifier of the relay chain. + - `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. From 303d0046d414915e975ba649cf24dd74cc36dfed Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Thu, 18 Jan 2024 12:44:46 +0200 Subject: [PATCH 15/25] chainSpec: Rename method name Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index b040d4b..8ee833d 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -1,4 +1,4 @@ -# chainSpec_unstable_clientSpec +# chainSpec_unstable_spec **Parameters**: From aa2b37e35f78ca1652853d97ed096b44cc63bf93 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Tue, 23 Jul 2024 16:21:17 +0300 Subject: [PATCH 16/25] Add checkpoint fields Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 102 +++++++++++++++++++++++++++-- 1 file changed, 97 insertions(+), 5 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 8ee833d..95aa322 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -52,12 +52,17 @@ The JSON object returned by this function has the following format: }, "checkpoint": { + "chainInformation": { + ... + }, + "trustedBlocks": [ { "blockNumber": "...", "blockHash": "0x...", } ], + "badBlocks": [ "0x...", ], @@ -159,8 +164,95 @@ Each object has the following format: - `id` is an unsigned integer indicating the id of the parachain. - `relayChain` is a string containing the identifier of the relay chain. -- `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. -The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. +- `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. + - The `"chainInformation"` field is a JSON object. This object has the following format: + + ```json + { + "finalized_block_header": "0x...", + + "consensus": { + "consensusType": "Aura" | "Babe" | "AllAuthorized", + + "aura": { + "authorities": [ + { + "publicKey": "0x...", + }, + ], + + "slot_duration": 0, + }, + + "babe": { + "slotPerEpoch": 0, + + "finalizedCurrentEpoch": { + "epochIndex": 0, + "startSlotNumber": 0, + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, + }, + ], + "randomness": "0x...", + "constant": { + "numerator": 0, + "denominator": 0, + }, + "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", + }, + + "finalizedNextEpoch": { + "epochIndex": 0, + "startSlotNumber": 0, + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, + }, + ], + "randomness": "0x...", + "constant": { + "numerator": 0, + "denominator": 0, + }, + "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", + } + } + + }, + + "finality": { + "finalityType": "Grandpa" | "Outsourced", + + "grandpa": { + "authoritiesSetId": 0, + + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, + }, + ], + + "scheduledChange": { + "delay": 0, + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, + }, + ], + }, + } + } + } + ``` + + + - The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. ```json "trustedBlocks": [ @@ -171,7 +263,7 @@ The `"trustedBlocks"` field is an array of JSON objects representing the expecte ] ``` - - `"blockNumber"` is an unsigned integer represented as string indicating the block number. - - `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. + - `"blockNumber"` is an unsigned integer represented as string indicating the block number. + - `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. - The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. + - The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. From 62ce3aee477e674c164097a97ecc2ae3907ecf15 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:08:24 +0300 Subject: [PATCH 17/25] chainSpec: Spec out babe, aura and grandpa Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 221 +++++++++++++++++++++-------- 1 file changed, 158 insertions(+), 63 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 95aa322..56bd181 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -70,9 +70,15 @@ The JSON object returned by this function has the following format: } ``` -- `name` is a string containing the name of the chain, identical to the result of `chainSpec_v1_chainName`. +## Parameters -- `id` is a string containing the identifier of the chain. +### Name + +The `name` is a string containing the name of the chain, identical to the result of `chainSpec_v1_chainName`. + +### Id + +The `id` is a string containing the identifier of the chain. - `chainType` is an object containing the type of the chain. This information can be used by tools to display additional information to the user. @@ -164,92 +170,181 @@ Each object has the following format: - `id` is an unsigned integer indicating the id of the parachain. - `relayChain` is a string containing the identifier of the relay chain. -- `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize the client with the head of the chain. - - The `"chainInformation"` field is a JSON object. This object has the following format: +### Checkpoint - ```json - { - "finalized_block_header": "0x...", +The `checkpoint` is an _optional_ JSON object containing the checkpoint of the chain. This information could be used to synchronize to with the head of the chain. + +#### ChainInformation + +The `"chainInformation"` field is a JSON object. This object has the following format: + +```json +{ + "finalized_block_header": "0x...", - "consensus": { - "consensusType": "Aura" | "Babe" | "AllAuthorized", + "consensus": { + "consensusType": "Aura" | "Babe" | "AllAuthorized", - "aura": { + "aura": { + "authorities": [ + { + "publicKey": "0x...", + }, + ], + + "slot_duration": 0, + }, + + "babe": { + "slotPerEpoch": 0, + + "finalizedCurrentEpoch": { + "epochIndex": 0, + "startSlotNumber": 0, "authorities": [ { "publicKey": "0x...", + "weight": 0, }, ], - - "slot_duration": 0, + "randomness": "0x...", + "constant": { + "numerator": 0, + "denominator": 0, + }, + "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", }, - "babe": { - "slotPerEpoch": 0, - - "finalizedCurrentEpoch": { - "epochIndex": 0, - "startSlotNumber": 0, - "authorities": [ - { - "publicKey": "0x...", - "weight": 0, - }, - ], - "randomness": "0x...", - "constant": { - "numerator": 0, - "denominator": 0, + "finalizedNextEpoch": { + "epochIndex": 0, + "startSlotNumber": 0, + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, }, - "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", + ], + "randomness": "0x...", + "constant": { + "numerator": 0, + "denominator": 0, }, - - "finalizedNextEpoch": { - "epochIndex": 0, - "startSlotNumber": 0, - "authorities": [ - { - "publicKey": "0x...", - "weight": 0, - }, - ], - "randomness": "0x...", - "constant": { - "numerator": 0, - "denominator": 0, - }, - "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", - } + "allowedSlots": "PrimarySlots" | "PrimaryAndSecondaryPlainSlots" | "PrimaryAndSecondaryVRFSlots", } - }, + }, + + "finality": { + "finalityType": "Grandpa" | "Outsourced", - "finality": { - "finalityType": "Grandpa" | "Outsourced", + "grandpa": { + "authoritiesSetId": 0, - "grandpa": { - "authoritiesSetId": 0, + "authorities": [ + { + "publicKey": "0x...", + "weight": 0, + }, + ], + "scheduledChange": { + "delay": 0, "authorities": [ { "publicKey": "0x...", "weight": 0, }, ], - - "scheduledChange": { - "delay": 0, - "authorities": [ - { - "publicKey": "0x...", - "weight": 0, - }, - ], - }, - } + }, } } - ``` +} +``` + +- `finalized_block_header` is a hexadecimal-encoded string representing the hash of highest known finalized block. + +- `consensus` is an _optional_ JSON object containing the consensus information of the chain. + If the chain does not have a consensus algorithm, this field is not present. + This object has the following format: + + - `consensusType` is a string indicating the consensus algorithm used by the chain. + This field can be one of the following values: + + - `"Aura"`: A string indicating the chain uses the Aura consensus algorithm. + - `"Babe"`: A string indicating the chain uses the Babe consensus algorithm. + - `"AllAuthorized"`: A string indicating the any node of the chain is allowed to produce blocks. + The user is encourage to limit, through other means, the number of blocks that being accepted. + + - `aura` is an _optional_ JSON object containing the Aura consensus information of the chain. + This field is only present if the `consensusType` is `"Aura"`. + This object has the following format: + + - `authorities` is an array of JSON objects representing the list of authorities that must validate children of the block referred to by `finalized_block_header`. + Each object has the following format: + - `publicKey` is a hexadecimal-encoded string representing the Sr25519 public key of the authority. + - `slot_duration` is an unsigned integer indicating the slot duration of the chain in milliseconds. + + - `babe` is an _optional_ JSON object containing the Babe consensus information of the chain. + This field is only present if the `consensusType` is `"Babe"`. + This object has the following format: + + - `slotPerEpoch` is an unsigned integer indicating the number of slots per epoch. + This field is configured at the genesis block and is constant for the lifetime of the chain. + - `finalizedCurrentEpoch` is an _optional_ JSON object the information about the epoch the finalized block belongs to. + This field is not present if and only if the finalized block is the first block of the chain. + Epoch number zero starts at the block number one. + This object has the following format: + - `epochIndex` is an unsigned integer indicating the index of the epoch. + The epoch index is zero-based and is incremented by one for each new epoch. + - `startSlotNumber` is an _optional_ unsigned integer indicating the slot at which the epoch starts. + This field is not present if and only if the `epochIndex` is zero. + - `authorities` is an array of JSON objects representing the authorities of the chain that are allowed to author blocks during this epoch. + Each object has the following format: + - `publicKey` is a hexadecimal-encoded string representing the Sr25519 public key of the authority. + - `weight` is an unsigned integer indicating the weight of the authority. + - `randomness` is a hexadecimal-encoded string representing the randomness of the epoch. + This value is determined using the VRF output of the validators of the previous epoch. + - `constant` is a JSON object containing the constant information of the epoch. + The constant represents a fraction, where the numerator is always inferior or equal to the denominator. + This object has the following format: + - `numerator` is an unsigned integer indicating the numerator of the constant. + - `denominator` is an unsigned integer indicating the denominator of the constant. + - `allowedSlots` is a string indicating the allowed slots of the epoch. + This field can be one of the following values: + - `"PrimarySlots"`: A string indicating the primary slots are allowed. + - `"PrimaryAndSecondaryPlainSlots"`: A string indicating the primary and secondary plain slots are allowed. + - `"PrimaryAndSecondaryVRFSlots"`: A string indicating the primary and secondary VRF slots are allowed. + - `finalizedNextEpoch` is a JSON object containing the information about the next epoch. + This object has the same format as the `finalizedCurrentEpoch` object. + +- `finality` is an _optional_ JSON object containing the finality information of the chain. + If the chain does not have a finality algorithm, this field is not present. + This object has the following format: + + - `finalityType` is a string indicating the finality algorithm used by the chain. + This field can be one of the following values: + + - `"Grandpa"`: A string indicating the chain uses the Grandpa finality algorithm. + - `"Outsourced"`: A string indicating the chain uses the outsourced finality algorithm. + + - `grandpa` is an _optional_ JSON object containing the Grandpa finality information of the chain. + This field is only present if the `finalityType` is `"Grandpa"`. + This object has the following format: + + - `authoritiesSetId` is an unsigned integer indicating the id of the authorities set of the block right after the finalized block. + - `authorities` is an array of JSON objects representing the authorities of the chain that are allowed to finalize blocks right after the finalized block. + Each object has the following format: + - `publicKey` is a hexadecimal-encoded string representing the Sr25519 public key of the authority. + - `weight` is an unsigned integer indicating the weight of the authority. + - `scheduledChange` is an _optional_ JSON object containing the information about the scheduled change of the authorities. + This field is not present if and only if the authorities set is not scheduled to change. + The block whose height is containing this field is still finalized using the authorities found in the above `authorities` field. + This object has the following format: + - `delay` is an unsigned integer indicating the delay in blocks before the authorities set is changed. + - `authorities` is an array of JSON objects representing the new authorities set. + Each object has the following format: + - `publicKey` is a hexadecimal-encoded string representing the Sr25519 public key of the authority. + - `weight` is an unsigned integer indicating the weight of the authority. - The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. From 7baed6c7455f72bae5ce8e6f4fd89f2663f17a01 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:22:57 +0300 Subject: [PATCH 18/25] chainSpec: Format document Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 153 ++++++++++++++++------------- 1 file changed, 85 insertions(+), 68 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 56bd181..2419295 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -88,87 +88,100 @@ This fields can be one of the following values: - `"Development"`: A string indicating the chain is a development chain that runs mainly on one node. - `{ "Custom": "..." }`: A JSON object indicating the chain is a custom chain. The value of the `"Custom"` field is a string. -- `bootnodes` is an array of strings containing the [multi adresss format](https://github.com/multiformats/multiaddr) of the bootnodes of the chain. +### Bootnodes + +The `bootnodes` is an array of strings containing the [multi adresss format](https://github.com/multiformats/multiaddr) of the bootnodes of the chain. For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU"` is a valid p2p multiaddr, where `12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU` represents the peer ID of the bootnode. To establish a connection to the chain at least one bootnode is needed. The servers are encouraged to provide at least one trusted bootnode. -- `genesis` is a JSON object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. - - If `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: +### Genesis - ```json - { - "raw": { - "top": { - "0x..": "0x..", - ... - }, - } +The `genesis` is a JSON object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. + +When `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: + +```json +{ + "raw": { + "top": { + "0x..": "0x..", + ... + }, } - ``` +} +``` - The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. - Both the keys and the values are hexadecimal-encoded strings. - The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. - For example, the wasm code of the runtime is stored under the key `b":code"`. +The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. +Both the keys and the values are hexadecimal-encoded strings. +The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. +For example, the wasm code of the runtime is stored under the key `b":code"`. - - If `rawGenesis` is `false`, then the `genesis` field is a JSON object containing the Merkle value of the genesis block. - The object has the following format: +When `rawGenesis` is `false`, then the `genesis` field is a JSON object containing the Merkle value of the genesis block. +The object has the following format: - ```json - { - "stateRootHash": "0x...", - } - ``` +```json +{ + "stateRootHash": "0x...", +} +``` - The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. +The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. -- `properties` is a JSON object containing a key-value map of properties of the chain. - The following are examples of possible properties, although implementations are free to diverge from this list: - The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). - The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. - The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. +### Properties -- `codeSubstitutes` is an _optional_ JSON object containing a key-value map of code substitutes of the chain. The key is an unsigned integer represented as string indicating the block number at which the code substitute is applied. The value is a hexadecimal-encoded string representing the wasm runtime code, which is normally found under `b:code:` key. +The `properties` is a JSON object containing a key-value map of properties of the chain. +The following are examples of possible properties, although implementations are free to diverge from this list: +The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). +The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. +The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. + +### Code Substitues + +The `codeSubstitutes` is an _optional_ JSON object containing a key-value map of code substitutes of the chain. The key is an unsigned integer represented as string indicating the block number at which the code substitute is applied. The value is a hexadecimal-encoded string representing the wasm runtime code, which is normally found under `b:code:` key. The given wasm runtime code is used to substitute the runtime code starting from the provided block number and until the spec-version of the chain changes. A substitute should be used when runtime upgrades cannot fix an underlying issue. For example, when the runtime upgrade panics. -- `telemetryEndpoints` is an _optional_ array of objects containing the telemetry endpoints of the chain. +### Telemetry Endpoints + +The `telemetryEndpoints` is an _optional_ array of objects containing the telemetry endpoints of the chain. Each object has the following format: - ```json - { - "address": "...", - "verbosity_level": 0, - } - ``` +```json +{ + "address": "...", + "verbosity_level": 0, +} +``` - - `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. - - `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. +- `"address"` is a string containing the address of the telemetry server. The address can be specified in the URL format, or in the multi address format. +- `"verbosity_level"` is an unsigned integer indicating the verbosity level of the telemetry server. The verbosity ranges from 0 to 9, where 0 is the least verbose and 9 is the most verbose. -- `networkProperties` is an _optional_ JSON object containing the network properties of the chain. The object has the following format: +### Network Properties - ```json - { - "protocolId": "...", - "forkId": "...", - } - ``` +The `networkProperties` is an _optional_ JSON object containing the network properties of the chain. The object has the following format: + +```json +{ + "forkId": "...", +} +``` - - `protocolId` is an _optional_ string containing the network protocol id that identifies the chain. - - `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. +- `forkId` is an _optional_ string containing the fork id that identifies the chain. In the case where two chains have the same genesis, this field can be used to signal a fork on the networking level. + +### Parachain - `parachain` is an _optional_ JSON object containing the parachain information. This fields is present only if the client spec describes a parachain. The object has the following format: - ```json - { - "id": 0, - "relayChain": "..." - } - ``` +```json +{ + "id": 0, + "relayChain": "..." +} +``` - - `id` is an unsigned integer indicating the id of the parachain. - - `relayChain` is a string containing the identifier of the relay chain. +- `id` is an unsigned integer indicating the id of the parachain. +- `relayChain` is a string containing the identifier of the relay chain. ### Checkpoint @@ -346,19 +359,23 @@ The `"chainInformation"` field is a JSON object. This object has the following f - `publicKey` is a hexadecimal-encoded string representing the Sr25519 public key of the authority. - `weight` is an unsigned integer indicating the weight of the authority. +#### Trusted Blocks - - The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. +The `"trustedBlocks"` field is an array of JSON objects representing the expected hashes of blocks at given heights. +This can be used to set trusted checkpoints. The client should refuse to import blocks with a different hash at the given height. - ```json - "trustedBlocks": [ - { - "blockNumber": "...", - "blockHash": "0x...", - } - ] - ``` +```json + "trustedBlocks": [ + { + "blockNumber": "...", + "blockHash": "0x...", + } + ] +``` + +- `"blockNumber"` is an unsigned integer represented as string indicating the block number. +- `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. - - `"blockNumber"` is an unsigned integer represented as string indicating the block number. - - `"blockHash"` is a hexadecimal-encoded string representing the hash of the block at the given height. +#### Bad Blocks - - The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. +The `"badBlocks"` field is an array of hexadecimal-encoded strings representing the hashes of blocks that should be considered invalid. These hashes represent known and unwanted blocks on forks that have been pruned. From a72d250b52e99ee05851a390ddc989e7675caac1 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:25:26 +0300 Subject: [PATCH 19/25] chainSpec: Remove chainType Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 2419295..ddbcd5f 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -14,8 +14,6 @@ The JSON object returned by this function has the following format: "id": "...", - "chainType": "Live" | "Local" | "Development" | { "Custom": "..." }, - "bootnodes": [ "...", ], @@ -80,14 +78,6 @@ The `name` is a string containing the name of the chain, identical to the result The `id` is a string containing the identifier of the chain. -- `chainType` is an object containing the type of the chain. -This information can be used by tools to display additional information to the user. -This fields can be one of the following values: - - `"Live"`: A string indicating the chain is a live chain. - - `"Local"`: A string indicating the chain is a local chain that runs on multiple nodes for testing purposes. - - `"Development"`: A string indicating the chain is a development chain that runs mainly on one node. - - `{ "Custom": "..." }`: A JSON object indicating the chain is a custom chain. The value of the `"Custom"` field is a string. - ### Bootnodes The `bootnodes` is an array of strings containing the [multi adresss format](https://github.com/multiformats/multiaddr) of the bootnodes of the chain. From 5b19be4b562c4aa43291a8980fc0d2c8011204b4 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:30:40 +0300 Subject: [PATCH 20/25] chainSpec: Remove properties object Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index ddbcd5f..adc18ef 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -22,16 +22,12 @@ The JSON object returned by this function has the following format: "stateRootHash": "0x...", }, - "properties": { - ... - }, - - // Optional fields: - + // Optional "codeSubstitutes": { "...": "0x...", }, + // Optional "telemetryEndpoints": [ { "address": "...", @@ -39,16 +35,18 @@ The JSON object returned by this function has the following format: } ], + // Optional "networkProperties": { "protocolId": "...", "forkId": "...", }, + // Optional "parachain": { "id": 0, - "relayChain": "..." }, + // Optional "checkpoint": { "chainInformation": { ... @@ -83,7 +81,6 @@ The `id` is a string containing the identifier of the chain. The `bootnodes` is an array of strings containing the [multi adresss format](https://github.com/multiformats/multiaddr) of the bootnodes of the chain. For example, the `"/dns/polkadot-bootnode-0.polkadot.io/tcp/30333/p2p/12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU"` is a valid p2p multiaddr, where `12D3KooWSz8r2WyCdsfWHgPyvD8GKQdJ1UAiRmrcrs8sQB3fe2KU` represents the peer ID of the bootnode. To establish a connection to the chain at least one bootnode is needed. -The servers are encouraged to provide at least one trusted bootnode. ### Genesis @@ -118,14 +115,6 @@ The object has the following format: The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. -### Properties - -The `properties` is a JSON object containing a key-value map of properties of the chain. -The following are examples of possible properties, although implementations are free to diverge from this list: -The `"ss58Format"` field is an unsigned integer indicating the designated SS58 prefix of the addresses of the chain. For more details see [Polkadot Accounts In-Depth](https://wiki.polkadot.network/docs/learn-account-advanced). -The `"tokenDecimals` field is an unsigned integer indicating the number of decimals of the native token of the chain. -The `"tokenSymbol"` field is a string containing the symbol of the native token of the chain. - ### Code Substitues The `codeSubstitutes` is an _optional_ JSON object containing a key-value map of code substitutes of the chain. The key is an unsigned integer represented as string indicating the block number at which the code substitute is applied. The value is a hexadecimal-encoded string representing the wasm runtime code, which is normally found under `b:code:` key. From 303083aabeb59cf5fa2600c0e4a2f1b5d5325eb1 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:31:47 +0300 Subject: [PATCH 21/25] chainSpec: Remove name field Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index adc18ef..5c67e4a 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -10,8 +10,6 @@ The JSON object returned by this function has the following format: ```json { - "name": "...", - "id": "...", "bootnodes": [ @@ -68,10 +66,6 @@ The JSON object returned by this function has the following format: ## Parameters -### Name - -The `name` is a string containing the name of the chain, identical to the result of `chainSpec_v1_chainName`. - ### Id The `id` is a string containing the identifier of the chain. From 67d662822dd1393faa410d089078e4287d6cb962 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:39:15 +0300 Subject: [PATCH 22/25] chainSpec: Remove rawGenesis param Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 5c67e4a..8dc276e 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -1,8 +1,6 @@ # chainSpec_unstable_spec -**Parameters**: - -- `rawGenesis`: A boolean indicating whether the genesis block should be returned in raw format or not. +**Parameters**: *none* **Return value**: A JSON object. @@ -17,6 +15,9 @@ The JSON object returned by this function has the following format: ], "genesis": { + "raw": { + .. + }, "stateRootHash": "0x...", }, @@ -64,7 +65,7 @@ The JSON object returned by this function has the following format: } ``` -## Parameters +## Description ### Id @@ -78,9 +79,9 @@ To establish a connection to the chain at least one bootnode is needed. ### Genesis -The `genesis` is a JSON object containing the genesis storage of the chain. This field has the following formats, depending on the provided `rawGenesis` parameter. +The `genesis` is a JSON object containing the genesis storage of the chain. This field has the following formats, depending on the information available to the node. -When `rawGenesis` is `true`, then the `genesis` field is a JSON object containing the raw genesis storage of the chain. The object has the following format: +#### Raw Format ```json { @@ -93,13 +94,11 @@ When `rawGenesis` is `true`, then the `genesis` field is a JSON object containin } ``` -The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. -Both the keys and the values are hexadecimal-encoded strings. -The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. -For example, the wasm code of the runtime is stored under the key `b":code"`. +This format is used when the node has access to the raw genesis storage and chooses to provide it. +The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. Both the keys and the values are hexadecimal-encoded strings. +The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. For example, the wasm code of the runtime is stored under the key `b":code"`. -When `rawGenesis` is `false`, then the `genesis` field is a JSON object containing the Merkle value of the genesis block. -The object has the following format: +#### State Root Hash ```json { @@ -107,6 +106,7 @@ The object has the following format: } ``` +This format is used when the node does not have access to the raw genesis storage, or chooses to provide only the state root hash. The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. ### Code Substitues From 27c7ecc2b932f132ab8b620ea12f65111d9c4b8b Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:42:42 +0300 Subject: [PATCH 23/25] chainSpec: Clarify genesis formats Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index 8dc276e..f0332a3 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -95,7 +95,8 @@ The `genesis` is a JSON object containing the genesis storage of the chain. This ``` This format is used when the node has access to the raw genesis storage and chooses to provide it. -The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. Both the keys and the values are hexadecimal-encoded strings. +If the node has provided a different format, the raw genesis storage can be reconstructed by iterating over the storage entries of the genesis block using the `archive` methods if available. +The `"top"` field contains a map of keys to values for the top-level storage entries of the genesis. Both the keys and the values are hexadecimal-encoded strings. The provided keys are guaranteed to be unique and to not be a default storage child key. A default storage child key is a key that is prefixed with `b":child_storage:default:"`. For example, the wasm code of the runtime is stored under the key `b":code"`. #### State Root Hash @@ -107,6 +108,7 @@ The provided keys are guaranteed to be unique and to not be a default storage ch ``` This format is used when the node does not have access to the raw genesis storage, or chooses to provide only the state root hash. +If the node has provided a different format, the state root hash can be reconstructed by calculating the Merkle root of the genesis storage entries, or by directly fetching the Merkle value of the genesis block using the `archive` methods if available. The `"stateRootHash"` contains a hexadecimal-encoded string representing the Merkle value of the genesis block. ### Code Substitues From 5b4aa997c958bfbed43889dec186cbcf8495f6a1 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:43:29 +0300 Subject: [PATCH 24/25] chainSpec: Remove parachain::relay_chain Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index f0332a3..cf6ad8c 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -151,12 +151,10 @@ The `networkProperties` is an _optional_ JSON object containing the network prop ```json { "id": 0, - "relayChain": "..." } ``` - `id` is an unsigned integer indicating the id of the parachain. -- `relayChain` is a string containing the identifier of the relay chain. ### Checkpoint From c2b950cc7f33c5d25df44c136f7d03af4f78c383 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 24 Jul 2024 18:46:48 +0300 Subject: [PATCH 25/25] chainSpec: Remove protocolID Signed-off-by: Alexandru Vasile --- src/api/chainSpec_unstable_spec.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/api/chainSpec_unstable_spec.md b/src/api/chainSpec_unstable_spec.md index cf6ad8c..89e4928 100644 --- a/src/api/chainSpec_unstable_spec.md +++ b/src/api/chainSpec_unstable_spec.md @@ -36,7 +36,6 @@ The JSON object returned by this function has the following format: // Optional "networkProperties": { - "protocolId": "...", "forkId": "...", },