|

RGB on Liquid: Inside KaleidoSwap’s Simplicity Proof of Concept

ByRGB Team
RGB on Liquid: a seal anchored on Bitcoin or Liquid, with a Simplicity covenant rejecting spends that lack an RGB commitment

RGB Protocol on Bitcoin keeps an asset’s full history off-chain: the chain only ever carries a small cryptographic commitment inside an ordinary transaction. RGB on Liquid applies the same model to Blockstream’s Liquid sidechain, anchoring RGB assets on Liquid transactions instead of Bitcoin ones. KaleidoSwap tested the portability of this system, and then used Liquid’s smart-contract language, Simplicity, so that the chain itself enforces the RGB commitment rules.

In Brief

  • KaleidoSwap made RGB on Liquid work with a 207-line patch across seven files that leaves existing Bitcoin behavior unchanged: all 45 existing tests still pass without errors, and four libraries built on RGB need no changes. The patch is proposed as an RFC, and an RGB maintainer has confirmed the direction.
  • It works because Bitcoin and Liquid define Taproot outputs identically (BIP-341): the standard RGB Tapret verifier read a real Liquid transaction unmodified.
  • A Simplicity covenant, built on an Opret-style commitment, makes Elements consensus reject any spend of an RGB seal that lacks an RGB commitment.
  • The team issued an asset and completed an atomic swap between Bitcoin and Liquid, with no custodian, on regtest.

Why Did KaleidoSwap Run RGB on Liquid?

An RGB contract has two layers.

  • The first is client-side validation: the asset’s issuance rules and full transfer history are checked by each holder off-chain, independently of any particular blockchain.
  • The second is the anchor: a single-use seal binds each transfer to a real on-chain transaction, so spending the seal’s UTXO settles the transfer and prevents double-spending.

Because each contract is bound to a single chain from its genesis, an asset issued for Bitcoin and one issued for Liquid are two separate contracts, not one asset in two places. Moreover, since a seal is an ordinary UTXO, the spending conditions the chain supports apply to the asset as well: Bitcoin Script on Bitcoin, and potentially something far more expressive on Liquid.

Liquid was the natural next chain to try. It has one-minute blocks, confidential transactions and a federated peg already used by exchanges and traders. Since July 2025 it also has Simplicity, a formally verifiable smart-contract language that Bitcoin’s base layer doesn’t offer.

How Big Was the Gap Between RGB and Liquid?

The gap turned out to be small: the RGB code already had much of the groundwork for Liquid. While going through the code, KaleidoSwap found three things:

  • a Liquid variant already existed in the RGB chain enum (the fixed list of blockchains known to the code);
  • LiquidMainnet and LiquidTestnet were already listed as networks;
  • a contract’s genesis already recorded the chain of the contract.

None of these parts were connected to the code that actually checks transactions.

Likewise, the cryptography needed no new design. RGB hides its commitment inside an ordinary-looking Taproot output, and Bitcoin and Liquid define that output format identically under BIP-341. KaleidoSwap confirmed the match: the standard, unmodified RGB verifier accepted an output in a real, confirmed Liquid transaction as carrying a valid RGB commitment.

What Changed with the 207-Line Patch?

RGB checks a transfer by reading the on-chain transaction that anchors it.

The code relied on a transaction format built only for Bitcoin, so it couldn’t read a Liquid transaction, which is structured differently (it has confidential amounts, an explicit asset for each output and an explicit fee output). Nonetheless, those three places only needed a few basic details: the transaction’s inputs, to confirm the spending of the seal, and its output scripts, to find the commitment.

KaleidoSwap’s patch stops the code from depending on the Bitcoin-only transaction format, so the code requests only the details it needs to verify a transfer (the inputs and the output scripts) through a small common “adapter”, available for any type of transaction. Nothing changes for existing Bitcoin users, and Liquid transactions can now go through the same Bitcoin verification path.

The modification is small: 207 lines across seven files. All 45 existing tests, which check the correct behavior of RGB, still pass without errors. Four other libraries built on top of the RGB code (rgb-ops, rgb-schemas, rgb-invoicing and rgb-aluvm) also build against it without any changes of their own, the strongest sign that the patch doesn’t break anything else.

The adapter isn’t specific to Liquid, which means any blockchain that tracks funds as UTXOs could use it. KaleidoSwap sees it as a step toward portable client-side assets across Bitcoin’s different layers, not just a Liquid fix.

As a demonstration, the team issued a real asset on Liquid with RGB tools and transferred it between two holders. The transfer, which included a change output (the leftover amount sent back to the sender), was recorded in a Liquid transaction and verified from start to finish. The patch is now proposed to the RGB maintainers as an RFC (a formal proposal open to review by the maintainers before any approval), tracked as rgb-consensus#12. An RGB maintainer replied that the direction looks good and gave implementation guidance: the new code stays in the consensus library, and Liquid support becomes an optional feature, leaving builds for Bitcoin only unchanged. KaleidoSwap agreed to all the points and will update the patch after the publication of upcoming changes to the consensus library.

RGB consensus verification path: a 207-line WitnessTx adapter lets Bitcoin and Liquid transactions pass through the same RGB verification

Image credits: Kaleidoswap

How Do You Swap Between Bitcoin and Liquid Without a Custodian?

An asset always stays on the chain of its contract’s genesis, so it cannot move from Bitcoin to Liquid and back. The practical alternative is an atomic swap: a trade that either completes on both sides or doesn’t happen at all, with no third party ever holding both assets at once.

To test a swap, KaleidoSwap created a real RGB token on Bitcoin and another on Liquid, both on regtest. The two tokens were exchanged in a single linked operation, tied together by one shared secret. When one party reveals the secret to claim their side of the swap, it becomes public, so the other party can use it to claim theirs. Neither can walk away with both assets, and neither can cheat.

The team made the mechanism safer and closer to real-world use through a Hash Time-Locked Contract (HTLC) on both chains. In an HTLC, funds stay locked until the recipient reveals the secret, or go back to the sender after a deadline. Here, only the claimer’s key can use the claim path, and the refund path opens only after the deadline. The team also tested the behavior of the swap in unexpected situations: the HTLC rejects a wrong secret and an early refund, and accepts a refund after the deadline.

One assumption had to hold for RGB to work on Liquid, whose confidential transactions hide amounts. RGB places its commitment in the scriptPubKey (the part of an output that defines the conditions for spending it), a field that Elements (the software behind Liquid) never hides. As a result, the unmodified RGB verifiers could read the commitment without any unblinding data. KaleidoSwap calls it the “load-bearing assumption behind RGB on Liquid”, the foundation for everything else, and the test confirmed its validity.

The result is an “RGB-wrapped claim”: a single transaction spends the HTLC, carries the RGB commitment and re-anchors the asset on the claimer’s own output. The swap is settled and the asset moves in one atomic step, meaning it either happens completely or not at all.

How Does Simplicity Make Liquid Enforce RGB Rules?

A Simplicity covenant (a rule attached to a coin that limits the ways of spending it) makes a Liquid node reject any spending of an RGB seal that doesn’t carry an RGB commitment.

Liquid already supports covenants: the rules that lock a coin can inspect the transaction trying to spend it. Liquid’s Taproot upgrade added over thirty introspection opcodes, already used in production by Blockstream’s options contracts.

Simplicity goes a step further: it can express complex contracts with many conditions and any finite computation, without Script’s size and opcode constraints, and a program’s behavior can be proven mathematically. Through SimplicityHL (a Rust-like language that compiles down to Simplicity), developers can attach a Simplicity program to an output as one more way of spending it, alongside the ordinary ones.

Because an RGB seal is just an ordinary UTXO, a Simplicity program can limit the spending of the seal without ever needing to understand the RGB contract riding on top of it. KaleidoSwap wrote a covenant, in SimplicityHL, that locks an RGB seal under two conditions at once: the spender must reveal the secret behind a given hash, and the spending transaction must carry, at output 0, an output shaped exactly like an RGB commitment (an OP_RETURN followed by a 32-byte payload).

The covenant targets Opret rather than Tapret, because a Tapret commitment hides inside the output’s key, using a value the covenant can’t know in advance, while an Opret commitment lies in a plain data field with an easily verifiable shape.

In the decisive test, the team built a transaction that satisfied the program, then removed the commitment output and rebroadcast it. Elements consensus rejected it. The rule that spending an RGB seal must carry an RGB commitment is enforced at the consensus level, instead of being left to wallet software to check afterward. Whether the transfer itself is valid is still checked client-side. So far it works only on regtest.

Programmable seals on Liquid: six uses of Simplicity covenants for RGB assets, from chain-enforced swaps to lending, vault custody and private programmability

Image credits: Kaleidoswap. Since publication, backed minting also has a regtest prototype.

What Could Programmable Seals Unlock?

Pairing Simplicity covenants with RGB seals opens up possibilities well beyond swaps. Of the ideas below, the first is demonstrated, and backed minting has a regtest prototype in the repo; the others are still proposals:

  • Chain-enforced swaps: demonstrated, as described above.
  • Lending against RGB collateral: Blockstream is already building a Bitcoin-collateralized lending application on Simplicity. The same structure could lock an RGB asset’s seal under a loan covenant: the asset returns to the borrower on repayment, or goes to the lender on default, with no liquidator and no custodian holding the collateral.
  • Verifiably backed dollar issuance: Liquid already hosts Tether’s USD₮ natively, so creating a new RGB dollar asset could require locking native USD₮ in a covenant vault in the same transaction, making the backing publicly auditable on-chain. The repo already includes a regtest prototype of a backed-minting covenant, which allows permissionless minting against a locked vault. KaleidoSwap openly acknowledges that redemption remains the open problem: the chain can’t validate RGB state on its own, so exits would still need a release verified by an operator, or an atomic swap against market-maker liquidity.
  • Vault custody for RGB holdings: a recursive covenant (one that applies itself to the following output) could force every spend through a delayed staging step, cancelable with a recovery key. If someone steals a key, the real owner has time to step in and block the theft.
  • Protected market-maker inventory: a trading venue’s hot wallet could hold its seals under a covenant that only allows spends shaped like a swap, so a stolen hot key alone can’t drain the inventory to an attacker’s address. The idea is directly relevant to an RFQ venue (where market makers quote prices on request) like KaleidoSwap’s own maker model.
  • Programmability without losing privacy: ordinary Liquid covenants that need to inspect an amount generally require the unblinding (revealing) of that amount, forcing a tradeoff between programmability and confidentiality. RGB sidesteps the tradeoff, since asset amounts never touch the chain: the covenant only constrains an ordinary Liquid output, while the actual asset ledger stays off-chain and private.

The result draws a clear line between the two layers. In RGB, the logic of private contracts runs on AluVM, the RGB virtual machine, and is validated client-side. In this integration, Simplicity operates on the other side of the boundary: underneath RGB, guarding the seals on-chain, while AluVM keeps governing the private contract logic off-chain.

What’s Left Before the Launch of RGB on Liquid?

KaleidoSwap already supports Liquid and, separately, RGB on Bitcoin mainnet in its browser extension, currently in closed beta. RGB on Liquid, combining the two, is one option for KaleidoSwap’s next integration. For now, though, everything described here is an engineering proof of concept, tested only on Bitcoin and Liquid regtest and not shipped to production.

Making it ready for wallets still requires ordinary engineering work:

  • The 207-line patch has to be updated following the maintainer’s guidance and the upcoming consensus changes, and then merged; full validation on Liquid also needs a second step, making the code that looks up transactions work with Liquid ones as well.
  • Wallets need a way to fetch Liquid transactions during validation.
  • The RGB wallet library needs a Liquid version of the issue, send and receive functions it already offers for Bitcoin.
  • Swaps need a coordinator to handle timeouts, refunds and the exchange of consignments (the data packages that carry an asset’s history).
  • The covenant needs two additions to be production-ready: the claimer’s signature and a refund path.

Further Reading

Similar Posts