An implementor of FullPrunedBlockStore saves StoredBlock objects to some storage mechanism.

In addition to keeping track of a chain using StoredBlocks, it should also keep track of a second
copy of the chain which holds StoredUndoableBlocks. In this way, an application can perform a
headers-only initial sync and then use that information to more efficiently download a locally verified
full copy of the block chain.

A FullPrunedBlockStore should function well as a standard BlockStore and then be able to
trivially switch to being used as a FullPrunedBlockStore.

It should store the StoredUndoableBlocks of a number of recent blocks before verifiedHead.height and
all those after verifiedHead.height.
It is advisable to store any StoredUndoableBlock which has a height > verifiedHead.height - N.
Because N determines the memory usage, it is recommended that N be customizable. N should be chosen such that
re-orgs beyond that point are vanishingly unlikely, for example, a few thousand blocks is a reasonable choice.

Returns the StoredBlock that represents the top of the chain of greatest total work that has
been fully verified and the point in the chain at which the unspent transaction output set in this
store represents.

Method Detail

put

Though not required for proper function of a FullPrunedBlockStore, any user of a FullPrunedBlockStore should ensure
that a StoredUndoableBlock for each block up to the fully verified chain head has been added to this block store using
this function (not put(StoredBlock)), so that the ability to perform reorgs is maintained.

Throws:

BlockStoreException - if there is a problem with the underlying storage layer, such as running out of disk space.

getUndoBlock

Returns a StoredUndoableBlock whose block.getHash() method will be equal to the parameter. If no such
block is found, returns null. Note that this may return null more often than get(Sha256Hash hash) as not all
StoredBlocks have a StoredUndoableBlock copy stored as well.

getVerifiedChainHead

Returns the StoredBlock that represents the top of the chain of greatest total work that has
been fully verified and the point in the chain at which the unspent transaction output set in this
store represents.

setVerifiedChainHead

Sets the StoredBlock that represents the top of the chain of greatest total work that has been
fully verified. It should generally be set after a batch of updates to the transaction unspent output set,
before a call to commitDatabaseBatchWrite.
If chainHead has a greater height than the non-verified chain head (ie that set with
BlockStore.setChainHead(org.bitcoinj.core.StoredBlock)) the non-verified chain head should be set to the one set here.
In this way a class using a FullPrunedBlockStore only in full-verification mode can ignore the regular
BlockStore functions implemented as a part of a FullPrunedBlockStore.

beginDatabaseBatchWrite

If abortDatabaseBatchWrite() is called by the same thread that called beginDatabaseBatchWrite(),
any data writes between this call and abortDatabaseBatchWrite() made by the same thread
should be discarded.

Furthermore, any data written after a call to beginDatabaseBatchWrite() should not be readable
by any other threads until commitDatabaseBatchWrite() has been called by this thread.
Multiple calls to beginDatabaseBatchWrite() in any given thread should be ignored and treated as one call.