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 occurred.

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

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

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, ranging from p2sh to segwit.

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

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) getMedianTime(prev, timenullable) → {Promise}

Calculate median time past.

Parameters:
Name Type Attributes Description
prev ChainEntry
time Number <nullable>
Source:
Returns:
  • Returns Number.
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

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) getState(prev, id) → {Promise}

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

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
id String

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

(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

(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. Necessary for bip30.

Parameters:
Name Type Description
tx TX
Source:
See:
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

(async) invalidate(hash) → {Promise}

Invalidate block.

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

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

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

Parameters:
Name Type Description
prev ChainEntry

Previous chain entry.
id String

Deployment id.
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) 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(prev, first) → {Number}

Retarget. This is called when the chain height hits a retarget diff interval.

Parameters:
Name Type Description
prev ChainEntry

Previous entry.
first ChainEntry

Chain entry from 2 weeks prior.
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 valid block that comes in. It may add and connect the block (main chain), save the block without connection (alternate chain), or reorganize the chain (a higher fork).

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, 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, private) verifyDuplicates(block, prev) → {Promise}

Determine whether to check block for duplicate txids in blockchain history (BIP30). If we're on a chain that has bip34 activated, we can skip this.

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

(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