Skip to content

Enhancements protocol configuration markers #3504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
turmelclem merged 8 commits into from
Aug 31, 2026
Merged

Enhancements protocol configuration markers #3504

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b284da3
docs: fix protocol configuration markers runbook
turmelclem Aug 28, 2026
112939d
refactor(aggregator): add option --force on protocol configuration ma…
turmelclem Aug 28, 2026
d686461
refactor(aggregator): add a debug log showing Mithril network configu…
turmelclem Aug 28, 2026
d42a4f4
refactor(signer): add a debug log showing Mithril network configuration
turmelclem Aug 28, 2026
62765fe
refactor(aggregator): update dev and preview config files variables
turmelclem Aug 28, 2026
5047b84
refactor(aggregator): fix typo in protocol-configuration commands pri…
turmelclem Aug 31, 2026
f8d4b38
refactor(aggregator): make protocol-configuration tx-datum helpers st…
turmelclem Aug 31, 2026
2fd9a6d
chore: upgrade crate versions
turmelclem Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 144 additions & 45 deletions docs/runbook/protocol-configuration-markers/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Export the environment variables needed to complete the process:
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 PROTOCOL_CONFIGURATION_MARKERS_SECRET_KEY=**YOUR_PROTOCOL_CONFIGURATION_MARKERS_SECRET_KEY**
export PROTOCOL_CONFIGURATION_READER_SECRET_KEY=**YOUR_PROTOCOL_CONFIGURATION_READER_SECRET_KEY**
export PROTOCOL_CONFIGURATION_READER_VERIFICATION_KEY=**YOUR_PROTOCOL_CONFIGURATION_READER_VERIFICATION_KEY**
export ASSETS_PATH=**YOUR_ASSETS_PATH**
export SCRIPT_TX_VALUE=**MINIMUM_SCRIPT_TX_VALUE**
Expand Down Expand Up @@ -82,6 +82,14 @@ Export latest active configurations from the Cardano chain:
./mithril-aggregator protocol-configuration export-markers --target-path $ASSETS_PATH/protocol-configurations.json
```

Execution of previous command must return the following information:

```bash
No protocol configurations found on chain, getting default protocol configurations output file...
Generating JSON protocol configurations output file...
Successfully wrote JSON protocol configurations file at **YOUR_ASSETS_PATH**/protocol-configurations.json
```

Default JSON prettified export will look like below:

```bash
Expand Down Expand Up @@ -131,6 +139,20 @@ Generate Tx Datum payload file by using previously edited JSON file
./mithril-aggregator protocol-configuration import-markers --import-path $ASSETS_PATH/protocol-configurations.json --target-path $ASSETS_PATH/protocol-configurations-datum.json
```
Comment thread
turmelclem marked this conversation as resolved.

Execution of previous command must return the following information:

```
Reading file content **YOUR_ASSETS_PATH**/protocol-configurations.json
Json parsing ...
Verifying protocol configuration consistency...
Verifying protocol configuration against on chain configuration...
Generating Tx datum ...
Verifying datum content do not exceed maximum size...
Datum size: 3.09 KB
Generating Tx datum output file...
Successfully wrote Tx datum file at **YOUR_ASSETS_PATH**/protocol-configurations-datum.json
```

> [!IMPORTANT]
> You may encounter errors if JSON is not valid, contains zero values or contains inconsistent configurations regarding the chain configurations of the targeted environment.

Expand Down Expand Up @@ -231,7 +253,7 @@ Transaction successfully submitted. Transaction hash is:
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 $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
$CARDANO_CLI $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH | jq
```

```json
Expand Down Expand Up @@ -366,32 +388,85 @@ Optional : We can also validate what has been written on chain by re-running the
Retrieve the utxo of the payment address:

```bash
$CARDANO_CLI $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
$CARDANO_CLI $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH | jq
```

```json
{
"add77f3246f19d2d1d599ff2decb7ac477b8a4839d7f9040ee704a53b519bc8b#0": {
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"inlineDatumRaw": null,
"referenceScript": null,
"value": {
"lovelace": 10000000000
"5ea0faac1d4b3ea633c4b2667b24d649b5d778123b32e942881246479bdab08d#0": {
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"inlineDatum": {
"constructor": 0,
"fields": [
{
"bytes": "7b226d61726b657273223a5b7b2265706f6368223a313338362c22636f6e66696775726174696f6e223a22613437333730373236663734366636333666366335"
},
{
"bytes": "66373036313732363136643635373436353732373361333631366231393037393836313664313934323334363537303638363935663636666233666339393939"
},
{
"bytes": "39393939393939396137383162363536653631363236633635363435663733363936373665363536343566363536653734363937343739356637343739373036"
},
{
"bytes": "35373338353738313834643639373436383732363936633533373436313662363534343639373337343732363936323735373436393666366537383138343336"
},
{
"bytes": "31373236343631366536663533373436313662363534343639373337343732363936323735373436393666366536663433363137323634363136653666343436"
},
{
"bytes": "31373436313632363137333635373334333631373236343631366536663534373236313665373336313633373436393666366537333738313934333631373236"
},
{
"bytes": "34363136653666343236633666363336623733353437323631366537333631363337343639366636653733373436333631373236343631366536663566373437"
},
{
"bytes": "32363136653733363136333734363936663665373361323732373336353633373537323639373437393566373036313732363136643635373436353732303036"
},
{
"bytes": "34373337343635373030663738316236333631373236343631366536663566363236633666363336623733356637343732363136653733363136333734363936"
},
{
"bytes": "66366537336132373237333635363337353732363937343739356637303631373236313664363537343635373231383634363437333734363537303138316522"
},
{
"bytes": "7d5d2c227369676e6174757265223a22363331306538656162303236313634336135313135636665333331643738633138323664353633376332636632386165"
},
{
"bytes": "30653464663732636331316239353635376336393438666634363832323766666332663136343731626233666333653434393733656333306137386138656630"
},
{
"bytes": "64653232393534353431373165373036227d"
}
]
},
"inlineDatumRaw": "d8799f58407b226d61726b657273223a5b7b2265706f6368223a313338362c22636f6e66696775726174696f6e223a2261343733373037323666373436663633366636633558406637303631373236313664363537343635373237336133363136623139303739383631366431393432333436353730363836393566363666623366633939393958403939393939393939613738316236353665363136323663363536343566373336393637366536353634356636353665373436393734373935663734373937303658403537333835373831383464363937343638373236393663353337343631366236353434363937333734373236393632373537343639366636653738313834333658403137323634363136653666353337343631366236353434363937333734373236393632373537343639366636653666343336313732363436313665366634343658403137343631363236313733363537333433363137323634363136653666353437323631366537333631363337343639366636653733373831393433363137323658403436313665366634323663366636333662373335343732363136653733363136333734363936663665373337343633363137323634363136653666356637343758403236313665373336313633373436393666366537336132373237333635363337353732363937343739356637303631373236313664363537343635373230303658403437333734363537303066373831623633363137323634363136653666356636323663366636333662373335663734373236313665373336313633373436393658406636653733613237323733363536333735373236393734373935663730363137323631366436353734363537323138363436343733373436353730313831652258407d5d2c227369676e6174757265223a223633313065386561623032363136343361353131356366653333316437386331383236643536333763326366323861655840306534646637326363313162393536353763363934386666343638323237666663326631363437316262336663336534343937336563333061373861386566305264653232393534353431373165373036227dff",
"inlineDatumhash": "2a08b8f14e45f9d0e5d0a6b9c03cc2217198f8c66fd6f32138c81e163cd28c74",
"referenceScript": null,
"value": {
"lovelace": 4600000
}
},
"5ea0faac1d4b3ea633c4b2667b24d649b5d778123b32e942881246479bdab08d#1": {
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"inlineDatumRaw": null,
"referenceScript": null,
"value": {
"lovelace": 9995190983
}
}
}
}
```

And create the variable `TX_IN_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inline datum are available):
And create the variable `TX_IN_DATUM={TxHash}#{TxIn}` by replacing with values from the previous command (where inlineDatum is available):

```bash
TX_IN_DATUM=add77f3246f19d2d1d599ff2decb7ac477b8a4839d7f9040ee704a53b519bc8b#0
```

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

```bash
TX_IN_NO_DATUM=add77f3246f19d2d1d599ff2decb7ac477b8a4839d7f9040ee704a53b519bc8b#1
Expand Down Expand Up @@ -431,20 +506,10 @@ $CARDANO_CLI $CARDANO_ERA transaction submit \
Transaction successfully submitted.
```

Also get the transaction id:

```bash
$CARDANO_CLI $CARDANO_ERA transaction txid --tx-file $ASSETS_PATH/tx.signed
```

```bash
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 $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH
$CARDANO_CLI $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/payment.addr) $CARDANO_NETWORK_MAGIC --socket-path $CARDANO_NODE_SOCKET_PATH | jq
```

```json
Expand Down Expand Up @@ -526,24 +591,58 @@ $CARDANO_CLI $CARDANO_ERA query utxo --address $(cat $CARDANO_WALLET_PATH/paymen

```bash
{
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"inlineDatum": {
"constructor": 0,
"fields": [
{
"bytes": "5b7b226e223a227468616c6573222c2265223a317d2c7b226e223a227079746861676f726173222c2265223a6e756c6c7d5d"
},
{
"bytes": "5e5004f86b33c42f8b0955ad488a1cc24d44f099e38e7ab586d5a832dedb6931f6155c5df79a558f2d5e766d7471cccf23ecd50cc931989128a1033bb780c30d"
}
]
},
"inlineDatumhash": "021310e8764d7d7ec3d66c00792ff391fa2145e1c8328eaf4630734c43bcfedc",
"referenceScript": null,
"value": {
"lovelace": 2000000
}
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"inlineDatum": {
"constructor": 0,
"fields": [
{
"bytes": "7b226d61726b657273223a5b7b2265706f6368223a313338362c22636f6e66696775726174696f6e223a22613437333730373236663734366636333666366335"
},
{
"bytes": "66373036313732363136643635373436353732373361333631366231393037393836313664313934323334363537303638363935663636666233666339393939"
},
{
"bytes": "39393939393939396137383162363536653631363236633635363435663733363936373665363536343566363536653734363937343739356637343739373036"
},
{
"bytes": "35373338353738313834643639373436383732363936633533373436313662363534343639373337343732363936323735373436393666366537383138343336"
},
{
"bytes": "31373236343631366536663533373436313662363534343639373337343732363936323735373436393666366536663433363137323634363136653666343436"
},
{
"bytes": "31373436313632363137333635373334333631373236343631366536663534373236313665373336313633373436393666366537333738313934333631373236"
},
{
"bytes": "34363136653666343236633666363336623733353437323631366537333631363337343639366636653733373436333631373236343631366536663566373437"
},
{
"bytes": "32363136653733363136333734363936663665373361323732373336353633373537323639373437393566373036313732363136643635373436353732303036"
},
{
"bytes": "34373337343635373030663738316236333631373236343631366536663566363236633666363336623733356637343732363136653733363136333734363936"
},
{
"bytes": "66366537336132373237333635363337353732363937343739356637303631373236313664363537343635373231383634363437333734363537303138316522"
},
{
"bytes": "7d5d2c227369676e6174757265223a22363331306538656162303236313634336135313135636665333331643738633138323664353633376332636632386165"
},
{
"bytes": "30653464663732636331316239353635376336393438666634363832323766666332663136343731626233666333653434393733656333306137386138656630"
},
{
"bytes": "64653232393534353431373165373036227d"
}
]
},
"inlineDatumRaw": "d8799f58407b226d61726b657273223a5b7b2265706f6368223a313338362c22636f6e66696775726174696f6e223a2261343733373037323666373436663633366636633558406637303631373236313664363537343635373237336133363136623139303739383631366431393432333436353730363836393566363666623366633939393958403939393939393939613738316236353665363136323663363536343566373336393637366536353634356636353665373436393734373935663734373937303658403537333835373831383464363937343638373236393663353337343631366236353434363937333734373236393632373537343639366636653738313834333658403137323634363136653666353337343631366236353434363937333734373236393632373537343639366636653666343336313732363436313665366634343658403137343631363236313733363537333433363137323634363136653666353437323631366537333631363337343639366636653733373831393433363137323658403436313665366634323663366636333662373335343732363136653733363136333734363936663665373337343633363137323634363136653666356637343758403236313665373336313633373436393666366537336132373237333635363337353732363937343739356637303631373236313664363537343635373230303658403437333734363537303066373831623633363137323634363136653666356636323663366636333662373335663734373236313665373336313633373436393658406636653733613237323733363536333735373236393734373935663730363137323631366436353734363537323138363436343733373436353730313831652258407d5d2c227369676e6174757265223a223633313065386561623032363136343361353131356366653333316437386331383236643536333763326366323861655840306534646637326363313162393536353763363934386666343638323237666663326631363437316262336663336534343937336563333061373861386566305264653232393534353431373165373036227dff",
"inlineDatumhash": "2a08b8f14e45f9d0e5d0a6b9c03cc2217198f8c66fd6f32138c81e163cd28c74",
"referenceScript": null,
"value": {
"lovelace": 4600000
}
}
```

Expand Down
9 changes: 3 additions & 6 deletions mithril-aggregator/config/dev.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,18 @@
{
"environment": "Production",
"cardano_node_version": "11.0.1",
"cardano_cli_path": "cardano-cli",
"cardano_node_socket_path": "/ipc/node.socket",
"network": "devnet",
"network_magic": 42,
"run_interval": 30000,
"protocol_parameters": {
"k": 5,
"m": 100,
"phi_f": 0.65
},
"ancillary_files_signer_config": {
"type": "secret-key",
"secret_key": "5b3131382c3138342c3232342c3137332c3136302c3234312c36312c3134342c36342c39332c3130362c3232392c38332c3133342c3138392c34302c3138392c3231302c32352c3138342c3136302c3134312c3233372c32362c3136382c35342c3233392c3230342c3133392c3131392c31332c3139395d"
},
"snapshot_uploader_type": "local",
"data_stores_directory": "/tmp/mithril-aggregator/stores",
"genesis_verification_key": "5b33322c3235332c3138362c3230312c3137372c31312c3131372c3133352c3138372c3136372c3138312c3138382c32322c35392c3230362c3130352c3233312c3135302c3231352c33302c37382c3231322c37362c31362c3235322c3138302c37322c3133342c3133372c3234372c3136312c36385d",
"era_adapter_type": "bootstrap"
"era_reader_adapter_type": "bootstrap",
"chain_observer_type": "pallas"
}
12 changes: 5 additions & 7 deletions mithril-aggregator/config/preview.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
{
"environment": "Production",
"cardano_node_version": "11.0.1",
"cardano_cli_path": "cardano-cli",
"cardano_node_socket_path": "/ipc/node.socket",
"network": "preview",
"run_interval": 60000,
"protocol_parameters": {
"k": 5,
"m": 100,
"phi_f": 0.65
},
"snapshot_uploader_type": "gcp",
"snapshot_bucket_name": "cardano-testnet",
"stores_directory": "./mithril-aggregator/stores",
"data_stores_directory": "/tmp/mithril-aggregator/stores",
"genesis_verification_key": "5b3132372c37332c3132342c3136312c362c3133372c3133312c3231332c3230372c3131372c3139382c38352c3137362c3139392c3136322c3234312c36382c3132332c3131392c3134352c31332c3233322c3234332c34392c3232392c322c3234392c3230352c3230352c33392c3233352c34345d",
"limit_keys_in_stores": 5,
"era_adapter_type": "bootstrap"
"era_reader_adapter_type": "bootstrap",
"chain_observer_type": "pallas",
"protocol_configuration_reader_adapter_config": "{\"type\": \"cardano-chain\", \"address\": \"addr_test1vr9gfzm8ryem4nck0tm6tqtf2mj407gwl3nhf2wh7d2t5kcl6r65s\", \"verification_key\": \"5b35342c3233362c3130322c33352c36372c3139362c3138372c36352c32332c37372c35342c3132392c3138322c32352c37312c3230322c3132322c36392c3234322c36302c3234332c3133312c36342c3131352c34302c32352c37362c3134302c3137342c3130342c322c3139335d\"}"
}
Loading
Loading