Architecture Overview

KaleidoSwap operates on a decentralized architecture that combines the power of RGB Protocol with the scalability of the Lightning Network.

​

Core Components

​

System Architecture

The platform consists of three client interfaces (desktop app, web app, and browser extension) that connect to RGB Lightning Nodes and Lightning Service Providers, all anchored to the Bitcoin blockchain for final settlement.

​

RGB Protocol

​

RGB Protocol Overview

RGB enables scalable and confidential smart contracts on Bitcoin using client-side validation. For a detailed explanation of how RGB works, see How RGB Works. Key Architectural Features:

• Client-Side Validation: Contract state is validated by the recipient, not globally
• Scalability: No blockchain bloat - contracts are off-chain
• Privacy: Transaction details are only known to involved parties
• Bitcoin Security: Anchored to Bitcoin blockchain for security

​

RGB Asset Types

​

Lightning Network Integration

​

Why Lightning?

The Lightning Network provides the scalability layer for instant, low-cost RGB asset transfers. See Concepts: Lightning Network for more details. Integration Benefits:

• Instant Settlement: Transactions complete in milliseconds
• Low Fees: Fraction of on-chain costs
• Security: Backed by Bitcoin’s security model
• Scalability: Millions of transactions per second

​

How It Works

1. Payment Channels: Users open bidirectional payment channels
2. Off-Chain Transactions: Multiple transfers happen off-chain
3. Channel State: Only final state is settled on Bitcoin blockchain
4. Routing: Payments route through network of channels

​

RGB on Lightning

KaleidoSwap extends the Lightning Network to support RGB assets alongside native BTC:

• Transfer USDT instantly through Lightning channels
• Trade assets atomically via HTLC-based atomic swaps
• Multi-asset channels supporting BTC + RGB20 tokens simultaneously

​

Lightning Service Providers (LSPs)

​

LSP Integration

Lightning Service Providers (LSPs) are critical for onboarding users to the Lightning Network without requiring them to manage complex channel operations manually. LSP Functions in Architecture:

• Liquidity Provision: Opening channels with users to provide inbound capacity
• Routing: Finding optimal paths for payments
• Swap Facilitation: Enabling atomic swaps between assets

​

RGB LSPS1 Specification

KaleidoSwap implements the RGB Lightning Service Provider Specification (RGB-LSPS1):

• Standardized Interface: Common API for LSP interactions
• Asset Allocation: Specify RGB assets when opening channels
• Swap Support: Built-in atomic swap functionality
• Fee Transparency: Clear fee structure for all operations

​

Desktop Client Architecture

​

Non-Custodial Design

Everything runs on your device. The desktop application communicates directly with your RGB Lightning Node, which manages keys locally, controls channels, and validates contracts. No third party ever has access to your funds. Security Principles:

• Your Keys, Your Coins: Private keys never leave your device
• Encrypted Storage: All sensitive data encrypted locally
• No Custody: No third party can access your funds
• Client Validation: You validate all RGB contracts

​

Component Layers

1. UI Layer: React-based desktop interface
2. Business Logic: State management and workflow orchestration
3. Node Interface: Communication with RGB Lightning node
4. Network Layer: P2P connections and LSP integration

​

Data Flow

​

Atomic Swap Process

The atomic swap uses Hash Time-Locked Contracts (HTLCs) to ensure trustless execution:

1. Request Quote — Taker requests a price for the asset pair
2. Init Swap — Taker initiates the swap, creating an HTLC
3. Lock Assets — Both sides lock their assets (BTC and RGB) in HTLCs
4. Reveal & Claim — The secret is revealed, allowing both parties to claim
5. Complete — Both parties receive their swapped assets atomically

​

Security Model

​

Multi-Layer Security

​

Trustless Trading

• No Counterparty Risk: Atomic swaps execute atomically or fail completely
• No Custodians: Users maintain control of their keys and assets
• No Trust Required: Cryptographic guarantees, not trust in intermediaries

​

Scalability

​

Transaction Throughput

​

Why This Matters

• Mass Adoption: Can scale to billions of users
• Micro-Transactions: Economically viable even for tiny amounts
• Real-Time Trading: No waiting for blockchain confirmations

​

Next Steps