com.google.bitcoin.core
Class BloomFilter

java.lang.Object
  com.google.bitcoin.core.Message
      com.google.bitcoin.core.BloomFilter

All Implemented Interfaces:

Serializable

public class BloomFilter
extends Message

A Bloom filter is a probabilistic data structure which can be sent to another client so that it can avoid sending us transactions that aren't relevant to our set of keys. This allows for significantly more efficient use of available network bandwidth and CPU time.

Because a Bloom filter is probabilistic, it has a configurable false positive rate. So the filter will sometimes match transactions that weren't inserted into it, but it will never fail to match transactions that were. This is a useful privacy feature - if you have spare bandwidth the false positive rate can be increased so the remote peer gets a noisy picture of what transactions are relevant to your wallet.

See Also:

Serialized Form

Nested Class Summary

static class

BloomFilter.BloomUpdate The BLOOM_UPDATE_* constants control when the bloom filter is auto-updated by the peer using it as a filter, either never, for all outputs or only for pay-2-pubkey outputs (default)

Nested classes/interfaces inherited from class com.google.bitcoin.core.Message

Message.LazyParseException

Field Summary

Fields inherited from class com.google.bitcoin.core.Message

bytes, checksum, cursor, length, MAX_SIZE, offset, params, parsed, parseLazy, parseRetain, protocolVersion, recached, UNKNOWN_LENGTH

Constructor Summary

BloomFilter(int elements, double falsePositiveRate, long randomNonce)
Constructs a filter with the given parameters which is updated on pay2pubkey outputs only.

BloomFilter(int elements, double falsePositiveRate, long randomNonce, BloomFilter.BloomUpdate updateFlag)
Constructs a new Bloom Filter which will provide approximately the given false positive rate when the given number of elements have been inserted.

BloomFilter(NetworkParameters params, byte[] payloadBytes)
Construct a BloomFilter by deserializing payloadBytes

Method Summary

boolean	contains(byte[] object) Returns true if the given object matches the filter either because it was inserted, or because we have a false-positive.
boolean	equals(Object other)
double	getFalsePositiveRate(int elements) Returns the theoretical false positive rate of this filter if were to contain the given number of elements.
int	hashCode()
void	insert(byte[] object) Insert the given arbitrary data into the filter
boolean	matchesAll() Returns true if this filter will match anything.
void	merge(BloomFilter filter) Copies filter into this.
protected void	parseLite() Perform the most minimal parse possible to calculate the length of the message.
void	setMatchAll() Sets this filter to match all objects.
String	toString()

Methods inherited from class com.google.bitcoin.core.Message

adjustLength, bitcoinSerialize, bitcoinSerialize, ensureParsed, getHash, getMessageSize, getParams, isCached, isParsed, isRecached, maybeParse, unCache, unsafeBitcoinSerialize

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BloomFilter

public BloomFilter(NetworkParameters params,
                   byte[] payloadBytes)
            throws ProtocolException

Construct a BloomFilter by deserializing payloadBytes

Throws:

ProtocolException

BloomFilter

public BloomFilter(int elements,
                   double falsePositiveRate,
                   long randomNonce)

Constructs a filter with the given parameters which is updated on pay2pubkey outputs only.

BloomFilter

public BloomFilter(int elements,
                   double falsePositiveRate,
                   long randomNonce,
                   BloomFilter.BloomUpdate updateFlag)

Constructs a new Bloom Filter which will provide approximately the given false positive rate when the given number of elements have been inserted. If the filter would otherwise be larger than the maximum allowed size, it will be automatically downsized to the maximum size.

To check the theoretical false positive rate of a given filter, use getFalsePositiveRate(int).

The anonymity of which coins are yours to any peer which you send a BloomFilter to is controlled by the false positive rate. For reference, as of block 187,000, the total number of addresses used in the chain was roughly 4.5 million. Thus, if you use a false positive rate of 0.001 (0.1%), there will be, on average, 4,500 distinct public keys/addresses which will be thought to be yours by nodes which have your bloom filter, but which are not actually yours. Keep in mind that a remote node can do a pretty good job estimating the order of magnitude of the false positive rate of a given filter you provide it when considering the anonymity of a given filter.

In order for filtered block download to function efficiently, the number of matched transactions in any given block should be less than (with some headroom) the maximum size of the MemoryPool used by the Peer doing the downloading (default is MemoryPool.MAX_SIZE). See the comment in processBlock(FilteredBlock) for more information on this restriction.

randomNonce is a tweak for the hash function used to prevent some theoretical DoS attacks. It should be a random value, however secureness of the random value is of no great consequence.

updateFlag is used to control filter behaviour on the server (remote node) side when it encounters a hit. See BloomFilter.BloomUpdate for a brief description of each mode. The purpose of this flag is to reduce network round-tripping and avoid over-dirtying the filter for the most common wallet configurations.

Method Detail

getFalsePositiveRate

public double getFalsePositiveRate(int elements)

Returns the theoretical false positive rate of this filter if were to contain the given number of elements.

toString

public String toString()

Overrides:

toString in class Object

parseLite

protected void parseLite()
                  throws ProtocolException

Description copied from class: Message

Perform the most minimal parse possible to calculate the length of the message. This is only required for subclasses of ChildClass as root level messages will have their length passed into the constructor.

Implementations should adhere to the following contract: If parseLazy = true the 'length' field must be set before returning. If parseLazy = false the length field must be set either within the parseLite() method OR the parse() method. The overriding requirement is that length must be set to non UNKNOWN_MESSAGE value by the time the constructor exits.

Specified by:

parseLite in class Message

Throws:

ProtocolException

contains

public boolean contains(byte[] object)

Returns true if the given object matches the filter either because it was inserted, or because we have a false-positive.

insert

public void insert(byte[] object)

Insert the given arbitrary data into the filter

setMatchAll

public void setMatchAll()

Sets this filter to match all objects. A Bloom filter which matches everything may seem pointless, however, it is useful in order to reduce steady state bandwidth usage when you want full blocks. Instead of receiving all transaction data twice, you will receive the vast majority of all transactions just once, at broadcast time. Solved blocks will then be send just as Merkle trees of tx hashes, meaning a constant 32 bytes of data for each transaction instead of 100-300 bytes as per usual.

merge

public void merge(BloomFilter filter)

Copies filter into this. Filter must have the same size, hash function count and nTweak or an IllegalArgumentException will be thrown.

matchesAll

public boolean matchesAll()

Returns true if this filter will match anything. See setMatchAll() for when this can be a useful thing to do.

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object