> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Understanding KaleidoSwap's decentralized architecture

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

## Core Components

<CardGroup cols={2}>
  <Card title="RGB Protocol" icon="layer-group">
    Client-validated smart contracts on Bitcoin enabling scalable and private asset issuance
  </Card>

  <Card title="Lightning Network" icon="bolt">
    Second-layer payment protocol providing instant, low-cost transactions
  </Card>

  <Card title="LSP Integration" icon="server">
    Lightning Service Providers offering liquidity and channel management services
  </Card>

  <Card title="Desktop Client" icon="desktop">
    Secure, user-friendly interface with full key control
  </Card>
</CardGroup>

## System Architecture

<img src="https://mintcdn.com/kaleidoswap/wIraRN-IMPyNpW_s/assets/images/architecture-overview.png?fit=max&auto=format&n=wIraRN-IMPyNpW_s&q=85&s=69abca0d8b59ebefdf97d47b0e2bfc89" alt="KaleidoSwap System Architecture" width="2752" height="1536" data-path="assets/images/architecture-overview.png" />

The platform connects 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](/whats-kaleidoswap/background#rgb-protocol).

**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

<Note>
  RGB interfaces were previously known by their schema numbers (RGB20, RGB21, RGB25). The current RGB standard names them **NIA**, **UDA**, **CFA**, and **IFA**.
</Note>

<Tabs>
  <Tab title="NIA - Fungible Assets">
    **NIA** (Non-Inflatable Asset, formerly RGB20) tokens are fixed-supply fungible assets similar to ERC-20 on Ethereum.

    **Use Cases**:

    * Stablecoins (USDT, USDC)
    * Tokenized commodities
    * Loyalty points
    * Currency tokens

    **Properties**:

    * Divisible
    * Interchangeable
    * Fixed supply (non-inflatable)
  </Tab>

  <Tab title="IFA - Inflatable Assets">
    <Note>
      IFA assets are **not currently supported** by KaleidoSwap. KaleidoSwap operates exclusively with NIA fungible tokens at this time.
    </Note>

    **IFA** (Inflatable Fungible Asset) tokens are fungible assets whose supply can be increased or decreased by the issuer (e.g. mint/burn).

    **Use Cases**:

    * Stablecoins with managed supply
    * Re-issuable utility tokens

    **Properties**:

    * Divisible
    * Interchangeable
    * Variable supply (issuer-controlled inflation/replacement)
  </Tab>

  <Tab title="UDA - NFTs">
    <Note>
      UDA assets are **not currently supported** by KaleidoSwap. KaleidoSwap operates exclusively with NIA fungible tokens at this time.
    </Note>

    **UDA** (Unique Digital Asset, formerly RGB21) tokens are non-fungible, unique digital assets.

    **Use Cases**:

    * Digital art
    * Collectibles
    * Identity tokens
    * Certificates

    **Properties**:

    * Unique
    * Non-divisible
    * Provably scarce
  </Tab>

  <Tab title="CFA - Collectibles">
    <Note>
      CFA assets are **not currently supported** by KaleidoSwap. KaleidoSwap operates exclusively with NIA fungible tokens at this time.
    </Note>

    **CFA** (Collectible Fungible Asset, formerly RGB25) provides collectible asset functionality with richer media and metadata.

    **Use Cases**:

    * Collectible series
    * Media-backed assets
    * Multi-edition items

    **Properties**:

    * Fungible within a collection
    * Rich metadata/media
    * Advanced state management
  </Tab>
</Tabs>

## Lightning Network Integration

### Why Lightning?

The Lightning Network provides the scalability layer for instant, low-cost RGB asset transfers. See [Concepts: Lightning Network](/whats-kaleidoswap/background#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 + NIA 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

<img src="https://mintcdn.com/kaleidoswap/wIraRN-IMPyNpW_s/assets/images/atomic-swap-flow.png?fit=max&auto=format&n=wIraRN-IMPyNpW_s&q=85&s=4e4a0582c9fdd1496bdefe81bf42ff8e" alt="Atomic Swap Flow" width="2752" height="1536" data-path="assets/images/atomic-swap-flow.png" />

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

<Steps>
  <Step title="Bitcoin Base Layer">
    Final settlement and security anchoring on Bitcoin blockchain
  </Step>

  <Step title="Lightning Layer">
    HTLC-based atomic swaps ensuring trustless execution
  </Step>

  <Step title="RGB Layer">
    Client-side validation preventing double-spending
  </Step>

  <Step title="Application Layer">
    Encrypted storage and secure key management
  </Step>
</Steps>

### 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

| Layer             | Throughput   | Finality    | Cost     |
| ----------------- | ------------ | ----------- | -------- |
| Bitcoin On-Chain  | \~7 TPS      | 10-60 min   | High     |
| Lightning Network | Millions TPS | Instant     | Very Low |
| RGB Contracts     | Unlimited    | Client-side | Minimal  |

### 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

<CardGroup cols={3}>
  <Card title="Key Features" icon="star" href="/whats-kaleidoswap/key-features">
    Explore core features and capabilities
  </Card>

  <Card title="Desktop App" icon="desktop" href="/desktop-app/getting-started/introduction">
    Atomic swaps with full node control
  </Card>

  <Card title="SDK" icon="code" href="/sdk/introduction">
    Build with our TypeScript or Python SDKs
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    REST API and swap protocol details
  </Card>
</CardGroup>