Merge pull request #217 from ckb-cell/release/0.3.0

Merge release/0.3.0 to main branch

Author: Flouse

README.md

@@ -66,6 +66,8 @@ This repository offers utilities for Bitcoin and RGB++ asset integration.
 ### How to get an access token of Bitcoin/RGB++ Assets Service?
 See [Generate a JSON Web Token (JWT) for Bitcoin/RGB++ Assets Service](./packages/service/README.md#get-an-access-token)
 
+### Where is the error code description for the RgbppLockScript?
+See [RGB++ Lock Script Error Codes](https://github.com/nervosnetwork/ckb-script-error-codes/blob/main/by-type-hash/bc6c568a1a0d0a09f6844dc9d74ddb4343c32143ff25f727c59edf4fb72d6936.md)
 
 ## License
 

examples/rgbpp/.env.example

@@ -16,6 +16,8 @@ CKB_INDEXER_URL=https://testnet.ckb.dev/indexer
 # BTC Variables
 
 # The BTC private key whose format is 32bytes hex string without 0x prefix
+# The Native Segwit P2WPKH address will be generated with the BTC private key
+# Read more about P2WPKH in BIP141: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#p2wpkh
 BTC_PRIVATE_KEY=private-key
 
 # The BTC assets api url which should be matched with IS_MAINNET

examples/rgbpp/README.md

@@ -3,8 +3,18 @@
 - xUDT directory: The examples for RGB++ UDT issuance, transfer, and leap
 - Spore directory: The examples for RGB++ Spore creation, transfer and leap
 
+> [!TIP]
+> All the parameters of the examples should be repalced with your own, including BTC private key, CKB private key, BTC Service origin, BTC Service token, BTC UTXO, xUDT type args, Spore type args, etc. Please confirm whether the parameters are correct according to the code comments
+
 ## How to Start
 
+### Install dependencies and build packages
+
+```
+pnpm install && pnpm build:packages
+```
+### Update .env
+
 Copy the `.env.example` file to `.env`:
 
 ```shell
@@ -31,6 +41,8 @@ CKB_INDEXER_URL=https://testnet.ckb.dev/indexer
 # BTC Variables
 
 # The BTC private key whose format is 32bytes hex string without 0x prefix
+# The Native Segwit P2WPKH address will be generated with the BTC private key
+# Read more about P2WPKH in BIP141: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#p2wpkh
 BTC_PRIVATE_KEY=private-key
 
 # The BTC assets api url which should be matched with IS_MAINNET
@@ -44,23 +56,36 @@ VITE_BTC_SERVICE_TOKEN=;
 VITE_BTC_SERVICE_ORIGIN=https://btc-test.app;
 ```
 
-
 ## RGB++ xUDT Examples
 
 ### RGB++ xUDT Launch on BTC
 
 #### 1. Prepare Launch
 
+> [!TIP]
+> Please make sure the CKB private key in the .env is correct
+
 ```shell
+# Create a CKB empty rgbpp lock cell to launch RGB++ xUDT assets later
 npx ts-node xudt/launch/1-prepare-launch.ts
 ```
 #### 2. Launch RGB++ xUDT on BTC
 
+> [!TIP]
+> Please make sure the `1-prepare-launch.ts` has been run and the corresponding CKB transaction has been committed
+
 ```shell
 npx ts-node xudt/launch/2-launch-rgbpp.ts
 ```
+
+When the command is executed successfully, the **RGB++ Asset type script args** will appear in the output log
+
 #### 3. Distribute RGB++ xUDT on BTC
 
+> [!TIP]
+> Please make sure the `2-launch-rgbpp.ts` has been run and the corresponding BTC and CKB transactions have been committed
+> The **RGB++ Asset type script args** in the above should be set to the `xudtTypeArgs`
+
 ```shell
 npx ts-node xudt/launch/3-distribute-rgbpp.ts
 ```
@@ -103,14 +128,26 @@ npx ts-node xudt/4-unlock-btc-time.ts
 
 #### 1. Create RGB++ Cluster Cell
 
+> [!TIP]
+> Please make sure all the variables in the .env are correct
+> The BTC UTXO of `1-prepare-cluster.ts` and `2-create-cluster.ts` should be same
+
 ```shell
+# Create a CKB empty rgbpp lock cell to create cluster later
 npx ts-node spore/launch/1-prepare-cluster.ts
 
+# Create a cluster cell with rgbpp lock
 npx ts-node spore/launch/2-create-cluster.ts
 ```
 
+When the commands are executed successfully, the **clusterId** and **cluster rgbpp lock args** will appear in the output log
+
 #### 2. Create RGB++ Spores with Cluster on BTC
 
+> [!TIP]
+> Please make sure the `2-create-cluster.ts` has been run and the corresponding BTC and CKB transactions have been committed
+> The **clusterId** in the above should be set to the `clusterId` and the **cluster rgbpp lock args** should be set to the `clusterRgbppLockArgs`
+
 ```shell
 npx ts-node spore/launch/3-create-spores.ts
 ```
@@ -147,6 +184,13 @@ npx ts-node spore/6-unlock-btc-time-cell.ts
 npx ts-node spore/7-leap-spore-to-btc.ts
 ```
 
+## FAQ
+
+If you have any questions, please refer to the FAQ first.
+
+See [RGBPP FAQ](https://github.com/ckb-cell/rgbpp-sdk/wiki/RGBPP--FAQ)
+
+
 ## What you must know about BTC transaction id
 
 **The BTC transaction id(hash) displayed on BTC explorer is different from the BTC transaction id(hash) in RGB++ lock args. They are in reverse byte order.**

examples/rgbpp/env.ts

@@ -1,4 +1,10 @@
-import { AddressPrefix, privateKeyToAddress } from '@nervosnetwork/ckb-sdk-utils';
+import {
+  blake160,
+  bytesToHex,
+  privateKeyToPublicKey,
+  scriptToAddress,
+  systemScripts,
+} from '@nervosnetwork/ckb-sdk-utils';
 import { DataSource, BtcAssetsApi } from 'rgbpp';
 import { ECPair, ECPairInterface, bitcoin, NetworkType } from 'rgbpp/btc';
 import dotenv from 'dotenv';
@@ -13,9 +19,11 @@ export const collector = new Collector({
   ckbIndexerUrl: process.env.CKB_INDEXER_URL!,
 });
 export const CKB_PRIVATE_KEY = process.env.CKB_SECP256K1_PRIVATE_KEY!;
-export const ckbAddress = privateKeyToAddress(CKB_PRIVATE_KEY, {
-  prefix: isMainnet ? AddressPrefix.Mainnet : AddressPrefix.Testnet,
-});
+const secp256k1Lock: CKBComponents.Script = {
+  ...systemScripts.SECP256K1_BLAKE160,
+  args: bytesToHex(blake160(privateKeyToPublicKey(CKB_PRIVATE_KEY))),
+};
+export const ckbAddress = scriptToAddress(secp256k1Lock, isMainnet);
 
 export const BTC_PRIVATE_KEY = process.env.BTC_PRIVATE_KEY!;
 export const BTC_SERVICE_URL = process.env.VITE_BTC_SERVICE_URL!;
@@ -24,6 +32,8 @@ export const BTC_SERVICE_ORIGIN = process.env.VITE_BTC_SERVICE_ORIGIN!;
 
 const network = isMainnet ? bitcoin.networks.bitcoin : bitcoin.networks.testnet;
 export const btcKeyPair: ECPairInterface = ECPair.fromPrivateKey(Buffer.from(BTC_PRIVATE_KEY, 'hex'), { network });
+// The Native Segwit P2WPKH address will be generated with the BTC private key
+// Read more about P2WPKH in BIP141: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#p2wpkh
 export const { address: btcAddress } = bitcoin.payments.p2wpkh({
   pubkey: btcKeyPair.publicKey,
   network,

examples/rgbpp/shared/utils.ts

@@ -5,6 +5,7 @@ import {
   SporeVirtualTxResult,
   SporeCreateVirtualTxResult,
   SporeTransferVirtualTxResult,
+  RgbppLaunchVirtualTxResult,
 } from 'rgbpp/ckb';
 
 /**
@@ -15,6 +16,7 @@ import {
 
 export type CkbVirtualTxResultType =
   | BaseCkbVirtualTxResult
+  | RgbppLaunchVirtualTxResult
   | SporeVirtualTxResult
   | SporeCreateVirtualTxResult
   | SporeTransferVirtualTxResult;

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,
@@ -68,10 +69,11 @@ const transferSpore = async ({ sporeRgbppLockArgs, toBtcAddress, sporeTypeArgs }
   }
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 // rgbppLockArgs: outIndexU32 + btcTxId
 transferSpore({
   sporeRgbppLockArgs: buildRgbppLockArgs(2, 'd5868dbde4be5e49876b496449df10150c356843afb6f94b08f8d81f394bb350'),
   toBtcAddress: 'tb1qhp9fh9qsfeyh0yhewgu27ndqhs5qlrqwau28m7',
+  // Please use your own RGB++ spore asset's sporeTypeArgs
   sporeTypeArgs: '0x42898ea77062256f46e8f1b861d526ae47810ecc51ab50477945d5fa90452706',
 });

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,
@@ -69,10 +70,11 @@ const leapSporeFromBtcToCkb = async ({ sporeRgbppLockArgs, toCkbAddress, sporeTy
   }
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 // rgbppLockArgs: outIndexU32 + btcTxId
 leapSporeFromBtcToCkb({
   sporeRgbppLockArgs: buildRgbppLockArgs(3, 'd8a31796fbd42c546f6b22014b9b82b16586ce1df81b0e7ca9a552cdc492a0af'),
   toCkbAddress: 'ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq0e4xk4rmg5jdkn8aams492a7jlg73ue0gc0ddfj',
+  // Please use your own RGB++ spore asset's sporeTypeArgs
   sporeTypeArgs: '0x42898ea77062256f46e8f1b861d526ae47810ecc51ab50477945d5fa90452706',
 });

examples/rgbpp/spore/7-leap-spore-to-btc.ts

@@ -40,9 +40,10 @@ const leapSporeFromCkbToBtc = async ({
   console.info(`RGB++ Spore has been jumped from CKB to BTC and tx hash is ${txHash}`);
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 leapSporeFromCkbToBtc({
   outIndex: 1,
   btcTxId: '448897515cf07b4ca0cd38af9806399ede55775b4c760b274ed2322121ed185f',
+  // Please use your own RGB++ spore asset's sporeTypeArgs
   sporeTypeArgs: '0x42898ea77062256f46e8f1b861d526ae47810ecc51ab50477945d5fa90452706',
 });

examples/rgbpp/spore/launch/1-prepare-cluster.ts

@@ -70,6 +70,7 @@ const prepareClusterCell = async ({ outIndex, btcTxId }: { outIndex: number; btc
   console.info(`Cluster cell has been prepared and the tx hash ${txHash}`);
 };
 
+// Please use your real BTC UTXO information on the BTC Testnet
 prepareClusterCell({
   outIndex: 3,
   btcTxId: 'aee4e8e3aa95e9e9ab1f0520714031d92d3263262099dcc7f7d64e62fa2fcb44',

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

@@ -11,6 +11,7 @@ import {
 } from 'rgbpp/ckb';
 import { saveCkbVirtualTxResult } from '../../shared/utils';
 
+// Warning: Before runing this file, please run 1-prepare-cluster.ts
 const createCluster = async ({ ownerRgbppLockArgs }: { ownerRgbppLockArgs: string }) => {
   const ckbVirtualTxResult = await genCreateClusterCkbVirtualTx({
     collector,
@@ -23,7 +24,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 +33,7 @@ const createCluster = async ({ ownerRgbppLockArgs }: { ownerRgbppLockArgs: strin
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: [btcAddress!],
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,
@@ -79,7 +81,7 @@ const createCluster = async ({ ownerRgbppLockArgs }: { ownerRgbppLockArgs: strin
   }, 30 * 1000);
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet which should be same as the 1-prepare-cluster.ts
 // rgbppLockArgs: outIndexU32 + btcTxId
 createCluster({
   ownerRgbppLockArgs: buildRgbppLockArgs(3, 'aee4e8e3aa95e9e9ab1f0520714031d92d3263262099dcc7f7d64e62fa2fcb44'),

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

@@ -30,6 +30,7 @@ interface SporeCreateParams {
   }[];
 }
 
+// Warning: Before runing this file for the first time, please run 2-prepare-cluster.ts
 const createSpores = async ({ clusterRgbppLockArgs, receivers }: SporeCreateParams) => {
   const ckbVirtualTxResult = await genCreateSporeCkbVirtualTx({
     collector,
@@ -42,7 +43,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 +52,7 @@ const createSpores = async ({ clusterRgbppLockArgs, receivers }: SporeCreatePara
     ckbVirtualTx: ckbRawTx,
     commitment,
     tos: btcTos,
+    needPaymaster: needPaymasterCell,
     ckbCollector: collector,
     from: btcAddress!,
     source: btcDataSource,
@@ -114,7 +116,7 @@ const createSpores = async ({ clusterRgbppLockArgs, receivers }: SporeCreatePara
   }, 30 * 1000);
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 // rgbppLockArgs: outIndexU32 + btcTxId
 createSpores({
   // The cluster cell will be spent and the new cluster cell will be created in each spore creation tx,

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,
@@ -91,11 +92,12 @@ const transferSpore = async ({ sporeRgbppLockArgs, toBtcAddress, sporeTypeArgs }
   }, 30 * 1000);
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 // rgbppLockArgs: outIndexU32 + btcTxId
 transferSpore({
   // The spore rgbpp lock args is from 3-create-spore.ts
   sporeRgbppLockArgs: buildRgbppLockArgs(1, 'f203c8c13eacdbd126f85d286a963c85f233f8145363b1d997c4d552afb990e1'),
   toBtcAddress: 'tb1qhp9fh9qsfeyh0yhewgu27ndqhs5qlrqwau28m7',
+  // Please use your own RGB++ spore asset's sporeTypeArgs
   sporeTypeArgs: '0x42898ea77062256f46e8f1b861d526ae47810ecc51ab50477945d5fa90452706',
 });

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,
@@ -91,11 +92,12 @@ const leapSpore = async ({ sporeRgbppLockArgs, toCkbAddress, sporeTypeArgs }: Sp
   }, 30 * 1000);
 };
 
-// Use your real BTC UTXO information on the BTC Testnet
+// Please use your real BTC UTXO information on the BTC Testnet
 // rgbppLockArgs: outIndexU32 + btcTxId
 leapSpore({
   // The spore rgbpp lock args is from 3-create-spore.ts
   sporeRgbppLockArgs: buildRgbppLockArgs(3, 'd8a31796fbd42c546f6b22014b9b82b16586ce1df81b0e7ca9a552cdc492a0af'),
   toCkbAddress: 'ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq0e4xk4rmg5jdkn8aams492a7jlg73ue0gc0ddfj',
+  // Please use your own RGB++ spore asset's sporeTypeArgs
   sporeTypeArgs: '0x42898ea77062256f46e8f1b861d526ae47810ecc51ab50477945d5fa90452706',
 });

examples/rgbpp/tsconfig.json

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