spv

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 14, 2021 License: ISC Imports: 9 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNoTxInputs returns if an envelope is attempted to be created from a transaction that has no inputs.
	ErrNoTxInputs = errors.New("provided tx has no inputs to build envelope from")

	// ErrPaymentNotVerified returns if a transaction in the tree provided was missed during verification.
	ErrPaymentNotVerified = errors.New("a tx was missed during validation")

	// ErrTipTxConfirmed returns if the tip transaction is already confirmed.
	ErrTipTxConfirmed = errors.New("tip transaction must be unconfirmed")

	// ErrNoConfirmedTransaction returns if a path from tip to beginning/anchor contains no confirmed transaction.
	ErrNoConfirmedTransaction = errors.New("not confirmed/anchored tx(s) provided")

	// ErrTxIDMismatch returns if they key value pair of a transactions input has a mismatch in txID.
	ErrTxIDMismatch = errors.New("input and proof ID mismatch")

	// ErrNotAllInputsSupplied returns if an unconfirmed transaction in envelope contains inputs which are not
	// present in the parent envelope.
	ErrNotAllInputsSupplied = errors.New("a tx input missing in parent envelope")

	// ErrNoTxInputsToVerify returns if a transaction has no inputs.
	ErrNoTxInputsToVerify = errors.New("a tx has no inputs to verify")

	// ErrNilInitialPayment returns if a transaction has no inputs.
	ErrNilInitialPayment = errors.New("initial payment cannot be nil")

	// ErrInputRefsOutOfBoundsOutput returns if a transaction has no inputs.
	ErrInputRefsOutOfBoundsOutput = errors.New("tx input index into output is out of bounds")

	// ErrNoFeeQuoteSupplied is returned when VerifyFees is enabled but no bt.FeeQuote has been supplied.
	ErrNoFeeQuoteSupplied = errors.New("no bt.FeeQuote supplied for fee validation, supply the bt.FeeQuote using VerifyFees opt")

	// ErrFeePaidNotEnough returned when not enough fees have been paid.
	ErrFeePaidNotEnough = errors.New("not enough fees paid")

	// ErrCannotCalculateFeePaid returned when fee check is enabled but the tx has no parents.
	ErrCannotCalculateFeePaid = errors.New("no parents supplied in envelope which means we cannot valdiate " +
		"fees, either ensure parents are supplied or remove fee check")

	// ErrInvalidProof is returned if the merkle proof validation fails.
	ErrInvalidProof = errors.New("invalid merkle proof, payment invalid")

	// ErrMissingOutput is returned when checking fees if an output in a parent tx is missing.
	ErrMissingOutput = errors.New("expected output used in payment tx missing")

	// ErrProofOrInputMissing returns if a path from tip to beginning/anchor is broken.
	ErrProofOrInputMissing = errors.New("break in the ancestry missing either a parent transaction or a proof")

	// ErrTriedToParseZeroBytes returns when we attempt to parse a slice of bytes of zero length which should be a mapi response.
	ErrTriedToParseZeroBytes = errors.New("there are no mapi response bytes to parse")

	// ErrUnsupporredVersion returns if another version of the binary format is being used - since we cannot guarantee we know how to parse it.
	ErrUnsupporredVersion = errors.New("we only support version 1 of the Ancestor Binary format")

	// ErrInvalidMerkleFlags returns if a merkle proof being verified uses something other than the one currently supported.
	ErrInvalidMerkleFlags = errors.New("invalid flags used in merkle proof")

	// ErrMissingTxidInProof returns if there's a missing txid in the proof.
	ErrMissingTxidInProof = errors.New("missing txid in proof")

	// ErrMissingRootInProof returns if there's a missing root in the proof.
	ErrMissingRootInProof = errors.New("missing root in proof")

	// ErrInvalidNodes returns if there is a * on the left hand side within the node array.
	ErrInvalidNodes = errors.New("invalid nodes")
)

Functions

func VerifyAncestors added in v0.1.8

func VerifyAncestors(ancestry *Ancestry, mpv MerkleProofVerifier, opts *verifyOptions) error

VerifyAncestors will run through the map of Ancestors and check each input of each transaction to verify it. Only if there is no Proof attached.

func VerifyAncestryBinary added in v0.1.8

func VerifyAncestryBinary(binaryData []byte, mpv MerkleProofVerifier, opts ...VerifyOpt) (bool, error)

VerifyAncestryBinary will verify a slice of bytes which is a binary spv envelope.

Types

type Ancestor added in v0.1.8

type Ancestor struct {
	Tx            *bt.Tx
	Proof         []byte
	MapiResponses []*bc.MapiCallback
}

Ancestor is an internal struct for validating transactions with their ancestors.

type AncestorJSON added in v0.1.8

type AncestorJSON struct {
	RawTx         string             `json:"hex,omitempty"`
	Proof         *bc.MerkleProof    `json:"proof,omitempty"`
	MapiResponses []*bc.MapiCallback `json:"mapiResponses,omitempty"`
}

AncestorJSON is one of the serial objects within the overall list of ancestors.

type Ancestry added in v0.1.8

type Ancestry struct {
	PaymentTx *bt.Tx
	Ancestors map[[32]byte]*Ancestor
}

Ancestry is a payment and its ancestors.

func NewAncestryFromBytes added in v0.1.8

func NewAncestryFromBytes(b []byte) (*Ancestry, error)

NewAncestryFromBytes creates a new struct from the bytes of a txContext.

type AncestryJSON added in v0.1.8

type AncestryJSON struct {
	PaymentTx string         `json:"paymentTx,omitempty"`
	Depth     uint64         `json:"depth,omitempty"`
	Ancestors []AncestorJSON `json:"ancestors,omitempty"`
}

AncestryJSON is a spec at https://tsc.bitcoinassociation.net/standards/spv-envelope/ eventually.

func NewAncestoryJSONFromBytes added in v0.1.8

func NewAncestoryJSONFromBytes(b []byte) (*AncestryJSON, error)

NewAncestoryJSONFromBytes is a way to create the JSON format for Ancestry from the binary format.

func (*AncestryJSON) Bytes added in v0.1.8

func (j *AncestryJSON) Bytes() ([]byte, error)

Bytes takes an AncestryJSON and returns the serialised bytes.

type Envelope

type Envelope struct {
	TxID          string               `json:"txid,omitempty"`
	RawTx         string               `json:"rawTx,omitempty"`
	Proof         *bc.MerkleProof      `json:"proof,omitempty"`
	MapiResponses []bc.MapiCallback    `json:"mapiResponses,omitempty"`
	Parents       map[string]*Envelope `json:"parents,omitempty"`
}

Envelope is a struct which contains all information needed for a transaction to be verified.

func (*Envelope) Bytes added in v0.1.8

func (e *Envelope) Bytes() ([]byte, error)

Bytes takes an spvEnvelope struct and returns the serialised binary format.

func (*Envelope) HasParents added in v0.1.6

func (e *Envelope) HasParents() bool

HasParents returns true if this envelope has immediate parents.

func (*Envelope) IsAnchored

func (e *Envelope) IsAnchored() bool

IsAnchored returns true if the envelope is the anchor tx.

func (*Envelope) ParentTx added in v0.1.8

func (e *Envelope) ParentTx(txID string) (*bt.Tx, error)

ParentTx will return a parent if found and convert the rawTx to a bt.TX, otherwise a ErrNotAllInputsSupplied error is returned.

type EnvelopeCreator

type EnvelopeCreator interface {
	CreateEnvelope(context.Context, *bt.Tx) (*Envelope, error)
}

An EnvelopeCreator is an interface used to build the spv.Envelope data type for Simple Payment Verification (SPV).

The implementation of an spv.TxStore and spv.MerkleProofStore which is supplied will depend on the client you are using.

func NewEnvelopeCreator

func NewEnvelopeCreator(txc TxStore, mpc MerkleProofStore) (EnvelopeCreator, error)

NewEnvelopeCreator creates a new spv.Creator with the provided spv.TxStore and tx.MerkleProofStore. If either implementation is not provided, the setup will return an error.

type MerkleProofStore

type MerkleProofStore interface {
	MerkleProof(ctx context.Context, txID string) (*bc.MerkleProof, error)
}

MerkleProofStore interfaces a Merkle Proof store.

type MerkleProofValidation added in v0.1.8

type MerkleProofValidation struct {
	TxID         string
	Valid        bool
	IsLastInTree bool
}

MerkleProofValidation is a wrapper for the response of a validation operation.

type MerkleProofVerifier

type MerkleProofVerifier interface {
	VerifyMerkleProof(context.Context, []byte) (*MerkleProofValidation, error)
	VerifyMerkleProofJSON(context.Context, *bc.MerkleProof) (bool, bool, error)
}

MerkleProofVerifier interfaces the verification of Merkle Proofs.

func NewMerkleProofVerifier

func NewMerkleProofVerifier(bhc bc.BlockHeaderChain) (MerkleProofVerifier, error)

NewMerkleProofVerifier creates a new spv.MerkleProofVerifer with the bc.BlockHeaderChain provided. If no BlockHeaderChain implementation is provided, the setup will return an error.

type PaymentVerifier

type PaymentVerifier interface {
	VerifyPayment(context.Context, *Envelope, ...VerifyOpt) (*bt.Tx, error)
	MerkleProofVerifier
}

A PaymentVerifier is an interface used to complete Simple Payment Verification (SPV) in conjunction with a Merkle Proof.

The implementation of bc.BlockHeaderChain which is supplied will depend on the client you are using, some may return a HeaderJSON response others may return the blockhash.

func NewPaymentVerifier

func NewPaymentVerifier(bhc bc.BlockHeaderChain, opts ...VerifyOpt) (PaymentVerifier, error)

NewPaymentVerifier creates a new spv.PaymentVerifer with the bc.BlockHeaderChain provided. If no BlockHeaderChain implementation is provided, the setup will return an error.

opts control the global behaviour of the verifier and all options are enabled by default, they are: - envelope verification (proofs checked etc) - fees checked, ensuring the root tx covers enough fees - script verification which checks the script is correct (not currently implemented).

type TxStore

type TxStore interface {
	Tx(ctx context.Context, txID string) (*bt.Tx, error)
}

TxStore interfaces the a tx store.

type VerifyOpt added in v0.1.6

type VerifyOpt func(opts *verifyOptions)

VerifyOpt defines a functional option that is used to modify behaviour of the payment verifier.

func NoVerifyFees added in v0.1.6

func NoVerifyFees() VerifyOpt

NoVerifyFees will switch off transaction fee verification and rely on mAPI / node verification when the transaction is broadcast.

func NoVerifyProofs added in v0.1.6

func NoVerifyProofs() VerifyOpt

NoVerifyProofs will switch off envelope proof verification and rely on mAPI/node verification when the tx is broadcast.

func NoVerifySPV added in v0.1.6

func NoVerifySPV() VerifyOpt

NoVerifySPV will turn off any spv validation for merkle proofs and script validation. This is a helper method that is equivalent to NoVerifyProofs && NoVerifyScripts.

func NoVerifyScript added in v0.1.6

func NoVerifyScript() VerifyOpt

NoVerifyScript will switch off script verification and rely on mAPI / node verification when the tx is broadcast.

func VerifyFees added in v0.1.6

func VerifyFees(fees *bt.FeeQuote) VerifyOpt

VerifyFees will make the verifier check the transaction fees of the supplied transaction are enough based on the feeQuote provided.

It is recommended to provide a fresh fee quote when calling the VerifyPayment method rather than loading fees when calling NewPaymentVerifier as fees can go out of date over the lifetime of the application and you may be supplying different feeQuotes to different consumers.

func VerifyProofs added in v0.1.6

func VerifyProofs() VerifyOpt

VerifyProofs will make the verifier validate the envelope merkle proofs for each parent transaction.

func VerifySPV added in v0.1.6

func VerifySPV() VerifyOpt

VerifySPV will turn on spv validation for merkle proofs and script validation. This is a helper method that is equivalent to VerifyProofs && VerifyScripts.

func VerifyScript added in v0.1.6

func VerifyScript() VerifyOpt

VerifyScript will ensure the scripts provided in the transaction are valid.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL