Bigmi Library - Complete Function Documentation

Overview

Bigmi is a TypeScript library for Bitcoin applications that provides a comprehensive set of functions for interacting with the Bitcoin blockchain. It includes actions for querying blockchain data, managing transactions, and working with various Bitcoin data providers.

Core Functions

1. getBalance

getBalance(client: Client, params: { address: string }): Promise<bigint>

Retrieves the balance of a Bitcoin address.

Parameters:

client: The configured client instance
address: The Bitcoin address to check

Returns: The balance in satoshis as a bigint

Example:

const balance = await getBalance(client, { 
  address: "bc1qpvk0kjdg0kantu9z78qz7gqk53q643auz33yaw" 
});

2. getBlock

getBlock(client: Client, params: { blockHash?: string, blockNumber?: number }): Promise<Block>

Retrieves a block by hash or number.

Parameters:

client: The configured client instance
blockHash: The block hash (optional if blockNumber provided)
blockNumber: The block number (optional if blockHash provided)

Returns: A bitcoinjs-lib Block object

Example:

const block = await getBlock(client, { blockNumber: 897002 });

3. getBlockCount

getBlockCount(client: Client): Promise<number>

Gets the current block height of the blockchain.

Parameters:

client: The configured client instance

Returns: The current block count

Example:

const blockCount = await getBlockCount(client);

4. getBlockStats

getBlockStats(client: Client, params: { 
  blockHash?: string, 
  blockNumber?: number, 
  stats?: BlockStatsKeys[] 
}): Promise<BlockStats>

Retrieves statistics about a specific block.

Parameters:

client: The configured client instance
blockHash: The block hash (optional if blockNumber provided)
blockNumber: The block number (optional if blockHash provided)
stats: Array of specific stats to retrieve (optional)

Returns: Block statistics object

Available Stats:

avgfee, avgfeerate, avgtxsize, blockhash, feerate_percentiles
height, ins, maxfee, maxfeerate, maxtxsize
medianfee, mediantime, mediantxsize, minfee, minfeerate
mintxsize, outs, subsidy, swtotal_size, swtotal_weight
swtxs, time, total_out, total_size, total_weight
totalfee, txs, utxo_increase, utxo_size_inc

5. getTransactionFee

getTransactionFee(client: Client, params: { txId: string }): Promise<bigint>

Gets the fee paid for a specific transaction.

Parameters:

client: The configured client instance
txId: The transaction ID

Returns: The transaction fee in satoshis as bigint

Example:

const fee = await getTransactionFee(client, { 
  txId: "4b6ee974f1dd179071d027562e1fd1c83965efa4a171ec84f00b6c638e36fa4e" 
});

6. getTransactions

getTransactions(client: Client, params: {
  address: string,
  offset?: number,
  limit?: number,
  lastBlock?: string,
  afterTxId?: string
}): Promise<{
  transactions: Array<Partial<UTXOTransaction>>,
  total: number,
  hasMore?: boolean
}>

Retrieves transactions for an address with pagination support.

Parameters:

client: The configured client instance
address: The Bitcoin address
offset: Pagination offset (optional)
limit: Number of transactions to return (optional)
lastBlock: Last block to include (optional)
afterTxId: Return transactions after this ID (optional)

Returns: Object containing transactions array and pagination info

7. getUTXOs

getUTXOs(client: Client, params: {
  address: string,
  minValue?: number
}): Promise<Array<UTXO>>

Gets unspent transaction outputs (UTXOs) for an address.

Parameters:

client: The configured client instance
address: The Bitcoin address
minValue: Minimum total value of UTXOs to retrieve (optional)

Returns: Array of UTXO objects

UTXO Object Structure:

{
  txId: string,
  vout: number,
  value: number,
  isConfirmed?: boolean,
  confirmations?: number,
  blockHeight: number,
  scriptHex: string
}

8. getUTXOTransaction

getUTXOTransaction(client: Client, params: {
  txId: string,
  blockHash?: string
}): Promise<UTXOTransaction>

Retrieves detailed information about a specific transaction.

Parameters:

client: The configured client instance
txId: The transaction ID
blockHash: The block hash containing the transaction (optional)

Returns: Detailed transaction object

9. sendUTXOTransaction

sendUTXOTransaction(client: Client, params: {
  hex: string,
  maxFeeRate?: number
}): Promise<string>

Broadcasts a raw transaction to the network.

Parameters:

client: The configured client instance
hex: The hex string of the raw transaction
maxFeeRate: Maximum acceptable fee rate in BTC/kB (optional, default: 0.10)

Returns: The transaction ID

10. signPsbt

signPsbt(client: Client, params: {
  psbt: string,
  inputsToSign: Array<{
    sigHash?: number,
    address: string,
    signingIndexes: number[]
  }>,
  finalize?: boolean
}): Promise<string>

Signs a Partially Signed Bitcoin Transaction (PSBT).

Parameters:

client: The configured client instance
psbt: The PSBT encoded as a hexadecimal string
inputsToSign: Array of input signing details
finalize: Whether to finalize the PSBT after signing (optional)

Returns: The signed PSBT as a hex string

11. waitForTransaction

waitForTransaction(client: Client, params: {
  txId: string,
  txHex: string,
  senderAddress?: string,
  confirmations?: number,
  onReplaced?: (response: ReplacementReturnType) => void,
  pollingInterval?: number,
  retryCount?: number,
  retryDelay?: number | ((config: { count: number; error: Error }) => number),
  timeout?: number
}): Promise<UTXOTransaction>

Waits for a transaction to be confirmed on the blockchain with replacement detection support.

Parameters:

client: The configured client instance
txId: The transaction ID to wait for
txHex: The hex string of the raw transaction
senderAddress: The sender's address (optional, for replacement detection)
confirmations: Number of confirmations to wait for (default: 1)
onReplaced: Callback for transaction replacement events
pollingInterval: Polling frequency in ms
retryCount: Number of retry attempts (default: 10)
retryDelay: Delay between retries
timeout: Maximum wait time in ms

Returns: The confirmed transaction

12. watchBlockNumber

watchBlockNumber(client: Client, params: {
  onBlockNumber: (blockNumber: number, prevBlockNumber?: number) => Promise<void>,
  onError?: (error: Error) => void,
  emitMissed?: boolean,
  emitOnBegin?: boolean,
  pollingInterval?: number
}): () => void

Watches for new blocks and calls a callback when they arrive.

Parameters:

client: The configured client instance
onBlockNumber: Callback function for new blocks
onError: Error handler callback
emitMissed: Whether to emit missed block numbers
emitOnBegin: Whether to emit the latest block on start
pollingInterval: Polling frequency in ms

Returns: A function to stop watching

Transport Providers

1. Ankr Transport

ankr(config?: { baseUrl?: string, apiKey?: string })

Creates a transport using Ankr's API.

Supported Methods:

getBalance
getTransactions
getTransactionFee

2. Blockchair Transport

blockchair(config?: { baseUrl?: string, apiKey?: string })

Creates a transport using Blockchair's API.

Supported Methods:

getBalance
getUTXOs
getTransactionFee

3. Blockcypher Transport

blockcypher(config?: { baseUrl?: string, apiKey?: string })

Creates a transport using Blockcypher's API.

Supported Methods:

getBalance
getUTXOs
getTransactionFee

4. Mempool Transport

mempool(config?: { baseUrl?: string })

Creates a transport using Mempool.space API.

Supported Methods:

getBalance
getTransactions
getTransactionFee

5. HTTP Transport

http(url?: string, config?: HttpTransportConfig)

Creates a generic HTTP JSON-RPC transport.

6. Fallback Transport

fallback(transports: Transport[], config?: FallbackTransportConfig)

Creates a transport that falls back to other transports on failure.

Example:

const transport = fallback([
  blockcypher({ apiKey: 'your-key' }),
  blockchair({ apiKey: 'your-key' }),
  mempool()
]);

Client Creation

createClient

createClient(config: ClientConfig): Client

Creates a client instance for interacting with Bitcoin.

Parameters:

account: Account or address to use
chain: The blockchain configuration
transport: The transport provider
pollingInterval: Default polling interval in ms (default: 4000)
cacheTime: Cache duration in ms (default: 4000)

Example:

import { createClient, bitcoin, mempool } from '@bigmi/core';

const client = createClient({
  chain: bitcoin,
  transport: mempool()
});

Utility Functions

Address Utilities

getAddressInfo

getAddressInfo(address: string): AddressInfo

Parses and validates a Bitcoin address.

Returns:

{
  bech32: boolean,
  network: 'mainnet' | 'testnet' | 'regtest',
  address: string,
  type: 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr',
  purpose: 'payment' | 'ordinals' | 'stacks'
}

isUTXOAddress

isUTXOAddress(address: string, network?: Network): boolean

Validates if a string is a valid Bitcoin address.

Transaction Utilities

cancelTransaction

cancelTransaction(psbt: Psbt, accountAddress: string): Psbt

Creates a replacement transaction that cancels the original by sending funds back to sender.

modifyFee

modifyFee(psbt: Psbt, newFee: bigint, accountAddress: string): Psbt

Modifies the fee of a transaction by adjusting the change output.

Conversion Utilities

hexToBase64

hexToBase64(hex: string): string

base64ToHex

base64ToHex(base64: string): string

stringToHex

stringToHex(value: string): string

hexToUnit8Array

hexToUnit8Array(value: string): Uint8Array

Async Utilities

withRetry

withRetry<T>(fn: () => Promise<T>, options?: {
  delay?: number | ((config: { count: number; error: Error }) => number),
  retryCount?: number,
  shouldRetry?: (config: { count: number; error: Error }) => boolean | Promise<boolean>
}): Promise<T>

Retries an async function with configurable delay and retry logic.

withTimeout

withTimeout<T>(fn: ({ signal }: { signal: AbortSignal | null }) => Promise<T>, options: {
  errorInstance?: Error,
  timeout: number,
  signal?: boolean
}): Promise<T>

Adds a timeout to an async function.

poll

poll<T>(fn: ({ unpoll }: { unpoll: () => void }) => Promise<T | undefined>, options: {
  emitOnBegin?: boolean,
  initialWaitTime?: (data: T | undefined) => Promise<number>,
  interval: number
}): () => void

Polls a function at specified intervals.

Error Types

The library includes specific error types for different scenarios:

InvalidAddressError: Invalid Bitcoin address format
BaseError: Base error class for all library errors
BlockNotFoundError: Block not found
TransactionNotFoundError: Transaction not found
TransactionReceiptNotFoundError: Transaction receipt not found
WaitForTransactionReceiptTimeoutError: Timeout waiting for transaction
InsufficientUTXOBalanceError: Insufficient UTXO balance
HttpRequestError: HTTP request failed
RpcRequestError: RPC request failed
TimeoutError: Request timeout
UserRejectedRequestError: User rejected the request
MethodNotSupportedRpcError: RPC method not supported

Chain Configuration

The library includes a pre-configured Bitcoin mainnet chain:

const bitcoin = {
  id: 20000000000001,
  name: 'Bitcoin',
  nativeCurrency: { name: 'Bitcoin', symbol: 'BTC', decimals: 8 },
  rpcUrls: {
    default: {
      http: ['https://node-router.thorswap.net/bitcoin'],
    },
  },
  blockExplorers: {
    default: {
      name: 'Mempool',
      url: 'https://mempool.space/',
    },
  },
}

You can also define custom chains using defineChain().

ezynda3/bigmi-docs.md

Bigmi Library - Complete Function Documentation

Overview

Core Functions

1. getBalance

2. getBlock

3. getBlockCount

4. getBlockStats

5. getTransactionFee

6. getTransactions

7. getUTXOs

8. getUTXOTransaction

9. sendUTXOTransaction

10. signPsbt

11. waitForTransaction

12. watchBlockNumber

Transport Providers

1. Ankr Transport

2. Blockchair Transport

3. Blockcypher Transport

4. Mempool Transport

5. HTTP Transport

6. Fallback Transport

Client Creation

createClient

Utility Functions

Address Utilities

getAddressInfo

isUTXOAddress

Transaction Utilities

cancelTransaction

modifyFee

Conversion Utilities

hexToBase64

base64ToHex

stringToHex

hexToUnit8Array

Async Utilities

withRetry

withTimeout

poll

Error Types

Chain Configuration