@1sat/cli 0.0.114 → 0.0.115

package/README.md

@@ -232,14 +232,27 @@ OpNS (Ordinals Name System) binds your BAP identity to an on-chain name inscript
 
 ### Sweep
 
-Import assets from an external private key (e.g., a legacy P2PKH wallet) into your BRC-100 wallet.
+Import assets from an external private key (legacy P2PKH / Yours backup WIF) into the BRC-100 wallet.
 
 ```bash
-1sat sweep scan --wif <key>     # Preview what a key holds (BSV, ordinals, tokens)
-1sat sweep import --wif <key>   # Import everything into your wallet
+1sat sweep scan --wif <key>
+1sat sweep import --wif <key> --dry-run
+1sat sweep import --wif <key>
+1sat sweep import --wif <key> --only opns,bsv20
+1sat sweep import --wif <key> --skip bsv21
 ```
 
-`scan` is non-destructive. `import` broadcasts transactions — confirm when prompted or pass `--yes`.
+`scan` is the full inventory. `import --dry-run` is the same plan after `--only` / `--skip`. `import` with no class flags attempts every class that can move into BRC-100:
+
+| Class | Destination |
+|---|---|
+| `bsv` | Funding |
+| `ordinals` | `1sat` basket |
+| `opns` | `opns` basket |
+| `bsv20` | `bsv20` basket (ticker identity) |
+| `bsv21` | `bsv21` basket (deploy-outpoint identity) |
+
+Listed OrdLocks cancel into the destination in the same transaction. Time-locks and RUN outputs stay as leftover. `--only` and `--skip` take `bsv,ordinals,opns,bsv20,bsv21`. Confirm when prompted, or pass `--yes`.
 
 ---
 

package/dist/cli.js

@@ -1328,13 +1328,41 @@ var init_help = __esm(() => {
       subcommands: [
         {
           name: "scan",
-          description: "Scan an address for sweepable UTXOs (BSV, ordinals, BSV21)",
-          args: [{ flag: "--wif", values: "<key>", required: true }]
+          description: "Show every UTXO class at an address (BSV, ordinals, OpNS, BSV-20, BSV-21, leftover locks/RUN)",
+          args: [
+            { flag: "--wif", values: "<key>", required: true },
+            {
+              flag: "--only",
+              values: "<bsv,ordinals,opns,bsv20,bsv21>",
+              description: "Limit the report to these classes"
+            },
+            {
+              flag: "--skip",
+              values: "<class,...>",
+              description: "Omit classes from the report"
+            }
+          ]
         },
         {
           name: "import",
-          description: "Sweep UTXOs from a WIF into the wallet",
-          args: [{ flag: "--wif", values: "<key>", required: true }]
+          description: "Sweep transferable UTXOs from a WIF into the wallet. Default is all classes we can move to BRC-100 (including listed OrdLocks). Locks and RUN stay.",
+          args: [
+            { flag: "--wif", values: "<key>", required: true },
+            {
+              flag: "--only",
+              values: "<bsv,ordinals,opns,bsv20,bsv21>",
+              description: "Sweep only these classes"
+            },
+            {
+              flag: "--skip",
+              values: "<class,...>",
+              description: "Skip these classes"
+            },
+            {
+              flag: "--dry-run",
+              description: "Print the plan and do not broadcast"
+            }
+          ]
         }
       ]
     },
@@ -3964,11 +3992,146 @@ var init_storage = __esm(() => {
   init_output();
 });
 
+// src/commands/sweep-classes.ts
+function parseSweepClasses(raw, flag) {
+  if (!raw)
+    return new Set;
+  const selected = new Set;
+  for (const token of raw.split(",").map((t) => t.trim().toLowerCase())) {
+    if (!token)
+      continue;
+    const mapped = ALIASES[token];
+    if (!mapped) {
+      throw new Error(`Unknown ${flag} class '${token}'. Use: ${SWEEP_CLASSES.join(", ")}`);
+    }
+    selected.add(mapped);
+  }
+  return selected;
+}
+function selectedSweepClasses(only, skip) {
+  if (only && skip) {
+    throw new Error("--only and --skip are mutually exclusive");
+  }
+  if (only) {
+    const selected2 = parseSweepClasses(only, "--only");
+    if (selected2.size === 0) {
+      throw new Error("--only requires at least one class");
+    }
+    return selected2;
+  }
+  const selected = new Set(SWEEP_CLASSES);
+  if (skip) {
+    for (const cls of parseSweepClasses(skip, "--skip"))
+      selected.delete(cls);
+  }
+  return selected;
+}
+var SWEEP_CLASSES, ALIASES;
+var init_sweep_classes = __esm(() => {
+  SWEEP_CLASSES = [
+    "bsv",
+    "ordinals",
+    "opns",
+    "bsv20",
+    "bsv21"
+  ];
+  ALIASES = {
+    bsv: "bsv",
+    funding: "bsv",
+    ordinals: "ordinals",
+    ord: "ordinals",
+    opns: "opns",
+    names: "opns",
+    bsv20: "bsv20",
+    bsv21: "bsv21"
+  };
+});
+
+// src/commands/sweep-plan.ts
+import {
+  groupBsv20Tokens,
+  isListedOutput
+} from "@1sat/actions";
+function listedCount(outputs) {
+  return outputs.filter((o) => isListedOutput(o)).length;
+}
+function buildSweepPlan(scan, classes) {
+  const want = (cls) => classes.has(cls);
+  const groupedBsv20 = groupBsv20Tokens(scan.bsv20Tokens);
+  const parsedOutpoints = new Set(groupedBsv20.flatMap((g) => g.outputs.map((o) => o.outpoint)));
+  const transferableBsv21 = scan.bsv21Tokens.filter((t) => t.outputs.length > 0);
+  const skippedBsv21 = scan.bsv21Tokens.filter((t) => t.outputs.length === 0);
+  return {
+    classes: SWEEP_CLASSES.filter((c) => classes.has(c)),
+    bsv: want("bsv") ? { count: scan.funding.length, sats: scan.totalFundingSats } : { count: 0, sats: 0 },
+    ordinals: want("ordinals") ? {
+      count: scan.ordinals.length,
+      listed: listedCount(scan.ordinals)
+    } : { count: 0, listed: 0 },
+    opns: want("opns") ? {
+      count: scan.opnsNames.length,
+      listed: listedCount(scan.opnsNames)
+    } : { count: 0, listed: 0 },
+    bsv20: want("bsv20") ? groupedBsv20.map((g) => ({
+      tick: g.tick,
+      amount: g.totalAmount.toString(),
+      count: g.outputs.length,
+      listed: listedCount(g.outputs)
+    })) : [],
+    bsv21: want("bsv21") ? transferableBsv21.map((t) => ({
+      tokenId: t.tokenId,
+      symbol: t.symbol,
+      amount: t.totalAmount.toString(),
+      count: t.outputs.length,
+      listed: listedCount(t.outputs),
+      active: t.isActive
+    })) : [],
+    leftover: {
+      locked: scan.locked.length,
+      run: scan.run.length,
+      inactiveBsv21: skippedBsv21.reduce((n, t) => n + t.outputs.length, 0),
+      unparsedBsv20: scan.bsv20Tokens.filter((o) => !parsedOutpoints.has(o.outpoint)).length
+    }
+  };
+}
+function planHasWork(plan) {
+  return plan.bsv.count > 0 || plan.ordinals.count > 0 || plan.opns.count > 0 || plan.bsv20.length > 0 || plan.bsv21.length > 0;
+}
+function describePlan(plan) {
+  const parts = [];
+  if (plan.bsv.count)
+    parts.push(`${plan.bsv.sats} sats (${plan.bsv.count} UTXOs)`);
+  if (plan.ordinals.count) {
+    const listed = plan.ordinals.listed ? `, ${plan.ordinals.listed} listed` : "";
+    parts.push(`${plan.ordinals.count} ordinal(s)${listed}`);
+  }
+  if (plan.opns.count) {
+    const listed = plan.opns.listed ? `, ${plan.opns.listed} listed` : "";
+    parts.push(`${plan.opns.count} OpNS name(s)${listed}`);
+  }
+  for (const t of plan.bsv20) {
+    const listed = t.listed ? `, ${t.listed} listed` : "";
+    parts.push(`${t.amount} ${t.tick} (${t.count} UTXOs${listed})`);
+  }
+  for (const t of plan.bsv21) {
+    const listed = t.listed ? `, ${t.listed} listed` : "";
+    parts.push(`${t.amount} ${t.symbol ?? t.tokenId.slice(0, 12)} (${t.count} UTXOs${listed})`);
+  }
+  return parts;
+}
+var init_sweep_plan = __esm(() => {
+  init_sweep_classes();
+});
+
 // src/commands/sweep.ts
 import {
+  SWEEP_BATCH_SIZE,
+  bsv21SweepBatches,
+  groupBsv20Tokens as groupBsv20Tokens2,
   prepareSweepInputs,
   scanAddress,
   sweepBsv,
+  sweepBsv20,
   sweepBsv21,
   sweepOrdinals
 } from "@1sat/actions";
@@ -3988,176 +4151,253 @@ async function handleSweepCommand(args, opts) {
       }
   }
 }
-async function sweepScan(args, opts) {
+function loadSweepKey(args) {
   const wif = extractFlag(args, "--wif");
   if (!wif)
     fatal("Missing --wif <private-key>");
-  let address;
   try {
     const pk = PrivateKey4.fromWif(wif);
-    address = pk.toPublicKey().toAddress();
+    return { wif, address: pk.toPublicKey().toAddress() };
   } catch {
     fatal("Invalid WIF private key");
   }
+}
+function loadClasses(args) {
+  try {
+    return selectedSweepClasses(extractFlag(args, "--only"), extractFlag(args, "--skip"));
+  } catch (error) {
+    fatal(error instanceof Error ? error.message : String(error));
+  }
+}
+function leftoverLines(plan) {
+  const lines = [];
+  if (plan.leftover.locked)
+    lines.push(`${plan.leftover.locked} locked output(s) (not swept)`);
+  if (plan.leftover.run)
+    lines.push(`${plan.leftover.run} RUN token output(s) (not sweepable)`);
+  if (plan.leftover.inactiveBsv21)
+    lines.push(`${plan.leftover.inactiveBsv21} BSV-21 UTXO(s) with no parseable amount`);
+  if (plan.leftover.unparsedBsv20)
+    lines.push(`${plan.leftover.unparsedBsv20} BSV-20 UTXO(s) with no parseable tick/amt`);
+  return lines;
+}
+function printInventory(address, plan, opts, mode) {
+  if (opts.json) {
+    output({
+      address,
+      mode,
+      classes: plan.classes,
+      wouldSweep: {
+        bsv: plan.bsv,
+        ordinals: plan.ordinals,
+        opns: plan.opns,
+        bsv20: plan.bsv20,
+        bsv21: plan.bsv21
+      },
+      leftover: plan.leftover
+    }, opts);
+    return;
+  }
+  const title = mode === "dry-run" ? "Dry run" : "Scan";
+  console.log(`
+  ${title} for ${formatValue(address)}
+`);
+  console.log(`  ${formatLabel("Classes:")} ${formatValue(plan.classes.join(", ") || "(none)")}`);
+  console.log(`
+  ${formatLabel("Funding UTXOs:")} ${plan.bsv.count}`);
+  if (plan.bsv.count > 0) {
+    console.log(`  ${formatLabel("Total funding:")} ${formatValue(plan.bsv.sats)} satoshis`);
+  }
+  console.log(`
+  ${formatLabel("Ordinal UTXOs:")} ${plan.ordinals.count}`);
+  if (plan.ordinals.listed)
+    console.log(`  ${formatLabel("Listed:")} ${plan.ordinals.listed}`);
+  console.log(`
+  ${formatLabel("OpNS names:")} ${plan.opns.count}`);
+  if (plan.opns.listed)
+    console.log(`  ${formatLabel("Listed:")} ${plan.opns.listed}`);
+  console.log(`
+  ${formatLabel("BSV-20:")} ${plan.bsv20.length} ticker(s)`);
+  for (const t of plan.bsv20) {
+    const listed = t.listed ? `  ${formatLabel(`listed ${t.listed}`)}` : "";
+    console.log(`    ${formatValue(t.tick)}  ${formatLabel("amount:")} ${formatValue(t.amount)}  ${formatLabel("UTXOs:")} ${t.count}${listed}`);
+  }
+  console.log(`
+  ${formatLabel("BSV-21:")} ${plan.bsv21.length} token(s)`);
+  for (const t of plan.bsv21) {
+    const listed = t.listed ? `  ${formatLabel(`listed ${t.listed}`)}` : "";
+    console.log(`    ${formatValue(t.symbol ?? t.tokenId.slice(0, 12))}  ${formatLabel("amount:")} ${formatValue(t.amount)}  ${formatLabel("UTXOs:")} ${t.count}${listed}`);
+  }
+  const leftover = leftoverLines(plan);
+  if (leftover.length) {
+    console.log(`
+  ${formatLabel("Leftover:")}`);
+    for (const line of leftover)
+      console.log(`    ${formatWarning(line)}`);
+  }
+  const transferable = plan.bsv.count + plan.ordinals.count + plan.opns.count + plan.bsv20.reduce((n, t) => n + t.count, 0) + plan.bsv21.reduce((n, t) => n + t.count, 0);
+  console.log(`
+  ${transferable} transferable UTXO(s) in selected classes.`);
+}
+async function sweepScan(args, opts) {
+  const { address } = loadSweepKey(args);
+  const classes = loadClasses(args);
   const privateKey = await loadKey();
   const { ctx, destroy } = await loadContext(privateKey, {
     chain: opts.chain
   });
   try {
-    if (!ctx.services) {
+    if (!ctx.services)
       fatal("Services required for sweep scan");
-    }
-    const result = await scanAddress(ctx.services, address);
-    if (opts.json) {
-      output(result, opts);
-      return;
-    }
-    console.log(`
-  Scan results for ${formatValue(address)}:
-`);
-    console.log(`  ${formatLabel("Funding UTXOs:")} ${result.funding.length}`);
-    if (result.funding.length > 0) {
-      console.log(`  ${formatLabel("Total funding:")} ${formatValue(result.totalFundingSats)} satoshis`);
-      for (const f of result.funding) {
-        console.log(`    ${formatValue(f.outpoint)}  ${formatLabel(`${f.satoshis ?? 0} sats`)}`);
-      }
-    }
-    console.log(`
-  ${formatLabel("Ordinal UTXOs:")} ${result.ordinals.length}`);
-    if (result.ordinals.length > 0) {
-      for (const o of result.ordinals) {
-        console.log(`    ${formatValue(o.outpoint)}`);
-      }
-    }
-    console.log(`
-  ${formatLabel("BSV-21 Tokens:")} ${result.bsv21Tokens.length}`);
-    if (result.bsv21Tokens.length > 0) {
-      for (const t of result.bsv21Tokens) {
-        console.log(`    ${formatValue(t.symbol ?? t.tokenId.slice(0, 12))}  ${formatLabel("amount:")} ${formatValue(t.totalAmount.toString())}  ${formatLabel("UTXOs:")} ${t.outputs.length}  ${formatLabel("dec:")} ${t.decimals}`);
-      }
-    }
-    console.log(`
-  ${formatLabel("RUN Tokens:")} ${result.run.length}`);
-    if (result.run.length > 0) {
-      const runSats = result.run.reduce((sum, r) => sum + (r.satoshis ?? 0), 0);
-      console.log(`  ${formatLabel("Total locked:")} ${formatValue(runSats)} satoshis (not sweepable)`);
-      for (const r of result.run) {
-        console.log(`    ${formatValue(r.outpoint)}  ${formatLabel(`${r.satoshis ?? 0} sats`)}`);
-      }
-    }
-    const total = result.funding.length + result.ordinals.length + result.bsv21Tokens.reduce((n, t) => n + t.outputs.length, 0);
-    console.log(`
-  ${total} sweepable UTXO(s) found.`);
-    if (result.run.length > 0) {
-      console.log(`  ${result.run.length} RUN token output(s) excluded.`);
-    }
+    const scan = await scanAddress(ctx.services, address);
+    printInventory(address, buildSweepPlan(scan, classes), opts, "scan");
   } finally {
     await destroy();
   }
 }
 async function sweepImport(args, opts) {
-  const wif = extractFlag(args, "--wif");
-  if (!wif)
-    fatal("Missing --wif <private-key>");
-  let address;
-  let sweepKey;
-  try {
-    sweepKey = PrivateKey4.fromWif(wif);
-    address = sweepKey.toPublicKey().toAddress();
-  } catch {
-    fatal("Invalid WIF private key");
-  }
+  const { wif, address } = loadSweepKey(args);
+  const classes = loadClasses(args);
+  const dryRun = hasFlag(args, "--dry-run");
+  const sweepKey = PrivateKey4.fromWif(wif);
   const privateKey = await loadKey();
   const { ctx, destroy } = await loadContext(privateKey, {
     chain: opts.chain
   });
+  let failed = false;
   try {
-    if (!ctx.services) {
+    if (!ctx.services)
       fatal("Services required for sweep import");
-    }
     const scan = await scanAddress(ctx.services, address);
-    const hasFunding = scan.funding.length > 0;
-    const hasOrdinals = scan.ordinals.length > 0;
-    const hasTokens = scan.bsv21Tokens.some((t) => t.isActive && t.outputs.length > 0);
-    if (!hasFunding && !hasOrdinals && !hasTokens) {
-      if (scan.run.length > 0) {
-        fatal(`No sweepable UTXOs found at ${address} (${scan.run.length} RUN token output(s) excluded)`);
-      }
-      fatal(`No UTXOs found at ${address}`);
-    }
-    const parts = [];
-    if (hasFunding)
-      parts.push(`${scan.totalFundingSats} sats (${scan.funding.length} UTXOs)`);
-    if (hasOrdinals)
-      parts.push(`${scan.ordinals.length} ordinal(s)`);
-    if (hasTokens) {
-      for (const t of scan.bsv21Tokens) {
-        if (t.isActive && t.outputs.length > 0) {
-          parts.push(`${t.totalAmount} ${t.symbol ?? t.tokenId.slice(0, 12)} token(s)`);
-        }
-      }
+    const plan = buildSweepPlan(scan, classes);
+    if (dryRun) {
+      printInventory(address, plan, opts, "dry-run");
+      return;
     }
-    if (scan.run.length > 0) {
-      parts.push(`${scan.run.length} RUN token output(s) excluded`);
+    if (!planHasWork(plan)) {
+      const leftover = leftoverLines(plan);
+      const extra = leftover.length ? ` (${leftover.join("; ")})` : "";
+      fatal(`No transferable UTXOs found at ${address}${extra}`);
     }
+    const parts = describePlan(plan);
+    for (const line of leftoverLines(plan))
+      parts.push(line);
     if (!opts.yes) {
       const ok = await confirm7({
         message: `Sweep ${parts.join(", ")} from ${address}?`
       });
-      if (isCancel8(ok) || !ok) {
+      if (isCancel8(ok) || !ok)
         fatal("Sweep cancelled.");
-      }
     }
     const txids = [];
-    if (hasFunding) {
-      const inputs = await prepareSweepInputs(ctx, scan.funding);
-      const keys = inputs.map(() => sweepKey);
-      const result = await sweepBsv.execute(ctx, { inputs, keys });
-      if (result.error) {
-        fatal(`BSV sweep failed: ${result.error}`);
+    const errors = [];
+    const run = async (label, fn) => {
+      try {
+        const result = await fn();
+        if (result.error) {
+          errors.push(`${label}: ${result.error}`);
+          return false;
+        }
+        if (result.txid)
+          txids.push(result.txid);
+        return true;
+      } catch (error) {
+        errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+      }
+    };
+    const keysFor = (inputs) => inputs.map(() => sweepKey);
+    const runOrdinalBatches = async (label, outputs) => {
+      for (let offset = 0;offset < outputs.length; offset += SWEEP_BATCH_SIZE) {
+        const batch = outputs.slice(offset, offset + SWEEP_BATCH_SIZE);
+        const ok = await run(outputs.length <= SWEEP_BATCH_SIZE ? label : `${label} (${offset + 1}–${offset + batch.length} of ${outputs.length})`, async () => {
+          const inputs = await prepareSweepInputs(ctx, batch);
+          return sweepOrdinals.execute(ctx, {
+            inputs,
+            keys: keysFor(inputs)
+          });
+        });
+        if (!ok)
+          break;
       }
-      if (result.txid)
-        txids.push(result.txid);
-    }
-    if (hasOrdinals) {
-      const inputs = await prepareSweepInputs(ctx, scan.ordinals);
-      const keys = inputs.map(() => sweepKey);
-      const result = await sweepOrdinals.execute(ctx, { inputs, keys });
-      if (result.error) {
-        fatal(`Ordinals sweep failed: ${result.error}`);
+    };
+    if (plan.bsv.count) {
+      await run("BSV", async () => {
+        const inputs = await prepareSweepInputs(ctx, scan.funding);
+        return sweepBsv.execute(ctx, {
+          inputs,
+          keys: keysFor(inputs)
+        });
+      });
+    }
+    if (plan.ordinals.count) {
+      await runOrdinalBatches("Ordinals", scan.ordinals);
+    }
+    if (plan.opns.count) {
+      await runOrdinalBatches("OpNS", scan.opnsNames);
+    }
+    if (plan.bsv20.length) {
+      const grouped = groupBsv20Tokens2(scan.bsv20Tokens);
+      for (const token of grouped) {
+        await run(`BSV-20 ${token.tick}`, async () => {
+          const base = await prepareSweepInputs(ctx, token.outputs);
+          const inputs = base.map((b) => ({
+            ...b,
+            tick: token.tick,
+            amount: token.amounts.get(b.outpoint) ?? "0"
+          }));
+          return sweepBsv20.execute(ctx, {
+            inputs,
+            keys: inputs.map(() => sweepKey)
+          });
+        });
       }
-      if (result.txid)
-        txids.push(result.txid);
     }
-    if (hasTokens) {
+    if (plan.bsv21.length) {
       for (const token of scan.bsv21Tokens) {
-        if (!token.isActive || token.outputs.length === 0)
+        if (token.outputs.length === 0)
           continue;
-        const base = await prepareSweepInputs(ctx, token.outputs);
-        const inputs = base.map((b) => ({
-          ...b,
-          tokenId: token.tokenId,
-          amount: token.amounts.get(b.outpoint) ?? "0"
-        }));
-        const keys = inputs.map(() => sweepKey);
-        const result = await sweepBsv21.execute(ctx, { inputs, keys });
-        if (result.error) {
-          fatal(`Token sweep failed (${token.symbol ?? token.tokenId.slice(0, 12)}): ${result.error}`);
+        const name = token.symbol ?? token.tokenId.slice(0, 12);
+        for (const batch of bsv21SweepBatches(token.outputs)) {
+          await run(`BSV-21 ${name}`, async () => {
+            const base = await prepareSweepInputs(ctx, batch);
+            const inputs = base.map((b) => ({
+              ...b,
+              tokenId: token.tokenId,
+              amount: token.amounts.get(b.outpoint) ?? "0"
+            }));
+            return sweepBsv21.execute(ctx, {
+              inputs,
+              keys: inputs.map(() => sweepKey)
+            });
+          });
         }
-        if (result.txid)
-          txids.push(result.txid);
       }
     }
-    output(opts.json ? { txids, swept: parts } : `Sweep complete. ${txids.length} transaction(s): ${txids.join(", ")}`, opts);
+    if (opts.json) {
+      output({ txids, errors, swept: parts }, opts);
+    } else if (errors.length) {
+      console.log(`Sweep finished with errors. ${txids.length} transaction(s): ${txids.join(", ") || "(none)"}`);
+      for (const err of errors)
+        console.error(formatWarning(err));
+    } else {
+      output(`Sweep complete. ${txids.length} transaction(s): ${txids.join(", ")}`, opts);
+    }
+    if (errors.length)
+      failed = true;
   } finally {
     await destroy();
   }
+  if (failed)
+    process.exit(1);
 }
 var init_sweep = __esm(() => {
   init_context();
   init_help();
   init_keys();
   init_output();
+  init_sweep_classes();
+  init_sweep_plan();
 });
 
 // src/commands/tokens.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/cli",
-  "version": "0.0.114",
+  "version": "0.0.115",
   "description": "CLI for 1Sat Ordinals SDK",
   "type": "module",
   "main": "./dist/cli.js",
@@ -27,9 +27,9 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@1sat/actions": "0.0.216",
+    "@1sat/actions": "0.0.217",
     "@1sat/client": "0.0.53",
-    "@1sat/types": "0.0.45",
+    "@1sat/types": "0.0.46",
     "@1sat/wallet-node": "0.0.75",
     "@1sat/wallet-server": "0.0.51",
     "@bopen-io/messagebox-server": "^1.3.2",

package/src/commands/sweep-classes.ts

@@ -0,0 +1,64 @@
+/**
+ * Transferable sweep classes. Locked and RUN outputs are leftover, not classes.
+ */
+export const SWEEP_CLASSES = [
+	'bsv',
+	'ordinals',
+	'opns',
+	'bsv20',
+	'bsv21',
+] as const
+
+export type SweepClass = (typeof SWEEP_CLASSES)[number]
+
+const ALIASES: Record<string, SweepClass> = {
+	bsv: 'bsv',
+	funding: 'bsv',
+	ordinals: 'ordinals',
+	ord: 'ordinals',
+	opns: 'opns',
+	names: 'opns',
+	bsv20: 'bsv20',
+	bsv21: 'bsv21',
+}
+
+export function parseSweepClasses(
+	raw: string | undefined,
+	flag: string,
+): Set<SweepClass> {
+	if (!raw) return new Set()
+	const selected = new Set<SweepClass>()
+	for (const token of raw.split(',').map((t) => t.trim().toLowerCase())) {
+		if (!token) continue
+		const mapped = ALIASES[token]
+		if (!mapped) {
+			throw new Error(
+				`Unknown ${flag} class '${token}'. Use: ${SWEEP_CLASSES.join(', ')}`,
+			)
+		}
+		selected.add(mapped)
+	}
+	return selected
+}
+
+/** Default is every transferable class. `--only` and `--skip` are exclusive. */
+export function selectedSweepClasses(
+	only: string | undefined,
+	skip: string | undefined,
+): Set<SweepClass> {
+	if (only && skip) {
+		throw new Error('--only and --skip are mutually exclusive')
+	}
+	if (only) {
+		const selected = parseSweepClasses(only, '--only')
+		if (selected.size === 0) {
+			throw new Error('--only requires at least one class')
+		}
+		return selected
+	}
+	const selected = new Set<SweepClass>(SWEEP_CLASSES)
+	if (skip) {
+		for (const cls of parseSweepClasses(skip, '--skip')) selected.delete(cls)
+	}
+	return selected
+}

package/src/commands/sweep-plan.ts

@@ -0,0 +1,134 @@
+import {
+	type ScanResult,
+	groupBsv20Tokens,
+	isListedOutput,
+} from '@1sat/actions'
+import { SWEEP_CLASSES, type SweepClass } from './sweep-classes.js'
+
+function listedCount(
+	outputs: Array<{ events?: string[]; data?: Record<string, unknown> }>,
+): number {
+	return outputs.filter((o) => isListedOutput(o)).length
+}
+
+export type SweepPlan = {
+	classes: SweepClass[]
+	bsv: { count: number; sats: number }
+	ordinals: { count: number; listed: number }
+	opns: { count: number; listed: number }
+	bsv20: Array<{
+		tick: string
+		amount: string
+		count: number
+		listed: number
+	}>
+	bsv21: Array<{
+		tokenId: string
+		symbol?: string
+		amount: string
+		count: number
+		listed: number
+		active: boolean
+	}>
+	leftover: {
+		locked: number
+		run: number
+		inactiveBsv21: number
+		unparsedBsv20: number
+	}
+}
+
+export function buildSweepPlan(
+	scan: ScanResult,
+	classes: Set<SweepClass>,
+): SweepPlan {
+	const want = (cls: SweepClass) => classes.has(cls)
+	const groupedBsv20 = groupBsv20Tokens(scan.bsv20Tokens)
+	const parsedOutpoints = new Set(
+		groupedBsv20.flatMap((g) => g.outputs.map((o) => o.outpoint)),
+	)
+	const transferableBsv21 = scan.bsv21Tokens.filter((t) => t.outputs.length > 0)
+	const skippedBsv21 = scan.bsv21Tokens.filter((t) => t.outputs.length === 0)
+
+	return {
+		classes: SWEEP_CLASSES.filter((c) => classes.has(c)),
+		bsv: want('bsv')
+			? { count: scan.funding.length, sats: scan.totalFundingSats }
+			: { count: 0, sats: 0 },
+		ordinals: want('ordinals')
+			? {
+					count: scan.ordinals.length,
+					listed: listedCount(scan.ordinals),
+				}
+			: { count: 0, listed: 0 },
+		opns: want('opns')
+			? {
+					count: scan.opnsNames.length,
+					listed: listedCount(scan.opnsNames),
+				}
+			: { count: 0, listed: 0 },
+		bsv20: want('bsv20')
+			? groupedBsv20.map((g) => ({
+					tick: g.tick,
+					amount: g.totalAmount.toString(),
+					count: g.outputs.length,
+					listed: listedCount(g.outputs),
+				}))
+			: [],
+		bsv21: want('bsv21')
+			? transferableBsv21.map((t) => ({
+					tokenId: t.tokenId,
+					symbol: t.symbol,
+					amount: t.totalAmount.toString(),
+					count: t.outputs.length,
+					listed: listedCount(t.outputs),
+					active: t.isActive,
+				}))
+			: [],
+		leftover: {
+			locked: scan.locked.length,
+			run: scan.run.length,
+			inactiveBsv21: skippedBsv21.reduce((n, t) => n + t.outputs.length, 0),
+			unparsedBsv20: scan.bsv20Tokens.filter(
+				(o) => !parsedOutpoints.has(o.outpoint),
+			).length,
+		},
+	}
+}
+
+export function planHasWork(plan: SweepPlan): boolean {
+	return (
+		plan.bsv.count > 0 ||
+		plan.ordinals.count > 0 ||
+		plan.opns.count > 0 ||
+		plan.bsv20.length > 0 ||
+		plan.bsv21.length > 0
+	)
+}
+
+export function describePlan(plan: SweepPlan): string[] {
+	const parts: string[] = []
+	if (plan.bsv.count)
+		parts.push(`${plan.bsv.sats} sats (${plan.bsv.count} UTXOs)`)
+	if (plan.ordinals.count) {
+		const listed = plan.ordinals.listed
+			? `, ${plan.ordinals.listed} listed`
+			: ''
+		parts.push(`${plan.ordinals.count} ordinal(s)${listed}`)
+	}
+	if (plan.opns.count) {
+		const listed = plan.opns.listed ? `, ${plan.opns.listed} listed` : ''
+		parts.push(`${plan.opns.count} OpNS name(s)${listed}`)
+	}
+	for (const t of plan.bsv20) {
+		const listed = t.listed ? `, ${t.listed} listed` : ''
+		parts.push(`${t.amount} ${t.tick} (${t.count} UTXOs${listed})`)
+	}
+	for (const t of plan.bsv21) {
+		const listed = t.listed ? `, ${t.listed} listed` : ''
+		parts.push(
+			`${t.amount} ${t.symbol ?? t.tokenId.slice(0, 12)} (${t.count} UTXOs${listed})`,
+		)
+	}
+	return parts
+}

package/src/commands/sweep.ts

@@ -5,20 +5,37 @@
  */
 
 import {
+	SWEEP_BATCH_SIZE,
+	bsv21SweepBatches,
+	groupBsv20Tokens,
 	prepareSweepInputs,
 	scanAddress,
 	sweepBsv,
+	sweepBsv20,
 	sweepBsv21,
 	sweepOrdinals,
 } from '@1sat/actions'
 import { PrivateKey } from '@bsv/sdk'
 import { confirm, isCancel } from '@clack/prompts'
 import type { GlobalFlags } from '../args.js'
-import { extractFlag } from '../args.js'
+import { extractFlag, hasFlag } from '../args.js'
 import { loadContext } from '../context.js'
 import { printCommandHelp } from '../help.js'
 import { loadKey } from '../keys.js'
-import { fatal, formatLabel, formatValue, output } from '../output.js'
+import {
+	fatal,
+	formatLabel,
+	formatValue,
+	formatWarning,
+	output,
+} from '../output.js'
+import { type SweepClass, selectedSweepClasses } from './sweep-classes.js'
+import {
+	type SweepPlan,
+	buildSweepPlan,
+	describePlan,
+	planHasWork,
+} from './sweep-plan.js'
 
 export async function handleSweepCommand(
 	args: string[],
@@ -39,217 +56,306 @@ export async function handleSweepCommand(
 	}
 }
 
-async function sweepScan(args: string[], opts: GlobalFlags): Promise<void> {
+function loadSweepKey(args: string[]): { wif: string; address: string } {
 	const wif = extractFlag(args, '--wif')
-
 	if (!wif) fatal('Missing --wif <private-key>')
-
-	let address: string
 	try {
 		const pk = PrivateKey.fromWif(wif)
-		address = pk.toPublicKey().toAddress()
+		return { wif, address: pk.toPublicKey().toAddress() }
 	} catch {
 		fatal('Invalid WIF private key')
 	}
+}
 
-	const privateKey = await loadKey()
-	const { ctx, destroy } = await loadContext(privateKey, {
-		chain: opts.chain,
-	})
-
+function loadClasses(args: string[]): Set<SweepClass> {
 	try {
-		if (!ctx.services) {
-			fatal('Services required for sweep scan')
-		}
-
-		const result = await scanAddress(ctx.services, address)
+		return selectedSweepClasses(
+			extractFlag(args, '--only'),
+			extractFlag(args, '--skip'),
+		)
+	} catch (error) {
+		fatal(error instanceof Error ? error.message : String(error))
+	}
+}
 
-		if (opts.json) {
-			output(result, opts)
-			return
-		}
+function leftoverLines(plan: SweepPlan): string[] {
+	const lines: string[] = []
+	if (plan.leftover.locked)
+		lines.push(`${plan.leftover.locked} locked output(s) (not swept)`)
+	if (plan.leftover.run)
+		lines.push(`${plan.leftover.run} RUN token output(s) (not sweepable)`)
+	if (plan.leftover.inactiveBsv21)
+		lines.push(
+			`${plan.leftover.inactiveBsv21} BSV-21 UTXO(s) with no parseable amount`,
+		)
+	if (plan.leftover.unparsedBsv20)
+		lines.push(
+			`${plan.leftover.unparsedBsv20} BSV-20 UTXO(s) with no parseable tick/amt`,
+		)
+	return lines
+}
 
-		console.log(`\n  Scan results for ${formatValue(address)}:\n`)
+function printInventory(
+	address: string,
+	plan: SweepPlan,
+	opts: GlobalFlags,
+	mode: 'scan' | 'dry-run',
+): void {
+	if (opts.json) {
+		output(
+			{
+				address,
+				mode,
+				classes: plan.classes,
+				wouldSweep: {
+					bsv: plan.bsv,
+					ordinals: plan.ordinals,
+					opns: plan.opns,
+					bsv20: plan.bsv20,
+					bsv21: plan.bsv21,
+				},
+				leftover: plan.leftover,
+			},
+			opts,
+		)
+		return
+	}
 
-		console.log(`  ${formatLabel('Funding UTXOs:')} ${result.funding.length}`)
-		if (result.funding.length > 0) {
-			console.log(
-				`  ${formatLabel('Total funding:')} ${formatValue(result.totalFundingSats)} satoshis`,
-			)
-			for (const f of result.funding) {
-				console.log(
-					`    ${formatValue(f.outpoint)}  ${formatLabel(`${f.satoshis ?? 0} sats`)}`,
-				)
-			}
-		}
+	const title = mode === 'dry-run' ? 'Dry run' : 'Scan'
+	console.log(`\n  ${title} for ${formatValue(address)}\n`)
+	console.log(
+		`  ${formatLabel('Classes:')} ${formatValue(plan.classes.join(', ') || '(none)')}`,
+	)
 
+	console.log(`\n  ${formatLabel('Funding UTXOs:')} ${plan.bsv.count}`)
+	if (plan.bsv.count > 0) {
 		console.log(
-			`\n  ${formatLabel('Ordinal UTXOs:')} ${result.ordinals.length}`,
+			`  ${formatLabel('Total funding:')} ${formatValue(plan.bsv.sats)} satoshis`,
 		)
-		if (result.ordinals.length > 0) {
-			for (const o of result.ordinals) {
-				console.log(`    ${formatValue(o.outpoint)}`)
-			}
-		}
+	}
+
+	console.log(`\n  ${formatLabel('Ordinal UTXOs:')} ${plan.ordinals.count}`)
+	if (plan.ordinals.listed)
+		console.log(`  ${formatLabel('Listed:')} ${plan.ordinals.listed}`)
 
+	console.log(`\n  ${formatLabel('OpNS names:')} ${plan.opns.count}`)
+	if (plan.opns.listed)
+		console.log(`  ${formatLabel('Listed:')} ${plan.opns.listed}`)
+
+	console.log(`\n  ${formatLabel('BSV-20:')} ${plan.bsv20.length} ticker(s)`)
+	for (const t of plan.bsv20) {
+		const listed = t.listed ? `  ${formatLabel(`listed ${t.listed}`)}` : ''
 		console.log(
-			`\n  ${formatLabel('BSV-21 Tokens:')} ${result.bsv21Tokens.length}`,
+			`    ${formatValue(t.tick)}  ${formatLabel('amount:')} ${formatValue(t.amount)}  ${formatLabel('UTXOs:')} ${t.count}${listed}`,
 		)
-		if (result.bsv21Tokens.length > 0) {
-			for (const t of result.bsv21Tokens) {
-				console.log(
-					`    ${formatValue(t.symbol ?? t.tokenId.slice(0, 12))}  ${formatLabel('amount:')} ${formatValue(t.totalAmount.toString())}  ${formatLabel('UTXOs:')} ${t.outputs.length}  ${formatLabel('dec:')} ${t.decimals}`,
-				)
-			}
-		}
+	}
 
-		console.log(`\n  ${formatLabel('RUN Tokens:')} ${result.run.length}`)
-		if (result.run.length > 0) {
-			const runSats = result.run.reduce((sum, r) => sum + (r.satoshis ?? 0), 0)
-			console.log(
-				`  ${formatLabel('Total locked:')} ${formatValue(runSats)} satoshis (not sweepable)`,
-			)
-			for (const r of result.run) {
-				console.log(
-					`    ${formatValue(r.outpoint)}  ${formatLabel(`${r.satoshis ?? 0} sats`)}`,
-				)
-			}
-		}
+	console.log(`\n  ${formatLabel('BSV-21:')} ${plan.bsv21.length} token(s)`)
+	for (const t of plan.bsv21) {
+		const listed = t.listed ? `  ${formatLabel(`listed ${t.listed}`)}` : ''
+		console.log(
+			`    ${formatValue(t.symbol ?? t.tokenId.slice(0, 12))}  ${formatLabel('amount:')} ${formatValue(t.amount)}  ${formatLabel('UTXOs:')} ${t.count}${listed}`,
+		)
+	}
 
-		const total =
-			result.funding.length +
-			result.ordinals.length +
-			result.bsv21Tokens.reduce((n, t) => n + t.outputs.length, 0)
-		console.log(`\n  ${total} sweepable UTXO(s) found.`)
-		if (result.run.length > 0) {
-			console.log(`  ${result.run.length} RUN token output(s) excluded.`)
-		}
-	} finally {
-		await destroy()
+	const leftover = leftoverLines(plan)
+	if (leftover.length) {
+		console.log(`\n  ${formatLabel('Leftover:')}`)
+		for (const line of leftover) console.log(`    ${formatWarning(line)}`)
 	}
+
+	const transferable =
+		plan.bsv.count +
+		plan.ordinals.count +
+		plan.opns.count +
+		plan.bsv20.reduce((n, t) => n + t.count, 0) +
+		plan.bsv21.reduce((n, t) => n + t.count, 0)
+	console.log(`\n  ${transferable} transferable UTXO(s) in selected classes.`)
 }
 
-async function sweepImport(args: string[], opts: GlobalFlags): Promise<void> {
-	const wif = extractFlag(args, '--wif')
+async function sweepScan(args: string[], opts: GlobalFlags): Promise<void> {
+	const { address } = loadSweepKey(args)
+	const classes = loadClasses(args)
 
-	if (!wif) fatal('Missing --wif <private-key>')
+	const privateKey = await loadKey()
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
 
-	let address: string
-	let sweepKey: PrivateKey
 	try {
-		sweepKey = PrivateKey.fromWif(wif)
-		address = sweepKey.toPublicKey().toAddress()
-	} catch {
-		fatal('Invalid WIF private key')
+		if (!ctx.services) fatal('Services required for sweep scan')
+		const scan = await scanAddress(ctx.services, address)
+		printInventory(address, buildSweepPlan(scan, classes), opts, 'scan')
+	} finally {
+		await destroy()
 	}
+}
+
+async function sweepImport(args: string[], opts: GlobalFlags): Promise<void> {
+	const { wif, address } = loadSweepKey(args)
+	const classes = loadClasses(args)
+	const dryRun = hasFlag(args, '--dry-run')
+	const sweepKey = PrivateKey.fromWif(wif)
 
 	const privateKey = await loadKey()
 	const { ctx, destroy } = await loadContext(privateKey, {
 		chain: opts.chain,
 	})
+	let failed = false
 
 	try {
-		if (!ctx.services) {
-			fatal('Services required for sweep import')
-		}
+		if (!ctx.services) fatal('Services required for sweep import')
 
 		const scan = await scanAddress(ctx.services, address)
+		const plan = buildSweepPlan(scan, classes)
 
-		const hasFunding = scan.funding.length > 0
-		const hasOrdinals = scan.ordinals.length > 0
-		const hasTokens = scan.bsv21Tokens.some(
-			(t) => t.isActive && t.outputs.length > 0,
-		)
-
-		if (!hasFunding && !hasOrdinals && !hasTokens) {
-			if (scan.run.length > 0) {
-				fatal(
-					`No sweepable UTXOs found at ${address} (${scan.run.length} RUN token output(s) excluded)`,
-				)
-			}
-			fatal(`No UTXOs found at ${address}`)
+		if (dryRun) {
+			printInventory(address, plan, opts, 'dry-run')
+			return
 		}
 
-		const parts: string[] = []
-		if (hasFunding)
-			parts.push(`${scan.totalFundingSats} sats (${scan.funding.length} UTXOs)`)
-		if (hasOrdinals) parts.push(`${scan.ordinals.length} ordinal(s)`)
-		if (hasTokens) {
-			for (const t of scan.bsv21Tokens) {
-				if (t.isActive && t.outputs.length > 0) {
-					parts.push(
-						`${t.totalAmount} ${t.symbol ?? t.tokenId.slice(0, 12)} token(s)`,
-					)
-				}
-			}
-		}
-		if (scan.run.length > 0) {
-			parts.push(`${scan.run.length} RUN token output(s) excluded`)
+		if (!planHasWork(plan)) {
+			const leftover = leftoverLines(plan)
+			const extra = leftover.length ? ` (${leftover.join('; ')})` : ''
+			fatal(`No transferable UTXOs found at ${address}${extra}`)
 		}
 
+		const parts = describePlan(plan)
+		for (const line of leftoverLines(plan)) parts.push(line)
+
 		if (!opts.yes) {
 			const ok = await confirm({
 				message: `Sweep ${parts.join(', ')} from ${address}?`,
 			})
-			if (isCancel(ok) || !ok) {
-				fatal('Sweep cancelled.')
-			}
+			if (isCancel(ok) || !ok) fatal('Sweep cancelled.')
 		}
 
 		const txids: string[] = []
-
-		// Sweep BSV funding UTXOs
-		if (hasFunding) {
-			const inputs = await prepareSweepInputs(ctx, scan.funding)
-			const keys = inputs.map(() => sweepKey)
-			const result = await sweepBsv.execute(ctx, { inputs, keys })
-			if (result.error) {
-				fatal(`BSV sweep failed: ${result.error}`)
+		const errors: string[] = []
+
+		const run = async (
+			label: string,
+			fn: () => Promise<{ txid?: string; error?: string }>,
+		): Promise<boolean> => {
+			try {
+				const result = await fn()
+				if (result.error) {
+					errors.push(`${label}: ${result.error}`)
+					return false
+				}
+				if (result.txid) txids.push(result.txid)
+				return true
+			} catch (error) {
+				errors.push(
+					`${label}: ${error instanceof Error ? error.message : String(error)}`,
+				)
+				return false
 			}
-			if (result.txid) txids.push(result.txid)
 		}
 
-		// Sweep ordinals
-		if (hasOrdinals) {
-			const inputs = await prepareSweepInputs(ctx, scan.ordinals)
-			const keys = inputs.map(() => sweepKey)
-			const result = await sweepOrdinals.execute(ctx, { inputs, keys })
-			if (result.error) {
-				fatal(`Ordinals sweep failed: ${result.error}`)
+		const keysFor = (inputs: { outpoint: string }[]) =>
+			inputs.map(() => sweepKey)
+
+		const runOrdinalBatches = async (
+			label: string,
+			outputs: typeof scan.ordinals,
+		): Promise<void> => {
+			for (
+				let offset = 0;
+				offset < outputs.length;
+				offset += SWEEP_BATCH_SIZE
+			) {
+				const batch = outputs.slice(offset, offset + SWEEP_BATCH_SIZE)
+				const ok = await run(
+					outputs.length <= SWEEP_BATCH_SIZE
+						? label
+						: `${label} (${offset + 1}–${offset + batch.length} of ${outputs.length})`,
+					async () => {
+						const inputs = await prepareSweepInputs(ctx, batch)
+						return sweepOrdinals.execute(ctx, {
+							inputs,
+							keys: keysFor(inputs),
+						})
+					},
+				)
+				if (!ok) break
 			}
-			if (result.txid) txids.push(result.txid)
 		}
 
-		// Sweep BSV-21 tokens (one sweep per active tokenId)
-		if (hasTokens) {
-			for (const token of scan.bsv21Tokens) {
-				if (!token.isActive || token.outputs.length === 0) continue
+		if (plan.bsv.count) {
+			await run('BSV', async () => {
+				const inputs = await prepareSweepInputs(ctx, scan.funding)
+				return sweepBsv.execute(ctx, {
+					inputs,
+					keys: keysFor(inputs),
+				})
+			})
+		}
 
-				const base = await prepareSweepInputs(ctx, token.outputs)
-				const inputs = base.map((b) => ({
-					...b,
-					tokenId: token.tokenId,
-					amount: token.amounts.get(b.outpoint) ?? '0',
-				}))
-				const keys = inputs.map(() => sweepKey)
+		if (plan.ordinals.count) {
+			await runOrdinalBatches('Ordinals', scan.ordinals)
+		}
 
-				const result = await sweepBsv21.execute(ctx, { inputs, keys })
-				if (result.error) {
-					fatal(
-						`Token sweep failed (${token.symbol ?? token.tokenId.slice(0, 12)}): ${result.error}`,
-					)
+		if (plan.opns.count) {
+			await runOrdinalBatches('OpNS', scan.opnsNames)
+		}
+
+		if (plan.bsv20.length) {
+			const grouped = groupBsv20Tokens(scan.bsv20Tokens)
+			for (const token of grouped) {
+				await run(`BSV-20 ${token.tick}`, async () => {
+					const base = await prepareSweepInputs(ctx, token.outputs)
+					const inputs = base.map((b) => ({
+						...b,
+						tick: token.tick,
+						amount: token.amounts.get(b.outpoint) ?? '0',
+					}))
+					return sweepBsv20.execute(ctx, {
+						inputs,
+						keys: inputs.map(() => sweepKey),
+					})
+				})
+			}
+		}
+
+		if (plan.bsv21.length) {
+			for (const token of scan.bsv21Tokens) {
+				if (token.outputs.length === 0) continue
+				const name = token.symbol ?? token.tokenId.slice(0, 12)
+				for (const batch of bsv21SweepBatches(token.outputs)) {
+					await run(`BSV-21 ${name}`, async () => {
+						const base = await prepareSweepInputs(ctx, batch)
+						const inputs = base.map((b) => ({
+							...b,
+							tokenId: token.tokenId,
+							amount: token.amounts.get(b.outpoint) ?? '0',
+						}))
+						return sweepBsv21.execute(ctx, {
+							inputs,
+							keys: inputs.map(() => sweepKey),
+						})
+					})
 				}
-				if (result.txid) txids.push(result.txid)
 			}
 		}
 
-		output(
-			opts.json
-				? { txids, swept: parts }
-				: `Sweep complete. ${txids.length} transaction(s): ${txids.join(', ')}`,
-			opts,
-		)
+		if (opts.json) {
+			output({ txids, errors, swept: parts }, opts)
+		} else if (errors.length) {
+			console.log(
+				`Sweep finished with errors. ${txids.length} transaction(s): ${txids.join(', ') || '(none)'}`,
+			)
+			for (const err of errors) console.error(formatWarning(err))
+		} else {
+			output(
+				`Sweep complete. ${txids.length} transaction(s): ${txids.join(', ')}`,
+				opts,
+			)
+		}
+
+		if (errors.length) failed = true
 	} finally {
 		await destroy()
 	}
+	if (failed) process.exit(1)
 }

package/src/help.ts

@@ -698,13 +698,42 @@ export const COMMANDS: CommandSpec[] = [
 			{
 				name: 'scan',
 				description:
-					'Scan an address for sweepable UTXOs (BSV, ordinals, BSV21)',
-				args: [{ flag: '--wif', values: '<key>', required: true }],
+					'Show every UTXO class at an address (BSV, ordinals, OpNS, BSV-20, BSV-21, leftover locks/RUN)',
+				args: [
+					{ flag: '--wif', values: '<key>', required: true },
+					{
+						flag: '--only',
+						values: '<bsv,ordinals,opns,bsv20,bsv21>',
+						description: 'Limit the report to these classes',
+					},
+					{
+						flag: '--skip',
+						values: '<class,...>',
+						description: 'Omit classes from the report',
+					},
+				],
 			},
 			{
 				name: 'import',
-				description: 'Sweep UTXOs from a WIF into the wallet',
-				args: [{ flag: '--wif', values: '<key>', required: true }],
+				description:
+					'Sweep transferable UTXOs from a WIF into the wallet. Default is all classes we can move to BRC-100 (including listed OrdLocks). Locks and RUN stay.',
+				args: [
+					{ flag: '--wif', values: '<key>', required: true },
+					{
+						flag: '--only',
+						values: '<bsv,ordinals,opns,bsv20,bsv21>',
+						description: 'Sweep only these classes',
+					},
+					{
+						flag: '--skip',
+						values: '<class,...>',
+						description: 'Skip these classes',
+					},
+					{
+						flag: '--dry-run',
+						description: 'Print the plan and do not broadcast',
+					},
+				],
 			},
 		],
 	},