new Chain(options)
Represents a blockchain.
Parameters:
| Name | Type | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
Properties
|
Properties:
| Name | Type | Attributes | Description |
|---|---|---|---|
loaded |
Boolean | ||
db |
ChainDB | Note that Chain |
|
total |
Number | ||
orphanLimit |
Number | ||
locker |
Locker | ||
invalid |
Object | ||
bestHeight |
Number | ||
tip |
ChainEntry |
<nullable> |
|
height |
Number | ||
segwitActive |
Boolean | ||
csvActive |
Boolean | ||
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:invalid
- Chain#event:exists
- Chain#event:purge
- Chain#event:add entry
- Chain#event:remove entry
- Chain#event:add block
- Chain#event:remove block
Methods
(private) _checkDeployments(block, prev, ancestors, callback)
Check all deployments on a chain, ranging from p2sh to segwit.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | |
prev |
ChainEntry | |
ancestors |
Array.<ChainEntry> | |
callback |
function | Returns [VerifyError, DeploymentState]. |
- Source:
(private) _checkDuplicates(block, prev, callback)
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 | MerkleBlock | |
prev |
ChainEntry | |
callback |
function | Returns [VerifyError]. |
- Source:
- See:
(private) _checkInputs(block, prev, state, callback)
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 useCheckpoints is enabled, it will skip verification for historical data.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | |
prev |
ChainEntry | |
state |
DeploymentState | |
callback |
function | Returns [VerifyError]. |
- Source:
- See:
(private) _findDuplicates(block, prev, callback)
Check block for duplicate txids in blockchain history (BIP30). Note that txids are only considered duplicate if they are not yet completely spent.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | MerkleBlock | |
prev |
ChainEntry | |
callback |
function | Returns [VerifyError]. |
- Source:
- See:
(private) _findFork(fork, longer, callback)
Find the block at which a fork ocurred.
Parameters:
| Name | Type | Description |
|---|---|---|
fork |
ChainEntry | The current chain. |
longer |
ChainEntry | The competing chain. |
callback |
function | Returns [Error, ChainEntry]. |
- Source:
(private) _getInitialState(callback)
A helper function to test whether segwit is active at any given time. Since segwit affects almost all of bitcoin, it is one deployment that needs to be checked frequently.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function | Returns [Error, Boolean]. |
- Source:
(private) _preload(callback)
Stream headers from electrum.org for quickly preloading the chain. Electrum.org stores headers in the standard block header format, but they do not store chainwork, so we have to calculate it ourselves.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
- Source:
(private) _reorganize(entry, block, callback)
Reorganize the blockchain (connect and disconnect inputs). Called when a competing chain with a higher chainwork is received.
Parameters:
| Name | Type | Description |
|---|---|---|
entry |
ChainEntry | The competing chain's tip. |
block |
Block | MerkleBlock | The being being added. |
callback |
function |
- Source:
(private) _setBestChain(entry, block, prev, callback)
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 | MerkleBlock | |
prev |
ChainEntry | |
callback |
function | Returns [VerifyError]. |
- Source:
(private) _verify(block, entry, callback)
Contextual verification for a block, including version deployments (IsSuperMajority), versionbits, coinbase height, finality checks.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | MerkleBlock | |
entry |
ChainEntry | |
callback |
function | Returns [VerifyError, VerifyFlags]. |
- Source:
(private) _verifyContext(block, entry, callback)
Perform all necessary contextual verification on a block.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | MerkleBlock | |
entry |
ChainEntry | |
callback |
function | Returns [VerifyError]. |
- Source:
add(block, callback)
Add a block to the chain, perform all necessary verification.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | MerkleBlock | CompactBlock | |
callback |
function | Returns [VerifyError]. |
- Source:
byTime(ts, callback)
Find a block entry by timestamp.
Parameters:
| Name | Type | Description |
|---|---|---|
ts |
Number | Timestamp. |
callback |
function | Returns [Error, ChainEntry]. |
- Source:
checkFinal(prev, tx, flags, callback)
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 | |
callback |
function | Returns [Error, Boolean]. |
- Source:
checkLocks(tx, flags, prev, callback)
Verify sequence locks.
Parameters:
| Name | Type | Description |
|---|---|---|
tx |
TX | |
flags |
LockFlags | |
prev |
ChainEntry | |
callback |
function | Returns [Error, Boolean]. |
- Source:
close(callback)
Close the chain, wait for the database to close.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
- Source:
computeBlockVersion(prev, callback)
Compute the version for a new block (BIP9: versionbits).
Parameters:
| Name | Type | Description |
|---|---|---|
prev |
ChainEntry | Previous chain entry (usually the tip). |
callback |
function | Returns [Error, Number]. |
- Source:
- See:
connect(entry, callback)
Connect 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 | |
callback |
function |
- Source:
disconnect(entry, callback)
Disconnect an entry from the chain (updates the tip).
Parameters:
| Name | Type | Description |
|---|---|---|
entry |
ChainEntry | |
callback |
function |
- Source:
evalLocks(prev, minHeight, minTime, callback)
Evaluate sequence locks.
Parameters:
| Name | Type | Description |
|---|---|---|
prev |
ChainEntry | |
minHeight |
Number | |
minTime |
Number | |
callback |
function | Returns [Error, Boolean]. |
- Source:
findLocator(locator, callback)
Find a locator. Analagous to bitcoind's FindForkInGlobalIndex().
Parameters:
| Name | Type | Description |
|---|---|---|
locator |
Array.<Hash> | Hashes. |
callback |
function | Returns [Error, Hash] (the hash of the latest known block). |
- Source:
getCurrentTarget(callback)
Calculate the next target based on the chain tip.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function | returns [Error, Number] (target is in compact/mantissa form). |
- Source:
getEntry(hash/height, callback)
Find the corresponding block entry by hash or height.
Parameters:
| Name | Type | Description |
|---|---|---|
hash/height |
Hash | Number | |
callback |
function | Returns [Error, ChainEntry]. |
- Source:
getLocator(startnullable, callback)
Calculate chain locator (an array of hashes).
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
start |
Number | 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. |
callback |
function | Returns [Error, Hash[]]. |
- Source:
getLocks(tx, flags, prev, callback)
Get the necessary minimum time and height sequence locks for a transaction.
Parameters:
| Name | Type | Description |
|---|---|---|
tx |
TX | |
flags |
LockFlags | |
prev |
ChainEntry | |
callback |
function | Returns [Error, Number(minTime), Number(minHeight)]. |
- Source:
getOrphan(hash) → {Block|MerkleBlock|CompactBlock}
Get an orphan block.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash |
- Source:
Returns:
- Type
- Block | MerkleBlock | CompactBlock
getOrphanRoot(hash) → (nullable) {Object}
Calculate the orphan root of the hash (if it is an orphan). Will also calculate "orphan soil" -- the block needed in * order to resolve the orphan root.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash |
- Source:
Returns:
- Type
- Object
getProgress() → {Number}
Get the fill percentage.
- Source:
Returns:
percent - Ranges from 0.0 to 1.0.
- Type
- Number
getState(prev, id, callback)
Get chain entry state for a deployment (BIP9: versionbits).
Parameters:
| Name | Type | Description |
|---|---|---|
prev |
ChainEntry | Previous chain entry. |
id |
String | Deployment id. |
callback |
function | Returns [Error, Number]. |
- Source:
- See:
Example
chain.getState(entry, 'witness', callback);getTarget(block, prev, callback)
Calculate the target synchronously. Must have ancestors pre-allocated.
Parameters:
| Name | Type | Description |
|---|---|---|
block |
Block | MerkleBlock | null | Current block. |
prev |
ChainEntry | Previous entry. |
callback |
function | returns [Error, Number] (target is in compact/mantissa form). |
- Source:
getTargetAsync(prev, prev, callback)
Calculate the target based on the passed-in chain entry.
Parameters:
| Name | Type | Description |
|---|---|---|
prev |
ChainEntry | Previous entry. |
prev |
Block | MerkleBlock | null | Current block. |
callback |
function | returns [Error, Number] (target is in compact/mantissa form). |
- Source:
has(hash, callback)
Test the chain to see if it has a block, orphan, or pending block.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash | |
callback |
function | Returns [Error, Boolean]. |
- Source:
hasBlock(hash, callback)
Test the chain to see if it contains a block.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash | |
callback |
function | Returns [Error, Boolean]. |
- Source:
hasOrphan(hash, callback)
Test the chain to see if it contains an orphan.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash | |
callback |
function | Returns [Error, Boolean]. |
- Source:
hasPending(hash, callback)
Test the chain to see if it contains a pending block in its queue.
Parameters:
| Name | Type | Description |
|---|---|---|
hash |
Hash | |
callback |
function | Returns [Error, Boolean]. |
- Source:
isActive(prev, id, callback)
Check whether a versionbits deployment is active (BIP9: versionbits).
Parameters:
| Name | Type | Description |
|---|---|---|
prev |
ChainEntry | Previous chain entry. |
id |
String | Deployment id. |
callback |
function | Returns [Error, Number]. |
- Source:
- See:
Example
chain.isActive(entry, 'witness', callback);isBusy() → {Boolean}
Test whether the chain is in the process of adding blocks.
- Source:
Returns:
- Type
- Boolean
isFull() → {Boolean}
Test the chain to see if it is synced.
- Source:
Returns:
- Type
- Boolean
isInitial() → {Boolean}
Test the chain to see if it is still in the initial
syncing phase. Mimic's bitcoind's IsInitialBlockDownload()
function.
- Source:
- See:
-
- IsInitalBlockDownload()
Returns:
- Type
- Boolean
onDrain(callback)
Wait for the chain to drain (finish processing all of the blocks in its queue).
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
- Source:
open(callback)
Open the chain, wait for the database to load.
Parameters:
| Name | Type | Description |
|---|---|---|
callback |
function |
- 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:
purgePending()
Purge any pending blocks in the queue: note that this call is unpredictable and may screw up the blockchain sync. It is only used as a last resort if more than 500mb of pending blocks are in the queue.
- Source:
reset(height, callback)
Reset the chain to the desired height. This is useful for replaying the blockchain download for SPV.
Parameters:
| Name | Type | Description |
|---|---|---|
height |
Number | |
callback |
function |
- Source:
resetTime(ts, callback)
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. |
callback |
function |
- Source:
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