com.google.bitcoin.core

Interface BlockChainListener

All Known Implementing Classes:

AbstractBlockChainListener, NativeBlockChainListener, Wallet

public interface BlockChainListener

Implementors can be connected to a BlockChain and have its methods called when various things happen that modify the state of the chain, for example: new blocks being received, a re-org occurring, or the best chain head changing.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	isTransactionRelevant(Transaction tx) Returns true if the given transaction is interesting to the listener.
void	notifyNewBestBlock(StoredBlock block) Called by the BlockChain when a new block on the best chain is seen, AFTER relevant transactions are extracted and sent to us UNLESS the new block caused a re-org, in which case this will not be called (the Wallet.reorganize(StoredBlock, java.util.List, java.util.List) method will call this one in that case).
void	notifyTransactionIsInBlock(Sha256Hash txHash, StoredBlock block, AbstractBlockChain.NewBlockType blockType, int relativityOffset) Called by the BlockChain when we receive a new FilteredBlock that contains the given transaction hash in its merkle tree.
void	receiveFromBlock(Transaction tx, StoredBlock block, AbstractBlockChain.NewBlockType blockType, int relativityOffset) Called by the BlockChain when we receive a new block that contains a relevant transaction.
void	reorganize(StoredBlock splitPoint, List<StoredBlock> oldBlocks, List<StoredBlock> newBlocks) Called by the BlockChain when the best chain (representing total work done) has changed.

Method Detail

notifyNewBestBlock

void notifyNewBestBlock(StoredBlock block)
                        throws VerificationException

Called by the BlockChain when a new block on the best chain is seen, AFTER relevant transactions are extracted and sent to us UNLESS the new block caused a re-org, in which case this will not be called (the Wallet.reorganize(StoredBlock, java.util.List, java.util.List) method will call this one in that case).

Parameters:

block -

Throws:

VerificationException

reorganize

void reorganize(StoredBlock splitPoint,
              List<StoredBlock> oldBlocks,
              List<StoredBlock> newBlocks)
                throws VerificationException

Called by the BlockChain when the best chain (representing total work done) has changed. In this case, we need to go through our transactions and find out if any have become invalid. It's possible for our balance to go down in this case: money we thought we had can suddenly vanish if the rest of the network agrees it should be so.

The oldBlocks/newBlocks lists are ordered height-wise from top first to bottom last.

Throws:

VerificationException

isTransactionRelevant

boolean isTransactionRelevant(Transaction tx)
                              throws ScriptException

Returns true if the given transaction is interesting to the listener. If yes, then the transaction will be provided via the receiveFromBlock method. This method is essentially an optimization that lets BlockChain bypass verification of a blocks merkle tree if no listeners are interested, which can save time when processing full blocks on mobile phones. It's likely the method will be removed in future and replaced with an alternative mechanism that involves listeners providing all keys that are interesting.

Throws:

ScriptException

receiveFromBlock

void receiveFromBlock(Transaction tx,
                    StoredBlock block,
                    AbstractBlockChain.NewBlockType blockType,
                    int relativityOffset)
                      throws VerificationException

Called by the BlockChain when we receive a new block that contains a relevant transaction.

A transaction may be received multiple times if is included into blocks in parallel chains. The blockType parameter describes whether the containing block is on the main/best chain or whether it's on a presently inactive side chain.

The relativityOffset parameter is an arbitrary number used to establish an ordering between transactions within the same block. In the case where full blocks are being downloaded, it is simply the index of the transaction within that block. When Bloom filtering is in use, we don't find out the exact offset into a block that a transaction occurred at, so the relativity count is not reflective of anything in an absolute sense but rather exists only to order the transaction relative to the others.

Throws:

VerificationException

notifyTransactionIsInBlock

void notifyTransactionIsInBlock(Sha256Hash txHash,
                              StoredBlock block,
                              AbstractBlockChain.NewBlockType blockType,
                              int relativityOffset)
                                throws VerificationException

Called by the BlockChain when we receive a new FilteredBlock that contains the given transaction hash in its merkle tree.

A transaction may be received multiple times if is included into blocks in parallel chains. The blockType parameter describes whether the containing block is on the main/best chain or whether it's on a presently inactive side chain.

The relativityOffset parameter in this case is an arbitrary (meaningless) number, that is useful only when compared to the relativity count of another transaction received inside the same block. It is used to establish an ordering of transactions relative to one another.

Throws:

VerificationException