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, s Submitter, tx *legacy.Tx) error
• func MissingFieldsError(name ...string) error
• func Sign(ctx context.Context, tpl *Template, xpubs []chainkd.XPub, signFn SignFunc) error
• type Action
  • func DecodeControlProgramAction(data []byte) (Action, error)
  • func DecodeControlReceiverAction(data []byte) (Action, error)
  • func DecodeRetireAction(data []byte) (Action, error)
  • func DecodeSetTxRefDataAction(data []byte) (Action, error)
• type Receiver
• type RemoteGenerator
  • func (rg *RemoteGenerator) Submit(ctx context.Context, tx *legacy.Tx) error
• type SignFunc
• type SigningInstruction
  • func (si *SigningInstruction) AddWitnessKeys(xpubs []chainkd.XPub, path [][]byte, quorum int)
  • func (si *SigningInstruction) UnmarshalJSON(b []byte) error
• type Submitter
• type Template
  • func Build(ctx context.Context, tx *legacy.TxData, actions []Action, maxTime time.Time) (*Template, error)
  • func (t *Template) Hash(idx uint32) bc.Hash
• type TemplateBuilder
  • func NewBuilder(maxTime time.Time) *TemplateBuilder
  • func (b *TemplateBuilder) AddInput(in *legacy.TxInput, sigInstruction *SigningInstruction) error
  • func (b *TemplateBuilder) AddOutput(o *legacy.TxOutput) error
  • func (b *TemplateBuilder) Build() (*Template, *legacy.TxData, error)
  • func (b *TemplateBuilder) MaxTime() time.Time
  • func (b *TemplateBuilder) OnBuild(buildFn func() error)
  • func (b *TemplateBuilder) OnRollback(rollbackFn func())
  • func (b *TemplateBuilder) RestrictMaxTime(t time.Time)
  • func (b *TemplateBuilder) RestrictMinTime(t time.Time)

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 (
	// ErrNoTxSighashCommitment is returned when no input commits to the
	// complete transaction.
	// 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).
	ErrNoTxSighashCommitment = errors.New("no commitment to tx sighash")

	// ErrNoTxSighashAttempt is returned when there was no attempt made to sign
	// this transaction.
	ErrNoTxSighashAttempt = errors.New("no tx sighash attempted")

	// ErrTxSignatureFailure is returned when there was an attempt to sign this
	// transaction, but it failed.
	ErrTxSignatureFailure = errors.New("tx signature was attempted but failed")
)

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")
	ErrAction              = errors.New("errors occurred in one or more actions")
	ErrMissingFields       = errors.New("required field is missing")
)

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

Functions

func FinalizeTx

func FinalizeTx(ctx context.Context, c *protocol.Chain, s Submitter, tx *legacy.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 MissingFieldsError

func MissingFieldsError(name ...string) error

MissingFieldsError returns a wrapped error ErrMissingFields with a data item containing the given field names.

func Sign

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

Types

type Action

type Action interface {
	Build(context.Context, *TemplateBuilder) error
}

func DecodeControlProgramAction

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

func DecodeControlReceiverAction

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

func DecodeRetireAction

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

func DecodeSetTxRefDataAction

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

type Receiver

type Receiver struct {
	ControlProgram chainjson.HexBytes `json:"control_program"`
	ExpiresAt      time.Time          `json:"expires_at"`
}

Receiver encapsulates information about where to send assets.

type RemoteGenerator

type RemoteGenerator struct {
	Peer *rpc.Client
}

RemoteGenerator implements the Submitter interface and submits the transaction to a remote generator. TODO(jackson): This implementation maybe belongs elsewhere.

func (*RemoteGenerator) Submit

func (rg *RemoteGenerator) Submit(ctx context.Context, tx *legacy.Tx) error

type SignFunc

type SignFunc func(context.Context, chainkd.XPub, [][]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 SigningInstruction

type SigningInstruction struct {
	Position           uint32              `json:"position"`
	SignatureWitnesses []*signatureWitness `json:"witness_components,omitempty"`
}

SigningInstruction gives directions for signing inputs in a TxTemplate.

func (*SigningInstruction) AddWitnessKeys

func (si *SigningInstruction) AddWitnessKeys(xpubs []chainkd.XPub, path [][]byte, quorum int)

AddWitnessKeys adds a signatureWitness with the given quorum and list of keys derived by applying the derivation path to each of the xpubs.

func (*SigningInstruction) UnmarshalJSON

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

type Submitter

type Submitter interface {
	Submit(ctx context.Context, tx *legacy.Tx) error
}

Submitter submits a transaction to the generator so that it may be confirmed in a block.

type Template

type Template struct {
	Transaction         *legacy.Tx            `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"`
}

Template represents a partially- or fully-signed transaction.

func Build

func Build(ctx context.Context, tx *legacy.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 uint32) bc.Hash

type TemplateBuilder

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

func NewBuilder

func NewBuilder(maxTime time.Time) *TemplateBuilder

func (*TemplateBuilder) AddInput

func (b *TemplateBuilder) AddInput(in *legacy.TxInput, sigInstruction *SigningInstruction) error

func (*TemplateBuilder) AddOutput

func (b *TemplateBuilder) AddOutput(o *legacy.TxOutput) error

func (*TemplateBuilder) Build

func (b *TemplateBuilder) Build() (*Template, *legacy.TxData, error)

func (*TemplateBuilder) MaxTime

func (b *TemplateBuilder) MaxTime() time.Time

func (*TemplateBuilder) OnBuild

func (b *TemplateBuilder) OnBuild(buildFn func() error)

OnBuild registers a function that will be run after all actions have been successfully built.

func (*TemplateBuilder) OnRollback

func (b *TemplateBuilder) OnRollback(rollbackFn func())

OnRollback registers a function that can be used to attempt to undo any side effects of building actions. For example, it might cancel any reservations reservations that were made on UTXOs in a spend action. Rollback is a "best-effort" operation and not guaranteed to succeed. Each action's side effects, if any, must be designed with this in mind.

func (*TemplateBuilder) RestrictMaxTime

func (b *TemplateBuilder) RestrictMaxTime(t time.Time)

func (*TemplateBuilder) RestrictMinTime

func (b *TemplateBuilder) RestrictMinTime(t time.Time)