Skip to content

Commit b073bd4

Browse files
jpraynaudjpraynaud
committed
Update README
Add mithril infra scripts documentation and fast genesis process
1 parent f839c09 commit b073bd4

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎mithril-infra/README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,3 +92,160 @@ The commands to run when bootstrapping is:
9292
```bash
9393
docker exec mithril-aggregator /app/bin/mithril-aggregator -vvv genesis bootstrap
9494
```
95+
96+
## Tools
97+
98+
The Mithril infrastructure comes with some scripts that help handle common tasks.
99+
100+
### Utils
101+
102+
This script is mainly used by the GitHub Actions workflows in the terraform deployments.
103+
104+
| Script | Description | Usage |
105+
|--------|-------------|-------|
106+
| `google-credentials-public-key.sh` | Extract a public key from a GCP credentials file and adds it to an authorized `ssh_keys` file for a specific user. | `./google-credentials-public-key.sh credentials.json ssh_keys username` |
107+
108+
### Pool
109+
110+
These scripts are used to create and maintain a **Cardano Stake Pool Operator (SPO)** on a Mithril network, for **Tests only**.
111+
112+
Connect to the VM and select the Cardano node and the Mithril signer node:
113+
```
114+
# Show debug output
115+
export DEBUG=1
116+
117+
# Select Cardano network
118+
export NETWORK=preview
119+
export NETWORK_MAGIC=2
120+
121+
# Selet Cardano node
122+
export CARDANO_NODE=cardano-node-signer-1
123+
124+
# Select Mithril signer node
125+
export SIGNER_NODE=mithril-signer-1
126+
```
127+
128+
In order to create a stake pool from scratch:
129+
* Create keys with `create-keys.sh`
130+
* Register the stake address of the pool with `register-stake-address.sh`
131+
* Register the stake pool with `register-stake-pool.sh`
132+
133+
In order to query a stake pool information:
134+
* Query the stake pool with `query-stake-pool.sh`
135+
136+
In order to maintain the stake pool:
137+
* Renew the operational certificate of the stake pool with `renew-opcert.sh`
138+
139+
In order to retire a stake pool:
140+
* Retire a stake poool with `retire-stake-pool.sh`
141+
142+
| Script | Description | Usage |
143+
|--------|-------------|-------|
144+
| `create-keys.sh` | Script for creating keys for a Cardano pool (SPO) | `./tools/pool/create-keys.sh` |
145+
| `query-stake-pool.sh` | Script for querying info about a Cardano pool (SPO) | `./tools/pool/query-stake-pool.sh` |
146+
| `register-stake-address.sh` | Script for registering stake address of a Cardano pool (SPO) | `TX_IN=***YOUR_TX_IN*** ./tools/pool/register-stake-address.sh` |
147+
| `register-stake-pool.sh` | Script for registering a Cardano stake pool (SPO) | `TX_IN=***YOUR_TX_IN*** SIGNER_DOMAIN=***YOUR_SIGNER_DOMAIN_NAME*** POOL_TICKER=***YOUR_TICKER*** ./tools/pool/register-stake-pool.sh` |
148+
| `renew-opcert.sh` | Script for renewing Operational Certificate for a Cardano pool (SPO) | `./tools/pool/renew-opcert.sh` |
149+
| `retire-stake-pool.sh` | Script for retiring a Cardano pool (SPO) | `TX_IN=***YOUR_TX_IN*** VALUE_OUT=***YOUR_VALUE_OUT*** ./tools/pool/retire-stake-pool.sh` |
150+
151+
### Genesis
152+
153+
These scripts are used to fast bootstrap the genesis cerificates of a Mithril network, for **Tests only**.
154+
The principle is to antedate the databases of the signers and aggregators so that we can bootstrap then a valid genesis certificate.
155+
156+
:warning: This process is experimental and recommended for expert users only.
157+
158+
| Script | Description | Usage |
159+
|--------|-------------|-------|
160+
| `fast-genesis-aggregator.sh` | Script for antedating an aggregator database to run after the first signer registration (create fake `2` previous epochs with current epoch data for `stake`, `verification_key` and `protocol_parameters`) | `./tools/genesis/fast-genesis-aggregators.sh` |
161+
| `fast-genesis-signer.sh` | Script for antedating a signer database to run after the first signer registration (create fake `2` previous epochs with current epoch data for `stake`, `protocol_initializer`) | `./tools/genesis/fast-genesis-signer.sh` |
162+
| `update-genesis-certificate.sh` | Script for updating the content of the genesis certificate in the aggregator database | `./tools/genesis/update-genesis-certificate.sh` |
163+
| `update-stake-distribution-aggregator.sh` | Script for adding a Pool Id to an existing stake distribution in the aggregator database | `./tools/genesis/update-stake-distribution-aggregator.sh` |
164+
| `update-stake-distribution-signer.sh` | Script for adding a Pool Id to an existing stake distribution in the signer database | `./tools/genesis/update-stake-distribution-signer.sh` |
165+
166+
Here is an example process to fast bootstrap a Mithril network on preview with `2` signer nodes:
167+
```
168+
# Set env var
169+
export NETWORK=preview
170+
export NETWORK_MAGIC=2
171+
export SIGNER_DOMAIN=dev-${NETWORK}.api.mithril.network
172+
173+
# Check that all cardano nodes are synced
174+
docker exec mithril-aggregator /app/bin/cardano-cli query tip --testnet-magic $NETWORK_MAGIC
175+
docker exec mithril-signer-1 /app/bin/cardano-cli query tip --testnet-magic $NETWORK_MAGIC
176+
docker exec mithril-signer-2 /app/bin/cardano-cli query tip --testnet-magic $NETWORK_MAGIC
177+
178+
## Clean signer db
179+
sqlite3 data/$NETWORK/mithril-signer-1/mithril/stores/signer.sqlite3 "DELETE FROM protocol_initializer; DELETE FROM stake;"
180+
sqlite3 data/$NETWORK/mithril-signer-2/mithril/stores/signer.sqlite3 "DELETE FROM protocol_initializer; DELETE FROM stake;"
181+
182+
## Clean aggregator db
183+
sqlite3 data/$NETWORK/mithril-aggregator/mithril/stores/aggregator.sqlite3 "DELETE FROM certificate; DELETE FROM single_signature; DELETE FROM verification_key; DELETE FROM pending_certificate; DELETE FROM snapshot; DELETE FROM stake;"
184+
185+
## Restart nodes
186+
docker restart mithril-aggregator
187+
docker restart mithril-signer-1
188+
docker restart mithril-signer-2
189+
190+
## If with certified signer
191+
### Create certified signer and retrieve its pool id
192+
CARDANO_NODE=cardano-node-signer-1 SIGNER_NODE=mithril-signer-1 POOL_TICKER=MSI01 ./tools/pool/create-keys-pool.sh
193+
CARDANO_NODE=cardano-node-signer-1 SIGNER_NODE=mithril-signer-1 POOL_TICKER=MSI01 ./tools/pool/register-stake-address.sh
194+
CARDANO_NODE=cardano-node-signer-1 SIGNER_NODE=mithril-signer-1 POOL_TICKER=MSI01 ./tools/pool/register-stake-pool.sh
195+
196+
CARDANO_NODE=cardano-node-signer-2 SIGNER_NODE=mithril-signer-2 POOL_TICKER=MSI02 ./tools/pool/create-keys-pool.sh
197+
CARDANO_NODE=cardano-node-signer-2 SIGNER_NODE=mithril-signer-2 POOL_TICKER=MSI02 ./tools/pool/register-stake-address.sh
198+
CARDANO_NODE=cardano-node-signer-2 SIGNER_NODE=mithril-signer-2 POOL_TICKER=MSI02 ./tools/pool/register-stake-pool.sh
199+
200+
## If with certified signer
201+
### Update stake distribution with new pool ids
202+
#### This is not completely working: you will have to wait for one epoch before going to the next step
203+
./tools/genesis/update-stake-distribution-aggregator.sh $NETWORK mithril-aggregator $(cat ./data/$NETWORK/mithril-signer-1/cardano/pool/pool_id.txt) 100000000123456
204+
./tools/genesis/update-stake-distribution-signer.sh $NETWORK mithril-signer-1 $(cat ./data/$NETWORK/mithril-signer-1/cardano/pool/pool_id.txt) 100000000123456
205+
./tools/genesis/update-stake-distribution-signer.sh $NETWORK mithril-signer-2 $(cat ./data/$NETWORK/mithril-signer-1/cardano/pool/pool_id.txt) 100000000123456
206+
207+
./tools/genesis/update-stake-distribution-aggregator.sh $NETWORK mithril-aggregator $(cat ./data/$NETWORK/mithril-signer-2/cardano/pool/pool_id.txt) 100000000123456
208+
./tools/genesis/update-stake-distribution-signer.sh $NETWORK mithril-signer-1 $(cat ./data/$NETWORK/mithril-signer-2/cardano/pool/pool_id.txt) 100000000123456
209+
./tools/genesis/update-stake-distribution-signer.sh $NETWORK mithril-signer-2 $(cat ./data/$NETWORK/mithril-signer-2/cardano/pool/pool_id.txt) 100000000123456
210+
211+
## Wait until stake distribution is updated and signer is registered
212+
docker logs -f --tail 250 mithril-aggregators
213+
docker logs -f --tail 250 mithril-signer-1
214+
docker logs -f --tail 250 mithril-signer-2
215+
216+
## Run fast genesis scripts
217+
./tools/genesis/fast-genesis-aggregator.sh $NETWORK mithril-aggregator
218+
./tools/genesis/fast-genesis-signer.sh $NETWORK mithril-signer-1
219+
./tools/genesis/fast-genesis-signer.sh $NETWORK mithril-signer-2
220+
221+
## Bootstrap genesis certificate
222+
docker exec mithril-aggregator /app/bin/mithril-aggregator -vvv genesis bootstrap
223+
224+
## Update genesis certificate to previous epoch
225+
### Select current genesis certificate in the aggregator database
226+
sqlite3 data/$NETWORK/mithril-aggregator/mithril/stores/aggregator.sqlite3 "SELECT * FROM certificate;"
227+
228+
### Recompute the genesis certificate hash
229+
Run the following Rust snippet (see below)
230+
231+
### Update the current genesis certificate of the aggregator database
232+
./tools/genesis/update-genesis-certificate.sh $NETWORK mithril-aggregator ***YOUR_UPDATED_CERTIFICATE_HASH*** '***YOUR_UPDATED_JSON_CERTIFICATE***'
233+
```
234+
235+
Snippet code to re-compute a valid genesis certificate:
236+
```rust
237+
### Add this test to the mithril-common/src/crypto_helper/genesis.rs file and run the test
238+
#[test]
239+
fn update_genesis_certificate() {
240+
use crate::entities::Certificate;
241+
242+
let certificate_json = "***YOUR_GENESIS_CERTIFICATE***";
243+
let mut certificate: Certificate = serde_json::from_str(certificate_json).unwrap();
244+
certificate.beacon.epoch -= 1;
245+
certificate.hash = certificate.compute_hash();
246+
println!(
247+
"UPDATED_CERTIFICATE_JSON={}",
248+
serde_json::to_string(&certificate).unwrap()
249+
);
250+
}
251+
```

0 commit comments

Comments
 (0)