Spark Program | Fiber RGB++ Swap
Tags: Spark-Program
1. Project Overview
Project name: Fiber RGB++ Swap
One-sentence summary: A working, atomic path that takes an RGB++ asset locked on Bitcoin, converts it via RGB++'s existing leap mechanism into a standard CKB asset, and swaps it through a Fiber Network channel for a target CKB asset — with the conversion and the swap composed so that they succeed or fail together, never leaving funds stranded mid-way.
Project type: Developer tool / protocol extension — a module built directly on top of Fiber Network’s existing Cross-Chain Hub (CCH) code.
Context for reviewers: this is a resubmission. The committee’s earlier feedback (Pending status) asked specifically for clearer, individually verifiable deliverables mapped to milestones, and objective, non-code-review verification criteria — including how atomic-swap correctness, edge cases, and security are tested. This revision restructures the entire proposal around that feedback, most visibly in Sections 6 and 8 below.
2. Team Profile
Core member: Carl — Solo developer, project lead and sole contributor. No collaborators on this application.
Contact:oxdev6 (Oxdev) · GitHub
-
Discord: carlcn6
-
Email: [email protected]
-
Telegram: carl6
-
GitHub: @oxdev6
3. Project Background
Fiber’s Cross-Chain Hub (CCH) module already proves atomic cross-chain swaps work at the protocol level, and it’s worth being precise about what “already works” means here, since the whole case for this project rests on the distinction between what’s proven and what’s missing. A hub operator runs both a Fiber node and a Lightning node simultaneously. When a user wants to swap BTC held on Lightning for wrapped BTC on Fiber, the hub locks funds on both sides using the same HTLC payment hash — meaning either both legs of the swap settle, or neither does, with no custodian ever holding both assets at once and no bridge-style waiting period. This is live, shipped code, not a whitepaper concept.
But it was built to prove the mechanism, not to be general. In an April 2026 GitHub discussion titled “Fiber CCH Summary and Future Plan” (nervosnetwork/fiber Discussion #1243), the Fiber core team described its current state without ambiguity: CCH supports exactly one asset pair — BTC against a single, hard-coded wrapped-BTC type script — at a fixed 1:1 ratio. There is no negotiation mechanism, no way for a hub operator to add a second asset pair, and no way for a client to discover which hub supports what, since discovery of a second option isn’t possible when only one option can ever exist. In that same discussion, the core team names the fix themselves: hub operators broadcasting signed advertisements describing which assets and rates they support, discoverable by clients before a swap is initiated. This proposal is not asserting a gap the team disputes — it’s built directly from their own dated, public description of unfinished work.
Here’s the concrete scenario this creates today: someone holds an RGB++ asset — a token issued on Bitcoin using RGB++'s isomorphic binding model — and wants it represented as a native CKB asset, so they can use it inside CKB’s ecosystem of dApps, DeFi, or Fiber-speed payments. Fiber’s own protocol design already lists RGB++ assets as a supported channel asset class, meaning the protocol was built with this use case in mind. But there is currently no way to actually execute that move quickly and non-custodially. The user’s only options today are slower bridge processes or trusting a third party to hold funds during the transfer — the exact problems Fiber and CCH were built to eliminate for BTC, just not yet extended to this second, increasingly important asset type.
This isn’t a narrow technical curiosity — it sits at the center of where CKB says it’s heading. RGB++ is the mechanism that lets Bitcoin-native value move onto CKB in the first place; Fiber is the layer meant to make that value usable at Lightning speed once it’s there. Today, those two pieces of the same ecosystem, both built by the same core team, don’t talk to each other. Closing that gap isn’t a side project — it’s finishing a connection the protocol’s own architecture already anticipated.
One structural detail is worth stating plainly here, because it shapes the entire design in Section 4: an RGB++ asset’s Bitcoin-bound state is represented by a specific lock script on its CKB cell (the RGB++ lock, tied to a Bitcoin UTXO via a single-use-seal), while a Fiber channel’s funding cell must use the 2-of-2 funding lock derived from both parties’ pubkeys, since that lock is what makes the channel’s dispute and settlement mechanism work. A CKB cell can only carry one lock script — so an RGB+±bound asset cannot sit inside a funding cell in its native, Bitcoin-bound form. This isn’t a flaw to design around quietly; it’s why RGB++ already has a “leap” mechanism — a one-time, on-chain conversion between the Bitcoin-bound RGB++ lock and a standard CKB UDT cell, and back again. This project uses that existing leap mechanism at the boundary rather than inventing a way around the lock conflict, which is detailed in Section 4.
Fiber RGB++ Swap
(extends nervosnetwork/fiber fiber-lib/src/cch/)
┌─────────────────────────┐ ┌─────────────────────────┐
│ Advertisement layer │ │ Client (CLI + JS) │
│ Broadcasts rates over │ │ Drives leap, then swap │
│ gossip │ │ │
└─────────────────────────┘ └─────────────────────────┘
┌─────────────────────────┐ ┌─────────────────────────┐
│ Leap integration │ │ Swap execution │
│ Existing RGB++ leap tx │ │ Generalized CCH HTLC │
└─────────────────────────┘ └─────────────────────────┘
Prior art, addressed directly: this general shape — a market where operators advertise terms and clients discover them before committing — isn’t a new idea; it’s structurally close to Lightning’s own Liquidity Ads, where nodes advertise available channel capacity and rates so peers can discover terms before opening a channel, rather than negotiating out of band. Similar discussions have happened in the RGB Lightning community, but they largely stalled on getting the asset transport primitive itself right — moving an RGB-class asset through a Lightning-style channel at all. Fiber sidesteps that specific wall: it already carries RGB++ assets as a native channel asset type, so the hard transport problem is already solved at the protocol level. That’s what makes the market/discovery layer buildable now, in a way it wasn’t yet for RGB Lightning: this project isn’t solving asset transport, it’s building the discovery and negotiation layer on top of transport that already works.
4. Solution
RGB++ asset on Bitcoin
(locked via single-use-seal)
│
▼
Leap transaction
(existing RGB++ mechanism)
│
▼
Standard CKB UDT
(recoverable if swap fails here)
│
▼
Discover hub
(matches a swap advertisement)
│
▼
Fiber swap
(generalized CCH HTLC)
│
▼
Target CKB asset
Core approach: two additions to CCH, built in a deliberate order so that each piece is independently useful and testable rather than one large opaque build.
The first is an advertisement mechanism — a way for a hub operator to declare, in a signed and broadcast message, that they support a second asset pair (RGB++ against a CKB asset) and at what rate. This exists because CCH today has no concept of “more than one pair” at all; without this piece, there’s no way for a second asset to exist on CCH in the first place, regardless of whether the swap logic itself works.
The second is the leap-and-swap execution path, named accurately for what it actually does: since an RGB+±bound asset cannot sit inside a Fiber funding cell directly (Section 3 explains why), the asset first leaps — using RGB++'s existing, already-implemented leap mechanism, not a new one built by this project — from its Bitcoin-bound RGB++ lock into a standard CKB UDT. That leap is a single on-chain event touching both Bitcoin and CKB once, not something repeated per channel update. Once leaped, the asset is a normal UDT and can enter a Fiber channel like any other channel asset, where it’s then swapped for the target CKB asset using CCH’s existing commit-and-reveal pattern, generalized to this new asset pair. The client built in this project composes both steps — leap, then swap — into one user-facing flow, and treats them as a single atomic unit: if the leap succeeds but the swap fails to complete, the client automatically reverses or completes the pending state rather than leaving the user holding an intermediate UDT they didn’t ask for. This composition, not the leap or the swap individually, is the actual novel engineering work here, since both underlying primitives already exist separately.
From the user’s side, this still collapses into a simple flow: someone holding an RGB++ token on Bitcoin runs the swap client, which finds a hub currently offering that target asset pair, initiates the leap-and-swap, and ends up holding the target CKB asset — without needing to understand that a leap happened underneath, or manually run the leap and the swap as two separate steps themselves. There’s no bridge interface to learn, no multi-step manual process, and no point in the flow where a third party is holding funds mid-transition.
What makes this different from “just another bridge”: it isn’t a new bridge, and it doesn’t introduce a new cryptographic primitive that needs to be trusted or audited from scratch. It reuses two things that already exist and already work independently — CCH’s proven atomic-swap mechanism, and Fiber’s existing support for RGB++ as a channel asset — and builds the specific connective piece between them that currently doesn’t exist, per the core team’s own account of their roadmap. The engineering risk here is real but bounded: it’s about correctly generalizing existing, working logic to a second case, not inventing new trust assumptions.
5. Technical Approach
Stack: Rust, extending nervosnetwork/fiber’s existing fiber-lib/src/cch/ module directly rather than building a separate service that wraps it; TypeScript for the accompanying JS client, so the swap can be triggered from a web dApp and not only a terminal.
Architecture, piece by piece:
Advertisement layer — a new SwapAdvertisement message type carrying the asset pair being offered, the rate and fee, the operator’s public key, a signature over the message, and an expiry timestamp so stale offers don’t linger indefinitely. This rides Fiber’s existing peer gossip layer — the same broadcast/refresh mechanism already used today for node and channel announcements — deliberately, so this project isn’t introducing a new network transport or a new class of infrastructure to run and secure. A listening node simply gains the ability to also recognize and index this new message type.
Leap layer — the RGB++ asset’s transition out of its Bitcoin-bound lock uses RGB++'s existing leap transaction construction (via the existing rgbpp SDK/tooling), not a reimplementation. This project’s work here is composition, not invention: calling the existing leap flow as the first step of a larger user-facing action, and holding the resulting UDT in an intermediate state the client tracks until the swap leg either completes or is rolled back.
On-chain commitment frequency, addressed directly: it’s worth being explicit that Bitcoin does not see a commitment for every off-chain action here. The leap transaction touches Bitcoin exactly once, at entry (and once more at exit, if a user later leaps the asset back to its Bitcoin-bound form). Once inside the channel, the asset circulates as a standard UDT under Fiber’s own revocable-commitment scheme — each new channel state revokes the previous one, and only the final state is ever broadcast, at settlement or close, mirroring how Lightning and Fiber already handle channel updates generally. This is the same shape as RGB++'s own “transaction folding” concept: many off-chain transfers, one on-chain commitment, just applied at the leap boundary rather than per transfer. Bitcoin involvement is concentrated at the two boundary crossings, not spread across every update inside the channel.
Swap execution layer — once the asset exists as a standard UDT, CCH’s existing HTLC lock-and-reveal logic, currently hard-coded to the BTC/wrapped-BTC pair, is generalized to accept this UDT as a second asset type, swapped against the target CKB asset. Because both sides of this particular swap leg are CKB-native at this point (the leap already happened), this leg avoids Bitcoin-Lightning-side finality entirely — it inherits Fiber’s own channel-state finality, using the same revocable-commitment pattern (each new channel state revokes the previous one) already proven in CCH. The core design goal is minimal surface area: extend the existing state machine to parametrize over asset type rather than writing a second, parallel swap implementation that could drift out of sync with the first.
Client — a CLI (fiber-rgbpp-swap) that performs the full user-facing flow: query active advertisements, select a hub and pair, trigger the leap, confirm the leap on-chain, initiate the swap, and confirm settlement — printing transaction references at each stage the user (or a reviewer) can independently check. A minimal JS client wraps the same underlying calls so a web dApp can trigger the identical flow programmatically.
The hardest technical problem, named directly: it’s not cross-chain atomicity in the classic sense — since the leap resolves Bitcoin-side finality before the swap ever begins, the swap leg itself is CKB/Fiber-native and inherits CCH’s already-proven atomicity guarantees. The actual hard problem is composing two independently-atomic operations (leap, then swap) into one user-facing action that’s atomic as a pair: if the leap succeeds but the swap subsequently fails or times out, the user must not be left holding a UDT in limbo with no clear path forward. This is addressed by having the client treat the leaped UDT as recoverable at every stage — if the swap doesn’t complete, the client’s fallback path simply leaves the user holding the plain UDT they leaped to (a strictly better outcome than the RGB+±bound asset they started with, and never a stuck or lost state), rather than attempting to automatically reverse the leap itself, which would reintroduce the same cross-chain-finality complexity the leap-first design was meant to avoid. This failure path is treated as a first-class deliverable, not an afterthought: Section 6 dedicates explicit build time to it, and Section 8 requires it be demonstrated on video, not just asserted in writing.
Language: all documentation and code comments are in English, satisfying the template’s minimum-language requirement, though I’m glad to also produce a Chinese-language summary if that would help committee members who prefer it.
6. To-Do List
Week 1 — Foundation and risk reduction. Read fiber-lib/src/cch/ and the existing gossip/announcement code in depth before writing new code, so the implementation extends the existing patterns rather than fighting them. Post the project’s direction in Discussion #1243 specifically to ask whether anyone is already building the advertisement/negotiation piece, closing the “duplicate effort” risk in week one rather than discovering it in week four. Finalize the exact SwapAdvertisement message schema.
Week 2 — Advertisement mechanism. Implement SwapAdvertisement signing and verification, and integrate broadcast into Fiber’s existing gossip cycle. Milestone: a hub node running on testnet successfully broadcasts an RGB++ asset-pair advertisement, and a separately run listening node receives and correctly parses it. This is the first independently checkable proof of progress, and it’s checkable without touching the swap logic at all.
Week 3 — Leap integration and swap logic. Integrate RGB++'s existing leap transaction construction into the client as the first stage of the flow, and confirm it reliably converts an RGB+±bound asset into a standard UDT on testnet. In parallel, generalize CCH’s HTLC lock-and-reveal state machine to accept that UDT as a second swappable asset type, alongside the existing BTC/wrapped-BTC pair.
Week 4 — Client integration and first live leap-and-swap. Build the CLI client that chains both stages together: trigger the leap, wait for on-chain confirmation, then initiate the swap. Milestone: the first successful end-to-end testnet run — an RGB++ asset leaps to a UDT, that UDT swaps for the target CKB asset, and both stages are independently confirmable on-chain. This is the point where the project stops being a design and becomes a demonstrated capability.
Week 5 — Edge cases and failure handling, treated as real deliverables, not polish. Explicitly build and test: the leap succeeding but the swap subsequently failing or timing out (confirming the client correctly leaves the user holding the recoverable UDT rather than a stuck state), a one-leg timeout inside the swap stage itself with automatic refund, handling of duplicate or expired advertisements, rejection of malformed or unsigned advertisements, and correct behavior when a hub’s advertised rate no longer matches what a client expects at execution time. Build the minimal JS client wrapper in parallel, since it reuses the same calls already proven working in the CLI.
Week 6 — Documentation, demo, and delivery. Record a demo of a full successful swap and, separately, a demo of the timeout/refund path actually recovering funds rather than leaving them stuck. Write documentation sufficient for another builder to run their own advertising hub or extend the pattern to a third asset pair. Publish a public write-up back to Discussion #1243, closing the loop with the core team whose roadmap this implements. Milestone: public repo, both demos, and documentation are delivered and independently reviewable.
7. Required Funding & Funding Breakdown
A. Requested amount: $1,000 total — a single technical-development project, within the Spark Program’s standard cap, so no justification for exceeding $1,000 is needed here.
B. Funding Breakdown, mapped to the same weeks as Section 6, so funding transparently tracks delivered work rather than being requested as a lump sum against a plan:
Weeks 1–2 — $300. Covers the protocol study, core-team coordination in Discussion #1243, and implementation of the advertisement mechanism. This is deliberately the lowest-risk, lowest-cost phase — it’s foundational work with a clear, quickly checkable output (the advertisement broadcast/receive demo).
Weeks 3–4 — $400. Covers the most technically demanding phase of the build — integrating RGB++'s existing leap mechanism, generalizing the HTLC swap logic to accept the resulting UDT, and getting the first live leap-and-swap working end to end — plus the minor cost of testnet node hosting needed to actually run and demonstrate it. This is the largest allocation because it’s where the real engineering risk and effort concentrate.
Weeks 5–6 — $300. Covers dedicated time for edge-case and failure-path testing (deliberately not compressed into the final days, since this is exactly where subtle bugs in cross-chain logic tend to hide), the JS client wrapper, and production of the two recorded demos and documentation.
No portion of this budget covers hardware, marketing, or third-party paid services — it is development time, plus minimal testnet infrastructure, weighted toward the weeks carrying the highest technical risk rather than split evenly by default.
8. Deliverables + How to Verify
This section is structured so every deliverable can be checked by a reviewer without reading a single line of Rust or TypeScript — a deliberate response to the committee’s earlier feedback that verification shouldn’t depend on code review, which the committee has limited capacity for.
Deliverable 1 — Advertisement mechanism (end of Week 2) What’s delivered: An open-source commit to the project repository containing the SwapAdvertisement implementation and gossip broadcast integration, accompanied by a short log or screenshot showing a testnet hub’s advertisement being received by a separately run listening node. How to verify: The reviewer runs a single provided listener command against the testnet hub’s public node address. Expected output: the advertised asset pair and rate printed to the console within a few seconds — no code reading required to confirm this worked. Environment needed: a synced CKB/Fiber testnet node, with setup steps provided step-by-step in the repo README. Estimated verification time: under 10 minutes.
Deliverable 2 — Working leap-and-swap (end of Week 4) What’s delivered: A recorded demo of a complete leap-and-swap, plus three on-chain transaction references — the leap transaction (showing the RGB+±bound asset converting to a standard UDT, touching both Bitcoin and CKB), and the two sides of the subsequent Fiber swap — along with the repo commit implementing the client and generalized HTLC logic. How to verify: The reviewer opens all three provided transaction references in a public block explorer and confirms, in order, that the asset left its RGB+±bound form, then moved from the resulting UDT to the target CKB asset. No code execution or code review needed. Environment needed: none beyond a web browser. Estimated verification time: under 5 minutes.
Deliverable 3 — Edge-case and security handling (end of Week 5) What’s delivered: Two recorded demos of failure paths — (a) the swap stage failing or timing out after the leap has already completed, showing the client leaving the user holding the recoverable UDT rather than a stuck state, and (b) a one-leg timeout within the swap stage itself with automatic refund — plus a short written test report listing every edge case exercised (leap-succeeds-swap-fails, swap-stage timeout/refund, malformed advertisement, expired advertisement, rate mismatch at execution time) and the observed outcome for each. How to verify: The reviewer watches both recorded demos and reads the one-page test report. No environment setup, code execution, or code review needed. Estimated verification time: under 10 minutes.
Deliverable 4 — Documentation and public write-up (end of Week 6) What’s delivered: README and setup documentation detailed enough for another builder to run their own advertising hub or extend the swap to a third asset pair without asking me questions first, plus a public write-up posted back to Discussion #1243 summarizing what was built against the specific gap the core team originally documented. How to verify: The reviewer reads the README and confirms it contains concrete, followable setup steps rather than only prose description, and reads the linked forum write-up. Estimated verification time: under 10 minutes.
Across all four deliverables, verification never requires reading the underlying implementation — it relies on transaction hashes checkable in a public explorer, a single runnable command with predictable output, and recorded video evidence, which keeps the committee’s review cost low regardless of reviewer technical background.
9. Current State vs. Funded Work
Current state, stated plainly so there’s no overlap with what follows: the gap this project addresses has been researched and documented, grounded in the core team’s own dated discussion identifying it. No implementation code has been written. No project repository exists yet. Nothing beyond research and this proposal currently exists.
Funded scope, i.e., the delta this grant actually pays for: everything from designing and implementing the SwapAdvertisement message through a fully working, edge-case-tested, documented atomic RGB+±to-CKB-asset swap running on testnet, exactly as detailed week-by-week in Section 6 and deliverable-by-deliverable in Section 8.
Explicitly out of scope for this grant, so expectations are clear going in: mainnet deployment, formal third-party security auditing, and support for asset pairs beyond the single initial RGB++/CKB-asset pair. These are natural next steps once the core pattern is proven — the kind of scope a follow-on Community Fund DAO application would cover — but including them here would make this project too large to realistically finish inside a $1,000, six-week Spark grant, which is itself part of why this scope was chosen.
10. CKB Alignment
This project doesn’t use CKB as a generic settlement target that happens to be convenient — its entire value proposition only exists because of three CKB-specific technical features working together. Fiber Network’s channel and gossip architecture provides the instant, off-chain settlement layer. RGB++'s isomorphic binding model is what makes a Bitcoin-native asset representable and provably tied to a CKB-side state in the first place. And CCH’s existing HTLC-based swap mechanism, built specifically for CKB/Fiber, is the proven pattern this project generalizes rather than replaces.
Concretely, if any one of these three pieces didn’t exist in its current CKB-specific form, this project wouldn’t be buildable in its current shape: without Fiber’s gossip layer, there’d be no existing broadcast mechanism to extend for advertisements; without RGB++'s binding model, there’d be no well-defined way to represent the Bitcoin-side asset at all; without CCH’s existing atomic-swap logic, this project would need to design cross-chain HTLC coordination from first principles instead of generalizing something already proven. The project is implemented as a direct extension of nervosnetwork/fiber’s own codebase, not an external service that merely calls into CKB — meaning its success is inseparable from CKB’s specific architecture, not portable to a generic EVM chain with minor changes.
