@utexo/rgb-sdk 1.0.0-beta.8

package/cli/README.md

@@ -0,0 +1,348 @@
+# UTEXO CLI
+
+CLI for UTEXOWallet. All commands run via the single entrypoint.
+
+**Usage:** `utexo <command> <wallet_name> [options]` or `npm run utexo -- <command> <wallet_name> [options]` or `node cli/run.mjs <command> <wallet_name> [options]`
+
+**Exception:** `sign-psbt` has no wallet: `utexo sign-psbt --psbt "<psbt>" --network <net> --mnemonic "<mn>"`
+
+## Structure
+
+- **`run.mjs`** — Single entrypoint for all commands
+- **`commands/`** — Command modules (each exports `run(walletName, flagArgs[, options])`)
+- **`utils.mjs`** — Shared helpers (parseFlags, runWithWallet, wallet config load/save)
+- **`data/`** — Wallet configs (`data/<wallet_name>.json`)
+- **`generate_keys.mjs`** — Setup script to create a new wallet config (also: `utexo generate_keys <wallet> [network]`)
+
+## Scripts
+
+### generate_keys
+
+Generates new wallet keys and saves them to a JSON file.
+
+**Usage:**
+```bash
+utexo generate_keys <wallet_name> [network]
+# or: node cli/generate_keys.mjs <wallet_name> [network]
+```
+
+**Examples:**
+```bash
+utexo generate_keys mywallet          # default: regtest
+utexo generate_keys mywallet testnet
+```
+
+**Parameters:**
+- `wallet_name` (required) - Name for the wallet configuration file
+- `network` (optional) - Bitcoin network, defaults to `regtest` if not provided
+  - Options: `mainnet`, `testnet`, `testnet4`, `regtest`, `utexo`
+
+**Output:**
+- Creates a JSON file in `cli/data/<wallet_name>.json` containing:
+  - Wallet name
+  - Network
+  - Mnemonic (⚠️ keep secure!)
+  - xpub, accountXpubVanilla, accountXpubColored
+  - masterFingerprint
+  - xpriv
+  - Created timestamp
+
+### address
+
+Get wallet address.
+
+**Usage:** `utexo address <wallet_name>`
+
+**Parameters:**
+- `wallet_name` (required) - Name of the wallet (must match a file in `data/<wallet_name>.json`)
+
+**Output:**
+- Displays the wallet address and wallet information
+
+### btcbalance
+
+Get BTC balance.
+
+**Usage:** `utexo btcbalance <wallet_name>`
+
+**Parameters:**
+- `wallet_name` (required) - Name of the wallet (must match a file in `data/<wallet_name>.json`)
+
+**Output:**
+- Displays BTC balance information including:
+  - Vanilla (Regular BTC) balance: settled, future, spendable
+  - Colored (RGB Assets) balance: settled, future, spendable
+  - Wallet information
+
+### createutxos
+
+Create UTXOs.
+
+**Usage:** `utexo createutxos <wallet_name> [options]`
+
+**Options:**
+- `--num <number>` - Number of UTXOs to create (default: 5)
+- `--size <number>` - Size of each UTXO in sats (default: 1000)
+- `--feeRate <number>` - Fee rate in sat/vB (default: 1)
+- `--upTo` - Create UTXOs up to the specified number (optional flag)
+
+**Examples:**
+```bash
+utexo createutxos mywallet
+utexo createutxos mywallet --num 10 --size 2000 --feeRate 2
+utexo createutxos mywallet --num 20 --upTo
+```
+
+**Parameters:**
+- `wallet_name` (required) - Name of the wallet (must match `data/<wallet_name>.json`)
+- Options are optional and have sensible defaults
+
+**Output:**
+- Displays the number of UTXOs created
+- Shows wallet information
+
+**Note:** This command requires the wallet to have sufficient BTC balance to create UTXOs and pay fees.
+
+### listassets
+
+List RGB assets.
+
+**Usage:** `utexo listassets <wallet_name> [--assetId <id>]`
+
+**Parameters:**
+- `wallet_name` (required) - Name of the wallet (must match `data/<wallet_name>.json`)
+
+**Output:**
+- Lists all assets by type: NIA (RGB20), UDA, CFA, IFA
+- For each asset: ticker/name, asset ID, settled and spendable balance
+- Total asset count
+- Raw JSON response from `listAssets()`
+
+### blindreceive
+
+Create blind receive invoice.
+
+**Usage:** `utexo blindreceive <wallet_name> --amount <number> [options]`
+
+**Options:**
+- `--amount <number>` (required) - Amount to receive
+- `--assetId <string>` - Asset ID (optional)
+- `--minConfirmations <n>` - Min confirmations (optional)
+- `--durationSeconds <n>` - Invoice duration in seconds (optional)
+
+**Examples:**
+```bash
+utexo blindreceive mywallet --amount 100
+utexo blindreceive mywallet --amount 50 --assetId rgb:xxx... --durationSeconds 2000
+```
+
+**Output:**
+- Raw JSON response from `blindReceive()`: invoice, recipientId, expirationTimestamp, batchTransferIdx
+- Wallet info
+
+### witnessreceive
+
+Create witness receive invoice.
+
+**Usage:** `utexo witnessreceive <wallet_name> --amount <number> [options]`
+
+**Options:**
+- `--amount <number>` (required) - Amount to receive
+- `--assetId <string>` - Asset ID (optional)
+- `--minConfirmations <n>` - Min confirmations (optional)
+- `--durationSeconds <n>` - Invoice duration in seconds (optional)
+
+**Examples:**
+```bash
+utexo witnessreceive mywallet --amount 100
+utexo witnessreceive mywallet --amount 50 --assetId rgb:xxx... --durationSeconds 2000
+```
+
+**Output:**
+- Raw JSON response from `witnessReceive()`: invoice, recipientId, expirationTimestamp, batchTransferIdx
+- Wallet info
+
+### decodergbinvoice
+
+Decode an RGB invoice.
+
+**Usage:** `utexo decodergbinvoice <wallet_name> --invoice "<invoice_string>"`
+
+**Output:**
+- Raw JSON response from `decodeRGBInvoice()`: invoice, recipientId, assetSchema, assetId, network, assignment, assignmentName, expirationTimestamp, transportEndpoints
+- Wallet info
+
+### refresh
+
+Refresh wallet state.
+
+**Usage:** `utexo refresh <wallet_name>`
+
+**Parameters:**
+- `wallet_name` (required) - Name of the wallet (must match `data/<wallet_name>.json`)
+
+**Output:**
+- Success message and wallet info
+
+### listtransfers
+
+List transfers.
+
+**Usage:** `utexo listtransfers <wallet_name> [--assetId <asset_id>]`
+- `--assetId <string>` (optional) - Filter transfers by asset ID
+
+**Examples:**
+```bash
+utexo listtransfers mywallet
+utexo listtransfers mywallet --assetId rgb:xxx...
+```
+
+**Output:**
+- Raw JSON response from `listTransfers()` (array of transfers)
+- Total transfer count
+- Wallet info
+
+### onchainreceive
+
+Generate on-chain deposit invoice (mainnet → UTEXO).
+
+**Usage:** `utexo onchainreceive <wallet_name> --amount <n> [--assetId <id>] [--minConfirmations <n>] [--durationSeconds <n>]`
+
+**Output:** Mainnet invoice for depositing to UTEXO.
+
+### onchainsendbegin
+
+Begin on-chain send, returns unsigned PSBT.
+
+**Usage:** `utexo onchainsendbegin <wallet_name> --invoice "<invoice_string>"`
+
+### signpsbt
+
+Sign PSBT (uses wallet; requires init/goOnline).
+
+**Usage:** `utexo signpsbt <wallet_name> --psbt "<psbt_string>" [--mnemonic "<mnemonic>"]`
+
+### sign-psbt
+
+Sign PSBT standalone (no wallet). Use when signing without loading a wallet config.
+
+**Usage:** `utexo sign-psbt --psbt "<psbt>" --network <regtest|testnet|mainnet> --mnemonic "<mnemonic>"`
+
+### onchainsendend
+
+Complete on-chain send with signed PSBT.
+
+**Usage:** `utexo onchainsendend <wallet_name> --invoice "<invoice_string>" --signedPsbt "<signed_psbt>"`
+
+### onchainsend
+
+Complete on-chain send flow (begin + sign + end).
+
+**Usage:** `utexo onchainsend <wallet_name> --invoice "<invoice_string>" [--mnemonic "<mnemonic>"]`
+
+### send
+
+Standard RGB send (blind/witness invoice).
+
+**Usage:** `utexo send <wallet_name> --invoice "<inv>" [--assetId <id>] [--amount <n>] [--witnessData "<json>"] [--mnemonic "<mn>"] [--feeRate <n>] [--minConfirmations <n>]`
+
+### listunspents
+
+List unspent UTXOs.
+
+**Usage:** `utexo listunspents <wallet_name>`
+
+### getonchainsendstatus
+
+Get on-chain send status.
+
+**Usage:** `utexo getonchainsendstatus <wallet_name> --invoice "<invoice_string>"`
+
+### createlightninginvoice
+
+Create Lightning invoice.
+
+**Usage:** `utexo createlightninginvoice <wallet_name> --assetId <id> --amount <n> [--amountSats <n>] [--expirySeconds <n>]`
+
+### paylightninginvoicebegin
+
+Begin Lightning payment, returns unsigned PSBT.
+
+**Usage:** `utexo paylightninginvoicebegin <wallet_name> --lnInvoice "<ln_invoice>" [--maxFee <n>]`
+
+### paylightninginvoice
+
+Complete Lightning payment (begin + sign + end).
+
+**Usage:** `utexo paylightninginvoice <wallet_name> --lnInvoice "<ln_invoice>" [--amount <n>] [--assetId <id>] [--maxFee <n>] [--mnemonic "<mn>"]`
+
+### paylightninginvoiceend
+
+Complete Lightning payment with signed PSBT.
+
+**Usage:** `utexo paylightninginvoiceend <wallet_name> --lnInvoice "<ln_invoice>" --signedPsbt "<signed_psbt>"`
+
+### getlightningsendrequest
+
+Get Lightning send status.
+
+**Usage:** `utexo getlightningsendrequest <wallet_name> --lnInvoice "<ln_invoice>"`
+
+### getlightningreceiverequest
+
+Get Lightning receive status.
+
+**Usage:** `utexo getlightningreceiverequest <wallet_name> --lnInvoice "<ln_invoice>"`
+
+## Example Workflow
+
+```bash
+# 1. Generate keys (default: regtest)
+utexo generate_keys testwallet
+
+# 2. Get address, balance, create UTXOs
+utexo address testwallet
+utexo btcbalance testwallet
+utexo createutxos testwallet --num 10 --size 1500
+utexo listassets testwallet
+
+# 3. Receive invoices
+utexo blindreceive testwallet --amount 100
+utexo witnessreceive testwallet --amount 100
+
+# 4. On-chain (UTEXO)
+utexo onchainreceive testwallet --amount 100
+utexo onchainsend testwallet --invoice "<mainnet_invoice>"
+utexo getonchainsendstatus testwallet --invoice "<invoice>"
+
+# 5. Lightning
+utexo createlightninginvoice testwallet --assetId rgb:xxx... --amount 100
+utexo paylightninginvoice testwallet --lnInvoice "lnbc..."
+
+# 6. Standard RGB send
+utexo send testwallet --invoice "<inv>" --assetId <id> --amount <n>
+```
+
+**WalletManager (standard RGB, same keys):** `utexo wm address|btcbalance|refresh|sync|createutxos|blindreceive|listassets|listtransfers|sendbatch|sendbtc <wallet> [options]`
+
+## Security Warning
+
+⚠️ **IMPORTANT**: The wallet configuration files contain sensitive information (mnemonic, private keys). 
+- Never commit these files to version control
+- Keep them secure and encrypted
+- This folder is automatically ignored by git (see `.gitignore`)
+
+## Data folder
+
+Wallet config files and other test data live in **`cli/data/`**:
+- `data/<wallet_name>.json` — wallet configs created by `generate_keys.mjs`
+- `data/bridge.txt` — optional bridge-related data
+
+Scripts read and write wallet configs under `data/` automatically.
+
+## Notes
+
+- All scripts use ES modules (`.mjs` extension)
+- Scripts require the project to be built (`npm run build`) before use
+- Wallet files are stored in `cli/data/` as `<wallet_name>.json`
+- Wallet `network` from config (e.g. `regtest`, `utexo`, `testnet`) is mapped to UTEXOWallet presets `mainnet` or `testnet` automatically

package/cli/commands/address.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * address command: get wallet address
+ */
+
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+
+    await runWithWallet(walletName, async (wallet) => {
+        const address = await wallet.getAddress();
+        console.log(`✅ Address: ${address}`);
+    }, { quiet: true });
+}

package/cli/commands/blindreceive.mjs

@@ -0,0 +1,15 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['amount'], optional: ['assetId', 'minConfirmations', 'durationSeconds'] }, { usage: options.usage });
+    const request = {
+        amount: parseInt(opts.amount, 10),
+        ...(opts.assetId && { assetId: opts.assetId }),
+        ...(opts.minConfirmations && { minConfirmations: parseInt(opts.minConfirmations, 10) }),
+        ...(opts.durationSeconds && { durationSeconds: parseInt(opts.durationSeconds, 10) }),
+    };
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.blindReceive(request);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/btcbalance.mjs

@@ -0,0 +1,11 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWallet(walletName, async (wallet) => {
+        const balance = await wallet.getBtcBalance();
+        console.log('✅ BTC balance:');
+        console.log(`  Vanilla: settled ${balance.vanilla.settled}, spendable ${balance.vanilla.spendable} sats`);
+        console.log(`  Colored: settled ${balance.colored.settled}, spendable ${balance.colored.spendable} sats`);
+    }, { quiet: true });
+}

package/cli/commands/createlightninginvoice.mjs

@@ -0,0 +1,14 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['assetId', 'amount'], optional: ['amountSats', 'expirySeconds'] }, { usage: options.usage });
+    const request = {
+        asset: { assetId: opts.assetId, amount: parseInt(opts.amount, 10) },
+        ...(opts.amountSats && { amountSats: parseInt(opts.amountSats, 10) }),
+        ...(opts.expirySeconds && { expirySeconds: parseInt(opts.expirySeconds, 10) }),
+    };
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.createLightningInvoice(request);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/createutxos.mjs

@@ -0,0 +1,13 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, { required: [], optional: ['num', 'size', 'feeRate'] });
+    const upTo = flagArgs.includes('--upTo');
+    const num = opts.num ? parseInt(opts.num, 10) : 5;
+    const size = opts.size ? parseInt(opts.size, 10) : 1000;
+    const feeRate = opts.feeRate ? parseInt(opts.feeRate, 10) : 1;
+    await runWithWallet(walletName, async (wallet) => {
+        const count = await wallet.createUtxos({ num, size, feeRate, upTo: upTo || undefined });
+        console.log(`✅ Created ${count} UTXO(s)`);
+    }, { quiet: true });
+}

package/cli/commands/decodergbinvoice.mjs

@@ -0,0 +1,9 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['invoice'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.decodeRGBInvoice({ invoice: opts.invoice });
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/generate_keys.mjs

@@ -0,0 +1,35 @@
+/**
+ * Generate new wallet keys and save to cli/data/<wallet_name>.json
+ * Usage: utexo generate_keys <wallet_name> [network]
+ *   network: regtest (default), testnet, mainnet
+ */
+
+import { generateKeys } from '../../dist/index.mjs';
+import { saveWalletConfig } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, { usage } = {}) {
+    if (!walletName) {
+        console.error('Usage: utexo generate_keys <wallet_name> [network]');
+        if (usage) console.error(usage);
+        process.exit(1);
+    }
+
+    const network = flagArgs[0] || 'regtest';
+    const keys = await generateKeys(network);
+
+    const walletConfig = {
+        walletName,
+        network,
+        mnemonic: keys.mnemonic,
+        xpub: keys.xpub,
+        accountXpubVanilla: keys.accountXpubVanilla,
+        accountXpubColored: keys.accountXpubColored,
+        masterFingerprint: keys.masterFingerprint,
+        xpriv: keys.xpriv,
+        createdAt: new Date().toISOString(),
+    };
+
+    const filepath = saveWalletConfig(walletName, walletConfig);
+    console.log(`✅ Keys saved to ${filepath}`);
+    console.log(`   Network: ${network}`);
+}

package/cli/commands/getlightningreceiverequest.mjs

@@ -0,0 +1,10 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['lnInvoice'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const status = await wallet.getLightningReceiveRequest(opts.lnInvoice);
+        console.log(status === null ? '✅ No transfer found' : `✅ Status: ${status}`);
+        if (status !== null) console.log(JSON.stringify(status, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/getlightningsendrequest.mjs

@@ -0,0 +1,10 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['lnInvoice'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const status = await wallet.getLightningSendRequest(opts.lnInvoice);
+        console.log(status === null ? '✅ No transfer found' : `✅ Status: ${status}`);
+        if (status !== null) console.log(JSON.stringify(status, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/getonchainsendstatus.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * getonchainsendstatus command: get onchain send status for an invoice
+ */
+
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const { usage } = options;
+    const opts = parseFlags(flagArgs, { required: ['invoice'], optional: [] }, {
+        usage: usage ? `❌ --invoice "<invoice_string>" is required\n\n${usage}` : undefined,
+    });
+
+    await runWithWallet(walletName, async (wallet) => {
+        const status = await wallet.getOnchainSendStatus(opts.invoice);
+        console.log(status === null ? '✅ No transfer found for this invoice' : `✅ Status: ${status}`);
+        if (status !== null) console.log(JSON.stringify(status, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/listassets.mjs

@@ -0,0 +1,11 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWallet(walletName, async (wallet) => {
+        const assets = await wallet.listAssets();
+        console.log(JSON.stringify(assets, null, 2));
+        const n = (assets.nia?.length || 0) + (assets.uda?.length || 0) + (assets.cfa?.length || 0) + (assets.ifa?.length || 0);
+        console.log(`✅ Total: ${n} asset(s)`);
+    }, { quiet: true });
+}

package/cli/commands/listtransfers.mjs

@@ -0,0 +1,10 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, { required: [], optional: ['assetId'] });
+    await runWithWallet(walletName, async (wallet) => {
+        const transfers = await wallet.listTransfers(opts.assetId);
+        console.log(JSON.stringify(transfers, null, 2));
+        console.log(`✅ Total: ${Array.isArray(transfers) ? transfers.length : 0} transfer(s)`);
+    }, { quiet: true });
+}

package/cli/commands/listunspents.mjs

@@ -0,0 +1,10 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWallet(walletName, async (wallet) => {
+        const unspents = await wallet.listUnspents();
+        console.log(JSON.stringify(unspents, null, 2));
+        console.log(`✅ Total: ${Array.isArray(unspents) ? unspents.length : 0} unspent(s)`);
+    }, { quiet: true });
+}

package/cli/commands/onchainreceive.mjs

@@ -0,0 +1,16 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['amount'], optional: ['assetId', 'minConfirmations', 'durationSeconds'] }, { usage: options.usage });
+    const request = {
+        amount: parseInt(opts.amount, 10),
+        ...(opts.assetId && { assetId: opts.assetId }),
+        ...(opts.minConfirmations && { minConfirmations: parseInt(opts.minConfirmations, 10) }),
+        ...(opts.durationSeconds && { durationSeconds: parseInt(opts.durationSeconds, 10) }),
+    };
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.onchainReceive(request);
+        console.log(JSON.stringify(result, null, 2));
+        if (result?.invoice) console.log('\nMainnet invoice:', result.invoice);
+    }, { quiet: true });
+}

package/cli/commands/onchainsend.mjs

@@ -0,0 +1,11 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['invoice'], optional: ['assetId', 'amount', 'mnemonic'] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet, walletConfig) => {
+        const mnemonic = opts.mnemonic || walletConfig.mnemonic;
+        const request = { invoice: opts.invoice, ...(opts.assetId && { assetId: opts.assetId }), ...(opts.amount && { amount: parseInt(opts.amount, 10) }) };
+        const result = await wallet.onchainSend(request, mnemonic);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/onchainsendbegin.mjs

@@ -0,0 +1,9 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['invoice'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const psbt = await wallet.onchainSendBegin({ invoice: opts.invoice });
+        console.log(psbt);
+    }, { quiet: true });
+}

package/cli/commands/onchainsendend.mjs

@@ -0,0 +1,9 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['invoice', 'signedPsbt'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.onchainSendEnd({ invoice: opts.invoice, signedPsbt: opts.signedPsbt });
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/paylightninginvoice.mjs

@@ -0,0 +1,11 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['lnInvoice'], optional: ['amount', 'assetId', 'maxFee', 'mnemonic'] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet, walletConfig) => {
+        const mnemonic = opts.mnemonic || walletConfig.mnemonic;
+        const request = { lnInvoice: opts.lnInvoice, ...(opts.amount && { amount: parseInt(opts.amount, 10) }), ...(opts.assetId && { assetId: opts.assetId }), ...(opts.maxFee && { maxFee: parseInt(opts.maxFee, 10) }) };
+        const result = await wallet.payLightningInvoice(request, mnemonic);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/paylightninginvoicebegin.mjs

@@ -0,0 +1,10 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['lnInvoice'], optional: ['maxFee'] }, { usage: options.usage });
+    const request = { lnInvoice: opts.lnInvoice, ...(opts.maxFee && { maxFee: parseInt(opts.maxFee, 10) }) };
+    await runWithWallet(walletName, async (wallet) => {
+        const psbt = await wallet.payLightningInvoiceBegin(request);
+        console.log(psbt);
+    }, { quiet: true });
+}

package/cli/commands/paylightninginvoiceend.mjs

@@ -0,0 +1,9 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['lnInvoice', 'signedPsbt'], optional: [] }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet) => {
+        const result = await wallet.payLightningInvoiceEnd({ lnInvoice: opts.lnInvoice, signedPsbt: opts.signedPsbt });
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/refresh.mjs

@@ -0,0 +1,9 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWallet(walletName, async (wallet) => {
+        await wallet.refreshWallet();
+        console.log('✅ Wallet refreshed');
+    }, { quiet: true });
+}