com.google.bitcoin.core

Class MemoryPool

java.lang.Object

com.google.bitcoin.core.MemoryPool

public class MemoryPool
extends Object

Tracks transactions that are being announced across the network. Typically one is created for you by a PeerGroup and then given to each Peer to update. The current purpose is to let Peers update the confidence (number of peers broadcasting). It helps address an attack scenario in which a malicious remote peer (or several) feeds you invalid transactions, eg, ones that spend coins which don't exist. If you don't see most of the peers announce the transaction within a reasonable time, it may be that the TX is not valid. Alternatively, an attacker may control your entire internet connection: in this scenario counting broadcasting peers does not help you.

It is not at this time directly equivalent to the Satoshi clients memory pool, which tracks all transactions not currently included in the best chain - it's simply a cache.

Field Summary

Fields

Modifier and Type	Field and Description
protected ReentrantLock	lock
static int	MAX_SIZE The max size of a memory pool created with the no-args constructor.

Constructor Summary

Constructors

Constructor and Description
MemoryPool() Creates a memory pool that will track at most MAX_SIZE entries.
MemoryPool(int size) Creates a memory pool that will track at most the given number of transactions (allowing you to bound memory usage).

Method Summary

Methods

Modifier and Type	Method and Description
Transaction	get(Sha256Hash hash) Returns the Transaction for the given hash if we have downloaded it, or null if that hash is unknown or we only saw advertisements for it yet or it has been downloaded but garbage collected due to nowhere else holding a reference to it.
Transaction	intern(Transaction tx) Puts the tx into the table and returns either it, or a different Transaction object that has the same hash.
boolean	maybeWasSeen(Sha256Hash hash) Returns true if the TX identified by hash has been seen before (ie, in an inv).
int	numBroadcastPeers(Sha256Hash txHash) Returns the number of peers that have seen the given hash recently.
void	seen(Sha256Hash hash, PeerAddress byPeer) Called by peers when they see a transaction advertised in an "inv" message.
Transaction	seen(Transaction tx, PeerAddress byPeer) Called by peers when they receive a "tx" message containing a valid serialized transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

lock

protected ReentrantLock lock

MAX_SIZE

public static final int MAX_SIZE

The max size of a memory pool created with the no-args constructor.

See Also:

Constant Field Values

Constructor Detail

MemoryPool

public MemoryPool(int size)

Creates a memory pool that will track at most the given number of transactions (allowing you to bound memory usage).

Parameters:

size - Max number of transactions to track. The pool will fill up to this size then stop growing.

MemoryPool

public MemoryPool()

Creates a memory pool that will track at most MAX_SIZE entries. You should normally use this constructor.

Method Detail

numBroadcastPeers

public int numBroadcastPeers(Sha256Hash txHash)

Returns the number of peers that have seen the given hash recently.

intern

public Transaction intern(Transaction tx)

Puts the tx into the table and returns either it, or a different Transaction object that has the same hash. Unlike seen and the other methods, this one does not imply that a tx has been announced by a peer and does not mark it as such.

seen

public Transaction seen(Transaction tx,
               PeerAddress byPeer)

Called by peers when they receive a "tx" message containing a valid serialized transaction.

Parameters:

tx - The TX deserialized from the wire.

byPeer - The Peer that received it.

Returns:

An object that is semantically the same TX but may be a different object instance.

seen

public void seen(Sha256Hash hash,
        PeerAddress byPeer)

Called by peers when they see a transaction advertised in an "inv" message. It either will increase the confidence of the pre-existing transaction or will just keep a record of the address for future usage.

get

@Nullable
public Transaction get(Sha256Hash hash)

Returns the Transaction for the given hash if we have downloaded it, or null if that hash is unknown or we only saw advertisements for it yet or it has been downloaded but garbage collected due to nowhere else holding a reference to it.

maybeWasSeen

public boolean maybeWasSeen(Sha256Hash hash)

Returns true if the TX identified by hash has been seen before (ie, in an inv). Note that a transaction that was broadcast, downloaded and nothing kept a reference to it will eventually be cleared out by the garbage collector and wasSeen() will return false - it does not keep a permanent record of every hash ever broadcast.