TransactionConfidence (bitcoinj 0.12 API)

java.lang.Object
- org.bitcoinj.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 incrementDepthInBlocks() method to ensure the block depth is up to date.
To make a copy that won't be changed, use duplicate().
See Also:

Serialized Form

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(Transaction tx)

Constructors
Constructor and Description
`TransactionConfidence(Transaction tx)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 `PeerAddress`es that announced the transaction.
`TransactionConfidence.ConfidenceType`	`getConfidenceType()` Returns a general statement of the level of confidence you can have in this transaction.
`ListenableFuture<Transaction>`	`getDepthFuture(int depth)`
`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.
`void`	`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`	`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(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(org.bitcoinj.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
  - incrementDepthInBlocks
```
public void 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.
  - 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)
```
  - 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. 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<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 ListenableFuture<Transaction> getDepthFuture(int depth)
```

Class TransactionConfidence

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TransactionConfidence

Method Detail

addEventListener

addEventListener

removeEventListener

getAppearedAtChainHeight

setAppearedAtChainHeight

getConfidenceType

setConfidenceType

markBroadcastBy

numBroadcastPeers

getBroadcastBy

wasBroadcastBy

toString

incrementDepthInBlocks

getDepthInBlocks

setDepthInBlocks

getOverridingTransaction

setOverridingTransaction

duplicate

queueListeners

getSource

setSource

getDepthFuture

getDepthFuture