RGB++ Protocol - Bitcoin Layer 2 Protocol

Prerequisites

Before You Start

Before getting started, refer to the btc-assets-api section to apply for an access token.

Node.js 16+ installed

Basic understanding of Bitcoin UTXOs

RGB++ API access token

Testnet Access

Testnet API:https://api.testnet.rgbpp.io

Signet API:https://api.signet.rgbpp.io

Installation

Primary SDK (Recommended):

npm install @ckb-ccc/rgbpp

UDT Token Operations

In CKB, custom tokens are implemented as User-Defined Tokens (UDTs). The following examples demonstrate RGB++ protocol by issuing a RGB++ token using the pre-deployed xUDT Script.

1. Token Issuance

Process Overview

UTXO Selection

Select or create initial single-use seal

CKB Transaction

Create RGB++ lock script with UTXO

Bitcoin Transaction

Submit commitment to Bitcoin network

Finalization

Complete CKB transaction after confirmation

Code Example: Token Issuance

async function issueUdt({
  udtScriptInfo,
  utxoSeal,
}: {
  udtScriptInfo: ScriptInfo;
  utxoSeal?: UtxoSeal;
}) {
  // Initialize the RGB++ environment
  const {
    rgbppBtcWallet, 
    rgbppUdtClient, 
    utxoBasedAccountAddress, 
    ckbRgbppUnlockSinger,
  } = initializeRgbppEnv();

  // Prepare the initial single-use seal and corresponding RGB++ cells
  if (!utxoSeal) {
    utxoSeal = await rgbppBtcWallet.prepareUtxoSeal();
  }
  const rgbppIssuanceCells = await prepareRgbppCells(utxoSeal, rgbppUdtClient);

  // Construct the partial CKB transaction
  const ckbPartialTx = await rgbppUdtClient.issuanceCkbPartialTx({
    token: udtToken,
    amount: issuanceAmount,
    rgbppLiveCells: rgbppIssuanceCells,
    udtScriptInfo,
  });

  // Build and submit the Bitcoin transaction
  const { psbt, indexedCkbPartialTx } = await rgbppBtcWallet.buildPsbt({
    ckbPartialTx,
    ckbClient,
    rgbppUdtClient,
    btcChangeAddress: utxoBasedAccountAddress,
    receiverBtcAddresses: [utxoBasedAccountAddress],
  });
  
  const btcTxId = await rgbppBtcWallet.signAndSendTx(psbt);
  
  // Complete the CKB transaction
  const ckbPartialTxInjected = await rgbppUdtClient.injectTxIdToRgbppCkbTx(
    indexedCkbPartialTx,
    btcTxId,
  );
  
  const rgbppSignedCkbTx = await ckbRgbppUnlockSinger.signTransaction(ckbPartialTxInjected);
  await rgbppSignedCkbTx.completeFeeBy(ckbSigner);
  const ckbFinalTx = await ckbSigner.signTransaction(rgbppSignedCkbTx);
  const txHash = await ckbSigner.client.sendTransaction(ckbFinalTx);
  
  return txHash;
}

2. Token Transfer on Bitcoin

The process of transferring RGB++ xUDT tokens on Bitcoin follows a similar pattern to the issuance process. The unique ID obtained during issuance is used to construct the xUDT script that identifies the token.

Code Example: Token Transfer

async function transferUdt({
  udtScriptInfo,
  receivers,
}: {
  udtScriptInfo: ScriptInfo;
  receivers: RgbppBtcReceiver[];
}) {
  const udt = new ccc.udt.Udt(
    udtScriptInfo.cellDep.outPoint,
    udtScriptInfo.script,
  );
  
  // Complete the outputs
  let { res: tx } = await udt.transfer(
    ckbSigner as unknown as ccc.Signer,
    receivers.map((receiver) => ({
      to: rgbppUdtClient.buildPseudoRgbppLockScript(),
      amount: ccc.fixedPointFrom(receiver.amount),
    })),
  );
  
  // Auto complete the xUDT inputs
  const txWithInputs = await udt.completeChangeToLock(
    tx,
    ckbRgbppUnlockSinger,
    rgbppUdtClient.buildPseudoRgbppLockScript(),
  );

  // Continue with Bitcoin transaction submission...
}

3. Leap to CKB

The process of leaping xUDT from Bitcoin to CKB follows the same pattern as regular transfer, with one key distinction: after the leap, the lock script changes from RGBPP_Lock to BTC_TIME_lock.

Code Example: Leap to CKB

async function btcUdtToCkb({
  udtScriptInfo,
  receivers,
}: {
  udtScriptInfo: ScriptInfo;
  receivers: { address: string; amount: bigint }[];
}) {
  const udt = new ccc.udt.Udt(
    udtScriptInfo.cellDep.outPoint,
    udtScriptInfo.script,
  );

  let { res: tx } = await udt.transfer(
    ckbSigner as unknown as ccc.Signer,
    await Promise.all(
      receivers.map(async (receiver) => ({
        // build the BTC_TIME_lock script
        to: await rgbppUdtClient.buildBtcTimeLockScript(receiver.address),
        amount: ccc.fixedPointFrom(receiver.amount),
      })),
    ),
  );

  // Continue with transaction processing...
}

4. Unlocking BTC_TIME_lock

This process is straightforward. Wait for the required number of confirmations (default is 6) before unlocking the BTC_TIME_lock. After unlocking, the xUDT becomes a standard CKB asset.

Important Note

This process does not require any Bitcoin transaction. Only CKB transaction is needed to unlock the time lock.

API Configuration

Testnet Configuration

API Endpoint:https://api.testnet.rgbpp.io

Network:Bitcoin Testnet3 + CKB Testnet

Token Generation:Available via /token/generate API

Mainnet Configuration

Access:Whitelisted users only

Network:Bitcoin Mainnet + CKB Mainnet

Contact:Request access token from team

What's Next?

Now that you understand the basics, dive deeper into RGB++ concepts and explore advanced features.

Quick Start