org.bitcoinj.core

Class TransactionConfidence

java.lang.Object

org.bitcoinj.core.TransactionConfidence

public class TransactionConfidence
extends Object

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 incrementDepthInBlocks() method to ensure the block depth is up to date.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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

Constructors

Constructor and Description
TransactionConfidence(Sha256Hash hash)

Method Summary

Modifier and Type	Method and Description
void	addEventListener(Executor executor, TransactionConfidence.Listener listener) Adds an event listener that will be run when this confidence object is updated.
void	addEventListener(TransactionConfidence.Listener listener) Adds an event listener that will be run when this confidence object is updated.
void	clearBroadcastBy() Erases the set of broadcast/seen peers.
TransactionConfidence	duplicate() Returns a copy of this object.
int	getAppearedAtChainHeight() Returns the chain height at which the transaction appeared if confidence type is BUILDING.
Set<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.
ListenableFuture<TransactionConfidence>	getDepthFuture(int depth)
ListenableFuture<TransactionConfidence>	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.
Date	getLastBroadcastedAt() Return the time the transaction was last announced to us.
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.
Sha256Hash	getTransactionHash()
int	incrementDepthInBlocks() Called by the wallet when the tx appears on the best chain and a new block is added to the top.
boolean	markBroadcastBy(PeerAddress address) Called by a Peer when a transaction is pending and announced by a peer.
int	numBroadcastPeers() Returns how many peers have been passed to markBroadcastBy(org.bitcoinj.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	setLastBroadcastedAt(Date lastBroadcastedAt) Set the time the transaction was last announced to us.
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.
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(Sha256Hash hash)

Method Detail

addEventListener

public void addEventListener(Executor executor,
                             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, 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. Does not run listeners.

Parameters:

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

Returns:

true if marked, false if this address was already seen

numBroadcastPeers

public int numBroadcastPeers()

Returns how many peers have been passed to markBroadcastBy(org.bitcoinj.core.PeerAddress).

getBroadcastBy

public Set<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()

getLastBroadcastedAt

public Date getLastBroadcastedAt()

Return the time the transaction was last announced to us.

setLastBroadcastedAt

public void setLastBroadcastedAt(Date lastBroadcastedAt)

Set the time the transaction was last announced to us.

toString

public String toString()

Overrides:

toString in class Object

incrementDepthInBlocks

public int incrementDepthInBlocks()

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.

Returns:

the new depth

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. Bitcoin Core 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)

clearBroadcastBy

public void clearBroadcastBy()

Erases the set of broadcast/seen peers. This cannot be called whilst the confidence is PENDING. It is useful for saving memory and wallet space once a tx is buried so deep it doesn't seem likely to go pending again.

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

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. The overriding transaction may not directly double spend this one, but could also have double spent a dependency of this tx.

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 ListenableFuture<TransactionConfidence> 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 ListenableFuture<TransactionConfidence> getDepthFuture(int depth)

getTransactionHash

public Sha256Hash getTransactionHash()