Core Concepts

`IProtocolAdapter` — the contract

Every protocol implements the same interface: connect, list assets and transactions, create and decode invoices, send and receive, and optionally quote and execute swaps. Two flavours ship — native adapters (direct SDK integrations) and WDK-backed adapters. Both satisfy the same contract, so app code cannot tell which is underneath. The contract is decomposed into a small required core (ICoreProtocolAdapter) plus optional capability groups:

Group	Covers
`IOnchainOperations`	raw BTC sends, transaction broadcast
`ISimplicityOperations`	Liquid PSET review and signing, Simplicity compilation (experimental)
`IRgbOperations`	RGB assets, invoices, transfers
`ISparkOperations`	Spark invoices, L1 deposit claim and sweep
`IArkadeOperations`	VTXO lifecycle, boarding
`ISigningOperations`	message and PSBT signing
`IBackupOperations`	backup and restore
`ISwapOperations`	quote and execute
`IKeysendOperations`	spontaneous payments

IProtocolAdapter is their composition — core plus Partial<…> of each group — so the flat surface is unchanged and every existing call site still works. A new adapter can implements ICoreProtocolAdapter & IRgbOperations to opt into a group with required rather than optional methods, and callers narrow cleanly instead of optional-chaining across the whole surface:

import { asRgbOperations, asSwapOperations } from '@kaleidorg/wallet-engine'

const rgb = asRgbOperations(adapter)
if (rgb) await rgb.createRgbInvoice({ assetId, amount })

Third-party protocols implement the core and connect with any BaseProtocolConfig-shaped config — no edit to the engine’s config union required.

Capability manifest — differences as data

PROTOCOL_CAPABILITIES is the single source of truth for what each protocol can do: layers, asset support, swaps, and the behavioural quirks a UI or router must know about — zeroFee, staticReceiveAddress, boarding, invoiceExpiry, needsChannelLiquidity — plus its backing WDK module and maturity.

import { PROTOCOL_CAPABILITIES, getCapabilities, protocolsForLayer } from '@kaleidorg/wallet-engine'

PROTOCOL_CAPABILITIES.SPARK.zeroFee              // true
PROTOCOL_CAPABILITIES.RGB_LN.needsChannelLiquidity // true
protocolsForLayer('BTC_LN')                      // protocols that can settle on LN

The rule: when you are tempted to add a method to the contract for one protocol, add a capability flag here instead. The router and UI read the manifest; they must never special-case a protocol by name.

`CrossProtocolRouter` — choosing between protocols

The router takes a destination string or a receive layer and returns the protocols that can fulfil it, filtered to those actually registered and connected.

const { best, routes } = router.resolveSend('lnbc1…')

routes carries every candidate with a direct flag verified against the manifest — a candidate is only a direct route if its protocol genuinely supports the surface the destination settles on. Direct routes sort first, so .best is always a genuinely-direct route or null. That is what makes lite mode possible: lite uses .best, advanced shows the full ranked list. For a unified payment URI carrying several rails at once, resolveUnifiedSend(uri, { preference }) matches every present rail to the protocols that can settle it and ranks the whole set by the user’s RoutePreference — a per-asset layer ranking — falling back to a Lightning-first default.

const { best, routes } = router.resolveUnifiedSend(bip321Uri, { preference })

BIP353 (₿user@domain) is resolved to a URI by the host before it reaches the router.

Unified receive (BIP321)

buildUnifiedReceiveURI builds one bitcoin: URI carrying on-chain plus Lightning (BOLT11 and BOLT12), Spark, Arkade, Liquid and RGB. Other wallets ignore the params they don’t recognise; Kaleido-aware wallets get the full menu and let the router choose.

const uri = buildUnifiedReceiveURI({
  btcAddress: 'bc1q…',
  lightningInvoice: 'lnbc1…',
  lightningOffer: 'lno1…',
  liquidAddress: 'lq1…',
  rgbInvoice: 'rgb:…',
  label: 'invoice #42',
})

The address is optional, so a lite wallet can publish a single Lightning- or asset-only QR. Amounts are only emitted for a finite, strictly-positive value — a zero or negative input never produces a misleading amount=0 that a payer’s wallet would read literally.

Disclosure — lite and advanced

Lite versus advanced is one reversible setting, not a code fork. It controls how much the UI reveals (networks, route selector, channel management, raw ids) and how much the router auto-decides.

import { aggregateForLite } from '@kaleidorg/wallet-engine'

const { btc, usd, other } = aggregateForLite(assets)

Lite mode collapses every BTC representation — on-chain, Lightning, Spark, Arkade, Liquid BTC — into one “BTC”, and USDt-on-Liquid into one “USD”. Advanced mode shows the same data per protocol and per layer.

Platform ports — write once, run everywhere

The engine never touches platform APIs directly. Each host injects an IStorageProvider and an IRuntimeProvider (storage, CSPRNG, clock) once at startup, so the same engine runs on React Native, the browser extension and Node unchanged.

import { setPlatform, consoleLogger } from '@kaleidorg/wallet-engine'

setPlatform({ storage, runtime, logger: consoleLogger })

Engine modules that persist state read getPlatform()?.storage. Modules whose correctness depends on durable state refuse to run without it — the chain-swap store throws NO_PLATFORM rather than hand out a derivation index it cannot persist — while modules holding merely convenient state fall back to an in-memory map that does not survive a reload. Inject the platform at startup and neither case applies.

Swaps

KaleidoswapSwap wraps the KaleidoSwap RFQ flow — quote, execute, status — behind domain Quote and SwapResult types, so no SDK type leaks across the boundary.

import { KaleidoswapSwap } from '@kaleidorg/wallet-engine/swap'

const swap = new KaleidoswapSwap(rlnAccount, { baseUrl: 'https://api.kaleidoswap.com' })

const quote = await swap.getQuote({
  fromAsset: 'rgb:USDT…', toAsset: 'BTC',
  fromLayer: 'RGB_LN',    toLayer: 'BTC_LN',
  fromAmount: 100,
})

const result = await swap.executeSwap(quote)

await swap.getSwapStatus(result.swapId)  // pending → confirmed / failed

executeSwap refuses to proceed without the approved quote’s rfqId and amounts, and rejects a quote that has already expired. The maker binds execution to that rfqId and those exact raw amounts — there is no server-side re-quote, so both legs settle at what the user approved or the swap fails with no funds moved. Both legs settle against the account the swap was constructed with — there is no per-swap receiver address. A second venue sits alongside the RFQ rail for BTC ↔ L-BTC chain swaps over the Boltz protocol against a KaleidoSwap maker. RGB always stays on the RFQ path. The engine deliberately never funds a lockup itself: createSwap returns the maker’s binding amounts and the address to pay, and the host performs the send with its own adapter.

Add a Protocol

Everything above picks up a new protocol with no changes to existing code.

Introduction

Guides

`IProtocolAdapter` — the contract

Capability manifest — differences as data

`CrossProtocolRouter` — choosing between protocols

Unified receive (BIP321)

Disclosure — lite and advanced

Platform ports — write once, run everywhere

Swaps

Next

Add a Protocol

​IProtocolAdapter — the contract

​Capability manifest — differences as data

​CrossProtocolRouter — choosing between protocols

​Unified receive (BIP321)

​Disclosure — lite and advanced

​Platform ports — write once, run everywhere

​Swaps

​Next

Add a Protocol

`IProtocolAdapter` — the contract

Capability manifest — differences as data

`CrossProtocolRouter` — choosing between protocols

Unified receive (BIP321)

Disclosure — lite and advanced

Platform ports — write once, run everywhere

Swaps

Next