Merge pull request #3318 from input-output-hk/jpraynaud/3303-dmq-node-ledger-peer-support

feat: ledger peers support for DMQ node

Author: jpraynaud

.github/workflows/actions/deploy-terraform-infrastructure/action.yml

@@ -67,19 +67,23 @@ inputs:
     description: Google Cloud VM SSH keys environment (`testing` or `production`).
     required: true
   mithril_use_p2p_network:
-    description: Mithril use P2P network (experimental, for test only).
+    description: Mithril use P2P network (experimental).
     required: false
     default: "false"
   mithril_p2p_use_dmq_protocol:
-    description: Mithril P2P network use DMQ protocol (experimental, for test only).
+    description: Mithril P2P network use DMQ protocol (experimental).
     required: false
     default: "false"
   mithril_p2p_use_real_dmq_node:
-    description: Use the real Decentralized Message Queue (DMQ) node (experimental, for test only).
+    description: Use the real Decentralized Message Queue (DMQ) node (experimental).
+    required: false
+    default: "false"
+  mithril_p2p_dmq_use_ledger_peers:
+    description: Use ledger peers declared with SRV records (CIP-155) for DMQ nodes (experimental).
     required: false
     default: "false"
   mithril_p2p_network_bootstrap_peer:
-    description: Mithril P2P network bootstrap peer (experimental, for test only).
+    description: Mithril P2P network bootstrap peer (experimental).
     required: false
     default: ""
   mithril_p2p_signer_relay_signer_registration_mode:
@@ -282,6 +286,7 @@ runs:
           mithril_use_p2p_network                                                       = "${{ inputs.mithril_use_p2p_network }}"
           mithril_p2p_use_dmq_protocol                                                  = "${{ inputs.mithril_p2p_use_dmq_protocol }}"
           mithril_p2p_use_real_dmq_node                                                 = "${{ inputs.mithril_p2p_use_real_dmq_node }}"
+          mithril_p2p_dmq_use_ledger_peers                                              = "${{ inputs.mithril_p2p_dmq_use_ledger_peers }}"
           mithril_p2p_network_bootstrap_peer                                            = "${{ inputs.mithril_p2p_network_bootstrap_peer }}"
           mithril_p2p_signer_relay_signer_registration_mode                             = "${{ inputs.mithril_p2p_signer_relay_signer_registration_mode }}"
           mithril_p2p_signer_relay_signature_registration_mode                          = "${{ inputs.mithril_p2p_signer_relay_signature_registration_mode }}"

.github/workflows/pre-release.yml

@@ -210,6 +210,7 @@ jobs:
             mithril_use_p2p_network: true
             mithril_p2p_use_dmq_protocol: true
             mithril_p2p_use_real_dmq_node: true
+            mithril_p2p_dmq_use_ledger_peers: true
             mithril_api_domain: api.mithril.network
             mithril_protocol_parameters: |
               {
@@ -280,6 +281,7 @@ jobs:
           mithril_use_p2p_network: ${{ matrix.mithril_use_p2p_network }}
           mithril_p2p_use_dmq_protocol: ${{ matrix.mithril_p2p_use_dmq_protocol }}
           mithril_p2p_use_real_dmq_node: ${{ matrix.mithril_p2p_use_real_dmq_node }}
+          mithril_p2p_dmq_use_ledger_peers: ${{ matrix.mithril_p2p_dmq_use_ledger_peers }}
           mithril_p2p_network_bootstrap_peer: ${{ vars.MITHRIL_P2P_NETWORK_BOOTSTRAP_PEER }}
           mithril_api_domain: ${{ matrix.mithril_api_domain }}
           mithril_image_id: ${{ env.DOCKER_IMAGE_ID }}

.github/workflows/release.yml

@@ -107,6 +107,10 @@ jobs:
           - environment: release-preprod
             environment_prefix: release
             cardano_network: preprod
+            mithril_use_p2p_network: true
+            mithril_p2p_use_dmq_protocol: true
+            mithril_p2p_use_real_dmq_node: true
+            mithril_p2p_dmq_use_ledger_peers: true
             mithril_api_domain: api.mithril.network
             mithril_protocol_parameters: |
               {
@@ -132,6 +136,10 @@ jobs:
           - environment: release-mainnet
             environment_prefix: release
             cardano_network: mainnet
+            mithril_use_p2p_network: true
+            mithril_p2p_use_dmq_protocol: true
+            mithril_p2p_use_real_dmq_node: true
+            mithril_p2p_dmq_use_ledger_peers: true
             mithril_api_domain: api.mithril.network
             mithril_protocol_parameters: |
               {
@@ -193,6 +201,11 @@ jobs:
           google_compute_instance_data_disk_snapshot: ${{ vars.GOOGLE_COMPUTE_INSTANCE_DATA_DISK_SNAPSHOT }}
           google_compute_instance_ssh_keys_environment: production
           google_application_credentials: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
+          mithril_use_p2p_network: ${{ matrix.mithril_use_p2p_network }}
+          mithril_p2p_use_dmq_protocol: ${{ matrix.mithril_p2p_use_dmq_protocol }}
+          mithril_p2p_use_real_dmq_node: ${{ matrix.mithril_p2p_use_real_dmq_node }}
+          mithril_p2p_dmq_use_ledger_peers: ${{ matrix.mithril_p2p_dmq_use_ledger_peers }}
+          mithril_p2p_network_bootstrap_peer: ${{ vars.MITHRIL_P2P_NETWORK_BOOTSTRAP_PEER }}
           mithril_api_domain: ${{ matrix.mithril_api_domain }}
           mithril_image_id: ${{ env.DOCKER_IMAGE_ID }}
           mithril_protocol_parameters: ${{ toJSON(matrix.mithril_protocol_parameters) }}

CHANGELOG.md

@@ -24,6 +24,7 @@ As a minor extension, we have adopted a slightly different versioning convention
   - Implemented new message id format for the DMQ message to follow specification of the [CIP-0137](https://cips.cardano.org/cip/CIP-0137).
   - Added support for the DMQ node `0.6.0.0` stable version.
   - Promoted the DMQ node as stable (beta) on `release-mainnet` and `release-preprod` networks.
+  - Added optional support for ledger peers declared with `SRV` records ([CIP-155](https://cips.cardano.org/cip/CIP-0155)).
 
 - Gracefully handle unknown signed entity types across Mithril nodes for improved forward compatibility.
 

docs/website/root/manual/operate/run-aggregator-node.md

@@ -906,16 +906,11 @@ Make sure your domain name points to your server's public IP address and that po
 
 :::
 
-## Set up the DMQ node (unstable)
+## Set up the DMQ node (beta)
 
-:::danger
-
-The DMQ node setup is currently **unstable** and not suitable for production use.
-
-During the stabilization and ramp-up phase of the DMQ network:
+:::info
 
-- Signatures are still sent to the central aggregator (using the DMQ node is harmless)
-- This section is subject to frequent changes.
+The DMQ node setup is currently **beta**. During the stabilization and ramp-up phase of the DMQ network, signatures received through it may not be enough to reach the quorum and thus produce valid certificates.
 
 :::
 

docs/website/root/manual/operate/run-signer-node.md

@@ -893,16 +893,13 @@ sudo service netfilter-persistent save
 
 :::
 
-## Set up the DMQ node (unstable)
+## Set up the DMQ node (beta)
 
-:::danger
-
-The DMQ node setup is currently **unstable** and not suitable for production use.
+:::info
 
-During the stabilization and ramp-up phase of the DMQ network:
+The DMQ node setup is currently **beta** and suitable for production use by SPOs.
 
-- Signatures are still sent to the central aggregator (using the DMQ node is harmless)
-- This section is subject to frequent changes.
+During the stabilization and ramp-up phase of the DMQ network, signatures are still sent to the leader aggregator (using the DMQ node is harmless).
 
 :::
 
@@ -1486,6 +1483,69 @@ More information about the recommended firewall configuration of the Cardano nod
 
 :::
 
+### Declare your DMQ node as a ledger peer (CIP-155)
+
+:::info
+
+This step is **optional** but **recommended**. It allows other DMQ nodes of the Mithril network to discover your relay automatically through the Cardano ledger, instead of relying solely on the bootstrap peer.
+
+:::
+
+[CIP-155](https://cips.cardano.org/cip/CIP-0155) defines a registry of `SRV` record prefixes that decentralized protocols can use to publish their service endpoints on the Cardano ledger. By declaring an `SRV` record with the `_mithril._tcp` prefix on your pool relay domain, your DMQ relay node becomes discoverable as a **ledger peer** by any DMQ node that uses ledger peers.
+
+The declaration requires two steps:
+
+1. Publish an `SRV` record for your **relay** DMQ node under the `_mithril._tcp` prefix of your pool domain.
+2. Register your pool domain as a multi-host relay in your stake pool registration certificate.
+
+:::caution
+
+Only the **relay** DMQ node must be published as a ledger peer. The **block producer** DMQ node must **never** be exposed.
+
+Here is the needed information to declare your DMQ node as a ledger peer:
+
+- `**YOUR_SPO_DOMAIN_NAME**`: replace with the domain name registered as a multi-host relay in your stake pool registration certificate (for example `example.com`)
+- `**YOUR_DMQ_NODE_RELAY_PUBLIC_HOSTNAME**`: replace with the public hostname (A or AAAA record) of your DMQ relay node
+- `**YOUR_DMQ_NODE_RELAY_PORT**`: replace with the listening port of your DMQ relay node.
+
+:::
+
+#### Publish the SRV record
+
+Add an `SRV` record to the DNS zone of your pool domain so that `_mithril._tcp.**YOUR_SPO_DOMAIN_NAME**` points to your DMQ relay node:
+
+```
+_mithril._tcp.**YOUR_SPO_DOMAIN_NAME**. 86400 IN SRV 10 5 **YOUR_DMQ_NODE_RELAY_PORT** **YOUR_DMQ_NODE_RELAY_PUBLIC_HOSTNAME**.
+```
+
+:::tip
+
+Here is an example for the pool domain `example.com`, with the DMQ relay node reachable at `cardano.example.com` on port `6161`:
+
+```
+_mithril._tcp.example.com. 86400 IN SRV 10 5 6161 cardano.example.com.
+```
+
+The values after `SRV` are the standard priority (`10`), weight (`5`), port (`6161`), and target hostname (`cardano.example.com`). More information is available in [RFC 2782](https://datatracker.ietf.org/doc/html/rfc2782).
+
+:::
+
+#### Register the pool domain as a multi-host relay
+
+Register `**YOUR_SPO_DOMAIN_NAME**` as a multi-host relay of your stake pool so that it is published on the Cardano ledger:
+
+```bash
+cardano-cli latest stake-pool registration-certificate \
+  ... \
+  --multi-host-pool-relay **YOUR_SPO_DOMAIN_NAME**
+```
+
+:::info
+
+The `_cardano._tcp` prefix is used by the Cardano node to discover Cardano relays on the same domain, while the `_mithril._tcp` prefix is used by the DMQ node to discover Mithril DMQ relays. Both prefixes can coexist on the same pool domain.
+
+:::
+
 ## Verify the Mithril signer deployment
 
 :::tip

mithril-infra/assets/infra.version

@@ -1,2 +1,2 @@
-0.5.16
+0.5.17
 

mithril-infra/mithril.aggregator.tf

@@ -123,6 +123,13 @@ if [ "${var.mithril_use_p2p_network}" = "true" ] && [ "${var.mithril_p2p_use_dmq
     cat $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json | jq '.localRoots[0].advertise = true' | jq '.localRoots[0].valency = (.localRoots[0].accessPoints | length)' > $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json.new
     rm -f $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json
     mv $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json.new $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json
+
+    # Enable dmq node ledger peers (CIP-155 SRV records)
+    if [ "${var.mithril_p2p_dmq_use_ledger_peers}" = "true" ]; then
+      cat $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json | jq '. + {"useLedgerAfterSlot": 0}' > $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json.new
+      rm -f $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json
+      mv $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json.new $AGGREGATOR_CONFIG_DIRECTORY/config/topology.json
+    fi
   fi
 fi
 EOT

mithril-infra/mithril.signer.tf

@@ -174,6 +174,13 @@ if [ "${var.mithril_use_p2p_network}" = "true" ] && [ "${var.mithril_p2p_use_dmq
     rm -f $DMQ_RELAY_CONFIG_DIRECTORY/topology.json
     mv $DMQ_RELAY_CONFIG_DIRECTORY/topology.json.new $DMQ_RELAY_CONFIG_DIRECTORY/topology.json
 
+    # Enable DMQ relay ledger peers (CIP-155 SRV records)
+    if [ "${var.mithril_p2p_dmq_use_ledger_peers}" = "true" ]; then
+      cat $DMQ_RELAY_CONFIG_DIRECTORY/topology.json | jq '. + {"useLedgerAfterSlot": 0}' > $DMQ_RELAY_CONFIG_DIRECTORY/topology.json.new
+      rm -f $DMQ_RELAY_CONFIG_DIRECTORY/topology.json
+      mv $DMQ_RELAY_CONFIG_DIRECTORY/topology.json.new $DMQ_RELAY_CONFIG_DIRECTORY/topology.json
+    fi
+
     # Update DMQ block-producer topology valency
     cat $DMQ_BP_CONFIG_DIRECTORY/topology.json | jq '.localRoots[0].valency = (.localRoots[0].accessPoints | length)' > $DMQ_BP_CONFIG_DIRECTORY/topology.json.new
     rm -f $DMQ_BP_CONFIG_DIRECTORY/topology.json

mithril-infra/variables.tf

@@ -212,19 +212,19 @@ variable "mithril_container_logging_max_file" {
 
 variable "mithril_use_p2p_network" {
   type        = bool
-  description = "Use the P2P network layer (experimental, for test only)"
+  description = "Use the P2P network layer (experimental)"
   default     = false
 }
 
 variable "mithril_p2p_use_dmq_protocol" {
   type        = bool
-  description = "Use the Decentralized Message Queue protocol (DMQ) (experimental, for test only)"
+  description = "Use the Decentralized Message Queue protocol (DMQ) (experimental)"
   default     = false
 }
 
 variable "mithril_p2p_use_real_dmq_node" {
   type        = bool
-  description = "Use the real Decentralized Message Queue (DMQ) node (experimental, for test only)"
+  description = "Use the real Decentralized Message Queue (DMQ) node (experimental)"
   default     = false
 }
 
@@ -234,6 +234,12 @@ variable "mithril_p2p_dmq_dense_topology" {
   default     = false
 }
 
+variable "mithril_p2p_dmq_use_ledger_peers" {
+  type        = bool
+  description = "Use ledger peers declared with SRV records (CIP-155) for DMQ nodes. When true, the public facing DMQ nodes (aggregator and signer relays) discover peers from the Cardano ledger. Disabled by default to isolate Mithril networks sharing the same Cardano network. (experimental)"
+  default     = false
+}
+
 variable "dmq_image_id" {
   type        = string
   description = "The DMQ image tag of service to deploy"
@@ -248,7 +254,7 @@ variable "dmq_image_registry" {
 
 variable "mithril_p2p_network_bootstrap_peer" {
   type        = string
-  description = "The dial to address of a bootstrap peer of the P2P network layer. Useful when setting-up a follower aggregator and signers in a different VM. (experimental, for test only)"
+  description = "The dial to address of a bootstrap peer of the P2P network layer. Useful when setting-up a follower aggregator and signers in a different VM. (experimental)"
   default     = ""
 }