0
Date: 25.10.2025
Scope: Detail the architectural choices for integrating the Lightspark platform for Lightning Network (LN) payment rails and wallet features into the existing RSK-focused Bitcoin Payment System.
1
Requirement & Rationale
The Colabonate ecosystem requires high-speed, high-volume, low-fee standard payment rails for services, subscriptions, and small transfers. Legacy L1 Bitcoin and RSK consensus times are inappropriate for these use cases. Lightspark is integrated to serve as the exclusive standard transaction layer, leveraging its enterprise-grade infrastructure to reduce on-chain congestion and transaction costs, while retaining HID-based verification.
2
Wallet Abstraction Layer (Lightspark Support)
The Colabonate Wallet must serve as a unified user interface, abstracting the complexity of managing funds across L1, RSK (RBTC/Forks), and L2 (LN).
2.1
Custody Model Decision
Leveraging Lightspark’s enterprise-grade node management, we adopt a Managed Custodial Model for all standard users. This abstracts away the complexity of node and channel management.
| Model | Description | Pros | Cons | Decision Rationale |
|---|---|---|---|---|
| Non-Custodial (NC) | User controls their own LN private keys and manages their own channels. | Highest security, user autonomy. | Poor UX, high maintenance, potential for offline payment issues. | Retained as an option for advanced users who wish to connect their own nodes to the ecosystem. |
| Managed Custodial (MC) | L1/RSK funds remain non-custodial. LN funds are managed by Colabonate’s infrastructure, which is built upon the Lightspark Grid. Lightspark handles node uptime, liquidity, and routing. | Superior UX, zero channel management for users, high reliability, enterprise-grade security and compliance. | Reliance on Lightspark as a service provider. | Adopted Model: The MC model provides the best balance of user experience and robust infrastructure, allowing Colabonate to focus on its core DAO functionalities. Trust is mitigated by the Audit Layer and Lightspark’s proven reliability. |
Decision: Adopt a Managed Custodial (MC) model for all standard users. All Lightspark-powered transactions will be logged in the Audit Layer and linked to the user’s HID. Non-Custodial LN support remains an optional feature for power users.
2.2
Wallet Features
- Balance Aggregation: Display a single aggregated Bitcoin balance, clearly segmented into: L1/RSK balance, Lightspark Balance (MC or NC), and Fork Asset balance.
- Automatic Switching: The wallet automatically selects the Lightspark rail for standard payments below a defined threshold (e.g., $100 USD equivalent) and the RSK/L1 rail for higher values or governed transactions (Escrow, Fork Transfer).
- HID Authorization: Every Lightspark invoice generation or payment execution must pass an internal HID check (e.g., authenticated session linked to the HID-key context) before execution via the Lightspark API.
- Stablecoin Support: The wallet will natively support sending and receiving stablecoins via Spark, Lightspark’s Layer-2 solution, treating them as a distinct asset type within the Lightspark balance.
3
Lightspark Payment Module (LPM)
The LPM is the backend infrastructure responsible for all Lightspark operations, acting as a bridge between the Colabonate ecosystem and the Lightspark Grid.
3.1
Infrastructure & Integration
- Node Management: All Lightning node operations, including uptime, routing, and liquidity, are fully managed by Lightspark’s enterprise-grade infrastructure. Colabonate does not need to run its own nodes for standard user transactions.
- API Integration: The LPM will integrate directly with the Lightspark API and developer toolkits (e.g., Lightspark SDKs) to perform all payment actions.
- HID-Linked Accounts: Each user’s Lightspark balance is represented as an account within the Colabonate system, mapped directly to their HID. All API calls to Lightspark will be authorized and logged against this HID-linked account.
3.2
Invoice Generation & Settlement Workflow
- Request: A user initiates a standard payment (e.g., buying a feature), requests a payment, or initiates a stablecoin transfer.
- HID Check: The system verifies the initiator’s active HID context via the Identity Layer.
- Invoice Generation: The LPM calls the Lightspark API to generate a universal, compliant invoice (e.g., using UMA for enhanced data). This applies to both Bitcoin and Spark stablecoin transactions.
- Payment: The payer’s wallet (or an external wallet) settles the invoice via the Lightspark Grid.
- Audit Logging: Upon successful settlement confirmation from the Lightspark API, a detailed transaction record (Payment Hash, Value, Asset Type, HID Originator/Recipient, UMA data if applicable) is immediately logged to the Audit Layer’s Off-Chain Index. This ensures all payments are traceable for DAO governance and dispute resolution via the Ticket System.
4
Interoperability with RSK & Governance
Lightning transactions, being off-chain, must maintain adherence to the on-chain governance rules where necessary.
- Fork Transactions: Trading or management of Codex Forks remains strictly on the RSK Contract Layer due to the need for atomic execution and static governance assurance. LN is unsuitable for Fork transfers.
- Liquidity Governance: High-value operations, such as moving significant funds from the Colabonate L1/RSK treasury to the Lightspark operational wallet for liquidity, require Proximity Proof authorization.
- RSK Bridge Interoperability: A direct, programmatic bridge between RBTC on RSK and the Colabonate Lightspark operational wallet is necessary for rapid on/off-boarding of funds. This process, managed by the LPM, minimizes friction for funding and defunding the L2 infrastructure. This link must be secured by multi-signature governance defined by the DAO.
5
5. Security & Audit Implications
The integration of Layer 2 requires tailored security controls.
- L2 Anti-Fraud: Colabonate will leverage Lightspark’s built-in compliance and anti-fraud capabilities (e.g., via UMA). The LPM will also monitor transaction patterns for anomalies specific to the DAO’s activities and report them to the Audit Layer.
- MC System Auditability: The Managed Custodial model requires granular auditing. The Audit Layer must log:
- Funding/defunding operations between L1/RSK and the Lightspark operational wallet.
- All payment settlements confirmed by the Lightspark API.
- HID linkage for every invoice and payment.
- Key Management: The private keys for Colabonate’s operational wallets used to fund the Lightspark integration must be managed using robust hardware security modules (HSMs). Access to large funds requires a quorum multisig controlled by the DAO via RSK smart contract governance.
