Package org.bitcoinj.core

Class TransactionBroadcast

java.lang.Object
org.bitcoinj.core.TransactionBroadcast
public class TransactionBroadcast extends Object
Represents a single transaction broadcast that we are performing. A broadcast occurs after a new transaction is created (typically by a Wallet) and needs to be sent to the network. A broadcast can succeed or fail. A success is defined as seeing the transaction be announced by peers via inv messages, thus indicating their acceptance. A failure is defined as not reaching acceptance within a timeout period, or getting an explicit reject message from a peer indicating that the transaction was not acceptable.

  • Field Details

    • random

      public static Random random
      Used for shuffling the peers before broadcast: unit tests can replace this to make themselves deterministic.

  • Method Details

    • transaction

      public Transaction transaction()

    • createMockBroadcast

      public static TransactionBroadcast createMockBroadcast(Transaction tx, CompletableFuture<Transaction> future)

    • future

      @Deprecated public ListenableCompletableFuture<Transaction> future()
      Deprecated.
      Use awaitRelayed() (and maybe CompletableFuture.thenApply(Function))
      Returns:
      future that completes when some number of remote peers has rebroadcast the transaction

    • setMinConnections

      public void setMinConnections(int minConnections)

    • setDropPeersAfterBroadcast

      public void setDropPeersAfterBroadcast(boolean dropPeersAfterBroadcast)

    • broadcastOnly

      public CompletableFuture<TransactionBroadcast> broadcastOnly()
      Broadcast this transaction to the proper calculated number of peers. Returns a future that completes when the message has been "sent" to a set of remote peers. The TransactionBroadcast itself is the returned type/value for the future.

      The complete broadcast process includes the following steps:

      1. Wait until enough Peers are connected.
      2. Broadcast the transaction to a determined number of Peers
      3. Wait for confirmation from a determined number of remote peers that they have received the broadcast
      4. Mark awaitRelayed() ()} ("seen future") as complete
      The future returned from this method completes when Step 2 is completed.

      It should further be noted that "broadcast" in this class means that MessageWriteTarget.writeBytes(byte[]) has completed successfully which means the message has been sent to the "OS network buffer" -- see MessageWriteTarget.writeBytes(byte[]) or its implementation.

      Returns:
      A future that completes when the message has been sent (or at least buffered) to the correct number of remote Peers. The future will complete exceptionally if any of the peer broadcasts fails.

    • broadcastAndAwaitRelay

      public CompletableFuture<TransactionBroadcast> broadcastAndAwaitRelay()
      Broadcast the transaction and wait for confirmation that the transaction has been received by the appropriate number of Peers before completing.
      Returns:
      A future that completes when the message has been relayed by the appropriate number of remote peers

    • awaitRelayed

      public CompletableFuture<TransactionBroadcast> awaitRelayed()
      Wait for confirmation the transaction has been relayed.
      Returns:
      A future that completes when the message has been relayed by the appropriate number of remote peers

    • awaitSent

      public CompletableFuture<TransactionBroadcast> awaitSent()
      Wait for confirmation the transaction has been sent to a remote peer. (Or at least buffered to be sent to a peer.)
      Returns:
      A future that completes when the message has been relayed by the appropriate number of remote peers

    • broadcast

      @Deprecated public ListenableCompletableFuture<Transaction> broadcast()
      Deprecated.
      Use broadcastAndAwaitRelay() or broadcastOnly() as appropriate
      If you migrate to broadcastAndAwaitRelay() and need a CompletableFuture that returns Transaction you can use: 
      
  CompletableFuture<Transaction> seenFuture = broadcast
              .broadcastAndAwaitRelay()
              .thenApply(TransactionBroadcast::transaction);

    • setProgressCallback

      public void setProgressCallback(TransactionBroadcast.ProgressCallback callback)
      Sets the given callback for receiving progress values, which will run on the user thread. See Threading for details. If the broadcast has already started then the callback will be invoked immediately with the current progress.

    • setProgressCallback

      public void setProgressCallback(TransactionBroadcast.ProgressCallback callback, @Nullable Executor executor)
      Sets the given callback for receiving progress values, which will run on the given executor. If the executor is null then the callback will run on a network thread and may be invoked multiple times in parallel. You probably want to provide your UI thread or Threading.USER_THREAD for the second parameter. If the broadcast has already started then the callback will be invoked immediately with the current progress.