[FEAT] Cross-Chain Relayer P2P Gossip Mesh & Threshold BLS Consensus Engine

[jotel-dev]

[FEAT] Cross-Chain Relayer P2P Gossip Mesh & Threshold BLS Consensus Engine

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Velo's relayer nodes in apps/relayer currently operate as isolated single-node watchers (apps/relayer/src/soroban-watcher.ts and apps/relayer/src/evm-htlc.ts). This creates single points of failure, censorship risks, and key compromise vulnerabilities during cross-chain HTLC releases between Stellar and EVM networks.

This feature implements a Cross-Chain Relayer P2P Gossip Mesh & Threshold BLS Consensus Engine. It connects relayer nodes over an encrypted Libp2p gossip network, aggregates threshold BLS signatures off-chain, and submits verified aggregate signatures to Soroban (contracts/atomic-swap/src/lib.rs) and EVM (contracts-evm/HTLC.sol) contracts.

---

2. Background & Architectural Risks

• Censorship & Single Point of Failure: A single relayer node going offline or censoring transactions halts cross-chain claims.
• Key Compromise: Single-key relayer architectures allow compromised keys to drain cross-chain HTLC escrows.
• Race Condition Finality: Without off-chain BLS consensus, relayers can race competing release transactions on-chain.

---

3. Database Layer Specifications

Migration SQL (018_add_relayer_bls_consensus.sql)

CREATE TYPE consensus_status AS ENUM ('PROPOSED', 'VOTING', 'AGGREGATED', 'SUBMITTED', 'FAILED');

CREATE TABLE relayer_nodes (
    peer_id VARCHAR(64) PRIMARY KEY,
    bls_pubkey VARCHAR(192) NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE consensus_round_logs (
    round_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    swap_id VARCHAR(64) NOT NULL,
    threshold_required INT NOT NULL,
    signatures_collected INT NOT NULL DEFAULT 0,
    aggregate_signature TEXT NULL,
    status consensus_status NOT NULL DEFAULT 'PROPOSED',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Data Locking (SELECT FOR UPDATE)

BEGIN;
SELECT round_id, status FROM consensus_round_logs WHERE swap_id = $1 FOR UPDATE;
-- Process BLS signature share and update aggregate status...
COMMIT;

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/relayer/bls-share

1. Validation: Zod validates swapId, peerId, and partialSignature.
2. Locking: DB transaction acquires SELECT FOR UPDATE on consensus_round_logs.
3. BLS Partial Verification: Verifies BLS signature share against node public key.
4. Aggregate Check: If threshold $t$-of-$n$ is met, aggregates signatures into single BLS signature.
5. Response: Returns HTTP 202 Accepted with consensus round status.

Request Schema (Zod)

export const BlsShareRequestSchema = z.object({
  swapId: z.string().length(64),
  peerId: z.string().min(10),
  partialSignature: z.string().min(96),
});

---

5. Background Processors / Workers

Redis P2P Consensus Worker (apps/relayer/src/consensus/state-machine.ts)

• P2P Topic: Libp2p GossipSub velo:crosschain:gossip:v1.
• Retries: Max 5 attempts with exponential backoff (delayMs = 500 * 2^attempt).
• DLQ: Un-resolvable rounds routed to velo:bls-dlq.

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/pages/RelayerConsensusDashboard.tsx

• Visualizer: Real-time mesh peer graph rendering node health and BLS signature aggregation progress bars.
• States: Displays PROPOSED -> COLLECTING_SHARES -> BLS_AGGREGATED -> ON_CHAIN_SETTLED.

---

7. Rigor & Test Plan

1. Unit Tests (apps/relayer/src/__tests__/bls-consensus.test.ts): Verify BLS share aggregation math.
2. 5-Node Mesh Integration Test (tests/e2e/cross_chain_consensus_e2e.test.ts): 5-node cluster achieving 3-of-5 threshold BLS release.

---

8. Relevant Files Inventory (20 Files)

• apps/relayer/src/p2p/node.ts
• apps/relayer/src/p2p/gossip.ts
• apps/relayer/src/p2p/protocol.ts
• apps/relayer/src/consensus/bls-engine.ts
• apps/relayer/src/consensus/dkg-manager.ts
• apps/relayer/src/consensus/state-machine.ts
• apps/relayer/src/db/migrations/018_add_relayer_bls_consensus.sql
• apps/relayer/src/routes/telemetry.ts
• apps/relayer/src/soroban-watcher.ts
• apps/relayer/src/evm-htlc.ts
• contracts/atomic-swap/src/lib.rs
• contracts/atomic-swap/src/bls_verifier.rs
• contracts-evm/HTLC.sol
• contracts-evm/BLSVerifier.sol
• apps/api/src/lib/stellar.ts
• packages/shared/src/types/consensus.ts
• packages/shared/src/index.ts
• apps/relayer/src/__tests__/bls-consensus.test.ts
• contracts/atomic-swap/src/bls_test.rs
• tests/e2e/cross_chain_consensus_e2e.test.ts

---

9. Acceptance Criteria

• 5-node relayer network achieves BLS consensus.
• On-chain contracts verify BLS signatures in Rust and Solidity.
• Equivocating nodes are excluded from DKG.

---

10. Contributor Notes

• ⚠️ Crypto Safety: NEVER process unverified BLS signature shares without checking Against peer DKG public keys.

[mijinummi]

Hello maintainers I'm a full stack developer experience in building scalable systems I can handle this perfectly

[grantfox-oss]

🦊 GrantFox — @mijinummi has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #400)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.

[mijinummi]

Hello @jotel-dev , please kindly review

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@mijinummi's PR #425 was approved and merged by @jotel-dev.

🏆 @mijinummi: You earned 45 FoxPoints for this contribution! Your current tier: Specialist (3,245 total points). Track your full progress on GrantFox.

👏 Great work, @mijinummi! Keep contributing to Nullifier-Systems.