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

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

  • Constructor Details

    • TransactionConfidence

      public TransactionConfidence(Sha256Hash hash)

  • Method Details

    • 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 NewBestBlockListener and related listeners, attach them 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()

    • getLastBroadcastTime

      public Optional<Instant> getLastBroadcastTime()
      Return the time the transaction was last announced to us, or empty if unknown.
      Returns:
      time the transaction was last announced to us, or empty if unknown

    • getLastBroadcastedAt

      @Deprecated @Nullable public Date getLastBroadcastedAt()
      Deprecated.
      use getLastBroadcastTime()

    • setLastBroadcastTime

      public void setLastBroadcastTime(Instant lastBroadcastTime)
      Set the time the transaction was last announced to us.
      Parameters:
      lastBroadcastTime - time the transaction was last announced to us

    • setLastBroadcastedAt

      @Deprecated public void setLastBroadcastedAt(Date lastBroadcastedAt)
      Deprecated.
      use setLastBroadcastTime(Instant)

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

    • getOverridingTxId

      @Nullable public Sha256Hash getOverridingTxId()
      If this transaction has been overridden by a double spend (is dead), this call returns the overriding transaction ID. 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 id that double spent this one
      Throws:
      IllegalStateException - if confidence type is not DEAD.

    • setOverridingTransaction

      @Deprecated public void setOverridingTransaction(Transaction overridingTransaction)
      Deprecated.
      Use getOverridingTxId() (and null is no-longer allowed)
      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.

    • setOverridingTxId

      public void setOverridingTxId(@Nullable Sha256Hash overridingTxId)
      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.

      Once set it's immutable.

    • maybeSetSourceToNetwork

      public void maybeSetSourceToNetwork()
      Called when we receive a transaction from the network. It's possible we may have already seen this locally so we don't want to override a setting of Source.SELF, but if source was not set, we should set it. This method should only be used internally to bitcoinj and will be removed in a future release.

    • getDepthFuture

      public ListenableCompletableFuture<TransactionConfidence> getDepthFuture(int depth)

    • getTransactionHash

      public Sha256Hash getTransactionHash()