Skip to content

Commit

Permalink
docs: enhance the era markers runbook
Browse files Browse the repository at this point in the history
  • Loading branch information
@jpraynaud
jpraynaud committed Oct 21, 2024
1 parent 6ad37fc commit 6116b06
Showing 1 changed file with 128 additions and 52 deletions.
180 changes: 128 additions & 52 deletions docs/runbook/era-markers/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@

This is the process for storing Mithril activation eras markers on the Cardano chain (bootstrap and update operations).

:warning: The process described in this document can lead to disturbed service of the associated Mihtril network. Thus it should be manipulated by experts only.
> [!IMPORTANT]
> :fire: The process described in this document can lead to disturbed service of the associated Mihtril network. Thus it should be manipulated by experts only.
## Pre-requisites

Expand All @@ -16,36 +17,119 @@ This is the process for storing Mithril activation eras markers on the Cardano c

## Setup

### Setup environment variables

Export the environment variables needed to complete the process:

```bash
$ export CARDANO_NODE_SOCKET_PATH=**PATH_TO_YOUR_NODE_SOCKET**
$ export CARDANO_TESTNET_MAGIC=**YOUR_TESTNET_MAGIC**
$ export CARDANO_WALLET_PATH=**PATH_TO_YOUR_KEYPAIRS**
$ export ERA_ACTIVATION_SECRET_KEY=**YOUR_ERA_ACTIVATION_SECRET_KEY**
$ export ASSETS_PATH=**YOUR_ASSETS_PATH**
export CARDANO_CLI=**CARDANO_CLI_COMMAND**
export CARDANO_NODE_SOCKET_PATH=**PATH_TO_YOUR_NODE_SOCKET**
export CARDANO_WALLET_PATH=**PATH_TO_YOUR_KEYPAIRS**
export ERA_ACTIVATION_SECRET_KEY=**YOUR_ERA_ACTIVATION_SECRET_KEY**
export ASSETS_PATH=**YOUR_ASSETS_PATH**
export SCRIPT_TX_VALUE=**MINIUM_SCRIPT_TX_VALUE**
```

A common value for the transaction amount used when a script transaction is made is:

```bash
export SCRIPT_TX_VALUE=2000000
```

Compute the network magic parameter that handles both the Cardano mainnet and Cardano test networks:

- If this is for a testing network

```bash
export CARDANO_TESTNET_MAGIC=**YOUR_TESTNET_MAGIC**
export CARDANO_NETWORK_MAGIC="--testnet-magic $CARDANO_TESTNET_MAGIC"
```

- If this is for the `mainnet`

```bash
export CARDANO_NETWORK_MAGIC="--mainnet"
```

Compute the current Cardano era:

```bash
CARDANO_ERA=$(cardano-cli query tip --testnet-magic $CARDANO_TESTNET_MAGIC | jq -r '.era |= ascii_downcase | .era')
export CARDANO_ERA=$($CARDANO_CLI query tip $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH | jq -r '.era |= ascii_downcase | .era')
```

### Prepare era markers

> [!IMPORTANT]
> :fire: A misconfiguration of the era markers can cause disturbed service on a Mithril network. The `CURRENT_ERA_EPOCH` and `NEXT_ERA_EPOCH` must be selected very cautiously.
#### If there is only one supported era

Set the epoch at which the era is active:

```bash
export CURRENT_ERA_EPOCH=**ERA_FIRST_ACTIVATION_EPOCH**
```

Create the datum file for a unique era:

```bash
./mithril-aggregator era generate-tx-datum --current-era-epoch $CURRENT_ERA_EPOCH --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY --target-path $ASSETS_PATH/mithril-era-datum.json
```

Set the transaction amount used when a script transaction is made:
#### If there are two supported era

Set the epoch at which the current era and the next era are active (the `CURRENT_ERA_EPOCH` must be lower than the current epoch and the `NEXT_ERA_EPOCH` must be set to a strictly greater epoch than the current epoch):

```bash
$ export SCRIPT_TX_VALUE=2000000
export CURRENT_ERA_EPOCH=**CURRENT_ERA_FIRST_ACTIVATION_EPOCH**
export NEXT_ERA_EPOCH=**NEXT_ERA_FIRST_ACTIVATION_EPOCH**
```

Create the datum file for two eras:

```bash
./mithril-aggregator era generate-tx-datum --current-era-epoch $CURRENT_ERA_EPOCH --next-era-epoch $NEXT_ERA_EPOCH --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY --target-path $ASSETS_PATH/mithril-era-datum.json
```

#### Verify the produced era marker

> [!IMPORTANT]
> :fire: The `mithril-aggregator` binary used to create the era markers must imperatively be compiled with all the targeted supported eras.
Verify that the produced era markers are exactly what is expected with the following command:

```bash
cat $ASSETS_PATH/mithril-era-datum.json| jq -r '.fields[].bytes' | tr '\n' ' ' | xxd -r -p | jq
```

An example output of the command is:

```json
{
"markers": [
{
"name": "thales",
"epoch": 1
},
{
"name": "pythagoras",
"epoch": 723
}
],
"signature": "fdcd45debabc148ef11c0bf71e42b7e583102dd5b8e486cd621a18e56136a57ff4f7bf9d036aed6148328a30a20eb6e79422ea4d1cc613e0bf97e14da64a5f00"
}
```

## Bootstrap Era Markers: Write a transaction with the first version of datum on chain

:warning: This step must be done only once for an address
> [!IMPORTANT]
> :fire: This step must be done only once for an address when no prior datum has been written in a UTxO.
> Otherwise, you need to refer to this [section](#update-era-markers-write-a-new-version-of-datum-on-chain)
Verify that the payment address has funds:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
TxHash TxIx Amount
--------------------------------------------------------------------------------------
f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7 0 10000000000 lovelace + TxOutDatumNone
Expand All @@ -54,57 +138,53 @@ f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7 0 10
And create the variable `TX_IN={TxHash}#{TxIn}` by replacing with values from the previous command:

```bash
$ TX_IN=f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7#0
```

Create the initial datum file:

```bash
$ ./mithril-aggregator era generate-tx-datum --current-era-epoch 1 --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY --target-path $ASSETS_PATH/mithril-era-datum-1.json
TX_IN=f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7#0
```

Now create the bootstrap transaction with datum:

```bash
$ cardano-cli $CARDANO_ERA transaction build --testnet-magic $CARDANO_TESTNET_MAGIC \
$CARDANO_CLI $CARDANO_ERA transaction build $CARDANO_NETWORK_MAGIC \
--tx-in $TX_IN \
--tx-out $(cat $CARDANO_WALLET_PATH/payment.addr)+$SCRIPT_TX_VALUE \
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum-1.json \
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum.json \
--change-address $(cat $CARDANO_WALLET_PATH/payment.addr) \
--out-file $ASSETS_PATH/tx.raw
--out-file $ASSETS_PATH/tx.raw \
--socket-path $CARDANO_NODE_SOCKET_PATH
Estimated transaction fee: Lovelace 168669
```

Then sign the transaction:

```bash
$ cardano-cli $CARDANO_ERA transaction sign \
$CARDANO_CLI $CARDANO_ERA transaction sign \
--tx-body-file $ASSETS_PATH/tx.raw \
--signing-key-file $CARDANO_WALLET_PATH/payment.skey \
--testnet-magic $CARDANO_TESTNET_MAGIC \
$CARDANO_NETWORK_MAGIC \
--out-file $ASSETS_PATH/tx.signed
```

And submit it:

```bash
$ cardano-cli $CARDANO_ERA transaction submit \
--testnet-magic $CARDANO_TESTNET_MAGIC \
--tx-file $ASSETS_PATH/tx.signed
$CARDANO_CLI $CARDANO_ERA transaction submit \
$CARDANO_NETWORK_MAGIC \
--tx-file $ASSETS_PATH/tx.signed \
--socket-path $CARDANO_NODE_SOCKET_PATH
Transaction successfully submitted.
```

Also get the transaction id:

```bash
$ cardano-cli transaction txid --tx-file $ASSETS_PATH/tx.signed
$CARDANO_CLI transaction txid --tx-file $ASSETS_PATH/tx.signed
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb
```

We need to wait a few seconds before the transaction is available and we can see the initial datum for the script address:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
TxHash TxIx Amount
--------------------------------------------------------------------------------------
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb 0 1500000 lovelace + TxOutDatumInline ReferenceTxInsScriptsInlineDatumsInBabbageEra (ScriptDataConstructor 0 [ScriptDataBytes "[{\"n\":\"thales\",\"e\":1}]",ScriptDataBytes "\165\143\232\227\&6\244e\222\211\187\167\197\167\175\229\181\162o/\182[|Nnt.h\ACKE\241=\242\139\242\182:a\204r\217\200&\190I\SO,\US\DLE\152\217U\223P5\128\164\232\153\181\ETB8\132\227\SO"])
Expand All @@ -116,7 +196,7 @@ Optional: We can retrieve the initial value stored in the datum with the cardano
The full utxo json representation:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC --out-file temp.json && cat temp.json | jq '. [] | select(.inlineDatum | . != null and . != "")'
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH --out-file temp.json && cat temp.json | jq '. [] | select(.inlineDatum | . != null and . != "")'
{
"address": "addr_test1qzzngukkj9ydjemqjlgfn42sevy2xnvauay46weushlpuq9thd4ray00csjssf4sxftv04xeequ3xfx72nujg9y4d5ysgkxxlh",
"datum": null,
Expand All @@ -141,12 +221,14 @@ $ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --te

## Update Era Markers: Write a new version of datum on chain

:warning: This step must be used anytime the era markers must be updated on chain
> [!IMPORTANT]
> :fire: This step must be used anytime the era markers must be updated on chain for an address when prior datum has already been written in a UTxO.
> Otherwise, you need to refer to this [section](#bootstrap-era-markers-write-a-transaction-with-the-first-version-of-datum-on-chain)
Retrieve the utxo of the payment address:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
TxHash TxIx Amount
--------------------------------------------------------------------------------------
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb 0 1500000 lovelace + TxOutDatumInline ReferenceTxInsScriptsInlineDatumsInBabbageEra (ScriptDataConstructor 0 [ScriptDataBytes "[{\"n\":\"thales\",\"e\":1}]",ScriptDataBytes "\165\143\232\227\&6\244e\222\211\187\167\197\167\175\229\181\162o/\182[|Nnt.h\ACKE\241=\242\139\242\182:a\204r\217\200&\190I\SO,\US\DLE\152\217U\223P5\128\164\232\153\181\ETB8\132\227\SO"])
Expand All @@ -156,66 +238,60 @@ $ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --te
And create the variable `TX_IN_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inline datumn are available):

```bash
$ TX_IN_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#0
TX_IN_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#0
```

And create the variable `TX_IN_NO_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inline datumn are not available):

```bash
$ TX_IN_NO_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#1
```

Create the updated datum file:

:warning: The options provided in the following command are for example only, you need to use adequately the options of the `era generate-tx-datum` command, which will depend on the operation you want to execute: announce an upcoming era or activate an upcoming era. This operation should be done very cautiously as a misconfiguration can lead to disturbed service of the network.

```bash
$ ./mithril-aggregator era generate-tx-datum --current-era-epoch 1 --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY --target-path $ASSETS_PATH/mithril-era-datum-2.json
TX_IN_NO_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#1
```

Now create the update transaction with datum:

```bash
$ cardano-cli $CARDANO_ERA transaction build --testnet-magic $CARDANO_TESTNET_MAGIC \
$CARDANO_CLI $CARDANO_ERA transaction build $CARDANO_NETWORK_MAGIC \
--tx-in $TX_IN_DATUM \
--tx-in $TX_IN_NO_DATUM \
--tx-out $(cat $CARDANO_WALLET_PATH/payment.addr)+$SCRIPT_TX_VALUE \
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum-2.json \
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum.json \
--change-address $(cat $CARDANO_WALLET_PATH/payment.addr) \
--out-file $ASSETS_PATH/tx.raw
--out-file $ASSETS_PATH/tx.raw \
--socket-path $CARDANO_NODE_SOCKET_PATH
Estimated transaction fee: Lovelace 179889
```

Then sign the transaction:

```bash
$ cardano-cli $CARDANO_ERA transaction sign \
$CARDANO_CLI $CARDANO_ERA transaction sign \
--tx-body-file $ASSETS_PATH/tx.raw \
--signing-key-file $CARDANO_WALLET_PATH/payment.skey \
--testnet-magic $CARDANO_TESTNET_MAGIC \
$CARDANO_NETWORK_MAGIC \
--out-file $ASSETS_PATH/tx.signed
```

And submit it:

```bash
$ cardano-cli $CARDANO_ERA transaction submit \
--testnet-magic $CARDANO_TESTNET_MAGIC \
--tx-file $ASSETS_PATH/tx.signed
$CARDANO_CLI $CARDANO_ERA transaction submit \
$CARDANO_NETWORK_MAGIC \
--tx-file $ASSETS_PATH/tx.signed \
--socket-path $CARDANO_NODE_SOCKET_PATH
Transaction successfully submitted.
```

Also get the transaction id:

```bash
$ cardano-cli transaction txid --tx-file $ASSETS_PATH/tx.signed
$CARDANO_CLI transaction txid --tx-file $ASSETS_PATH/tx.signed
1fd4d3e131afe3c8b212772a3f3083d2fbc6b2a7b20e54e4ff08e001598818d8
```

We need to wait a few seconds before the transaction is available and we can see the updated datum for the script address:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
TxHash TxIx Amount
--------------------------------------------------------------------------------------
1f139b47017c9c90d4622ac768e249d25d37ad4461db44a20486b7da72a78915 0 2000000 lovelace + TxOutDatumInline ReferenceTxInsScriptsInlineDatumsInBabbageEra (ScriptDataConstructor 0 [ScriptDataBytes "[{\"n\":\"thales\",\"e\":1},{\"n\":\"pythagoras\",\"e\":null}]",ScriptDataBytes "^P\EOT\248k3\196/\139\tU\173H\138\FS\194MD\240\153\227\142z\181\134\213\168\&2\222\219i1\246\NAK\\]\247\154U\143-^vmtq\204\207#\236\213\f\201\&1\152\145(\161\ETX;\183\128\195\r"])
Expand All @@ -227,7 +303,7 @@ We can retrieve the updated value stored in the datum with the cardano cli:
The full utxo json representation:

```bash
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC --out-file temp.json && cat temp.json | jq '. [] | select(.inlineDatum | . != null and . != "")'
$CARDANO_CLI query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH --out-file temp.json && cat temp.json | jq '. [] | select(.inlineDatum | . != null and . != "")'
{
"address": "addr_test1qzzngukkj9ydjemqjlgfn42sevy2xnvauay46weushlpuq9thd4ray00csjssf4sxftv04xeequ3xfx72nujg9y4d5ysgkxxlh",
"datum": null,
Expand Down

0 comments on commit 6116b06

Please sign in to comment.