ChainBridge is a trustless cross-chain atomic swap protocol built on Stellar's Soroban smart contract platform. It enables peer-to-peer swapping of assets between Stellar and other blockchains without requiring wrapped tokens, custodians, or trusted third parties.
The architecture is designed around the Hash Time-Locked Contract (HTLC) pattern, which guarantees atomicity - either both sides of the swap complete successfully, or both parties can refund their funds.
┌─────────────────────────────────────────────────────────────────────────┐
│ USER INTERACTION LAYER │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ Web Frontend │ │ Mobile Apps │ │ Third-Party Integrations│ │
│ │ (Next.js) │ │ (Future) │ │ (API Access) │ │
│ └────────┬────────┘ └─────────────────┘ └───────────┬─────────────┘ │
└───────────┼─────────────────────────────────────────────┼───────────────┘
│ │
│ REST API │ WebSocket
▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ BACKEND SERVICES LAYER │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Application │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │ │
│ │ │ Order │ │ Swap │ │ Proof │ │ Analytics & │ │ │
│ │ │ Matching │ │ Manager │ │ Verifier │ │ Monitoring │ │ │
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────────┬─────────┘ │ │
│ └───────┼────────────┼────────────┼─────────────────┼─────────────┘ │
│ │ │ │ │ │
│ ┌───────▼────────────▼────────────▼─────────────────▼─────────────┐ │
│ │ PostgreSQL + Redis Cache │ │
│ │ • Swap orders • Swap states • Proof data • Metrics │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ Soroban RPC
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STELLAR SOROBAN LAYER │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ ChainBridge Smart Contract │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ │
│ │ │ HTLC Module │ │ Order Module │ │ Swap Module │ │ │
│ │ │ ──────────── │ │ ──────────── │ │ ──────────── │ │ │
│ │ │ • create_htlc │ │ • create_order │ │ • verify_proof │ │ │
│ │ │ • claim_htlc │ │ • match_order │ │ • complete_swap │ │ │
│ │ │ • refund_htlc │ │ • cancel_order │ │ • get_swap │ │ │
│ │ │ • get_htlc │ │ • get_order │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ └──────────────────┘ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ Storage Layer (Persistent) │ │ │
│ │ │ • HTLC records • Order book • Swap states • Config │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ Events & Proofs
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ RELAYER NETWORK LAYER │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Relayer Infrastructure │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │
│ │ │ Chain Monitor│ │ Proof Gen │ │ Event Indexer │ │ │
│ │ │ ──────────── │ │ ──────────── │ │ ───────────────── │ │ │
│ │ │ • Bitcoin │ │ • SPV proofs │ │ • HTLC events │ │ │
│ │ │ • Ethereum │ │ • Merkle │ │ • Claim events │ │ │
│ │ │ • Solana │ │ • Signatures │ │ • Refund events │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ Light Client Implementations │ │ │
│ │ │ • Bitcoin SPV • Ethereum Light Client • Solana RPC │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ Network Connections
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL BLOCKCHAINS │
│ ┌─────────────┐ ┌─────────────────┐ ┌──────────────────────────┐ │
│ │ Bitcoin │ │ Ethereum │ │ Solana │ │
│ │ Network │ │ Network │ │ Network │ │
│ │ ───────── │ │ ───────────── │ │ ─────────────────── │ │
│ │ • HTLC txs │ │ • HTLC contract │ │ • HTLC program │ │
│ │ • Scripts │ │ • Events │ │ • Instructions │ │
│ └─────────────┘ └─────────────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
The smart contract is the heart of ChainBridge, deployed on Stellar's Soroban platform. It manages all swap logic, HTLC creation, and state management.
HTLC Module (smartcontract/src/htlc.rs)
- Creates and manages Hash Time-Locked Contracts
- Validates secrets against hash locks
- Enforces timelock constraints
- Handles claim and refund operations
Order Module (smartcontract/src/order.rs)
- Manages the decentralized order book
- Creates and matches swap orders
- Tracks order lifecycle
- Enforces order validity periods
Swap Module (smartcontract/src/swap.rs)
- Coordinates cross-chain swap execution
- Verifies cross-chain proofs
- Manages swap completion workflow
- Emits events for relayer tracking
Storage Module (smartcontract/src/storage.rs)
- Persistent storage for HTLCs, orders, and swaps
- Instance storage for counters and admin
- Efficient key-value data structures
// HTLC Structure
pub struct HTLC {
sender: Address, // Creator of the HTLC
receiver: Address, // Intended recipient
amount: i128, // Amount locked
hash_lock: Bytes, // SHA256 hash of the secret
time_lock: u64, // Unix timestamp for expiry
status: HTLCStatus, // Active, Claimed, Refunded, Expired
secret: Option<Bytes>, // Revealed secret (if claimed)
created_at: u64, // Creation timestamp
}
// Swap Order Structure
pub struct SwapOrder {
id: u64,
creator: Address,
from_chain: Chain,
to_chain: Chain,
from_asset: String,
to_asset: String,
from_amount: i128,
to_amount: i128,
expiry: u64,
matched: bool,
counterparty: Option<Address>,
}
// Cross-Chain Swap Structure
pub struct CrossChainSwap {
id: u64,
stellar_htlc_id: u64,
other_chain: Chain,
other_chain_tx: String, // Transaction hash on other chain
stellar_party: Address,
other_party: String,
completed: bool,
}The backend provides REST API access, order matching, and integration services.
FastAPI Application (backend/app/main.py)
- RESTful API endpoints for swap operations
- WebSocket support for real-time updates
- CORS middleware for frontend integration
- Health checks and monitoring endpoints
Planned Services:
- Order Matching Engine: Matches compatible swap orders
- Proof Verification Service: Validates cross-chain proofs
- Analytics Service: Tracks swap metrics and success rates
- Notification Service: Alerts users of swap events
| Component | Technology | Purpose |
|---|---|---|
| Web Framework | FastAPI | High-performance async API |
| Database | PostgreSQL | Persistent data storage |
| Cache | Redis | Fast state caching, pub/sub |
| ORM | SQLAlchemy | Database models and queries |
| Task Queue | Celery | Async job processing |
The relayer network monitors external blockchains and facilitates cross-chain communication.
┌──────────────────────────────────────────────────────────────┐
│ Relayer Process │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Chain Monitor Service │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │
│ │ │ Bitcoin RPC │ │ Ethereum RPC │ │ Solana RPC │ │ │
│ │ │ Connection │ │ Connection │ │ Connection │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬──────┘ │ │
│ └─────────┼─────────────────┼─────────────────┼─────────┘ │
│ │ │ │ │
│ ┌─────────▼─────────────────▼─────────────────▼─────────┐ │
│ │ Event Processing Pipeline │ │
│ │ • HTLC Created Events │ │
│ │ • HTLC Claimed Events │ │
│ │ • HTLC Refunded Events │ │
│ │ • Secret Revealed Events │ │
│ └────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼───────────────────────────────────┐ │
│ │ Proof Generation Service │ │
│ │ • SPV Proof Generation (Bitcoin) │ │
│ │ • Merkle Proof Generation (Ethereum) │ │
│ │ • Transaction Receipt Proofs │ │
│ └────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼───────────────────────────────────┐ │
│ │ Stellar Submission Service │ │
│ │ • Invoke Soroban contract methods │ │
│ │ • Submit proofs to ChainBridge contract │ │
│ │ • Update swap statuses │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
-
Chain Monitoring
- Watch for HTLC creation events on external chains
- Detect HTLC claims and secret revelations
- Monitor timelock expirations
-
Proof Generation
- Generate SPV proofs for Bitcoin transactions
- Create Merkle proofs for Ethereum events
- Compile transaction inclusion proofs
-
Cross-Chain Communication
- Submit proofs to Stellar smart contract
- Trigger swap completion flows
- Emit events for backend tracking
The frontend provides the user interface for creating and executing swaps.
┌──────────────────────────────────────────────────────────────┐
│ Next.js Application │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Pages │ │
│ │ • Home (Swap Dashboard) │ │
│ │ • Create Swap │ │
│ │ • Browse Orders │ │
│ │ • Active Swaps │ │
│ │ • History │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Components │ │
│ │ • Wallet Connection (Freighter, MetaMask, etc.) │ │
│ │ • Swap Form │ │
│ │ • Order Book │ │
│ │ • Swap Tracker │ │
│ │ • Transaction History │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Services │ │
│ │ • Stellar SDK Integration │ │
│ │ • Ethereum/Web3 Integration │ │
│ │ • Bitcoin Integration │ │
│ │ • Backend API Client │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
User Frontend Backend Smart Contract
│ │ │ │
│──Create Order───────>│ │ │
│ │──POST /orders──────>│ │
│ │ │──create_order()────>│
│ │ │<─────Order ID───────│
│ │<────Order ID───────│ │
│<──Order Created─────│ │ │
│ │ │ │
Alice Bob Stellar HTLC Bitcoin HTLC
│ │ │ │
│──Lock XLM─────────────────────────────>│ │
│ │ │ │
│<──HTLC Created────│─────────────────────│ │
│ │ │ │
│ │──Lock BTC──────────────────────────────────>│
│ │ │ │
│ │<──HTLC Created──────│──────────────────────│
│ │ │ │
│──Claim BTC (reveal secret)──────────────────────────────────────>│
│ │ │ │
│ │<──Secret Revealed───│──────────────────────│
│ │ │ │
│ │──Claim XLM (use secret)──>│ │
│ │ │<─────Claim───────────│
│ │ │ │
Bitcoin Network Relayer Stellar Contract Backend
│ │ │ │
│──HTLC Event──>│ │ │
│ │──Generate Proof─── │ │
│ │ │ │
│ │──verify_proof()────>│ │
│ │ │──Event Emitted──>│
│ │ │ │
│ │ │<──Update Swap───│
│ │ │ │
┌──────┐ ┌──────┐ ┌──────────┐ ┌───────┐ ┌──────────┐
│Alice │ │ Bob │ │ Stellar │ │Relayer│ │ Bitcoin │
│ │ │ │ │ Contract │ │ │ │ Network │
└──┬───┘ └──┬───┘ └────┬─────┘ └───┬───┘ └────┬─────┘
│ │ │ │ │
│ 1. Generate │ │ │ │
│ Secret S │ │ │ │
│ Hash H │ │ │ │
│ │ │ │ │
│ 2. Create Order│ │ │ │
│────────────────>│ │ │ │
│ │ │ │ │
│ │ 3. Match Order │ │ │
│<────────────────│ │ │ │
│ │ │ │ │
│ 4. Create HTLC │ │ │ │
│ (H, 24h) │ │ │ │
│─────────────────────────────────────>│ │ │
│ │ │ │ │
│ │ 5. Verify Lock │ │ │
│ │───────────────────────────────────────>│ │
│ │ │ │ │
│ │ 6. Create HTLC │ │ │
│ │ (H, 12h) │ │ │
│ │──────────────────────────────────────────────────────────>│
│ │ │ │ │
│ 7. Verify Lock │ │ │ │
│─────────────────────────────────────────────────────────>│ │
│ │ │ │ │
│ 8. Claim BTC │ │ │ │
│ (reveal S) │ │ │ │
│──────────────────────────────────────────────────────────────────────────────>│
│ │ │ │ │
│ │ 9. Detect Secret │ │ │
│ │<──────────────────────────────────────────────────────────│
│ │ │ │ │
│ │ 10. Claim XLM │ │ │
│ │ (use S) │ │ │
│ │─────────────────────────────────────>│ │
│ │ │ │ │
│ │ │ 11. Swap Complete│ │
│ │ │<──────────────────│ │
│ │ │ │ │
The HTLC protocol ensures atomic swaps through:
- Hash Lock: Funds can only be claimed by revealing the preimage
- Time Lock: Funds can be refunded after timeout
- Cascading Timeouts: Earlier timeouts on the receiving chain prevent race conditions
| Component | Trust Level | Rationale |
|---|---|---|
| Stellar Network | Minimal | Decentralized, battle-tested |
| Soroban Contract | Audited | Open-source, verifiable |
| Counterparty | None | HTLC ensures fair exchange |
| Relayers | Minimal | Only submit proofs, no custody |
| Backend | Minimal | No access to funds |
- Risk: Attacker observes secret revelation and front-runs claim
- Mitigation: Secret revealed on destination chain first, giving initiator claim priority
- Risk: Counterparty waits until last moment to claim
- Mitigation: Cascading timelocks ensure ample time for both parties
- Risk: Relayers refuse to submit proofs
- Mitigation: Anyone can submit proofs (decentralized)
- Risk: Vulnerabilities in contract code
- Mitigation: Formal verification, audits, bug bounties
- Throughput: Limited by Stellar's transaction capacity
- Finality: Dependent on external chain confirmation times
- Storage: On-chain storage costs for HTLC data
- Batch Processing: Group multiple swaps in single transactions
- Layer 2: Integrate with Stellar's future L2 solutions
- Optimistic Proofs: Use optimistic verification for faster swaps
- State Channels: Off-chain swap negotiation
┌─────────────────────────────────────────────────────────────┐
│ Docker Compose │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ Backend │ │ PostgreSQL │ │ Redis │ │
│ │ Container │ │ Container │ │ Container │ │
│ └──────────────┘ └──────────────┘ └────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Local Stellar Testnet (Future) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ ┌────────────────────────────────────────────────────────┐│
│ │ Ingress Controller ││
│ └────────────────────┬───────────────────────────────────┘│
│ │ │
│ ┌────────────────────▼───────────────────────────────────┐│
│ │ API Deployment (3 replicas) ││
│ └────────────────────────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────┐│
│ │ Relayer Deployment (2 replicas) ││
│ └────────────────────────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────┐│
│ │ Managed PostgreSQL (Cloud Provider) ││
│ └────────────────────────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────┐│
│ │ Managed Redis (Cloud Provider) ││
│ └────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
-
Swap Metrics
- Total swaps created
- Success rate
- Average completion time
- Volume by asset pair
-
Relayer Metrics
- Events processed
- Proof generation time
- Transaction submission success rate
-
System Metrics
- API response times
- Database query performance
- Cache hit rates
- Structured Logging: JSON format for easy parsing
- Log Levels: DEBUG, INFO, WARN, ERROR
- Sensitive Data: Never log private keys or secrets
- Retention: 30 days for operational logs
- Swap failures exceeding threshold
- Relayer downtime
- Smart contract errors
- High latency alerts
- Incentivized relayer network with stake-based rewards
- Reputation system for relayer reliability
- Distributed key generation for multi-sig operations
- AMM integration for instant swaps
- Governance DAO for protocol upgrades
- Cross-chain message passing for DeFi composability