txbuilder

Documentation

Overview

Package txbuilder builds a Chain Protocol transaction from a list of actions.

Index

• Variables
• func FinalizeTx(ctx context.Context, c *protocol.Chain, tx *bc.Tx) error
• func Sign(ctx context.Context, tpl *Template, xpubs []string, signFn SignFunc) error
• type Action
  • func DecodeControlProgramAction(data []byte) (Action, error)
  • func DecodeSetTxRefDataAction(data []byte) (Action, error)
• type BuildResult
• type KeyID
  • func KeyIDs(xpubs []chainkd.XPub, path [][]byte) []KeyID
• type SignFunc
• type SignatureWitness
  • func (sw SignatureWitness) MarshalJSON() ([]byte, error)
  • func (sw SignatureWitness) Materialize(tpl *Template, index int, args *[][]byte) error
  • func (sw *SignatureWitness) Sign(ctx context.Context, tpl *Template, index int, xpubs []string, signFn SignFunc) error
• type SigningInstruction
  • func (si *SigningInstruction) AddWitnessKeys(keys []KeyID, quorum int)
  • func (si *SigningInstruction) UnmarshalJSON(b []byte) error
• type Template
  • func Build(ctx context.Context, tx *bc.TxData, actions []Action, maxTime time.Time) (*Template, error)
  • func (t *Template) Hash(idx int) bc.Hash
• type WitnessComponent

Variables

var (
	// ErrRejected means the network rejected a tx (as a double-spend)
	ErrRejected = errors.New("transaction rejected")

	ErrMissingRawTx        = errors.New("missing raw tx")
	ErrBadInstructionCount = errors.New("too many signing instructions in template")
)

var (
	ErrBadRefData          = errors.New("transaction reference data does not match previous template's reference data")
	ErrBadTxInputIdx       = errors.New("unsigned tx missing input")
	ErrBadWitnessComponent = errors.New("invalid witness component")
	ErrBadAmount           = errors.New("bad asset amount")
	ErrBlankCheck          = errors.New("unsafe transaction: leaves assets free to control")
)

var ErrEmptyProgram = errors.New("empty signature program")

var ErrNoTxSighashCommitment = errors.New("no commitment to tx sighash")

To permit idempotence of transaction submission, we require at least one input to commit to the complete transaction (what you get when you build a transaction with allow_additional_actions=false).

var Generator *rpc.Client

Functions

func FinalizeTx

func FinalizeTx(ctx context.Context, c *protocol.Chain, tx *bc.Tx) error

FinalizeTx validates a transaction signature template, assembles a fully signed tx, and stores the effects of its changes on the UTXO set.

func Sign

func Sign(ctx context.Context, tpl *Template, xpubs []string, signFn SignFunc) error

Types

type Action

type Action interface {
	// TODO(bobg, jeffomatic): see if there is a way to remove the maxTime
	// parameter from the build call. One possibility would be to treat TTL as
	// a transaction-wide default parameter that gets folded into actions that
	// care about it. This could happen when the build request is being
	// deserialized.
	Build(context.Context, time.Time) (*BuildResult, error)
}

func DecodeControlProgramAction

func DecodeControlProgramAction(data []byte) (Action, error)

func DecodeSetTxRefDataAction

func DecodeSetTxRefDataAction(data []byte) (Action, error)

type BuildResult

type BuildResult struct {
	Inputs              []*bc.TxInput
	Outputs             []*bc.TxOutput
	SigningInstructions []*SigningInstruction
	MinTimeMS           uint64
	ReferenceData       []byte
}

type KeyID

type KeyID struct {
	XPub           string               `json:"xpub"`
	DerivationPath []chainjson.HexBytes `json:"derivation_path"`
}

func KeyIDs

func KeyIDs(xpubs []chainkd.XPub, path [][]byte) []KeyID

KeyIDs produces KeyIDs from a list of xpubs and a derivation path (applied to all the xpubs).

type SignFunc

type SignFunc func(context.Context, string, [][]byte, [32]byte) ([]byte, error)

SignFunc is the function passed into Sign that produces a signature for a given xpub, derivation path, and hash.

type SignatureWitness

type SignatureWitness struct {
	// Quorum is the number of signatures required.
	Quorum int `json:"quorum"`

	// Keys are the identities of the keys to sign with.
	Keys []KeyID `json:"keys"`

	// Program is the predicate part of the signature program, whose hash is what gets
	// signed. If empty, it is computed during Sign from the outputs
	// and the current input of the transaction.
	Program chainjson.HexBytes `json:"program"`

	// Sigs are signatures of Program made from each of the Keys
	// during Sign.
	Sigs []chainjson.HexBytes `json:"signatures"`
}

func (SignatureWitness) MarshalJSON

func (sw SignatureWitness) MarshalJSON() ([]byte, error)

func (SignatureWitness) Materialize

func (sw SignatureWitness) Materialize(tpl *Template, index int, args *[][]byte) error

func (*SignatureWitness) Sign

func (sw *SignatureWitness) Sign(ctx context.Context, tpl *Template, index int, xpubs []string, signFn SignFunc) error

Sign populates sw.Sigs with as many signatures of the predicate in sw.Program as it can from the overlapping set of keys in sw.Keys and xpubs.

If sw.Program is empty, it is populated with an _inferred_ predicate: a program committing to aspects of the current transaction. Specifically, the program commits to:

• the mintime and maxtime of the transaction (if non-zero)
• the outpoint and (if non-empty) reference data of the current input
• the assetID, amount, control program, and (if non-empty) reference data of each output.

type SigningInstruction

type SigningInstruction struct {
	Position int `json:"position"`
	bc.AssetAmount
	WitnessComponents []WitnessComponent `json:"witness_components,omitempty"`
}

SigningInstruction gives directions for signing inputs in a TxTemplate.

func (*SigningInstruction) AddWitnessKeys

func (si *SigningInstruction) AddWitnessKeys(keys []KeyID, quorum int)

func (*SigningInstruction) UnmarshalJSON

func (si *SigningInstruction) UnmarshalJSON(b []byte) error

type Template

type Template struct {
	Transaction         *bc.TxData            `json:"raw_transaction"`
	SigningInstructions []*SigningInstruction `json:"signing_instructions"`

	// Local indicates that all inputs to the transaction are signed
	// exclusively by keys managed by this Core. Whenever accepting
	// a template from an external Core, `Local` should be set to
	// false.
	Local bool `json:"local"`

	// AllowAdditional affects whether Sign commits to the tx sighash or
	// to individual details of the tx so far. When true, signatures
	// commit to tx details, and new details may be added but existing
	// ones cannot be changed. When false, signatures commit to the tx
	// as a whole, and any change to the tx invalidates the signature.
	AllowAdditional bool `json:"allow_additional_actions"`
	// contains filtered or unexported fields
}

Template represents a partially- or fully-signed transaction.

func Build

func Build(ctx context.Context, tx *bc.TxData, actions []Action, maxTime time.Time) (*Template, error)

Build builds or adds on to a transaction. Initially, inputs are left unconsumed, and destinations unsatisfied. Build partners then satisfy and consume inputs and destinations. The final party must ensure that the transaction is balanced before calling finalize.

func (*Template) Hash

func (t *Template) Hash(idx int) bc.Hash

type WitnessComponent

type WitnessComponent interface {
	// Sign is called to add signatures. Actual signing is delegated to
	// a callback function.
	Sign(context.Context, *Template, int, []string, SignFunc) error

	// Materialize is called to turn the component into a vector of
	// arguments for the input witness.
	Materialize(*Template, int, *[][]byte) error
}

WitnessComponent encodes instructions for finalizing a transaction by populating its InputWitness fields. Each WitnessComponent object produces zero or more items for the InputWitness of the txinput it corresponds to.