Class: MTX

MTX

new MTX(options)

A mutable transaction object.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
version Number <nullable>
ps Number <nullable>
changeIndex Number <nullable>
inputs Array.<Input> <nullable>
outputs Array.<Output> <nullable>
Properties:
Name Type Description
type String

"tx" (inv type).
version Number

Transaction version. Note that BCoin reads versions as unsigned even though they are signed at the protocol level. This value will never be negative.
flag Number

Flag field for segregated witness. Always non-zero (1 if not present).
inputs Array.<Input>
outputs Array.<Output>
locktime Number

nLockTime
ts Number

Timestamp of the block the transaction was included in (unix time).
block Hash | null

Hash of the block the transaction was included in.
index Number

Transaction's index in the block tx vector.
ps Number

"Pending Since": The time at which the transaction was first seen. Only non-zero on unconfirmed transactions.
changeIndex Number

Index of the change output (-1 if unknown).
height Number

Height of the block the transaction was included in (-1 if unconfirmed).
rblock ReversedHash | null

Reversed block hash (uint256le).
rhash ReversedHash

Reversed transaction hash (uint256le).
rwhash ReversedHash

Reversed witness transaction hash (uint256le).
txid String

Transaction ID.
wtxid String

Witness transaction ID (Same as txid if no witness is present. All zeroes if coinbase).
Source:

Extends

Members

(static) parseExtended

Source:
See:

(static) parseJSON

Source:
See:

(static) parseRaw

Source:
See:

Methods

(static) fromExtended()

Source:
See:

(static) fromJSON()

Source:
See:

(static) fromRaw()

Source:
See:

(static) isMTX(obj) → {Boolean}

Test whether an object is an MTX.

Parameters:
Name Type Description
obj Object
Source:
Returns:
Type
Boolean

addInput(options, indexnullable)

Add an input to the transaction.

Parameters:
Name Type Attributes Description
options Object | TX | Coin

Options object, transaction, or coin.
index Number <nullable>

Input of output if options is a TX.
Source:
Example
tx.addInput({ prevout: { hash: ... }, sequence: ... });
tx.addInput(prev, prevIndex);
tx.addInput(coin);
tx.addInput(bcoin.coin.fromTX(prev, prevIndex));

addOutput(obj, valuenullable)

Add an output.

Parameters:
Name Type Attributes Description
obj Wallet | KeyRing | Object

Wallet, Address, or options (see Script.createOutputScript for options).
value Amount <nullable>

Only needs to be present for non-options.
Source:
Example
tx.addOutput({ address: ..., value: new bn(100000) });
tx.addOutput({ address: ..., value: utils.satoshi('0.1') });
tx.addOutput(receivingWallet, utils.satoshi('0.1'));

avoidFeeSniping(heightopt, nullable)

Avoid fee sniping.

Parameters:
Name Type Attributes Default Description
height Number <optional>
<nullable>
 network.height

Current chain height.
Source:
See:
  • bitcoin/src/wallet/wallet.cpp

checkInputs(spendHeight, retnullable) → {Boolean}

Perform contextual checks to verify input, output, and fee values, as well as coinbase spend maturity (coinbases can only be spent 100 blocks or more after they're created). Note that this function is consensus critical.

Parameters:
Name Type Attributes Description
spendHeight Number

Height at which the transaction is being spent. In the mempool this is the chain height plus one at the time it entered the pool.
ret Object <nullable>

Return object, may be set with properties reason and score.
Inherited From:
Source:
Returns:
Type
Boolean

clone() → {MTX}

Clone the transaction.

Overrides:
Source:
Returns:
Type
MTX

createSignature(index, prev, type, version) → {Buffer}

Create a signature suitable for inserting into scriptSigs/witnesses.

Parameters:
Name Type Description
index Number

Index of input being signed.
prev Script

Previous output script or redeem script (in the case of witnesspubkeyhash, this should be the generated p2pkh script).
type SighashType
version Number

Sighash version (0=legacy, 1=segwit).
Source:
Returns:

Signature in DER format.

Type
Buffer

fill(coins, options) → {Object}

Select coins and fill the inputs.

Parameters:
Name Type Description
coins Array.<Coin>
options Object

See MTX#selectCoins options.
Source:
Returns:

See MTX#selectCoins return value.

Type
Object

fillCoins(coins) → {Boolean}

Attempt to connect coins to prevouts.

Parameters:
Name Type Description
coins Coin | TX | Array.<Coin> | Array.<TX>
Inherited From:
Source:
Returns:

Whether the transaction is now completely filled.

Type
Boolean

getAddresses() → {Array.<Base58Address>}

Get all addresses.

Inherited From:
Source:
Returns:

addresses

Type
Array.<Base58Address>

getBaseSize() → {Number}

Calculate the size of the transaction without the witness. with the witness included.

Inherited From:
Source:
Returns:

size

Type
Number

getConfirmations(heightnullable) → {Number}

Calculate current number of transaction confirmations.

Parameters:
Name Type Attributes Description
height Number <nullable>

Current chain height. If not present, network chain height will be used.
Inherited From:
Source:
Returns:

confirmations

Type
Number

getCost() → {Number}

Calculate the cost of the transaction. Note that this is cached.

Inherited From:
Source:
Returns:

cost

Type
Number

getFee() → {Amount}

Calculate the fee for the transaction.

Inherited From:
Source:
Returns:

fee (zero if not all coins are available).

Type
Amount

getHashes() → {Array.<Hash>}

Get all address hashes.

Inherited From:
Source:
Returns:

hashes

Type
Array.<Hash>

getInputAddresses() → {Array.<Base58Address>}

Get all input addresses.

Inherited From:
Source:
Returns:

addresses

Type
Array.<Base58Address>

getInputHashes() → {Array.<Hash>}

Get all input address hashes.

Inherited From:
Source:
Returns:

hashes

Type
Array.<Hash>

getInputValue() → {Amount}

Calculate the total input value.

Inherited From:
Source:
Returns:

value

Type
Amount

getLegacySigops() → {Number}

Calculate legacy (inaccurate) sigop count.

Inherited From:
Source:
Returns:

sigop count

Type
Number

getMinFee(sizenullable, ratenullable) → {Amount}

Calculate minimum fee in order for the transaction to be relayable (not the constant min relay fee).

Parameters:
Name Type Attributes Description
size Number <nullable>

If not present, max size estimation will be calculated and used.
rate Rate <nullable>

Rate of satoshi per kB.
Inherited From:
Source:
Returns:

fee

Type
Amount

getModifiedSize(sizenullable) → {Number}

Calculate the modified size of the transaction. This is used in the mempool for calculating priority.

Parameters:
Name Type Attributes Description
size Number <nullable>

The size to modify. If not present, virtual size will be used.
Inherited From:
Source:
Returns:

Modified size.

Type
Number

getOutputAddresses() → {Array.<Base58Address>}

Get all output addresses.

Inherited From:
Source:
Returns:

addresses

Type
Array.<Base58Address>

getOutputHashes() → {Array.<Hash>}

Get all output address hashes.

Inherited From:
Source:
Returns:

hashes

Type
Array.<Hash>

getOutputValue() → {Amount}

Calculate the total output value.

Inherited From:
Source:
Returns:

value

Type
Amount

getPrevout() → {Array.<Hash>}

Get all unique outpoint hashes.

Inherited From:
Source:
Returns:

Outpoint hashes.

Type
Array.<Hash>

getPriority(heightnullable, sizenullable) → {Object}

Calculate the transaction priority.

Parameters:
Name Type Attributes Description
height Number <nullable>

If not present, tx height or mempool height will be used.
size Number <nullable>

Size to calculate priority based on. If not present, modified size will be calculated and used.
Inherited From:
Source:
Returns:

data - Object containing priority and value.

Type
Object

getRate(sizenullable) → {Rate}

Calculate the transaction's rate based on size and fees. Size will be calculated if not present.

Parameters:
Name Type Attributes Description
size Number <nullable>
Inherited From:
Source:
Returns:
Type
Rate

getRaw() → {Buffer}

Serialize the transaction. Note that this is cached. This will use the witness serialization if a witness is present.

Inherited From:
Source:
Returns:

Serialized transaction.

Type
Buffer

getRoundFee(sizenullable, ratenullable) → {Amount}

Calculate the minimum fee in order for the transaction to be relayable, but _round to the nearest kilobyte when taking into account size.

Parameters:
Name Type Attributes Description
size Number <nullable>

If not present, max size estimation will be calculated and used.
rate Rate <nullable>

Rate of satoshi per kB.
Inherited From:
Source:
Returns:

fee

Type
Amount

getScripthashSigops() → {Number}

Calculate accurate sigop count, taking into account redeem scripts.

Inherited From:
Source:
Returns:

sigop count

Type
Number

getSigops(flagsnullable) → {Number}

Calculate virtual sigop count.

Parameters:
Name Type Attributes Description
flags VerifyFlags <nullable>
Inherited From:
Source:
Returns:

sigop count

Type
Number

getSigopsCost(flagsnullable) → {Number}

Calculate sigops cost, taking into account witness programs.

Parameters:
Name Type Attributes Description
flags VerifyFlags <nullable>
Inherited From:
Source:
Returns:

sigop cost

Type
Number

getSize() → {Number}

Calculate the real size of the transaction with the witness included.

Inherited From:
Source:
Returns:

size

Type
Number

getSizes() → {Object}

Calculate real size and size of the witness bytes.

Inherited From:
Source:
Returns:

Contains size and witnessSize.

Type
Object

getVirtualSize() → {Number}

Calculate the virtual size of the transaction. Note that this is cached.

Inherited From:
Source:
Returns:

vsize

Type
Number

hasCoins() → {Boolean}

Test whether the transaction has all coins available/filled.

Inherited From:
Source:
Returns:
Type
Boolean

hash(encnullable) → {Hash|Buffer}

Hash the transaction with the non-witness serialization.

Parameters:
Name Type Attributes Description
enc String <nullable>

Can be 'hex' or null.
Inherited From:
Source:
Returns:

hash

Type
Hash | Buffer

hasStandardInputs(flagsnullable) → {Boolean}

Perform contextual checks to verify coin and input script standardness (including the redeem script).

Parameters:
Name Type Attributes Description
flags VerifyFlags <nullable>
Inherited From:
Source:
See:
  • AreInputsStandard()
Returns:
Type
Boolean

hasWitness() → {Boolean}

Test whether the transaction has a non-empty witness.

Inherited From:
Source:
Returns:
Type
Boolean

inspect() → {Object}

Inspect the transaction and return a more user-friendly representation of the data.

Inherited From:
Source:
Returns:
Type
Object

isCoinbase() → {Boolean}

Test whether the transaction is a coinbase by examining the inputs.

Inherited From:
Source:
Returns:
Type
Boolean

isFinal(height, ts) → {Boolean}

Check finality of transaction by examining nLockTime and nSequences.

Parameters:
Name Type Description
height Number

Height at which to test. This is usually the chain height, or the chain height + 1 when the transaction entered the mempool.
ts Number

Time at which to test. This is usually the chain tip's parent's median time, or the time at which the transaction entered the mempool. If MEDIAN_TIME_PAST is enabled this will be the median time of the chain tip's previous entry's median time.
Inherited From:
Source:
Returns:
Type
Boolean
Example
tx.isFinal(network.height + 1, utils.now());

isFree(heightnullable, sizenullable) → {Boolean}

Determine whether the transaction is above the free threshold in priority. A transaction which passed this test is most likely relayable without a fee.

Parameters:
Name Type Attributes Description
height Number <nullable>

If not present, tx height or mempool height will be used.
size Number <nullable>

If not present, modified size will be calculated and used.
Inherited From:
Source:
Returns:
Type
Boolean

isSane(retnullable) → {Boolean}

Non-contextual sanity checks for the transaction. Will mostly verify coin and output values.

Parameters:
Name Type Attributes Description
ret Object <nullable>

Return object, may be set with properties reason and score.
Inherited From:
Source:
See:
  • CheckTransaction()
Returns:

sane

Type
Boolean

isScripted() → {Boolean}

Test whether the transaction at least has all script templates built.

Source:
Returns:
Type
Boolean

isSigned() → {Boolean}

Test whether the transaction is fully-signed.

Source:
Returns:
Type
Boolean

isStandard(retnullable) → {Boolean}

Non-contextual checks to determine whether the transaction has all standard output script types and standard input script size with only pushdatas in the code. Will mostly verify coin and output values.

Parameters:
Name Type Attributes Description
ret Object <nullable>

Return object, may be set with properties reason and score.
Inherited From:
Source:
See:
  • IsStandardTx()
Returns:
Type
Boolean

isWatched(filter) → {Boolean}

Test a transaction against a bloom filter using the BIP37 matching algorithm. Note that this may update the filter depending on what the update value is.

Parameters:
Name Type Description
filter Bloom
Inherited From:
Source:
See:
Returns:

True if the transaction matched.

Type
Boolean

maxSize(optionsnullable, force) → {Number}

Estimate maximum possible size.

Parameters:
Name Type Attributes Description
options Wallet | Object <nullable>

Wallet or options object.

Properties
Name Type Description
m Number

Multisig m value.
n Number

Multisig n value.
force Boolean

maxSize will just calculate the virtual size instead of estimating it if the templates are already built. If true, this will force estimation of the size.
Overrides:
Source:
Returns:
Type
Number

render() → {Buffer}

Serialize the transaction. Note that this is cached. This will use the witness serialization if a witness is present.

Inherited From:
Source:
Returns:

Serialized transaction.

Type
Buffer

renderNormal() → {Buffer}

Serialize the transaction without the witness vector, regardless of whether it is a witness transaction or not.

Inherited From:
Source:
Returns:

Serialized transaction.

Type
Buffer

renderWitness() → {Buffer}

Serialize the transaction with the witness vector, regardless of whether it is a witness transaction or not.

Inherited From:
Source:
Returns:

Serialized transaction.

Type
Buffer

scriptInput(index, addr) → {Boolean}

Build input script (or witness) templates (with OP_0 in place of signatures).

Parameters:
Name Type Description
index Number

Input index.
addr Address

Address used to build. The address must be able to redeem the coin.
Source:
Throws:

on unavailable coins.

Returns:

Whether the script was able to be built.

Type
Boolean

scriptOutput(index, options)

Build output script (called automatically from MTX#addOutput).

Parameters:
Name Type Description
index Number

Output index.
options Object

See Script.createOutputScript.
Source:

selectCoins(coins, optionsnullable) → {CoinSelection}

Select necessary coins based on total output value.

Parameters:
Name Type Attributes Description
coins Array.<Coin>
options Object <nullable>
Properties
Name Type Attributes Description
selection String <nullable>

Coin selection priority. Can be age, random, or all. (default=age).
confirmed Boolean

Select only confirmed coins.
round Boolean

Whether to round to the nearest kilobyte for fee calculation. See TX#getMinFee vs. TX#getRoundFee.
free Boolean

Do not apply a fee if the transaction priority is high enough to be considered free.
fee Amount <nullable>

Use a hard fee rather than calculating one.
rate Rate <nullable>

Rate used for fee calculation.
subtractFee Number | Boolean

Whether to subtract the fee from * existing outputs rather than adding more inputs.
Source:
Throws:

  • on not enough funds available.

  • on unable to subtract fee.

Returns:
Type
CoinSelection

setBlock(block, index)

Set the block the transaction was included in.

Parameters:
Name Type Description
block Block | MerkleBlock
index Number
Inherited From:
Source:

setLocktime(locktime)

Set locktime and sequences appropriately.

Parameters:
Name Type Description
locktime Number
Source:

sign(index, addr, key, type) → {Boolean}

Built input scripts (or witnesses) and sign the inputs.

Parameters:
Name Type Description
index Number

Index of input being signed.
addr KeyRing

Address used to sign. The address must be able to redeem the coin.
key HDPrivateKey | KeyPair | Buffer

Private key.
type SighashType
Source:
Throws:

on unavailable coins.

Returns:

Whether the input was able to be signed.

Type
Boolean

signatureHash(index, prev, type, version) → {Buffer}

Get the signature hash of the transaction for signing verifying.

Parameters:
Name Type Description
index Number

Index of input being signed/verified.
prev Script

Previous output script or redeem script (in the case of witnesspubkeyhash, this should be the generated p2pkh script).
type SighashType

Sighash type.
version Number

Sighash version (0=legacy, 1=segwit).
Inherited From:
Source:
Returns:

Signature hash.

Type
Buffer

signInput(index, addr, key, type) → {Boolean}

Sign an input.

Parameters:
Name Type Description
index Number

Index of input being signed.
addr KeyRing

Address used to sign. The address must be able to redeem the coin.
key HDPrivateKey | KeyPair | Buffer

Private key.
type SighashType
Source:
Throws:

on unavailable coins.

Returns:

Whether the input was able to be signed.

Type
Boolean

sortMembers()

Sort inputs and outputs according to BIP69.

Source:
See:

testInputs(addressMap, indexnullable) → {Boolean}

Test the inputs against an address, an array of address hashes, or a map of address hashes.

Parameters:
Name Type Attributes Description
addressMap Hash | Array.<Hash> | AddressHashMap
index Number <nullable>
Inherited From:
Source:
Returns:

Whether the transaction matched.

Type
Boolean

testOutputs(addressMap, indexnullable) → {Boolean}

Test the outputs against an address, an array of address hashes, or a map of address hashes.

Parameters:
Name Type Attributes Description
addressMap Hash | Array.<Hash> | AddressHashMap
index Number <nullable>
Inherited From:
Source:
Returns:

Whether the transaction matched.

Type
Boolean

toCoins() → {Coins}

Convert transaction outputs to a {Coins} object.

Inherited From:
Source:
Returns:
Type
Coins

toExtended(saveCoinsnullable, encnullable) → {Buffer}

Serialize a transaction to BCoin "extended format". This is the serialization format BCoin uses internally to store transactions in the database. The extended serialization includes the height, block hash, index, timestamp, pending-since time, and optionally a vector for the serialized coins.

Parameters:
Name Type Attributes Description
saveCoins Boolean <nullable>

Whether to serialize the coins.
enc String <nullable>

One of "hex" or null.
Inherited From:
Source:
Returns:
Type
Buffer

toInv() → {InvItem}

Convert the tx to an inv item.

Inherited From:
Source:
Returns:
Type
InvItem

toJSON() → {Object}

Convert the transaction to an object suitable for JSON serialization. Note that the hashes will be reversed to abide by bitcoind's legacy of little-endian uint256s.

Inherited From:
Source:
Returns:
Type
Object

toRaw(encnullable) → {Buffer|String}

Serialize the transaction.

Parameters:
Name Type Attributes Description
enc String <nullable>

Encoding, can be 'hex' or null.
Inherited From:
Source:
See:
Returns:
Type
Buffer | String

toTX() → {TX}

Convert the MTX to a TX.

Source:
Returns:
Type
TX

unsetBlock()

Remove all relevant block data from the transaction.

Inherited From:
Source:

verify(indexnullable, forcenullable, flagsnullable) → {Boolean}

Verify the transaction inputs.

Parameters:
Name Type Attributes Description
index Number <nullable>

Index of output being verified. If not present, all outputs will be verified.
force Boolean <nullable>

Force the transaction to be verified, even if it has been confirmed.
flags VerifyFlags <nullable>
Inherited From:
Source:
Returns:

Whether the inputs are valid.

Type
Boolean

verifyAsync(indexnullable, forcenullable, flagsnullable, callback) → {Boolean}

Verify the transaction inputs on the worker pool (if workers are enabled).

Parameters:
Name Type Attributes Description
index Number <nullable>

Index of output being verified. If not present, all outputs will be verified.
force Boolean <nullable>

Force the transaction to be verified, even if it has been confirmed.
flags VerifyFlags <nullable>
callback function
Inherited From:
Source:
Returns:

Whether the inputs are valid.

Type
Boolean

witnessHash(encnullable) → {Hash|Buffer}

Hash the transaction with the witness serialization, return the wtxid (normal hash if no witness is present, all zeroes if coinbase).

Parameters:
Name Type Attributes Description
enc String <nullable>

Can be 'hex' or null.
Inherited From:
Source:
Returns:

hash

Type
Hash | Buffer