chaingate/dist/Connector/UtxoConnector/CustomUtxoTransaction.d.ts

Multi-chain cryptocurrency SDK for TypeScript — unified API for Bitcoin, Ethereum, Litecoin, Dogecoin, Bitcoin Cash, Polygon, Arbitrum, and any EVM-compatible chain. Create wallets, query balances, send transactions, and manage tokens and NFTs across UTXO

import type { UtxoExplorer } from '../../Explorer/UtxoExplorer';
import type { UtxoNetworkParams } from '../../ChainGate/networks/types';
import { BroadcastedUtxoTransaction } from './BroadcastedUtxoTransaction';
import type { UtxoFee, UtxoRecommendedFee, UtxoRecommendedFees } from './BaseUtxoTransaction';
import type { Amount } from '../../utils/Amount';
/** A single UTXO input for a custom transaction. */
export interface UtxoCustomInput {
    /** Transaction ID of the UTXO to spend. */
    txid: string;
    /** Output index within the referenced transaction. */
    index: number;
    /** UTXO value. */
    amount: Amount;
    /** Locking script of the UTXO (hex-encoded). */
    script: string;
}
/** A single output for a custom transaction. */
export interface UtxoCustomOutput {
    /** Recipient address. */
    address: string;
    /** Amount to send. */
    amount: Amount;
}
/** Parameters accepted by {@link CustomUtxoTransaction}. */
export interface CustomUtxoTransactionParams {
    /** Inputs to spend. */
    inputs: UtxoCustomInput[];
    /** Outputs to create. */
    outputs: UtxoCustomOutput[];
}
/** @internal */
interface InternalParams {
    explorer: UtxoExplorer;
    networkParams: UtxoNetworkParams;
    inputs: UtxoCustomInput[];
    outputs: UtxoCustomOutput[];
    getPrivateKey: () => Promise<Uint8Array>;
    signTransaction: (inputs: UtxoCustomInput[], outputs: UtxoCustomOutput[], privateKey: Uint8Array, networkParams: UtxoNetworkParams) => Uint8Array;
}
/**
 * A UTXO transaction with caller-defined inputs and outputs.
 *
 * The fee is implicitly the difference between the sum of input amounts and
 * the sum of output amounts.
 */
export declare class CustomUtxoTransaction {
    private readonly explorer;
    private readonly networkParams;
    private readonly inputList;
    private readonly outputList;
    private readonly getPrivateKey;
    private readonly _signTransaction;
    private sent;
    /** @internal */
    constructor(params: InternalParams);
    /** Returns the inputs that will be spent. */
    inputs(): readonly UtxoCustomInput[];
    /** Returns the outputs that will be created. */
    outputs(): readonly UtxoCustomOutput[];
    /**
     * Returns the implied fee (sum of inputs minus sum of outputs).
     *
     * A negative value means the outputs exceed the inputs — the transaction
     * would be invalid.
     */
    fee(): Amount;
    /**
     * Returns the estimated virtual size (vbytes) of this transaction.
     *
     * Returns `null` if the transaction has no inputs or no outputs.
     */
    estimatedSizeBytes(): number | null;
    /**
     * Appends an input to the transaction.
     *
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     */
    addInput(input: UtxoCustomInput): void;
    /**
     * Removes an input identified by its transaction ID and output index.
     *
     * @returns `true` if the input was found and removed.
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     */
    removeInput(txid: string, index: number): boolean;
    /**
     * Appends an output to the transaction.
     *
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     */
    addOutput(output: UtxoCustomOutput): void;
    /**
     * Removes an output by its position in the outputs list.
     *
     * @returns `true` if the index was valid and the output was removed.
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     */
    removeOutput(index: number): boolean;
    /**
     * Sets a change address and computes the change output automatically.
     *
     * Appends a change output whose amount equals the remaining value after
     * subtracting all other outputs and the estimated fee. If the change
     * amount is below the dust threshold, no change output is added and
     * the remainder goes entirely to fees.
     *
     * @param address - The address to receive the change.
     * @param fee - A tier object from {@link recommendedFees} or an explicit fee rate.
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     * @throws {Error} if inputs or outputs are empty, or if outputs exceed inputs.
     */
    setChangeAddress(address: string, fee: UtxoRecommendedFee | UtxoFee): void;
    /**
     * Returns recommended fees for each priority tier.
     *
     * Fee rates are fetched from the network. For each tier, the estimated fee
     * is computed from the current inputs and outputs.
     *
     * Returns `null` if the transaction has no inputs or no outputs.
     */
    recommendedFees(): Promise<UtxoRecommendedFees | null>;
    /**
     * Estimates the satoshis missing for the transaction to succeed at a given
     * fee rate by re-running selection with a synthetic high-value input. Returns
     * `null` when the gap cannot be estimated.
     */
    private estimateMissingFunds;
    /**
     * Signs the transaction and broadcasts it to the network.
     *
     * @throws {@link TransactionAlreadySentError} if already broadcast.
     * @throws {Error} if outputs exceed inputs.
     */
    signAndBroadcast(): Promise<BroadcastedUtxoTransaction>;
    private guardNotSent;
    /**
     * Runs selectUTXO with the 'all' strategy so every input is included.
     * Uses the current outputs as-is. Returns null if selection fails.
     */
    private runSelection;
}
/**
 * Standard UTXO signing (BTC, LTC, DOGE, tBTC).
 * @internal
 */
export declare function signCustomUtxoTransaction(inputs: UtxoCustomInput[], outputs: UtxoCustomOutput[], privateKey: Uint8Array, networkParams: UtxoNetworkParams): Uint8Array;
export {};