Spark Program | Fiber Submarine Swap Service
1. Project Overview
Project Name: Fiber Submarine Swap Service
One-line Summary: A trustless testnet service that solves the inbound liquidity problem for Fiber Network users by enabling atomic swaps between on-chain CKB deposits and Fiber channel capacity.
Project Type: Developer Tool / Infrastructure Prototype
2. Team Profile
2. Team Profile
TerroLabs is a blockchain development company specializing in DeFi solutions, smart contract development, security audits, and developer tooling. The team has contributed to projects including Aave and Maker, with a focus on improving developer experience and ensuring robust security practices across the DeFi ecosystem.
Core Team:
George Abel — Lead Developer & Project Manager Oversees the project, coordinates between team members, manages milestones, and ensures timely delivery. Previously contributed to developer tooling for leading DeFi projects. Extensive experience in TypeScript, JavaScript, and project management. Has built and maintained popular React-based dApps with high user engagement and robust security practices. Twitter:@rustdevrustdev GitHub: divin3circle (Sylus Abel) · GitHub
Martin — Full-Stack Developer Develops the TypeScript/JavaScript backend, Fiber RPC integration, and front-end components. Specialized in React, TypeScript, and has a track record of building robust dApps with a focus on security and performance. Contributed to open-source Ethereum libraries including Ethers.js and participated in multiple DeFi protocol audits.
Christine — Backend Developer Versatile backend developer with expertise in Rust and blockchain technologies. Proven track record of building scalable applications and contributing to innovative blockchain projects. GitHub: chriss1525 (Chriss) · GitHub
Dancan — Infrastructure & DevOps Focuses on backend infrastructure, Docker deployment, and chain integration. Experience building production-grade applications with Java, Spring Boot, and DevOps tooling, including blockchain-adjacent systems. GitHub: Dancan254 (Ian Dancan ) · GitHub
Collective Experience: Over 10 years of combined blockchain development experience across Ethereum, DeFi protocols, and developer tooling. The team’s TypeScript and JavaScript depth maps directly to the tech stack chosen for this project.
Contact: Di@george890128cord: @george890128 Email: [email protected]
3. Project Background
When a new user joins the F@george890128ber Network and opens a payment channel, all of the channel’s capacity starts on their side. This means they can send payments immediately, but they cannot receive any payments until someone else has opened a channel toward them, or they have acquired inbound liquidity through some other mechanism. For most new users this problem is invisible until they actually try to receive their first Fiber payment and nothing arrives. There is currently no community-built service in the Fiber ecosystem that addresses this.
This is not a theoretical edge case. It is a structural property of how all payment channel networks operate, and it is the most common friction point for anyone setting up a new Fiber node. A developer demonstrating Fiber payments to a user, a merchant wanting to accept Fiber payments, or a node operator wanting to participate in routing — all of them hit this wall at the same point in their journey.
On the Lightning Network this problem has been solved for years through a mechanism called a submarine swap: a user pays on-chain Bitcoin, and in exchange receives inbound Lightning channel capacity, with the entire exchange secured atomically so neither party can lose funds if the swap is interrupted or abandoned. On Fiber Network, no equivalent service exists today.
This gap was raised directly by community member janx — one of the most credible technical builders in the Nervos ecosystem — in the Nervos Talk Idea Hunt thread, where he described a Fiber submarine swap as “extremely helpful” for user onboarding. Nobody responded to say they were building it, because nobody is. This proposal exists to fill that specific gap.
4. Solution
The Fiber Submarine Swap Service is a working testnet implementation of the submarine swap mechanism, built in three components that together form a complete, usable, and independently verifiable system.
The first component is the swap backend. This is a service that runs a Fiber Network node funded with a testnet CKB liquidity pool. When a user requests a swap, the backend generates a unique on-chain CKB deposit address for that specific request and monitors the CKB chain for a confirmed deposit to that address. Once the deposit confirms, the backend pushes an equivalent amount of inbound Fiber channel capacity to the requesting user’s node, secured by Fiber’s PTLC mechanism so that the capacity push and the on-chain deposit are atomically linked. Either both sides of the swap complete or neither does — the user and the service cannot lose funds in a failed or partial swap.
The second component is a minimal single-page web interface. The user enters their Fiber node’s public key and their desired inbound capacity amount. The interface displays a CKB deposit address and the amount to send. As the on-chain transaction confirms and the Fiber capacity is pushed, the interface updates in real time through each stage of the swap. There are no accounts, no registration, and no custody of user funds at any point. The interface is deliberately simple — designed to be usable by someone encountering the inbound liquidity problem for the first time.
The third component is the fully open-source repository and documentation. Every line of code is public from the first commit. The README explains how to reproduce the complete swap flow on testnet and how to run an independent instance of the service with custom liquidity. The goal is that any Fiber developer can read the repository and understand not just how to use the service but how it works, so this becomes a reusable foundation for future liquidity tooling.
The key differentiator from everything currently in the Fiber ecosystem: existing projects cover node setup (Fiber Demo Startup), payment integration for apps (fiber-checkout), and forum tipping (Fiber Link). None of them address the liquidity layer. This proposal fills the one gap that directly limits how many users can participate as receivers on the network — a more fundamental problem than any of the existing projects solve.
5. Technical Approach
Tech Stack:
-
Backend: TypeScript (Node.js) — chosen for its strong async I/O handling for chain watching and RPC calls, and for broad familiarity among CKB ecosystem developers who can review and extend the code
-
Chain interaction: C@ckb-lumosB JavaScript SDK (@ckb-lumos/lumos) for on-chain deposit monitoring and transaction construction
-
Fiber RPC: F@ckb-lumosber Network’s JSON-RPC API for node management, channel operations, and payment dispatch
-
Web UI: Plain HTML + vanilla JavaScript — no framework dependency, minimal surface area, easy to audit and fork
-
Infrastructure: Docker Compose for the swap service + Fiber node, making self-hosting straightforward
Architecture Overview:
The system has four logical layers that interact in sequence for each swap:
User Browser (Web UI)
│
▼
Swap API Server (TypeScript / Node.js)
│ │
▼ ▼
CKB Chain Watcher Fiber RPC Client
(lumos, monitors (sends inbound capacity
deposit address) to user’s node via PTLC)
│
▼
CKB Testnet Node
When a user submits a swap request, the API server generates a unique deposit address derived from the swap parameters, registers a chain watcher for that address, and returns the address to the UI. When the watcher detects a confirmed deposit, it triggers the Fiber RPC client to push the corresponding inbound capacity to the user’s node ID via a PTLC-secured Fiber payment. The UI polls the API for status updates and reflects each stage in real time.
Key Technical Challenge — PTLC vs HTLC:
This is the reason no one has built this for Fiber yet. Lightning Network submarine swaps use Hash Time-Locked Contracts (HTLCs), and every existing implementation (Loop, Boltz, etc.) is built on that primitive. Fiber Network uses Point Time-Locked Contracts (PTLCs), which offer better privacy properties but require a different cryptographic locking approach. Existing Lightning swap code cannot be ported directly.
The Week 1 milestone is entirely dedicated to resolving this: auditing Fiber’s RPC documentation and the fiber-scripts repository to confirm exactly how the PTLC locking needs to be structured for the on-chain side of the swap. The output of this investigation is a public technical writeup posted on Nervos Talk before any backend code is written. This ensures the implementation approach is validated and community-reviewed before the main build begins, and it gives the committee a verifiable first milestone that is independent of any subsequent delivery.
6. To-Do List
Week 1 — PTLC Investigation & Research (Milestone 1)
-
Audit Fiber Network RPC documentation for all channel and payment primitives relevant to inbound capacity management
-
Review fiber-scripts repository to identify which on-chain CKB script primitives are available and required for PTLC-secured swap locking
-
Confirm whether current Fiber RPC exposes sufficient hooks for atomic swap coordination, or whether additional on-chain script work is needed
-
Document findings, constraints, and chosen implementation approach
-
Publish technical writeup on Nervos Talk — this is the Milestone 1 deliverable
Week 2 — Swap Backend Core
-
Set up project repository with MIT license, public from day one
-
Implement CKB chain watcher using lumos: monitors a generated deposit address, detects confirmed transactions, extracts deposit amount
-
Implement Fiber RPC client wrapper: connects to a running Fiber node, queries channel state, prepares inbound capacity push
Week 3 — Swap Backend Complete
-
Implement PTLC locking mechanism based on Week 1 findings: links the on-chain deposit to the off-chain Fiber payment atomically
-
Implement deposit confirmation logic with configurable block depth threshold
-
Implement capacity push trigger: on confirmed deposit, dispatches Fiber payment to user’s node ID
-
Implement error handling for incomplete or timed-out swaps — funds must be safely returnable in failure cases
-
Write unit tests for chain watcher and Fiber RPC client
Week 4 — Web UI
-
Build single-page HTML interface: node ID input field, capacity amount selector, deposit address display
-
Implement real-time swap status polling: Pending Deposit → Deposit Confirmed → Capacity Pushed → Complete
-
Add basic error states: deposit timeout, node unreachable, insufficient liquidity
-
Test UI end-to-end against the backend running locally
Week 5 — Testnet Integration & Edge Cases
-
Deploy swap service + Fiber node to a persistent testnet environment
-
Run complete end-to-end swap flows against real Fiber testnet conditions
-
Identify and resolve edge cases that only appear in live network conditions (reorgs, payment routing failures, RPC timeouts)
-
Validate that failed swaps leave both parties’ funds intact
Week 6 — Documentation, Polish & Completion Report
-
Write README: what the service does, how to run the testnet demo, how to run your own instance with custom liquidity
-
Document the PTLC implementation approach in code comments and a dedicated technical section in the README
-
Prepare completion report with all links, verification instructions, and GitHub repo
-
Buffer for committee feedback and any final adjustments
7. Required Funding & Funding Breakdown
Total Requested: $1,000 USD, paid in CKB
The CKB equivalent will be calculated at the time of formal approval per the program’s standard pricing-snapshot convention. Disbursement follows the standard 20% / 80% split.
Milestone 1 — $200 (20%), released upon publication of the Week 1 technical writeup on Nervos Talk
This covers one week of focused technical research: auditing the Fiber RPC documentation and fiber-scripts repository, confirming the PTLC locking approach, and writing the public findings post. The deliverable is a publicly readable document that exists or it does not — this milestone requires zero trust in future delivery.
Milestone 2 — $800 (80%), released upon submission of the completion report
Broken down by category:
-
Swap backend development (Weeks 2–3): $400 — This is the most technically demanding work in the project. It covers the CKB chain watcher implementation, the Fiber RPC client, the PTLC locking mechanism, the deposit confirmation logic, the capacity push trigger, error handling for failed swaps, and unit tests. This is the core of the project and the work that cannot be parallelized or shortcut.
-
Web UI (Week 4): $150 — Single-page interface covering the full user-facing swap flow. Deliberately minimal to keep scope tight and the codebase auditable.
-
Testnet integration and edge case resolution (Week 5): $150 — Running the complete system against live Fiber testnet conditions, identifying and fixing issues that only appear under real network conditions, and validating failure safety.
-
Documentation and completion report (Week 6): $100 — README, technical documentation of the PTLC approach, and the formal Spark completion report with all required materials.
8. Deliverables + How to Verify
Deliverables:
-
Technical investigation writeup published on Nervos Talk — identifies which Fiber RPC calls and CKB on-chain primitives are used, how PTLC locking is structured for the swap, and what constraints were discovered. Completion standard: post exists, is publicly readable, and answers the three scoped questions above.
-
Open-source swap backend — TypeScript/Node.js service implementing the chain watcher, Fiber RPC client, PTLC locking, and swap coordination logic. Completion standard: repository is public on GitHub under MIT license with real commit history from Week 1 onward; npm install && npm start produces a running service per the README.
-
Single-page web UI — HTML interface for submitting swap requests and tracking swap status. Completion standard: accessible at a live URL; entering a valid Fiber testnet node ID and sending the specified CKB to the deposit address results in the UI reaching the “Complete” state.
-
End-to-end testnet demo — complete swap flow running against Fiber testnet. Completion standard: committee member follows the README steps, deposits testnet CKB, and confirms via list_channels Fiber RPC call that inbound capacity has arrived at their node.
-
README and developer documentation — explains what the service does, how to run it, how to run your own instance, and how the PTLC mechanism is implemented. Completion standard: a developer unfamiliar with the project can reproduce the swap flow from scratch using only the README.
How to Verify:
For Milestone 1: Open the Nervos Talk writeup linked in the thread reply. Read it. It should clearly identify which Fiber RPC methods are involved in the swap flow, how the PTLC locking is structured on the CKB on-chain side, and what edge cases or constraints were identified. No special technical setup required — the document is either complete and answers these questions or it is not.
For Milestone 2: The complete verification requires only a standard Fiber testnet node, which is documented in the Fiber Network GitHub repository.
Step 1 — Clone the repository and run npm install && npm start per the README. Confirm the service starts without errors.
Step 2 — Open the swap UI URL from the README. Enter your Fiber testnet node’s public key and a small capacity amount (e.g., 100 CKB equivalent).
Step 3 — Send the specified testnet CKB amount to the deposit address displayed by the UI.
Step 4 — Watch the UI progress through Pending → Confirmed → Complete. This takes as long as the on-chain transaction needs to confirm.
Step 5 — Call the Fiber RPC method list_channels on your testnet node. Confirm that a new inbound balance has appeared for the amount requested. This is a single RPC call that returns human-readable JSON.
Step 6 (optional, for deeper verification) — Read the swap backend source code and the PTLC locking implementation documented in the README. The logic should be legible without specialized CKB expertise due to inline comments.
No code review is required for primary verification. The swap either works end-to-end or it does not.
9. Current State vs. Funded Work
Current State:
-
The inbound liquidity problem and the submarine swap mechanism have been researched and documented — this is reflected in the proposal itself.
-
We have read the Fiber Network RPC documentation and the fiber-scripts repository at a high level.
-
We have engaged with the Nervos Talk community on the topic of PTLC feasibility for submarine swaps, which generated positive engagement and confirmed no one else is building this.
-
No code has been written. No prototype exists. The repository does not yet exist.
Funded Work (what Spark funding enables):
-
Week 1: Deep technical audit of Fiber RPC and CKB script primitives for PTLC swap locking — the foundational research that makes the rest of the build possible and de-risks the timeline.
-
Weeks 2–5: Full implementation of the swap backend, web UI, and testnet integration — everything from a blank repository to a working, verified service.
-
Week 6: Documentation and completion report.
The boundary is clear: today we have research and a proposal. Spark funding produces a working, open-source, community-verifiable testnet service.
10. CKB Alignment
This project is built directly on two of CKB’s most active infrastructure layers in 2026.
Fiber Network: The swap service runs a Fiber Network node and interacts with Fiber’s channel management, payment routing, and PTLC-secured payment primitives via the Fiber RPC. Every swap is a live Fiber Network operation — the service is not an abstraction layer on top of Fiber but a direct participant in the network. Inbound liquidity is a prerequisite for Fiber adoption at scale, and solving it at the community level reduces dependence on the core team to fill this gap.
CKB Cell Model and Scripts: The on-chain side of the swap — the deposit address and the PTLC locking mechanism — is implemented as CKB transactions using the Cell Model. The deposit address is a CKB lock script. The atomic locking between the on-chain deposit and the off-chain Fiber payment uses CKB’s script execution environment. The chain watcher built with lumos monitors the CKB chain directly. This project is not a general-purpose tool that happens to serve CKB developers — it is built on CKB-specific primitives and would not function on any other chain.
The Week 1 technical writeup will document specifically how the Cell Model and CKB script primitives are used in the PTLC locking implementation, making this the most technically detailed section of the project from a CKB-specificity standpoint.