Add filter builder and some tests
This commit is contained in:
Alex
Olaoluwa Osuntokun
parent
53c8e22157
commit
6654eb61e4
2 changed files with 380 additions and 0 deletions
275
gcs/builder/builder.go
Normal file
275
gcs/builder/builder.go
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
// Copyright (c) 2017 The btcsuite developers
|
||||
// Copyright (c) 2017 The Lightning Network Developers
|
||||
// Use of this source code is governed by an ISC
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
package builder
|
||||
|
||||
import (
|
||||
"crypto/rand"
|
||||
"encoding/binary"
|
||||
|
||||
"github.com/btcsuite/btcd/chaincfg/chainhash"
|
||||
"github.com/btcsuite/btcd/txscript"
|
||||
"github.com/btcsuite/btcd/wire"
|
||||
"github.com/btcsuite/btcutil/gcs"
|
||||
)
|
||||
|
||||
const DefaultP = 20
|
||||
|
||||
// GCSBuilder is a utility class that makes building GCS filters convenient.
|
||||
type GCSBuilder struct {
|
||||
p uint8
|
||||
key [gcs.KeySize]byte
|
||||
data [][]byte
|
||||
err error
|
||||
}
|
||||
|
||||
// RandomKey is a utility function that returns a cryptographically random
|
||||
// [gcs.KeySize]byte usable as a key for a GCS filter.
|
||||
func RandomKey() ([gcs.KeySize]byte, error) {
|
||||
var key [gcs.KeySize]byte
|
||||
|
||||
// Read a byte slice from rand.Reader.
|
||||
randKey := make([]byte, gcs.KeySize)
|
||||
_, err := rand.Read(randKey)
|
||||
|
||||
// This shouldn't happen unless the user is on a system that doesn't
|
||||
// have a system CSPRNG. OK to panic in this case.
|
||||
if err != nil {
|
||||
return key, err
|
||||
}
|
||||
|
||||
// Copy the byte slice to a [gcs.KeySize]byte array and return it.
|
||||
copy(key[:], randKey[:])
|
||||
return key, nil
|
||||
}
|
||||
|
||||
// DeriveKey is a utility function that derives a key from a chainhash.Hash by
|
||||
// truncating the bytes of the hash to the appopriate key size.
|
||||
func DeriveKey(keyHash *chainhash.Hash) [gcs.KeySize]byte {
|
||||
var key [gcs.KeySize]byte
|
||||
copy(key[:], keyHash.CloneBytes()[:])
|
||||
return key
|
||||
}
|
||||
|
||||
// OutPointToFilterEntry is a utility function that derives a filter entry from
|
||||
// a wire.OutPoint in a standardized way for use with both building and querying
|
||||
// filters.
|
||||
func OutPointToFilterEntry(outpoint wire.OutPoint) []byte {
|
||||
// Size of the hash plus size of int32 index
|
||||
data := make([]byte, chainhash.HashSize+4)
|
||||
copy(data[:], outpoint.Hash.CloneBytes()[:])
|
||||
binary.BigEndian.PutUint32(data[chainhash.HashSize:], outpoint.Index)
|
||||
return data
|
||||
}
|
||||
|
||||
// Key retrieves the key with which the builder will build a filter. This is
|
||||
// useful if the builder is created with a random initial key.
|
||||
func (b *GCSBuilder) Key() ([gcs.KeySize]byte, error) {
|
||||
// Do nothing if the builder's errored out.
|
||||
if b.err != nil {
|
||||
return [gcs.KeySize]byte{}, b.err
|
||||
}
|
||||
|
||||
return b.key, nil
|
||||
}
|
||||
|
||||
// SetKey sets the key with which the builder will build a filter to the passed
|
||||
// [gcs.KeySize]byte.
|
||||
func (b *GCSBuilder) SetKey(key [gcs.KeySize]byte) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
copy(b.key[:], key[:])
|
||||
return b
|
||||
}
|
||||
|
||||
// SetKeyFromHash sets the key with which the builder will build a filter to a
|
||||
// key derived from the passed chainhash.Hash using DeriveKey().
|
||||
func (b *GCSBuilder) SetKeyFromHash(keyHash *chainhash.Hash) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
return b.SetKey(DeriveKey(keyHash))
|
||||
}
|
||||
|
||||
// SetP sets the filter's probability after calling Builder().
|
||||
func (b *GCSBuilder) SetP(p uint8) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
// Basic sanity check.
|
||||
if p > 32 {
|
||||
b.err = gcs.ErrPTooBig
|
||||
return b
|
||||
}
|
||||
|
||||
b.p = p
|
||||
return b
|
||||
}
|
||||
|
||||
// Preallocate sets the estimated filter size after calling Builder() to reduce
|
||||
// the probability of memory reallocations. If the builder has already had data
|
||||
// added to it, SetN has no effect.
|
||||
func (b *GCSBuilder) Preallocate(n uint32) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
if len(b.data) == 0 {
|
||||
b.data = make([][]byte, 0, n)
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
// AddEntry adds a []byte to the list of entries to be included in the GCS
|
||||
// filter when it's built.
|
||||
func (b *GCSBuilder) AddEntry(data []byte) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
b.data = append(b.data, data)
|
||||
return b
|
||||
}
|
||||
|
||||
// AddEntries adds all the []byte entries in a [][]byte to the list of entries
|
||||
// to be included in the GCS filter when it's built.
|
||||
func (b *GCSBuilder) AddEntries(data [][]byte) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
for _, entry := range data {
|
||||
b.AddEntry(entry)
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
// AddOutPoint adds a wire.OutPoint to the list of entries to be included in the
|
||||
// GCS filter when it's built.
|
||||
func (b *GCSBuilder) AddOutPoint(outpoint wire.OutPoint) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
return b.AddEntry(OutPointToFilterEntry(outpoint))
|
||||
}
|
||||
|
||||
// AddHash adds a chainhash.Hash to the list of entries to be included in the
|
||||
// GCS filter when it's built.
|
||||
func (b *GCSBuilder) AddHash(hash *chainhash.Hash) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
return b.AddEntry(hash.CloneBytes())
|
||||
}
|
||||
|
||||
// AddScript adds all the data pushed in the script serialized as the passed
|
||||
// []byte to the list of entries to be included in the GCS filter when it's
|
||||
// built. T
|
||||
func (b *GCSBuilder) AddScript(script []byte) *GCSBuilder {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return b
|
||||
}
|
||||
|
||||
data, err := txscript.PushedData(script)
|
||||
if err != nil {
|
||||
b.err = err
|
||||
return b
|
||||
}
|
||||
return b.AddEntries(data)
|
||||
}
|
||||
|
||||
// Build returns a function which builds a GCS filter with the given parameters
|
||||
// and data.
|
||||
func (b *GCSBuilder) Build() (*gcs.Filter, error) {
|
||||
// Do nothing if the builder's already errored out.
|
||||
if b.err != nil {
|
||||
return nil, b.err
|
||||
}
|
||||
|
||||
return gcs.BuildGCSFilter(b.p, b.key, b.data)
|
||||
}
|
||||
|
||||
// WithKeyPN creates a GCSBuilder with specified key and the passed
|
||||
// probability and estimated filter size.
|
||||
func WithKeyPN(key [gcs.KeySize]byte, p uint8, n uint32) *GCSBuilder {
|
||||
b := GCSBuilder{}
|
||||
return b.SetKey(key).SetP(p).Preallocate(n)
|
||||
}
|
||||
|
||||
// WithKeyP creates a GCSBuilder with specified key and the passed
|
||||
// probability. Estimated filter size is set to zero, which means more
|
||||
// reallocations are done when building the filter.
|
||||
func WithKeyP(key [gcs.KeySize]byte, p uint8) *GCSBuilder {
|
||||
return WithKeyPN(key, p, 0)
|
||||
}
|
||||
|
||||
// WithKey creates a GCSBuilder with specified key. Probability is set to
|
||||
// 20 (2^-20 collision probability). Estimated filter size is set to zero, which
|
||||
// means more reallocations are done when building the filter.
|
||||
func WithKey(key [gcs.KeySize]byte) *GCSBuilder {
|
||||
return WithKeyPN(key, DefaultP, 0)
|
||||
}
|
||||
|
||||
// WithKeyHashPN creates a GCSBuilder with key derived from the specified
|
||||
// chainhash.Hash and the passed probability and estimated filter size.
|
||||
func WithKeyHashPN(keyHash *chainhash.Hash, p uint8, n uint32) *GCSBuilder {
|
||||
return WithKeyPN(DeriveKey(keyHash), p, n)
|
||||
}
|
||||
|
||||
// WithKeyHashP creates a GCSBuilder with key derived from the specified
|
||||
// chainhash.Hash and the passed probability. Estimated filter size is set to
|
||||
// zero, which means more reallocations are done when building the filter.
|
||||
func WithKeyHashP(keyHash *chainhash.Hash, p uint8) *GCSBuilder {
|
||||
return WithKeyHashPN(keyHash, p, 0)
|
||||
}
|
||||
|
||||
// WithKeyHash creates a GCSBuilder with key derived from the specified
|
||||
// chainhash.Hash. Probability is set to 20 (2^-20 collision probability).
|
||||
// Estimated filter size is set to zero, which means more reallocations are
|
||||
// done when building the filter.
|
||||
func WithKeyHash(keyHash *chainhash.Hash) *GCSBuilder {
|
||||
return WithKeyHashPN(keyHash, DefaultP, 0)
|
||||
}
|
||||
|
||||
// WithRandomKeyPN creates a GCSBuilder with a cryptographically random
|
||||
// key and the passed probability and estimated filter size.
|
||||
func WithRandomKeyPN(p uint8, n uint32) *GCSBuilder {
|
||||
key, err := RandomKey()
|
||||
if err != nil {
|
||||
b := GCSBuilder{err: err}
|
||||
return &b
|
||||
}
|
||||
return WithKeyPN(key, p, n)
|
||||
}
|
||||
|
||||
// WithRandomKeyP creates a GCSBuilder with a cryptographically random
|
||||
// key and the passed probability. Estimated filter size is set to zero, which
|
||||
// means more reallocations are done when building the filter.
|
||||
func WithRandomKeyP(p uint8) *GCSBuilder {
|
||||
return WithRandomKeyPN(p, 0)
|
||||
}
|
||||
|
||||
// WithRandomKey creates a GCSBuilder with a cryptographically random
|
||||
// key. Probability is set to 20 (2^-20 collision probability). Estimated
|
||||
// filter size is set to zero, which means more reallocations are done when
|
||||
// building the filter.
|
||||
func WithRandomKey() *GCSBuilder {
|
||||
return WithRandomKeyPN(DefaultP, 0)
|
||||
}
|
||||
105
gcs/builder/builder_test.go
Normal file
105
gcs/builder/builder_test.go
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
// Copyright (c) 2017 The btcsuite developers
|
||||
// Copyright (c) 2017 The Lightning Network Developers
|
||||
// Use of this source code is governed by an ISC
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
package builder_test
|
||||
|
||||
import (
|
||||
"encoding/hex"
|
||||
"testing"
|
||||
|
||||
"github.com/btcsuite/btcd/chaincfg/chainhash"
|
||||
"github.com/btcsuite/btcutil/gcs/builder"
|
||||
)
|
||||
|
||||
var (
|
||||
// No need to allocate an err variable in every test
|
||||
err error
|
||||
|
||||
// List of values for building a filter
|
||||
contents = [][]byte{
|
||||
[]byte("Alex"),
|
||||
[]byte("Bob"),
|
||||
[]byte("Charlie"),
|
||||
[]byte("Dick"),
|
||||
[]byte("Ed"),
|
||||
[]byte("Frank"),
|
||||
[]byte("George"),
|
||||
[]byte("Harry"),
|
||||
[]byte("Ilya"),
|
||||
[]byte("John"),
|
||||
[]byte("Kevin"),
|
||||
[]byte("Larry"),
|
||||
[]byte("Michael"),
|
||||
[]byte("Nate"),
|
||||
[]byte("Owen"),
|
||||
[]byte("Paul"),
|
||||
[]byte("Quentin"),
|
||||
}
|
||||
|
||||
// List of values for querying a filter using MatchAny()
|
||||
contents2 = [][]byte{
|
||||
[]byte("Alice"),
|
||||
[]byte("Betty"),
|
||||
[]byte("Charmaine"),
|
||||
[]byte("Donna"),
|
||||
[]byte("Edith"),
|
||||
[]byte("Faina"),
|
||||
[]byte("Georgia"),
|
||||
[]byte("Hannah"),
|
||||
[]byte("Ilsbeth"),
|
||||
[]byte("Jennifer"),
|
||||
[]byte("Kayla"),
|
||||
[]byte("Lena"),
|
||||
[]byte("Michelle"),
|
||||
[]byte("Natalie"),
|
||||
[]byte("Ophelia"),
|
||||
[]byte("Peggy"),
|
||||
[]byte("Queenie"),
|
||||
}
|
||||
)
|
||||
|
||||
// TestUseBlockHash tests using a block hash as a filter key.
|
||||
func TestUseBlockHash(t *testing.T) {
|
||||
// Block hash #448710, pretty high difficulty.
|
||||
hash, err := chainhash.NewHashFromStr("000000000000000000496d7ff9bd2c96154a8d64260e8b3b411e625712abb14c")
|
||||
if err != nil {
|
||||
t.Fatalf("Hash from string failed: %s", err.Error())
|
||||
}
|
||||
|
||||
// Create a Builder with a key hash and check that the key is derived
|
||||
// correctly.
|
||||
b := builder.WithKeyHash(hash)
|
||||
key, err := b.Key()
|
||||
if err != nil {
|
||||
t.Fatalf("Builder instantiation with key hash failed: %s",
|
||||
err.Error())
|
||||
}
|
||||
testKey := [16]byte{0x4c, 0xb1, 0xab, 0x12, 0x57, 0x62, 0x1e, 0x41,
|
||||
0x3b, 0x8b, 0x0e, 0x26, 0x64, 0x8d, 0x4a, 0x15}
|
||||
if key != testKey {
|
||||
t.Fatalf("Key not derived correctly from key hash:\n%s\n%s",
|
||||
hex.EncodeToString(key[:]),
|
||||
hex.EncodeToString(testKey[:]))
|
||||
}
|
||||
|
||||
// Build a filter and test matches.
|
||||
b.AddEntries(contents)
|
||||
f, err := b.Build()
|
||||
match, err := f.Match(key, []byte("Nate"))
|
||||
if err != nil {
|
||||
t.Fatalf("Filter match failed: %s", err)
|
||||
}
|
||||
if !match {
|
||||
t.Fatal("Filter didn't match when it should have!")
|
||||
}
|
||||
match, err = f.Match(key, []byte("weks"))
|
||||
if err != nil {
|
||||
t.Fatalf("Filter match failed: %s", err)
|
||||
}
|
||||
if match {
|
||||
t.Logf("False positive match, should be 1 in 2**%d!",
|
||||
builder.DefaultP)
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue