@bigmi/core/dist/esm/actions/waitForTransaction.d.ts

TypeScript library for Bitcoin apps.

import { Transaction } from 'bitcoinjs-lib';
import type { Chain } from '../types/chain.js';
import type { Client } from '../types/client.js';
import type { UTXOTransaction } from '../types/transaction.js';
import type { Transport } from '../types/transport.js';
export type ReplacementReason = 'cancelled' | 'replaced' | 'repriced';
export type ReplacementReturnType = {
    reason: ReplacementReason;
    replacedTransaction: Transaction;
    transaction: UTXOTransaction;
};
export type WaitForTransactionReceiptReturnType = UTXOTransaction;
export type WithRetryParameters = {
    delay?: ((config: {
        count: number;
        error: Error;
    }) => number) | number | undefined;
    retryCount?: number | undefined;
};
export type WaitForTransactionReceiptParameters = {
    /** The Id of the transaction. */
    txId: string;
    /** The hex string of the raw transaction. */
    txHex: string;
    /** The sender address of the transaction. */
    senderAddress?: string;
    /**
     * The number of confirmations (blocks that have passed) to wait before resolving.
     * @default 1
     */
    confirmations?: number | undefined;
    /** Optional callback to emit if the transaction has been replaced. */
    onReplaced?: ((response: ReplacementReturnType) => void) | undefined;
    /**
     * Polling frequency (in ms). Defaults to the client's pollingInterval config.
     * @default client.pollingInterval
     */
    pollingInterval?: number | undefined;
    /**
     * Number of times to retry if the transaction or block is not found.
     * @default 6 (exponential backoff)
     */
    retryCount?: number;
    /**
     * Time to wait (in ms) between retries.
     */
    retryDelay?: ((config: {
        count: number;
        error: Error;
    }) => number) | number;
    /** Optional timeout (in milliseconds) to wait before stopping polling. */
    timeout?: number | undefined;
};
/**
 * Waits for the transaction to be included on a block (one confirmation), and then returns the transaction.
 * - JSON-RPC Methods:
 * - Polls getrawtransaction on each block until it has been processed.
 * - If a transaction has been replaced:
 * - Calls getblock and extracts the transactions
 * - Checks if one of the transactions is a replacement
 * - If so, calls getrawtransaction.
 *
 * The `waitForTransaction` action additionally supports replacement detection (e.g. RBF - transactions replaced-by-fee ).
 *
 * Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel).
 * https://bitcoinops.org/en/topics/replace-by-fee/
 *
 * There are 3 types of Transaction Replacement reasons:
 *
 * - `repriced`: The fee has been modified (e.g. same outputs, different amounts)
 * - `cancelled`: The Transaction has been cancelled (e.g. output is sender address)
 * - `replaced`: The Transaction has been replaced (e.g. different outputs)
 * @param client - Client to use
 * @param parameters - {@link WaitForTransactionReceiptParameters}
 * @returns The UTXO transaction. {@link WaitForTransactionReceiptReturnType}
 */
export declare function waitForTransaction<chain extends Chain | undefined>(client: Client<Transport, chain>, { confirmations, txId, txHex, senderAddress, onReplaced, pollingInterval, retryCount, retryDelay, timeout, }: WaitForTransactionReceiptParameters): Promise<WaitForTransactionReceiptReturnType>;