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 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

      • 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