Class SRC20TokenBuilder

High-level builder for creating SRC-20 token transactions

Remarks

SRC20TokenBuilder simplifies the creation of SRC-20 token transactions by handling:

Token deployment, minting, and transfer operations
Automatic encoding of SRC-20 protocol data
Multi-signature output creation for data storage
UTXO selection with asset protection
Optimized fee calculation for token transactions

Features:

Support for all SRC-20 operations (DEPLOY, MINT, TRANSFER)
Automatic data validation and encoding
Built-in UTXO protection for special assets
Configurable fee rates and selection algorithms
Compatible with Stampchain protocol standards

Example

const builder = new SRC20TokenBuilder({
  network: networks.bitcoin,
  feeRate: 15
});

// Deploy a new token
const deployResult = await builder.buildSRC20Transaction({
  encodedData: await encoder.encode({
    p: 'SRC-20',
    op: 'DEPLOY',
    tick: 'MYTOKEN',
    max: '1000000',
    lim: '1000'
  }),
  utxos: availableUTXOs,
  changeAddress: 'bc1q...',
  feeRate: 20
});

Hierarchy (View Summary)

TransactionBuilder
- SRC20TokenBuilder

Implements

ISRC20TokenBuilder

Constructors

constructor

new SRC20TokenBuilder(
    network: Network,
    selectorFactory: SelectorFactory,
    options?: Partial<SRC20BuilderOptions>,
): SRC20TokenBuilder
Parameters
- network: Network
- selectorFactory: SelectorFactory
- Optionaloptions: Partial<SRC20BuilderOptions>
Returns SRC20TokenBuilder
Overrides TransactionBuilder.constructor
- Defined in builders/src20-token-builder.ts:137

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

buildDeploy

buildDeploy(deployData: SRC20DeployData): Promise<Transaction>
Build a DEPLOY transaction for creating a new SRC-20 token
Parameters
- deployData: SRC20DeployData
Returns Promise<Transaction>
Implementation of ISRC20TokenBuilder.buildDeploy
- Defined in builders/src20-token-builder.ts:180

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

buildMint

buildMint(mintData: SRC20MintData): Promise<Transaction>
Build a MINT transaction for minting SRC-20 tokens
Parameters
- mintData: SRC20MintData
Returns Promise<Transaction>
Implementation of ISRC20TokenBuilder.buildMint
- Defined in builders/src20-token-builder.ts:281

buildTokenDeploy

buildTokenDeploy(
utxos: UTXO[],
options: TokenDeployOptions,
): Promise<SRC20BuildResult>
Build a token deploy transaction
Parameters
- utxos: UTXO[]
- options: TokenDeployOptions
Returns Promise<SRC20BuildResult>
- Defined in builders/src20-token-builder.ts:922

buildTokenMint

buildTokenMint(
utxos: UTXO[],
options: TokenMintOptions,
): Promise<SRC20BuildResult>
Build a token mint transaction
Parameters
- utxos: UTXO[]
- options: TokenMintOptions
Returns Promise<SRC20BuildResult>
- Defined in builders/src20-token-builder.ts:800

buildTokenTransfer

buildTokenTransfer(
utxos: UTXO[],
options: TokenTransferOptions,
): Promise<SRC20BuildResult>
Build a token transfer transaction
Parameters
- utxos: UTXO[]
- options: TokenTransferOptions
Returns Promise<SRC20BuildResult>
- Defined in builders/src20-token-builder.ts:666

buildTransfer

buildTransfer(transferData: SRC20TransferData): Promise<Transaction>
Build a TRANSFER transaction for sending SRC-20 tokens
Parameters
- transferData: SRC20TransferData
Returns Promise<Transaction>
Implementation of ISRC20TokenBuilder.buildTransfer
- Defined in builders/src20-token-builder.ts:380

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

estimateTransactionCost

estimateTransactionCost(
    numInputs: number,
    numDataOutputs: number,
    includeRecipient: boolean,
    feeRate: number,
): number
Estimate transaction cost
Parameters
- numInputs: number
- numDataOutputs: number
- includeRecipient: boolean
- feeRate: number
Returns number
- Defined in builders/src20-token-builder.ts:1096

`Protected`estimateTransactionSize

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

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

getSRC20DustValue

getSRC20DustValue(): number
Get SRC-20 dust value - instance method

Returns number
- Defined in builders/src20-token-builder.ts:1054

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,
): EnhancedSelectionResult
Select UTXOs for a transaction using the configured selector
Parameters
- utxos: UTXO[]
- targetValue: number
- feeRate: number
- dustThreshold: number
Returns EnhancedSelectionResult
- Defined in builders/src20-token-builder.ts:605

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

validateAmount

validateAmount(amount: any): boolean
Validate amount string
Parameters
- amount: any
Returns boolean
- Defined in builders/src20-token-builder.ts:1078

validateTick

validateTick(tick: string): boolean
Validate tick symbol - SRC-20 protocol enforces 5 character maximum
Parameters
- tick: string
Returns boolean
- Defined in builders/src20-token-builder.ts:1068

`Static`getDustValue

getDustValue(): number
Get SRC-20 dust value - static method

Returns number
- Defined in builders/src20-token-builder.ts:1061

Class SRC20TokenBuilder

Remarks

Example

Hierarchy (View Summary)

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns SRC20TokenBuilder

Properties

ReadonlydustThreshold

ReadonlyenableCPFP

ReadonlyenableRBF

ReadonlyfeeRate

ReadonlymaxInputs

Readonlynetwork

Methods

addChange

Parameters

Returns void

addInputs

Parameters

Returns Promise<void>

addOutputs

Parameters

Returns Promise<void>

buildDeploy

Parameters

Returns Promise<Transaction>

buildFromUTXOs

Parameters

Returns Psbt & { outputCount: number }

buildMint

Parameters

Returns Promise<Transaction>

buildTokenDeploy

Parameters

Returns Promise<SRC20BuildResult>

buildTokenMint

Parameters

Returns Promise<SRC20BuildResult>

buildTokenTransfer

Parameters

Returns Promise<SRC20BuildResult>

buildTransfer

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

estimateTransactionCost

Parameters

Returns number

ProtectedestimateTransactionSize

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

`Static`getDustValue