feat(rgbpp): support for batch transferring of RGBPP XUDT assets

.changeset/twenty-jeans-warn.md

@@ -0,0 +1,8 @@
+---
+'rgbpp': minor
+---
+
+Support for batch transferring of RGBPP XUDT assets
+
+- Add `buildRgbppTransferAllTxs()` API to generate one or more BTC/CKB transaction groups for transferring the entire amount of a specific type of RGBPP XUDT asset from one or more BTC addresses to a recipient
+- Add `sendRgbppTxGroups()` API for sending BTC/CKB transaction groups to the `BtcAssetsApi`

.github/workflows/test.yaml

@@ -52,6 +52,8 @@ jobs:
       - name: Run tests for packages
         run: pnpm run test:packages
         env:
+          VITE_CKB_NODE_URL: https://testnet.ckb.dev/rpc
+          VITE_CKB_INDEXER_URL: https://testnet.ckb.dev/indexer
           VITE_BTC_SERVICE_URL: https://btc-assets-api.testnet.mibao.pro
           VITE_BTC_SERVICE_TOKEN: ${{ secrets.TESTNET_SERVICE_TOKEN }}
           VITE_BTC_SERVICE_ORIGIN: https://btc-assets-api.testnet.mibao.pro

package.json

@@ -31,7 +31,7 @@
     "tsx": "4.16.3",
     "tsup": "^8.1.0",
     "typescript": "^5.4.3",
-    "vitest": "1.6.0"
+    "vitest": "2.0.5"
   },
   "lint-staged": {
     "{packages,apps,examples,tests}/**/*.{js,jsx,ts,tsx}": [

packages/rgbpp/.env.example

@@ -0,0 +1,11 @@
+# Network
+VITE_IS_MAINNET=false
+
+# CKB
+VITE_CKB_NODE_URL=https://testnet.ckb.dev/rpc
+VITE_CKB_INDEXER_URL=https://testnet.ckb.dev/indexer
+
+# BTC
+VITE_BTC_SERVICE_URL=https://btc-assets-api.testnet.mibao.pro
+VITE_BTC_SERVICE_TOKEN=
+VITE_BTC_SERVICE_ORIGIN=

packages/rgbpp/README.md

@@ -16,7 +16,7 @@ $ pnpm add rgbpp
 
 ## Transfer RGB++ Assets on BTC
 
-The function `buildRgbppTransferTx` will generate CKB virtual transaction and related BTC transaction with the commitment for the RGB++ assets transfer on BTC. 
+The function `buildRgbppTransferTx` will generate a CKB virtual transaction and a related BTC transaction with the commitment for the RGB++ assets transfer on BTC. 
 
 The `btcPsbtHex` can be used to construct bitcoin PSBT to sign and send BTC transaction with BTC wallet, and then the BTC transaction id and `ckbVirtualTxResult` will be used to post to RGB++ Queue Service to complete the isomorphic CKB transaction.
 
@@ -39,7 +39,7 @@ const { ckbVirtualTxResult, btcPsbtHex } = await buildRgbppTransferTx({
   isMainnet,
 });
 
-// Construct SPBT with btcPsbtHex to sign and send BTC transaction with the BTC key pair
+// Construct PSBT with btcPsbtHex to sign and send BTC transaction with the BTC key pair
 const psbt = bitcoin.Psbt.fromHex(btcPsbtHex);
 psbt.signAllInputs(btcKeyPair);
 psbt.finalizeAllInputs();
@@ -49,4 +49,49 @@ const { txid: btcTxId } = await btcService.sendBtcTransaction(btcTx.toHex());
 
 // Post the BTC txId and ckbVirtualTxResult to the RGB++ Queue Service
 await btcService.sendRgbppCkbTransaction({ btc_txid: btcTxId, ckb_virtual_result: ckbVirtualTxResult });
-```
+```
+
+## Transfer all balance of an RGB++ Asset on BTC
+
+Similar to using the `buildRgbppTransferTx` function, the function `buildRgbppTransferAllTxs` will generate a list of RGB++ transaction groups (a transaction group includes a CKB virtual transaction and a BTC isomorphic transaction).
+
+You should sign all the PSBTs in the `transactions` and send all the BTC transactions, and then post all the BTC txIds and ckbVirtualTxResults to the RGB++ Queue Service. You can also review the transfer details in the `summary` object.
+
+```TypeScript
+const { transactions, summary } = await buildRgbppTransferAllTxs({
+  ckb: {
+    xudtTypeArgs,
+    collector,
+  },
+  btc: {
+    assetAddresses,
+    fromAddress,
+    toAddress,
+    dataSource,
+    feeRate,
+    pubkeyMap,
+  },
+  isMainnet,
+});
+
+// Sign BTC PSBTs with all the related BTC key pairs, and convert them to BTC transactions
+const signedGroups: RgbppTxGroup[] = transactions.map((group) => {
+  const psbt = bitcoin.Psbt.fromHex(group.btc.psbtHex);
+  signPsbt(psbt, keyPair);
+  psbt.finalizeAllInputs();
+
+  return {
+    ckbVirtualTxResult: JSON.stringify(group.ckb.virtualTxResult),
+    btcTxHex: psbt.extractTransaction().toHex(),
+  };
+});
+
+// Post the transaction groups to the RGB++ Queue Service
+const sentResult = await sendRgbppTxGroups({
+  txGroups: signedGroups,
+  btcService: btcSource.service,
+});
+
+// Review the summary of the transfer
+console.log(summary);
+```

packages/rgbpp/package.json

@@ -2,6 +2,7 @@
   "name": "rgbpp",
   "version": "0.5.0",
   "scripts": {
+    "test": "vitest",
     "build": "tsup",
     "lint": "tsc && eslint --ext .ts src/* && prettier --check 'src/*.ts'",
     "lint:fix": "tsc && eslint --fix --ext .ts src/* && prettier --write 'src/*.ts'"
@@ -58,12 +59,19 @@
     "dist"
   ],
   "dependencies": {
+    "@ckb-lumos/base": "^0.22.2",
+    "@ckb-lumos/codec": "^0.22.2",
+    "@nervosnetwork/ckb-sdk-utils": "0.109.2",
     "@rgbpp-sdk/btc": "workspace:*",
     "@rgbpp-sdk/ckb": "workspace:*",
-    "@rgbpp-sdk/service": "workspace:*",
-    "@nervosnetwork/ckb-sdk-utils": "0.109.2"
+    "@rgbpp-sdk/service": "workspace:*"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.3.1",
+    "lodash": "^4.17.21",
+    "zod": "^3.23.8"
   }
 }

packages/rgbpp/src/index.ts

@@ -58,5 +58,13 @@ export type { SendBtcProps, SendUtxosProps, SendRgbppUtxosProps } from '@rgbpp-s
 /**
  * RGB++
  */
-export { buildRgbppTransferTx } from './rgbpp/xudt';
-export type { RgbppTransferTxParams, RgbppTransferTxResult } from './rgbpp/types';
+export type {
+  RgbppTransferTxParams,
+  RgbppTransferTxResult,
+  RgbppTransferAllTxsParams,
+  RgbppTransferAllTxsResult,
+} from './rgbpp/types/xudt';
+export { RgbppError, RgbppErrorCodes } from './rgbpp/error';
+export { buildRgbppTransferTx } from './rgbpp/xudt/btc-transfer';
+export { buildRgbppTransferAllTxs } from './rgbpp/xudt/btc-transfer-all';
+export { sendRgbppTxGroups } from './rgbpp/utils/transaction';

packages/rgbpp/src/rgbpp/error.ts

@@ -0,0 +1,27 @@
+export enum RgbppErrorCodes {
+  UNKNOWN,
+
+  CANNOT_DECODE_UTXO_ID = 20,
+  UNEXPECTED_CKB_VTX_OUTPUTS_LENGTH,
+}
+
+export const RgbppErrorMessages = {
+  [RgbppErrorCodes.UNKNOWN]: 'Unknown error',
+
+  [RgbppErrorCodes.CANNOT_DECODE_UTXO_ID]: 'Cannot decode UtxoId',
+  [RgbppErrorCodes.UNEXPECTED_CKB_VTX_OUTPUTS_LENGTH]: 'Unexpected length of the CkbVirtualTx outputs',
+};
+
+export class RgbppError extends Error {
+  public code = RgbppErrorCodes.UNKNOWN;
+  constructor(code: RgbppErrorCodes, message = RgbppErrorMessages[code] || 'Unknown error') {
+    super(message);
+    this.code = code;
+    Object.setPrototypeOf(this, RgbppError.prototype);
+  }
+
+  static withComment(code: RgbppErrorCodes, comment?: string): RgbppError {
+    const message: string | undefined = RgbppErrorMessages[code];
+    return new RgbppError(code, comment ? `${message}: ${comment}` : message);
+  }
+}

packages/rgbpp/src/rgbpp/summary/asset-summarizer.ts

@@ -0,0 +1,100 @@
+import { Cell } from '@ckb-lumos/base';
+import { Utxo } from '@rgbpp-sdk/btc';
+import { leToU128 } from '@rgbpp-sdk/ckb';
+import { encodeCellId } from '../utils/ckb';
+import { encodeUtxoId } from '../utils/btc';
+
+export interface AssetSummary {
+  amount: bigint;
+  utxos: number;
+  cells: number;
+}
+
+export interface AssetGroupSummary {
+  utxoId: string;
+  cellIds: string[];
+  assets: Record<string, AssetSummary>;
+}
+
+export interface TransactionGroupSummary {
+  utxos: number;
+  cells: number;
+  utxoIds: string[];
+  cellIds: string[];
+  assets: Record<string, AssetSummary>;
+}
+
+export class AssetSummarizer {
+  groups: AssetGroupSummary[] = [];
+
+  constructor() {}
+
+  addGroup(utxo: Utxo, cells: Cell[]): AssetGroupSummary {
+    const utxoId = encodeUtxoId(utxo.txid, utxo.vout);
+    const assets: Record<string, Omit<AssetSummary, 'xudtTypeArgs'>> = {};
+    const cellIds: string[] = [];
+
+    for (const cell of cells) {
+      cellIds.push(encodeCellId(cell.outPoint!.txHash, cell.outPoint!.index));
+      const xudtTypeArgs = cell.cellOutput.type?.args ?? 'empty';
+      const amount = leToU128(cell.data.substring(0, 34));
+      if (assets[xudtTypeArgs] === undefined) {
+        assets[xudtTypeArgs] = {
+          utxos: 1,
+          cells: 0,
+          amount: 0n,
+        };
+      }
+
+      assets[xudtTypeArgs]!.cells += 1;
+      assets[xudtTypeArgs]!.amount += amount;
+    }
+
+    const result: AssetGroupSummary = {
+      utxoId,
+      cellIds,
+      assets,
+    };
+
+    this.groups.push(result);
+    return result;
+  }
+
+  addGroups(groups: { utxo: Utxo; cells: Cell[] }[]): TransactionGroupSummary {
+    const groupResults = groups.map((group) => this.addGroup(group.utxo, group.cells));
+    return this.summarizeGroups(groupResults);
+  }
+
+  summarizeGroups(groups?: AssetGroupSummary[]): TransactionGroupSummary {
+    const targetGroups = groups ?? this.groups;
+    const utxoIds = targetGroups.map((summary) => summary.utxoId);
+    const cellIds = targetGroups.flatMap((summary) => summary.cellIds);
+    const assets = targetGroups.reduce(
+      (result, summary) => {
+        for (const xudtTypeArgs in summary.assets) {
+          if (result[xudtTypeArgs] === undefined) {
+            result[xudtTypeArgs] = {
+              utxos: 0,
+              cells: 0,
+              amount: 0n,
+            };
+          }
+
+          result[xudtTypeArgs]!.utxos += summary.assets[xudtTypeArgs]!.utxos;
+          result[xudtTypeArgs]!.cells += summary.assets[xudtTypeArgs]!.cells;
+          result[xudtTypeArgs]!.amount += summary.assets[xudtTypeArgs]!.amount;
+        }
+        return result;
+      },
+      {} as Record<string, Omit<AssetSummary, 'xudtTypeArgs'>>,
+    );
+
+    return {
+      utxos: utxoIds.length,
+      cells: cellIds.length,
+      utxoIds,
+      cellIds,
+      assets,
+    };
+  }
+}