Cacti Interoperability Bridge

A production-style cross-ledger asset transfer bridge inspired by Hyperledger Cacti.

The bridge solves a fundamental problem in multi-chain ecosystems: moving assets between blockchains that have no native awareness of each other. It does this through a pluggable connector model — each ledger gets an adapter that speaks a common interface, and a central orchestrator drives the full transfer lifecycle from policy check to proof verification to minting on the target chain.

Everything here is fully simulated (no real blockchain nodes required), but the architecture is designed so that swapping in real connectors — ethers.js for Ethereum, the Fabric Node SDK for Hyperledger — requires only implementing the ILedgerConnector interface.

What it does

• Accepts cross-ledger transfer requests via a REST API
• Runs transfers through a 10-state lifecycle: policy approval → source lock → proof generation → verification → target mint → completion
• Retries failed transfers automatically, with configurable backoff and retry limits
• Enforces pluggable policy rules (allowed pairs, max amount, asset type, caller auth, rate limit) before any transfer proceeds
• Persists all transfer state and a full audit trail to SQLite
• Exposes Prometheus-compatible metrics and a Swagger UI
• Ships with Docker Compose for one-command local deployment

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                          Client / Admin                              │
└─────────────────────────────┬────────────────────────────────────────┘
                              │ HTTP REST
┌─────────────────────────────▼────────────────────────────────────────┐
│                       API Gateway  :3000                             │
│   POST /transfers   GET /transfers/:id   POST /transfers/:id/retry   │
│   GET  /health      GET /connectors      GET  /metrics               │
└──────────┬──────────────────────────────────────┬────────────────────┘
           │ initiates / queries                  │ reads
┌──────────▼──────────────────────────────────────▼────────────────────┐
│                     Transfer Orchestrator (core)                     │
│  ┌─────────────┐  ┌─────────────────┐  ┌──────────────────────────┐  │
│  │   Policy    │  │  Proof Verifier │  │  Connector Registry      │  │
│  │   Engine    │  │  (abstraction)  │  │  (pluggable adapters)    │  │
│  └─────────────┘  └─────────────────┘  └──────────────────────────┘  │
└──────────┬───────────────────────────────────────────────────────────┘
           │ reads/writes
┌──────────▼───────────────────────────────────────────────────────────┐
│               SQLite Persistence  (better-sqlite3)                   │
│              transfers table │ audit_log table                       │
└──────────────────────────────────────────────────────────────────────┘
           ▲
           │ polls (interval)
┌──────────┴───────────────────────────────────────────────────────────┐
│                    Relay Worker  :3001                               │
│         Finds pending transfers → drives them to completion          │
└──────────────────────────────────────────────────────────────────────┘

---

Transfer Lifecycle

REQUESTED
   │
   ▼  (policy evaluation)
POLICY_APPROVED ──── FAILED
   │
   ▼  (lock asset on source ledger)
SOURCE_LOCKED ─────── FAILED
   │
   ▼  (generate cross-chain proof)
PROOF_GENERATED ───── FAILED
   │
   ▼  (verify proof)
VERIFIED ──────────── FAILED
   │
   ▼  (mint representation on target ledger)
TARGET_MINTED ─────── FAILED
   │
   ▼  (finalize)
COMPLETED

FAILED ──────────────► ROLLBACK_PENDING ──► ROLLED_BACK
       (manual rollback)

---

Stack

TypeScript · Node.js · pnpm workspaces · Express · better-sqlite3 · Zod · Pino · Vitest · Docker

Docs

See diagrams.md for architecture diagrams, transfer lifecycle, monorepo structure, API reference, setup guide, failure simulation, policy configuration, and testing instructions.