RGB on Lightning: Walking with Upstream

Building Lightning's Smart-Contract Layer, In Lockstep with Upstream

We don't just claim RGB is compatible with the Lightning Network — we walk alongside Lightning's upstream evolution, release after release, fix after fix. We call this relationship Super-Compatibility — not as a slogan, but as a complete engineering commitment.

What it means: RGB is not a parallel chain alongside the Lightning Network — it is the smart-contract layer of Lightning itself, layered on top of the BOLT protocol via feature-bit extension. The BTC channel layer fully interoperates with the Lightning mainnet, while the asset layer is extended through feature negotiation, evolving in step with the LN protocol's progression.

To deliver on this commitment, we advance along three axes:

1. Zero Regression as a Right of Passage — compatibility is admission, not the destination
2. In Lockstep with Upstream Evolution — evolving alongside upstream, not chasing it
3. Carrying Lightning's Frontier into Asset-Land — bringing Lightning's cutting edge into asset capability

1. Overview

This v0.7 release is a continuous-delivery milestone for the super-compatibility commitment.

• v0.6 / Phase 3 completed the bootstrap of compatibility: 1,019 LDK state machine tests passing + 12 CLN/LND interop scenarios at 100% pass rate, proving that RLN nodes are first-class citizens of the BOLT protocol.
• v0.7 completes the continuous integration of compatibility: systematically bringing the protocol evolution and funds-safety fixes from upstream rust-lightning 0.1.4 → 0.2.2 and ldk-node 0.6.1 → 0.7.0 into RLN nodes.

This release absorbs 16 MEDIUM+ funds-safety fixes (covering 17 upstream PRs) and 4 mainline protocol features (splice / async-payments / LSPS2 underpaying / OutputSweeper async tick), advancing the version number in lockstep with upstream to v0.7.0.

Beyond the engineering work itself, the pivotal step of this super-compatibility cycle is the formal submission of RGB's compatibility design on Lightning as bLIP-0070 (lightning/blips#70 (opens in a new tab)) — opening the design to BOLT community review and giving the entire Lightning ecosystem an opportunity to embrace RGB through a unified standard. See §5 for details.

2. Recap and Focus Shift

2.1 The Baseline Established by v0.6 / Phase 3

The Phase 3 report (lightning-rgb-phase3-interop (opens in a new tab)) summarizes the key outputs of the compatibility bootstrap phase:

• 1,019 LDK state machine tests passing in full: 0 failed, 0 ignored
• TLV migration: all RGB wire fields migrated to odd TLV type 827167; feature bits 826/827 registered
• 12 interop scenarios validated against CLN v23.08 and LND v0.18.5-beta
• Fuzzing: 1,000+ randomized payment sequences with zero asset-conservation invariant violations
• Chaos testing: persistence-consistency boundaries established for in-flight HTLCs across node crashes

These outcomes prove that RLN nodes are not an isolated network — they coexist with, interoperate with, and participate in routing on the BOLT mainnet.

2.2 The Focus Shift in v0.7

v0.6 answered "can RGB join the Lightning Network?". v0.7 answers "can RGB stay in lockstep with the Lightning Network as it evolves?".

v0.6 is the starting point of super-compatibility; v0.7 is its proof of cadence — proof that this system can keep pace with upstream's evolution.

3. Three Axes of Super-Compatibility

3.1 Axis 1: Zero Regression as a Right of Passage

Compatibility is admission, not the destination.

We pass all 1,019 LDK state machine tests — proving that RLN integration has zero impact on native LN behavior. Strip the RGB module and the node remains a fully compliant LDK node.

Zero impact on native LN behavior is the code-layer foundation of super-compatibility — only by not disturbing native LN behavior can RLN coexist with CLN/LND on the same network.

v0.7's continuation along this axis:

• Full regression suite kept running throughout the upgrade
• BTC channel-layer interop tests with CLN / LND maintained at 100% pass rate
• No new disabled tests introduced from RGB integration

Zero impact on native LN behavior is not a one-time achievement — it is a commitment that must be re-proven with every upgrade.

3.2 Axis 2: In Lockstep with Upstream Evolution

Evolving alongside upstream, not chasing it.

Every BOLT proposal and every funds-safety fix is brought into RLN nodes through the continuous-upgrade pipeline.

This v0.7 upgrade absorbs:

• rust-lightning 0.1.4 → 0.2.2: spanning maintenance versions v0.1.5 / v0.1.6 / v0.1.7 / v0.1.8 / v0.1.9 + the major release v0.2.0 + patch releases v0.2.1 / v0.2.2
• ldk-node 0.6.1 → 0.7.0: version number aligned with upstream mainline
• 16 MEDIUM+ funds-safety fixes (see §4), 5 of which were introduced only in v0.2.x and never backported to v0.1.x — additional value unobtainable on the v0.1.x maintenance line
• 4 latest protocol features (see §6)

RGB users get the latest LN protocol stack and full RGB asset support in the same node — no fork, no version lag.

3.3 Axis 3: Carrying Lightning's Frontier into Asset-Land

Bringing Lightning's cutting edge into asset capability.

RLN is not a passive consumer of Lightning — we systematically reshape Lightning's most advanced capabilities into asset-aware versions.

This v0.7 upgrade first lands splice / async-payments at the BTC channel layer. This step alone already delivers direct value to RLN nodes:

• For the BTC payment paths of RLN nodes: splice lets nodes dynamically resize BTC channel capacity without closing the channel; async-payments lets the BTC paths support offline receiving
• For the LN mainnet ecosystem: as full BOLT-compliant citizens, RLN nodes participate normally in routing on the Lightning mainnet

Looking ahead, the roadmap is to extend these capabilities into the RGB asset layer — by bringing splice / async-payments and other BOLT advancements onto the existing RGB state machine:

• Splice for RGB: dynamic capacity adjustment of RGB asset channels
• Async Payments for RGB: offline RGB asset receiving
• JIT liquidity for RGB: just-in-time RGB asset channel opening

This is super-compatibility's commitment at the capability layer.

4. Funds Safety: 16 Upstream Fixes Absorbed

This release brings in 16 MEDIUM-or-above funds-safety / persistence / DoS fixes (covering 17 upstream PRs; LOW-tier entries trimmed). Of these, 5 were introduced only in v0.2.x and never backported to v0.1.x — additional value of this upgrade over staying on the v0.1.x maintenance line. 3 of them carry an upstream SECURITY tag.

4.1 Five High-Severity Highlights

A further 11 MEDIUM/HIGH fixes cover MPP claim state, reserve accounting, reorg handling, HTLC error-message tamper detection, and similar scenarios.

4.2 Why This Matters

Funds safety is not a one-time "we are safe now" declaration — it is a byproduct of continuously following upstream. The longer a node lingers on an old version, the larger the unfixed attack surface accumulates.

One core engineering value of super-compatibility is precisely making "running with the latest protocol-level safety fixes" the default option for RLN operators, not a luxury one.

5. Standardizing the Compatibility — bLIP-0070

Super-compatibility is more than "our implementation is BOLT-compatible" — we have formally submitted this compatibility design as bLIP-0070: RGB colored channel support for Lightning Network (opens in a new tab), opening it to BOLT community review and giving the entire Lightning ecosystem the chance to embrace RGB through a unified standard.

5.1 Design Essentials

bLIP-0070 defines a minimal, backward-compatible set of protocol extensions that let RGB assets transit Lightning channels without affecting any standard node.

Three key design choices:

• Feature bit 826/827 (rgb_channel) — even bit 826 is used in channel_type for mandatory negotiation; odd bit 827 is used in init / node_announcement / channel_announcement, where standard nodes silently ignore it. The numbering derives from the SLIP-0044 (opens in a new tab) RGB coin types 827166/827167, aligning the identifier system with RGB itself.

• TLV type 827167 — a single unified TLV type covers all RGB wire fields, distributed across five message classes: open_channel / open_channel2 / update_add_htlc / channel_announcement / channel_update / onion payload. An odd type, in line with BOLT #1's "it's ok to be odd" convention — standard nodes encountering an unrecognized odd TLV silently ignore it without disconnecting.

• Gossip signature coverage — RGB fields in channel_announcement / channel_update are appended as trailing TLV and remain covered by the existing BOLT signature — RGB requires no new signature scheme, and the existing gossip trust model continues to apply unchanged.

5.2 What This Means

Submitting this proposal to lightning/blips elevates super-compatibility from an implementation-level claim to a standardization proposal:

• For standard LN implementations: bLIP-0070 provides an explicit contract for coexistence with RLN nodes — no need to implement the RGB state machine in order to route BTC traffic through an RLN node;
• For RGB-on-Lightning implementations: based on this spec, RLN nodes integrate seamlessly into the Lightning Network as an optional feature extension, never breaking standard-node expectations.

This is the outward extension of super-compatibility: not just our code being upstream-compatible, but turning "RGB on Lightning" into a standardized capability that can be reviewed and adopted across the ecosystem.

6. New Capabilities Brought by Upstream Tracking

6.1 Splice (BOLT #1160) — Dynamic Channel Capacity

Splice allows a channel's capacity to be dynamically adjusted after it has been opened, without closing the channel. Splice-in adds on-chain BTC into an existing channel (increasing capacity); splice-out withdraws part of the channel funds back to an on-chain address (decreasing capacity).

v0.7 lands splice integration at the BTC channel layer (experimental), with HTTP / Library APIs and event callbacks in place. The next step on the roadmap is to extend the splice mechanism to RGB asset channels.

6.2 Async Payments (BOLT #1149) — Offline Receiving

Async Payments enables receivers who are frequently offline (e.g. mobile wallets) to receive BOLT-12 payments. The mechanism: before going offline, the receiver handshakes with an always-online Static Invoice Server (OON) and parks a pre-signed static invoice on the server; the sender obtains the invoice through the server and initiates payment; the server routes the HTLC along a blinded path to the receiver's mailbox node; the receiver claims it upon coming back online.

v0.7 lands async-payments integration at the BTC channel layer (experimental), configures the node role via CLI flag (Server / Client), with the HTTP API covering the full receiver-to-OON handshake configuration flow. The next step on the roadmap is to extend this mechanism to RGB assets, supporting offline receiving for RGB assets.

6.3 LSPS2 accept_underpaying_htlcs Default Correction

LSPS2 is a protocol between Lightning Service Providers (LSPs) and clients, enabling on-demand JIT channel openings. Upstream v0.7.0 corrects the default value of accept_underpaying_htlcs, fixing payment failures over JIT channels.

• Adoption scope: tracks upstream, no configuration required
• Impact: improved payment success rate for clients using LSPS2 JIT channels

6.4 OutputSweeper Async Tick — Timing Optimization for On-Chain Sweep

After force-close, on-chain outputs (HTLC, to_local, etc.) that the node is entitled to need to be scanned and reclaimed. Upstream v0.7.0 changes the scanner timer to an async tick, fixing the previous issue of sweeps stuck in PendingBroadcast.

• Adoption scope: tracks upstream
• Impact: more reliable on-chain fund recovery timing after force-close

6.5 How Protocol Evolution Reaches RLN

These four features come from different layers of the Lightning ecosystem — BOLT protocol (splice, async-payments), LSP specifications (LSPS2), and LDK internals (OutputSweeper) — and v0.7 absorbs them all in lockstep. The roadmap is to extend the BOLT-level advancements onto the asset layer (Axis 3).

7. Compatibility Maintenance Mechanism

Super-compatibility is not a one-shot engineering effort — it requires long-term mechanisms.

7.1 HTTP API Additions

This release adds three groups of endpoints to this repository's HTTP control plane:

• Splice control: splice_in / splice_out
• Async-payments configuration flow: blinded_paths_for_recipient / set_static_invoice_server_paths / receive_offer
• Network graph queries: node / channel listings and lookup by ID

The events endpoint also extends with splice-related DTOs.

7.2 Peer Allowlist for RLN-Business Nodes

A new CLI flag --require-rgb-peers enables a node-level allowlist that rejects standard LN nodes not advertising the RGB feature bit. Use case: RLN-only business nodes that do not want their connection budget consumed by vanilla CLN/LND peers.

• Off by default, fully backward-compatible
• Verified by interop tests: vanilla CLN / LND are indeed rejected

7.3 Forward-Looking Maintenance Commitments

To sustain super-compatibility over the long run, we plan:

• Pre-merge schema-change review — any PR that touches storage format / wire format must update the corresponding sections of release notes
• Release-notes maintenance documentation — to be consolidated in the next phase as an official document, requiring every future release to cover storage / protocol change entries
• Tracking the upstream cadence — keeping the absorption cycle for major upstream releases within a reasonable window, preventing version drift accumulation

8. Validation Results

9. Looking Forward: Smart-Contract Extension to RGB

v0.7 sustains the first two axes of super-compatibility (Zero Regression / In Lockstep). The next step on Axis 3 (Smart-Contract Extension to Asset-Land) lands on two main lines:

9.1 Extending Splice to RGB Asset Channels

Layering the splice mechanism onto the RGB state machine. Expected capabilities:

• Add on-chain RGB assets into a channel without closing the RGB channel
• Withdraw part of the in-channel RGB assets back to on-chain UTXOs
• Use cases: RGB application liquidity pools, dynamic RGB liquidity scheduling

9.2 Extending Async Payments to RGB Assets

Layering the async-payments mechanism onto the RGB asset path. Expected capabilities:

• Frequently offline RGB asset holders (e.g. mobile wallets) can receive RGB assets
• In combination with the BOLT-12 offer mechanism, support "always-on listings with asynchronous fulfillment" for RGB merchant scenarios

9.3 Cadence with BOLT Protocol Evolution

Our commitment: evolve in lockstep with the Lightning ecosystem, layering RGB asset management on top of every major BOLT feature, so that LN's frontier and RGB's asset semantics combine into a truly usable Smart-Asset Lightning.

Super-compatibility is not the destination — it is a continuously advancing engineering line.