Package org.bitcoinj.core

Class BlockChain

java.lang.Object

org.bitcoinj.core.AbstractBlockChain

org.bitcoinj.core.BlockChain

public class BlockChain
extends AbstractBlockChain

A BlockChain implements the simplified payment verification mode of the Bitcoin protocol. It is the right choice to use for programs that have limited resources as it won't verify transactions signatures or attempt to store all of the block chain. Really, this class should be called SPVBlockChain but for backwards compatibility it is not.

Nested Class Summary

Nested classes/interfaces inherited from class org.bitcoinj.core.AbstractBlockChain

AbstractBlockChain.NewBlockType

Field Summary

Fields

Modifier and Type	Field	Description
protected BlockStore	blockStore	Keeps a map of block hashes to StoredBlocks.

Fields inherited from class org.bitcoinj.core.AbstractBlockChain

chainHead, FP_ESTIMATOR_ALPHA, FP_ESTIMATOR_BETA, lock, params

Constructor Summary

Constructors

Constructor	Description
BlockChain(Network network, java.util.List<? extends Wallet> wallets, BlockStore blockStore)	Constructs a BlockChain connected to the given list of listeners and a store.
BlockChain(Network network, BlockStore blockStore)	Constructs a BlockChain that has no wallet at all.
BlockChain(Network network, Wallet wallet, BlockStore blockStore)	Constructs a BlockChain connected to the given wallet and store.
BlockChain(NetworkParameters params, Wallet wallet, BlockStore blockStore)

Method Summary

Modifier and Type	Method	Description
boolean	add(FilteredBlock block)	Processes a received block and tries to add it to the chain.
protected StoredBlock	addToBlockStore(StoredBlock storedPrev, Block blockHeader)	Adds/updates the given Block with the block store.
protected StoredBlock	addToBlockStore(StoredBlock storedPrev, Block blockHeader, TransactionOutputChanges txOutChanges)	Adds/updates the given StoredBlock with the block store.
protected TransactionOutputChanges	connectTransactions(int height, Block block)	Connect each transaction in block.transactions, verifying them as we go and removing spent outputs If an error is encountered in a transaction, no changes should be made to the underlying BlockStore.
protected TransactionOutputChanges	connectTransactions(StoredBlock newBlock)	Load newBlock from BlockStore and connect its transactions, returning changes to the set of unspent transactions.
protected void	disconnectTransactions(StoredBlock block)	Disconnect each transaction in the block (after reading it from the block store) Only called if(shouldVerifyTransactions())
protected void	doSetChainHead(StoredBlock chainHead)	Called before setting chain head in memory.
protected StoredBlock	getStoredBlockInCurrentScope(Sha256Hash hash)	For a standard BlockChain, this should return blockStore.get(hash), for a FullPrunedBlockChain blockStore.getOnceUndoableStoredBlock(hash)
protected void	notSettingChainHead()	Called if we (possibly) previously called disconnectTransaction/connectTransactions, but will not be calling preSetChainHead as a block failed verification.
protected void	rollbackBlockStore(int height)	Rollback the block store to a given height.
protected boolean	shouldVerifyTransactions()	Whether or not we are maintaining a set of unspent outputs and are verifying all transactions.

Methods inherited from class org.bitcoinj.core.AbstractBlockChain

add, addNewBestBlockListener, addNewBestBlockListener, addReorganizeListener, addReorganizeListener, addTransactionReceivedListener, addTransactionReceivedListener, addWallet, drainOrphanBlocks, estimateBlockTime, estimateBlockTimeInstant, getBestChainHeight, getBlockStore, getChainHead, getFalsePositiveRate, getHeightFuture, getOrphanRoot, getVersionTally, isOrphan, removeNewBestBlockListener, removeReorganizeListener, removeTransactionReceivedListener, removeWallet, resetFalsePositiveEstimate, setChainHead, trackFilteredTransactions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

blockStore

protected final BlockStore blockStore

Keeps a map of block hashes to StoredBlocks.

Constructor Detail

BlockChain

public BlockChain(Network network,
                  Wallet wallet,
                  BlockStore blockStore)
           throws BlockStoreException

Constructs a BlockChain connected to the given wallet and store. To obtain a Wallet you can construct one from scratch, or you can deserialize a saved wallet from disk using Wallet.loadFromFile(File, WalletExtension...)

For the store, you should use SPVBlockStore or you could also try a MemoryBlockStore if you want to hold all headers in RAM and don't care about disk serialization (this is rare).

Throws:

BlockStoreException

BlockChain

public BlockChain(Network network,
                  BlockStore blockStore)
           throws BlockStoreException

Constructs a BlockChain that has no wallet at all. This is helpful when you don't actually care about sending and receiving coins but rather, just want to explore the network data structures.

Throws:

BlockStoreException

BlockChain

public BlockChain(Network network,
                  java.util.List<? extends Wallet> wallets,
                  BlockStore blockStore)
           throws BlockStoreException

Constructs a BlockChain connected to the given list of listeners and a store.

Throws:

BlockStoreException

BlockChain

public BlockChain(NetworkParameters params,
                  Wallet wallet,
                  BlockStore blockStore)
           throws BlockStoreException

Throws:

BlockStoreException

Method Detail

addToBlockStore

protected StoredBlock addToBlockStore(StoredBlock storedPrev,
                                      Block blockHeader,
                                      TransactionOutputChanges txOutChanges)
                               throws BlockStoreException,
                                      VerificationException

Description copied from class: AbstractBlockChain

Adds/updates the given StoredBlock with the block store. This version is used when the transactions have already been verified to properly spend txOutputChanges.

Specified by:

addToBlockStore in class AbstractBlockChain

Parameters:

storedPrev - The StoredBlock which immediately precedes block.

blockHeader - The StoredBlock to add/update.

txOutChanges - The total sum of all changes made by this block to the set of open transaction outputs (from a call to connectTransactions), if in fully verifying mode (null otherwise).

Returns:

the newly created StoredBlock

Throws:

BlockStoreException - if a failure occurs while storing a block

VerificationException - if the block is invalid

addToBlockStore

protected StoredBlock addToBlockStore(StoredBlock storedPrev,
                                      Block blockHeader)
                               throws BlockStoreException,
                                      VerificationException

Description copied from class: AbstractBlockChain

Adds/updates the given Block with the block store. This version is used when the transactions have not been verified.

Specified by:

addToBlockStore in class AbstractBlockChain

Parameters:

storedPrev - The StoredBlock which immediately precedes block.

blockHeader - The Block to add/update.

Returns:

the newly created StoredBlock

Throws:

BlockStoreException - if a failure occurs while storing a block

VerificationException - if the block is invalid

rollbackBlockStore

protected void rollbackBlockStore(int height)
                           throws BlockStoreException

Description copied from class: AbstractBlockChain

Rollback the block store to a given height. This is currently only supported by BlockChain instances.

Specified by:

rollbackBlockStore in class AbstractBlockChain

Parameters:

height - height to roll back to

Throws:

BlockStoreException - if the operation fails or is unsupported.

shouldVerifyTransactions

protected boolean shouldVerifyTransactions()

Description copied from class: AbstractBlockChain

Whether or not we are maintaining a set of unspent outputs and are verifying all transactions. Also indicates that all calls to add() should provide a block containing transactions

Specified by:

shouldVerifyTransactions in class AbstractBlockChain

Returns:

true if we are verifying all transactions

connectTransactions

protected TransactionOutputChanges connectTransactions(int height,
                                                       Block block)

Description copied from class: AbstractBlockChain

Connect each transaction in block.transactions, verifying them as we go and removing spent outputs If an error is encountered in a transaction, no changes should be made to the underlying BlockStore. and a VerificationException should be thrown. Only called if(shouldVerifyTransactions())

Specified by:

connectTransactions in class AbstractBlockChain

Parameters:

height - block height to attach at

block - block to connect

Returns:

The full set of all changes made to the set of open transaction outputs.

connectTransactions

protected TransactionOutputChanges connectTransactions(StoredBlock newBlock)

Description copied from class: AbstractBlockChain

Load newBlock from BlockStore and connect its transactions, returning changes to the set of unspent transactions. If an error is encountered in a transaction, no changes should be made to the underlying BlockStore. Only called if(shouldVerifyTransactions())

Specified by:

connectTransactions in class AbstractBlockChain

Parameters:

newBlock - block to load

Returns:

The full set of all changes made to the set of open transaction outputs.

disconnectTransactions

protected void disconnectTransactions(StoredBlock block)

Description copied from class: AbstractBlockChain

Disconnect each transaction in the block (after reading it from the block store) Only called if(shouldVerifyTransactions())

Specified by:

disconnectTransactions in class AbstractBlockChain

Parameters:

block - block to disconnect

doSetChainHead

protected void doSetChainHead(StoredBlock chainHead)
                       throws BlockStoreException

Description copied from class: AbstractBlockChain

Called before setting chain head in memory. Should write the new head to block store and then commit any database transactions that were started by disconnectTransactions/connectTransactions.

Specified by:

doSetChainHead in class AbstractBlockChain

Parameters:

chainHead - chain head to set

Throws:

BlockStoreException - if a failure occurs while storing a block

notSettingChainHead

protected void notSettingChainHead()
                            throws BlockStoreException

Description copied from class: AbstractBlockChain

Called if we (possibly) previously called disconnectTransaction/connectTransactions, but will not be calling preSetChainHead as a block failed verification. Can be used to abort database transactions that were started by disconnectTransactions/connectTransactions.

Specified by:

notSettingChainHead in class AbstractBlockChain

Throws:

BlockStoreException - if a failure occurs while storing a block

getStoredBlockInCurrentScope

protected StoredBlock getStoredBlockInCurrentScope(Sha256Hash hash)
                                            throws BlockStoreException

Description copied from class: AbstractBlockChain

For a standard BlockChain, this should return blockStore.get(hash), for a FullPrunedBlockChain blockStore.getOnceUndoableStoredBlock(hash)

Specified by:

getStoredBlockInCurrentScope in class AbstractBlockChain

Parameters:

hash - hash of block to fetch

Returns:

block with matching hash

Throws:

BlockStoreException - if a failure occurs while storing a block

add

public boolean add(FilteredBlock block)
            throws VerificationException,
                   PrunedException

Description copied from class: AbstractBlockChain

Processes a received block and tries to add it to the chain. If there's something wrong with the block an exception is thrown. If the block is OK but cannot be connected to the chain at this time, returns false. If the block can be connected to the chain, returns true.

Overrides:

add in class AbstractBlockChain

Parameters:

block - received block

Returns:

true if block can be connected, false if block is valid but can't be connected

Throws:

VerificationException - if invalid block

PrunedException - a reorg that is too-long for our stored block data has occurred