@utexo/rgb-lib-wasm
v1.0.0-beta.4
Published
RGB wallet library WASM bindings for browsers
Keywords
Readme
rgb-lib-wasm
A WebAssembly port of rgb-lib for managing RGB protocol wallets in the browser.
Beta Software — This library is under active development and has not been audited. APIs may change without notice between versions. Use at your own risk.
What it does
rgb-lib-wasm lets you issue, send, and receive RGB assets from a web browser. It replaces the native Rust dependencies (filesystem, SQLite, TCP sockets) with browser-compatible alternatives:
- In-memory database with IndexedDB persistence
- Esplora indexer over HTTP
- Encrypted backup to a local file or a remote VSS server
Supported asset types:
- NIA (Non-Inflatable Asset)
- IFA (Inflatable Fungible Asset)
- BFA (Bridged Fungible Asset): issue, send, receive, burn and mint.
Prerequisites
- Rust 1.88.0+ with the
wasm32-unknown-unknowntarget - wasm-pack 0.14+
rustup target add wasm32-unknown-unknown
cargo install [email protected]Building
cd bindings/wasm
./build.shThis produces the pkg/ directory containing an npm-ready package (rgb_lib_wasm.js, .d.ts types, and the .wasm binary).
Trying the examples
cd bindings/wasm
python3 -m http.server 8000
# Open http://localhost:8000/examples/index.htmlThe examples/ folder contains interactive pages that cover the full API, split by topic:
| Page | Description |
|------|-------------|
| index.html | Quick start guide + automated "Run All" flow |
| wallet.html | Key management, wallet creation, go online, fund, create UTXOs, wallet state queries, fee estimation |
| bitcoin.html | Send BTC, drain wallet, PSBT sign/finalize utilities |
| rgb.html | Issue NIA/IFA, blind/witness receive, send RGB, inflate IFA, refresh/fail/delete transfers |
| backup.html | Local encrypted backup, VSS cloud backup, check proxy URL, error handling tests |
All pages share examples/lib/shared.js (WASM init, helpers, regtest utilities). Each page is self-contained with its own wallet setup section. Online operations (funding, sending, etc.) require the regtest Docker services — see DEV-ENVIRONMENT.md for setup.
Usage
import init, {
generateKeys, restoreKeys, checkProxyUrl,
validateConsignmentOffchain,
WasmWallet, WasmInvoice,
} from './pkg/rgb_lib_wasm.js';
await init();Key generation
const keys = generateKeys('Regtest');
// keys: { mnemonic, accountXpubVanilla, accountXpubColored, masterFingerprint }
const restored = restoreKeys('Regtest', keys.mnemonic);Creating a wallet
const walletData = {
dataDir: ':memory:',
bitcoinNetwork: 'Regtest',
databaseType: 'Sqlite',
maxAllocationsPerUtxo: 5,
accountXpubVanilla: keys.accountXpubVanilla,
accountXpubColored: keys.accountXpubColored,
mnemonic: keys.mnemonic,
masterFingerprint: keys.masterFingerprint,
vanillaKeychain: null,
supportedSchemas: ['Nia', 'Ifa'],
};
// create() restores state from IndexedDB if available
const wallet = await WasmWallet.create(JSON.stringify(walletData));
// Await durable IndexedDB commit before persisting dependent application state.
await wallet.flush();Persistence ordering
WasmWallet.create() and Rust Wallet::restore() finish IndexedDB restoration
before returning. They return an error instead of silently starting from fresh
state when a stored snapshot cannot be read or decoded.
Rust Wallet::flush() and JavaScript wallet.flush() resolve only after the
IndexedDB read-write transaction commits. Persist dependent application state,
acknowledge accepted RGB funding, or broadcast a transaction that depends on an
RGB mutation only after the flush succeeds. A failed flush leaves the current
in-memory wallet state intact and can be retried. A flush that writes nothing
fails. A wallet saves over a stored snapshot only if it loaded that snapshot
through create() or Wallet::restore(), or wrote it itself. A wallet built with
new on a data directory that holds a snapshot cannot save: its saves fail and
its calls return a persistence error.
Every call that changes the wallet saves it. Saves are written in order, and
none is dropped. An async call returns after its save commits, and returns a
persistence error if the save fails. sync, full_scan, refresh,
fail_transfers and the begins that sync first also save when they keep a
change and then fail. backup and vss_backup save the backup time. A sync call
(issue_asset_*, get_address, rotate_address, delete_transfers,
abort_pending_vanilla_tx, restore_backup) queues its save
and returns before the write. It returns a persistence error when an earlier save
failed and no save since has committed. Its change stays in memory and its save
is queued again. Await flush() to know that the state is stored.
backup returns its bytes also when a save failed. lastSaveError() returns
the error of the last failed save, until a save commits.
Lightning-specific consume_fascia and color_psbt_and_consume operations
await this durable commit before returning success.
Going online
const online = await wallet.goOnline({ indexerConfig: { Esplora: { url: 'http://localhost:8094/regtest/api' } }, skipConsistencyCheck: true, proxyAuthKeys: {} });
await wallet.sync(online);Creating UTXOs
RGB allocations live on UTXOs. Before issuing or receiving assets you need colored UTXOs:
const unsignedPsbt = await wallet.createUtxosBegin(online, true, 5, 1000, 1n, false);
const signedPsbt = wallet.signPsbt(unsignedPsbt);
const count = await wallet.createUtxosEnd(online, signedPsbt, false);Issuing assets
// NIA (fixed supply)
const nia = wallet.issueAssetNia('TICK', 'My Token', 0, [1000]);
// IFA (inflatable supply)
const ifa = wallet.issueAssetIfa('IFAT', 'Inflatable', 0, [1000], [500], undefined, false, null);Sending RGB assets
All send operations follow a three-step PSBT workflow: begin (build unsigned PSBT) → sign → end (broadcast).
const recipientMap = {
[assetId]: [{
recipientId: invoiceString,
witnessData: { amountSat: 1000, blinding: null },
amount: 100,
transportEndpoints: ['rpc://localhost:3000/json-rpc'],
// from the invoice: its `pk` and `enc` fields and its expiration
publicKey: invoiceData.publicKey,
encryption: invoiceData.encryption,
expirationTimestamp: invoiceData.expirationTimestamp,
}]
};
// the sender's own proxy, where the recipients post their ACK and get the signed TX from
const senderEndpoint = 'rpc://localhost:3000/json-rpc';
const begin = await wallet.sendBegin(online, recipientMap, false, 1n, 1, Math.floor(Date.now() / 1000) + 3600, senderEndpoint, null, false);
// begin: { psbt, batchTransferIdx, details }; dryRun = true saves nothing and gives batchTransferIdx null
const signed = wallet.signPsbt(begin.psbt);
const result = await wallet.sendEnd(online, signed, false);
// result: { txid, batchTransferIdx }Sending BTC
const psbt = await wallet.sendBtcBegin(online, address, 50000n, 1n, false);
const signed = wallet.signPsbt(psbt);
const txid = await wallet.sendBtcEnd(online, signed, false);Receiving assets
// Blind receive (UTXO-based)
// The wallet reserves the invoice on its proxies, so it takes the Online object. The last argument
// is the encryption preference ('Required' by default, 'Unsupported' or 'Optional').
const blind = await wallet.blindReceive(online, null, 'Any', Math.floor(Date.now() / 1000) + 86400, ['rpc://localhost:3000/json-rpc'], 1, null);
// blind: { invoice, recipientId, expirationTimestamp, batchTransferIdx, publicKey }
// Witness receive (address-based)
const witness = await wallet.witnessReceive(online, null, { Fungible: 100 }, Math.floor(Date.now() / 1000) + 86400, ['rpc://localhost:3000/json-rpc'], 1, null);Parsing invoices
const invoice = new WasmInvoice(invoiceString);
const data = invoice.invoiceData();
// data: { recipientId, assetSchema, assetId, assignment, assignmentName, network, expirationTimestamp, transportEndpoints, publicKey, encryption, unknownQueryParams }
// expirationTimestamp is a BigInt and unknownQueryParams is a plain object
const str = invoice.invoiceString(); // original stringQuerying wallet state
const btcBalance = wallet.getBtcBalance();
const assetBalance = wallet.getAssetBalance(assetId);
const metadata = wallet.getAssetMetadata(assetId);
// metadata: { assetSchema, name, ticker, precision, initialSupply, maxSupply, knownCirculatingSupply, timestamp, ... }
const assets = wallet.listAssets([]); // all schemas
const transfers = wallet.listTransfers(null); // all assets
const unspents = wallet.listUnspents(false);
const transactions = wallet.listTransactions();
const address = wallet.getAddress();Fee estimation
const feeRate = await wallet.getFeeEstimation(online, 6); // target 6 blocksDraining the wallet
const psbt = await wallet.drainToBegin(online, destinationAddress, true, 1n);
const signed = wallet.signPsbt(psbt);
const txid = await wallet.drainToEnd(online, signed);Inflating an IFA asset
const psbt = await wallet.inflateBegin(online, assetId, [200], 1n, 1);
const signed = wallet.signPsbt(psbt);
const result = await wallet.inflateEnd(online, signed);Burning IFA or BFA units
// the reason is optional: a hex-encoded 32-byte value, shown on the transfer as `burnReason`
const result = await wallet.burn(online, assetId, 50n, reason, 1n, 1);sendEnd, inflateEnd, burn, burnEnd and mintEnd return { txid, batchTransferIdx, entropy },
where entropy is the MPC entropy of the commitment.
Local encrypted backup
Wallet state is encrypted with Scrypt + XChaCha20Poly1305 and returned as bytes:
// Backup
const bytes = wallet.backup('my-password');
// bytes is a Uint8Array — save it as a file download
// Check if backup is needed
const needed = wallet.backupInfo(); // true if wallet changed since last backup
// Restore (create the wallet with create() and the same mnemonic)
wallet.restoreBackup(backupBytes, 'my-password');VSS cloud backup
VSS (Versioned Storage Service) provides cloud backup with optimistic locking.
VSS backups are manual: nothing uploads on its own. The app checks backupInfo() and calls vssBackup().
// Configure (signing key is a 32-byte hex-encoded secp256k1 secret key)
wallet.configureVssBackup('http://vss-server:8082/vss', 'my-store-id', signingKeyHex);
// Upload the first backup, if the wallet has changes (returns null when none)
await wallet.ensureInitialBackup();
// Upload
if (wallet.backupInfo()) {
const version = await wallet.vssBackup();
}
// Check status
const info = await wallet.vssBackupInfo();
// info: { backupExists, serverVersion, backupRequired }
// Restore
await wallet.vssRestoreBackup();
// Disable
wallet.disableVssBackup();Transfer management
const refreshResult = await wallet.refresh(online, null, [], false);
const failed = await wallet.failTransfers(online, null, false, false);
const deleted = wallet.deleteTransfers(null, false);Utilities
// Validate an RGB proxy server
await checkProxyUrl('http://localhost:3000/json-rpc');
// Validate an RGB consignment offchain (before TX is broadcast)
// consignmentBytes is a Uint8Array of the strict-encoded consignment
const result = validateConsignmentOffchain(consignmentBytes, txid, 'Regtest');
// result: { valid: true, warnings: [...] }
// result: { valid: false, error: "invalid", details: "..." }
// PSBT signing and finalization (standalone)
const signed = wallet.signPsbt(unsignedPsbtBase64);
const finalized = wallet.finalizePsbt(signedPsbtBase64);Security
The wallet trusts every script on its page. A script in the same page can call every wallet method, read the wasm memory, which holds the mnemonic while the wallet exists, and read the IndexedDB snapshot, which holds the wallet database without the mnemonic. getWalletData and Debug output do not show the mnemonic. This stops accidental leaks, not a hostile script.
To protect a wallet:
- Load no third-party scripts on the wallet's origin. Set a strict Content Security Policy and use Subresource Integrity on the scripts you load.
- Run the wallet on its own origin, for example in an iframe on a dedicated subdomain, and talk to it with
postMessage. Scripts on the main page then cannot reach its memory or its storage. - To keep the mnemonic out of the page, create the wallet with
mnemonic: null(watch-only). Sign the PSBT of each*Begincall elsewhere, for example on a hardware wallet, and pass the signed PSBT to the matching*Endcall.
API reference
Standalone functions
| Function | Description |
|----------|-------------|
| generateKeys(network) | Generate a new BIP39 mnemonic and derive xpubs |
| restoreKeys(network, mnemonic) | Restore xpubs from a mnemonic |
| checkProxyUrl(url) | Validate an RGB proxy server URL |
| validateConsignmentOffchain(bytes, txid, network) | Validate an RGB consignment using bundled witness data |
WasmInvoice
| Method | Description |
|--------|-------------|
| new(invoiceString) | Parse and validate an RGB invoice string |
| invoiceData() | Return parsed InvoiceData as a JS object |
| invoiceString() | Return the original invoice string |
WasmWallet methods
| Method | Async | Description |
|--------|-------|-------------|
| new(walletDataJson) | no | Create wallet (no IndexedDB restore) |
| create(walletDataJson) | yes | Create wallet with IndexedDB restore; fails if restore fails |
| flush() | yes | Durably commit current wallet state to IndexedDB |
| getWalletData() | no | Return WalletData as JS object; the mnemonic is not returned (mnemonic is null) |
| getAddress() | no | Get a new Bitcoin address |
| getBtcBalance() | no | Get BTC balance |
| getAssetBalance(assetId) | no | Get balance for an RGB asset |
| getAssetMetadata(assetId) | no | Get metadata for an RGB asset (name, ticker, precision, supply, etc.) |
| listAssets(schemas) | no | List known RGB assets |
| listTransfers(assetId?) | no | List RGB transfers |
| listUnspents(settledOnly) | no | List unspent outputs with RGB allocations |
| listTransactions() | no | List Bitcoin transactions, and begun vanilla operations with pending: true |
| listPendingVanillaTxs() | no | List begun vanilla operations that are not ended or aborted |
| abortPendingVanillaTx(txid) | no | Fail a begun vanilla operation and release its inputs |
| goOnline(onlineOptions) | yes | Connect to an Esplora indexer. The optional evmChains option maps an EVM chain ID to {rpcUrl, minMintLockBlocks, maxMintLockBlocks}, for BFA. Unless skipConsistencyCheck is true, it checks the wallet's data against the RGB stock and a full scan, and fails on a mismatch. |
| sync(online) | yes | Sync wallet with indexer |
| createUtxosBegin(...) | yes | Prepare PSBT to create colored UTXOs |
| createUtxosEnd(online, psbt, skipSync) | yes | Broadcast UTXO creation PSBT |
| issueAssetNia(ticker, name, precision, amounts) | no | Issue a Non-Inflatable Asset |
| issueAssetIfa(ticker, name, precision, amounts, inflationAmounts, rejectListUrl?, linkRight, linkedFromContract?) | no | Issue an Inflatable Fungible Asset, with its link right if linkRight |
| issueAssetBfa(ticker, name, precision, mintRights, chainId, contractAddress, rejectListAddress?, linkRight, linkedFromContract?) | no | Issue a Bridged Fungible Asset with mint rights and no units, with its link right if linkRight |
| blindReceive(...) | yes | Create a blind receive invoice and reserve it on the proxies |
| witnessReceive(...) | yes | Create a witness receive invoice and reserve it on the proxies |
| sendBegin(...) | yes | Prepare RGB send PSBT, save it as Initiated unless dryRun |
| sendEnd(online, psbt, skipSync) | yes | Broadcast RGB send PSBT |
| sendBtcBegin(...) | yes | Prepare BTC send PSBT |
| sendBtcEnd(online, psbt, skipSync) | yes | Broadcast BTC send PSBT |
| getFeeEstimation(online, blocks) | yes | Estimate fee rate for target blocks |
| drainToBegin(online, addr, destroyAssets, feeRate) | yes | Prepare drain PSBT |
| drainToEnd(online, psbt) | yes | Broadcast drain PSBT |
| inflateBegin(...) | yes | Prepare IFA inflation PSBT |
| inflateEnd(online, psbt) | yes | Broadcast IFA inflation PSBT |
| burn(online, assetId, amount, burnReason?, feeRate, minConf) | yes | Burn IFA or BFA units, signing with the wallet keys |
| burnBegin(online, assetId, amount, burnReason?, feeRate, minConf, dryRun) | yes | Prepare burn PSBT. burnReason is an optional hex-encoded 32-byte value |
| burnEnd(online, psbt) | yes | Broadcast burn PSBT |
| link(online, assetId, linkedToContract, feeRate, minConf) | yes | Link an IFA or BFA asset to another contract, spending its link right, signing with the wallet keys |
| linkBegin(online, assetId, linkedToContract, feeRate, minConf, dryRun) | yes | Prepare link PSBT |
| linkEnd(online, psbt) | yes | Broadcast link PSBT |
| mintBegin(online, assetId, recipient, beforeBlock, feeRate, minConf, senderEndpoint) | yes | Prepare BFA mint PSBT and post the consignment to the recipient. The lock has to be included before beforeBlock |
| mintEnd(online, psbt) | yes | Broadcast mint PSBT once the lock on the EVM chain is finalized |
| getReceivedMint(recipientId) | no | Return what the lock of a received mint has to match (lockId, amount, beforeBlock), or null |
| listUnspentsVanilla(online, minConf, skipSync) | yes | List non-colored UTXOs |
| refresh(online, assetId?, filter, skipSync) | yes | Refresh pending transfers and settle ended vanilla operations |
| failTransfers(online, batchIdx?, noAssetOnly, skipSync) | yes | Fail pending transfers |
| deleteTransfers(batchIdx?, noAssetOnly) | no | Delete failed transfers |
| signPsbt(psbt) | no | Sign a PSBT |
| finalizePsbt(psbt) | no | Finalize a signed PSBT |
| backup(password) | no | Create encrypted backup (returns bytes) |
| restoreBackup(bytes, password) | no | Restore from encrypted backup |
| backupInfo() | no | Check if backup is needed |
| configureVssBackup(url, storeId, keyHex) | no | Configure VSS cloud backup |
| disableVssBackup() | no | Disable VSS cloud backup |
| vssBackup() | yes | Upload backup to VSS server |
| ensureInitialBackup() | yes | Upload a VSS backup if the wallet has changes |
| vssRestoreBackup() | yes | Restore from VSS server |
| vssBackupInfo() | yes | Query VSS backup status |
Cargo features
| Feature | Default | Description |
|---------|---------|-------------|
| esplora | yes | Online operations via Esplora HTTP indexer |
| camel_case | yes | camelCase JSON serialization for all types |
Running tests
# Native unit tests (94 tests)
cargo test --lib
# WASM unit tests (headless Firefox)
wasm-pack test --headless --firefox --release -- --test keys_wasm
WASM_BINDGEN_TEST_TIMEOUT=300 wasm-pack test --headless --firefox --release -- --test pow_wasm
# Integration tests (requires regtest Docker services)
cd tests && bash regtest.sh start
cd .. && wasm-pack test --headless --firefox --release -- --test wallet_wasm
wasm-pack test --headless --firefox --release bindings/wasm --test bindings_wasm
wasm-pack test --headless --firefox --release -- --test integration_wasm
wasm-pack test --headless --firefox --release -- --test receive_wasm
wasm-pack test --headless --firefox --release -- --test send_wasm
cd tests && bash regtest.sh stopSee DEV-ENVIRONMENT.md for the full regtest infrastructure setup, CI configuration, Docker Compose details, and troubleshooting.
License
MIT
