unisat-dev-docs

RGB Swap: Pure P2P Mode

Use this mode when both users sign with their own UniSat wallets and the application backend never holds wallet keys or assets. Do not use syncSellSwapAck; that method belongs to the backend-coordinated mode in rgb-swap-backend.md.

Wallet version

The complete flow requires UniSat Wallet v1.8.4 or later because signBuySwapCommit was introduced in v1.8.4. Seller preparation and confirmation APIs are available from v1.8.0; the split buyer signing and ACK APIs are available from v1.8.3.

Feature-detect the required method before starting a swap:

if (typeof window.unisat?.rgb?.signBuySwapCommit !== 'function') {
  throw new Error('Pure P2P RGB swaps require UniSat Wallet v1.8.4+')
}

Required order

Buyer: createReceiveInvoice({ purpose: 'buy_swap' })
  -> Seller: prepareSwap
  -> Seller: signSellSwapAndPublishConsignment
  -> Buyer: signBuySwap using the unsigned colored transaction
  -> Seller: signBuySwapCommit
  -> Buyer: acceptBuySwap
  -> Trading page combines the seller and buyer partial PSBTs
  -> Seller: confirmSellSwap with the fully signed PSBT
  -> Trading page finalizes and broadcasts

signBuySwapCommit must run before acceptBuySwap and before confirmSellSwap. Calling it after confirmSellSwap would create a circular dependency because seller confirmation verifies the buyer ACK.

Seller preparation and publication

// v1.8.3+
const buyerInvoice = await buyer.rgb.createReceiveInvoice({
  assetId,
  amount,
  purpose: 'buy_swap',
})

// v1.8.0+
const prepared = await seller.rgb.prepareSwap({
  invoice: buyerInvoice.invoice,
  assetId,
  amount,
  btcReceiveAmount,
  feeRate,
  psbt: unsignedSwapPsbt,
})

// v1.8.0+
const sellerPartial = await seller.rgb.signSellSwapAndPublishConsignment(
  prepared.transferId,
  prepared.coloredPsbt,
)

The seller wallet creates a unique Proxy sender key for this transfer. The key is encrypted in wallet state and is never returned to the page.

Buyer signing

After the buyer invoice becomes PendingAccept, the buyer signs the same unsigned transaction without seller signatures:

// v1.8.3+
const buyerPartial = await buyer.rgb.signBuySwap({
  recipientId: buyerInvoice.recipientId,
  assetId,
  amount,
  maxBtcSpend,
  swapPsbt: prepared.coloredPsbt,
})

Compute SHA-256 over the binary PSBT decoded from buyerPartial.buyerSignedPsbt, not over the UTF-8 hex characters.

Seller commitment

const buyerSignedPsbtHash = sha256BinaryPsbt(
  buyerPartial.buyerSignedPsbt,
)

// v1.8.4+
const authorization = await seller.rgb.signBuySwapCommit(
  prepared.transferId,
  buyerPartial.txid,
  buyerSignedPsbtHash,
)

// {
//   transferId,
//   proxyTransferId,
//   txid,
//   buyerSignedPsbtHash,
//   commitment
// }

The seller wallet:

The seller’s Bitcoin keys are not used. The signature uses only this transfer’s ephemeral Proxy sender key.

Buyer ACK, final combination and broadcast

// v1.8.3+
await buyer.rgb.acceptBuySwap({
  recipientId: buyerInvoice.recipientId,
  backendCommit: authorization.commitment,
})

const fullySignedPsbt = combinePartialPsbts(
  sellerPartial.makerSignedPsbt,
  buyerPartial.buyerSignedPsbt,
)

// v1.8.0+
const ready = await seller.rgb.confirmSellSwap(
  prepared.transferId,
  fullySignedPsbt,
)
// ready.status === 'ready_for_dapp_finalize'

// The trading page finalizes and broadcasts ready.signedPsbt.

backendCommit is retained as the existing parameter name for compatibility; in pure P2P mode its value is the seller-wallet commitment above.

Cancellation and recovery