Phase 2: RGB Lightning Integration Testing - From Baseline Validation to Edge Case Coverage

1. Overview

Phase 2 testing is complete, addressing two core objectives:

1. Compatibility Validation: Does RGB integration affect the correctness of native Lightning functionality?
2. Edge Case Safety: Can RGB assets be safely recovered when HTLCs fail, timeout, or channels are force-closed?

Using TDD methodology, we verified that RGB code has no impact on LDK's native functionality, while discovering and implementing missing protocol capabilities for edge cases.

2. Phase 1 Recap and Phase 2 Objectives

Phase 1 Achievements

Phase 1 validated the foundational primitives of RGB-Lightning integration:

• 15/15 tests passed (5 Lightning scenarios + 10 L1 transfer scenarios)
• Multi-layer state management: Pending → Active → Applied → Base state transitions verified
• HTLC happy path: commitment creation, preimage settlement, sweep recovery all validated
• Asset conservation: RGB totals remained constant across all operations

Phase 2 Focus Shift

Phase 1 answered "does it work?", Phase 2 answers "is it safe and compatible?":

3. Native Lightning Compatibility Validation

RGB integration involves modifications to LDK core code (commitment transaction construction, HTLC processing, channel state management, etc.). Before developing RGB features, we must ensure these modifications don't break native Lightning functionality.

BTC Channel Baseline

We validated BTC channel complete lifecycle across multiple sync backends (Esplora, Electrum, Bitcoin Core RPC/REST), including zero-confirmation channels, force close, Legacy static remote key, and other scenarios. All 9 tests passed.

Advanced Lightning Features

We also verified that LDK's advanced features continue to work correctly after RGB integration:

• BOLT 12 Offers: Reusable payment requests
• BIP 21 Unified QR: On-chain/Lightning unified QR code
• LSPS2 JIT Channels: Just-in-time inbound liquidity (LSP integration)
• Anchor Outputs: Fee-adjustable

These tests ensure that RGB code introduction has not affected the correctness of basic Lightning functionality.

4. RGB Channel Core Functionality Tests

RGB Overlay Primer The RGB/LN protocol uses an "overlay" mechanism to attach asset state to Bitcoin transactions. Each commitment transaction requires corresponding overlay data to correctly resolve RGB asset ownership. Losing the overlay means losing the ability to recover assets.

4.1 Force Close Asset Recovery

Test: channel_force_close_rgb_recovery

Scenario: After one party broadcasts a commitment transaction to force-close the channel, can both parties correctly recover their RGB assets?

Issues Discovered:

1. Missing callback trigger: When force-closing, the channel is removed from the manager; when the commitment TX confirms on-chain, RGB state update callbacks weren't triggered
2. Incomplete overlay storage: Each node only saved the counterparty's overlay, causing asset recovery failure when their own transaction was confirmed

Fix:

• Store both parties' commitment overlays (previously only stored counterparty's)
• Look up the matching overlay based on the actual on-chain confirmed transaction when channel closes
• Complete the callback trigger mechanism for force close scenarios

Result: Passed. Both parties can correctly recover RGB assets from force-closed channels.

4.2 HTLC Fail Asset Safety

Test: rgb_htlc_fail_asset_safety

Scenario: After the receiver actively rejects an HTLC, can the sender's RGB assets be correctly returned?

Issues Discovered:

Root Cause: Original code directly updated state on HTLC fail, lacking a rollback mechanism.

4.3 HTLC Timeout Asset Safety

Test: rgb_htlc_timeout_asset_safety

Scenario: After an HTLC reaches its timeout, can the sender's assets be automatically recovered?

Issues Discovered: Original code directly modified state after commit, completely lacking a rollback mechanism for timeout scenarios.

5. RGB_OFFSET_V2: Dynamic Balance Calculation Mechanism

Background

Issues 4.2 and 4.3 share the same root cause: the original design directly modified state on HTLC state changes, causing:

1. State asymmetry: Both parties calculated different RGB balances
2. Signature verification failure: Commitment transaction signatures couldn't pass
3. Triggered force close: LDK detected state inconsistency and initiated channel closure

RGB_OFFSET_V2 Core Improvements

Design Principle: Don't update final state until fulfill

Original Design:
  HTLC add → Update state → HTLC fail → Cannot rollback → State corruption

RGB_OFFSET_V2:
  HTLC add → State unchanged → HTLC fail → HTLC removed → Assets naturally restored
                             → HTLC fulfill → Update state + offset compensation

Core Mechanism: Dynamic Compensation

• When HTLC is fulfilled but not yet removed from the list, use offset to compensate balance calculation
• When HTLC is removed from the list, offset returns to zero
• Both parties can always calculate symmetrically consistent RGB balances

This design ensures that regardless of what intermediate state an HTLC is in, both parties' RGB balance calculations remain symmetrically consistent, fundamentally solving the asset safety issues in HTLC fail/timeout scenarios.

6. RGB↔BTC Swap Feature

Design Principles

The current implementation supports atomic exchange between RGB assets and BTC: Alice exchanges RGB assets for Bob's BTC, with HTLC mechanism guaranteeing atomicity—either both parties complete the exchange, or neither does.

Future Extension: Direct asset-to-asset exchange (RGB-A ↔ RGB-B) requires more complex routing mechanisms and is planned for future versions.

Role Definitions:

• Maker: Initiates the swap request, constructs the route
• Taker: Intercepts and validates the HTLC, executes forwarding

Implementation Highlights

• HTLC interception and validation mechanism
• Taker validates request legitimacy through Swap state
• Independent Swap state persistence (Offered → Accepted → InFlight → Settled/Failed)
• Supports multiple event convergence (PaymentSent / PaymentFailed / PaymentForwarded)

Test Validation

rgb_swap_full_cycle end-to-end test passed, validating the complete swap flow.

7. Infrastructure Improvements

TLV Serialization Optimization

Problem: Original TLV type numbers were in the BOLT reserved range (0-65535), risking official appropriation.

Solution: Migrated to RGB-dedicated range 75535-85534 (10,000 numbers), safely isolated from LDK's official custom range.

ChannelMonitor Persistence Fix

Problem: RGB channel context data wasn't persisted; after node restart, RGB channels couldn't be correctly identified.

Fix: Added dedicated TLV field to persist RGB channel context.

Development Tooling

• rgbldkd HTTP Service: Complete REST API control interface supporting channel management, payments, Swap, and all core functionality
• CLI Tool (rgbldk): Command-line client with JSON/Text dual output format for development and debugging

8. Test Coverage and Feature Matrix

BTC Channel Baseline

RGB Channels

Advanced Lightning Features

9. Technical Summary

Value of TDD Methodology

Phase 2 employed test-driven development:

1. Write test cases → Define expected behavior
2. Discover test failures → Expose protocol gaps
3. Implement fixes → Complete protocol capabilities
4. Verify passing → Confirm fix correctness

Not Bug Fixes, But Capability Completion

The original code only covered the normal payment flow (happy path). Phase 2 completed the protocol capabilities for edge cases:

10. Phase 3 Outlook

Phase 2 proved RGB Lightning integration's safety in edge cases. Phase 3 will focus on production-environment reliability:

Automation & CI/CD:

• Automated integration test pipelines
• Performance benchmarking
• Regression test coverage

Fuzzing & Chaos Engineering:

• Random payment sequence testing
• Boundary value testing (0, u64::MAX)
• Network failure simulation
• Node crash recovery

Production-Grade Fault Tolerance:

• Network partition handling
• Disk I/O error recovery
• Concurrent payment stress testing
• Resource exhaustion scenarios

Phase 2's completion marks RGB Lightning integration's transition from "prototype validation" to "feature complete". The next phase will equip it with the reliability and robustness required for production environments.