Skip to content

Commit 76a6200

Browse files
0xLuccanhussein11eshaben
authored
Add custom keys in chainspec (#659)
* Add chainspec keys * Extract snippets * Update develop/parachains/deployment/generate-chain-specs.md Co-authored-by: Nicolás Hussein <[email protected]> * Fix llms.txt * Apply suggestions from code review Co-authored-by: Erin Shaben <[email protected]> * Fix llms.txt --------- Co-authored-by: Nicolás Hussein <[email protected]> Co-authored-by: Erin Shaben <[email protected]>
1 parent dcfb30d commit 76a6200

File tree

5 files changed

+165
-0
lines changed

5 files changed

+165
-0
lines changed

‎.snippets/code/develop/parachains/deployment/generate-chain-specs/invulnerables.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"collatorSelection": {
3+
"candidacyBond": 16000000000,
4+
"desiredCandidates": 0,
5+
"invulnerables": [
6+
"INSERT_ACCOUNT_ID_COLLATOR_1",
7+
"INSERT_ACCOUNT_ID_COLLATOR_2",
8+
"INSERT_ACCOUNT_ID_COLLATOR_3"
9+
]
10+
}
11+
}

‎.snippets/code/develop/parachains/deployment/generate-chain-specs/key.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<div id="termynal" data-termynal>
2+
<span data-ty="input"><span class="file-path"></span>docker run -it parity/subkey:latest generate --scheme sr25519</span>
3+
<span> <br />Secret phrase: lemon play remain picture leopard frog mad bridge hire hazard best buddy <br />Network ID: substrate <br />Secret seed: 0xb748b501de061bae1fcab1c0b814255979d74d9637b84e06414a57a1a149c004 <br />Public key (hex): 0xf4ec62ec6e70a3c0f8dcbe0531e2b1b8916cf16d30635bbe9232f6ed3f0bf422 <br />Account ID: 0xf4ec62ec6e70a3c0f8dcbe0531e2b1b8916cf16d30635bbe9232f6ed3f0bf422 <br />Public key (SS58): 5HbqmBBJ5ALUzho7tw1k1jEgKBJM7dNsQwrtfSfUskT1a3oe <br />SS58 Address: 5HbqmBBJ5ALUzho7tw1k1jEgKBJM7dNsQwrtfSfUskT1a3oe </span>
4+
</div>

‎.snippets/code/develop/parachains/deployment/generate-chain-specs/session-keys.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"session": {
3+
"keys": [
4+
[
5+
"INSERT_ACCOUNT_ID_COLLATOR_1",
6+
"INSERT_ACCOUNT_ID_COLLATOR_1",
7+
{
8+
"aura": "INSERT_SESSION_KEY_COLLATOR_1"
9+
}
10+
],
11+
[
12+
"INSERT_ACCOUNT_ID_COLLATOR_2",
13+
"INSERT_ACCOUNT_ID_COLLATOR_2",
14+
{
15+
"aura": "INSERT_SESSION_KEY_COLLATOR_2"
16+
}
17+
],
18+
[
19+
"INSERT_ACCOUNT_ID_COLLATOR_3",
20+
"INSERT_ACCOUNT_ID_COLLATOR_3",
21+
{
22+
"aura": "INSERT_SESSION_KEY_COLLATOR_3"
23+
}
24+
]
25+
],
26+
"nonAuthorityKeys": []
27+
}
28+
}

‎develop/parachains/deployment/generate-chain-specs.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,50 @@ After the conversion to the raw format, the `sudo key` snippet looks like this:
124124

125125
The raw chain specification can be used to initialize the genesis storage for a node.
126126

127+
## Generate Custom Keys for Your Collator
128+
129+
To securely deploy your parachain, you must generate custom cryptographic keys for your collators (block producers). Each collator requires two distinct sets of keys with different security requirements and operational purposes.
130+
131+
- **Account keys**: Serve as the primary identity and financial controller for your collator. These keys are used to interact with the network and manage funds. They should be treated as cold storage and must never exist on the filesystem of the collator node. Secure offline backup is essential.
132+
133+
- **Session keys**: Handle block production operations to identify your node and sign blocks on the network. These keys are stored in the parachain keystore and function as operational "hot wallet" keys. If compromised, an attacker could impersonate your node, potentially resulting in slashing of your funds. To minimize these risks, implement regular session key rotation and treat them with the same caution as hot wallet keys.
134+
135+
To perform this step, you can use [Subkey](https://docs.rs/crate/subkey/latest){target=\_blank}, a command-line tool for generating and managing keys:
136+
137+
```bash
138+
docker run -it parity/subkey:latest generate --scheme sr25519
139+
```
140+
141+
The output should look similar to the following:
142+
143+
--8<-- 'code/develop/parachains/deployment/generate-chain-specs/key.html'
144+
145+
Ensure that this command is executed twice to generate the keys for both the account and session keys. Save them for future reference.
146+
147+
After generating the plain chain specification, you need to edit this file by inserting the account IDs and session keys in SS58 format generated for your collators in the `collatorSelection.invulnerables` and `session.keys` fields.
148+
149+
### Add Invulnerables
150+
151+
In the `collatorSelection.invulnerables` array, add the SS58 addresses (account keys) of your collators. These addresses will be automatically included in the active collator set:
152+
153+
```json
154+
--8<-- 'code/develop/parachains/deployment/generate-chain-specs/invulnerables.json:2:10'
155+
```
156+
157+
- **`candidacyBond`**: Minimum stake required for collator candidates (in Planck units).
158+
159+
- **`desiredCandidates`**: Number of candidates beyond invulnerables (set to 0 for invulnerables-only).
160+
161+
- **`invulnerables`**: Use the SS58 addresses from your generated account keys as collators.
162+
163+
### Add Session Keys
164+
165+
For each invulnerable collator, add a corresponding entry in the `session.keys` array. This maps each collator's account ID to their session keys:
166+
167+
```json
168+
--8<-- 'code/develop/parachains/deployment/generate-chain-specs/session-keys.json:2:27'
169+
```
170+
127171
## Where to Go Next
128172

129173
After generating a chain specification, you can use it to initialize the genesis storage for a node. Refer to the following guides to learn how to proceed with the deployment of your blockchain:

‎llms.txt‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4440,6 +4440,84 @@ After the conversion to the raw format, the `sudo key` snippet looks like this:
44404440

44414441
The raw chain specification can be used to initialize the genesis storage for a node.
44424442

4443+
## Generate Custom Keys for Your Collator
4444+
4445+
To securely deploy your parachain, you must generate custom cryptographic keys for your collators (block producers). Each collator requires two distinct sets of keys with different security requirements and operational purposes.
4446+
4447+
- **Account keys**: Serve as the primary identity and financial controller for your collator. These keys are used to interact with the network and manage funds. They should be treated as cold storage and must never exist on the filesystem of the collator node. Secure offline backup is essential.
4448+
4449+
- **Session keys**: Handle block production operations to identify your node and sign blocks on the network. These keys are stored in the parachain keystore and function as operational "hot wallet" keys. If compromised, an attacker could impersonate your node, potentially resulting in slashing of your funds. To minimize these risks, implement regular session key rotation and treat them with the same caution as hot wallet keys.
4450+
4451+
To perform this step, you can use [Subkey](https://docs.rs/crate/subkey/latest){target=\_blank}, a command-line tool for generating and managing keys:
4452+
4453+
```bash
4454+
docker run -it parity/subkey:latest generate --scheme sr25519
4455+
```
4456+
4457+
The output should look similar to the following:
4458+
4459+
<div id="termynal" data-termynal>
4460+
<span data-ty="input"><span class="file-path"></span>docker run -it parity/subkey:latest generate --scheme sr25519</span>
4461+
<span> <br />Secret phrase: lemon play remain picture leopard frog mad bridge hire hazard best buddy <br />Network ID: substrate <br />Secret seed: 0xb748b501de061bae1fcab1c0b814255979d74d9637b84e06414a57a1a149c004 <br />Public key (hex): 0xf4ec62ec6e70a3c0f8dcbe0531e2b1b8916cf16d30635bbe9232f6ed3f0bf422 <br />Account ID: 0xf4ec62ec6e70a3c0f8dcbe0531e2b1b8916cf16d30635bbe9232f6ed3f0bf422 <br />Public key (SS58): 5HbqmBBJ5ALUzho7tw1k1jEgKBJM7dNsQwrtfSfUskT1a3oe <br />SS58 Address: 5HbqmBBJ5ALUzho7tw1k1jEgKBJM7dNsQwrtfSfUskT1a3oe </span>
4462+
</div>
4463+
4464+
Ensure that this command is executed twice to generate the keys for both the account and session keys. Save them for future reference.
4465+
4466+
After generating the plain chain specification, you need to edit this file by inserting the account IDs and session keys in SS58 format generated for your collators in the `collatorSelection.invulnerables` and `session.keys` fields.
4467+
4468+
### Add Invulnerables
4469+
4470+
In the `collatorSelection.invulnerables` array, add the SS58 addresses (account keys) of your collators. These addresses will be automatically included in the active collator set:
4471+
4472+
```json
4473+
"candidacyBond": 16000000000,
4474+
"desiredCandidates": 0,
4475+
"invulnerables": [
4476+
"INSERT_ACCOUNT_ID_COLLATOR_1",
4477+
"INSERT_ACCOUNT_ID_COLLATOR_2",
4478+
"INSERT_ACCOUNT_ID_COLLATOR_3"
4479+
]
4480+
}
4481+
```
4482+
4483+
- **`candidacyBond`**: Minimum stake required for collator candidates (in Planck units).
4484+
4485+
- **`desiredCandidates`**: Number of candidates beyond invulnerables (set to 0 for invulnerables-only).
4486+
4487+
- **`invulnerables`**: Use the SS58 addresses from your generated account keys as collators.
4488+
4489+
### Add Session Keys
4490+
4491+
For each invulnerable collator, add a corresponding entry in the `session.keys` array. This maps each collator's account ID to their session keys:
4492+
4493+
```json
4494+
"keys": [
4495+
[
4496+
"INSERT_ACCOUNT_ID_COLLATOR_1",
4497+
"INSERT_ACCOUNT_ID_COLLATOR_1",
4498+
{
4499+
"aura": "INSERT_SESSION_KEY_COLLATOR_1"
4500+
}
4501+
],
4502+
[
4503+
"INSERT_ACCOUNT_ID_COLLATOR_2",
4504+
"INSERT_ACCOUNT_ID_COLLATOR_2",
4505+
{
4506+
"aura": "INSERT_SESSION_KEY_COLLATOR_2"
4507+
}
4508+
],
4509+
[
4510+
"INSERT_ACCOUNT_ID_COLLATOR_3",
4511+
"INSERT_ACCOUNT_ID_COLLATOR_3",
4512+
{
4513+
"aura": "INSERT_SESSION_KEY_COLLATOR_3"
4514+
}
4515+
]
4516+
],
4517+
"nonAuthorityKeys": []
4518+
}
4519+
```
4520+
44434521
## Where to Go Next
44444522

44454523
After generating a chain specification, you can use it to initialize the genesis storage for a node. Refer to the following guides to learn how to proceed with the deployment of your blockchain:

0 commit comments

Comments
 (0)