Phase 1: Building the Foundation for RGB v0.12-Lightning Integration

1. Overview

Phase 1 of our RGB v0.12-Lightning integration is now complete. We've built and validated a comprehensive test suite covering the fundamental building blocks of protocol fusion—proving that RGB assets can safely flow through Lightning channels.

Test Results:

• 15 out of 15 tests passing (100% pass rate)
• 5 Lightning channel scenarios validated
• 10 L1 transfer scenarios verified

The core question we set out to answer: Can RGB v0.12's client-side validation model integrate with Lightning's state channel architecture? Our test results confirm it can.

Phase 1 validates the primitives needed for instant, low-cost transfers of stablecoins, tokens, and other RGB assets over Lightning—combining Bitcoin's security with RGB v0.12's programmability and Lightning's speed.

2. Background: The Challenge of Protocol Fusion

Two Off-Chain Protocols, One Vision

Bitcoin's Lightning Network enables instant, low-cost payments—but only for BTC. RGB v0.12 brings programmable assets to Bitcoin—but on-chain transactions remain slow and expensive. Combining these protocols promises the best of both worlds: instant asset transfers with Lightning speed and Bitcoin security.

However, integrating RGB v0.12 with Lightning presents a unique engineering challenge. Both are off-chain protocols, but they operate on fundamentally different principles:

RGB v0.12 is built on client-side validation. State transitions are stored in consignments and validated locally by each party. There is no global consensus—only bilateral validation between sender and receiver. RGB state lives outside the blockchain, anchored to Bitcoin transactions through commitments.

Lightning Network operates as a state channel protocol. Channel state is encoded in commitment transactions, validated by both counterparties, and can be enforced on-chain at any time. Lightning state is bilateral but fundamentally different from RGB's consignment model—it relies on the threat of on-chain publication for security.

Core Engineering Questions

Merging these two off-chain architectures requires addressing several critical questions:

State Representation: How do we represent RGB allocations within Lightning commitment transactions? Each commitment update must reflect both Bitcoin amounts and RGB asset allocations, while maintaining compatibility with Lightning's existing transaction structure.

State Synchronization: How do we ensure RGB state updates remain synchronized with Lightning commitment updates? When a Lightning HTLC is added, settled, or times out, the corresponding RGB allocations must transition correctly across multiple state layers.

Recovery and Safety: What happens during unilateral channel closure? Can both parties recover their RGB assets from broadcasted commitment transactions? The recovery mechanism must work for all scenarios: cooperative close, force close, and HTLC settlement.

Phase 1 Objective

Phase 1 focuses on validating the fundamental building blocks of protocol fusion. Rather than optimizing for production scale or handling every edge case, we aim to prove that the core integration is sound:

• RGB assets can be allocated within Lightning channel funding transactions
• Commitment updates correctly track RGB state transitions
• Channel closure (both cooperative and forced) preserves RGB asset ownership
• HTLC settlement mechanisms work correctly with RGB allocations
• Assets recovered from L2 channels remain fully functional on L1

Success in Phase 1 means we have established a solid foundation for more complex scenarios in subsequent phases.

3. Phase 1 Achievements Overview

Phase 1 validation encompasses 15 comprehensive test scenarios covering both Lightning channel operations and on-chain RGB transfers. All tests pass with 100% success rate, demonstrating robust integration across the protocol stack.

Test Coverage Matrix

Lightning Channel Tests (5 scenarios)

Our Lightning test suite validates the complete lifecycle of RGB-enabled channels:

1. Commitment State Management - Verifies RGB state transitions through multiple commitment updates, testing the Pending/Active layer mechanics and ensuring old commitments are properly replaced.

2. Cooperative Channel Close - Tests the negotiated closing flow where both parties agree on final settlement, validating RGB allocation in the closing transaction and recovery through sweep transactions.

3. Force Close Recovery - Validates unilateral channel closure by broadcasting commitment transactions, ensuring RGB assets can be recovered even when cooperation fails.

4. HTLC Complete Lifecycle - Tests the full payment flow including HTLC creation, settlement with preimage, and RGB allocation across multiple transaction outputs.

5. L2-to-L1 Asset Bridge - Verifies that RGB assets recovered from Lightning channels remain fully functional for standard on-chain transfers, proving seamless interoperability between layers.

L1 Transfer Tests (10 scenarios)

The L1 test suite covers fundamental RGB transfer operations on Bitcoin:

• Witness and Blinded transfer types
• Invoice mechanism and duplicate payment protection
• Multi-UTXO spending capability
• Replace-By-Fee (RBF) transaction support
• Zero-confirmation transfer acceptance
• Wallet state persistence and recovery
• Self-transfer validation

Core Validation Results

RGB Three-Layer State Management

Our implementation uses a multi-layer state architecture to handle the complexity of off-chain updates:

• Base Layer: Confirmed on-chain state, the source of truth
• Applied Layer: Broadcast transactions awaiting confirmation
• Active Layer: Acknowledged commitment transactions (off-chain)
• Pending Layer: Transactions currently being colored

This layered approach provides clear separation between different stages of state progression, enabling safe concurrent operations and straightforward recovery logic.

Channel Close Flows

We validated both primary channel closure mechanisms:

Cooperative Close: Both parties negotiate a closing transaction, sign it cooperatively, and broadcast. RGB state transitions from Active to Applied when the closing transaction is cached, then to Base upon confirmation.

Force Close: One party unilaterally broadcasts the latest commitment transaction. The system detects the on-chain publication, applies the RGB state from the Active layer directly, and enables sweep transactions to recover assets.

HTLC Settlement

Hash Time-Locked Contracts (HTLCs) add complexity by creating conditional outputs with timelocks. Our tests validate:

• Commitment transactions with multiple RGB-allocated outputs (to_local, to_remote, HTLC)
• HTLC-Success transactions that claim HTLC outputs with preimages
• Correct RGB amount tracking across all transaction stages
• Complete asset recovery through sweep transactions

Asset Conservation

Every test verifies strict conservation: the sum of all RGB allocations before and after any operation must remain constant. This property holds across commitment updates, channel closures, HTLC settlements, and L1 transfers.

Statistical Summary

• Total Tests: 15 (5 Lightning + 10 L1 transfer)
• Pass Rate: 100% (15/15)
• Total Execution Time: 383 seconds
• Test Coverage: State management, cooperative/force close, HTLC lifecycle, L1 transfers, L2-L1 bridge

4. Technical Insight: RGB State Layer Model

The multi-layer state architecture is central to how RGB assets integrate with Lightning channels. Understanding this model is key to appreciating the engineering challenges we addressed in Phase 1.

Why Multiple Layers?

Lightning channels operate through a sequence of commitment transactions that are created but not immediately broadcast. RGB must track asset allocations across these off-chain commitment transactions while maintaining compatibility with on-chain state.

The challenge: RGB validation requires witnessing transactions on the blockchain, but Lightning commitments exist only as signed (but unbroadcast) transactions. How do we validate RGB state transitions for transactions that may never hit the chain?

Our solution uses a staged state model where each layer represents a different level of commitment and blockchain visibility:

Pending Layer represents transactions currently being colored. When a new commitment transaction is created, RGB allocations are assigned to its outputs through a coloring process. The transaction remains in Pending until both parties acknowledge it.

Active Layer holds acknowledged commitment transactions. After both parties complete the commitment update protocol (including revoke_and_ack messages), the new commitment moves from Pending to Active. The Active layer represents the current off-chain channel state—these commitments could be broadcast at any time for force close.

Applied Layer contains transactions that have been broadcast and are awaiting confirmation. When a commitment or closing transaction is published to the blockchain, its RGB state moves to Applied. At this stage, the transaction is visible on-chain but not yet confirmed.

Base Layer is the confirmed on-chain state. After sufficient confirmations, transactions in Applied transition to Base, representing finalized RGB allocations that are universally accepted.

State Transition Scenarios

Commitment Update Flow

When Alice and Bob update their channel balance:

1. New commitment transaction created and colored (enters Pending)
2. Both parties exchange revoke_and_ack messages
3. New commitment moves to Active, old commitment removed
4. Base layer remains unchanged (no on-chain activity)

This flow repeats for every channel balance update, with Active layer commitments replacing each other as the channel evolves.

Channel Close Flow

For cooperative close:

1. Closing transaction created and colored (Pending)
2. Both parties sign and cache the closing transaction (on_coop_close_ready)
3. Closing transaction broadcast (moves to Applied)
4. After confirmation, state settles to Base

For force close:

1. Latest Active commitment directly broadcast
2. State immediately moves from Active to Applied
3. After confirmation, transitions to Base

The key difference: cooperative close creates a new transaction through Pending, while force close uses an existing Active commitment directly.

HTLC Settlement Flow

HTLCs add a third transaction tier:

1. Commitment transaction with HTLC output (Pending → Active → broadcast → Applied)
2. HTLC-Success/Timeout transaction claims HTLC output (created → colored → Applied)
3. Sweep transaction moves funds to wallet (Applied → Base)

Each stage requires correct RGB state tracking to ensure the claim transaction properly inherits RGB allocations from the HTLC output.

Design Benefits

This layered architecture provides several critical properties:

Separation of Concerns: Off-chain Lightning operations (Pending/Active) remain isolated from on-chain settlement (Applied/Base). This separation simplifies reasoning about RGB state during rapid commitment updates.

Clear Recovery Path: During force close, the system simply takes the Active commitment and moves it to Applied, then waits for confirmation to reach Base. No complex state reconstruction needed.

Concurrent Safety: Multiple operations can work in parallel because each layer has well-defined transition rules. A new commitment can be prepared in Pending while an HTLC settles through Applied.

5. Test Design Case Study: HTLC Complete Lifecycle

To illustrate our testing approach, we examine test_commitment_with_htlc in detail. This test represents the most complex scenario in Phase 1, covering commitment transactions, HTLC settlement, and complete asset recovery.

Why This Test Matters

HTLCs are the core payment mechanism in Lightning. When Alice pays Bob through the channel, an HTLC locks funds conditionally: Bob can claim with a preimage, or Alice can reclaim after timeout. Adding RGB to this flow requires:

• Allocating RGB assets to HTLC outputs in commitment transactions
• Tracking RGB through HTLC-Success/Timeout transactions
• Ensuring correct final settlement when assets move to wallets

This test validates that the entire HTLC lifecycle works correctly with RGB assets, proving the integration handles Lightning's most critical feature.

Test Scenario Setup

Initial state: 500,000 RGB units in a 2-of-2 multisig funding the Lightning channel.

Payment scenario: Alice wants to pay Bob 50,000 RGB units through an HTLC, while maintaining their existing balance split.

Expected outcome: After HTLC settlement and force close, Alice should have 200,000 RGB (her remaining balance after the payment), and Bob should have 300,000 RGB (his original 250,000 plus the 50,000 HTLC payment).

Six-Phase Test Flow

Phase 1: Funding

Standard Lightning channel funding with RGB assets:

• Create 2-of-2 multisig UTXO
• Allocate 500,000 RGB to the funding output
• Both parties acknowledge the funding transaction

Phase 2: Commitment with HTLC

Create commitment transaction with three outputs:

Output 0 (Alice to_local): 200,000 RGB - Alice's remaining balance after deducting the HTLC amount

Output 1 (Bob to_remote): 250,000 RGB - Bob's current balance, unaffected by the pending HTLC

Output 2 (HTLC output): 50,000 RGB - The conditional payment from Alice to Bob, claimable with preimage

The commitment transaction is colored, assigning RGB amounts to each output. Total: 200k + 250k + 50k = 500k (conservation verified).

Phase 3: Force Close

Alice or Bob broadcasts the commitment transaction (force close scenario). The system:

• Detects the on-chain publication
• Calls on_channel_closed to apply RGB state
• Transitions state from Active to Applied
• Caches RGB allocations for sweep transactions

Phase 4: HTLC-Success Transaction

Bob creates an HTLC-Success transaction to claim the HTLC output:

• Input: Commitment transaction output 2 (the HTLC output)
• Output: Bob's Lightning-controlled address (50,000 RGB)
• Witness: Includes the payment preimage that satisfies the HTLC condition

The transaction is colored, signed with preimage, broadcast, and confirmed. The system calls on_htlc_tx_confirmed to apply the HTLC RGB state.

Phase 5: Sweep All Outputs

Both parties create sweep transactions to move RGB to their wallets:

Alice sweep: Commitment output 0 → Alice's RGB wallet (200,000 RGB)

Bob commitment sweep: Commitment output 1 → Bob's RGB wallet (250,000 RGB)

Bob HTLC sweep: HTLC-Success output → Bob's RGB wallet (50,000 RGB)

Each sweep transaction detects that it's spending from Applied layer overlays and correctly inherits RGB allocations.

Phase 6: Final Verification

Query both wallets for RGB allocations:

• Alice: 200,000 RGB (confirmed)
• Bob: 300,000 RGB (250k + 50k, confirmed)
• Total: 500,000 RGB (conservation holds)

All RGB assets successfully recovered from Lightning channel through multi-stage transaction flow.

Key Validation Points

RGB Allocation Correctness: The commitment transaction properly splits 500k RGB across three outputs with the correct amounts. The coloring process maintains these allocations through transaction signing.

Multi-Layer State Transitions: RGB state moves through Pending (commitment creation) → Applied (commitment broadcast) → Applied (HTLC settlement) → Base (sweep confirmation). Each transition is validated.

HTLC Preimage Verification: The HTLC-Success transaction can only be created with the correct preimage, proving the payment condition was satisfied. RGB tracking works correctly even with conditional outputs.

Complete Recovery: All three outputs from the commitment transaction, plus the HTLC-Success output, are successfully swept. No RGB assets are lost or left unclaimed.

Asset Conservation: At every stage—commitment creation, commitment broadcast, HTLC settlement, sweeps—the total RGB amount equals 500,000. Conservation is maintained throughout the entire multi-transaction flow.

Test Significance

This test proves several critical capabilities:

• RGB assets can be allocated to complex commitment transactions with multiple output types
• HTLC payment flows work correctly with RGB, including preimage validation
• Force close recovery handles multi-output scenarios with HTLCs
• The Applied layer overlay mechanism enables correct RGB tracking across transaction chains
• End-to-end asset safety holds even in the most complex Lightning scenario

Passing this test means the integration handles Lightning's core payment mechanism, not just simple balance updates.

6. Looking Ahead: Phase 2

Foundation Established

Phase 1 has validated the fundamental primitives of RGB-Lightning integration:

• RGB assets can be safely allocated within Lightning channel structures
• State layer architecture handles commitment updates and channel closures correctly
• HTLC settlement mechanism works with RGB allocations
• Assets recovered from L2 channels remain fully functional on L1
• All core APIs (coloring, state transitions, recovery) operate as designed

These building blocks form a solid foundation, proving that the protocol fusion approach is sound at the architectural level.

Next Challenges

Phase 2 shifts focus from "does it work?" to "does it work in realistic conditions?" Key areas include:

Multi-Hop Routing: Extending RGB payment flows across multiple Lightning channels. This requires coordinating RGB state updates along the payment path while maintaining atomicity—either the entire route succeeds, or no RGB transfers occur.

Concurrent Operations: Testing scenarios with multiple simultaneous payments, commitment updates, and state transitions. The state layer architecture must remain consistent under concurrent access.

Complex Failure Recovery: Exploring edge cases like mid-flight payment failures, network partitions during channel updates, and recovery from corrupted state. Production systems must handle these scenarios gracefully.

Toward Production Readiness

Phase 2 represents a critical step toward production deployment. While Phase 1 proves the integration works in controlled scenarios, Phase 2 must demonstrate resilience under realistic stress and complexity.

Our roadmap continues beyond Phase 2 with production hardening (Phase 3), advanced features (Phase 4), and long-term scalability (Phase 5). Each phase builds on validated capabilities from previous phases, maintaining our commitment to thorough testing and engineering rigor.

The completion of Phase 1 marks an important milestone: we have proven that RGB and Lightning can work together. Now the work continues to make that integration robust, efficient, and ready for real-world use.

Learn More:

• Testing Framework: bitlightlabs/rgb-tests/ln-rgb-tests (opens in a new tab)
• RGB Protocol: rgb.tech (opens in a new tab)
• Lightning Network: lightning.network (opens in a new tab)