Merge pull request #102 from ckb-cell/develop

Merge `develop` into `main` branch

Author: Flouse

.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
-  "changelog": "@changesets/cli/changelog",
+  "changelog": ["@changesets/changelog-github", { "repo": "ckb-cell/rgbpp-sdk" }],
   "commit": false,
   "fixed": [["@rgbpp-sdk/*"]],
   "linked": [],

.eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+  }
+}

.github/workflows/release.yml

@@ -4,6 +4,9 @@ name: Release
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - main
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -12,6 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pull-requests: write
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -43,11 +47,13 @@ jobs:
       - name: Install dependencies
         run: pnpm i
 
-      - name: Create Release Pull Request or Publish to npm
+      - name: Create bump PR or release version
         id: changesets
         uses: changesets/action@v1
         with:
           publish: pnpm run release:packages
+          title: "bump: assumable rgbpp-sdk version"
+          commit: "bump: assumable rgbpp-sdk version"
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/snapshot.yml

@@ -3,6 +3,7 @@
 name: Release Snapshots
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
@@ -54,6 +55,8 @@ jobs:
 
       - name: Version packages
         run: npx changeset version --snapshot snap
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Publish to npm (ignore GitHub)
         id: changesets

.github/workflows/test.yaml

@@ -45,6 +45,9 @@ jobs:
 
       - name: Build packages
         run: pnpm run build:packages
+
+      - name: Lint packages
+        run: pnpm run lint:packages
 
       - name: Run tests for packages
         run: pnpm run test:packages

.gitignore

@@ -36,3 +36,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+devbox.json
+devbox.lock
+.envrc

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npx lint-staged
+pnpm exec lint-staged

README.md

@@ -1,9 +1,65 @@
 # RGB++ SDK
 
-## Packages
+This repository offers utilities for Bitcoin and RGB++ asset integration.
+
+### Packages in this repository
 
 - [@rgbpp-sdk/btc](./packages/btc): Bitcoin part of the SDK
 - [@rgbpp-sdk/ckb](./packages/ckb): Nervos CKB part of the SDK
+- [@rgbpp-sdk/service](./packages/service): A wrapped class to interact with `Bitcoin/RGB++ Assets Service`
+
+## RGB++ Code Examples
+
+- Find code examples at https://github.com/ckb-cell/rgbpp-sdk/tree/develop/examples/rgbpp
+
+## Related CKB Scripts (Contracts)
+- [CKB Bitcoin SPV Type Script](https://github.com/ckb-cell/ckb-bitcoin-spv-contracts/tree/master/contracts/ckb-bitcoin-spv-type-lock): A [type script](https://docs.nervos.org/docs/basics/glossary#type-script) for [Bitcoin SPV](https://bitcoinwiki.org/wiki/simplified-payment-verification) clients which synchronize [Bitcoin](https://bitcoin.org) state into [CKB](https://github.com/nervosnetwork/ckb)
+
+- [RgbppLockScript and BtcTimeLockScript](https://github.com/ckb-cell/rgbpp-sdk/blob/cf25ea014d4e0fc24723df8eea8bd61f59e1060a/packages/ckb/src/constants/index.ts#L11-L121)
+  * design: https://github.com/ckb-cell/RGBPlusPlus-design/blob/main/docs/light-paper-en.md
+  * testnet: https://pudge.explorer.nervos.org/scripts#RGB++
+  * mainnet: https://explorer.nervos.org/scripts#RGB++
+
+## RGB++ Asset Workflow Overview
+
+1. **Creation of `rgbpp_ckb_tx_virtual` using [@rgbpp-sdk/ckb](https://github.com/ckb-cell/rgbpp-sdk/tree/develop/packages/ckb)**
+
+  - xUDT
+
+    1. **[BTC → BTC](https://github.com/ckb-cell/rgbpp-sdk/tree/develop/packages/ckb#rgb-xudt-transfer-on-btc)**
+    2. **[BTC → CKB](https://github.com/ckb-cell/rgbpp-sdk/tree/develop/packages/ckb#rgb-xudt-leap-from-btc-to-ckb)**
+    3. **[CKB → BTC](https://github.com/ckb-cell/rgbpp-sdk/tree/develop/packages/ckb#rgb-xudt-leap-from-ckb-to-btc)** *(isomorphic rgbpp_btc_tx is not required in this workflow)*
+
+  - Spore
+  
+    1. **[BTC → BTC](https://github.com/ckb-cell/rgbpp-sdk/blob/develop/packages/ckb/README.md#rgb-spore-transfer-on-btc)**
+    2. **[BTC → CKB](https://github.com/ckb-cell/rgbpp-sdk/blob/develop/packages/ckb/README.md#rgb-spore-leap-from-btc-to-ckb)**
+    3. **[CKB → BTC](https://github.com/ckb-cell/rgbpp-sdk/blob/develop/packages/ckb/README.md#rgb-spore-leap-from-ckb-to-btc)** *(isomorphic rgbpp_btc_tx is not required in this workflow)*
+
+  > [!IMPORTANT]  
+  > It's recommended to save the `rgbpp_ckb_tx_virtual` locally in case you need it in the future.
+
+2. **Creation of `rgbpp_btc_tx` through [@rgbpp-sdk/btc](https://github.com/ckb-cell/rgbpp-sdk/tree/develop/packages/btc)**
+    1. construct isomorphic rgbpp_btc_tx based on rgbpp_ckb_tx_virtual and rgbpp commitment
+    2. sign and broadcast rgbpp_btc_tx to obtain `rgbpp_btc_txid`
+
+3. JoyID or dApp sends `rgbpp_btc_txid` and `rgbpp_ckb_tx_virtual` to RGB++ CKB transaction Queue (API Endpoint: `/rgbpp/v1/transaction/ckb-tx`)
+
+4. `RGB++ CKB transaction Queue` will process the following things:
+    1. **verify** the received requests
+    2. continuously fetch request from the queue through a **cron job**
+    3. check whether the **confirmations** of req.rgbpp_btc_txid is sufficient
+    4. generate the **witnesses for RgbppLocks** in the rgbpp_ckb_tx_virtual
+    5. add a **paymaster cell** into rgbpp_ckb_tx_virtual.inputs if the CKB capacity is insufficient
+        1. need to **verify the existence of paymaster UTXO** in the rgbpp_btc_tx
+        2. sign the paymaster cell and the entire transaction if needed
+    6. **finalize** the rgbpp_ckb_tx_virtual to a rgbpp_ckb_tx
+    7. **broadcast** rgbpp_ckb_tx and mark the job as completed upon tx-confirmation
+
+### Notes
+
+- The RGB++ CKB transaction Queue is designed to streamline the transaction workflow. Developers have the option to implement its features by themselves without limitation.
+
 
 ## License
 

examples/rgbpp/README.md

@@ -1,6 +1,10 @@
 # RGB++ Examples
 
-**All examples are just to demonstrate the use of RGB++ SDK. SPV proof is not ready yet, so these examples do not involve the verification of SPV proof.**
+**All examples are just to demonstrate the use of RGB++ SDK.**
+
+- Local and Queue directories: The examples for RGB++ UDT issuance, transfer, and leap
+- Spore directory: The examples for RGB++ spore creation, transfer and leap
+- xUDT directory: The examples for xUDT issuance, mint and transfer on CKB
 
 ## What you must know about BTC transaction id
 
@@ -25,70 +29,119 @@ But when you're searching for this transaction in [Bitcoin Core](https://bitcoin
 018025fb6989eed484774170eefa2bef1074b0c24537f992a64dbc138277bc4a
 ```
 
-## Examples with Queue service(Recommended)
+## xUDT on CKB Examples
+
+### Issue xUDT on CKB
+
+```shell
+npx ts-node examples/rgbpp/xudt/1-issue-xudt.ts 
+```
+
+### Mint/Transfer xUDT on CKB
 
-### Mint XUDT
-As a simple example, Omiga protocol is reused for a quick demonstration of XUDT asset insurance.
-Developers have the option to utilize an existing XUDT (User-Defined Token) on CKB.
+You can use this command to mint or transfer xUDT assets
 
 ```shell
-npx ts-node examples/rgbpp/queue/1-mint-xudt.ts 
+npx ts-node examples/rgbpp/xudt/2-transfer-xudt.ts 
 ```
 
-### Jump XUDT from CKB to BTC
+## RGB++ xUDT Examples with Queue service(Recommended)
+
+### Leap xUDT from CKB to BTC
 
 ```shell
-npx ts-node examples/rgbpp/queue/2-ckb-jump-btc.ts 
+npx ts-node examples/rgbpp/queue/1-ckb-jump-btc.ts 
 ```
 
-### Transfer RGB++ asset on BTC
+### Transfer RGB++ xUDT on BTC
 
 ```shell
-npx ts-node examples/rgbpp/queue/3-btc-transfer.ts 
+npx ts-node examples/rgbpp/queue/2-btc-transfer.ts 
 ```
 
-### Jump RGB++ asset from BTC to CKB
+### Leap RGB++ xUDT from BTC to CKB
 
 ```shell
-npx ts-node examples/rgbpp/queue/4-btc-jump-ckb.ts 
+npx ts-node examples/rgbpp/queue/3-btc-jump-ckb.ts 
 ```
 
-### Unlock BTC time cells on CKB
+### Unlock xUDT BTC time cells on CKB
 
 A cron job in RGB++ Queue service will construct a transaction unlocking the mature BTC time cells to the their `target_ckb_address`.
 
-## Local Examples
 
-### Mint XUDT
-As a simple example, Omiga protocol is reused for a quick demonstration of XUDT asset insurance.
-Developers have the option to utilize an existing XUDT (User-Defined Token) on CKB.
+## RGB++ xUDT Local Examples
+
+### Leap RGB++ xUDT from CKB to BTC
 
 ```shell
-npx ts-node examples/rgbpp/local/1-mint-xudt.ts 
+npx ts-node examples/rgbpp/local/1-ckb-jump-btc.ts 
 ```
 
-### Jump XUDT from CKB to BTC
+### Transfer RGB++ xUDT on BTC
 
 ```shell
-npx ts-node examples/rgbpp/local/2-ckb-jump-btc.ts 
+npx ts-node examples/rgbpp/local/2-btc-transfer.ts 
 ```
 
-### Transfer RGB++ asset on BTC
+### Leap RGB++ xUDT from BTC to CKB
 
 ```shell
-npx ts-node examples/rgbpp/local/3-btc-transfer.ts 
+npx ts-node examples/rgbpp/local/3-btc-jump-ckb.ts 
 ```
 
-### Jump RGB++ asset from BTC to CKB
+### Unlock xUDT BTC time cells on CKB
+
+**Warning: Wait at least 6 BTC confirmation blocks to unlock the BTC time cells after 4-btc-jump-ckb.ts**
 
 ```shell
-npx ts-node examples/rgbpp/local/4-btc-jump-ckb.ts 
+npx ts-node examples/rgbpp/local/4-spend-btc-time-cell.ts 
 ```
 
-### Unlock BTC time cells on CKB
+## RGB++ Spore Examples
 
-**Warning: Wait at least 6 BTC confirmation blocks to unlock the BTC time cells after 4-btc-jump-ckb.ts**
+**You can use RGB++ Queue service to complete spore transfer and leap, and the examples can be found in `examples/rgbpp/spore/queue`**
+
+### Create RGB++ Cluster Cell
+
+```shell
+npx ts-node examples/rgbpp/spore/1-prepare-cluster.ts
+
+npx ts-node examples/rgbpp/spore/2-create-cluster.ts
+```
+
+### Create RGB++ Spores with Cluster on BTC
+
+```shell
+npx ts-node examples/rgbpp/spore/3-create-spores.ts
+```
+
+### Transfer RGB++ Spore on BTC
+
+```shell
+npx ts-node examples/rgbpp/spore/4-transfer-spore.ts
+```
+
+### Leap RGB++ Spore from BTC to CKB
+
+```shell
+npx ts-node examples/rgbpp/spore/5-leap-spore-to-ckb.ts
+```
+
+### Unlock Spore BTC time cells on CKB
+
+A cron job in RGB++ Queue service will construct a transaction unlocking the mature BTC time cells to the their `target_ckb_address`.
+
+However, you can still manually unlock the spore btc time cell through the following command
+
+**Warning: Wait at least 6 BTC confirmation blocks to unlock the BTC time cells after 5-leap-spore-to-ckb.ts**
+
+```shell
+npx ts-node examples/rgbpp/spore/6-unlock-btc-time-cell.ts
+```
+
+### Leap Spore from CKB to BTC
 
 ```shell
-npx ts-node examples/rgbpp/local/5-spend-btc-time-cell.ts 
+npx ts-node examples/rgbpp/spore/7-leap-spore-to-btc.ts
 ```

examples/rgbpp/local/2-ckb-jump-btc.ts renamed to examples/rgbpp/local/1-ckb-jump-btc.ts

@@ -1,5 +1,11 @@
 import { AddressPrefix, privateKeyToAddress, serializeScript } from '@nervosnetwork/ckb-sdk-utils';
-import { genCkbJumpBtcVirtualTx, Collector, getSecp256k1CellDep, buildRgbppLockArgs } from '@rgbpp-sdk/ckb';
+import {
+  genCkbJumpBtcVirtualTx,
+  Collector,
+  getSecp256k1CellDep,
+  buildRgbppLockArgs,
+  getXudtTypeScript,
+} from '@rgbpp-sdk/ckb';
 
 // CKB SECP256K1 private key
 const CKB_TEST_PRIVATE_KEY = '0x0000000000000000000000000000000000000000000000000000000000000001';
@@ -11,15 +17,15 @@ const jumpFromCkbToBtc = async ({ outIndex, btcTxId }: { outIndex: number; btcTx
   });
   const isMainnet = false;
   const address = privateKeyToAddress(CKB_TEST_PRIVATE_KEY, {
-      prefix: isMainnet ? AddressPrefix.Mainnet : AddressPrefix.Testnet,
-    });
+    prefix: isMainnet ? AddressPrefix.Mainnet : AddressPrefix.Testnet,
+  });
   console.log('ckb address: ', address);
 
   const toRgbppLockArgs = buildRgbppLockArgs(outIndex, btcTxId);
 
+  // Warning: Please replace with your real xUDT type script here
   const xudtType: CKBComponents.Script = {
-    codeHash: '0x25c29dc317811a6f6f3985a7a9ebc4838bd388d19d0feeecf0bcd60f6c0975bb',
-    hashType: 'type',
+    ...getXudtTypeScript(isMainnet),
     args: '0x1ba116c119d1cfd98a53e9d1a615cf2af2bb87d95515c9d217d367054cfc696b',
   };
 
@@ -29,19 +35,18 @@ const jumpFromCkbToBtc = async ({ outIndex, btcTxId }: { outIndex: number; btcTx
     toRgbppLockArgs,
     xudtTypeBytes: serializeScript(xudtType),
     transferAmount: BigInt(800_0000_0000),
-    witnessLockPlaceholderSize: 1000
   });
 
   const emptyWitness = { lock: '', inputType: '', outputType: '' };
-  let unsignedTx: CKBComponents.RawTransactionToSign = {
+  const unsignedTx: CKBComponents.RawTransactionToSign = {
     ...ckbRawTx,
-    cellDeps: [...ckbRawTx.cellDeps, getSecp256k1CellDep(false)],
+    cellDeps: [...ckbRawTx.cellDeps, getSecp256k1CellDep(isMainnet)],
     witnesses: [emptyWitness, ...ckbRawTx.witnesses.slice(1)],
   };
 
   const signedTx = collector.getCkb().signTransaction(CKB_TEST_PRIVATE_KEY)(unsignedTx);
 
-  let txHash = await collector.getCkb().rpc.sendTransaction(signedTx, 'passthrough');
+  const txHash = await collector.getCkb().rpc.sendTransaction(signedTx, 'passthrough');
   console.info(`Rgbpp asset has been jumped from CKB to BTC and tx hash is ${txHash}`);
 };
 
@@ -50,4 +55,3 @@ jumpFromCkbToBtc({
   outIndex: 1,
   btcTxId: '4ff1855b64b309afa19a8b9be3d4da99dcb18b083b65d2d851662995c7d99e7a',
 });
-