Package org.bitcoinj.store

Interface FullPrunedBlockStore

All Superinterfaces:
BlockStore, UTXOProvider
All Known Implementing Classes:
MemoryFullPrunedBlockStore
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 Details

    • 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