Class TransactionConfidence
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 in a block on the best 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.
duplicate()
.-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
Describes the state of the transaction in general terms.static class
static interface
A confidence listener is informed when the level ofTransactionConfidence
is updated by something, like for example aWallet
.static enum
Information about where the transaction was first seen (network, sent direct from peer, created by ourselves). -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addEventListener
(Executor executor, TransactionConfidence.Listener listener) Adds an event listener that will be run when this confidence object is updated.void
Adds an event listener that will be run when this confidence object is updated.void
Erases the set of broadcast/seen peers.Returns a copy of this object.int
Returns the chain height at which the transaction appeared if confidence type is BUILDING.Returns a snapshot ofPeerAddress
es that announced the transaction.Returns a general statement of the level of confidence you can have in this transaction.com.google.common.util.concurrent.ListenableFuture<TransactionConfidence>
getDepthFuture
(int depth) com.google.common.util.concurrent.ListenableFuture<TransactionConfidence>
getDepthFuture
(int depth, Executor executor) Returns a future that completes when the transaction has been confirmed by "depth" blocks.int
Depth in the chain is an approximation of how much time has elapsed since the transaction has been confirmed.Return the time the transaction was last announced to us.If this transaction has been overridden by a double spend (is dead), this call returns the overriding transaction.The source of a transaction tries to identify where it came from originally.int
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 aPeer
when a transaction is pending and announced by a peer.int
Returns how many peers have been passed tomarkBroadcastBy(org.bitcoinj.core.PeerAddress)
.void
Call this after adjusting the confidence, for cases where listeners should be notified.boolean
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 aWallet
, 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
The source of a transaction tries to identify where it came from originally.toString()
boolean
wasBroadcastBy
(PeerAddress address) Returns true if the given address has been seen via markBroadcastBy()
-
Constructor Details
-
TransactionConfidence
-
-
Method Details
-
addEventListener
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
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
NewBestBlockListener
and related listeners, attach them to aBlockChain
and then use the getters on the confidence object to determine the new depth. -
removeEventListener
-
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 toTransactionConfidence.ConfidenceType.BUILDING
and depth to one. -
getConfidenceType
Returns a general statement of the level of confidence you can have in this transaction. -
setConfidenceType
Called by other objects in the system, like aWallet
, when new information about the confidence of a transaction becomes available. -
markBroadcastBy
Called by aPeer
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 toTransactionConfidence.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 tomarkBroadcastBy(org.bitcoinj.core.PeerAddress)
. -
getBroadcastBy
Returns a snapshot ofPeerAddress
es that announced the transaction. -
wasBroadcastBy
Returns true if the given address has been seen via markBroadcastBy() -
getLastBroadcastedAt
Return the time the transaction was last announced to us. -
setLastBroadcastedAt
Set the time the transaction was last announced to us. -
toString
-
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
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
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
Returns a copy of this object. Event listeners are not duplicated. -
queueListeners
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
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 forCoinSelector
implementations to risk analyze transactions and decide when to spend them. -
setSource
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 forCoinSelector
implementations to risk analyze transactions and decide when to spend them. -
getDepthFuture
public com.google.common.util.concurrent.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 com.google.common.util.concurrent.ListenableFuture<TransactionConfidence> getDepthFuture(int depth) -
getTransactionHash
-