@utexo/rgb-sdk 1.0.0-beta.8

package/cli/commands/send.mjs

@@ -0,0 +1,31 @@
+import { parseFlags, runWithWallet } from '../utils.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, {
+        required: ['invoice'],
+        optional: ['assetId', 'amount', 'mnemonic', 'feeRate', 'minConfirmations', 'witnessData'],
+    }, { usage: options.usage });
+    await runWithWallet(walletName, async (wallet, walletConfig) => {
+        const mnemonic = opts.mnemonic || walletConfig.mnemonic;
+        let witnessData;
+        if (opts.witnessData) {
+            try {
+                witnessData = JSON.parse(opts.witnessData);
+                if (typeof witnessData.amountSat !== 'number') witnessData.amountSat = parseInt(witnessData.amountSat, 10);
+                if (witnessData.blinding != null && typeof witnessData.blinding !== 'number') witnessData.blinding = parseInt(witnessData.blinding, 10);
+            } catch (e) {
+                throw new Error('--witnessData must be valid JSON, e.g. \'{"amountSat":1000,"blinding":123}\'');
+            }
+        }
+        const request = {
+            invoice: opts.invoice,
+            ...(opts.assetId && { assetId: opts.assetId }),
+            ...(opts.amount && { amount: parseInt(opts.amount, 10) }),
+            ...(opts.feeRate && { feeRate: parseInt(opts.feeRate, 10) }),
+            ...(opts.minConfirmations && { minConfirmations: parseInt(opts.minConfirmations, 10) }),
+            ...(witnessData && { witnessData }),
+        };
+        const result = await wallet.send(request, mnemonic);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/commands/sign-psbt.mjs

@@ -0,0 +1,12 @@
+/**
+ * Sign a PSBT with mnemonic + network only. No wallet, no goOnline.
+ * Usage: utexo sign-psbt --psbt "<base64>" --network <testnet|mainnet|signet|regtest> --mnemonic "<words>"
+ */
+import { parseFlags } from '../utils.mjs';
+import { signPsbt } from '../../dist/index.mjs';
+
+export async function run(walletName, flagArgs, options = {}) {
+    const opts = parseFlags(flagArgs, { required: ['psbt', 'network', 'mnemonic'], optional: [] }, { usage: options.usage });
+    const signed = await signPsbt(opts.mnemonic, opts.psbt, opts.network);
+    console.log(signed);
+}

package/cli/commands/signpsbt.mjs

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

package/cli/commands/witnessreceive.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.witnessReceive(request);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}

package/cli/data/stage2-receiver.example.json

@@ -0,0 +1,11 @@
+{
+  "walletName": "stage2-receiver",
+  "network": "signet",
+  "mnemonic": "REPLACE_WITH_12_OR_24_WORD_MNEMONIC",
+  "xpub": "REPLACE_WITH_XPUB",
+  "accountXpubVanilla": "REPLACE_WITH_ACCOUNT_XPUB_VANILLA",
+  "accountXpubColored": "REPLACE_WITH_ACCOUNT_XPUB_COLORED",
+  "masterFingerprint": "REPLACE_WITH_FINGERPRINT",
+  "xpriv": "REPLACE_WITH_XPRIV",
+  "createdAt": "REPLACE_WITH_ISO_TIMESTAMP"
+}

package/cli/data/stage2-sender.example.json

@@ -0,0 +1,11 @@
+{
+  "walletName": "stage2-sender",
+  "network": "signet",
+  "mnemonic": "REPLACE_WITH_12_OR_24_WORD_MNEMONIC",
+  "xpub": "REPLACE_WITH_XPUB",
+  "accountXpubVanilla": "REPLACE_WITH_ACCOUNT_XPUB_VANILLA",
+  "accountXpubColored": "REPLACE_WITH_ACCOUNT_XPUB_COLORED",
+  "masterFingerprint": "REPLACE_WITH_FINGERPRINT",
+  "xpriv": "REPLACE_WITH_XPRIV",
+  "createdAt": "REPLACE_WITH_ISO_TIMESTAMP"
+}

package/cli/generate_keys.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * Generate Keys Script
+ * 
+ * Generates new wallet keys and saves them to a JSON file.
+ * 
+ * Usage:
+ *   node generate_keys.mjs <wallet_name> [network]
+ * 
+ * Examples:
+ *   node generate_keys.mjs mywallet          # Uses default network (regtest)
+ *   node generate_keys.mjs mywallet testnet  # Uses testnet
+ */
+
+import { generateKeys } from '../dist/index.mjs';
+import { saveWalletConfig, handleError } from './utils.mjs';
+
+async function main() {
+    const args = process.argv.slice(2);
+    
+    if (args.length === 0) {
+        console.error('Usage: node generate_keys.mjs <wallet_name> [network]');
+        console.error('Example: node generate_keys.mjs mywallet');
+        console.error('Example: node generate_keys.mjs mywallet testnet');
+        process.exit(1);
+    }
+
+    const walletName = args[0];
+    const network = args[1] || 'regtest';
+
+    console.log(`Generating keys for wallet: ${walletName}`);
+    console.log(`Network: ${network}`);
+
+    try {
+        // Generate keys
+        const keys = await generateKeys(network);
+        
+        // Create wallet config object
+        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(),
+        };
+
+        // Save to JSON file
+        const filepath = saveWalletConfig(walletName, walletConfig);
+        
+        console.log(`\n✅ Keys generated successfully!`);
+        console.log(`📁 Saved to: ${filepath}`);
+        console.log(`\n⚠️  IMPORTANT: Keep your mnemonic safe and secure!`);
+        console.log(`   Mnemonic: ${keys.mnemonic}`);
+        console.log(`\nYou can now use this wallet with: node getaddress.mjs ${walletName}`);
+        
+    } catch (error) {
+        handleError(error, 'generating keys');
+    }
+}
+
+main();

package/cli/run.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+/**
+ * Single entrypoint for UTEXO CLI commands.
+ * Usage: utexo <command> <wallet_name> [options...]
+ */
+
+import { handleError } from './utils.mjs';
+import { run as runAddress } from './commands/address.mjs';
+import { run as runBtcbalance } from './commands/btcbalance.mjs';
+import { run as runListassets } from './commands/listassets.mjs';
+import { run as runListtransfers } from './commands/listtransfers.mjs';
+import { run as runRefresh } from './commands/refresh.mjs';
+import { run as runListunspents } from './commands/listunspents.mjs';
+import { run as runGetOnchainSendStatus } from './commands/getonchainsendstatus.mjs';
+import { run as runDecodergbinvoice } from './commands/decodergbinvoice.mjs';
+import { run as runBlindreceive } from './commands/blindreceive.mjs';
+import { run as runWitnessreceive } from './commands/witnessreceive.mjs';
+import { run as runOnchainreceive } from './commands/onchainreceive.mjs';
+import { run as runCreateutxos } from './commands/createutxos.mjs';
+import { run as runOnchainsendbegin } from './commands/onchainsendbegin.mjs';
+import { run as runSignpsbt } from './commands/signpsbt.mjs';
+import { run as runSignPsbtStandalone } from './commands/sign-psbt.mjs';
+import { run as runOnchainsendend } from './commands/onchainsendend.mjs';
+import { run as runOnchainsend } from './commands/onchainsend.mjs';
+import { run as runSend } from './commands/send.mjs';
+import { run as runCreatelightninginvoice } from './commands/createlightninginvoice.mjs';
+import { run as runPaylightninginvoicebegin } from './commands/paylightninginvoicebegin.mjs';
+import { run as runPaylightninginvoice } from './commands/paylightninginvoice.mjs';
+import { run as runPaylightninginvoiceend } from './commands/paylightninginvoiceend.mjs';
+import { run as runGetlightningsendrequest } from './commands/getlightningsendrequest.mjs';
+import { run as runGetlightningreceiverequest } from './commands/getlightningreceiverequest.mjs';
+import { run as runGenerateKeys } from './commands/generate_keys.mjs';
+import { parseFlags, runWithWalletManager } from './utils.mjs';
+
+const args = process.argv.slice(2);
+let command = args[0];
+let walletName = args[1];
+let flagArgs = args.slice(2);
+// sign-psbt: no wallet name, only flags (--psbt --network --mnemonic)
+if (command === 'sign-psbt') {
+    walletName = null;
+    flagArgs = args.slice(1);
+}
+
+// WalletManager subcommands: utexo wm <subcommand> <wallet_name> [flags]
+if (command === 'wm') {
+    const wmSubcommand = args[1];
+    walletName = args[2];
+    flagArgs = args.slice(3);
+    if (!wmSubcommand || !['address', 'btcbalance', 'refresh', 'sync', 'createutxos', 'blindreceive', 'listassets', 'listtransfers', 'sendbatch', 'sendbtc'].includes(wmSubcommand)) {
+        console.error('Usage: utexo wm <address|btcbalance|refresh|sync|createutxos|blindreceive|listassets|listtransfers|sendbatch|sendbtc> <wallet_name> [options...]');
+        process.exit(1);
+    }
+    command = `wm_${wmSubcommand}`;
+}
+
+export const USAGE = `Usage: utexo <command> <wallet_name> [options...]
+
+Commands (no extra flags): address, btcbalance, listassets, listtransfers, refresh, listunspents
+  utexo address <wallet>
+  utexo btcbalance <wallet>
+  utexo listassets <wallet> [--assetId <id>]
+  utexo listtransfers <wallet> [--assetId <id>]
+  utexo refresh <wallet>
+  utexo listunspents <wallet>
+
+Onchain: getonchainsendstatus, onchainreceive, onchainsendbegin, onchainsendend, onchainsend, send
+  utexo getonchainsendstatus <wallet> --invoice "<inv>"
+  utexo onchainreceive <wallet> --amount <n> [--assetId <id>] [--minConfirmations <n>] [--durationSeconds <n>]
+  utexo onchainsendbegin <wallet> --invoice "<inv>"
+  utexo onchainsendend <wallet> --invoice "<inv>" --signedPsbt "<psbt>"
+  utexo onchainsend <wallet> --invoice "<inv>" [--mnemonic "<mn>"]
+  utexo send <wallet> --invoice "<inv>" [--assetId <id>] [--amount <n>] [--witnessData "<json>"] [--mnemonic "<mn>"] [--feeRate <n>] [--minConfirmations <n>]
+
+Receive invoices: blindreceive, witnessreceive
+  utexo blindreceive <wallet> --amount <n> [--assetId <id>] [--minConfirmations <n>] [--durationSeconds <n>]
+  utexo witnessreceive <wallet> --amount <n> [--assetId <id>] [--minConfirmations <n>] [--durationSeconds <n>]
+
+Lightning: createlightninginvoice, paylightninginvoicebegin, paylightninginvoice, paylightninginvoiceend, getlightningsendrequest, getlightningreceiverequest
+  utexo createlightninginvoice <wallet> --assetId <id> --amount <n> [--amountSats <n>] [--expirySeconds <n>]
+  utexo paylightninginvoicebegin <wallet> --lnInvoice "<inv>" [--maxFee <n>]
+  utexo paylightninginvoice <wallet> --lnInvoice "<inv>" [--amount <n>] [--assetId <id>] [--maxFee <n>] [--mnemonic "<mn>"]
+  utexo paylightninginvoiceend <wallet> --lnInvoice "<inv>" --signedPsbt "<psbt>"
+  utexo getlightningsendrequest <wallet> --lnInvoice "<inv>"
+  utexo getlightningreceiverequest <wallet> --lnInvoice "<inv>"
+
+Other: decodergbinvoice, createutxos, signpsbt, sign-psbt, generate_keys
+  utexo decodergbinvoice <wallet> --invoice "<inv>"
+  utexo createutxos <wallet> [--num <n>] [--size <n>] [--feeRate <n>] [--upTo]
+  utexo signpsbt <wallet> --psbt "<psbt>" [--mnemonic "<mn>"]   # uses wallet (init/goOnline)
+  utexo sign-psbt --psbt "<psbt>" --network <net> --mnemonic "<mn>"   # standalone, no wallet
+  utexo generate_keys <wallet_name> [network]   # network: regtest (default), testnet, mainnet
+
+WalletManager (same keys file, standard RGB wallet):
+  utexo wm address <wallet>
+  utexo wm btcbalance <wallet>
+  utexo wm refresh <wallet>
+  utexo wm sync <wallet>
+  utexo wm createutxos <wallet> [--num <n>] [--size <n>] [--feeRate <n>] [--upTo]
+  utexo wm blindreceive <wallet> --amount <n> [--assetId <id>] [--minConfirmations <n>] [--durationSeconds <n>]
+  utexo wm listassets <wallet>   # list assets and BTC balance
+  utexo wm listtransfers <wallet> [--assetId <id>]
+  utexo wm sendbatch <wallet> --assetId <id> --amount <n> --invoices "<inv1>,<inv2>,..." [--feeRate <n>] [--minConfirmations <n>]
+  utexo wm sendbtc <wallet> --address <addr> --amount <sats> [--feeRate <n>]
+
+  Or run script with hardcoded params: node cli/scripts/send-batch-wm.mjs`;
+
+function printUsage() {
+    console.error(USAGE);
+}
+
+const withUsage = (fn) => (walletName, flagArgs) => fn(walletName, flagArgs, { usage: USAGE });
+
+async function runWmAddress(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWalletManager(walletName, async (wallet) => {
+        const address = await wallet.getAddress();
+        console.log(`✅ Address: ${address}`);
+    }, { quiet: true });
+}
+
+async function runWmBtcbalance(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWalletManager(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 });
+}
+
+async function runWmRefresh(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWalletManager(walletName, async (wallet) => {
+        await wallet.refreshWallet();
+        console.log('✅ Wallet refreshed');
+    }, { quiet: true });
+}
+
+async function runWmSync(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWalletManager(walletName, async (wallet) => {
+        await wallet.syncWallet();
+        console.log('✅ Wallet synced');
+    }, { quiet: true });
+}
+
+async function runWmCreateutxos(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 runWithWalletManager(walletName, async (wallet) => {
+        const count = await wallet.createUtxos({ num, size, feeRate, upTo: upTo || undefined });
+        console.log(`✅ Created ${count} UTXO(s)`);
+    }, { quiet: true });
+}
+
+async function runWmBlindreceive(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, { required: ['amount'], optional: ['assetId', 'minConfirmations', 'durationSeconds'] }, { usage: 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 runWithWalletManager(walletName, async (wallet) => {
+        const result = await wallet.blindReceive(request);
+        console.log(JSON.stringify(result, null, 2));
+    }, { quiet: true });
+}
+
+async function runWmListassets(walletName, flagArgs) {
+    parseFlags(flagArgs, { required: [], optional: [] });
+    await runWithWalletManager(walletName, async (wallet) => {
+        const [assets, btcBalance] = await Promise.all([wallet.listAssets(), wallet.getBtcBalance()]);
+        console.log('BTC balance:');
+        console.log(`  Vanilla: settled ${btcBalance.vanilla.settled}, spendable ${btcBalance.vanilla.spendable} sats`);
+        console.log(`  Colored: settled ${btcBalance.colored.settled}, spendable ${btcBalance.colored.spendable} sats`);
+        console.log('\nAssets:');
+        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(`\n✅ Total: ${n} asset(s)`);
+    }, { quiet: true });
+}
+
+async function runWmListtransfers(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, { required: [], optional: ['assetId'] });
+    await runWithWalletManager(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 });
+}
+
+const DEFAULT_TRANSPORT = 'rpcs://proxy.iriswallet.com/0.2/json-rpc';
+
+async function buildRecipientMap(wallet, assetId, amount, invoices) {
+    const recipients = [];
+    for (const invoiceStr of invoices) {
+        const invoiceData = await wallet.decodeRGBInvoice({ invoice: invoiceStr });
+        const transportEndpoints =
+            invoiceData.transportEndpoints?.length > 0
+                ? invoiceData.transportEndpoints
+                : [DEFAULT_TRANSPORT];
+        recipients.push({
+            recipientId: invoiceData.recipientId,
+            witnessData: null,
+            assignment: { Fungible: amount },
+            transportEndpoints,
+        });
+    }
+    return { [assetId]: recipients };
+}
+
+async function runWmSendbtc(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, {
+        required: ['address', 'amount'],
+        optional: ['feeRate', 'skipSync'],
+    }, { usage: USAGE });
+    const address = opts.address;
+    const amount = parseInt(opts.amount, 10);
+    const feeRate = opts.feeRate ? parseInt(opts.feeRate, 10) : 1;
+    const skipSync = opts.skipSync === 'true' || opts.skipSync === '1';
+    await runWithWalletManager(walletName, async (wallet) => {
+        const txid = await wallet.sendBtc({ address, amount, feeRate, ...(skipSync && { skipSync }) });
+        console.log(`✅ BTC sent. Txid: ${txid}`);
+    }, { quiet: true });
+}
+
+async function runWmSendbatch(walletName, flagArgs) {
+    const opts = parseFlags(flagArgs, {
+        required: ['assetId', 'amount', 'invoices'],
+        optional: ['feeRate', 'minConfirmations'],
+    }, { usage: USAGE });
+    const invoices = opts.invoices.split(',').map((s) => s.trim()).filter(Boolean);
+    if (invoices.length === 0) {
+        console.error('--invoices must contain at least one invoice (comma-separated)');
+        process.exit(1);
+    }
+    const assetId = opts.assetId;
+    const amount = parseInt(opts.amount, 10);
+    await runWithWalletManager(walletName, async (wallet) => {
+        const recipientMap = await buildRecipientMap(wallet, assetId, amount, invoices);
+        const result = await wallet.sendBatch({
+            recipientMap,
+            ...(opts.feeRate && { feeRate: parseInt(opts.feeRate, 10) }),
+            ...(opts.minConfirmations && { minConfirmations: parseInt(opts.minConfirmations, 10) }),
+        });
+        console.log(JSON.stringify(result, null, 2));
+        console.log('✅ Batch send completed');
+    }, { quiet: true });
+}
+
+const commands = {
+    address: runAddress,
+    btcbalance: runBtcbalance,
+    listassets: runListassets,
+    listtransfers: runListtransfers,
+    refresh: runRefresh,
+    listunspents: runListunspents,
+    getonchainsendstatus: withUsage(runGetOnchainSendStatus),
+    decodergbinvoice: withUsage(runDecodergbinvoice),
+    blindreceive: withUsage(runBlindreceive),
+    witnessreceive: withUsage(runWitnessreceive),
+    onchainreceive: withUsage(runOnchainreceive),
+    createutxos: runCreateutxos,
+    onchainsendbegin: withUsage(runOnchainsendbegin),
+    signpsbt: withUsage(runSignpsbt),
+    'sign-psbt': withUsage(runSignPsbtStandalone),
+    onchainsendend: withUsage(runOnchainsendend),
+    onchainsend: withUsage(runOnchainsend),
+    send: withUsage(runSend),
+    createlightninginvoice: withUsage(runCreatelightninginvoice),
+    paylightninginvoicebegin: withUsage(runPaylightninginvoicebegin),
+    paylightninginvoice: withUsage(runPaylightninginvoice),
+    paylightninginvoiceend: withUsage(runPaylightninginvoiceend),
+    getlightningsendrequest: withUsage(runGetlightningsendrequest),
+    getlightningreceiverequest: withUsage(runGetlightningreceiverequest),
+    generate_keys: runGenerateKeys,
+    wm_address: runWmAddress,
+    wm_btcbalance: runWmBtcbalance,
+    wm_refresh: runWmRefresh,
+    wm_sync: runWmSync,
+    wm_createutxos: runWmCreateutxos,
+    wm_blindreceive: runWmBlindreceive,
+    wm_listassets: runWmListassets,
+    wm_listtransfers: runWmListtransfers,
+    wm_sendbatch: runWmSendbatch,
+    wm_sendbtc: runWmSendbtc,
+};
+
+async function main() {
+    if (!command || !commands[command]) {
+        printUsage();
+        process.exit(1);
+    }
+
+    try {
+        await commands[command](walletName, flagArgs);
+    } catch (error) {
+        handleError(error, `running command '${command}'`);
+    }
+}
+
+main();