Spark Program | Fiber RGB++ Swap

[Carl]

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.

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.

Is this project closely tied to RGB++? Yes — not loosely, at the core. The RGB++ leap (Section 4) is not a workaround bolted onto the project; it is the reason the project exists. Every asset that enters this swap originates as an RGB++ asset locked on Bitcoin, and the entire purpose of the project is to make that specific asset class usable on CKB. Without RGB++, there is nothing to advertise and nothing to swap.

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.

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. Final Architecture

This section is written to stand on its own — a reviewer should be able to read only this section and understand what gets built, without needing the implementation detail in Section 5.

At the highest level, the project is three additions sitting on top of Fiber’s existing, proven code, plus a client that chains them into one user action:

┌────────────────────────────────────────────────────────────────┐
│                         Client (CLI + JS)                        │
│   Drives the full flow: discover hub → leap → swap → confirm     │
└──────────────────────────────┬───────────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────┐
│              Orchestration (extends existing CCH code)           │
│   Chains leap → swap into one atomic-feeling user action,        │
│   and recovers cleanly if the swap leg fails after the leap      │
└───────┬───────────────────┬──────────────────────┬───────────────┘
        │                   │                       │
        ▼                   ▼                       ▼
┌───────────────┐  ┌────────────────────┐  ┌────────────────────────┐
│ Advertisement  │  │   Leap module       │  │  Swap execution module  │
│ module         │  │                     │  │                          │
│ New gossip     │  │ Wraps RGB++'s own   │  │ CCH's existing HTLC      │
│ message type,  │  │ leap tx tooling —   │  │ lock-and-reveal,         │
│ broadcast &    │  │ does not reimplement│  │ generalized to a second  │
│ discovery      │  │ it                  │  │ asset pair               │
└───────┬────────┘  └──────────┬──────────┘  └────────────┬─────────────┘
        │                      │                            │
        ▼                      ▼                            ▼
┌────────────────────────────────────────────────────────────────┐
│                        Chain interfaces                          │
│   Bitcoin RPC (reads/spends RGB++ UTXOs)                          │
│   CKB RPC + Fiber node RPC (cell queries, tx build/send)          │
└────────────────────────────────────────────────────────────────┘

What’s new versus what’s reused, stated plainly:

• Advertisement module — new. A new gossip message type (SwapAdvertisement) that lets a hub operator broadcast which asset pair and rate it supports, and lets a client discover that before committing. This is the piece CCH is missing today (Section 3).
• Leap module — not new logic, new integration. Calls RGB++'s already-existing leap transaction construction as the first stage of the flow. This project does not build a new way to move an asset off Bitcoin; it uses the one that already exists and works.
• Swap execution module — extension, not a rewrite. CCH’s existing HTLC lock-and-reveal state machine, currently hard-coded to one asset pair, is generalized to accept a second. The atomicity guarantee itself is not new — it’s the same mechanism CCH already proves — just parametrized over asset type.
• Orchestration — the actual novel work. Composing two independently-atomic operations (leap, then swap) into one user-facing action that behaves as a single unit, including the recovery path if the leap succeeds but the swap does not.

Node compatibility, stated up front: participating in swap advertisement broadcast, relay, or discovery requires running the extended Fiber node built by this project, because the advertisement is a new gossip message type added to Fiber’s core message set — not a message an unmodified node can already parse. Unmodified nodes are unaffected and continue operating exactly as they do today; they simply don’t participate in advertisement relay, the same way they don’t participate in CCH swaps today unless they’re running CCH-aware code. This is not a network-wide upgrade or a hard fork — it’s opt-in, in the same sense CCH itself is opt-in.

5. 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.

6. 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 (see Section 4 for the plain-language version of this same structure):

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 — rather than introducing a new network transport. Because this is a new message type added to Fiber’s core gossip protocol rather than an already-recognized format, only nodes running the extended Fiber node built by this project can broadcast, relay, or index it. Unmodified Fiber nodes are unaffected and continue operating normally — they simply don’t participate in advertisement relay, exactly as they don’t participate in CCH swaps today unless running CCH-aware code. This is not a hard fork of network consensus; it’s an opt-in extension, following the same pattern CCH itself already established.

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 7 dedicates explicit build time to it, and Section 9 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.

7. 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 — using the extended Fiber node built in this project — successfully broadcasts an RGB++ asset-pair advertisement, and a separately run listening node, also running the extended build, 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 — including the extended node build requirement — 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.

8. 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 7, 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.

9. 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, using the extended node build provided in the repo, 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 running the extended build (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 — including the extended node build it requires — 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.

10. 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 7 and deliverable-by-deliverable in Section 9.

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.

11. 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.

[matt_ckb]

On the BTC side, (inside the channel) are users iterating on a OP_RETURN commitment that could be pushed to the chain to settle the channel balances?

Really glad to see you looking at this, it has been a missing component of RGB++/Fiber for some time now.

[ArthurZhang]

Nice one, this kind of reminds me a bit of Lightning Liquidity Ads. There have actually been similar discussions in the RGB Lightning community as well, but they have been largely caught up with the complexity of getting the asset transport primitive itself right.

I think you are taking it one step further here by moving from channel liquidity discovery towards multi-asset liquidity discovery. Really looking forward to seeing how this evolves.

[Carl]

Hi Matt, exactly the right question — and yes, that’s the mechanism.

Users aren’t broadcasting an OP_RETURN commitment per update; that would mean a Bitcoin tx per payment, which defeats the point of a channel. Instead each new channel state produces a new signed single-use-seal spend that stays off-chain, with prior states revoked as the channel advances — the same revocable-commitment pattern Fiber/Lightning already use, extended to cover the RGB++ seal. Bitcoin only ever sees the final state, broadcast at settlement or close.

It’s the same shape as RGB++'s existing transaction folding (many off-chain transfers, one on-chain commitment), just applied at the channel boundary. I’m wiring two things that already work into a flow that doesn’t exist yet, not inventing new crypto.

If you’ve spotted edge cases here (multi-hop through an RGB++ leg, especially), I’d love to hear them before I start building.

[Carl]

Hi Arthur, good parallel — structurally this is close to Liquidity Ads: a gossip-broadcast offer that lets peers discover terms before committing, rather than negotiating out of band.

I think the reason RGB Lightning discussions stalled on the asset transport primitive is that they had to solve it from scratch. Fiber’s an advantage here: it already carries RGB++ assets as a native channel asset type, so the hard part — getting the asset itself to move through a channel — is already solved. That’s what let me skip straight to the market layer: once assets can move, the missing piece is just letting hubs advertise which ones and at what rate, the same way Liquidity Ads let nodes advertise capital.

Appreciate you flagging the RGB Lightning attempts

[xingtianchunyan]

Hi @Carl ,

Thank you for your continued interest in the Spark Program.

After review by the Spark Program committee, your proposal has been assigned a status of Pending. This is not a rejection, but an invitation to revise.

The committee recognizes the value of connecting RGB++ assets with Fiber’s instant-settlement layer, and we appreciate your clear identification of the current limitation in CCH. However, the proposal lacks sufficient detail to demonstrate that the project can achieve its stated goals within the proposed timeline and budget.

Main Revision Recommendations:

1. Clarify deliverables and verification criteria:
   The current proposal does not provide specific and verifiable deliverables for each milestone. Please list a clear set of deliverables (the list should specify the format of each deliverable) based on the template (Spark Program: Mini-Grant Initiative - #7 by xingtianchunyan) and map them to each milestone; Additionally, define objectively measurable verification methods and success criteria for each deliverable, including how to test the correctness of atomic exchanges, how to handle edge cases, and how to ensure security, so that the committee can objectively evaluate progress.

Please revise and resubmit based on the feedback above. We will arrange a new round of review as soon as possible.

Best,
xingtian
On behalf of the Spark Program Committee

[Carl]

Hi xingtian, thanks for the clear feedback

.

I’ve revised the proposal to map every milestone to specific deliverables with defined formats, plus verification steps that don’t require code review (transaction hashes, runnable commands with expected output, recorded demos), including explicit testing for the atomic-swap failure/timeout path and other edge cases. Reposting the updated version now.

Thanks again for the detailed guidance.

[fgh]

Really like this direction. One thing I’m not clear on:

When opening a Fiber channel, you choose the asset type script. The lock is always the funding lock derived from both sides’ funding pubkeys. But a bound RGB++ asset already uses the RGB++ lock tied to the Bitcoin UTXO, and a cell can only have one lock.

So how does that work in this design? If the asset has to leap to CKB first, then it seems like it’s just a normal UDT inside Fiber and Bitcoin isn’t involved once the channel is open.

[Carl]

Right — a cell can’t carry both locks, so the design was never planning to keep the RGB++ lock alive inside the channel.

The flow uses RGB++'s existing leap mechanism at the boundary: the asset leaps from its Bitcoin-bound RGB++ lock into a standard UDT once, on-chain, before it ever touches a funding cell. From there it’s a normal UDT circulating under the funding lock like any other channel asset — Bitcoin only comes back into play if the user leaps it back out later. Same shape CCH already uses for BTC/wrapped BTC: swap in once, circulate freely, settle at the boundary.

This is laid out in full in the resubmitted proposal, with a diagram

[Carl]

here is the prototype GitHub - oxdev6/Fiber-RGB-Swap · GitHub

[Hanssen]

Hi @Carl! I’m Hanssen from the Spark Committee. It’s great to see your exploration of the Fiber token swap. I have a few questions about the current proposal:

1. As you explained to @fgh earlier, users must unlock their RGB++ assets from the RGB++ Lock (from the BTC Leap back to CKB) before entering this swap. Does this mean the project isn’t very closely tied to RGB++?

@Carl

Right — a cell can’t carry both locks, so the design was never planning to keep the RGB++ lock alive inside the channel.

2. You mentioned that this project will create a new message type on top of Fiber’s gossip layer. Does this mean you need to modify the Fiber node? Will all users of this project need to use this modified node version?

@Carl

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.

Honestly, the current proposal deliverables focus too much on implementation details, and I can’t quite see what the final architecture of this project will look like. It would be great if you could provide more information on this point.

[Carl]

Q1 — Does this mean the project isn’t closely tied to RGB++?

Not less tied — the leap step is the RGB++ integration, not a workaround of it. The unlock is a one-time technical necessity: a cell can’t carry both the RGB++ lock and a channel lock at once, so the asset has to leap out of RGB++'s lock before it can enter a channel. But every asset in this swap originates as an RGB++ asset — without RGB++, there’s nothing to advertise or swap. It’s the foundation, not a side door.

Q2 — Do you need to modify the Fiber node? Will all users need the modified version?

Nodes that want to broadcast or index swap advertisements need the extended fiber node — this isn’t a config toggle on stock Fiber, it’s a new message type added to the core gossip code. Regular unmodified nodes are unaffected and continue operating normally; they simply don’t participate in advertisement relay, the same way they wouldn’t relay any message type they don’t know about. This isn’t a hard fork of network consensus — it’s the same pattern Fiber already uses for CCH (cross-chain hub) forwarding today, which only works between CCH-aware nodes.

Q3 — The proposal is too implementation-heavy, what’s the final architecture?

Fair — that’s on me for leading with implementation. At a high level: an orchestration layer sits on top of the existing Actix backend, split into three pieces — a leap module (wraps RGB++'s own leap tooling, doesn’t reimplement it), an advertisement module (the new gossip message type above), and a swap execution module (generalizes CCH’s existing HTLC lock-and-reveal to a new asset pair). Chain interfaces underneath talk to Bitcoin and CKB directly. Nothing here is a new subsystem — three extensions wired into code that already works. I’ve got a full diagram and phase-by-phase build plan if that’s useful context.

[Carl]

Fiber RGB++ Swap — Full Build Roadmap

From current mocked scaffold to a real, working leap-and-swap on testnet

This is the engineering plan behind the Spark proposal, written at implementation depth rather than grant-pitch depth. It assumes the current state of oxdev6/Fiber-RGB-Swap: an Actix backend and Yew frontend with working API endpoints (initiate, status, list), but simulated funding/leap logic and mock transaction hashes.

1. Full Architecture

┌───────────────────────────────────────────────────────────────────┐
│                          Client Layer                              │
│   CLI (fiber-rgbpp-swap)         JS client (web dApp integration)  │
└───────────────────────────────┬─────────────────────────────────────┘
                                  │  calls
                                  ▼
┌───────────────────────────────────────────────────────────────────┐
│                        API / Orchestration Layer                    │
│              (existing Actix backend — extend, don't replace)       │
│   - swap initiate / status / list  (already built)                  │
│   - NEW: leap orchestration                                         │
│   - NEW: advertisement query/relay                                  │
│   - NEW: swap state machine (replaces mock phase progression)       │
└──────────┬─────────────────────┬─────────────────────┬─────────────┘
           │                     │                     │
           ▼                     ▼                     ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────────┐
│   Leap Module       │ │  Advertisement     │ │   Swap Execution        │
│                     │ │  Module            │ │   Module                │
│ Wraps RGB++'s       │ │                    │ │                          │
│ existing leap tx    │ │ SwapAdvertisement  │ │ Generalized CCH HTLC     │
│ construction        │ │ message: sign,     │ │ lock-and-reveal,         │
│ (rgbpp-sdk / ckb-cli│ │ broadcast, verify, │ │ parametrized over        │
│ rgbpp tooling)       │ │ index — a new      │ │ asset type instead of    │
│                     │ │ gossip message      │ │ hard-coded BTC pair      │
│                     │ │ type; requires the  │ │                          │
│                     │ │ extended node to    │ │                          │
│                     │ │ send/relay/index    │ │                          │
└──────────┬──────────┘ └─────────┬──────────┘ └────────────┬─────────────┘
           │                       │                          │
           ▼                       ▼                          ▼
┌───────────────────────────────────────────────────────────────────┐
│                     Chain Interfaces                                │
│   Bitcoin RPC/wallet (rust-bitcoin)     CKB RPC (ckb-sdk-rust)      │
│   — reads/spends RGB++ single-use-seal  — cell queries, tx build,   │
│     UTXOs                                 tx send, Fiber node RPC   │
└───────────────────────────────────────────────────────────────────┘

Design principle carried through every layer: extend existing, proven code (Fiber’s gossip layer, CCH’s HTLC logic, RGB++'s leap tx construction) rather than reimplementing any of it. The only genuinely new code is the advertisement message type/index and the orchestration that chains leap → swap into one atomic-feeling user action.

Node compatibility note: the advertisement module adds a new message type to Fiber’s core gossip protocol (BroadcastMessage/GossipMessage in fiber-lib), not an already-recognized format. That means only nodes running this project’s extended fiber build can broadcast, relay, or index advertisements. Unmodified Fiber nodes are unaffected and keep operating normally — they just don’t participate in advertisement relay, the same way they don’t participate in CCH swaps unless running CCH-aware code today. This isn’t a network-wide upgrade or a hard fork; it’s opt-in, following the pattern CCH itself already set.

2. Step-by-Step Build Plan

Phase 0 — Environment and tooling (before writing new logic)

1. Stand up a CKB testnet node and a Fiber testnet node (fnn) locally; confirm you can query both via RPC.
2. Set up a Bitcoin testnet/signet wallet with test coins, and confirm you can construct and broadcast a basic transaction.
3. Pull in rgbpp-sdk (or the CLI tooling the RGB++ team ships, if the SDK isn’t stable enough) and get a single leap transaction working manually, outside your app, using their examples. Do not write your own leap logic until you’ve seen theirs work — this de-risks the entire project’s riskiest dependency first.
4. Add core Rust dependencies to the existing Actix backend: ckb-sdk-rust (CKB RPC/tx construction), rust-bitcoin (Bitcoin-side tx handling), whatever crate rgbpp-sdk exposes, and molecule if you need to hand-construct any CKB transaction fields not covered by the SDK.

Exit criterion: you can, from the command line, leap a real testnet RGB++ asset into a UDT, manually, using existing tooling. This is the single highest-risk unknown in the whole project — resolve it before building anything on top of it.

Phase 1 — Replace mock funding/leap logic with the real leap module

1. Wrap the manual leap flow from Phase 0 into a Rust module (leap.rs) with a clean interface: leap_to_udt(asset_ref, amount) -> Result<LeapReceipt>.
2. LeapReceipt should carry both transaction references (Bitcoin-side and CKB-side) so they’re available for the “How to Verify” step later — don’t discard them.
3. Wire this into the existing Actix swap initiate endpoint, replacing the current mock-hash logic, behind a feature flag or config toggle so you can still run the UI against mocks for fast frontend iteration if needed.
4. Write an integration test that runs this against testnet and asserts a real LeapReceipt comes back.

Exit criterion: hitting your existing /swap/initiate endpoint on testnet produces a real leap transaction, not a mock hash. This alone is a postable, verifiable milestone.

Phase 2 — Advertisement module

1. Define the SwapAdvertisement struct (asset pair, rate, fee, operator pubkey, signature, expiry) using molecule or existing Fiber message-encoding conventions — match their style so it’s a natural extension, not a foreign format.
2. Find the exact point in fiber-lib’s gossip code where node/channel announcements are broadcast and indexed (the BroadcastMessage/BroadcastMessageID/GossipMessage types and the GossipMessageStore trait), and add SwapAdvertisement as a new variant through the same path. Note: these are closed enums with dedicated per-type storage methods today, so this is a real extension to fiber-lib’s core types, not a plug-in.
3. Build a minimal in-memory index on the listening side: list_offers() -> Vec<SwapAdvertisement>, best_rate(pair) -> Option<SwapAdvertisement>.
4. Expose this through a new Actix endpoint (/advertisements) so the frontend and CLI can query it.

Exit criterion: two locally run testnet nodes — both running your extended fiber build, one broadcasting, one listening — demonstrate the second node correctly receiving and indexing an advertisement. This is your Milestone 1 deliverable from the proposal, made real.

Phase 3 — Swap execution module

1. Locate CCH’s existing HTLC lock-and-reveal implementation for the BTC/wrapped-BTC pair. Read it fully before touching it.
2. Generalize the asset-type parameter so it accepts the UDT produced by your leap module, not just wrapped BTC. Keep the existing BTC pair working — this should be a parametrization, not a fork.
3. Implement the commit/reveal/settle flow for the new pair, reusing Fiber’s existing revocable-commitment state machine rather than writing new dispute logic.
4. Wire this into the backend as the second half of /swap/initiate, called automatically after a successful leap.

Exit criterion: a full leap-then-swap completes on testnet, end to end, with three checkable transaction references (leap, and both sides of the swap) — this is Milestone 2 from the proposal.

Phase 4 — Client wiring

1. Update the CLI (fiber-rgbpp-swap) to call the real endpoints instead of any remaining mocks, and to print all transaction references clearly at each stage.
2. Build the minimal JS client wrapper, mirroring the same calls, for web dApp use.
3. Update the Yew frontend to show real transaction status (pending/confirmed/failed) instead of simulated phase progression, polling the real /swap/status endpoint.

Exit criterion: someone unfamiliar with the code can run the CLI against your testnet deployment and complete a real swap without reading source.

Phase 5 — Edge cases and failure handling (don’t compress this)

1. Deliberately trigger: leap succeeds, swap never starts (simulate a crash between the two) — confirm the client correctly reports “you hold a recoverable UDT,” not an error with no recovery path.
2. Deliberately trigger: swap starts but one leg times out — confirm the existing HTLC timeout/refund logic (inherited from CCH) fires correctly for the new asset type.
3. Test malformed and expired advertisements are rejected, and a rate mismatch between advertised and actual-at-execution-time is handled gracefully (re-quote or clean failure, not a silent bad trade).
4. Write up each scenario and its outcome — this becomes your Deliverable 3 test report.

Exit criterion: every failure mode from Section 8 of the proposal has a recorded demo and a written outcome, not just a description of what should happen.

Phase 6 — Documentation, demo, and delivery

1. Write setup docs precise enough that a stranger can run their own advertising hub from scratch, no side-channel questions needed — including the fact that both broadcasting and listening for advertisements requires the extended fiber build, not stock Fiber.
2. Record a demo of a full successful leap-and-swap.
3. Record a separate demo of the timeout/refund path actually recovering funds.
4. Publish the public write-up back to Discussion #1243, closing the loop with the core team.

Exit criterion: public repo, both demos, and documentation are delivered and independently reviewable — matching Deliverable 4 in the proposal exactly.

[Hanssen]

@Carl

without RGB++, there’s nothing to advertise or swap. It’s the foundation, not a side door.

你还是可以用 CKB 中的硬币，和从 RGB++ Leap 回来完全一样的那一种，来支撑 Swap 协议。这对这份协议并没有产生根本上的改变。

@Carl

they simply don’t participate in advertisement relay, the same way they wouldn’t relay any message type they don’t know about.

我还是希望你能直接澄清问题：是否所有使用者都需要运行一个修改版本的 Fiber 节点？

---

嘿，我不是来这里读 AI 生成的结果的，我有自己的 AI 工具。如果你愿意用自己的语言简要说明你想做什么事情，即使它看起来没那么 Fancy，我也会很感激你。

[Carl]

No, not everyone needs a modified node. Only nodes that want to broadcast or relay swap advertisements need the extended build a regular user just connects their client to one of those directly.

One real tradeoff: until more operators run the extended build, advertisements only reach nodes directly peered with an upgraded one, not the whole gossip network yet. Same bootstrapping situation CCH itself is in today

[Hanssen]

@Carl

No, not everyone needs a modified node. Only nodes that want to broadcast or relay swap advertisements need the extended build a regular user just connects their client to one of those directly.

Thank you for the explanation. By the “client” you mentioned, do you mean the CLI or JS client? Considering that users need their own Fiber node to connect to the network (to create a channel with other peers), is it reasonable to say that the “client” should connect to a modified Fiber node that manages the user’s channels (usually with their private key), whether self-hosted or custodial, to perform swaps?

[Carl]

Good distinction, and you’re right CLI/JS is just the interface, that’s not the full picture.

The node actually managing the user’s channel (the one holding the key and co-signing commitment updates) does need to run the extended build, self-hosted or custodial. It’s not just relaying an advertisement it has to understand and sign the new commitment structure for the leaped asset, and a stock node can’t do that. So this is more than an opt-in relay feature; it’s a real requirement for whoever’s holding the user’s channel.

[zz_tovarishch]

Hi @Carl,

The committee commends your initiative and appreciates your effort to push Fiber Network tooling forward.

However, after reviewing the proposal, we consider the RGB++ protocol integration part out of scope for this grant. As a result, we would like to adjust the approved budget to $500 USD equivalent in CKB for the remaining core development.

Please let us know if you accept this revised budget so we can proceed accordingly.

Best regards,

Spark Program Committee

cc @Hanssen @xingtianchunyan @yixiu.ckbfans.bit

[Carl]

Thanks I accept the revised scope and $500 budget.Will post progress updates the same way I have been. Appreciate the committee working through this with me.

[Carl]

Revised Budget — $500, 4 weeks

Week 1 — Design and setup — $100
Stand up CKB/Fiber testnet nodes, study fiber-lib’s existing gossip code (BroadcastMessage/GossipMessage types), and finalize the SwapAdvertisement message schema (asset pair, rate, fee, operator pubkey, signature, expiry).

Week 2 — Gossip integration — $150
Implement SwapAdvertisement signing/verification and wire it into fiber-lib’s existing broadcast/relay path as a new message type. This is the highest-effort week, since it touches the core gossip protocol directly.

Week 3 — Discovery index and interface — $150
Build the listening-side index (list_offers(), best_rate(pair)), expose it through an API endpoint, and wire up the CLI so a user can query live advertisements.

Week 4 — Testing, demo, documentation — $100
Run the two-node broadcast/discovery test, record a short demo, write setup docs for anyone wanting to run their own advertising node, and post the write-up to Discussion #1243.

Total — $500, no hardware or third-party costs, development time only.