Class BitcoinStampBuilder

High-level builder for creating Bitcoin Stamp transactions

Remarks

BitcoinStampBuilder simplifies the creation of Bitcoin Stamp transactions by handling:

Image/file data encoding and compression
Multi-signature output creation for data storage
UTXO selection with protection for special assets
Fee calculation optimized for stamp transactions
Counterparty protocol integration

Features:

Automatic data compression (gzip/brotli)
Base64 encoding for binary data
CPID support for Counterparty assets
Built-in UTXO protection (Ordinals, Stamps, etc.)
Configurable fee rates and algorithms

Example

const builder = new BitcoinStampBuilder(network, selectorFactory);
const result = await builder.buildStampTransaction(utxos, {
  stampData: {
    imageData: imageBuffer,
    filename: 'art.png'
  },
  fromAddress: 'bc1q...',
  feeRate: 20
});

Hierarchy (View Summary)

TransactionBuilder
- BitcoinStampBuilder

Constructors

constructor

new BitcoinStampBuilder(config: BitcoinStampBuilderConfig): BitcoinStampBuilder
Parameters
- config: BitcoinStampBuilderConfig
Returns BitcoinStampBuilder
Overrides TransactionBuilder.constructor
- Defined in builders/bitcoin-stamp-builder.ts:121

Properties

`Readonly`dustThreshold

dustThreshold: number

`Readonly`enableCPFP

enableCPFP: boolean

`Readonly`enableRBF

enableRBF: boolean

`Readonly`feeRate

feeRate: number

`Readonly`maxInputs

maxInputs: number

`Readonly`network

network: Network

Methods

addChange

addChange(psbt: Psbt, changeAddress: string, changeAmount: number): void
Add change output if needed
Parameters
- psbt: Psbt
- changeAddress: string
- changeAmount: number
Returns void
Inherited from TransactionBuilder.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>
Inherited from TransactionBuilder.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>
Inherited from TransactionBuilder.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 }
Inherited from TransactionBuilder.buildFromUTXOs
- Defined in core/transaction-builder.ts:353

buildIssuance

buildIssuance(issuanceData: BitcoinStampIssuanceData): Promise<Transaction>
Build a simple issuance transaction (for testing or simple asset creation)
Parameters
- issuanceData: BitcoinStampIssuanceData
Returns Promise<Transaction>
- Defined in builders/bitcoin-stamp-builder.ts:309

buildStampTransaction

buildStampTransaction(buildData: BitcoinStampBuildData): Promise<Transaction>
Build a Bitcoin Stamp transaction
Parameters
- buildData: BitcoinStampBuildData
Returns Promise<Transaction>
- Defined in builders/bitcoin-stamp-builder.ts:154

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
Inherited from TransactionBuilder.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 }
Inherited from TransactionBuilder.calculateStampOptimalChange
- 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;
            };
        },
    >,
>
Inherited from TransactionBuilder.calculateStampTransactionFee
- 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 }>
Inherited from TransactionBuilder.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 }>
Inherited from TransactionBuilder.estimateOptimalFee
- 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
Inherited from TransactionBuilder.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
Inherited from TransactionBuilder.estimateSizeWithTypes
- 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;
        },
    >,
>
Inherited from TransactionBuilder.estimateStampTransactionCost
- Defined in core/transaction-builder.ts:513

`Protected`estimateTransactionSize

estimateTransactionSize(numInputs: number, numOutputs: number): number
Estimate transaction size for fee calculation
Parameters
- numInputs: number
- numOutputs: number
Returns number
- Defined in builders/bitcoin-stamp-builder.ts:607

finalize

finalize(psbt: Psbt): Promise<Transaction>
Finalize and extract transaction (with validation)
Parameters
- psbt: Psbt
Returns Promise<Transaction>
Inherited from TransactionBuilder.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
Inherited from TransactionBuilder.getDustThresholds
- 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
Inherited from TransactionBuilder.getNetworkType
- Defined in core/transaction-builder.ts:484

getSrc20MinValue

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

Returns number
Inherited from TransactionBuilder.getSrc20MinValue
- 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;
    };
}
Inherited from TransactionBuilder.getStampFeeRates
- 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
Inherited from TransactionBuilder.isChangeAboveDust
- 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
Inherited from TransactionBuilder.isStampTransaction
- Defined in core/transaction-builder.ts:599

`Protected`selectUTXOs

selectUTXOs(
    utxos: UTXO[],
    targetValue: number,
    feeRate: number,
    dustThreshold: number,
    algorithm?: "accumulative" | "branch-and-bound" | "blackjack" | "knapsack",
): EnhancedSelectionResult
Select UTXOs for a transaction using the configured selector
Parameters
- utxos: UTXO[]
- targetValue: number
- feeRate: number
- dustThreshold: number
- algorithm: "accumulative" | "branch-and-bound" | "blackjack" | "knapsack" = 'accumulative'
Returns EnhancedSelectionResult
- Defined in builders/bitcoin-stamp-builder.ts:532

sign

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

Class BitcoinStampBuilder

Remarks

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns BitcoinStampBuilder

Properties

ReadonlydustThreshold

ReadonlyenableCPFP

ReadonlyenableRBF

ReadonlyfeeRate

ReadonlymaxInputs

Readonlynetwork

Methods

addChange

Parameters

Returns void

addInputs

Parameters

Returns Promise<void>

addOutputs

Parameters

Returns Promise<void>

buildFromUTXOs

Parameters

Returns Psbt & { outputCount: number }

buildIssuance

Parameters

Returns Promise<Transaction>

buildStampTransaction

Parameters

Returns Promise<Transaction>

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; }, >,>

ProtectedestimateTransactionSize

Parameters

Returns 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

`Readonly`dustThreshold

`Readonly`enableCPFP

`Readonly`enableRBF

`Readonly`feeRate

`Readonly`maxInputs

`Readonly`network

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;
},
>,
>

`Protected`estimateTransactionSize

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;
};
}

`Protected`selectUTXOs