Package org.bitcoinj.core

Class Peer

java.lang.Object
org.bitcoinj.net.AbstractTimeoutHandler
org.bitcoinj.core.PeerSocketHandler
org.bitcoinj.core.Peer
All Implemented Interfaces:
StreamConnection
public class Peer extends PeerSocketHandler

A Peer handles the high level communication with a Bitcoin node, extending a PeerSocketHandler which handles low-level message (de)serialization.

Note that timeouts are handled by the extended AbstractTimeoutHandler and timeout is automatically disabled (using AbstractTimeoutHandler.setTimeoutEnabled(boolean)) once the version handshake completes.

  • Field Details

  • Constructor Details

  • Method Details

    • addBlocksDownloadedEventListener

      public void addBlocksDownloadedEventListener(BlocksDownloadedEventListener listener)
      Registers a listener that is invoked when new blocks are downloaded.

    • addBlocksDownloadedEventListener

      public void addBlocksDownloadedEventListener(Executor executor, BlocksDownloadedEventListener listener)
      Registers a listener that is invoked when new blocks are downloaded.

    • addChainDownloadStartedEventListener

      public void addChainDownloadStartedEventListener(ChainDownloadStartedEventListener listener)
      Registers a listener that is invoked when a blockchain downloaded starts.

    • addChainDownloadStartedEventListener

      public void addChainDownloadStartedEventListener(Executor executor, ChainDownloadStartedEventListener listener)
      Registers a listener that is invoked when a blockchain downloaded starts.

    • addConnectedEventListener

      public void addConnectedEventListener(PeerConnectedEventListener listener)
      Registers a listener that is invoked when a peer is connected.

    • addConnectedEventListener

      public void addConnectedEventListener(Executor executor, PeerConnectedEventListener listener)
      Registers a listener that is invoked when a peer is connected.

    • addDisconnectedEventListener

      public void addDisconnectedEventListener(PeerDisconnectedEventListener listener)
      Registers a listener that is invoked when a peer is disconnected.

    • addDisconnectedEventListener

      public void addDisconnectedEventListener(Executor executor, PeerDisconnectedEventListener listener)
      Registers a listener that is invoked when a peer is disconnected.

    • addGetDataEventListener

      public void addGetDataEventListener(GetDataEventListener listener)
      Registers a listener that is called when messages are received.

    • addGetDataEventListener

      public void addGetDataEventListener(Executor executor, GetDataEventListener listener)
      Registers a listener that is called when messages are received.

    • addOnTransactionBroadcastListener

      public void addOnTransactionBroadcastListener(OnTransactionBroadcastListener listener)
      Registers a listener that is called when a transaction is broadcast across the network

    • addOnTransactionBroadcastListener

      public void addOnTransactionBroadcastListener(Executor executor, OnTransactionBroadcastListener listener)
      Registers a listener that is called when a transaction is broadcast across the network

    • addPreMessageReceivedEventListener

      public void addPreMessageReceivedEventListener(PreMessageReceivedEventListener listener)
      Registers a listener that is called immediately before a message is received

    • addPreMessageReceivedEventListener

      public void addPreMessageReceivedEventListener(Executor executor, PreMessageReceivedEventListener listener)
      Registers a listener that is called immediately before a message is received

    • removeBlocksDownloadedEventListener

      public boolean removeBlocksDownloadedEventListener(BlocksDownloadedEventListener listener)

    • removeChainDownloadStartedEventListener

      public boolean removeChainDownloadStartedEventListener(ChainDownloadStartedEventListener listener)

    • removeConnectedEventListener

      public boolean removeConnectedEventListener(PeerConnectedEventListener listener)

    • removeDisconnectedEventListener

      public boolean removeDisconnectedEventListener(PeerDisconnectedEventListener listener)

    • removeGetDataEventListener

      public boolean removeGetDataEventListener(GetDataEventListener listener)

    • removeOnTransactionBroadcastListener

      public boolean removeOnTransactionBroadcastListener(OnTransactionBroadcastListener listener)

    • removePreMessageReceivedEventListener

      public boolean removePreMessageReceivedEventListener(PreMessageReceivedEventListener listener)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toStringServices

      @Deprecated public String toStringServices(long services)
      Deprecated.

    • timeoutOccurred

      protected void timeoutOccurred()
      Overrides:
      timeoutOccurred in class PeerSocketHandler

    • connectionClosed

      public void connectionClosed()
      Description copied from interface: StreamConnection
      Called when the connection socket is closed

    • connectionOpened

      public void connectionOpened()
      Description copied from interface: StreamConnection
      Called when the connection socket is first opened

    • getConnectionOpenFuture

      public com.google.common.util.concurrent.ListenableFuture<Peer> getConnectionOpenFuture()
      Provides a ListenableFuture that can be used to wait for the socket to connect. A socket connection does not mean that protocol handshake has occurred.

    • getVersionHandshakeFuture

      public com.google.common.util.concurrent.ListenableFuture<Peer> getVersionHandshakeFuture()

    • processMessage

      protected void processMessage(Message m) throws Exception
      Description copied from class: PeerSocketHandler
      Called every time a message is received from the network
      Specified by:
      processMessage in class PeerSocketHandler
      Throws:
      Exception

    • processUTXOMessage

      protected void processUTXOMessage(UTXOsMessage m)

    • startFilteredBlock

      protected void startFilteredBlock(FilteredBlock m)

    • processNotFoundMessage

      protected void processNotFoundMessage(NotFoundMessage m)

    • processHeaders

      protected void processHeaders(HeadersMessage m) throws ProtocolException
      Throws:
      ProtocolException

    • processGetData

      protected void processGetData(GetDataMessage getdata)

    • processTransaction

      protected void processTransaction(Transaction tx) throws VerificationException
      Throws:
      VerificationException

    • downloadDependencies

      public com.google.common.util.concurrent.ListenableFuture<List<Transaction>> downloadDependencies(Transaction tx)

      Returns a future that wraps a list of all transactions that the given transaction depends on, recursively. Only transactions in peers memory pools are included; the recursion stops at transactions that are in the current best chain. So it doesn't make much sense to provide a tx that was already in the best chain and a precondition checks this.

      For example, if tx has 2 inputs that connect to transactions A and B, and transaction B is unconfirmed and has one input connecting to transaction C that is unconfirmed, and transaction C connects to transaction D that is in the chain, then this method will return either {B, C} or {C, B}. No ordering is guaranteed.

      This method is useful for apps that want to learn about how long an unconfirmed transaction might take to confirm, by checking for unexpectedly time locked transactions, unusually deep dependency trees or fee-paying transactions that depend on unconfirmed free transactions.

      Note that dependencies downloaded this way will not trigger the onTransaction method of event listeners.

    • downloadDependenciesInternal

      protected com.google.common.util.concurrent.ListenableFuture<Object> downloadDependenciesInternal(int maxDepth, int depth, Transaction tx, Object marker, List<Transaction> results)

    • processBlock

      protected void processBlock(Block m)

    • endFilteredBlock

      protected void endFilteredBlock(FilteredBlock m)

    • processInv

      protected void processInv(InventoryMessage inv)

    • getBlock

      public com.google.common.util.concurrent.ListenableFuture<Block> getBlock(Sha256Hash blockHash)
      Asks the connected peer for the block of the given hash, and returns a future representing the answer. If you want the block right away and don't mind waiting for it, just call .get() on the result. Your thread will block until the peer answers.

    • getPeerMempoolTransaction

      public com.google.common.util.concurrent.ListenableFuture<Transaction> getPeerMempoolTransaction(Sha256Hash hash)
      Asks the connected peer for the given transaction from its memory pool. Transactions in the chain cannot be retrieved this way because peers don't have a transaction ID to transaction-pos-on-disk index, and besides, in future many peers will delete old transaction data they don't need.

    • getAddr

      public com.google.common.util.concurrent.ListenableFuture<AddressMessage> getAddr()
      Sends a getaddr request to the peer and returns a future that completes with the answer once the peer has replied.

    • setDownloadParameters

      public void setDownloadParameters(long secondsSinceEpoch, boolean useFilteredBlocks)
      When downloading the block chain, the bodies will be skipped for blocks created before the given date. Any transactions relevant to the wallet will therefore not be found, but if you know your wallet has no such transactions it doesn't matter and can save a lot of bandwidth and processing time. Note that the times of blocks isn't known until their headers are available and they are requested in chunks, so some headers may be downloaded twice using this scheme, but this optimization can still be a large win for newly created wallets.
      Parameters:
      secondsSinceEpoch - Time in seconds since the epoch or 0 to reset to always downloading block bodies.

    • addWallet

      public void addWallet(Wallet wallet)
      Links the given wallet to this peer. If you have multiple peers, you should use a PeerGroup to manage them and use the PeerGroup.addWallet(Wallet) method instead of registering the wallet with each peer independently, otherwise the wallet will receive duplicate notifications.

    • removeWallet

      public void removeWallet(Wallet wallet)
      Unlinks the given wallet from peer. See addWallet(Wallet).

    • startBlockChainDownload

      public void startBlockChainDownload()
      Starts an asynchronous download of the block chain. The chain download is deemed to be complete once we've downloaded the same number of blocks that the peer advertised having in its version handshake message.

    • ping

      public com.google.common.util.concurrent.ListenableFuture<Long> ping() throws ProtocolException
      Sends the peer a ping message and returns a future that will be invoked when the pong is received back. The future provides a number which is the number of milliseconds elapsed between the ping and the pong. Once the pong is received the value returned by getLastPingTime() is updated.
      Throws:
      ProtocolException - if the peer version is too low to support measurable pings.

    • ping

      protected com.google.common.util.concurrent.ListenableFuture<Long> ping(long nonce) throws ProtocolException
      Throws:
      ProtocolException

    • getLastPingTime

      public long getLastPingTime()
      Returns the elapsed time of the last ping/pong cycle. If ping() has never been called or we did not hear back the "pong" message yet, returns Long.MAX_VALUE.

    • getPingTime

      public long getPingTime()
      Returns a moving average of the last N ping/pong cycles. If ping() has never been called or we did not hear back the "pong" message yet, returns Long.MAX_VALUE. The moving average window is 5 buckets.

    • processPong

      protected void processPong(Pong m)

    • getPeerBlockHeightDifference

      public int getPeerBlockHeightDifference()
      Returns the difference between our best chain height and the peers, which can either be positive if we are behind the peer, or negative if the peer is ahead of us.

    • isDownloadData

      public boolean isDownloadData()
      Returns true if this peer will try and download things it is sent in "inv" messages. Normally you only need one peer to be downloading data. Defaults to true.

    • setDownloadData

      public void setDownloadData(boolean downloadData)
      If set to false, the peer won't try and fetch blocks and transactions it hears about. Normally, only one peer should download missing blocks. Defaults to true. Changing this value from false to true may trigger a request to the remote peer for the contents of its memory pool, if Bloom filtering is active.

    • getPeerVersionMessage

      public VersionMessage getPeerVersionMessage()
      Returns version data announced by the remote peer.

    • getFeeFilter

      public Coin getFeeFilter()
      Returns the fee filter announced by the remote peer, interpreted as satoshis per kB.

    • getVersionMessage

      public VersionMessage getVersionMessage()
      Returns version data we announce to our remote peers.

    • getBestHeight

      public long getBestHeight()
      Returns:
      the height of the best chain as claimed by peer: sum of its ver announcement and blocks announced since.

    • setMinProtocolVersion

      public boolean setMinProtocolVersion(int minProtocolVersion)
      The minimum P2P protocol version that is accepted. If the peer speaks a protocol version lower than this, it will be disconnected.
      Returns:
      true if the peer was disconnected as a result

    • setBloomFilter

      public void setBloomFilter(BloomFilter filter)

      Sets a Bloom filter on this connection. This will cause the given BloomFilter object to be sent to the remote peer and if either a memory pool has been set using the constructor or the vDownloadData property is true, a MemoryPoolMessage is sent as well to trigger downloading of any pending transactions that may be relevant.

      The Peer does not automatically request filters from any wallets added using addWallet(Wallet). This is to allow callers to avoid redundantly recalculating the same filter repeatedly when using multiple peers and multiple wallets together.

      Therefore, you should not use this method if your app uses a PeerGroup. It is called for you.

      If the remote peer doesn't support Bloom filtering, then this call is ignored. Once set you presently cannot unset a filter, though the underlying p2p protocol does support it.

    • setBloomFilter

      public void setBloomFilter(BloomFilter filter, boolean andQueryMemPool)

      Sets a Bloom filter on this connection. This will cause the given BloomFilter object to be sent to the remote peer and if requested, a MemoryPoolMessage is sent as well to trigger downloading of any pending transactions that may be relevant.

      The Peer does not automatically request filters from any wallets added using addWallet(Wallet). This is to allow callers to avoid redundantly recalculating the same filter repeatedly when using multiple peers and multiple wallets together.

      Therefore, you should not use this method if your app uses a PeerGroup. It is called for you.

      If the remote peer doesn't support Bloom filtering, then this call is ignored. Once set you presently cannot unset a filter, though the underlying p2p protocol does support it.

    • getBloomFilter

      public BloomFilter getBloomFilter()
      Returns the last BloomFilter set by setBloomFilter(BloomFilter). Bloom filters tell the remote node what transactions to send us, in a compact manner.

    • getUTXOs

      public com.google.common.util.concurrent.ListenableFuture<UTXOsMessage> getUTXOs(List<TransactionOutPoint> outPoints)
      Sends a query to the remote peer asking for the unspent transaction outputs (UTXOs) for the given outpoints, with the memory pool included. The result should be treated only as a hint: it's possible for the returned outputs to be fictional and not exist in any transaction, and it's possible for them to be spent the moment after the query returns. Most peers do not support this request. You will need to connect to Bitcoin XT peers if you want this to work.
      Throws:
      ProtocolException - if this peer doesn't support the protocol.

    • getUTXOs

      public com.google.common.util.concurrent.ListenableFuture<UTXOsMessage> getUTXOs(List<TransactionOutPoint> outPoints, boolean includeMempool)
      Sends a query to the remote peer asking for the unspent transaction outputs (UTXOs) for the given outpoints. The result should be treated only as a hint: it's possible for the returned outputs to be fictional and not exist in any transaction, and it's possible for them to be spent the moment after the query returns. Most peers do not support this request. You will need to connect to Bitcoin XT peers if you want this to work.
      Parameters:
      includeMempool - If true (the default) the results take into account the contents of the memory pool too.
      Throws:
      ProtocolException - if this peer doesn't support the protocol.

    • isDownloadTxDependencies

      public boolean isDownloadTxDependencies()
      Returns true if this peer will use getdata/notfound messages to walk backwards through transaction dependencies before handing the transaction off to the wallet. The wallet can do risk analysis on pending/recent transactions to try and discover if a pending tx might be at risk of double spending.

    • setDownloadTxDependencies

      public void setDownloadTxDependencies(boolean enable)
      Sets if this peer will use getdata/notfound messages to walk backwards through transaction dependencies before handing the transaction off to the wallet. The wallet can do risk analysis on pending/recent transactions to try and discover if a pending tx might be at risk of double spending.

    • setDownloadTxDependencies

      public void setDownloadTxDependencies(int depth)
      Sets if this peer will use getdata/notfound messages to walk backwards through transaction dependencies before handing the transaction off to the wallet. The wallet can do risk analysis on pending/recent transactions to try and discover if a pending tx might be at risk of double spending.