Class: Chain

blockchain.Chain(options)

Blockchain

Constructor

new Chain(options)

Create a blockchain.

Parameters:
Name Type Description
options Object
Properties:
Name Type Attributes Description
db ChainDB
tip ChainEntry <nullable>
height Number
state DeploymentState
Source:

Methods

(async, private) _add(block, flagsnullable, idnullable) → {Promise}

Add a block to the chain without a lock.

Parameters:
Name Type Attributes Description
block Block
flags Number <nullable>
id Number <nullable>
Source:
Returns:
Type
Promise

(async, private) _getLocator(startnullable) → {Promise}

Calculate chain locator without a lock.

Parameters:
Name Type Attributes Description
start Hash <nullable>
Source:
Returns:
Type
Promise

(async) _invalidate(hash) → {Promise}

Invalidate block (no lock).

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Promise

(async, private) _replay(block, silentnullable) → {Promise}

Reset the chain without a lock.

Parameters:
Name Type Attributes Description
block Hash | Number

hash/height
silent Boolean <nullable>
Source:
Returns:
Type
Promise

(async, private) _reset(block) → {Promise}

Reset the chain to the desired block without a lock.

Parameters:
Name Type Description
block Hash | Number
Source:
Returns:
Type
Promise

(async, private) _verifyBlock(block) → {Promise}

Perform all necessary contextual verification on a block, without POW check (no lock).

Parameters:
Name Type Description
block Block
Source:
Returns:
Type
Promise

(async) add(block, flagsnullable, idnullable) → {Promise}

Add a block to the chain, perform all necessary verification.

Parameters:
Name Type Attributes Description
block Block
flags Number <nullable>
id Number <nullable>
Source:
Returns:
Type
Promise

(private) addOrphan(orphan) → {Orphan}

Add an orphan.

Parameters:
Name Type Description
orphan Orphan
Source:
Returns:
Type
Orphan

(async) close() → {Promise}

Close the chain, wait for the database to close.

Source:
Returns:
Type
Promise

(async) computeBlockVersion(prev) → {Promise}

Compute the version for a new block (BIP9: versionbits).

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry (usually the tip).
Source:
See:
Returns:
  • Returns Number.
Type
Promise

(async, private) connect(prev, block, flags) → {Promise}

Connect block to chain.

Parameters:
Name Type Description
prev ChainEntry
block Block
flags Number
Source:
Returns:
Type
Promise

(async) disconnect(entry) → {Promise}

Disconnect an entry from the chain (updates the tip).

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
Type
Promise

(async, private) findFork(fork, longer) → {Promise}

Find the block at which a fork ocurred.

Parameters:
Name Type Description
fork ChainEntry

The current chain.
longer ChainEntry

The competing chain.
Source:
Returns:
Type
Promise

(async) findLocator(locator) → {Promise}

Find a locator. Analagous to bitcoind's FindForkInGlobalIndex().

Parameters:
Name Type Description
locator Array.<Hash>

Hashes.
Source:
Returns:
  • Returns Hash (the hash of the latest known block).
Type
Promise

getAncestor(entry, height) → {Promise}

Get ancestor by height.

Parameters:
Name Type Description
entry ChainEntry
height Number
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

(async) getBIP9Stats(prev, deployment) → {Promise}

Get signalling statistics for BIP9/versionbits soft fork

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
deployment Obejct

Deployment.
Source:
Returns:
  • Returns JSON object.
Type
Promise

getBlock(hash) → {Promise}

Retrieve a block from the database (not filled with coins).

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Block.
Type
Promise

getBlockView(hash) → {Promise}

Get a historical block coin viewpoint.

Parameters:
Name Type Description
hash Block
Source:
Returns:
  • Returns CoinView.
Type
Promise

getCoin(hash, index) → {Promise}

Get a coin (unspents only).

Parameters:
Name Type Description
hash Hash
index Number
Source:
Returns:
  • Returns Coin.
Type
Promise

getCoinsByAddress(addrs) → {Promise}

Get all coins pertinent to an address.

Parameters:
Name Type Description
addrs Array.<Address>
Source:
Returns:
  • Returns Coin[].
Type
Promise

getCoinView(tx) → {Promise}

Get coin viewpoint.

Parameters:
Name Type Description
tx TX
Source:
Returns:
  • Returns CoinView.
Type
Promise

(async) getCurrentTarget() → {Promise}

Calculate the next target based on the chain tip.

Source:
Returns:
  • returns Number (target is in compact/mantissa form).
Type
Promise

(async) getDeployments(time, prev) → {Promise}

Check all deployments on a chain.

Parameters:
Name Type Description
time Number
prev ChainEntry
Source:
Returns:
  • Returns DeploymentState.
Type
Promise

(async, private) getDeploymentState() → {Promise}

Get the current deployment state of the chain. Called on load.

Source:
Returns:
  • Returns DeploymentState.
Type
Promise

getEntry(hash/height) → {Promise}

Find the corresponding block entry by hash or height.

Parameters:
Name Type Description
hash/height Hash | Number
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getEntryByHash(hash) → {Promise}

Retrieve a chain entry by hash.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getEntryByHeight(height) → {Promise}

Retrieve a chain entry by height.

Parameters:
Name Type Description
height Number
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getHash(height) → {Promise}

Get the hash of a block by height. Note that this will only return hashes in the main chain.

Parameters:
Name Type Description
height Number
Source:
Returns:
Type
Promise

getHashes(startopt, endopt) → {Promise}

Get range of hashes.

Parameters:
Name Type Attributes Default Description
start Number <optional>
 -1
end Number <optional>
 -1
Source:
Returns:
Type
Promise

getHashesByAddress(addrs) → {Promise}

Get all transaction hashes to an address.

Parameters:
Name Type Description
addrs Array.<Address>
Source:
Returns:
Type
Promise

getHeight(hash) → {Promise}

Get the height of a block by hash.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Number.
Type
Promise

(async) getLocator(startnullable) → {Promise}

Calculate chain locator (an array of hashes).

Parameters:
Name Type Attributes Description
start Hash <nullable>

Height or hash to treat as the tip. The current tip will be used if not present. Note that this can be a non-existent hash, which is useful for headers-first locators.
Source:
Returns:
Type
Promise

(async) getLocks(prev, tx, view, flags) → {Promise}

Get the necessary minimum time and height sequence locks for a transaction.

Parameters:
Name Type Description
prev ChainEntry
tx TX
view CoinView
flags LockFlags
Source:
Returns:
Type
Promise

(async) getMainHeight(hash) → {Number}

Get main chain height for hash.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Number

(async) getMedianTime(prev) → {Promise}

Calculate median time past.

Parameters:
Name Type Description
prev ChainEntry
Source:
Returns:
  • Returns Number.
Type
Promise

getMeta(hash) → {Promise}

Get a transaction with metadata.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns TXMeta.
Type
Promise

getMetaByAddress(addrs) → {Promise}

Get all transactions pertinent to an address.

Parameters:
Name Type Description
addrs Array.<Address>
Source:
Returns:
  • Returns TXMeta[].
Type
Promise

getNext(entry) → {Promise}

Get next entry.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getNextEntry(entry) → {Promise}

Get next entry.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getNextHash(hash) → {Promise}

Get the next block hash (does not work by height).

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Promise

(async, private) getNextState() → {Promise}

Get the next deployment state of the chain.

Source:
Returns:
  • Returns DeploymentState.
Type
Promise

getOrphan(hash) → {Block}

Get an orphan block.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Block

getOrphanRoot(hash) → {Hash}

Calculate the orphan root of the hash (if it is an orphan).

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Hash

getPrevCache(entry) → {ChainEntry|null}

Get previous cached entry.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
Type
ChainEntry | null

getPrevious(entry) → {Promise}

Get previous entry.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
  • Returns ChainEntry.
Type
Promise

getProgress() → {Number}

Get the fill percentage.

Source:
Returns:

percent - Ranges from 0.0 to 1.0.

Type
Number

getProofTime(to, from) → {Number}

Calculate the time difference (in seconds) between two blocks by examining chainworks.

Parameters:
Name Type Description
to ChainEntry
from ChainEntry
Source:
Returns:
Type
Number

getRawBlock(hash) → {Promise}

Retrieve a block from the database (not filled with coins).

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Block.
Type
Promise

(async) getSafeRoot() → {Hash}

Get safe tree root.

Source:
Returns:
Type
Hash

(async) getSpentView(tx) → {Promise}

Get coin viewpoint (spent).

Parameters:
Name Type Description
tx TX
Source:
Returns:
  • Returns CoinView.
Type
Promise

(async) getState(prev, deployment) → {Promise}

Get chain entry state for a deployment (BIP9: versionbits).

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
deployment Object

Deployment.
Source:
See:
Returns:
  • Returns Number.
Type
Promise
Example
await chain.getState(tip, deployments.segwit);

(async) getSuitableBlock(prev) → {Promise}

Get median block by timestamp.

Parameters:
Name Type Description
prev ChainEntry
Source:
Returns:
Type
Promise

(async) getTarget(time, prev) → {Promise}

Calculate the next target.

Parameters:
Name Type Description
time Number

Next block timestamp.
prev ChainEntry

Previous entry.
Source:
Returns:
  • returns Number (target is in compact/mantissa form).
Type
Promise

getTips() → {Promise}

Get all tip hashes.

Source:
Returns:
Type
Promise

getTX(hash) → {Promise}

Retrieve a transaction.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns TX.
Type
Promise

getTXByAddress(addrs) → {Promise}

Get all transactions pertinent to an address.

Parameters:
Name Type Description
addrs Array.<Address>
Source:
Returns:
  • Returns TX[].
Type
Promise

(async, private) handleOrphans(entry) → {Promise}

Handle orphans.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
Type
Promise

(async) has(hash) → {Promise}

Test the chain to see if it contains a block, or has recently seen a block.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

hasChainwork() → {Boolean}

Test the chain to see if it has the minimum required chainwork for the network.

Source:
Returns:
Type
Boolean

hasCoins(tx) → {Promise}

Check whether coins are still unspent.

Parameters:
Name Type Description
tx TX
Source:
Returns:
  • Returns Boolean.
Type
Promise

hasEntry(hash) → {Promise}

Test the chain to see if it contains a block.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

(private) hasInvalid(block) → {Boolean}

Test whether an invalid block hash has been seen.

Parameters:
Name Type Description
block Block
Source:
Returns:
Type
Boolean

(private) hasNextOrphan(hash) → {Boolean}

Test whether a hash would resolve the next orphan.

Parameters:
Name Type Description
hash Hash

Previous block hash.
Source:
Returns:
Type
Boolean

hasOrphan(hash) → {Promise}

Test the chain to see if it contains an orphan.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

hasPending(hash) → {Promise}

Test the chain to see if it contains a pending block in its queue.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

hasTX(hash) → {Promise}

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

(async) invalidate(hash) → {Promise}

Invalidate block.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
Type
Promise

(async) isActive(prev, deployment) → {Promise}

Check whether a versionbits deployment is active (BIP9: versionbits).

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
deployment Object

Deployment.
Source:
See:
Returns:
  • Returns Number.
Type
Promise
Example
await chain.isActive(tip, deployments.segwit);

isFull() → {Boolean}

Test the chain to see if it is synced.

Source:
Returns:
Type
Boolean

isHistorical(prev) → {Boolean}

Test whether the entry is potentially an ancestor of a checkpoint.

Parameters:
Name Type Description
prev ChainEntry
Source:
Returns:
Type
Boolean

isMainChain(entry) → {Promise}

Test whether the entry is in the main chain.

Parameters:
Name Type Description
entry ChainEntry
Source:
Returns:
  • Returns Boolean.
Type
Promise

isMainHash(hash) → {Promise}

Test whether the hash is in the main chain.

Parameters:
Name Type Description
hash Hash
Source:
Returns:
  • Returns Boolean.
Type
Promise

(private) isSlow() → {Boolean}

Test whether the chain has reached its slow height.

Source:
Returns:
Type
Boolean

limitOrphans()

Prune orphans, only keep the orphan with the highest coinbase height (likely to be the peer's tip).

Source:

(private) logStatus(start, block, entry)

Calculate the time difference from start time and log block.

Parameters:
Name Type Description
start Array
block Block
entry ChainEntry
Source:

(private) maybeSync()

Potentially emit a full event.

Source:

(async) open() → {Promise}

Open the chain, wait for the database to load.

Source:
Returns:
Type
Promise

(async) prune() → {Promise}

Retroactively prune the database.

Source:
Returns:
Type
Promise

purgeOrphans()

Purge any waiting orphans.

Source:

(private) readCoin(prevout) → {Promise}

Get a coin (unspents only).

Parameters:
Name Type Description
prevout Outpoint
Source:
Returns:
  • Returns CoinEntry.
Type
Promise

(async, private) readDeploymentState() → {Promise}

Get deployment state.

Source:
Returns:
  • Returns DeploymentState.
Type
Promise

(async) reconnect(entry, flags) → {Promise}

Reconnect an entry to the chain (updates the tip). This will do contextual-verification on the block (necessary because we cannot validate the inputs in alternate chains when they come in).

Parameters:
Name Type Description
entry ChainEntry
flags Number
Source:
Returns:
Type
Promise

(private) removeInvalid(hash)

Forget an invalid block hash.

Parameters:
Name Type Description
hash Hash
Source:

(private) removeOrphan(orphan) → {Orphan}

Remove an orphan.

Parameters:
Name Type Description
orphan Orphan
Source:
Returns:
Type
Orphan

(async, private) reorganize(competitor) → {Promise}

Reorganize the blockchain (connect and disconnect inputs). Called when a competing chain with a higher chainwork is received.

Parameters:
Name Type Description
competitor ChainEntry

The competing chain's tip.
Source:
Returns:
Type
Promise

(async, private) reorganizeSPV(competitor) → {Promise}

Reorganize the blockchain for SPV. This will reset the chain to the fork block.

Parameters:
Name Type Description
competitor ChainEntry

The competing chain's tip.
Source:
Returns:
Type
Promise

(async) replay(block) → {Promise}

Reset the chain to a height or hash. Useful for replaying the blockchain download for SPV.

Parameters:
Name Type Description
block Hash | Number

hash/height
Source:
Returns:
Type
Promise

(async) reset(block) → {Promise}

Reset the chain to the desired block. This is useful for replaying the blockchain download for SPV.

Parameters:
Name Type Description
block Hash | Number
Source:
Returns:
Type
Promise

(private) resolveOrphan(hash) → {Orphan}

Resolve an orphan.

Parameters:
Name Type Description
hash Hash

Previous block hash.
Source:
Returns:
Type
Orphan

retarget(first, last) → {Number}

Calculate the next target.

Parameters:
Name Type Description
first ChainEntry

Suitable block from 1 day prior.
last ChainEntry

Last suitable block.
Source:
Returns:

target - Target in compact/mantissa form.

Type
Number

(async, private) saveAlternate(entry, block, prev, flags) → {Promise}

Save block on an alternate chain.

Parameters:
Name Type Description
entry ChainEntry
block Block
prev ChainEntry
flags Number
Source:
Returns:
Type
Promise

(async) scan(start, filter, iter) → {Promise}

Scan the blockchain for transactions containing specified address hashes.

Parameters:
Name Type Description
start Hash

Block hash to start at.
filter Bloom

Bloom filter containing tx and address hashes.
iter function

Iterator.
Source:
Returns:
Type
Promise

(async, private) setBestChain(entry, block, prev, flags) → {Promise}

Set the best chain. This is called on every incoming block with greater chainwork than the current tip.

Parameters:
Name Type Description
entry ChainEntry
block Block
prev ChainEntry
flags Number
Source:
Returns:
Type
Promise

setDeploymentState(state)

Set a new deployment state.

Parameters:
Name Type Description
state DeploymentState
Source:

(private) setInvalid(hash)

Mark a block as invalid.

Parameters:
Name Type Description
hash Hash
Source:

(private) storeOrphan(block, flagsnullable, idnullable)

Store an orphan.

Parameters:
Name Type Attributes Description
block Block
flags Number <nullable>
id Number <nullable>
Source:

(async) syncTree()

Sync tree state.

Source:

(async, private) unreorganize(fork, last) → {Promise}

Revert a failed reorganization.

Parameters:
Name Type Description
fork ChainEntry

The common ancestor.
last ChainEntry

The previous valid tip.
Source:
Returns:
Type
Promise

(async, private) updateInputs(block, prev) → {Promise}

Spend and update inputs (checkpoints only).

Parameters:
Name Type Description
block Block
prev ChainEntry
Source:
Returns:
  • Returns CoinView.
Type
Promise

(async, private) verify(block, prev, flags) → {Promise}

Contextual verification for a block, including version deployments (IsSuperMajority), versionbits, coinbase height, finality checks.

Parameters:
Name Type Description
block Block
prev ChainEntry
flags Number
Source:
Returns:
  • Returns DeploymentState.
Type
Promise

(async) verifyBlock(block) → {Promise}

Perform all necessary contextual verification on a block, without POW check.

Parameters:
Name Type Description
block Block
Source:
Returns:
Type
Promise

(private) verifyCheckpoint(prev, hash) → {Boolean}

Verify a block hash and height against the checkpoints.

Parameters:
Name Type Description
prev ChainEntry
hash Hash
Source:
Returns:
Type
Boolean

(async, private) verifyContext(block, prev, flags) → {Promise}

Perform all necessary contextual verification on a block.

Parameters:
Name Type Description
block Block
prev ChainEntry
flags Number
Source:
Returns:
  • Returns ContextResult.
Type
Promise

(async) verifyCovenants(tx, view, height, hardened)

Verify covenants.

Parameters:
Name Type Description
tx TX
view CoinView
height Number
hardened Boolean
Source:

(async) verifyFinal(prev, tx, flags) → {Promise}

Check transaction finality, taking into account MEDIAN_TIME_PAST if it is present in the lock flags.

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
tx TX
flags LockFlags
Source:
Returns:
  • Returns Boolean.
Type
Promise

(async, private) verifyInputs(block, prev, state) → {Promise}

Check block transactions for all things pertaining to inputs. This function is important because it is what actually fills the coins into the block. This function will check the block reward, the sigops, the tx values, and execute and verify the scripts (it will attempt to do this on the worker pool). If checkpoints is enabled, it will skip verification for historical data.

Parameters:
Name Type Description
block Block
prev ChainEntry
state DeploymentState
Source:
See:
  • TX#verifyInputs
  • TX#verify
Returns:
  • Returns CoinView.
Type
Promise

(async) verifyLocks(prev, tx, view, flags) → {Promise}

Verify sequence locks.

Parameters:
Name Type Description
prev ChainEntry
tx TX
view CoinView
flags LockFlags
Source:
Returns:
  • Returns Boolean.
Type
Promise

(async) verifyRenewal(hash, height) → {Boolean}

Verify a renewal.

Parameters:
Name Type Description
hash Hash
height Number
Source:
Returns:
Type
Boolean