How KaleidoSwap Works: Bitcoin, Lightning & L2s

Bitcoin is no longer one layer. Assets now live on Lightning channels, on statechains, in virtual UTXOs, on a federated sidechain, and on client-validated overlays anchored to Bitcoin itself. Each of those layers has its own state model, and none of them can read another’s balance sheet. What almost all of them can express is a hash-locked contract: pay out only to whoever reveals the preimage of a hash, or refund after a deadline. That single shared primitive is what KaleidoSwap builds on. One preimage, used on both legs of a trade, makes an exchange across two incompatible layers either complete on both sides or complete on neither.

​

Bitcoin: the settlement layer

Every KaleidoSwap wallet is a Bitcoin wallet at its core: it holds UTXOs, signs transactions, and broadcasts to the Bitcoin network. On-chain transactions are used for:

• Wallet funding — depositing BTC before moving to a faster layer
• Channel opens and closes — anchoring Lightning channels to the chain
• RGB commitments — embedding asset state transitions into Bitcoin transactions
• Peg-ins and exits — entering and leaving Liquid, Arkade, or Spark

Bitcoin is where value ultimately settles and where every layer above inherits its security.

​

Lightning: the interoperability bus

The Lightning Network is a second-layer protocol that moves value through bidirectional payment channels instead of blocks. In KaleidoSwap it plays two distinct roles. The first is fast, cheap payments. Swaps settle in seconds rather than confirmations, and fees are measured in satoshis. The second is the reason the whole stack works: Lightning is the interoperability bus. Most Bitcoin layers can be reached over Lightning, either natively or through a provider, and Lightning’s HTLCs are hash-locked. That makes it the common medium a cross-layer trade can be routed through, even when the two layers involved know nothing about each other.

​

The layers KaleidoSwap connects

​

Asset overlays: RGB

RGB is a client-validated smart contract system built on top of Bitcoin (see the official RGB protocol documentation for the full specification). Unlike account-based smart contract platforms, RGB keeps contract logic and state off-chain, using Bitcoin transactions only as cryptographic commitments. That gives it:

• Privacy — asset balances and transfers are not visible on the blockchain
• Scalability — no chain bloat from token transfers
• Bitcoin security — asset state is anchored to Bitcoin’s proof-of-work
• Programmability — all four RGB interfaces supported: NIA fungible tokens (USDT, XAUT), IFA, UDA, and CFA

RGB is an overlay, not a layer of its own: the same asset can sit on a Bitcoin UTXO or ride inside a Lightning channel. Riding inside a channel is what makes RGB assets tradable at Lightning speed, and what powered the first ever RGB asset swap on Lightning mainnet, executed by KaleidoSwap in 2025.

​

How a swap works

KaleidoSwap uses a Request for Quote (RFQ) model rather than an automated market maker. You ask for a price, a market maker answers, and you decide whether to take it. For the wire-level detail — endpoints, the swapstring, and the sequence diagram — see Atomic Swap Protocol.

​

Where atomicity holds

Atomicity is a property of the layers a trade touches. Two things decide it, and they are independent: whether the layer has a native hashlock, and whose guarantee enforces it.

• Enforced by Bitcoin consensus. Bitcoin L1, Lightning, and RGB on Lightning. The hashlock needs no one’s cooperation, so neither side can walk away with both assets.
• Enforced within a layer’s own trust model. Spark exposes HTLCs, Arkade builds VHTLCs from Tapscript, and Liquid inherits Bitcoin Script. The hashlock is real, but it carries that layer’s assumptions (an operator set, a server signature, a federation) so the leg is atomic within the layer, not below it.
• Provider-mediated. No native hashlock at all: a service bridges the leg, you trust it for the duration, and the trade is not atomic end to end.

KaleidoSwap’s shipped atomic path is BTC ↔ RGB assets over Lightning. Other routes run through supported venues and are labelled as such in the apps. Extending native hash-locked settlement to more layers is active work; on Spark, Arkade, and Liquid the constraint is our implementation, not a missing primitive.

​

Liquidity: LSPs and market makers

A hash-locked trade still needs someone on the other side, with the right asset, in the right place. Lightning Service Providers (LSPs) solve the placement problem. Rather than hunting for peers and sizing channels yourself, you connect to an LSP that:

• Opens channels on demand — order inbound liquidity when you need it, optionally pre-loaded with an RGB asset
• Routes payments — allowing your transactions to reach their destination
• Implements LSPS1 — the standard channel-ordering interface, which KaleidoSwap extends to RGB assets
• Facilitates swaps — acting as the counterparty that locks the other leg

Market makers solve the pricing problem: they publish quotes into the RFQ engine and earn the spread plus routing fees. Today the KaleidoSwap LSP bootstraps this liquidity itself; external makers compete on the same interface from 2027, which is what turns a single counterparty into a market.

​

Networks