npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@utexo/rgb-lib-wasm

v1.0.0-beta.4

Published

RGB wallet library WASM bindings for browsers

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-unknown target
  • wasm-pack 0.14+
rustup target add wasm32-unknown-unknown
cargo install [email protected]

Building

cd bindings/wasm
./build.sh

This 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.html

The 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 string

Querying 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 blocks

Draining 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 *Begin call elsewhere, for example on a hardware wallet, and pass the signed PSBT to the matching *End call.

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 stop

See DEV-ENVIRONMENT.md for the full regtest infrastructure setup, CI configuration, Docker Compose details, and troubleshooting.

License

MIT