Skip to main content

BRC-20 Tokens

The BRC-20 module provides comprehensive functionality for interacting with BRC-20 tokens on Bitcoin, enabling transfers and management of these fungible tokens. This module handles the complex inscription and transaction construction required for BRC-20 operations.

Overview

The BRC-20 module provides:

  • Transfer of BRC-20 tokens between addresses
  • Fee estimation for BRC-20 operations
  • Multi-step transaction handling
  • UTXO management for token operations

Core Operations

Transferring BRC-20 Tokens

Transferring BRC-20 tokens is a three-step process that involves creating a transfer inscription and then sending it:

const sendResult = await send({
gatheredUtxos,
toAddress: "bc1...",
ticker: "ORDI",
amount: 100,
feeRate: 2,
account,
provider,
signer
})

// Returns transaction IDs for all steps
console.log(sendResult.sendBrc20Txids) // [commitTxId, revealTxId, transferTxId]

Fee Estimation

Accurate fee estimation for transfer operations:

const estimate = await transferEstimate({
gatheredUtxos,
toAddress,
feeRate: 2,
account,
provider
})

console.log(estimate.fee) // Estimated fee in satoshis

Transaction Steps

1. Commit Transaction

Creates the initial transaction that will hold the transfer inscription:

const commitResult = await commit({
gatheredUtxos,
ticker: "ORDI",
amount: 100,
feeRate: 2,
tweakedTaprootPublicKey,
account,
provider
})

2. Reveal Transaction

Reveals the inscription content:

const revealResult = await reveal({
receiverAddress,
script,
feeRate: 2,
tweakedTaprootKeyPair,
provider,
commitTxId
})

3. Transfer Transaction

Completes the token transfer:

const transferResult = await transfer({
commitChangeUtxoId,
revealTxId,
toAddress,
feeRate: 2,
account,
provider
})

Best Practices

  1. Transaction Handling

    • Always handle all three steps (commit, reveal, transfer)
    • Monitor transaction confirmations between steps
    • Implement proper error handling for failed transactions
  2. Fee Management

    • Use fee estimation before initiating transfers
    • Account for network congestion in fee calculations
    • Consider fee bumping for stuck transactions
  3. UTXO Management

    • Verify UTXO availability before operations
    • Handle UTXO selection carefully
    • Avoid using UTXOs with existing inscriptions
  4. Security Considerations

    • Validate all addresses and amounts
    • Implement proper transaction signing
    • Test operations on testnet first

Complete Usage Example

Here's a full example of transferring BRC-20 tokens:

import { BRC20 } from 'oyl-sdk/brc20'

// Initialize provider and account
const provider = new Provider(network)
const account = await mnemonicToAccount({ mnemonic, network })

// Gather UTXOs for the operation
const gatheredUtxos = await accountUtxos({
account,
provider
})

// Estimate fees
const estimate = await transferEstimate({
gatheredUtxos,
toAddress,
feeRate: 2,
account,
provider
})

// Execute the transfer
const result = await send({
gatheredUtxos,
toAddress,
ticker: "ORDI",
amount: 100,
feeRate: 2,
account,
provider,
signer
})

// Handle the result
console.log("Transfer complete:", result.sendBrc20Txids)

Error Handling

The module uses the OylTransactionError class for error handling:

try {
await send({ ... })
} catch (error) {
if (error instanceof OylTransactionError) {
console.error('Transaction failed:', error.message)
// Handle specific error cases
}
}

Transaction Monitoring

Monitor transaction progress between steps:

await waitForTransaction({
txId: revealTxId,
sandshrewBtcClient: provider.sandshrew
})

This ensures proper sequencing of the multi-step transfer process and helps prevent transaction failures.