Module: fees

This module provides functions for calculating & validating transaction fees.

Source:

Members

(inner, constant) MAX_FEE_RATE_SATS_PER_VBYTE :BigNumber

Maxmium acceptable transaction fee rate in Satoshis/vbyte.

Type:
  • BigNumber
Default Value:
  • 1000 Satoshis/vbyte
Source:

(inner, constant) MAX_FEE_SATS :BigNumber

Maxmium acceptable transaction fee in Satoshis.

Type:
  • BigNumber
Default Value:
  • 2500000 Satoshis (=0.025 BTC)
Source:

Methods

(static) estimateMultisigTransactionFee(config) → {number}

Estimate transaction fee based on fee rate, address type, number of inputs and outputs.

Parameters:
Name Type Description
config Object

configuration for the calculation

Properties
Name Type Description
addressType module:multisig.MULTISIG_ADDRESS_TYPES

address type used for estimation
numInputs number

number of inputs used in calculation
numOutputs number

number of outputs used in calculation
m number

number of required signers for the quorum
n number

number of total signers for the quorum
feesPerByteInSatoshis string

satoshis per byte fee rate
Source:
Returns:

estimated transaction fee

Type
number
Example
// get fee for P2SH multisig transaction with 2 inputs and 3 outputs at 10 satoshis per byte
import {estimateMultisigP2WSHTransactionFee} from "unchained-bitcoin";
const fee = estimateMultisigTransactionFee({
  addressType: P2SH, 
  numInputs: 2, 
  numOutputs: 3, 
  m: 2,
  n: 3,
  feesPerByteInSatoshis: 10
});

(static) estimateMultisigTransactionFeeRate(config) → {string}

Estimate transaction fee rate based on actual fee and address type, number of inputs and number of outputs.

Parameters:
Name Type Description
config Object

configuration for the calculation

Properties
Name Type Description
addressType module:multisig.MULTISIG_ADDRESS_TYPES

address type used for estimation
numInputs number

number of inputs used in calculation
numOutputs number

number of outputs used in calculation
m number

number of required signers for the quorum
n number

number of total signers for the quorum
feesInSatoshis BigNumber

total transaction fee in satoshis
Source:
Returns:

estimated fee rate

Type
string
Example
import {estimateMultisigP2WSHTransactionFeeRate} from "unchained-bitcoin";
// get the fee rate a P2WSH multisig transaction with 2 inputs and 3 outputs with a known fee of 7060
const feerate = estimateMultisigTransactionFeeRate({
  addressType: P2WSH, 
  numInputs: 2, 
  numOutputs: 3, 
  m: 2,
  n: 3,
  feesInSatoshis: 7060
});

(static) validateFee(feeSats, inputsTotalSats) → {string}

Validate the given transaction fee (in Satoshis).

  • Must be a parseable as a number.

  • Cannot be negative (zero is OK).

  • Cannot exceed the total input amount.

  • Cannot be higher than the limit set by MAX_FEE_SATS.

Parameters:
Name Type Description
feeSats string | number | BigNumber

fee in Satoshis
inputsTotalSats string | number | BigNumber

total input amount in Satoshis
Source:
Returns:

empty if valid or corresponding validation message if not

Type
string
Example
import {validateFee} from "unchained-bitcoin";
console.log(validateFee(3000000, 10000000)) // "Fee is too high."
console.log(validateFee(30000, 20000)) // "Fee is too high."
console.log(validateFee(-30000)) // "Fee cannot be negative."
console.log(validateFee(30000, 10000000)) // ""

(static) validateFeeRate(feeRateSatsPerVbyte) → {string}

Validate the given transaction fee rate (in Satoshis/vbyte).

  • Must be a parseable as a number.

  • Cannot be negative (zero is OK).

  • Cannot be greater than the limit set by MAX_FEE_RATE_SATS_PER_VBYTE.

Parameters:
Name Type Description
feeRateSatsPerVbyte string | number | BigNumber

the fee rate in Satoshis/vbyte
Source:
Returns:

empty if valid or corresponding validation message if not

Type
string
Example
import {validateFeeRate} from "unchained-bitcoin";
console.log(validateFeeRate(-1)); // "Fee rate must be positive."
console.log(validateFeeRate(10000)); // "Fee rate is too high."
console.log(validateFeeRate(250)); // ""