KaleidoSwap Architecture

KaleidoSwap is vertically integrated: the same SDKs power every client we ship and every third-party integration, so each surface talks to the same swap engine, the same protocol adapters, and the same liquidity. Adding a protocol once makes it available everywhere; adding a client costs no new protocol work. This page walks the stack from the top down. For the protocols themselves and why hash-locked contracts make cross-layer trades possible, start with How It Works. For the broader multi-protocol thesis behind this design, read Solving Bitcoin’s L2 liquidity problem.

The stack

The desktop app, SDKs, CLI and wallet engine are open source under MIT, and the AI tooling (kaleido-mcp, KaleidoAgent, KaleidoMind) under Apache 2.0, all inspectable on GitHub; the browser extension and the maker-side RFQ engine are not public today.

Integration layer

Three packages sit between an application and the protocols. Our own clients consume them on exactly the same terms as an external integrator.

Protocol layer

Every Bitcoin Layer ships its own SDK, address formats, and quirks: channel liquidity here, boarding transactions there, static receive addresses somewhere else. Left unmanaged, that becomes a protocol check on every screen of every app. Instead, each protocol implements one adapter contract: connect, list assets and transactions, create and decode invoices, send, receive, and optionally quote and execute swaps. Differences between protocols live as data in a capability manifest, not as branches in application code. The router and the UI read that manifest and never special-case a protocol by name. The practical consequences:

• Adding a protocol touches one adapter and one manifest entry — never another protocol’s path.
• Clients call one API, never a protocol SDK directly, so behaviour is consistent across Desktop, Extension, and Mobile.
• The router picks the rail. Given a destination — a Lightning invoice, a Bitcoin address, an RGB invoice, a Liquid address — it resolves which protocols can pay it and which is best.
• One receive QR can carry several protocols at once, so any wallet can pay it while KaleidoSwap wallets read the richer parameters.

Swap engine

Swaps use a Request for Quote model settled by hash-locked contracts. The maker prices the trade; the shared preimage makes it atomic. The maker’s /v2 API is wire-compatible with the Boltz swap protocol. Through the Swap SDK, a client:

1. Reads the maker’s pair catalogue and creates a swap with its own public key and, for swaps it claims, the hash of its own secret.
2. Rebuilds the swap’s Taproot contract locally and checks it against the maker’s answer before funding anything.
3. Funds a lockup on chain, or pays a Lightning hold invoice, depending on the direction.
4. Claims the other side with the secret, which lets the counterparty settle. If either side stalls, the timeout lets each side recover its own funds.

The same pattern covers on-chain → Lightning, Lightning → on-chain, and chain-to-chain swaps across Bitcoin and Liquid, with USDT on RGB through HTLC swaps or single-transaction atomic swaps, and Arkade through the Intents corridor. The client holds the keys throughout; the maker never takes custody. Step by step: How swaps work and Swap flow. RGB assets inside Lightning channels use a node-to-node variant of the same idea: two RGB Lightning Nodes exchange a hash-locked payment for an asset payment. That path is part of the Node SDK and the Desktop App.

Liquidity layer

Lightning Service Providers

LSPs make Lightning usable without manual channel operations. In the architecture they:

• Provide liquidity — open channels with inbound capacity, optionally pre-loaded with an RGB asset
• Route payments — find paths for both payments and swap legs
• Act as counterparty — locking the other leg of a swap

RGB-LSPS1

KaleidoSwap implements the RGB Lightning Service Provider Specification, extending the standard LSPS1 channel-ordering flow to assets:

• Standardised interface — one API shape for LSP interactions
• Asset allocation — specify RGB assets when ordering a channel
• Swap support — atomic swap coordination built into the same surface
• Fee transparency — costs stated before you commit

See the Maker API for the endpoints.

Market makers

The RFQ engine is designed for competition on the maker side. Today the KaleidoSwap LSP bootstraps liquidity itself. From 2027, external market makers connect through the same interface and compete on spread.

Intelligence layer

The AI surfaces are clients of the same stack. They call the same tools a human interface calls, with the same confirmation gates.

Client architecture

Non-custodial design

Everything that touches keys runs on your device. Clients hold or drive the wallet locally, validate state themselves, and talk to makers and LSPs only over the network interfaces above. No third party has access to your funds at any point in a swap.

• Your keys, your coins — private keys never leave your device
• Encrypted storage — sensitive data encrypted at rest with your password
• No custody — makers and LSPs are counterparties, never custodians
• Client-side validation — you validate RGB state yourself rather than trusting a server

Protocol coverage per client

Component layers

Inside a client the separation is the same regardless of platform:

1. UI layer — the interface, per platform
2. Business logic — state management and workflow orchestration
3. Protocol layer — wallet-engine adapters and the cross-protocol router
4. Network layer — node RPC, maker APIs, LSP integration, P2P connections

Security model

What trustless means here

• No counterparty risk — on atomic paths the swap completes on both sides or neither
• No custodians — you keep your keys and your assets throughout
• Cryptographic guarantees — enforced by timelocks and preimages

Settlement characteristics

Different layers make different trade-offs, which is why the stack uses several. There is no layer that is fastest, cheapest, and most final at once. Lightning is where trading happens because it settles in seconds at negligible cost; Bitcoin L1 is where positions come to rest. The hashlock column is what decides whether a leg can be atomic, and under whose guarantee — see Where atomicity holds.

RGB asset interfaces

RGB defines several asset interfaces, previously known by their schema numbers. The wallet supports all four; trading covers NIA assets today. Definitions for each term are in the Glossary.