Class TransactionBuilder

Main transaction builder for creating Bitcoin transactions with advanced features

Remarks

Provides comprehensive transaction building capabilities including:

UTXO selection and management
Fee calculation and optimization
Multi-signature support
RBF (Replace-By-Fee) configuration
Dust threshold management

Example

const builder = new TransactionBuilder({
  network: networks.bitcoin,
  dustThreshold: 546,
  defaultFeeRate: 10
});

const psbt = await builder.buildTransaction({
  inputs: [...],
  outputs: [...],
  feeRate: 15
});

Hierarchy (View Summary)

TransactionBuilder
- BitcoinStampBuilder
- SRC20TokenBuilder

Implements

ITransactionBuilder

Constructors

constructor

new TransactionBuilder(config: TransactionBuilderConfig): TransactionBuilder
Parameters
- config: TransactionBuilderConfig
Returns TransactionBuilder
- Defined in core/transaction-builder.ts:83

Methods

addChange

addChange(psbt: Psbt, changeAddress: string, changeAmount: number): void
Add change output if needed
Parameters
- psbt: Psbt
- changeAddress: string
- changeAmount: number
Returns void
Implementation of ITransactionBuilder.addChange
- Defined in core/transaction-builder.ts:280

addInputs

addInputs(psbt: Psbt, inputs: TransactionInput[]): Promise<void>
Add inputs to transaction (with validation)
Parameters
- psbt: Psbt
- inputs: TransactionInput[]
Returns Promise<void>
Implementation of ITransactionBuilder.addInputs
- Defined in core/transaction-builder.ts:205

addOutputs

addOutputs(psbt: Psbt, outputs: TransactionOutput[]): Promise<void>
Add outputs to transaction (with validation)
Parameters
- psbt: Psbt
- outputs: TransactionOutput[]
Returns Promise<void>
Implementation of ITransactionBuilder.addOutputs
- Defined in core/transaction-builder.ts:249

buildFromUTXOs

buildFromUTXOs(
    utxos: UTXO[],
    outputs: TransactionOutput[],
    changeAddress: string,
    options?: Partial<BuildOptions>,
): Psbt & { outputCount: number }
Build complete transaction from UTXOs
Parameters
- utxos: UTXO[]
- outputs: TransactionOutput[]
- changeAddress: string
- Optionaloptions: Partial<BuildOptions>
Returns Psbt & { outputCount: number }
Implementation of ITransactionBuilder.buildFromUTXOs
- Defined in core/transaction-builder.ts:353

calculateFee

calculateFee(size: number, feeRate: number): number
Calculate fee based on size and fee rate Simply: size * feeRate
Parameters
- size: number
- feeRate: number
Returns number
Implementation of ITransactionBuilder.calculateFee
- Defined in core/transaction-builder.ts:476

calculateStampOptimalChange

calculateStampOptimalChange(
    inputValue: number,
    outputValue: number,
    estimatedFee: number,
): { changeValue: number; shouldCreateChange: boolean }
Calculate optimal change for stamp transactions
Parameters
- inputValue: number
- outputValue: number
- estimatedFee: number
Returns { changeValue: number; shouldCreateChange: boolean }
- Defined in core/transaction-builder.ts:608

calculateStampTransactionFee

calculateStampTransactionFee(
    params: Src20TransactionParams,
    inputs: { type: InputType; witnessScript?: Buffer<ArrayBufferLike> }[],
    outputs: { size?: number; type: OutputType }[],
    priority?: "low" | "medium" | "high" | "urgent",
): Promise<
    Promise<
        FeeEstimate & {
            normalizedFee: NormalizedFeeRate;
            sizeBreakdown: {
                inputSize: number;
                outputSize: number;
                virtualSize: number;
                witnessSize: number;
            };
            src20Rules: {
                appliedMultiplier: number;
                dataOutputCount: number;
                recommendedFeeRateSatsPerVB: number;
            };
        },
    >,
>
Calculate fee for stamp transaction using SRC-20 calculator
Parameters
- params: Src20TransactionParams
- inputs: { type: InputType; witnessScript?: Buffer<ArrayBufferLike> }[]
- outputs: { size?: number; type: OutputType }[]
- priority: "low" | "medium" | "high" | "urgent" = 'medium'
Returns Promise<
    Promise<
        FeeEstimate & {
            normalizedFee: NormalizedFeeRate;
            sizeBreakdown: {
                inputSize: number;
                outputSize: number;
                virtualSize: number;
                witnessSize: number;
            };
            src20Rules: {
                appliedMultiplier: number;
                dataOutputCount: number;
                recommendedFeeRateSatsPerVB: number;
            };
        },
    >,
>
- Defined in core/transaction-builder.ts:496

create

create(options: BuildOptions): Promise<Psbt & { outputCount: number }>
Create a new transaction
Parameters
- options: BuildOptions
Returns Promise<Psbt & { outputCount: number }>
Implementation of ITransactionBuilder.create
- Defined in core/transaction-builder.ts:124

estimateOptimalFee

estimateOptimalFee(
    inputs: { type: InputType }[],
    outputs: { type: OutputType }[],
    priority?: "low" | "medium" | "high" | "urgent",
): Promise<{ feeRate: number; totalFee: number; virtualSize: number }>
Estimate optimal fee for different input/output combinations
Parameters
- inputs: { type: InputType }[]
- outputs: { type: OutputType }[]
- priority: "low" | "medium" | "high" | "urgent" = 'medium'
Returns Promise<{ feeRate: number; totalFee: number; virtualSize: number }>
- Defined in core/transaction-builder.ts:560

estimateSize

estimateSize(
    inputCount: number,
    outputCount: number,
    hasWitness?: boolean,
): number
Estimate transaction size in bytes Basic formula: ~180 bytes per input + ~34 bytes per output + ~10 bytes overhead
Parameters
- inputCount: number
- outputCount: number
- OptionalhasWitness: boolean
Returns number
Implementation of ITransactionBuilder.estimateSize
- Defined in core/transaction-builder.ts:460

estimateSizeWithTypes

estimateSizeWithTypes(
inputs: { type: InputType }[],
outputs: { type: OutputType }[],
): number
Estimate transaction size with different input/output types
Parameters
- inputs: { type: InputType }[]
- outputs: { type: OutputType }[]
Returns number
- Defined in core/transaction-builder.ts:588

estimateStampTransactionCost

estimateStampTransactionCost(
    params: Src20TransactionParams,
    inputs: { type: InputType; witnessScript?: Buffer<ArrayBufferLike> }[],
    outputs: { size?: number; type: OutputType }[],
    priority?: "low" | "medium" | "high" | "urgent",
): Promise<
    Promise<
        {
            breakdown: {
                baseTransactionFee: number;
                dataPremium: number;
                priorityMultiplier: number;
                stampPremium: number;
            };
            networkFee: number;
            stampValue: number;
            totalCost: number;
        },
    >,
>
Estimate total cost of stamp transaction including stamp value
Parameters
- params: Src20TransactionParams
- inputs: { type: InputType; witnessScript?: Buffer<ArrayBufferLike> }[]
- outputs: { size?: number; type: OutputType }[]
- priority: "low" | "medium" | "high" | "urgent" = 'medium'
Returns Promise<
    Promise<
        {
            breakdown: {
                baseTransactionFee: number;
                dataPremium: number;
                priorityMultiplier: number;
                stampPremium: number;
            };
            networkFee: number;
            stampValue: number;
            totalCost: number;
        },
    >,
>
- Defined in core/transaction-builder.ts:513

finalize

finalize(psbt: Psbt): Promise<Transaction>
Finalize and extract transaction (with validation)
Parameters
- psbt: Psbt
Returns Promise<Transaction>
Implementation of ITransactionBuilder.finalize
- Defined in core/transaction-builder.ts:336

getDustThresholds

getDustThresholds(feeRate?: number): DustThresholds
Get dynamic dust thresholds for different output types
Parameters
- OptionalfeeRate: number
Returns DustThresholds
- Defined in core/transaction-builder.ts:581

getNetworkType

getNetworkType(network?: Network): string
Get network type string from bitcoin.Network Return 'mainnet', 'testnet', or 'regtest' based on network
Parameters
- Optionalnetwork: Network
Returns string
- Defined in core/transaction-builder.ts:484

getSrc20MinValue

getSrc20MinValue(): number
Get SRC-20 minimum value (500,000 satoshis)

Returns number
- Defined in core/transaction-builder.ts:530

getStampFeeRates

getStampFeeRates(): {
    regularWithStamp: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
    stampCreation: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
    stampTransfer: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
}
Get stamp fee rates for different transaction types

Returns {
    regularWithStamp: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
    stampCreation: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
    stampTransfer: {
        high: number;
        low: number;
        medium: number;
        urgent: number;
    };
}
- Defined in core/transaction-builder.ts:537

isChangeAboveDust

isChangeAboveDust(amount: number, outputType?: OutputType): boolean
Check if change amount is above dust threshold
Parameters
- amount: number
- outputType: OutputType = 'P2WPKH'
Returns boolean
- Defined in core/transaction-builder.ts:544

isStampTransaction

isStampTransaction(
    params: {
        dataOutputCount: number;
        isStampCreation: boolean;
        stampValue: number;
    },
): boolean
Check if transaction meets stamp criteria
Parameters
- params: { dataOutputCount: number; isStampCreation: boolean; stampValue: number }
Returns boolean
- Defined in core/transaction-builder.ts:599

sign

sign(psbt: Psbt, options: SignOptions): Promise<void>
Sign transaction
Parameters
- psbt: Psbt
- options: SignOptions
Returns Promise<void>
Implementation of ITransactionBuilder.sign
- Defined in core/transaction-builder.ts:293

Class TransactionBuilder

Remarks

Example

Hierarchy (View Summary)

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns TransactionBuilder

Methods

addChange

Parameters

Returns void

addInputs

Parameters

Returns Promise<void>

addOutputs

Parameters

Returns Promise<void>

buildFromUTXOs

Parameters

Returns Psbt & { outputCount: number }

calculateFee

Parameters

Returns number

calculateStampOptimalChange

Parameters

Returns { changeValue: number; shouldCreateChange: boolean }

calculateStampTransactionFee

Parameters

Returns Promise< Promise< FeeEstimate & { normalizedFee: NormalizedFeeRate; sizeBreakdown: { inputSize: number; outputSize: number; virtualSize: number; witnessSize: number; }; src20Rules: { appliedMultiplier: number; dataOutputCount: number; recommendedFeeRateSatsPerVB: number; }; }, >,>

create

Parameters

Returns Promise<Psbt & { outputCount: number }>

estimateOptimalFee

Parameters

Returns Promise<{ feeRate: number; totalFee: number; virtualSize: number }>

estimateSize

Parameters

Returns number

estimateSizeWithTypes

Parameters

Returns number

estimateStampTransactionCost

Parameters

Returns Promise< Promise< { breakdown: { baseTransactionFee: number; dataPremium: number; priorityMultiplier: number; stampPremium: number; }; networkFee: number; stampValue: number; totalCost: number; }, >,>

finalize

Parameters

Returns Promise<Transaction>

getDustThresholds

Parameters

Returns DustThresholds

getNetworkType

Parameters

Returns string

getSrc20MinValue

Returns number

getStampFeeRates

Returns { regularWithStamp: { high: number; low: number; medium: number; urgent: number; }; stampCreation: { high: number; low: number; medium: number; urgent: number; }; stampTransfer: { high: number; low: number; medium: number; urgent: number; };}

isChangeAboveDust

Parameters

Returns boolean

isStampTransaction

Parameters

Returns boolean

sign

Parameters

Returns Promise<void>

Settings

On This Page

Returns Promise<
Promise<
FeeEstimate & {
normalizedFee: NormalizedFeeRate;
sizeBreakdown: {
inputSize: number;
outputSize: number;
virtualSize: number;
witnessSize: number;
};
src20Rules: {
appliedMultiplier: number;
dataOutputCount: number;
recommendedFeeRateSatsPerVB: number;
};
},
>,
>

Returns Promise<
Promise<
{
breakdown: {
baseTransactionFee: number;
dataPremium: number;
priorityMultiplier: number;
stampPremium: number;
};
networkFee: number;
stampValue: number;
totalCost: number;
},
>,
>

Returns {
regularWithStamp: {
high: number;
low: number;
medium: number;
urgent: number;
};
stampCreation: {
high: number;
low: number;
medium: number;
urgent: number;
};
stampTransfer: {
high: number;
low: number;
medium: number;
urgent: number;
};
}