Skip to content

Commit 6229d88

Browse files
jpraynaudjpraynaud
committed
Add doc to create/update era markers on chain
1 parent b657ece commit 6229d88

File tree

1 file changed

+225
-0
lines changed

1 file changed

+225
-0
lines changed

‎mithril-aggregator/utils/era/README.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Store Mithril Era Markers On Chain
2+
3+
**This is a work in progress** :hammer_and_wrench:
4+
5+
This is the process for storing Mithril activation eras markers on the Cardano chain (bootstrap and update operations).
6+
7+
: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.
8+
9+
## Pre-requisites
10+
11+
* You need to have a recent version of [`jq`](https://stedolan.github.io/jq/download/) running (1.6+)
12+
* A running Cardano node running locally on the network you are targeting
13+
* A running Mithril Aggregator node
14+
* The era activation marker Cardano payment keypairs of your Mithril network
15+
* The era activation marker secret key of your Mithril network
16+
17+
## Setup
18+
19+
Export the environment variables needed to complete the process:
20+
```bash
21+
$ export CARDANO_NODE_SOCKET_PATH=**PATH_TO_YOUR_NODE_SOCKET**
22+
$ export CARDANO_TESTNET_MAGIC=**YOUR_TESTNET_MAGIC**
23+
$ export CARDANO_WALLET_PATH=**PATH_TO_YOUR_KEYPAIRS**
24+
$ export ERA_ACTIVATION_SECRET_KEY=**YOUR_ERA_ACTIVATION_SECRET_KEY**
25+
$ export ASSETS_PATH=**YOUR_ASSETS_PATH**
26+
```
27+
28+
Set the transaction amount used when a script transaction is made:
29+
```bash
30+
$ export SCRIPT_TX_VALUE=2000000
31+
```
32+
33+
## Bootstrap Era Markers: Write a transaction with the first version of datum on chain
34+
35+
:warning: This step must be done only once for an address
36+
37+
Verify that the payment address has funds:
38+
```bash
39+
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
40+
TxHash TxIx Amount
41+
--------------------------------------------------------------------------------------
42+
f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7 0 10000000000 lovelace + TxOutDatumNone
43+
```
44+
45+
And create the variable `TX_IN={TxHash}#{TxIn}` by replacing with values from the previous command:
46+
```bash
47+
$ TX_IN=f0c0345f151f9365fbbb4e7afa217e56b987d9e91fd754ca609d9dfec97275c7#0
48+
```
49+
50+
Create the initial datum file:
51+
```bash
52+
$ ./mithril-aggregator era generate-tx-datum --current-era-epoch 1 --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY > $ASSETS_PATH/mithril-era-datum-1.json
53+
```
54+
55+
Now create the bootstrap transaction with datum:
56+
```bash
57+
$ cardano-cli transaction build --babbage-era --testnet-magic $CARDANO_TESTNET_MAGIC \
58+
--tx-in $TX_IN \
59+
--tx-out $(cat $CARDANO_WALLET_PATH/payment.addr)+$SCRIPT_TX_VALUE \
60+
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum-1.json \
61+
--change-address $(cat $CARDANO_WALLET_PATH/payment.addr) \
62+
--out-file $ASSETS_PATH/tx.raw
63+
Estimated transaction fee: Lovelace 168669
64+
```
65+
66+
Then sign the transaction:
67+
```bash
68+
$ cardano-cli transaction sign \
69+
--tx-body-file $ASSETS_PATH/tx.raw \
70+
--signing-key-file $CARDANO_WALLET_PATH/payment.skey \
71+
--testnet-magic $CARDANO_TESTNET_MAGIC \
72+
--out-file $ASSETS_PATH/tx.signed
73+
```
74+
75+
And submit it:
76+
```bash
77+
$ cardano-cli transaction submit \
78+
--testnet-magic $CARDANO_TESTNET_MAGIC \
79+
--tx-file $ASSETS_PATH/tx.signed
80+
Transaction successfully submitted.
81+
```
82+
83+
Also get the transaction id:
84+
```bash
85+
$ cardano-cli transaction txid --tx-file $ASSETS_PATH/tx.signed
86+
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb
87+
```
88+
89+
We need to wait a few seconds before the transaction is available and we can see the initial datum for the script address:
90+
```bash
91+
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
92+
TxHash TxIx Amount
93+
--------------------------------------------------------------------------------------
94+
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"])
95+
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb 1 9998327415 lovelace + TxOutDatumNone
96+
```
97+
98+
Optional: We can retrieve the initial value stored in the datum with the cardano cli:
99+
100+
The full utxo json representation:
101+
```bash
102+
$ 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 . != "")'
103+
{
104+
"address": "addr_test1qzzngukkj9ydjemqjlgfn42sevy2xnvauay46weushlpuq9thd4ray00csjssf4sxftv04xeequ3xfx72nujg9y4d5ysgkxxlh",
105+
"datum": null,
106+
"inlineDatum": {
107+
"constructor": 0,
108+
"fields": [
109+
{
110+
"bytes": "5b7b226e223a227468616c6573222c2265223a317d5d"
111+
},
112+
{
113+
"bytes": "a58fe8e336f465ded3bba7c5a7afe5b5a26f2fb65b7c4e6e742e680645f13df28bf2b63a61cc72d9c826be490e2c1f1098d955df503580a4e899b5173884e30e"
114+
}
115+
]
116+
},
117+
"inlineDatumhash": "d8c1865816a520b92aa19ac5bc295fb1996281adf5ff06366343c6432d591cd1",
118+
"referenceScript": null,
119+
"value": {
120+
"lovelace": 1500000
121+
}
122+
}
123+
```
124+
125+
## Update Era Markers: Write a new version of datum on chain
126+
127+
:warning: This step must be used anytime the era markers must be updated on chain
128+
129+
Retrieve the utxo of the payment address:
130+
```bash
131+
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
132+
TxHash TxIx Amount
133+
--------------------------------------------------------------------------------------
134+
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"])
135+
6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb 1 9998327415 lovelace + TxOutDatumNone
136+
```
137+
138+
And create the variable `TX_IN_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inline datumn are available):
139+
```bash
140+
$ TX_IN_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#0
141+
```
142+
143+
And create the variable `TX_IN_NO_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inline datumn are not available):
144+
```bash
145+
$ TX_IN_NO_DATUM=6518b3cea0b49b55746ec61148e7c60ab042959d534f6bb6e8f6a844d4af69fb#1
146+
```
147+
148+
Create the updated datum file:
149+
150+
: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.
151+
152+
```bash
153+
$ ./mithril-aggregator era generate-tx-datum --current-era-epoch 1 --era-markers-secret-key $ERA_ACTIVATION_SECRET_KEY > $ASSETS_PATH/mithril-era-datum-2.json
154+
```
155+
156+
Now create the update transaction with datum:
157+
```bash
158+
$ cardano-cli transaction build --babbage-era --testnet-magic $CARDANO_TESTNET_MAGIC \
159+
--tx-in $TX_IN_DATUM \
160+
--tx-in $TX_IN_NO_DATUM \
161+
--tx-out $(cat $CARDANO_WALLET_PATH/payment.addr)+$SCRIPT_TX_VALUE \
162+
--tx-out-inline-datum-file $ASSETS_PATH/mithril-era-datum-2.json \
163+
--change-address $(cat $CARDANO_WALLET_PATH/payment.addr) \
164+
--out-file $ASSETS_PATH/tx.raw
165+
Estimated transaction fee: Lovelace 179889
166+
```
167+
168+
Then sign the transaction:
169+
```bash
170+
$ cardano-cli transaction sign \
171+
--tx-body-file $ASSETS_PATH/tx.raw \
172+
--signing-key-file $CARDANO_WALLET_PATH/payment.skey \
173+
--testnet-magic $CARDANO_TESTNET_MAGIC \
174+
--out-file $ASSETS_PATH/tx.signed
175+
```
176+
177+
And submit it:
178+
```bash
179+
$ cardano-cli transaction submit \
180+
--testnet-magic $CARDANO_TESTNET_MAGIC \
181+
--tx-file $ASSETS_PATH/tx.signed
182+
Transaction successfully submitted.
183+
```
184+
185+
Also get the transaction id:
186+
```bash
187+
$ cardano-cli transaction txid --tx-file $ASSETS_PATH/tx.signed
188+
1fd4d3e131afe3c8b212772a3f3083d2fbc6b2a7b20e54e4ff08e001598818d8
189+
```
190+
191+
We need to wait a few seconds before the transaction is available and we can see the updated datum for the script address:
192+
```bash
193+
$ cardano-cli query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) --testnet-magic $CARDANO_TESTNET_MAGIC
194+
TxHash TxIx Amount
195+
--------------------------------------------------------------------------------------
196+
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"])
197+
1f139b47017c9c90d4622ac768e249d25d37ad4461db44a20486b7da72a78915 1 9997647526 lovelace + TxOutDatumNone
198+
```
199+
200+
We can retrieve the updated value stored in the datum with the cardano cli:
201+
202+
The full utxo json representation:
203+
```bash
204+
$ 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 . != "")'
205+
{
206+
"address": "addr_test1qzzngukkj9ydjemqjlgfn42sevy2xnvauay46weushlpuq9thd4ray00csjssf4sxftv04xeequ3xfx72nujg9y4d5ysgkxxlh",
207+
"datum": null,
208+
"inlineDatum": {
209+
"constructor": 0,
210+
"fields": [
211+
{
212+
"bytes": "5b7b226e223a227468616c6573222c2265223a317d2c7b226e223a227079746861676f726173222c2265223a6e756c6c7d5d"
213+
},
214+
{
215+
"bytes": "5e5004f86b33c42f8b0955ad488a1cc24d44f099e38e7ab586d5a832dedb6931f6155c5df79a558f2d5e766d7471cccf23ecd50cc931989128a1033bb780c30d"
216+
}
217+
]
218+
},
219+
"inlineDatumhash": "021310e8764d7d7ec3d66c00792ff391fa2145e1c8328eaf4630734c43bcfedc",
220+
"referenceScript": null,
221+
"value": {
222+
"lovelace": 2000000
223+
}
224+
}
225+
```

0 commit comments

Comments
 (0)