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

Draft
turmelclem wants to merge 5 commits into
base: main
Choose a base branch
from
+123 −52
Draft

Enhancements protocol configuration markers #3504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ce55409
docs: fix protocol configuration markers runbook
turmelclem Aug 28, 2026
c76d6ec
refactor(aggregator): add option --force on protocol configuration ma…
turmelclem Aug 28, 2026
9f6bd94
refactor(aggregator): add a debug log showing Mithril network configu…
turmelclem Aug 28, 2026
551b90f
refactor(signer): add a debug log showing Mithril network configuration
turmelclem Aug 28, 2026
9ab8cb2
refactor(aggregator): update dev and preview config files variables
turmelclem Aug 28, 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
126 changes: 91 additions & 35 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 following informations :

```bash
No protocol configurations found on chain, getting default protocol configurations output file...
Generating JSON protocol configurations output file...
Sucessfully wrote JSON protocol configurations file at **YOUR_ASSET_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 on lines 139 to 140

Execution of previous command must return following informations :

```
Reading file content **YOUR_ASSET_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...
Sucessfully wrote Tx datum file at **YOUR_ASSET_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,42 @@ 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,
"inlineDatum": **INLINE DATUM**,
"inlineDatumRaw": **INLINE DATUM RAW**,
"referenceScript": null,
"value": {
"lovelace": 8000000
}
},
"add77f3246f19d2d1d599ff2decb7ac477b8a4839d7f9040ee704a53b519bc8b#1": {
"address": "addr_test1qrcym4tvqjdntjvv0pdsp6keenwrk4xe7gq9exqqeh2x2p6gm9mtgjyvcvps92vzd3j2x0gzdudypuaca5r7d5elfe4q9da4p9",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"inlineDatumRaw": null,
"referenceScript": null,
"value": {
"lovelace": 10000000000
"lovelace": 9991762251
}
}
}
```

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 are 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 +463,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 +548,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"
}
11 changes: 5 additions & 6 deletions mithril-aggregator/config/preview.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
{
"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",
"data_stores_directory": "/tmp/mithril-aggregator/stores",
"stores_directory": "./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\"}"
}
20 changes: 15 additions & 5 deletions mithril-aggregator/src/commands/protocol_configuration_command.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,8 +245,8 @@ pub fn get_default_protocol_configurations() -> ConfigurationResolverFromMarkers
Epoch(0),
ProtocolConfigurationForEpoch {
protocol_parameters: ProtocolParameters {
k: 2422,
m: 20973,
k: 1944,
m: 16948,
phi_f: 0.2,
},
enabled_signed_entity_types: BTreeSet::from([
Expand Down Expand Up @@ -283,6 +283,10 @@ pub struct ImportProtocolConfigurationSubCommand {
/// Protocol Configuration Markers Secret Key
#[clap(long, env = "PROTOCOL_CONFIGURATION_READER_SECRET_KEY")]
protocol_configuration_markers_secret_key: HexEncodedProtocolConfigurationMarkersSecretKey,

/// Force datum file generation without verifying protocol configuration markers against on chain configuration
#[clap(long)]
force: bool,
Comment thread
turmelclem marked this conversation as resolved.
}

impl ImportProtocolConfigurationSubCommand {
Expand Down Expand Up @@ -324,12 +328,17 @@ impl ImportProtocolConfigurationSubCommand {
println!("Verifying protocol configuration consistency...");
Self::verify_protocol_configurations(&protocol_configurations)?;

// 4: Verify protocol configuration against on chain configuration
println!("Verifying protocol configuration against on chain configuration...");
let tools = ProtocolConfigurationTools::from_dependencies(dependencies)
.await
.with_context(|| "protocol-configuration-tools: initialization error")?;
tools.verify_configurations_against_chain(protocol_configurations.clone())?;

// 4: Verify protocol configuration against on chain configuration
if self.force {
println!("/!\\ --force option is set, bypassing the verification against chain /!\\");
} else {
println!("Verifying protocol configuration against on chain configuration...");
tools.verify_configurations_against_chain(protocol_configurations.clone())?;
}
Comment on lines 331 to +341

// 5: Generate Tx datum
println!("Generating Tx datum ...");
Expand Down Expand Up @@ -508,6 +517,7 @@ mod tests {
"protocol_configuration_tx_datum.json",
"--protocol-configuration-markers-secret-key",
&signer_secret_key,
"--force",
])
.expect("CLI parse should succeed");
}
Expand Down
5 changes: 5 additions & 0 deletions mithril-aggregator/src/services/epoch_service.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,11 @@ impl EpochService for MithrilEpochService {
.get_network_configuration(epoch)
.await?;

debug!(
self.logger,
"Mithril network configuration: {network_configuration:?}"
);
Comment on lines +308 to +311

let signer_registration_epoch_settings = AggregatorEpochSettings {
protocol_parameters: network_configuration
.configuration_for_registration
Expand Down
4 changes: 4 additions & 0 deletions mithril-signer/src/runtime/state_machine.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,10 @@ impl StateMachine {
nested_error: Some(e),
})?;
info!(self.logger, "→ Mithril network configuration found");
debug!(
self.logger,
"Mithril network configuration: {network_configuration:?}"
);
Comment on lines +236 to +239

if signer_registrations.epoch >= epoch {
info!(self.logger, "New Epoch found");
Expand Down
Loading