chaingate
Version:
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
157 lines (156 loc) • 6.05 kB
TypeScript
/**
* Abstract base class for UTXO-family transactions (BTC/LTC/DOGE/BCH).
*
* Contains all shared logic: fee estimation, UTXO gathering/selection,
* sign-and-broadcast flow, and local UTXO cache management.
*
* Subclasses only need to implement {@link signTransaction} (network-specific
* signing) and a static `create()` factory.
*
* @internal
*/
import type { UtxoExplorer } from '../../Explorer/UtxoExplorer';
import type { UtxoFeeRateResponse } from '../../Client';
import type { UtxoNetworkParams } from '../../ChainGate/networks/types';
import { BroadcastedUtxoTransaction } from './BroadcastedUtxoTransaction';
import { Amount } from '../../utils/Amount';
/** Fee tier names (shared by all UTXO-family transactions). */
export type UtxoFeeTier = 'low' | 'normal' | 'high' | 'maximum';
/** Custom fee parameters for UTXO transactions. */
export interface UtxoFee {
/** Fee rate in satoshis per kilobyte. */
feePerKbSat: bigint;
}
/** A recommended fee tier with per-kB rate, estimated amount, confirmation time, and balance check. */
export interface UtxoRecommendedFee {
/** Fee rate in satoshis per kilobyte. */
feePerKbSat: bigint;
/** Estimated fee for this specific transaction in satoshis, or `null` if not enough funds. */
estimatedFeeSat: bigint | null;
/** Estimated seconds until confirmation. */
estimatedConfirmationSecs: number;
/** Whether the wallet has enough funds to cover the transfer plus this fee. */
enoughFunds: boolean;
/**
* Additional satoshis needed for the transaction to be broadcastable at this fee.
* Present only when `enoughFunds` is `false`, and `null` when the gap cannot
* be estimated.
*/
missingFunds?: bigint | null;
}
/** All recommended fee tiers. */
export interface UtxoRecommendedFees {
low: UtxoRecommendedFee;
normal: UtxoRecommendedFee;
high: UtxoRecommendedFee;
maximum: UtxoRecommendedFee;
}
/** Internal UTXO representation. */
export interface Txo {
txid: string;
amount: Amount;
n: number;
script: Uint8Array;
}
/** Internal UTXO-gathering state. */
export interface UtxoApiState {
page: number;
utxos: Txo[];
crawled: boolean;
}
/** Constructor parameters for BaseUtxoTransaction. */
export interface BaseUtxoTransactionParams {
explorer: UtxoExplorer;
fromAddress: string;
toAddress: string;
valueSat: bigint;
networkParams: UtxoNetworkParams;
feeRates: UtxoRecommendedFees;
getPrivateKey: () => Promise<Uint8Array>;
state: UtxoApiState;
}
export declare abstract class BaseUtxoTransaction {
protected readonly explorer: UtxoExplorer;
protected readonly fromAddress: string;
protected readonly toAddress: string;
protected readonly valueSat: bigint;
protected readonly networkParams: UtxoNetworkParams;
protected readonly feeRates: UtxoRecommendedFees;
protected readonly getPrivateKey: () => Promise<Uint8Array>;
protected readonly state: UtxoApiState;
protected currentFeePerKbSat: bigint;
protected sent: boolean;
/** @internal */
constructor(params: BaseUtxoTransactionParams);
/**
* Returns all recommended fee tiers (low, normal, high, maximum).
*/
recommendedFees(): UtxoRecommendedFees;
/**
* Returns whether the wallet has enough funds to cover the transfer plus fee
* at the current fee rate.
*/
enoughFunds(): boolean;
/**
* Returns the estimated virtual size (vbytes) of this transaction at the
* current fee rate, or `null` if there are not enough funds.
*/
estimatedSizeBytes(): number | null;
/**
* Sets the fee for this transaction.
*
* Pass a tier object from {@link recommendedFees} or an object with a
* custom `feePerKbSat` value in satoshis per kilobyte.
*
* @throws {@link TransactionAlreadySentError} if the transaction has already been sent.
*/
setFee(fee: UtxoRecommendedFee | UtxoFee): void;
/**
* Signs the transaction with the wallet's private key and broadcasts it to the network.
*
* @throws {@link TransactionAlreadySentError} if the transaction has already been sent.
* @throws {@link NotEnoughFundsError} if the wallet does not have enough funds.
*/
signAndBroadcast(): Promise<BroadcastedUtxoTransaction>;
/**
* Signs a transaction given the selected inputs, outputs, and private key.
* Returns the serialized raw transaction bytes.
*/
protected abstract signTransaction(inputs: Txo[], outputs: Array<{
address: string;
amount: bigint;
}>, privateKey: Uint8Array): Uint8Array;
/** Fetches UTXOs page by page until we have enough to cover the tx, or all are fetched. */
protected findUtxos(feePerKbSat: bigint): Promise<void>;
/** Attempts to select UTXOs and compute outputs. Returns null if insufficient. */
protected selectUtxos(feePerKbSat: bigint): {
inputs: Txo[];
outputs: Array<{
address: string;
amount: bigint;
}>;
fee: bigint;
weight: number;
} | null;
}
/**
* Builds recommended fee tiers by fetching UTXOs and running selection for each tier.
* Shared by all UTXO-family transaction `create()` factories.
* @internal
*/
export declare function buildRecommendedFees(apiResponse: UtxoFeeRateResponse, explorer: UtxoExplorer, fromAddress: string, toAddress: string, valueSat: bigint, networkParams: UtxoNetworkParams, state: UtxoApiState): Promise<UtxoRecommendedFees>;
/**
* Estimates the satoshis missing for a transaction to succeed at a given fee
* rate by re-running selection with a synthetic high-value input that uses the
* same script type as the sender's address. Returns `null` when the gap cannot
* be estimated.
* @internal
*/
export declare function estimateMissingFunds(params: {
utxos: Txo[];
fromAddress: string;
toAddress: string;
valueSat: bigint;
feePerKbSat: bigint;
networkParams: UtxoNetworkParams;
}): bigint | null;