Skip to main content
All four packages (Rust, Python, TypeScript, React Native) share one version number. Each entry lists breaking changes first. The full history, including fixes, is in the repository’s CHANGELOG.md.

0.14.2 (2026-11-10)

Fixed

  • Submarine swaps that fund an asset (USDT-RGB or L-USDT to Lightning) no longer reject the maker’s quote: the amount to lock is checked with the pair card’s fees converted together with the payout. On chain swaps the bound is in the lockup’s units.

0.14.1 (2026-11-09)

Recommended for every 0.14.0 user of the KaleidoSwap API.

Security

  • A reverse swap’s claim is followed on chain from the moment it starts, until it confirms or something else spends the lockup, whatever the maker reports and while the maker cannot be reached. The swap is settled when its own claim confirms.
  • A claim falls back to the script path on any failure of the cooperative claim.
  • FileStore never hands out the same swap index to two instances or processes that share a directory.

0.14.0 (2026-11-08)

Breaking changes

  • TypeScript: PayThroughClient requires lightningNetwork and refuses an invoice for another network. See Pay an address from Lightning.
  • Rust: RfqQuote::verify_receive_invoice takes the Lightning network the client pays on.
  • Create calls that pass a pairHash are checked against that pair card. The reverse payout, the chain swap’s computed leg, and the submarine expectedAmount must stay within what the card’s rate and fees imply. A card the maker has since replaced is refused: read the card again and retry.

Added

  • The KaleidoSwap API, in the Rust core with TypeScript, Python, and React Native bindings: quote, start, and resume, one phase machine for every swap, and a store and signer you provide. It persists each swap before you fund it and claims or refunds on its own. It serves Lightning ↔ on-chain BTC and L-BTC. See The KaleidoSwap API.
  • simple/ examples on the KaleidoSwap API beside the advanced/ examples on the swap engine, in every binding. See Examples.
  • Submarine create responses check a non-empty bip21 against the response’s address, amount, and asset.

Changed

  • The atomic pair constants use the maker’s canonical pair ids (BTC@L1/USDT-RGB@L1, USDT-RGB@L1/BTC@L1).
  • Python: str() on a generated record prints swap_auth and blinding_key as <redacted>. The attributes stay readable.

0.13.0 (2026-10-28)

Breaking changes

  • Claims check the chain before revealing the preimage. constructClaim and prepareLiquidClaim refuse to build a claim unless your chain backend shows the lockup confirmed and unspent, with the tip outside the safety margin (6 blocks on Bitcoin, 60 on Liquid). The maker’s status is never used for this. A zero-conf claim needs allowZeroConf: true. The policy fields are minConfirmations, allowZeroConf, claimSafetyMarginBlocks, and allowConflictingSpend (snake_case on TransactionOptions in Python). See Claims and refunds.
  • L-USDT on testnet and regtest requires a pinned asset id. The create calls take lusdtAssetId (lusdt_asset_id on the request in Python). An L-USDT create without it is refused before any request is sent. On mainnet the SDK pins the canonical Liquid USDt itself.
  • React Native: SwapClient.kaleidoMaker refuses to run in an app unless you pass { allowMobile: true }, like allowBrowser in TypeScript. Create attributed swaps from a server, or use an organization key.
  • Rust: implementors of BitcoinClient and LiquidClient add get_tip_height and get_output_status.

Added

  • Timeout headroom checks at creation: validateReverseTimeoutHeadroom and validateChainTimeoutHeadroom refuse a response whose timeout is already too close to a tip you trust.
  • checkMrh(invoice, chain, network) returns a magic routing hint’s destination only after bounding its amount by the invoice.
  • LnurlOptions { allow_private_hosts } for development setups (Rust and Python).

Security

  • Create responses are bound to the amounts you requested: a reverse swap’s invoice must equal invoiceAmount, and a chain swap’s lockup and claim amounts must equal the request.
  • Browser requests to the maker refuse redirects, so a swap’s swapAuth never leaves the maker’s origin.
  • LNURL requests refuse non-public destinations, and LNURL-withdraw uses the same hardened transport as LNURL-pay.
  • Rust Debug and Python str() redact per-swap secrets.

Fixed

  • The React Native package loads the SDK again on Android.

0.12.0 (2026-10-19)

Breaking changes

  • TypeScript: createKaleidoMakerClient refuses workers and extensions. It already refused a page; it now also refuses Web, shared, and service workers and browser extension contexts. Pass allowBrowser: true to build it there on purpose. Plain Node is unaffected.
  • Rust and TypeScript: typed swap DTOs. Create, status, and restore methods return types generated from the Rust definitions instead of any. Response amounts and heights are bigint; request literals reject unmodeled keys (including pairId); RgbLock.cooperativeRefund is string | undefined. Rust struct literals for ClaimDetails, RefundDetails, SwapRestoreResponse, GetSwapResponse, and SwapEvent must set the new optional fields.

Added

  • Atomic BTC ↔ USDT-RGB swaps on L1: AtomicSwaps in TypeScript and atomic_* methods in Rust and Python. See Swap BTC and USDT on RGB.
  • Organization keys for client-side partner attribution: createKaleidoOrgClient, SwapClient.kaleido_org, KaleidoOrgClient. See Attribute swaps to your organization.
  • Pay-through idempotency keys: create(request, { idempotencyKey }) and supportsIdempotency().
  • Stateless claim and refund helpers in TypeScript with confirmation and timeout checks. See Claims and refunds.
  • SwapScript.fromRestored rebuilds scripts from restore entries.
  • Lightning address and LNURL-pay lookup: resolveLightningAddress / resolve_lightning_address.
  • Corridor discovery card: corridorCard() and corridorCardRaw().
  • Esplora chain-data helpers in @kaleidorg/swap-sdk/chain-data.
  • Transaction recovery from saved hex: BtcLikeTransaction.fromHex.
  • SwapWsApi.close() (TypeScript) and shutdown() (Python) stop a status stream.

Security

  • Claims require trusted chain evidence and pin the lockup transaction before revealing a preimage; automatic claims fall back to the script path after a failed cooperative claim.
  • Esplora broadcasts check the HTTP status and parse the returned txid.
  • LNURL-pay resolution requires HTTPS on clearnet, rejects redirects, and verifies the invoice description hash.

0.11.0 (2026-10-12)

Breaking changes

  • Rust core: RGB-aware Bitcoin swap scripts. Rust struct literals for Cooperative, TransactionOptions, BtcSwapScript, and the submarine and reverse create responses gain optional fields (swap_auth, rgb); add None where you build them. Currency gains UsdtRgb. Python defaults the new fields; TypeScript is unchanged.

Added

  • USDT-RGB submarine and reverse swaps in Rust, Python, and TypeScript, with rgb-lib wallet integration. See Swap BTC and USDT on RGB.
  • RGB cooperative submarine refunds (rgb-coop-refund-v1).
  • Cooperative refund authorization with swapAuth, and signed credential recovery with recoverSwapAuth.

0.10.0 (2026-09-24)

Breaking changes

  • Rust core: chain-swap validation takes the preimage hash. TypeScript and Python call sites are unchanged.

Added

  • Swap responses are checked on every route: hashlock, timeout height and encoding, lockup txid, claim preimage, counterparty key, and dust.
  • Multi-output claims and refunds.
  • @kaleidorg/swap-sdk/pay-through, a client for the maker’s pay-through API.

0.9.0 (2026-09-23)

Breaking changes

  • The binding surfaces stop saying Boltz. There are no aliases; rename on upgrade:

Added

  • Versioning and security policies, and runnable TypeScript examples.