Technical Overview

1. Background & Motivation

Submarine swaps enable atomic, trust-minimized transfers between on-chain CKB and off-chain Fiber Network channels. This feature is modeled after Lightning Loop (Lightning Loop Swap Case Study ) and addresses key liquidity challenges for users who need to move funds between on-chain and off-chain environments without closing channels or relying on custodial services.

Key Use Cases:

• Move funds from Fiber channels to on-chain (Swap Out)
• Move on-chain funds into Fiber channels (Swap In)
• Instant swaps using pre-funded reservations for fast liquidity
• Automated liquidity management (Autoswap) for channel rebalancing

2. Technical Approach

• HTLCs (Hash Time-Locked Contracts): Core mechanism for atomic swaps, implemented as CKB lock scripts with dual spending paths (success with preimage, timeout for refund).
• MuSig2 Reservations: For instant swaps, pre-funded UTXOs use a dedicated Reservation lock script (implemented in this spec) with 2-of-2 MuSig2 cooperative spending and timeout reclaim paths, allowing fast settlement or fallback to HTLC if needed.
• Persistent Storage: All swap state, preimages, reservations, and rules are stored in RocksDB for crash recovery and auditability.
• API: JSON-RPC endpoints for all swap operations, status queries, and autoswap rule management.

3. User Stories & Priorities

1. Swap Out (P1): Move funds from Fiber to on-chain. Highest priority, foundational for all other features.
2. Swap In (P2): Move on-chain funds to Fiber. Complements Swap Out for full bidirectional liquidity.
3. Instant Swap Out (P3): Fast swaps using reservations, optimized for user experience.
4. Autoswap (P4): Automated, rules-based liquidity management for advanced users and routing nodes.

Each user story is independently testable and can be delivered incrementally.

4. Data Model & State Machines