Skip to content

Commit 590a01f

Browse files
newhoggynewhoggy
authored
Merge pull request #4767 from input-output-hk/create-cardano-doc
Docs for create-cardano
2 parents 7b731ab + 3c4f855 commit 590a01f

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎doc/reference/create-cardano.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Creating Cardano testnets
2+
3+
In [Shelley genesis](shelley-genesis.md) we discussed how to manually create a Shelley blockchain
4+
and how to create a testnet semi-automatically using the `cardano-cli genesis create` command. That explainer
5+
did not cover the steps needed to create a testnet that starts in the Byron era and is updated to the latest
6+
era. This process requires a fair amount of manual work: converting genesis and delegate keys from Byron to
7+
Shelley, creating genesis files, handling file hashing, manually updating the configuration file, etc.
8+
9+
Creating a testnet that starts in Byron and can transition to Shelley and later eras is possible with the
10+
`cardano-cli genesis create-cardano` command. Note that on mainnet, we need to use the manual method
11+
described in [Shelley genesis](shelley-genesis.md).
12+
13+
The `create-cardano` command automatically generates the Byron, Shelley and Alonzo genesis files, including
14+
the needed genesis keys, delegate keys, and UTXO keys. This command also handles all the hashing and
15+
generates the configuration file for the node.
16+
17+
The `create-cardano` command also requires us to provide template files for the node configuration file,
18+
Byron genesis, Shelley genesis and Alonzo genesis. These template files contain the parameters needed for
19+
the testnet, all eras, and the configuration file for the nodes. You can find template files in the
20+
[cardano-world repository](https://github.com/input-output-hk/cardano-world/tree/master/nix/cardano/environments/testnet-template)
21+
and adjust them to your needs.
22+
23+
By calling help for `create-cardano`, you will see the needed parameters:
24+
25+
```bash
26+
$ cardano-cli genesis create-cardano
27+
28+
--genesis-dir DIR The genesis directory containing the genesis template
29+
and required genesis/delegation/spending keys.
30+
--gen-genesis-keys INT The number of genesis keys to make [default is 3].
31+
--gen-utxo-keys INT The number of UTXO keys to create [default is 0].
32+
--start-time UTC-TIME The genesis start time in YYYY-MM-DDThh:mm:ssZ
33+
format. If unspecified, will be the current time +30
34+
seconds.
35+
--supply LOVELACE The initial coin supply in lovelace which will be
36+
evenly distributed across initial, non-delegating
37+
stake holders.
38+
--security-param INT Security parameter for the genesis file [default is 108].
39+
--slot-length INT Slot length (ms) parameter for genesis file [default
40+
is 1000].
41+
--slot-coefficient RATIONAL
42+
Slot coefficient for the genesis file [default is .05].
43+
--mainnet Use the mainnet magic ID.
44+
--testnet-magic NATURAL Specify a testnet magic ID.
45+
--byron-template FILEPATH
46+
JSON file with genesis defaults for each Byron.
47+
--shelley-template FILEPATH
48+
JSON file with genesis defaults for each Shelley.
49+
--alonzo-template FILEPATH
50+
JSON file with genesis defaults for each Alonzo.
51+
--node-config-template FILEPATH
52+
The node config template
53+
54+
```
55+
56+
There are also a few things to consider:
57+
58+
* The _maximum supply_ is hardcoded to 45 billion ada (like on mainnet). The amount in `--supply` is distributed evenly across initial UTXO keys. The difference between 45 billion and `--supply` will be available on the _Reserves_ when updating to the Shelley era.
59+
60+
* `--slot-length`, `--security-param` and `--slot-coefficient` together determine the epoch length on the resulting network. Byron epochs last _10k_ slots, and Shelley epochs last _10k/f_ slots. Where _k_ is the security parameter and _f_ is the slot coefficient.
61+
62+
### Example
63+
64+
For a network with three genesis keys, three delegate nodes, two non-delegated UTXO keys with five billion each and 10 minutes epochs, run:
65+
66+
```bash
67+
$ cardano-cli genesis create-cardano \
68+
--genesis-dir cluster \
69+
--gen-genesis-keys 3 \
70+
--gen-utxo-keys 2 \
71+
--supply 10000000000000000 \
72+
--security-param 300 \
73+
--slot-length 100 \
74+
--slot-coefficient 5/100 \
75+
--testnet-magic 42 \
76+
--byron-template byron.json \
77+
--shelley-template shelley.json \
78+
--alonzo-template alonzo.json \
79+
--node-config-template config.json
80+
```
81+
82+
This creates the following:
83+
84+
* The 'cluster' directory
85+
* Byron, Shelley and Alonzo genesis files
86+
* The node configuration file
87+
* Three Byron era genesis keys
88+
* Three Shelley era genesis keys (converted from Byron keys)
89+
* Three delegate Byron keys
90+
* Three delegation certificates
91+
* Three operational certificates and operational certificate counters
92+
* Three cold, KES, and VRF keys
93+
* Two Byron era non-delegated UTXO keys
94+
* Two Shelley era UTXO keys (converted from Byron keys)
95+
96+
```bash
97+
$ tree cluster/
98+
cluster/
99+
├── alonzo-genesis.json
100+
├── byron-genesis.json
101+
├── delegate-keys
102+
│ ├── byron.000.cert.json
103+
│ ├── byron.000.key
104+
│ ├── byron.001.cert.json
105+
│ ├── byron.001.key
106+
│ ├── byron.002.cert.json
107+
│ ├── byron.002.key
108+
│ ├── shelley.000.counter.json
109+
│ ├── shelley.000.kes.skey
110+
│ ├── shelley.000.kes.vkey
111+
│ ├── shelley.000.opcert.json
112+
│ ├── shelley.000.skey
113+
│ ├── shelley.000.vkey
114+
│ ├── shelley.000.vrf.skey
115+
│ ├── shelley.000.vrf.vkey
116+
│ ├── shelley.001.counter.json
117+
│ ├── shelley.001.kes.skey
118+
│ ├── shelley.001.kes.vkey
119+
│ ├── shelley.001.opcert.json
120+
│ ├── shelley.001.skey
121+
│ ├── shelley.001.vkey
122+
│ ├── shelley.001.vrf.skey
123+
│ ├── shelley.001.vrf.vkey
124+
│ ├── shelley.002.counter.json
125+
│ ├── shelley.002.kes.skey
126+
│ ├── shelley.002.kes.vkey
127+
│ ├── shelley.002.opcert.json
128+
│ ├── shelley.002.skey
129+
│ ├── shelley.002.vkey
130+
│ ├── shelley.002.vrf.skey
131+
│ └── shelley.002.vrf.vkey
132+
├── genesis-keys
133+
│ ├── byron.000.key
134+
│ ├── byron.001.key
135+
│ ├── byron.002.key
136+
│ ├── shelley.000.skey
137+
│ ├── shelley.000.vkey
138+
│ ├── shelley.001.skey
139+
│ ├── shelley.001.vkey
140+
│ ├── shelley.002.skey
141+
│ └── shelley.002.vkey
142+
├── node-config.json
143+
├── shelley-genesis.json
144+
└── utxo-keys
145+
├── byron.000.key
146+
├── byron.001.key
147+
├── shelley.000.skey
148+
├── shelley.000.vkey
149+
├── shelley.001.skey
150+
└── shelley.001.vkey
151+
152+
4 directories, 53 files
153+
```
154+
155+
Starting the cluster requires topology files for each of the nodes. For example:
156+
157+
```JSON
158+
{
159+
"Producers": [
160+
{
161+
"addr": "127.0.0.1",
162+
"port": 3001,
163+
"valency": 1
164+
},
165+
{
166+
"addr": "127.0.0.1",
167+
"port": 3002,
168+
"valency": 1
169+
}
170+
]
171+
}
172+
```
173+
Note: For details about topology files please refer to [Understanding configuration files](../getting-started/understanding-config-files.md).
174+
175+
176+
Then, run the nodes with block production keys, for example:
177+
178+
```bash
179+
$ cardano-node run \
180+
--config node-config.json \
181+
--topology topology.json \
182+
--database-path db \
183+
--socket-path node.socket \
184+
--port 3000 \
185+
--delegation-certificate delegate-keys/byron.000.cert.json \
186+
--signing-key delegate-keys/byron.000.key
187+
```
188+
189+
Updating the testnet to later eras can be done using update proposals, please refer to [Cardano governance](./cardano-governance.md) to learn how to do it.

0 commit comments

Comments
 (0)