feat: add standalone quorum list server deploy

README.md

@@ -57,6 +57,9 @@ Ansible configuration is stored in the `*.yml` file. The
 file contains the majority of playbook options.
 The rest are defined in [ansible roles](https://github.com/dashpay/dash-network-deploy/tree/master/ansible/roles).
 
+Standalone quorum API hosts can be enabled with `quorum_list_server_count`.
+See [Standalone Quorum List Server](docs/quorum-list-server.md) for details.
+
 Configure your credentials in the `.env` file.
 
 ### Using git

ansible/deploy.yml

@@ -374,6 +374,19 @@
     - dashmate_deploy
 
 
+- name: Set up quorum list servers
+  hosts: quorum_list_servers
+  become: true
+  gather_facts: false
+  strategy: free
+  roles:
+    - role: quorum_list_server
+      when: quorum_list_server_enabled | bool
+  tags:
+    - full_deploy
+    - dashmate_deploy
+    - quorum_list_server
+
 - name: Set up protx diff script
   hosts: masternodes
   become: true

ansible/roles/quorum_list_server/defaults/main.yml

@@ -0,0 +1,21 @@
+---
+
+quorum_list_server_enabled: true
+quorum_list_server_image: dashpay/quorum-list-server:latest
+quorum_list_server_pull: true
+quorum_list_server_container_name: quorum-list-server
+quorum_list_server_config_dir: /etc/quorum-list-server
+quorum_list_server_config_path: "{{ quorum_list_server_config_dir }}/config.toml"
+quorum_list_server_host: "0.0.0.0"
+quorum_list_server_port: 8080
+quorum_list_server_previous_blocks_offset: 8
+
+quorum_list_server_rpc_host: "{{ (groups['seed_nodes'] | default([]) | first) | default('') }}"
+quorum_list_server_rpc_url: "http://{{ hostvars[quorum_list_server_rpc_host].private_ip }}:{{ dashd_rpc_port }}"
+quorum_list_server_rpc_user: "{{ dashd_rpc_user }}"
+quorum_list_server_rpc_password: "{{ dashd_rpc_password }}"
+quorum_list_server_network: "{{ dash_network }}"
+quorum_list_server_health_host: "{{ '127.0.0.1' if quorum_list_server_host in ['0.0.0.0', '::'] else quorum_list_server_host }}"
+
+quorum_list_server_version_check_host: ""
+quorum_list_server_address_host_override: ""

ansible/roles/quorum_list_server/tasks/main.yml

@@ -0,0 +1,52 @@
+---
+
+- name: Check quorum-list-server RPC target
+  ansible.builtin.assert:
+    that:
+      - groups['seed_nodes'] | default([]) | length > 0
+      - quorum_list_server_rpc_host is defined
+      - quorum_list_server_rpc_host | length > 0
+      - quorum_list_server_rpc_host in hostvars
+      - hostvars[quorum_list_server_rpc_host].private_ip is defined
+    fail_msg: "quorum_list_server_rpc_host must point at an inventory host with a private_ip"
+
+- name: Create quorum-list-server config dir
+  ansible.builtin.file:
+    path: "{{ quorum_list_server_config_dir }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0750"
+
+- name: Write quorum-list-server config
+  ansible.builtin.template:
+    src: config.toml.j2
+    dest: "{{ quorum_list_server_config_path }}"
+    owner: root
+    group: root
+    mode: "0640"
+  no_log: true
+  register: quorum_list_server_config
+
+- name: Start quorum-list-server
+  community.docker.docker_container:
+    name: "{{ quorum_list_server_container_name }}"
+    image: "{{ quorum_list_server_image }}"
+    state: started
+    restart_policy: always
+    pull: "{{ quorum_list_server_pull | bool }}"
+    recreate: "{{ quorum_list_server_config.changed }}"
+    user: "appuser:root"
+    network_mode: host
+    volumes:
+      - "{{ quorum_list_server_config_path }}:/app/config.toml:ro"
+
+- name: Wait for quorum-list-server health endpoint
+  ansible.builtin.uri:
+    url: "http://{{ quorum_list_server_health_host }}:{{ quorum_list_server_port }}/health"
+    status_code: 200
+    timeout: 3
+  register: quorum_list_server_health
+  until: quorum_list_server_health.status == 200
+  retries: 30
+  delay: 2

ansible/roles/quorum_list_server/templates/config.toml.j2

@@ -0,0 +1,23 @@
+network = {{ quorum_list_server_network | to_json }}
+
+[server]
+port = {{ quorum_list_server_port | int }}
+host = {{ quorum_list_server_host | to_json }}
+
+[rpc]
+url = {{ quorum_list_server_rpc_url | to_json }}
+username = {{ quorum_list_server_rpc_user | to_json }}
+password = {{ quorum_list_server_rpc_password | to_json }}
+
+[quorum]
+previous_blocks_offset = {{ quorum_list_server_previous_blocks_offset | int }}
+
+{% if quorum_list_server_version_check_host | length > 0 or quorum_list_server_address_host_override | length > 0 %}
+[docker]
+{% if quorum_list_server_version_check_host | length > 0 %}
+version_check_host = {{ quorum_list_server_version_check_host | to_json }}
+{% endif %}
+{% if quorum_list_server_address_host_override | length > 0 %}
+address_host_override = {{ quorum_list_server_address_host_override | to_json }}
+{% endif %}
+{% endif %}

docs/quorum-list-server.md

@@ -0,0 +1,83 @@
+# Standalone Quorum List Server
+
+`dash-network-deploy` can provision a standalone `dashpay/quorum-list-server`
+node for networks that need a public quorum API endpoint.
+
+Each enabled network gets a separate EC2 instance running the
+`dashpay/quorum-list-server` Docker image, a private RPC connection to its seed
+node, and a network-specific public HTTPS endpoint.
+
+## Enable
+
+Set a non-zero `quorum_list_server_count` in the network Terraform vars:
+
+```hcl
+quorum_list_server_count = 1
+```
+
+Optional Terraform settings:
+
+```hcl
+quorum_list_server_port           = 8080
+quorum_list_server_instance_size  = "micro"
+quorum_list_server_root_disk_size = 20
+```
+
+Terraform creates:
+
+- `quorum-list-server-N` EC2 host(s)
+- An Ansible inventory group named `quorum_list_servers`
+- A classic ELB with an HTTPS listener and an internal HTTP health check
+- An ACM certificate for `quorums.<network>.<main_domain>`
+- A Route53 CNAME for `quorums.<network>.<main_domain>`
+
+For devnets, `<network>` is derived generically from the Terraform workspace
+name: `devnet-<name>` produces `quorums.<name>.<main_domain>`.
+
+## Provisioning
+
+The deploy playbook applies the `quorum_list_server` Ansible role to hosts in
+the `quorum_list_servers` inventory group. The role writes
+`/etc/quorum-list-server/config.toml` as root-readable group material and starts
+the non-root Docker process with the root group so it can read the mounted
+configuration while using host networking.
+
+By default, the server reads quorum data from the first seed node over the
+private VPC RPC endpoint:
+
+```text
+http://<seed-1-private-ip>:20002
+```
+
+The role uses the network's existing Dash Core RPC credentials from Ansible
+vars. The HTTP JSON-RPC hop stays on private VPC addresses and is restricted by
+the network security groups; it is not exposed through the public ELB. Do not
+commit those credentials into docs or examples.
+
+Optional Ansible vars:
+
+```yaml
+quorum_list_server_image: dashpay/quorum-list-server:latest
+quorum_list_server_pull: true
+quorum_list_server_port: 8080
+quorum_list_server_previous_blocks_offset: 8
+quorum_list_server_rpc_host: seed-1
+quorum_list_server_version_check_host: ""
+quorum_list_server_address_host_override: ""
+```
+
+The role passes the generic Dash network class (`mainnet`, `testnet`, `devnet`,
+or `regtest`) to `quorum-list-server`. The Terraform workspace keeps the
+specific `devnet-<name>` deployment identity, while the service receives
+`devnet` and selects the standard Platform devnet LLMQ settings. Set
+`quorum_list_server_pull: false` only for an image tag built locally on the
+target host.
+
+## Verify
+
+After deploy:
+
+```bash
+curl -fsS https://quorums.<network>.<main_domain>/health
+curl -fsS https://quorums.<network>.<main_domain>/quorums
+```

terraform/aws/ansible_inventory_output.tf

@@ -35,7 +35,19 @@ locals {
     )
   ]
 
-    mixer_hosts = [
+  quorum_list_server_hosts = [
+    for n in range(length(aws_instance.quorum_list_server)) : templatefile(
+      "${path.module}/templates/inventory/hostname.tpl",
+      {
+        index      = n + 1
+        name       = element(aws_instance.quorum_list_server.*.tags.Hostname, n)
+        public_ip  = element(aws_instance.quorum_list_server.*.public_ip, n)
+        private_ip = element(aws_instance.quorum_list_server.*.private_ip, n)
+      }
+    )
+  ]
+
+  mixer_hosts = [
     for n in range(length(aws_instance.mixer)) : templatefile(
       "${path.module}/templates/inventory/hostname.tpl",
       {
@@ -168,6 +180,7 @@ locals {
           local.web_hosts.*,
           local.logs_hosts.*,
           local.wallet_node_hosts.*,
+          local.quorum_list_server_hosts.*,
           local.mixer_hosts.*,
           local.seed_node_hosts.*,
           local.miner_hosts.*,
@@ -178,16 +191,18 @@ locals {
           local.metrics_hosts.*,
         ),
       )
-      web_hosts           = join("\n", concat(aws_instance.web.*.tags.Hostname))
-      logs_hosts          = join("\n", concat(aws_instance.logs.*.tags.Hostname))
-      wallet_node_hosts   = join("\n", concat(aws_instance.dashd_wallet.*.tags.Hostname))
-      mixer_hosts         = join("\n", concat(aws_instance.mixer.*.tags.Hostname))
-      miner_hosts         = join("\n", concat(aws_instance.miner.*.tags.Hostname))
-      masternode_hosts    = join("\n", concat(aws_instance.masternode_amd.*.tags.Hostname), concat(aws_instance.masternode_arm.*.tags.Hostname))
-      hp_masternode_hosts = join("\n", concat(aws_instance.hp_masternode_amd.*.tags.Hostname), concat(aws_instance.hp_masternode_arm.*.tags.Hostname))
-      seed_hosts          = join("\n", concat(aws_instance.seed_node.*.tags.Hostname))
-      load_test_hosts     = join("\n", concat(aws_instance.load_test.*.tags.Hostname))
-      metrics_hosts     = join("\n", concat(aws_instance.metrics.*.tags.Hostname))
+      web_hosts                  = join("\n", concat(aws_instance.web.*.tags.Hostname))
+      logs_hosts                 = join("\n", concat(aws_instance.logs.*.tags.Hostname))
+      wallet_node_hosts          = join("\n", concat(aws_instance.dashd_wallet.*.tags.Hostname))
+      quorum_list_servers        = join("\n", concat(aws_instance.quorum_list_server.*.tags.Hostname))
+      quorum_list_server_port    = var.quorum_list_server_port
+      mixer_hosts                = join("\n", concat(aws_instance.mixer.*.tags.Hostname))
+      miner_hosts                = join("\n", concat(aws_instance.miner.*.tags.Hostname))
+      masternode_hosts           = join("\n", concat(aws_instance.masternode_amd.*.tags.Hostname), concat(aws_instance.masternode_arm.*.tags.Hostname))
+      hp_masternode_hosts        = join("\n", concat(aws_instance.hp_masternode_amd.*.tags.Hostname), concat(aws_instance.hp_masternode_arm.*.tags.Hostname))
+      seed_hosts                 = join("\n", concat(aws_instance.seed_node.*.tags.Hostname))
+      load_test_hosts            = join("\n", concat(aws_instance.load_test.*.tags.Hostname))
+      metrics_hosts              = join("\n", concat(aws_instance.metrics.*.tags.Hostname))
     }
   )
 }

terraform/aws/instances.tf

@@ -159,6 +159,43 @@ resource "aws_instance" "miner" {
 
 }
 
+resource "aws_instance" "quorum_list_server" {
+  count = var.quorum_list_server_count
+
+  ami                  = var.main_host_arch == "arm64" ? data.aws_ami.ubuntu_arm.id : data.aws_ami.ubuntu_amd.id
+  instance_type        = join(".", [var.main_host_arch == "arm64" ? "t4g" : "t3", var.quorum_list_server_instance_size])
+  key_name             = aws_key_pair.auth.id
+  iam_instance_profile = aws_iam_instance_profile.monitoring.name
+
+  root_block_device {
+    volume_size = var.quorum_list_server_root_disk_size
+    volume_type = var.volume_type
+  }
+
+  vpc_security_group_ids = [
+    aws_security_group.default.id,
+    aws_security_group.quorum_list_server.id,
+  ]
+
+  subnet_id = element(aws_subnet.public.*.id, count.index)
+
+  volume_tags = {
+    Name        = "dn-${terraform.workspace}-quorum-list-server-${count.index + 1}"
+    Hostname    = "quorum-list-server-${count.index + 1}"
+    DashNetwork = terraform.workspace
+  }
+
+  tags = {
+    Name        = "dn-${terraform.workspace}-quorum-list-server-${count.index + 1}"
+    Hostname    = "quorum-list-server-${count.index + 1}"
+    DashNetwork = terraform.workspace
+  }
+
+  lifecycle {
+    ignore_changes = [ami]
+  }
+}
+
 # masternodes (amd)
 resource "aws_instance" "masternode_amd" {
   count = var.masternode_amd_count