blockcf2

README

blockcf2

Package blockcf2 provides functions to build version 2 block filters. Unlike the gcs package, which is a general implementation of golomb coded sets, this package is tailored for specific filter creation for Decred blocks.

License

Package blockcf2 is licensed under the copyfree ISC License.

Documentation

Overview

Package blockcf2 provides functions for building committed filters for blocks using Golomb-coded sets in a way that is useful for light clients such as SPV wallets.

Committed filters are a reversal of how bloom filters are typically used by a light client: a consensus-validating full node commits to filters for every block with a predetermined collision probability and light clients match against the filters locally rather than uploading personal data to other nodes. If a filter matches, the light client should fetch the entire block and further inspect it for relevant transactions.

Index

• Constants
• func Key(merkleRoot *chainhash.Hash) [gcs.KeySize]byte
• func Regular(block *wire.MsgBlock, prevScripts PrevScripter) (*gcs.FilterV2, error)
• type Entries
  • func (e *Entries) AddRegularPkScript(script []byte)
  • func (e *Entries) AddStakePkScript(script []byte)
• type PrevScriptError
  • func (e PrevScriptError) Error() string
• type PrevScripter

Constants

const (
	// B is bits parameter for constructing GCS filters and results in the
	// tunable parameter that is essentially used as the bin size in the
	// underlying Golomb coding having a value of 2^B.
	B = 19

	// M is the inverse of the target false positive rate for constructing GCS
	// filters.  This is the optimal value of M to minimize the size of the
	// filter for B = 19.
	M = 784931
)

Functions

func Key

func Key(merkleRoot *chainhash.Hash) [gcs.KeySize]byte

Key creates a block filter key by truncating the Merkle root of a block to the key size.

func Regular

func Regular(block *wire.MsgBlock, prevScripts PrevScripter) (*gcs.FilterV2, error)

Regular builds a GCS filter from a block and the previous output scripts it references as inputs. The filter will be keyed by the merkle root of the block.

The following section describes the items that will be added to the filter, however, there are a few special cases that apply:

• Scripts that are not version 0, empty, or otherwise provably unspendable are NOT included
• Output scripts for transactions in the stake tree do NOT include the initial stake opcode tag (OP_SS*)
• This allows users of the filter to only match against a normal P2PKH or P2SH script, instead of many extra matches for each tag

Considering the aforementioned exceptions, the filter will contain the following items for transactions in the regular tree:

• Previous output scripts referenced by the transaction inputs with the exception of the coinbase
• Output scripts in the transaction outputs

In addition, also considering the aforementioned exceptions, the filter will contain the following items for transactions in the stake tree: - For ticket purchases:

• Previous output scripts referenced by the transaction inputs
• Commitment output scripts (converted from the commitment hash and type)
• Change output scripts except those that are provably unspendable

- For votes:

• Subsidy generation output scripts
• Output scripts that pay the original ticket commitments

- For revocations:

• Output scripts that pay the original ticket commitments

Types

type Entries

type Entries [][]byte

Entries describes all of the filter entries used to create a GCS filter and provides methods for appending data structures found in blocks.

func (*Entries) AddRegularPkScript

func (e *Entries) AddRegularPkScript(script []byte)

AddRegularPkScript adds the regular tx output script to an entries slice. Empty scripts are ignored.

func (*Entries) AddStakePkScript

func (e *Entries) AddStakePkScript(script []byte)

AddStakePkScript adds the output script without the stake opcode tag to an entries slice. Empty scripts are ignored.

type PrevScriptError

type PrevScriptError struct {
	PrevOut wire.OutPoint
	TxHash  chainhash.Hash
	TxInIdx int
}

PrevScriptError represents an error when looking up a previous output script. The caller can use type assertions to determine the specific details of the previous outpoint and the transaction input that references it.

func (PrevScriptError) Error

func (e PrevScriptError) Error() string

Error returns the previous script error as a human-readable string and satisfies the error interface.

type PrevScripter

type PrevScripter interface {
	PrevScript(*wire.OutPoint) (uint16, []byte, bool)
}

PrevScripter defines an interface that provides access to scripts and their associated version keyed by an outpoint. It is used within this package as a generic means to provide the scripts referenced by all of the inputs to transactions within a block that are needed to construct a filter. The boolean return indicates whether or not the script and version for the provided outpoint was found.