com.google.bitcoin.core
Class TransactionConfidence

java.lang.Object
  com.google.bitcoin.core.TransactionConfidence

All Implemented Interfaces:

Serializable

public class TransactionConfidence
extends Object
implements Serializable

A TransactionConfidence object tracks data you can use to make a confidence decision about a transaction. It also contains some pre-canned rules for common scenarios: if you aren't really sure what level of confidence you need, these should prove useful. You can get a confidence object using Transaction.getConfidence(). They cannot be constructed directly.

Confidence in a transaction can come in multiple ways:

• Because you created it yourself and only you have the necessary keys.
• Receiving it from a fully validating peer you know is trustworthy, for instance, because it's run by yourself.
• Receiving it from a peer on the network you randomly chose. If your network connection is not being intercepted, you have a pretty good chance of connecting to a node that is following the rules.
• Receiving it from multiple peers on the network. If your network connection is not being intercepted, hearing about a transaction from multiple peers indicates the network has accepted the transaction and thus miners likely have too (miners have the final say in whether a transaction becomes valid or not).
• Seeing the transaction appear appear in a block on the main chain. Your confidence increases as the transaction becomes further buried under work. Work can be measured either in blocks (roughly, units of time), or amount of work done.

Alternatively, you may know that the transaction is "dead", that is, one or more of its inputs have been double spent and will never confirm unless there is another re-org.

TransactionConfidence is updated via the notifyWorkDone(Block) method to ensure the block depth and work done are up to date.

To make a copy that won't be changed, use duplicate().

See Also:

Serialized Form

Nested Class Summary

static class	TransactionConfidence.ConfidenceType Describes the state of the transaction in general terms.
static interface	TransactionConfidence.Listener A confidence listener is informed when the level of TransactionConfidence is updated by something, like for example a Wallet.
static class	TransactionConfidence.Source Information about where the transaction was first seen (network, sent direct from peer, created by ourselves).

Constructor Summary

TransactionConfidence(Transaction tx)

Method Summary

void	addEventListener(TransactionConfidence.Listener listener) Adds an event listener that will be run when this confidence object is updated.
void	addEventListener(TransactionConfidence.Listener listener, Executor executor) Adds an event listener that will be run when this confidence object is updated.
TransactionConfidence	duplicate() Returns a copy of this object.
int	getAppearedAtChainHeight() Returns the chain height at which the transaction appeared if confidence type is BUILDING.
ListIterator<PeerAddress>	getBroadcastBy() Returns a snapshot of PeerAddresses that announced the transaction.
TransactionConfidence.ConfidenceType	getConfidenceType() Returns a general statement of the level of confidence you can have in this transaction.
com.google.common.util.concurrent.ListenableFuture<Transaction>	getDepthFuture(int depth)
com.google.common.util.concurrent.ListenableFuture<Transaction>	getDepthFuture(int depth, Executor executor) Returns a future that completes when the transaction has been confirmed by "depth" blocks.
int	getDepthInBlocks() Depth in the chain is an approximation of how much time has elapsed since the transaction has been confirmed.
Transaction	getOverridingTransaction() If this transaction has been overridden by a double spend (is dead), this call returns the overriding transaction.
TransactionConfidence.Source	getSource() The source of a transaction tries to identify where it came from originally.
BigInteger	getWorkDone() Returns the estimated amount of work (number of hashes performed) on this transaction.
boolean	markBroadcastBy(PeerAddress address) Called by a Peer when a transaction is pending and announced by a peer.
boolean	notifyWorkDone(Block block) Called by the wallet when the tx appears on the best chain and a new block is added to the top.
int	numBroadcastPeers() Returns how many peers have been passed to markBroadcastBy(com.google.bitcoin.core.PeerAddress).
void	queueListeners(TransactionConfidence.Listener.ChangeReason reason) Call this after adjusting the confidence, for cases where listeners should be notified.
boolean	removeEventListener(TransactionConfidence.Listener listener)
void	setAppearedAtChainHeight(int appearedAtChainHeight) The chain height at which the transaction appeared, if it has been seen in the best chain.
void	setConfidenceType(TransactionConfidence.ConfidenceType confidenceType) Called by other objects in the system, like a Wallet, when new information about the confidence of a transaction becomes available.
void	setDepthInBlocks(int depth)
void	setOverridingTransaction(Transaction overridingTransaction) Called when the transaction becomes newly dead, that is, we learn that one of its inputs has already been spent in such a way that the double-spending transaction takes precedence over this one.
void	setSource(TransactionConfidence.Source source) The source of a transaction tries to identify where it came from originally.
void	setWorkDone(BigInteger workDone)
String	toString()
boolean	wasBroadcastBy(PeerAddress address) Returns true if the given address has been seen via markBroadcastBy()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionConfidence

public TransactionConfidence(Transaction tx)

Method Detail

addEventListener

public void addEventListener(TransactionConfidence.Listener listener,
                             Executor executor)

Adds an event listener that will be run when this confidence object is updated. The listener will be locked and is likely to be invoked on a peer thread.

Note that this is NOT called when every block arrives. Instead it is called when the transaction transitions between confidence states, ie, from not being seen in the chain to being seen (not necessarily in the best chain). If you want to know when the transaction gets buried under another block, consider using a future from getDepthFuture(int).

addEventListener

public void addEventListener(TransactionConfidence.Listener listener)

Adds an event listener that will be run when this confidence object is updated. The listener will be locked and is likely to be invoked on a peer thread.

Note that this is NOT called when every block arrives. Instead it is called when the transaction transitions between confidence states, ie, from not being seen in the chain to being seen (not necessarily in the best chain). If you want to know when the transaction gets buried under another block, implement a BlockChainListener, attach it to a BlockChain and then use the getters on the confidence object to determine the new depth.

removeEventListener

public boolean removeEventListener(TransactionConfidence.Listener listener)

getAppearedAtChainHeight

public int getAppearedAtChainHeight()

Returns the chain height at which the transaction appeared if confidence type is BUILDING.

Throws:

IllegalStateException - if the confidence type is not BUILDING.

setAppearedAtChainHeight

public void setAppearedAtChainHeight(int appearedAtChainHeight)

The chain height at which the transaction appeared, if it has been seen in the best chain. Automatically sets the current type to TransactionConfidence.ConfidenceType.BUILDING and depth to one.

getConfidenceType

public TransactionConfidence.ConfidenceType getConfidenceType()

Returns a general statement of the level of confidence you can have in this transaction.

setConfidenceType

public void setConfidenceType(TransactionConfidence.ConfidenceType confidenceType)

Called by other objects in the system, like a Wallet, when new information about the confidence of a transaction becomes available.

markBroadcastBy

public boolean markBroadcastBy(PeerAddress address)

Called by a Peer when a transaction is pending and announced by a peer. The more peers announce the transaction, the more peers have validated it (assuming your internet connection is not being intercepted). If confidence is currently unknown, sets it to TransactionConfidence.ConfidenceType.PENDING. Listeners will be invoked in this case.

Parameters:

address - IP address of the peer, used as a proxy for identity.

numBroadcastPeers

public int numBroadcastPeers()

Returns how many peers have been passed to markBroadcastBy(com.google.bitcoin.core.PeerAddress).

getBroadcastBy

public ListIterator<PeerAddress> getBroadcastBy()

Returns a snapshot of PeerAddresses that announced the transaction.

wasBroadcastBy

public boolean wasBroadcastBy(PeerAddress address)

Returns true if the given address has been seen via markBroadcastBy()

toString

public String toString()

Overrides:

toString in class Object

notifyWorkDone

public boolean notifyWorkDone(Block block)
                       throws VerificationException

Called by the wallet when the tx appears on the best chain and a new block is added to the top. Updates the internal counter that tracks how deeply buried the block is. Work is the value of block.getWork().

Throws:

VerificationException

getDepthInBlocks

public int getDepthInBlocks()

Depth in the chain is an approximation of how much time has elapsed since the transaction has been confirmed. On average there is supposed to be a new block every 10 minutes, but the actual rate may vary. The reference (Satoshi) implementation considers a transaction impractical to reverse after 6 blocks, but as of EOY 2011 network security is high enough that often only one block is considered enough even for high value transactions. For low value transactions like songs, or other cheap items, no blocks at all may be necessary.

If the transaction appears in the top block, the depth is one. If it's anything else (pending, dead, unknown) the depth is zero.

setDepthInBlocks

public void setDepthInBlocks(int depth)

getWorkDone

public BigInteger getWorkDone()

Returns the estimated amount of work (number of hashes performed) on this transaction. Work done is a measure of security that is related to depth in blocks, but more predictable: the network will always attempt to produce six blocks per hour by adjusting the difficulty target. So to know how much real computation effort is needed to reverse a transaction, counting blocks is not enough. If a transaction has not confirmed, the result is zero.

Returns:

estimated number of hashes needed to reverse the transaction.

setWorkDone

public void setWorkDone(BigInteger workDone)

getOverridingTransaction

public Transaction getOverridingTransaction()

If this transaction has been overridden by a double spend (is dead), this call returns the overriding transaction. Note that this call can return null if you have migrated an old wallet, as pre-Jan 2012 wallets did not store this information.

Returns:

the transaction that double spent this one

Throws:

IllegalStateException - if confidence type is not OVERRIDDEN_BY_DOUBLE_SPEND.

setOverridingTransaction

public void setOverridingTransaction(@Nullable
                                     Transaction overridingTransaction)

Called when the transaction becomes newly dead, that is, we learn that one of its inputs has already been spent in such a way that the double-spending transaction takes precedence over this one. It will not become valid now unless there is a re-org. Automatically sets the confidence type to DEAD.

duplicate

public TransactionConfidence duplicate()

Returns a copy of this object. Event listeners are not duplicated.

queueListeners

public void queueListeners(TransactionConfidence.Listener.ChangeReason reason)

Call this after adjusting the confidence, for cases where listeners should be notified. This has to be done explicitly rather than being done automatically because sometimes complex changes to transaction states can result in a series of confidence changes that are not really useful to see separately. By invoking listeners explicitly, more precise control is available. Note that this will run the listeners on the user code thread.

getSource

public TransactionConfidence.Source getSource()

The source of a transaction tries to identify where it came from originally. For instance, did we download it from the peer to peer network, or make it ourselves, or receive it via Bluetooth, or import it from another app, and so on. This information is useful for CoinSelector implementations to risk analyze transactions and decide when to spend them.

setSource

public void setSource(TransactionConfidence.Source source)

The source of a transaction tries to identify where it came from originally. For instance, did we download it from the peer to peer network, or make it ourselves, or receive it via Bluetooth, or import it from another app, and so on. This information is useful for CoinSelector implementations to risk analyze transactions and decide when to spend them.

getDepthFuture

public com.google.common.util.concurrent.ListenableFuture<Transaction> getDepthFuture(int depth,
                                                                                      Executor executor)

Returns a future that completes when the transaction has been confirmed by "depth" blocks. For instance setting depth to one will wait until it appears in a block on the best chain, and zero will wait until it has been seen on the network.

getDepthFuture

public com.google.common.util.concurrent.ListenableFuture<Transaction> getDepthFuture(int depth)