bloom

package

v0.0.0-...-0c57b5a Latest Latest Go to latest Published: Dec 12, 2024 License: ISC Imports: 8 Imported by: 8

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gcash/bchutil

README ¶

bloom

Package bloom provides an API for dealing with bitcoin-specific bloom filters.

A comprehensive suite of tests is provided to ensure proper functionality. See test_coverage.txt for the gocov coverage report. Alternatively, if you are running a POSIX OS, you can run the cov_report.sh script for a real-time report.

Installation and Updating

$ go get -u github.com/gcash/bchutil/bloom

Examples

NewFilter Example Demonstrates how to create a new bloom filter, add a transaction hash to it, and check if the filter matches the transaction.

License

Package bloom is licensed under the copyfree ISC License.

Documentation ¶

Index ¶

func GetMatchedIndices(block *bchutil.Block, filter *Filter) map[int]bool
func MurmurHash3(seed uint32, data []byte) uint32
func NewMerkleBlock(block *bchutil.Block, filter *Filter) (*wire.MsgMerkleBlock, []uint32)
type Filter
- func LoadFilter(filter *wire.MsgFilterLoad) *Filter
- func NewFilter(elements, tweak uint32, fprate float64, flags wire.BloomUpdateType) *Filter

Examples ¶

NewFilter

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func GetMatchedIndices ¶

func GetMatchedIndices(block *bchutil.Block, filter *Filter) map[int]bool

GetMatchedIndices returns the index of the transactions that match the filter. This works even with CTOR ordering.

func MurmurHash3 ¶

func MurmurHash3(seed uint32, data []byte) uint32

MurmurHash3 implements a non-cryptographic hash function using the MurmurHash3 algorithm. This implementation yields a 32-bit hash value which is suitable for general hash-based lookups. The seed can be used to effectively randomize the hash function. This makes it ideal for use in bloom filters which need multiple independent hash functions.

func NewMerkleBlock ¶

func NewMerkleBlock(block *bchutil.Block, filter *Filter) (*wire.MsgMerkleBlock, []uint32)

NewMerkleBlock returns a new *wire.MsgMerkleBlock and an array of the matched transaction index numbers based on the passed block and filter.

Types ¶

type Filter ¶

type Filter struct {
	// contains filtered or unexported fields
}

Filter defines a bitcoin bloom filter that provides easy manipulation of raw filter data.

func LoadFilter ¶

func LoadFilter(filter *wire.MsgFilterLoad) *Filter

LoadFilter creates a new Filter instance with the given underlying wire.MsgFilterLoad.

func NewFilter ¶

func NewFilter(elements, tweak uint32, fprate float64, flags wire.BloomUpdateType) *Filter

NewFilter creates a new bloom filter instance, mainly to be used by SPV clients. The tweak parameter is a random value added to the seed value. The false positive rate is the probability of a false positive where 1.0 is "match everything" and zero is unachievable. Thus, providing any false positive rates less than 0 or greater than 1 will be adjusted to the valid range.

For more information on what values to use for both elements and fprate, see https://en.wikipedia.org/wiki/Bloom_filter.

Example ¶

This example demonstrates how to create a new bloom filter, add a transaction hash to it, and check if the filter matches the transaction.

package main

import (
	"fmt"
	"math/rand"
	"time"

	"github.com/gcash/bchd/chaincfg/chainhash"
	"github.com/gcash/bchd/wire"
	"github.com/gcash/bchutil/bloom"
)

func main() {
	rand.Seed(time.Now().UnixNano())
	tweak := rand.Uint32()

	// Create a new bloom filter intended to hold 10 elements with a 0.01%
	// false positive rate and does not include any automatic update
	// functionality when transactions are matched.
	filter := bloom.NewFilter(10, tweak, 0.0001, wire.BloomUpdateNone)

	// Create a transaction hash and add it to the filter.  This particular
	// trasaction is the first transaction in block 310,000 of the main
	// bitcoin block chain.
	txHashStr := "fd611c56ca0d378cdcd16244b45c2ba9588da3adac367c4ef43e808b280b8a45"
	txHash, err := chainhash.NewHashFromStr(txHashStr)
	if err != nil {
		fmt.Println(err)
		return
	}
	filter.AddHash(txHash)

	// Show that the filter matches.
	matches := filter.Matches(txHash[:])
	fmt.Println("Filter Matches?:", matches)

}

Output:

Filter Matches?: true