For RGB++ features preview purpose

packages/connector/src/signers/index.ts

@@ -45,7 +45,7 @@ export class SignersController {
   hostConnected(): void {
     void this.refresh();
     // Wait for plugins to be loaded
-    setTimeout(() => this.refresh(), 500);
+    setTimeout(() => void this.refresh(), 500);
   }
 
   hostDisconnected(): void {

packages/demo/src/app/connected/(tools)/IssueRgbppXUdt/page.tsx

@@ -122,8 +122,9 @@ export default function IssueRGBPPXUdt() {
 
     const config: BtcAssetApiConfig = {
       url: process.env.NEXT_PUBLIC_BTC_ASSETS_API_URL!,
-      token: process.env.NEXT_PUBLIC_BTC_ASSETS_API_TOKEN!,
-      origin: process.env.NEXT_PUBLIC_BTC_ASSETS_API_ORIGIN!,
+      token: process.env.NEXT_PUBLIC_BTC_ASSETS_API_TOKEN,
+      origin: process.env.NEXT_PUBLIC_BTC_ASSETS_API_ORIGIN,
+      isMainnet: networkConfig.isMainnet,
     };
 
     return createBrowserRgbppBtcWallet(signer, networkConfig, config);

packages/playground/RGBPP_UDT_ISSUANCE_GUIDE.md

@@ -0,0 +1,126 @@
+# `@ckb-ccc/rgbpp` Development Guide
+
+## Overview
+
+This guide demonstrates how to use the `@ckb-ccc/rgbpp` package to build RGB++ applications on Bitcoin and CKB. We'll walk through a complete RGB++ [xUDT](https://docs.nervos.org/docs/tech-explanation/xudt) issuance example to showcase the key concepts and development patterns on the interactive playground environment.
+
+## Prerequisites
+
+Before running this example, ensure you have:
+
+1. **Supported Wallet**: UniSat, JoyID
+2. **Testnet Environment**: Currently only Bitcoin Testnet3 and CKB Testnet are supported on the playground environment
+3. **Test Funds**: 
+   - Bitcoin Testnet3 funds from [Bitcoin Faucet](https://bitcoinfaucet.uo1.net/)
+   - CKB Testnet funds from [Nervos Faucet](https://faucet.nervos.org/)
+
+Basic understanding of the RGB++ protocol is also desired. Learn more at [RGB++ Protocol](https://rgbpp.com/).
+
+## RGB++ xUDT Issuance Example
+
+Let's walk through a complete RGB++ xUDT issuance example using `@ckb-ccc/rgbpp`:
+
+### Step 1: Basic Setup
+
+Environment validation and network configuration:
+
+```typescript
+// Basic wallet and network validation
+if (!signer || !(signer instanceof ccc.SignerBtc)) {
+  throw new Error("Wallet not supported");
+}
+if (client.addressPrefix !== "ckt") {
+  throw new Error("Only Testnet is supported for now");
+}
+
+// Initialize RGB++ network configuration
+const networkConfig = ccc.rgbpp.buildNetworkConfig(
+  ccc.rgbpp.PredefinedNetwork.BitcoinTestnet3,
+  { cellDeps: { /* ... */ } }
+);
+```
+
+`buildNetworkConfig` sets up the essential RGB++ network configuration with proper cell dependencies for isomorphic binding, among other configurations.
+
+### Step 2: RGB++ Wallet and Client Setup
+
+```typescript
+const btcRgbppSigner = await ccc.rgbpp.createBrowserRgbppBtcWallet(
+  signer,
+  networkConfig,
+  {
+    url: "https://api-testnet.rgbpp.com",
+    isMainnet: signer.client.addressPrefix === "ckt",
+  },
+);
+
+const rgbppUdtClient = new ccc.rgbpp.RgbppUdtClient(networkConfig, signer.client);
+const ckbRgbppUnlockSinger = new ccc.rgbpp.CkbRgbppUnlockSinger(...);
+```
+
+`https://api-testnet.rgbpp.com` here is the testnet btc-assets-api URL. It's a service that retrieves BTC/RGB++ information/assets and processes transactions with these assets. It serves as the critical infrastructure component that connects Bitcoin and CKB networks for RGB++ operations.
+
+**Key Components**: 
+- `createBrowserRgbppBtcWallet`: Creates RGB++ Bitcoin wallet for cross-chain operations
+- `RgbppUdtClient`: High-level APIs for xUDT operations
+- `CkbRgbppUnlockSinger`: Handles RGB++ lock script unlock logic
+
+### Step 3: UTXO Seal and Issuance Cell
+
+```typescript
+const utxoSeal = await btcRgbppSigner.prepareUtxoSeal();
+
+const rgbppIssuanceCells = await rgbppUdtClient.createRgbppUdtIssuanceCells(
+  signer,
+  utxoSeal,
+);
+```
+
+The `prepareUtxoSeal` method creates the foundation for **isomorphic binding** - a one-to-one mapping between Bitcoin UTXOs and CKB Cells. This UTXO becomes cryptographically "sealed" to the CKB Cell containing xUDT data.
+
+`rgbppIssuanceCells` is a CKB cell with its lock script set to the RGB++ lock script, using the UTXO as its argument. This configuration represents the user's intent to issue a RGB++ xUDT token, which will only be fulfilled after the initial UTXO is spent.
+
+### Step 4: Partial CKB Transaction and RGB++ Bitcoin Transaction
+
+```typescript
+const ckbPartialTx = await rgbppUdtClient.issuanceCkbPartialTx({
+  token: {
+    name: "Just UDT",
+    symbol: "jUDT", 
+    decimal: 8,
+  },
+  amount: 2100_0000n,
+  rgbppLiveCells: rgbppIssuanceCells,
+  udtScriptInfo: {/* ... */},
+});
+
+const { psbt, indexedCkbPartialTx } = await btcRgbppSigner.buildPsbt({
+  ckbPartialTx,
+  ckbClient: signer.client,
+  rgbppUdtClient,
+  btcChangeAddress: btcAddress,
+  receiverBtcAddresses: [btcAddress],
+});
+
+const btcTxId = await btcRgbppSigner.signAndBroadcast(psbt);
+```
+
+A partial CKB transaction is constructed using the CKB cell and xUDT script information, initially containing a placeholder for the corresponding Bitcoin transaction ID. Based on this, the commitment is calculated and the BTC transaction is assembled, which is then submitted to the network.
+
+### Step 5: Final RGB++ CKB Transaction
+
+```typescript
+const ckbPartialTxInjected = await rgbppUdtClient.injectTxIdToRgbppCkbTx(
+  indexedCkbPartialTx,
+  btcTxId,
+);
+
+const rgbppSignedCkbTx = await ckbRgbppUnlockSinger.signTransaction(ckbPartialTxInjected);
+await rgbppSignedCkbTx.completeFeeBy(signer);
+const ckbFinalTx = await signer.signTransaction(rgbppSignedCkbTx);
+const txHash = await signer.client.sendTransaction(ckbFinalTx);
+```
+
+In `ckbRgbppUnlockSinger.signTransaction`, the BTC transaction's confirmation status is periodically checked through the SPV service. Upon confirmation, we acquire the new single-use seal which represents ownership of the issued RGB++ xUDT token. The transaction ID of this UTXO is used to replace the placeholder value in the RGB++ lock script, enabling the assembly of the final CKB transaction.
+
+The final CKB transaction is then submitted to the network, completing the token issuance process.

packages/playground/package.json

@@ -47,4 +47,4 @@
     "tailwindcss": "^4.1.12"
   },
   "packageManager": "pnpm@10.8.1"
-}
+}

packages/playground/src/app/components/Editor.tsx

@@ -142,9 +142,14 @@ export function Editor({
           });
 
           monaco.languages.typescript.typescriptDefaults.addExtraLib(
-            "import { ccc } from '@ckb-ccc/core'; export function render(...msgs: unknown[]): Promise<void>; export const signer: ccc.Signer; export const client: ccc.Client;",
+            `import { ccc } from '@ckb-ccc/core'; 
+             export * from '@ckb-ccc/rgbpp';
+             export function render(...msgs: unknown[]): Promise<void>; 
+             export const signer: ccc.Signer; 
+             export const client: ccc.Client;`,
             "file:///node_modules/@ckb-ccc/playground/index.d.ts",
           );
+
           monaco.languages.typescript.typescriptDefaults.addExtraLib(
             '{ "type": "commonjs" }',
             "file:///node_modules/@ckb-ccc/playground/package.json",

packages/playground/src/app/examples.ts

@@ -31,3 +31,128 @@ await render(tx);
 await tx.completeFeeBy(signer, 1000);
 await render(tx);
 `;
+
+export const RGBPP_UDT_ISSUANCE = `import { ccc } from "@ckb-ccc/ccc";
+import { render, signer, client } from "@ckb-ccc/playground";
+
+// ensure supported wallet is connected
+if (!signer || !(signer instanceof ccc.SignerBtc)) {
+  throw new Error("Wallet not supported");
+}
+
+// only support Testnet for now
+if (client.addressPrefix !== "ckt") {
+  throw new Error("Only Testnet is supported for now");
+}
+
+const btcAddress = await signer.getBtcAccount();
+
+// initialize RGB++ env
+const networkConfig = ccc.rgbpp.buildNetworkConfig(
+  ccc.rgbpp.PredefinedNetwork.BitcoinTestnet3,
+  // TODO: remove the following 2 configs after updating RGB++ cell deps in ccc
+  {
+    cellDeps: {
+      [ccc.rgbpp.PredefinedScriptName.RgbppLock]: ccc.CellDep.from({
+        outPoint: {
+          txHash:
+            "0x0d1567da0979f78b297d5311442669fbd1bd853c8be324c5ab6da41e7a1ed6e5",
+          index: "0x0",
+        },
+        depType: "code",
+      }),
+      [ccc.rgbpp.PredefinedScriptName.BtcTimeLock]: ccc.CellDep.from({
+        outPoint: {
+          txHash:
+            "0x8fb747ff0416a43e135c583b028f98c7b81d3770551b196eb7ba1062dd9acc94",
+          index: "0x0",
+        },
+        depType: "code",
+      }),
+    },
+  },
+);
+
+const btcRgbppSigner = await ccc.rgbpp.createBrowserRgbppBtcWallet(
+  signer,
+  networkConfig,
+  {
+    url: "https://api-testnet.rgbpp.com",
+    isMainnet: signer.client.addressPrefix === "ckt",
+  },
+);
+if (!btcRgbppSigner) {
+  throw new Error("Failed to create browser RGBPP BTC singer");
+}
+
+const rgbppUdtClient = new ccc.rgbpp.RgbppUdtClient(networkConfig, signer.client);
+const ckbRgbppUnlockSinger = new ccc.rgbpp.CkbRgbppUnlockSinger(
+  signer.client,
+  await btcRgbppSigner.getAddress(),
+  btcRgbppSigner,
+  btcRgbppSigner,
+  rgbppUdtClient.getRgbppScriptInfos(),
+);
+
+const utxos = await btcRgbppSigner.getUtxos(await btcRgbppSigner.getAddress());
+if (!utxos.length) {
+  throw new Error(
+    "No Testnet3 BTC available. Go to a Testnet3 faucet (https://bitcoinfaucet.uo1.net/) to get some.",
+  );
+}
+
+const ckbBalance = await signer.getBalance();
+if (ckbBalance === BigInt(0)) {
+  throw new Error(
+    "No Testnet CKB available. Go to https://faucet.nervos.org/ to get some.",
+  );
+}
+const utxoSeal = await btcRgbppSigner.prepareUtxoSeal({ feeRate: 7 });
+
+const rgbppIssuanceCells = await rgbppUdtClient.createRgbppUdtIssuanceCells(
+  signer,
+  utxoSeal,
+);
+const ckbPartialTx = await rgbppUdtClient.issuanceCkbPartialTx({
+  token: {
+    name: "Just UDT",
+    symbol: "jUDT",
+    decimal: 8,
+  },
+  amount: 2100_0000n,
+  rgbppLiveCells: rgbppIssuanceCells,
+  udtScriptInfo: {
+    name: ccc.KnownScript.XUdt,
+    script: await ccc.Script.fromKnownScript(client, ccc.KnownScript.XUdt, ""),
+    cellDep: (await client.getKnownScript(ccc.KnownScript.XUdt)).cellDeps[0]
+      .cellDep,
+  },
+});
+
+const { psbt, indexedCkbPartialTx } = await btcRgbppSigner.buildPsbt({
+  ckbPartialTx,
+  ckbClient: signer.client,
+  rgbppUdtClient,
+  btcChangeAddress: btcAddress,
+  receiverBtcAddresses: [btcAddress],
+  feeRate: 7,
+});
+await render("Partial RGB++ CKB tx", indexedCkbPartialTx);
+
+const btcTxId = await btcRgbppSigner.signAndBroadcast(psbt);
+await render("RGB++ BTC tx id", btcTxId);
+
+const ckbPartialTxInjected = await rgbppUdtClient.injectTxIdToRgbppCkbTx(
+  indexedCkbPartialTx,
+  btcTxId,
+);
+const rgbppSignedCkbTx =
+  await ckbRgbppUnlockSinger.signTransaction(ckbPartialTxInjected);
+await rgbppSignedCkbTx.completeFeeBy(signer);
+const ckbFinalTx = await signer.signTransaction(rgbppSignedCkbTx);
+await render("Final RGB++ CKB tx", ckbFinalTx);
+
+const txHash = await signer.client.sendTransaction(ckbFinalTx);
+await ckbRgbppUnlockSinger.client.waitTransaction(txHash);
+await render("RGB++ CKB tx", txHash);
+`;

packages/playground/src/app/execute/index.tsx

@@ -1,6 +1,7 @@
 import * as cccLib from "@ckb-ccc/ccc";
 import * as cccAdvancedLib from "@ckb-ccc/ccc/advanced";
 import { ccc } from "@ckb-ccc/connector-react";
+import * as rgbppLib from "@ckb-ccc/rgbpp";
 import * as dobRenderLib from "@nervina-labs/dob-render";
 import * as React from "react";
 import ts from "typescript";
@@ -64,6 +65,7 @@ export async function execute(
       "@ckb-ccc/ccc": cccLib,
       "@ckb-ccc/ccc/advanced": cccAdvancedLib,
       "@nervina-labs/dob-render": dobRenderLib,
+      "@ckb-ccc/rgbpp": rgbppLib,
       "@ckb-ccc/playground": {
         render: async (...msgs: unknown[]) => {
           log("info", formatTimestamp(Date.now()), msgs);

packages/rgbpp/package.json

@@ -22,10 +22,16 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
+    "@ckb-ccc/spore": "workspace:*",
+    "@ckb-ccc/udt": "workspace:*",
+    "@ckb-lumos/base": "^0.22.2",
+    "@ckb-lumos/codec": "^0.22.2",
+    "@exact-realty/multipart-parser": "^1.0.13",
     "@types/jest": "^29.5.14",
     "@types/lodash": "^4.17.14",
     "@types/node": "^22.10.6",
     "copyfiles": "^2.4.1",
+    "dotenv": "^16.4.7",
     "eslint": "^9.18.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.2.1",
@@ -34,24 +40,19 @@
     "prettier-plugin-organize-imports": "^4.1.0",
     "rimraf": "^6.0.1",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.7.3",
-    "@ckb-ccc/shell": "workspace:*",
-    "@ckb-lumos/base": "^0.22.2",
-    "@ckb-lumos/codec": "^0.22.2",
-    "@ckb-ccc/spore": "workspace:*",
-    "dotenv": "^16.4.7",
-    "@exact-realty/multipart-parser": "^1.0.13"
+    "tsx": "^4.20.4",
+    "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@ckb-ccc/shell": "workspace:*",
+    "@bitcoinerlab/secp256k1": "1.1.1",
+    "@ckb-ccc/core": "workspace:*",
     "@ckb-lumos/base": "^0.23.0",
     "@ckb-lumos/bi": "^0.23.0",
     "@ckb-lumos/codec": "^0.23.0",
+    "bip32": "4.0.0",
     "bitcoinjs-lib": "6.1.6",
+    "ecpair": "2.1.0",
     "js-sha256": "^0.11.0",
-    "lodash": "^4.17.21",
-    "@bitcoinerlab/secp256k1": "1.1.1",
-    "bip32": "4.0.0",
-    "ecpair": "2.1.0"
+    "lodash": "^4.17.21"
   }
 }