feat(relayer): implement P2P gossip mesh and threshold BLS consensus engine

[mijinummi]

📝 Summary

This PR transitions Velo’s cross-chain HTLC release flow from an isolated, single-relayer execution model to a fault-tolerant, decentralized, threshold-authorized settlement network.

closes #400

Previously, relayer nodes operated independently across Stellar/Soroban and EVM networks, introducing single points of failure, censorship risks, and reliance on single relayer keys. This PR introduces a Libp2p GossipSub mesh for relayer-to-relayer communication and a Threshold BLS Consensus Engine to coordinate and authorize HTLC releases off-chain before on-chain submission.

---

🛠️ Key Architectural Additions

1. Libp2p GossipSub P2P Mesh

• Topic: velo:crosschain:gossip:v1
• Encrypted node-to-node peer discovery, heartbeats, and peer management abstractions.
• Distributed real-time propagation of consensus rounds and partial BLS signature shares across active relayers.

2. Threshold BLS Consensus Engine

• Validates incoming partial BLS shares against target swap IDs and consensus rounds.
• Deduplicates contributions and aggregates valid shares upon reaching the target threshold $k$-of-$n$.
• Prevents competing relayers from racing on-chain release transactions.

3. State Persistence & Concurrency Control

• Database Schema: 018_add_relayer_bls_consensus.sql introduces relayer_nodes, consensus_round_logs, and the consensus_status ENUM.
• Transactional Locking: Enforces SELECT FOR UPDATE on consensus round records to prevent race conditions during concurrent P2P signature submissions.

4. BLS Share Ingestion API & Asynchronous Worker

• Endpoint: POST /api/v1/relayer/bls-share (Zod-validated, returns 202 Accepted).
• Redis State Machine: Handles asynchronous event processing with exponential backoff retry logic:
  $$\text{delayMs} = 500 \times 2^{\text{attempt}} \quad (\text{Max Attempts} = 5)$$
• Dead-Letter Queue (DLQ): Routes unresolvable rounds to velo:bls-dlq.

5. On-Chain Verification Contracts

Extends both target settlement environments to verify aggregated BLS signatures prior to releasing locked funds:

• Soroban (Stellar): contracts/atomic-swap/src/bls_verifier.rs
• EVM (Solidity): contracts-evm/BLSVerifier.sol

6. Relayer Consensus Dashboard

Telemetry dashboard (apps/relayer/src/routes/telemetry.ts) providing real-time visibility into peer connectivity, node health, signature collection progress, and consensus lifecycle state.

---

🛡️ Security & Risk Mitigation Matrix

Identified Threat / Vulnerability	Architectural Solution
Single-Point of Failure / Censorship	Decentralized Libp2p gossip mesh with $k$-of-$n$ consensus requirement.
Relayer Key Compromise	Threshold BLS authorization (requires multiple compromised nodes to forge).
Relayer Transaction Racing	Deterministic off-chain leader assignment post-aggregation.
Mempool/State Race Conditions	Transactional row-level locking (SELECT FOR UPDATE) on consensus state.
Invalid Signature Flooding	Pre-aggregation verification of individual BLS partial signature shares.
Stalled Consensus Rounds	Exponential backoff worker retries + DLQ alerting (velo:bls-dlq).
Untrusted Off-Chain State	On-chain BLS signature verification in Soroban and EVM smart contracts.

---

📁 Key File Modifications

apps/relayer/
├── src/p2p/              # Libp2p node, gossip, protocol definitions
├── src/consensus/        # BLS engine, DKG manager, state machine
├── src/db/migrations/    # Schema 018: BLS consensus tables
├── src/soroban-watcher.ts
└── src/evm-htlc.ts
contracts/
├── atomic-swap/          # Soroban atomic swap & BLS verifier (Rust)
contracts-evm/
├── HTLC.sol              # EVM HTLC contract
└── BLSVerifier.sol       # On-chain EVM BLS verification
packages/shared/          # Consensus shared types & definitions

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
velo	Skipped		Aug 24, 2026 2:19pm
velo-frontend	Skipped		Aug 24, 2026 2:19pm

[jotel-dev]

Thanks for this @mijinummi looks like groundwork (schema + telemetry) rather than the full BLS consensus logic itself. A couple of questions:

1. Is the actual signature aggregation/threshold verification logic coming in a follow-up PR, or is this migration meant to support something already elsewhere in the codebase?
2. For telemetry.ts — is any sensitive data (keys, raw signatures) ever included in the telemetry payload?

Checks are passing and the diff itself looks clean, just want to understand scope before approving.

[jotel-dev]

One more thing — node-ci / build is failing after ~25s. Could you check the logs and fix that up too? Once that's green and my scope/telemetry questions above are answered, happy to approve.