Class: Chain

blockchain.Chain

new Chain(options)

Represents a blockchain.

Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
name String <nullable>

Database name.

location String <nullable>

Database file location.

db String <nullable>

Database backend ("leveldb" by default).

orphanLimit Number <nullable>
spv Boolean <nullable>
Properties:
Name Type Attributes Description
loaded Boolean
db ChainDB

Note that Chain options will be passed to the instantiated ChainDB.

total Number
locker Lock
invalid Object
tip ChainEntry <nullable>
height Number
state DeploymentState
orphan Object

Orphan map.

Source:
Fires:
  • Chain#event:open
  • Chain#event:error
  • Chain#event:block
  • Chain#event:competitor
  • Chain#event:resolved
  • Chain#event:checkpoint
  • Chain#event:fork
  • Chain#event:reorganize
  • Chain#event:invalid
  • Chain#event:exists
  • Chain#event:purge
  • Chain#event:connect
  • Chain#event:reconnect
  • Chain#event:disconnect

Methods

(private) _add(block) → {Promise}

Add a block to the chain without a lock.

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

(private) _getLocator(start) → {Promise}

Calculate chain locator without a lock.

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

(private) _init()

Initialize the chain.

Source:

(private) _replay(block) → {Promise}

Reset the chain without a lock.

Parameters:
Name Type Description
block Hash | Number

hash/height

Source:
Returns:
Type
Promise

(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

(private) _resetTime(ts) → {Promise}

Reset the chain to the desired timestamp without a lock.

Parameters:
Name Type Description
ts Number

Timestamp.

Source:
Returns:
Type
Promise

add(block) → {Promise}

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

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

(private) checkHeight(hash) → {Number}

Get the cached height for a hash if present.

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

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

disconnect(entry) → {Promise}

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

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

(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

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

(private) finish(block, entry)

Calculate the time difference from start time and log block.

Parameters:
Name Type Description
block Block
entry ChainEntry
Source:

getCoinView(tx) → {Promise}

Get coin viewpoint.

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

getCurrentTarget() → {Promise}

Calculate the next target based on the chain tip.

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

getDeployments(block, prev) → {Promise}

Check all deployments on a chain, ranging from p2sh to segwit.

Parameters:
Name Type Description
block Block
prev ChainEntry
Source:
Returns:
  • Returns [VerifyError, DeploymentState].
Type
Promise

(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

getLocator(start) → {Promise}

Calculate chain locator (an array of hashes).

Parameters:
Name Type Description
start Hash

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

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:

[Error, Number(minTime), Number(minHeight)].

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

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

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
yield chain.getState(tip, deployments.segwit);

getTarget(block, prev, ancestors) → {Promise}

Calculate the target synchronously. Must have ancestors pre-allocated.

Parameters:
Name Type Description
block Block

Current block.

prev ChainEntry

Previous entry.

ancestors Array:.<ChainEntry:>
Source:
Returns:
  • returns Number (target is in compact/mantissa form).
Type
Promise

getTargetAsync(prev) → {Promise}

Calculate the target based on the passed-in chain entry.

Parameters:
Name Type Description
prev ChainEntry

Previous entry.

Block

Current block.

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

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

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(hash, block) → {Boolean}

Test whether an invalid block hash has been seen.

Parameters:
Name Type Description
hash Hash
block Block
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

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
yield chain.isActive(tip, deployments.segwit);

isFull() → {Boolean}

Test the chain to see if it is synced.

Source:
Returns:
Type
Boolean

isGenesis(block) → {Boolean}

Test whether a block is the genesis block.

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

(private) isSlow() → {Boolean}

Test whether the chain has reached its slow height.

Source:
Returns:
Type
Boolean

(private) mark()

Mark the start time for block processing.

Source:

(private) maybeSync()

Potentially emit a full event.

Source:

pruneOrphans()

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

Source:

purgeOrphans()

Purge any waiting orphans.

Source:

reconnect(entry) → {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
Source:
Returns:
Type
Promise

(private) removeInvalid(hash)

Forget an invalid block hash.

Parameters:
Name Type Description
hash Hash
Source:

(private) reorganize(competitor, block) → {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.

block Block

The being being added.

Source:
Returns:
Type
Promise

(private) reorganizeSPV(competitor, block) → {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.

block Block

The being being added.

Source:
Returns:
Type
Promise

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

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

resetTime(ts) → {Promise}

Reset the chain to the desired timestamp (within 2 hours). This is useful for replaying the blockchain download for SPV.

Parameters:
Name Type Description
ts Number

Timestamp.

Source:
Returns:
Type
Promise

(private) resolveOrphan(hash) → {Block}

Resolve an orphan.

Parameters:
Name Type Description
hash Hash

Previous block hash.

Source:
Returns:
Type
Block

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

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

Save block on an alternate chain.

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

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

(private) seenOrphan(block) → {Boolean}

Verify we do not already have an orphan. Throw if there is an orphan fork.

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

(private) setBestChain(entry, block, prev) → {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
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)

Store an orphan.

Parameters:
Name Type Description
block Block
Source:

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

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

Parameters:
Name Type Description
block Block
prev ChainEntry
Source:
Returns:
  • Returns DeploymentState.
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

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

Perform all necessary contextual verification on a block.

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

(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

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

(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#checkInputs
Returns:
  • Returns CoinView.
Type
Promise

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