Skip to main content
@kaleidorg/wallet-engine is the headless core you build a multi-protocol Bitcoin wallet on. It hides the differences between Bitcoin L2s behind one interface, keeps app code identical across React Native, browser extension and Node hosts, and ships the hard parts — routing, unified receive, swaps, lite/advanced UX — as reusable primitives. It powers the KaleidoSwap browser extension and the rate mobile wallet.
Alpha — experimental. The engine moves real funds across Bitcoin L2s. Interfaces are unstable and nothing has been independently audited. Do not use it with mainnet funds you cannot afford to lose.

​
The problem

Every Bitcoin L2 ships its own SDK, its own address formats, and its own quirks — channel liquidity, boarding transactions, invoice expiry, zero-fee transfers. A wallet that supports more than one of them ends up with if (protocol === …) smeared across every screen, and each new protocol edits every existing path. The engine collapses that into one contract plus a data manifest of differences:
  • Screens call one API — ProtocolManager or CrossProtocolRouter — never a protocol SDK.
  • Protocol differences live as data in a capability manifest, not as branches in app code.
  • The same engine runs on every host; platform specifics are injected.

​
What you get

The adapters are the part you could write yourself. These four are the part you would rather not write twice.

Cross-protocol router

Hand it a destination string or a BIP321 URI, get back the ranked protocols that can settle it — filtered to what’s registered and connected. .best is the auto-route.

Unified receive

One bitcoin: QR carrying on-chain, BOLT11/BOLT12, Spark, Arkade, Liquid and RGB at once. Foreign wallets ignore the params they don’t know.

Capability manifest

Every protocol’s layers, quirks and limits as data. The router and your UI read it; nothing special-cases a protocol by name.

Disclosure

Lite vs advanced as one reversible setting rather than two codebases. Lite collapses every BTC representation into one “BTC”.
Add a protocol and all four pick it up with no changes to existing protocol code.

​
Supported protocols

Maturity is the field each protocol carries in the capability manifest. Read it at runtime rather than hardcoding it.

​
Where it sits

The engine consumes kaleido-sdk internally for the KaleidoSwap protocol. Consumers of the engine never import kaleido-sdk directly.

​
Next

Getting Started

Install it, then run the five-minute tour with no node and no credentials.

Core Concepts

The router, unified receive, the manifest, disclosure and platform ports.

Add a Protocol

The whole recipe, from the reference adapter to a manifest entry.

GitHub

Source, issues and the MIT license.