wdk-rgb-lightning Reference

@utexo/wdk-rgb-lightning is a WDK module for RGB-over-Lightning, built on rgb-lightning-node (RLN). It runs an LDK + rgb-lib node behind WDK’s manager/account contract: channels, BOLT11 and RGB invoices, payments, HODL invoices, optional VSS backup, and an LSP client. The node runs in external-signer mode. The BIP-39 mnemonic stays in the WDK secret manager. Channel-state crypto runs in-process through a VLS signer.

Pre-1.0 beta (0.1.0-beta line). APIs may change between releases.

Why a Separate Package

This module complements @utexo/wdk-wallet-rgb. Each owns its own rgb-lib SQLite state and they do not share asset records. Give each module a separate dataDir — rgb-lib takes an exclusive lock on a wallet directory. This module holds and transfers RGB assets for channels and invoices. For issuance, use @utexo/wdk-wallet-rgb. Node-level issuance calls are forwarded on the account, but wdk-wallet-rgb is the supported path.

Installation

npm install @utexo/wdk-rgb-lightning

# Native binding for your runtime (optional peer deps):
npm install @utexo/rgb-lightning-node-nodejs   # Node
# or
npm install @utexo/rgb-lightning-node-bare     # Bare / React Native

Install only the binding for your runtime. Each postinstall downloads a prebuilt native artifact; no Rust toolchain is required. On Node, import '@utexo/wdk-rgb-lightning' wires @utexo/rgb-lightning-node-nodejs. In a Bare worklet, require('@utexo/wdk-rgb-lightning') wires @utexo/rgb-lightning-node-bare. Both re-export the same manager, account, errors, and LSP surface.

Configuration

WalletManagerRgbLightning takes the seed at construction. network and dataDir are required.

Option	Type	Description
`network`	`string`	`'mainnet'`, `'testnet'`, `'signet'`, or `'regtest'`
`dataDir`	`string`	Persistent directory for RLN SQLite + LDK state
`daemonListeningPort`	`number`	RLN daemon port. Default `0` (ephemeral)
`ldkPeerListeningPort`	`number`	LDK peer port. Default `0` (ephemeral)
`enableVirtualChannelsV0`	`boolean`	Required for APay against a production LSP. Default `false`
`virtualPeerPubkeys`	`string[]`	Peer node IDs allowed to open `trusted_no_broadcast` virtual channels
`vssUrl`	`string`	VSS cloud backup URL. Omit to disable
`vssAllowHttp`	`boolean`	Allow plain `http://` for non-loopback VSS hosts. Default `false`
`lspBaseUrl`	`string`	LSP base URL for APay and `createLsp()`
`lspBearerToken`	`string`	Bearer token for LSP `/internal/*` routes

import WalletManagerRgbLightning from '@utexo/wdk-rgb-lightning';

const manager = new WalletManagerRgbLightning(mnemonic, {
  network: 'regtest',
  dataDir: '/path/to/wallet-data',
});

Classes

`WalletManagerRgbLightning`

Default export. Construct with a BIP-39 mnemonic (or Uint8Array seed) and config.

Methods

Method	Description
`getAccount(0)`	Return the single `WalletAccountRgbLightning`. Index must be `0`
`getAccountByPath(path)`	Same account, looked up by derivation path
`getFeeRates()`	`{ normal, fast }` fee rates as `bigint` sat/vB
`dispose()`	Shut down the node. Synchronous

const account = await manager.getAccount(0);

await account.unlock({
  indexer_url: 'tcp://localhost:50001',
  proxy_endpoint: 'rpc://localhost:3000/json-rpc',
  announce_addresses: [],
  announce_alias: 'my-node',
});

Unlock takes exactly one chain backend: indexer_url, or all four bitcoind_rpc_* fields (bitcoind_rpc_username, bitcoind_rpc_password, bitcoind_rpc_host, bitcoind_rpc_port). Mixing both is rejected. proxy_endpoint, announce_addresses, and announce_alias are always required.

`WalletAccountRgbLightning`

Returned by getAccount(0). RGB Lightning is single-account; RLN owns one LDK node per dataDir.

Lifecycle

Method	Description
`unlock(request)`	Bring the node online. Returns `{ ok: true }`
`getBootstrap()`	Signer/node identity material
`shutdown()`	Shut down the native node. Returns `{ ok: true }`
`dispose()`	No-op on the account. Call `manager.dispose()` to release the node

Node Info

Method	Description
`getNodeInfo()`	Node pubkey, channel counts, sync status
`getNetworkInfo()`	Bitcoin network and chain info
`refreshWalletSnapshot(options?)`	Production refresh. `options.mode` is `'routine'` (default) or `'recovery'`
`sync()`	Deprecated. Colored FastSync only — do not use for portfolio state
`getAddress()`	Current receive address. Throws `AccountLockedError` before unlock
`getAddressState()`	`{ status: 'ready', address }` or `{ status: 'locked', address: null }`
`rotateAddress()`	Advance the receive address. Returns the new address

Peers

Method	Description
`connectPeer(peerPubkeyAndAddr)`	Connect. String form: `'pubkey@host:port'`. Returns `{ ok: true }`
`disconnectPeer({ peer_pubkey })`	Disconnect a peer. Returns `{ ok: true }`
`listPeers()`	Connected peers

Channels

Method	Description
`openChannel({ peer_pubkey_and_opt_addr, capacity_sat, push_msat?, public?, with_anchors?, asset_id?, asset_amount?, virtual_open_mode? })`	Open a BTC or RGB channel
`closeChannel({ channel_id })`	Close a channel. Returns `{ ok: true }`
`listChannels()`	Open channels
`getChannelId(temporaryChannelIdHex)`	Resolve a temporary channel ID

Set virtual_open_mode: 'trusted_no_broadcast' for APay virtual channels. Requires enableVirtualChannelsV0: true and the peer in virtualPeerPubkeys.

Invoices & Payments

Method	Description
`createInvoice({ amt_msat?, expiry_sec, asset_id?, asset_amount? })`	Create a BOLT11 invoice (native snake_case)
`createLightningInvoice({ amountMsat?, expirySec, assetId?, assetAmount? })`	Same call, camelCase alias
`decodeInvoice(invoice)`	Decode a BOLT11 invoice
`getInvoiceStatus(invoice)`	Invoice status
`sendPayment({ invoice, amt_msat?, asset_id?, asset_amount?, max_total_routing_fee_msat? })`	Pay a BOLT11 invoice
`keysend({ dest_pubkey, amt_msat, asset_id?, asset_amount? })`	Spontaneous keysend
`listPayments()`	Payment history
`getPayment(paymentHash, type)`	One payment. `type` is `'Outbound'`, `'InboundAutoClaim'`, or `'InboundHodl'`

HODL Invoices

Method	Description
`createHodlInvoice({ paymentHash, expirySec, amtMsat?, assetId?, assetAmount? })`	Returns `{ bolt11, paymentHash }`
`cancelHodlInvoice({ payment_hash })`	Cancel. Returns `{ ok: true }`
`claimHodlInvoice({ payment_hash, preimage })`	Claim an inbound HODL payment

RGB Assets

RGB receive supports two invoice styles:

Blinded invoice — most common. The receiver creates a blinded endpoint; the sender pays the invoice directly.
Witness invoice — the receiver binds the transfer to witness data. The sender must provide witnessData (at minimum amountSats) in transfer().

// Blinded invoice
await receiver.createRgbInvoice({
  min_confirmations: 1,
  witness: false,
  asset_id: assetId,
  assignment_amount: 100,
});

await sender.transfer({
  recipient: blindedInvoice,
  amount: 100,
  token: assetId,
});

// Witness invoice
await receiver.createRgbInvoice({
  min_confirmations: 1,
  witness: true,
  asset_id: assetId,
  assignment_amount: 100,
});

await sender.transfer({
  recipient: witnessInvoice,
  amount: 100,
  token: assetId,
  witnessData: { amountSats: 1000 },
});

transfer() rejects witnessData on a blinded recipient. decodeRgbInvoice() reports recipient_type as 'Blind' or 'Witness'.

Method	Description
`listAssets(filterAssetSchemas?)`	List assets. Optional filter, e.g. `['Nia']`
`getAssetBalance(assetId)`	Balance for one asset
`getAssetMetadata(assetId)`	Asset metadata
`getTokenBalance(assetId)`	Spendable amount as `bigint`
`listTransfers(assetId)`	Transfer history for one asset
`listTransfersByTxid(txid)`	Transfers for an on-chain txid
`refreshTransfers(request)` / `failTransfers({ batch_transfer_idx })`	Advance or fail pending transfers
`createRgbInvoice({ min_confirmations, witness, asset_id?, assignment_amount?, duration_seconds? })`	On-chain RGB invoice. `witness: true` = witness receive, `false` = blinded
`decodeRgbInvoice(invoice)`	Decode an RGB invoice
`sendRgbAsset({ donation, fee_rate, min_confirmations, recipient_groups })`	Send RGB. Recipients come from `decodeRgbInvoice`
`importRgbContract({ contract_base64, expected_asset_id })`	Register trusted contract metadata only — no allocation
`importRgbTransferConsignment({ consignment_base64, offchain_txid })`	Persist metadata for a transfer the native receive path already accepted

Issuance (issueAssetNia, issueAssetUda, issueAssetCfa, issueAssetIfa, inflate) is forwarded to the binding. Prefer @utexo/wdk-wallet-rgb for issuance. Atomic swaps are on the native binding but are not on the WDK account.

BTC

Method	Description
`getBalance(skipSync?)`	Spendable vanilla BTC as `bigint` satoshis
`getBalanceDetails(skipSync?)`	Full vanilla/colored breakdown
`sendTransaction({ to, value, feeRate?, confirmationTarget? })`	WDK-shaped send. Returns `{ hash, fee }`
`sendBtc({ address, amount, fee_rate, skip_sync })`	Native RLN send. Returns `{ txid }`
`getTransactions(skipSync?)` / `getTransactionsByTxid(txid, skipSync?)`	On-chain history
`listUnspents(skipSync?)`	Unspent outputs with RGB allocations
`createUtxos({ up_to, num?, size?, fee_rate, skip_sync })`	Create colored UTXOs. Returns `{ ok: true }`
`estimateFee(blocks)`	Fee estimate for a confirmation target

Prepare/commit/cancel variants exist for BTC sends, RGB sends, and UTXO creation (prepareBtcSend, commitPreparedBtcSend, prepareRgbSend, prepareCreateUtxos, …).

VSS

Requires vssUrl at construction. Otherwise these throw VssNotConfiguredError.

Method	Description
`vssStatus()`	Local view: `{ configured, url, allowHttp, lastBackupVersion }`
`vssBackup()`	Flush now. Returns `{ version }`
`clearVssFence(password)`	Take over a stale VSS fence. Two live nodes on one store corrupt state
`vssDeleteAll(password)`	Delete all VSS keys. Returns `{ deleted_keys }`

VSS replicates RLN’s LDK and wallet KV state. It does not replicate the VLS signer database under dataDir, so same-device restarts work; cross-device recovery with open channels does not.

APay / LSP

Production APay needs enableVirtualChannelsV0: true and the LSP node ID in virtualPeerPubkeys.

Method	Description
`createLsp(peer?)`	Composed `UtexoLsp`. No-arg form discovers the peer from `lspBaseUrl`
`getLspConfig()`	`{ baseUrl, bearerToken }` from construction
`getLspInfo()`	Validated LSP `GET /get_info` document
`bootstrapLsp({ peerPubkeyAndAddr, hostNodeId? })`	Connect, wait until the peer is in `listPeers`, optionally call `apayNew`
`apayNewWithAddress(hostNodeId, username, domain)`	Register an attested hash batch
`apayNew(hostNodeId)`	Legacy unattested registration
`payLightningAddress(addr, amountMsat)`	Pay a Lightning Address
`requestLspRgbDeposit(args)` / `payRgbViaLsp(args)`	RGB deposit / pay via the LSP

const lsp = await account.createLsp();
await lsp.connect();
const { lnInvoice, rgbInvoice } = await lsp.receiveAsset({
  assetId,
  amountSats: 3_000,
  amountRgb: 100,
});
await lsp.awaitReceiveSettlement(lnInvoice);

UtexoLsp also exposes sendAsset(), quoteAddress(), payAddress(), enableLightningAddress(), and claimPendingPayments(). Do not call apayNew immediately before enableLightningAddress — the native batch can fill the LSP hash-pool cap.

WDK-standard

Method	Description
`transfer({ recipient, amount, token?, feeRate?, witnessData? })`	Routes BOLT11, LN pubkey, BTC address, or RGB invoice. `token` is an RGB asset id. Amounts are msats (LN) or sats (on-chain). Witness RGB invoices require `witnessData.amountSats`
`quoteTransfer(options)` / `quoteSendTransaction(tx)`	Fee quote
`getTransactionReceipt(hash)`	Receipt, or `null` if pending/unknown
`sign(message)` / `verify(message, signature)`	Lightning message sign/verify
`toReadOnlyAccount()`	Cached query-only account (`Promise`). No signing, channels, VSS recovery, or LSP credentials

Error Handling

Typed errors are exported from the package root. Branch on err.name / err.code. The original RLN message is on cause.

RgbLightningError            code: RGB_LIGHTNING_ERROR
├── UnlockError              code: UNLOCK_FAILED
├── AccountLockedError       code: ACCOUNT_LOCKED
├── VssError                 code: VSS_ERROR
│   └── VssNotConfiguredError code: VSS_NOT_CONFIGURED
├── ApayError                code: APAY_ERROR
├── WalletSyncError          code: WALLET_SYNC_FAILED
├── WalletSnapshotError      code: WALLET_SNAPSHOT_FAILED
└── NotImplementedError      code: NOT_IMPLEMENTED

import { UnlockError } from '@utexo/wdk-rgb-lightning';

try {
  await account.unlock(request);
} catch (err) {
  if (err instanceof UnlockError) {
    console.error(err.code, err.message, err.cause);
  }
}

LSP HTTP failures throw LspError / LspProtocolError. Channel and liquidity waits throw LspChannelTimeoutError and LspLiquidityTimeoutError.

Usage Example

import WalletManagerRgbLightning from '@utexo/wdk-rgb-lightning';

const manager = new WalletManagerRgbLightning(mnemonic, {
  network: 'regtest',
  dataDir: '/path/to/wallet-data',
});

const account = await manager.getAccount(0);

await account.unlock({
  indexer_url: 'tcp://localhost:50001',
  proxy_endpoint: 'rpc://localhost:3000/json-rpc',
  announce_addresses: [],
  announce_alias: 'my-node',
});

const info = await account.getNodeInfo();
console.log('Node pubkey:', info.pubkey);

await account.connectPeer(`${peerPubkey}@127.0.0.1:9736`);
await account.openChannel({
  peer_pubkey_and_opt_addr: `${peerPubkey}@127.0.0.1:9736`,
  capacity_sat: 500_000,
  push_msat: 0,
  public: false,
  with_anchors: true,
});

const invoice = await account.createInvoice({
  amt_msat: 5_000,
  expiry_sec: 3600,
});
await account.sendPayment({ invoice: bolt11 });

manager.dispose();

End-to-end LSP + RGB-over-Lightning examples live in utexo-rgb-wdk-demo.

Using with `wdk-wallet-rgb`

Both packages use rgb-lib, but they do not share asset records. Use @utexo/wdk-wallet-rgb for issuance and on-chain inventory; use this module for channels, invoices, and Lightning transfers. Give each module its own dataDir.

What Utexo Is

Getting Started

Product Suite

API Reference

Why a Separate Package

Installation

Configuration

Classes

`WalletManagerRgbLightning`

Methods

`WalletAccountRgbLightning`

Lifecycle

Node Info

Peers

Channels

Invoices & Payments

HODL Invoices

RGB Assets

BTC

VSS

APay / LSP

WDK-standard

Error Handling

Usage Example

Using with `wdk-wallet-rgb`

Further Reading

​Why a Separate Package

​Installation

​Configuration

​Classes

​WalletManagerRgbLightning

​Methods

​WalletAccountRgbLightning

​Lifecycle

​Node Info

​Peers

​Channels

​Invoices & Payments

​HODL Invoices

​RGB Assets

​BTC

​VSS

​APay / LSP

​WDK-standard

​Error Handling

​Usage Example

​Using with wdk-wallet-rgb

​Further Reading

Why a Separate Package

Installation

Configuration

Classes

`WalletManagerRgbLightning`

Methods

`WalletAccountRgbLightning`

Lifecycle

Node Info

Peers

Channels

Invoices & Payments

HODL Invoices

RGB Assets

BTC

VSS

APay / LSP

WDK-standard

Error Handling

Usage Example

Using with `wdk-wallet-rgb`

Further Reading