KaleidoSwap Architecture

KaleidoSwap is vertically integrated: a single SDK powers 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, wallet engine, and MCP/AI tooling are open source (MIT) and inspectable on GitHub; the browser extension and the maker-side RFQ engine are not public today.

​

Integration layer

Two packages sit between an application and the protocols. Both are consumed by our own clients on exactly the same terms as by an external integrator. kaleido-sdk exposes two sub-clients — client.maker for the market side and client.rln for node operations — and generates its types from the same OpenAPI specifications that the backend serves, so TypeScript and Python never drift apart.

​

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; Lightning carries it; the shared preimage makes it atomic. On the shipped BTC ↔ RGB path, the flow is:

1. The taker streams quotes from the maker over WebSocket and receives an rfq_id with each one.
2. POST /api/v1/swaps/init locks the rate and returns a swapstring and a payment_hash.
3. The taker’s RGB Lightning Node whitelists the swapstring, authorising it to route through the node.
4. POST /api/v1/swaps/execute starts the HTLC.
5. Lightning routes it: the maker reveals the preimage to claim one leg, which simultaneously releases the other.
6. If either side stalls, the timelocks expire and both sides recover their own funds.

The taker’s node is the one holding keys and validating state throughout — the maker never takes custody. Full endpoint reference and sequence diagram: Atomic Swap Protocol.

​

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 RGB LSPS1 APIs 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.