feat(btc|examples): add needPaymaster option in the sendRgbppUtxos() API

.changeset/warm-tomatoes-worry.md

@@ -0,0 +1,5 @@
+---
+"@rgbpp-sdk/btc": minor
+---
+
+Add "needPaymaster" option to the sendRgbppUtxos() API to allow manually specifying whether a paymaster output is required

examples/rgbpp/spore/4-transfer-spore.ts

@@ -27,13 +27,14 @@ const transferSpore = async ({ sporeRgbppLockArgs, toBtcAddress, sporeTypeArgs }
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '4-transfer-spore');
 
-  const { commitment, ckbRawTx } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, needPaymasterCell } = ckbVirtualTxResult;
 
   // Send BTC tx
   const psbt = await sendRgbppUtxos({
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [toBtcAddress],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/spore/5-leap-spore-to-ckb.ts

@@ -28,13 +28,14 @@ const leapSporeFromBtcToCkb = async ({ sporeRgbppLockArgs, toCkbAddress, sporeTy
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '5-leap-spore-to-ckb');
 
-  const { commitment, ckbRawTx } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, needPaymasterCell } = ckbVirtualTxResult;
 
   // Send BTC tx
   const psbt = await sendRgbppUtxos({
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [btcAddress!],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/spore/launch/2-create-cluster.ts

@@ -23,7 +23,7 @@ const createCluster = async ({ ownerRgbppLockArgs }: { ownerRgbppLockArgs: strin
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '2-create-cluster');
 
-  const { commitment, ckbRawTx, clusterId } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, clusterId, needPaymasterCell } = ckbVirtualTxResult;
 
   console.log('clusterId: ', clusterId);
 
@@ -32,6 +32,7 @@ const createCluster = async ({ ownerRgbppLockArgs }: { ownerRgbppLockArgs: strin
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [btcAddress!],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/spore/launch/3-create-spores.ts

@@ -42,7 +42,7 @@ const createSpores = async ({ clusterRgbppLockArgs, receivers }: SporeCreatePara
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '3-create-spores');
 
-  const { commitment, ckbRawTx, sumInputsCapacity, clusterCell } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, sumInputsCapacity, clusterCell, needPaymasterCell } = ckbVirtualTxResult;
 
   // Send BTC tx
   // The first btc address is the owner of the cluster cell and the rest btc addresses are spore receivers
@@ -51,6 +51,7 @@ const createSpores = async ({ clusterRgbppLockArgs, receivers }: SporeCreatePara
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: btcTos,
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/spore/local/4-transfer-spore.ts

@@ -39,7 +39,7 @@ const transferSpore = async ({ sporeRgbppLockArgs, toBtcAddress, sporeTypeArgs }
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '4-transfer-spore-local');
 
-  const { commitment, ckbRawTx, sporeCell } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, sporeCell, needPaymasterCell } = ckbVirtualTxResult;
 
   // console.log(JSON.stringify(ckbRawTx))
 
@@ -48,6 +48,7 @@ const transferSpore = async ({ sporeRgbppLockArgs, toBtcAddress, sporeTypeArgs }
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [toBtcAddress],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/spore/local/5-leap-spore-to-ckb.ts

@@ -39,7 +39,7 @@ const leapSpore = async ({ sporeRgbppLockArgs, toCkbAddress, sporeTypeArgs }: Sp
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '5-leap-spore-to-ckb-local');
 
-  const { commitment, ckbRawTx, sporeCell } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, sporeCell, needPaymasterCell } = ckbVirtualTxResult;
 
   // console.log(JSON.stringify(ckbRawTx))
 
@@ -48,6 +48,7 @@ const leapSpore = async ({ sporeRgbppLockArgs, toCkbAddress, sporeTypeArgs }: Sp
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [btcAddress!],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/tsconfig.json

@@ -21,6 +21,6 @@
     "skipLibCheck": true,
     "strict": true
   },
-  "include": ["queue/**/*.ts", "xudt/**/*.ts"],
+  "include": ["spore", "xudt", "shared"],
   "exclude": ["node_modules"]
 }

examples/rgbpp/xudt/launch/2-launch-rgbpp.ts

@@ -28,7 +28,7 @@ const launchRgppAsset = async ({ ownerRgbppLockArgs, launchAmount, rgbppTokenInf
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '2-launch-rgbpp');
 
-  const { commitment, ckbRawTx } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, needPaymasterCell } = ckbVirtualTxResult;
 
   console.log('RGB++ Asset type script args: ', ckbRawTx.outputs[0].type?.args);
 
@@ -37,6 +37,7 @@ const launchRgppAsset = async ({ ownerRgbppLockArgs, launchAmount, rgbppTokenInf
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [btcAddress!],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

examples/rgbpp/xudt/launch/3-distribute-rgbpp.ts

@@ -47,7 +47,7 @@ const distributeRgbppAssetOnBtc = async ({ rgbppLockArgsList, receivers, xudtTyp
   // Save ckbVirtualTxResult
   saveCkbVirtualTxResult(ckbVirtualTxResult, '3-distribute-rgbpp');
 
-  const { commitment, ckbRawTx, sumInputsCapacity, rgbppChangeOutIndex } = ckbVirtualTxResult;
+  const { commitment, ckbRawTx, sumInputsCapacity, rgbppChangeOutIndex, needPaymasterCell } = ckbVirtualTxResult;
 
   // The first output utxo is OP_RETURN
   // Rgbpp change utxo position depends on the number of distributions, if 50 addresses are distributed, then the change utxo position is 51
@@ -58,6 +58,7 @@ const distributeRgbppAssetOnBtc = async ({ rgbppLockArgsList, receivers, xudtTyp
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: receivers.map((receiver) => receiver.toBtcAddress),
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,

packages/btc/src/api/sendRgbppUtxos.ts

@@ -15,6 +15,7 @@ export interface SendRgbppUtxosProps {
   commitment: string;
   tos?: string[];
   paymaster?: TxAddressOutput;
+  needPaymaster?: boolean;
 
   ckbCollector: Collector;
   rgbppMinUtxoSatoshi?: number;
@@ -174,8 +175,14 @@ async function getMergedBtcOutputs(btcOutputs: InitOutput[], props: SendRgbppUtx
 
   // Add paymaster output, only if paymaster address exists and needed
   const paymaster = defaultPaymaster ?? props.paymaster;
-  const isCkbTxCapacitySufficient = await checkCkbTxInputsCapacitySufficient(props.ckbVirtualTx, props.ckbCollector);
-  if (paymaster && !isCkbTxCapacitySufficient) {
+  const isNeedPaymasterOutput = await (async () => {
+    if (props.needPaymaster !== undefined) {
+      return props.needPaymaster;
+    }
+    const isInputsSufficient = await checkCkbTxInputsCapacitySufficient(props.ckbVirtualTx, props.ckbCollector);
+    return !isInputsSufficient;
+  })();
+  if (paymaster && isNeedPaymasterOutput) {
     merged.push({
       ...paymaster,
       fixed: true,