# Integration of Mithril with Cardano

## Abstract

Mithril is an overlay protocol that creates state proofs for the Cardano blockchain in a decentralized manner. These proofs enable fast node bootstrapping and light clients for wallets and bridges. Currently, Mithril is not bundled with the Cardano node, limiting SPO adoption in the Mithril protocol. Mithril's security requires at least a participation of 80% of the stake participation to be considered secure. As no incentive mechanism currently exists for Mithril to encourage such participation, this document explores integration approaches to increase its adoption.

## State of the art

### Installation of the Cardano node

Today, SPOs install Cardano nodes through several methods, resulting in a highly fragmented ecosystem.

A [community poll conducted in November 2024](https://x.com/therealdisasm/status/1853449748297965684) (315 votes) revealed the following distribution:

| Deployment Method | Percentage |
| --------------------------------------- | ---------- |
| Scripts (CNTools, etc.) | 38.7% |
| Container-based (Kubernetes) | 10.8% |
| Nix/NixOS deployment | 6.3% |
| Other (manual, custom scripts, Ansible) | 44.1% |

The large "Other" category primarily consists of manual deployments with custom scripts, Ansible playbooks, and Docker setups outside Kubernetes. As noted by several respondents, the term "deploy" is overloaded: many SPOs manually deploy binaries but rely on tools like CNTools for day-to-day operations such as KES rotation, voting, and monitoring via gLiveView.

Each method requires manual configuration of topology files, genesis files, environment variables, and key management. Operators must follow documentation that varies in quality and currency across different sources. This fragmentation means there is no single, standardized deployment path, making it difficult to provide consistent tooling or automation across the SPO community.

### Installation of Mithril components

### Mithril signer

Mithril installation follows similar patterns but is entirely separate from the Cardano node setup. SPOs must install the Mithril signer on their block producer with its own environment file, key paths, and aggregator endpoint configuration. The Mithril relay is used by the Mithril signer to communicate with the Mithril aggregator and runs on relay nodes with its own settings.

This separation means operators must follow different documentation, manage independent release cycles, and manually ensure version compatibility between Cardano node and Mithril components. The cognitive overhead and additional maintenance burden discourages adoption.

### Upcoming DMQ node

The DMQ (Decentralized Message Queue) node enables peer-to-peer message diffusion for Mithril signatures using the Ouroboros network protocol. While this improves Mithril's decentralization and performance, it introduces significant challenges for SPOs.

Operators will need to deploy and configure yet another node with its own configuration. The DMQ node also has an independent release cycle, requiring additional version management. Network configuration between DMQ nodes adds complexity to already intricate SPO infrastructure setups. The DMQ node, as Cardano and Mithril nodes, follows a block-producer/relay architecture, further increasing the number of nodes to manage.

### Upcoming KES agent

The KES agent will provide access to KES keys (or provide KES signature capability) for Cardano node and Mithril nodes.

While this improves security and automation, it adds another component to the SPO infrastructure. SPOs will need to understand and configure this additional piece of infrastructure.

## Proposals

We have crafted different proposals to address the challenges outlined above. For each proposal, we have taken into consideration the difficulty of implementation, ease of maintenance, security implications, and ease of adoption by SPOs.

| Proposal | Implementation | Maintenance Ease | Security | SPO Adoption |
| ----------------------- | -------------- | ---------------- | -------- | ------------ |
| 1: Documentation | Easy | Easy | N/A | Medium |
| 2: GitHub artifacts | Easy | Poor | Good | Medium |
| 3: Docker bundle | Medium | Poor | Medium | Medium |
| 4: Guild Operator tools | Medium | Medium | Good | Medium |
| 4: Unified tool | Complex | Good | Good | Good |

### Proposal 1: make Mithril a default component in Cardano documentation for SPOs

This proposal involves adding Mithril as a default component in the official Cardano documentation for stake pool operators. The main Cardano documentation at [docs.cardano.org](https://docs.cardano.org/stake-pool-operators/operating-a-stake-pool), the developer portal at [developers.cardano.org](https://developers.cardano.org/docs/operate-a-stake-pool/), and community resources like the [Cardano Course gitbook](https://cardano-course.gitbook.io/cardano-course/handbook/create-a-stake-pool) would be updated to include guidance on installing and configuring Mithril alongside the Cardano node.

This approach requires minimal technical effort and leverages existing documentation infrastructure. SPOs following official guides would naturally encounter Mithril during their setup process, increasing awareness and adoption. The documentation would explain the benefits of running Mithril, provide installation instructions, and link to detailed Mithril-specific resources.

The DMQ node would also be documented as part of the Mithril setup, with clear instructions on its deployment and configuration.

However, this proposal only addresses awareness and does not solve the underlying complexity of managing separate installations. SPOs would still need to handle independent release cycles, maintain separate configuration files, and ensure version compatibility manually. The effectiveness depends entirely on SPOs reading and following the documentation, with no mechanism to verify or encourage compliance.

### Proposal 2: bundle the Mithril signer and DMQ node binaries in the Cardano GitHub release artifacts

With this proposal, we consider including Mithril and DMQ binaries in Cardano GitHub releases. The implementation would go through nix which is already implemented in the Mithril nodes and DMQ node repositories. The Mithril signer would need to be built statically to be included in the Cardano Docker image, but this should not pose significant challenges. The DMQ node is already statically built.

A concern is maintenance which could become problematic as the Cardano node, Mithril nodes and DMQ node have different release cycles (in particular Mithril ships more often than Cardano, and Mithril nodes must be compatible with the new released Cardano node which incurs a synchronzization effort between teams). Furthermore, this approach only helps operators using pre-built binaries, leaving those with other deployments out of the loop.

### Proposal 3: bundle Mithril signer and DMQ node binaries in the Cardano Docker image

In this proposal the Mithril signer and DMQ node binaries would be directly bundled into the official Cardano Docker image. This approach simplifies deployment for SPOs using Docker by providing a single image that includes all necessary components. The image would come with pre-configured Mithril default settings, allowing operators to enable Mithril components with minimal configuration changes. Also it easily allows to optout of Mithril for SPOs not willing to use it.

A drawback of this approach is to create an inflexible deployment where components cannot be upgraded independently. The combined Docker image also becomes significantly larger. Also, from a security perspective, bundling increases the attack surface of the container which may be a concern.

Concerns regarding maitenance are the same as in proposal 2. Furthermore, this approach only helps operators using Docker, leaving those with native deployments without a solution.

A prototype has been created by the Mithril team to validate the feasibility of this proposal in [mithril#2616](https://github.com/input-output-hk/mithril/issues/2616). The creation of the bundled Docker image would require to embed binaries of Mithril and DMQ node that would be statically built with nix (see Proposal 2), and some modifications to the official Cardano Docker image build and scripts used to run the container.

### Proposal 4: integrate Mithril and DMQ node deployment in the Guild Operators tools

The Guild Operators tools are a popular choice among SPOs for managing Cardano node deployments. This proposal suggests integrating by default the Mithril signer and DMQ node deployment capabilities into these tools.

Currently, the Guild Operators tools already support Mithril signer and relay deployment, but this functionality is optional and must be explicitly enabled. Also the DMQ node is not yet integrated. By making Mithril a default feature and adding DMQ node support, this proposal would significantly increase visibility and adoption among the substantial portion of SPOs who rely on Guild Operators for their infrastructure management.

### Proposal 5: a unified deployment tool

#### Overview

This proposal consists of a unified deployment tool (aka the **Cardano Deployer**) that addresses all previously identified challenges. This tool provides flexibility in deployment types and node selection, allowing operators to deploy only what they need or complete existing infrastructure with Mithril components.

Security is ensured through binary verification and reproducible deployments. Ease of use comes from replacing multiple manual procedures with a single tool. A compatibility matrix powered by continuous integration enables rapid validation of new releases, accelerating the path from release to production.

The tool supports both local execution on target machines and remote deployment via SSH, accommodating different security requirements. Multiple infrastructures can be managed from a single installation with centralized state tracking.

This tool is designed to become the default method for deploying Cardano nodes and overlay protocol nodes. By making Mithril deployment seamless and automatic, adoption by SPOs will naturally increase fast.

The tool offers simple and expert configuration modes. Simple mode requires minimal input with sensible defaults, while expert mode exposes all configuration options. It supports evolving infrastructure types from local development through testnet deployments to complex production setups with multiple relays and failover block producers.

The deployment process includes automatic health verification and rollback capabilities in case of failure. Granular upgrade features allow updating specific nodes independently. Fast bootstrap using Mithril state proofs speeds up initial Cardano node synchronization. All features are optional and can be enabled or disabled as needed.

In the context of emerging alternative Cardano node implementations, this tool can also facilitate their adoption by providing a consistent deployment experience, promoting ecosystem diversity and resilience.

| Capability | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| Multi-node deployment | Cardano node, Mithril signer, Mithril relay, DMQ node |
| Configuration modes | Simple (minimal input) and Expert (full control) |
| Granular upgrades | Update specific nodes independently |
| Fast bootstrap | Mithril state proofs for rapid initial sync |
| Health verification | Automatic checks after deployment with rollback on failure |
| Future extensions | Evolutivity toward SPO key management, monitoring, new node implementations, ... |

#### Features

The Cardano Deployer provides comprehensive deployment and management capabilities. It handles multi-node deployments including Cardano node, Mithril signer, Mithril relay, and DMQ node. Version management automatically selects the latest stable releases (or unstable pre-release) or allows pinning specific versions. Configuration generation creates topology files and environment configurations from minimal operator input. Health monitoring tracks chain synchronization, Prometheus metrics, and service status. Incremental updates detect configuration changes and apply only necessary modifications.

#### Deployment recipes

Deployment recipes define how each node type is deployed for each flavor. Recipes specify container images, volume mappings, and environment templates for Docker deployments, or binary paths, systemd service definitions, and user configurations for native deployments.

Recipes are extensible, allowing new node types to be added as they emerge. Future recipes could in particular support Hydra nodes, the KES agent, and alternative Cardano node implementations. Operators can customize recipes to match their specific requirements while maintaining compatibility with the overall deployment framework.

#### Deployment modes

The tool supports multiple execution modes to accommodate different operational requirements:

- Remote mode deploys and manages infrastructure from a central operator machine via SSH connections, providing unified management of the complete infrastructure.

- Local mode runs the tool directly on each target machine, suitable for security-sensitive environments where SSH access is restricted or for developers working on individual nodes.

Future releases could add support for reproducible builds with nix, Kubernetes deployments, Terraform infrastructure-as-code, and Ansible configuration management to serve operators with more sophisticated infrastructure requirements.

#### Compatibility matrix

The compatibility matrix ensures version coherence across all managed nodes. A continuous integration pipeline automatically tests new releases of each component against existing versions. When tests pass, the matrix is updated to reflect validated combinations.

The Cardano Deployer queries this matrix when resolving versions, recommending only tested combinations. Operators receive warnings when attempting to deploy untested version combinations. This system would dramatically reduce the time from release to production deployment by providing immediate confidence in compatibility.

#### Deployment Verification

After deployment, the tool automatically verifies that all nodes are working correctly. Service status checks confirm that systemd services or Docker containers are running. Chain synchronization is verified by querying the node tip and comparing against expected values.

Prometheus metrics endpoints are queried to verify peer connectivity, block production status, Mithril signer registration and signature diffusion, and DMQ node connectivty to the network and healthiness. The verification can run continuously in watch mode for ongoing monitoring or export results in Prometheus or JSON format for integration with external monitoring systems.

#### Binary Security

When deploying via downloaded binaries, security is ensured through GPG signature verification. Binaries are signed by project maintainers using their GPG keys, with public keys distributed through official channels. The deployer verifies signatures before installation, blocking deployment if verification fails.

This verification is enabled by default but can be disabled for development or testing scenarios. Checksums are also validated against official releases to ensure binary integrity.

#### Security Considerations

The tool maintains strict security boundaries throughout its operation. Cold keys are never handled by the tool, all operations requiring cold keys provide step-by-step guides for execution on air-gapped machines. Binary signatures are verified before installation when downloading from official sources.

Configuration files contain paths to secrets, never the secrets themselves. SSH-based deployment uses key authentication rather than passwords. Operators can choose local execution mode for security-sensitive machines, avoiding the need to grant SSH access.

#### Adoption challenges

Introducing this tool creates a tradeoff: Mithril adoption now depends on adoption of the Cardano Deployer itself. However, this tradeoff is favorable because the tool provides substantial value to SPOs beyond Mithril integration, improving their overall deployment and management experience.

Success requires comprehensive documentation, practical examples, and step-by-step tutorials. Community engagement through forums, social media, and direct outreach to SPOs will be essential. All existing Cardano, Mithril and DMQ documentations should be updated to reference this tool as the recommended deployment method. Promotion efforts must ensure SPOs understand both the tool's existence and its benefits.

The Guild Operators tools already provide a partial solution and are used by a significant portion of SPOs. Collaborating with the Guild Operators community to integrate or align with the Cardano Deployer could accelerate adoption and provide a smoother transition for existing users.

#### Example of CLI interface

The tool provides an intuitive command-line interface for all operations.

# Initialize configuration for a new infrastructure
cardano-deployer init --network mainnet

# Validate configuration and version compatibility
cardano-deployer validate

# Deploy the complete infrastructure
cardano-deployer deploy

# Check current deployment status
cardano-deployer status

# Upgrade a specific node
cardano-deployer upgrade mithril-signer

# Run health checks on deployed nodes
cardano-deployer verify

# Manage multiple infrastructures
cardano-deployer infra list
cardano-deployer deploy --infra pool-alpha-mainnet

# Execute locally on the current machine
cardano-deployer deploy --local

## References

- [Cardano Node Repository](https://github.com/IntersectMBO/cardano-node)
- [Cardano Developer Portal](https://developers.cardano.org/docs/operate-a-stake-pool/)
- [Mithril Repository](https://github.com/input-output-hk/mithril)
- [Mithril Signer Guide](https://mithril.network/doc/manual/operate/run-signer-node/)
- [DMQ Node Repository](https://github.com/IntersectMBO/dmq-node)
- [Guild Operators Tools](https://cardano-community.github.io/guild-operators/)
- [Guild Operators - Mithril Integration](https://cardano-community.github.io/guild-operators/Mithril/mithril-overview/)