feat: add UDT balance and transfer CLI commands (#447)

* feat: add UDT balance and transfer CLI commands

Add offckb udt-balance and udt-transfer commands leveraging the
CCC SDK. Supports both SUDT and xUDT via --kind.

- udt-balance: query UDT balance for an address
- udt-transfer: transfer UDT amount to an address with change output

Closes #445

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: reuse balance/transfer for UDT and add issue/destroy commands

- Reuse existing balance/transfer commands via --udt-type-args/--udt-kind flags
- Make balance default show CKB plus detected SUDT/xUDT balances
- Replace udt-balance/udt-transfer with udt issue/destroy subcommands
- Add detectUdtBalances, udtIssue, and udtDestroy to CKB SDK
- Update tests for the revised CLI

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: add changeset and fix formatting for UDT CLI refactor

- Add minor changeset for the new UDT issue/destroy commands and balance/transfer reuse.
- Apply prettier formatting to src/cmd/transfer.ts.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(udt): address PR review comments

- Use minimal cell capacity (capacity: 0) instead of hardcoded 61 CKB for UDT outputs
- Add missing cell deps in udtTransfer
- Reject full UDT destroy to avoid potential script rejection
- Add max input cell limit for udtDestroy
- Skip corrupted UDT cells in balance detection instead of failing
- Remove hard 500-cell cap on UDT balance scan (now 1000 with warning)
- Add input validation: amount, type args length, UDT kind enum
- Warn when --type-args is provided for SUDT issue
- Remove process.exit(0) from balance command
- Support filtering balance by --udt-kind alone
- Add CLI enum choices for --udt-kind and --kind
- Add SDK-level UDT tests and expand validator tests

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(udt): address code review comments from review squad

- Extract getUdtScriptInfo helper to unify SUDT/xUDT script/cellDeps handling
- Filter detectUdtBalances by UDT type script with prefix search instead of scanning all cells
- Add --no-udt flag and parallel CKB/UDT queries in balance command
- Restore process.exit(0) in balanceOf to prevent CLI hang
- Unify UDT kind CLI flag to --udt-kind across balance/transfer/udt commands
- Move UdtKind type to src/type/base.ts and reuse in validator
- Add u128 upper bound check to validateUdtAmount
- Add logTxSuccess helper to remove duplicated testnet/devnet success logging
- Fix ckb.udt.test.ts test title/content mismatch and cover SUDT type-args warning
- Update tests for renamed udtKind option and process.exit mocking

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: humble-little-bear

.changeset/tasty-walls-appear.md

@@ -0,0 +1,5 @@
+---
+"@offckb/cli": minor
+---
+
+Refactor UDT CLI support: reuse `balance` and `transfer` commands for CKB and UDT queries, and add `offckb udt issue` / `offckb udt destroy` subcommands.

src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { startNode, stopNode } from './cmd/node';
 import { accounts } from './cmd/accounts';
 import { clean } from './cmd/clean';
@@ -8,6 +8,7 @@ import { DepositOptions, deposit } from './cmd/deposit';
 import { DeployOptions, deploy } from './cmd/deploy';
 import { TransferOptions, transfer } from './cmd/transfer';
 import { BalanceOption, balanceOf } from './cmd/balance';
+import { udtIssue, udtDestroy, UdtIssueOption, UdtDestroyOption } from './cmd/udt';
 import { createScriptProject, CreateScriptProjectOptions } from './cmd/create';
 import { Config, ConfigItem } from './cmd/config';
 import { devnetConfig } from './cmd/devnet-config';
@@ -137,13 +138,15 @@ program
   });
 
 program
-  .command('transfer [toAddress] [amountInCKB]')
-  .description('Transfer CKB tokens to address, only devnet and testnet')
+  .command('transfer [toAddress] [amount]')
+  .description('Transfer CKB or UDT tokens to address, only devnet and testnet')
   .option('--network <network>', 'Specify the network to transfer to', 'devnet')
-  .option('--privkey <privkey>', 'Specify the private key to transfer CKB')
+  .option('--privkey <privkey>', 'Specify the private key to transfer')
+  .addOption(new Option('--udt-kind <kind>', 'Specify the UDT kind').choices(['sudt', 'xudt']).default('sudt'))
+  .option('--udt-type-args <typeArgs>', 'Specify the UDT type script args to transfer UDT')
   .option('-r, --proxy-rpc', 'Use Proxy RPC to connect to blockchain')
-  .action(async (toAddress: string, amountInCKB: string, options: TransferOptions) => {
-    return transfer(toAddress, amountInCKB, options);
+  .action(async (toAddress: string, amount: string, options: TransferOptions) => {
+    return transfer(toAddress, amount, options);
   });
 
 program
@@ -158,12 +161,40 @@ program
 
 program
   .command('balance [toAddress]')
-  .description('Check account balance, only devnet and testnet')
+  .description('Check account balance (CKB + detected SUDT/xUDT), only devnet and testnet')
   .option('--network <network>', 'Specify the network to check', 'devnet')
+  .addOption(new Option('--udt-kind <kind>', 'Filter by UDT kind').choices(['sudt', 'xudt']))
+  .option('--udt-type-args <typeArgs>', 'Filter by UDT type script args')
+  .option('--no-udt', 'Skip UDT balance scan')
   .action(async (toAddress: string, options: BalanceOption) => {
     return balanceOf(toAddress, options);
   });
 
+const udtCommand = program.command('udt').description('UDT token commands');
+
+udtCommand
+  .command('issue <amount>')
+  .description('Issue new UDT tokens, only devnet and testnet')
+  .option('--network <network>', 'Specify the network', 'devnet')
+  .addOption(new Option('--udt-kind <kind>', 'Specify the UDT kind').choices(['sudt', 'xudt']).default('sudt'))
+  .option('--type-args <typeArgs>', 'Specify the UDT type script args (xudt only; defaults to signer lock hash)')
+  .option('--to <toAddress>', 'Specify the receiver address (defaults to signer)')
+  .option('--privkey <privkey>', 'Specify the private key to issue UDT')
+  .action(async (amount: string, options: UdtIssueOption) => {
+    return udtIssue(amount, options);
+  });
+
+udtCommand
+  .command('destroy <amount>')
+  .description('Destroy UDT tokens, only devnet and testnet')
+  .option('--network <network>', 'Specify the network', 'devnet')
+  .addOption(new Option('--udt-kind <kind>', 'Specify the UDT kind').choices(['sudt', 'xudt']).default('sudt'))
+  .requiredOption('--type-args <typeArgs>', 'Specify the UDT type script args')
+  .option('--privkey <privkey>', 'Specify the private key to destroy UDT')
+  .action(async (amount: string, options: UdtDestroyOption) => {
+    return udtDestroy(amount, options);
+  });
+
 program
   .command('debugger')
   .description('Port of the raw CKB Standalone Debugger')

src/cmd/balance.ts

@@ -1,17 +1,46 @@
-import { CKB } from '../sdk/ckb';
+import { CKB, UdtBalanceInfo } from '../sdk/ckb';
 import { validateNetworkOpt } from '../util/validator';
-import { NetworkOption, Network } from '../type/base';
+import { NetworkOption, Network, UdtKind } from '../type/base';
 import { logger } from '../util/logger';
 
-export interface BalanceOption extends NetworkOption {}
+export interface BalanceOption extends NetworkOption {
+  udtKind?: UdtKind;
+  udtTypeArgs?: string;
+  udt?: boolean;
+}
 
 export async function balanceOf(address: string, opt: BalanceOption = { network: Network.devnet }) {
   const network = opt.network;
   validateNetworkOpt(network);
 
   const ckb = new CKB({ network });
 
-  const balanceInCKB = await ckb.balance(address);
-  logger.info(`Balance: ${balanceInCKB} CKB`);
+  const [balanceInCKB, udtBalances] = await Promise.all([
+    ckb.balance(address),
+    opt.udt !== false ? ckb.detectUdtBalances(address) : Promise.resolve([]),
+  ]);
+  logger.info(`CKB: ${balanceInCKB}`);
+
+  const filtered = filterUdtBalances(udtBalances, opt);
+
+  if (filtered.length > 0) {
+    logger.info('UDT:');
+    for (const udt of filtered) {
+      logger.info(`  ${udt.kind} (args=${udt.args}): ${udt.balance}`);
+    }
+  }
+
   process.exit(0);
 }
+
+function filterUdtBalances(balances: UdtBalanceInfo[], opt: BalanceOption): UdtBalanceInfo[] {
+  if (!opt.udtKind && !opt.udtTypeArgs) {
+    return balances;
+  }
+
+  return balances.filter((udt) => {
+    const kindMatch = opt.udtKind ? udt.kind === opt.udtKind : true;
+    const argsMatch = opt.udtTypeArgs ? udt.args === opt.udtTypeArgs : true;
+    return kindMatch && argsMatch;
+  });
+}

src/cmd/transfer.ts

@@ -1,18 +1,15 @@
 import { CKB } from '../sdk/ckb';
-import { NetworkOption, Network } from '../type/base';
-import { buildTestnetTxLink } from '../util/link';
-import { validateNetworkOpt } from '../util/validator';
-import { logger } from '../util/logger';
+import { NetworkOption, Network, UdtKind } from '../type/base';
+import { logTxSuccess } from '../util/link';
+import { validateNetworkOpt, validateUdtKind, validateUdtTypeArgs } from '../util/validator';
 
 export interface TransferOptions extends NetworkOption {
   privkey?: string | null;
+  udtKind?: UdtKind;
+  udtTypeArgs?: string;
 }
 
-export async function transfer(
-  toAddress: string,
-  amountInCKB: string,
-  opt: TransferOptions = { network: Network.devnet },
-) {
+export async function transfer(toAddress: string, amount: string, opt: TransferOptions = { network: Network.devnet }) {
   const network = opt.network;
   validateNetworkOpt(network);
 
@@ -23,15 +20,27 @@ export async function transfer(
   const privateKey = opt.privkey;
   const ckb = new CKB({ network });
 
+  if (opt.udtTypeArgs) {
+    const kind = opt.udtKind ?? 'sudt';
+    validateUdtKind(kind);
+    const udtTypeArgs = validateUdtTypeArgs(kind, opt.udtTypeArgs);
+    const udtType = await ckb.buildUdtTypeScript(kind, udtTypeArgs);
+    const txHash = await ckb.udtTransfer({
+      toAddress,
+      amount,
+      privateKey,
+      udtType,
+      kind,
+    });
+
+    logTxSuccess(network, txHash, 'transfer UDT');
+    return;
+  }
+
   const txHash = await ckb.transfer({
     toAddress,
-    amountInCKB,
+    amountInCKB: amount,
     privateKey,
   });
-  if (network === 'testnet') {
-    logger.info(`Successfully transfer, check ${buildTestnetTxLink(txHash)} for details.`);
-    return;
-  }
-
-  logger.info('Successfully transfer, txHash:', txHash);
+  logTxSuccess(network, txHash, 'transfer');
 }

src/cmd/udt.ts

@@ -0,0 +1,64 @@
+import { CKB } from '../sdk/ckb';
+import { NetworkOption, Network, UdtKind } from '../type/base';
+import { logTxSuccess } from '../util/link';
+import { validateNetworkOpt, validateUdtKind, validateUdtTypeArgs } from '../util/validator';
+
+export interface UdtIssueOption extends NetworkOption {
+  udtKind: UdtKind;
+  typeArgs?: string;
+  to?: string;
+  privkey: string;
+}
+
+export interface UdtDestroyOption extends NetworkOption {
+  udtKind: UdtKind;
+  typeArgs: string;
+  privkey: string;
+}
+
+export async function udtIssue(
+  amount: string,
+  opt: UdtIssueOption = { network: Network.devnet, udtKind: 'sudt', privkey: '' },
+) {
+  const network = opt.network;
+  validateNetworkOpt(network);
+  validateUdtKind(opt.udtKind);
+
+  if (!opt.privkey) {
+    throw new Error('--privkey is required!');
+  }
+
+  const ckb = new CKB({ network });
+  const txHash = await ckb.udtIssue({
+    privateKey: opt.privkey,
+    kind: opt.udtKind,
+    amount,
+    typeArgs: opt.typeArgs ? validateUdtTypeArgs(opt.udtKind, opt.typeArgs) : undefined,
+    toAddress: opt.to,
+  });
+
+  logTxSuccess(network, txHash, 'issued UDT');
+}
+
+export async function udtDestroy(
+  amount: string,
+  opt: UdtDestroyOption = { network: Network.devnet, udtKind: 'sudt', typeArgs: '', privkey: '' },
+) {
+  const network = opt.network;
+  validateNetworkOpt(network);
+  validateUdtKind(opt.udtKind);
+
+  if (!opt.privkey) {
+    throw new Error('--privkey is required!');
+  }
+
+  const ckb = new CKB({ network });
+  const txHash = await ckb.udtDestroy({
+    privateKey: opt.privkey,
+    kind: opt.udtKind,
+    amount,
+    typeArgs: validateUdtTypeArgs(opt.udtKind, opt.typeArgs),
+  });
+
+  logTxSuccess(network, txHash, 'destroyed UDT');
+}