org.bitcoinj.store

Interface FullPrunedBlockStore

All Superinterfaces:

BlockStore, UTXOProvider

All Known Implementing Classes:

DatabaseFullPrunedBlockStore, H2FullPrunedBlockStore, LevelDBFullPrunedBlockStore, MemoryFullPrunedBlockStore, MySQLFullPrunedBlockStore, PostgresFullPrunedBlockStore

public interface FullPrunedBlockStore
extends BlockStore, UTXOProvider

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.

It must store the StoredBlock of all blocks.

A FullPrunedBlockStore contains a map of hashes to [Full]StoredBlock. The hash is the double digest of the Bitcoin serialization of the block header, not the header with the extra data as well.

A FullPrunedBlockStore also contains a map of hash+index to UTXO. Again, the hash is a standard Bitcoin double-SHA256 hash of the transaction.

FullPrunedBlockStores are thread safe.

Method Summary

Modifier and Type	Method and Description
void	abortDatabaseBatchWrite()
void	addUnspentTransactionOutput(UTXO out) Adds a UTXO to the list of unspent TransactionOutputs
void	beginDatabaseBatchWrite() Begins/Commits/Aborts a database transaction.
void	commitDatabaseBatchWrite()
StoredBlock	getOnceUndoableStoredBlock(Sha256Hash hash) Returns the StoredBlock that was added as a StoredUndoableBlock given a hash.
UTXO	getTransactionOutput(Sha256Hash hash, long index) Gets a UTXO with the given hash and index, or null if none is found
StoredUndoableBlock	getUndoBlock(Sha256Hash hash) Returns a StoredUndoableBlock whose block.getHash() method will be equal to the parameter.
StoredBlock	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.
boolean	hasUnspentOutputs(Sha256Hash hash, int numOutputs) True if this store has any unspent outputs from a transaction with a hash equal to the first parameter
void	put(StoredBlock storedBlock, StoredUndoableBlock undoableBlock) Saves the given StoredUndoableBlock and StoredBlock.
void	removeUnspentTransactionOutput(UTXO out) Removes a UTXO from the list of unspent TransactionOutputs Note that the coinbase of the genesis block should NEVER be spendable and thus never in the list.
void	setVerifiedChainHead(StoredBlock chainHead) Sets the StoredBlock that represents the top of the chain of greatest total work that has been fully verified.

Methods inherited from interface org.bitcoinj.store.BlockStore

close, get, getChainHead, getParams, put, setChainHead

Methods inherited from interface org.bitcoinj.core.UTXOProvider

getChainHeadHeight, getOpenTransactionOutputs, getParams

Method Detail

put

void put(StoredBlock storedBlock,
         StoredUndoableBlock undoableBlock)
  throws BlockStoreException

Saves the given StoredUndoableBlock and StoredBlock. Calculates keys from the StoredBlock

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.

getOnceUndoableStoredBlock

StoredBlock getOnceUndoableStoredBlock(Sha256Hash hash)
                                throws BlockStoreException

Returns the StoredBlock that was added as a StoredUndoableBlock given a hash. The returned values block.getHash() method will be equal to the parameter. If no such block is found, returns null.

Throws:

BlockStoreException

getUndoBlock

StoredUndoableBlock getUndoBlock(Sha256Hash hash)
                          throws BlockStoreException

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.

Throws:

BlockStoreException

getTransactionOutput

UTXO getTransactionOutput(Sha256Hash hash,
                          long index)
                   throws BlockStoreException

Gets a UTXO with the given hash and index, or null if none is found

Throws:

BlockStoreException

addUnspentTransactionOutput

void addUnspentTransactionOutput(UTXO out)
                          throws BlockStoreException

Adds a UTXO to the list of unspent TransactionOutputs

Throws:

BlockStoreException

removeUnspentTransactionOutput

void removeUnspentTransactionOutput(UTXO out)
                             throws BlockStoreException

Removes a UTXO from the list of unspent TransactionOutputs Note that the coinbase of the genesis block should NEVER be spendable and thus never in the list.

Throws:

BlockStoreException - if there is an underlying storage issue, or out was not in the list.

hasUnspentOutputs

boolean hasUnspentOutputs(Sha256Hash hash,
                          int numOutputs)
                   throws BlockStoreException

True if this store has any unspent outputs from a transaction with a hash equal to the first parameter

Parameters:

numOutputs - the number of outputs the given transaction has

Throws:

BlockStoreException

getVerifiedChainHead

StoredBlock getVerifiedChainHead()
                          throws BlockStoreException

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.

Throws:

BlockStoreException

setVerifiedChainHead

void setVerifiedChainHead(StoredBlock chainHead)
                   throws BlockStoreException

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.

Throws:

BlockStoreException

beginDatabaseBatchWrite

void beginDatabaseBatchWrite()
                      throws BlockStoreException

Begins/Commits/Aborts a database transaction.

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.

Throws:

BlockStoreException

commitDatabaseBatchWrite

void commitDatabaseBatchWrite()
                       throws BlockStoreException

Throws:

BlockStoreException

abortDatabaseBatchWrite

void abortDatabaseBatchWrite()
                      throws BlockStoreException

Throws:

BlockStoreException