txbuilder

Documentation

Index

• Variables
• type Input
• type Issuance
  • func (iss *Issuance) AssetID() [32]byte
• type Output
• type Retirement
• type SignFunc
• type Template
  • func NewTemplate(maxTime time.Time, tags []byte) *Template
  • func (tpl *Template) AddInput(quorum int, keyHashes [][]byte, path [][]byte, pubkeys []ed25519.PublicKey, ...) *Input
  • func (tpl *Template) AddIssuance(version int, blockchainID []byte, assetTag []byte, quorum int, ...) *Issuance
  • func (tpl *Template) AddOutput(quorum int, pubkeys []ed25519.PublicKey, amount int64, assetID bc.Hash, ...) *Output
  • func (tpl *Template) AddRetirement(amount int64, assetID bc.Hash, refData []byte) *Retirement
  • func (tpl *Template) Commit() error
  • func (tpl *Template) Dematerialize()
  • func (tpl *Template) Materialize() (txid bc.Hash, prog []byte, err error)
  • func (tpl *Template) OnBuild(buildFn func() error)
  • func (tpl *Template) OnRollback(rollbackFn func())
  • func (tpl *Template) RestrictMaxTime(t time.Time)
  • func (tpl *Template) RestrictMinTime(t time.Time)
  • func (tpl *Template) Rollback()
  • func (t *Template) SetOutputV1()
  • func (tpl *Template) SetTransactionTags(tags []byte)
  • func (tpl *Template) Sign(ctx context.Context, signFn SignFunc) error
  • func (tpl *Template) Tx() (tx *bc.Tx, err error)

Variables

var (
	// ErrNoAnchor happens when the top-level contract stack contains no
	// values suitable for use as an anchor for finalize. This can
	// happen when invoking Tx on a Template that includes no Issuances
	// or Inputs.
	ErrNoAnchor = errors.New("no anchor for finalize")

	// ErrNonSigCheck happens when an unexpected item is left on the
	// top-level contract stack after finalize. This should be
	// impossible.
	ErrNonSigCheck = errors.New("non-signature-check item on stack after finalize")

	// ErrNumSigs happens when the number of signatures in an Input or
	// Issuance is not zero and not equal to the number of pubkeys.
	ErrNumSigs = errors.New("wrong number of signatures for pubkeys")

	// ErrInsufficientValue happens when an Output or Retirement
	// requires more units of a certain flavor than exist in values on
	// the top-level contract stack.
	ErrInsufficientValue = errors.New("cannot find enough units of desired flavor on the stack")

	// ErrRunlimit happens when a template has too many entries,
	// too many keys, or too much refdata.
	ErrRunlimit = errors.New("transaction exceeds maximum runlimit")
)

Types

type Input

type Input struct {
	Quorum        int                 `json:"quorum"`
	KeyHashes     []i10rjson.HexBytes `json:"key_hashes"`
	Path          []i10rjson.HexBytes `json:"derivation_path"`
	Pubkeys       []ed25519.PublicKey `json:"pubkeys"`
	Amount        int64               `json:"amount"`
	AssetID       bc.Hash             `json:"asset_id"`
	Anchor        i10rjson.HexBytes   `json:"anchor"`
	Sigs          []i10rjson.HexBytes `json:"signatures"`
	InputRefdata  i10rjson.HexBytes   `json:"reference_data"`
	Index         uint64              `json:"index"`
	OutputIndex   *int                `json:"output_index,omitempty"` // for "spend from output" - will be blank for "normal" inputs
	OutputVersion int                 `json:"output_version"`
}

Input contains information needed to add an input to a transaction. It is added to a template with AddInput.

type Issuance

type Issuance struct {
	Version      int                 `json:"contract_version"`
	BlockchainID i10rjson.HexBytes   `json:"blockchain_id"`
	Quorum       int                 `json:"quorum"`
	KeyHashes    []i10rjson.HexBytes `json:"key_hashes"`
	Path         []i10rjson.HexBytes `json:"derivation_path"`
	Pubkeys      []ed25519.PublicKey `json:"pubkeys"`
	Amount       int64               `json:"amount"`
	AssetTag     i10rjson.HexBytes   `json:"asset_tag"` // TODO(bobg): name this something that won't be confused with the mutable asset tags we already have
	Sigs         []i10rjson.HexBytes `json:"signatures"`
	Refdata      i10rjson.HexBytes   `json:"reference_data"`
	Index        uint64              `json:"index"`
	Nonce        i10rjson.HexBytes   `json:"nonce"`
	// contains filtered or unexported fields
}

Issuance contains information needed to add an issuance to a transaction. It is added to a template with AddIssuance.

func (*Issuance) AssetID

func (iss *Issuance) AssetID() [32]byte

AssetID computes the asset ID of the issuance.

type Output

type Output struct {
	Quorum    int                 `json:"quorum"`
	Pubkeys   []ed25519.PublicKey `json:"pubkeys"`
	Amount    int64               `json:"amount"`
	AssetID   bc.Hash             `json:"asset_id"`
	Refdata   i10rjson.HexBytes   `json:"reference_data"`
	TokenTags i10rjson.HexBytes   `json:"token_tags"`
	Index     uint64              `json:"index"`
	// contains filtered or unexported fields
}

Output contains information needed to add an output to a transaction. It is added to a template with AddOutput.

type Retirement

type Retirement struct {
	Amount  int64             `json:"amount"`
	AssetID bc.Hash           `json:"asset_id"`
	Refdata i10rjson.HexBytes `json:"reference_data"`
	Index   uint64            `json:"index"`
}

Retirement contains information needed to add a retirement to a transaction. It is added to a template with AddRetirement.

type SignFunc

type SignFunc func(ctx context.Context, msg []byte, keyID []byte, path [][]byte) ([]byte, error)

SignFunc is the type of a callback that can generate a signature for a given message and a given keyID and derivation path. If the function does not recognize the keyID, it should return (nil, nil), not an error.

type Template

type Template struct {
	Issuances   []*Issuance       `json:"issuances"`
	Inputs      []*Input          `json:"inputs"`
	Outputs     []*Output         `json:"outputs"`
	Retirements []*Retirement     `json:"retirements"`
	TxTags      i10rjson.HexBytes `json:"transaction_tags"`
	MinTimeMS   uint64            `json:"min_time_ms"`
	MaxTimeMS   uint64            `json:"max_time_ms"`
	// contains filtered or unexported fields
}

Template contains the ingredients for a transaction: Issuances, Inputs, Outputs, and Retirements, plus transaction tags and min- and maxtimes. A Template can be created directly or with a call to Build. Elements can be added to a template directly or with calls to AddIssuance, AddInput, AddOutput, AddRetirement, SetReferenceData, RestrictMinTime, and RestrictMaxTime. Once these elements have been added, any needed signatures are added with Sign. The completed transaction can be extracted with Tx.

func NewTemplate

func NewTemplate(maxTime time.Time, tags []byte) *Template

func (*Template) AddInput

func (tpl *Template) AddInput(quorum int, keyHashes [][]byte, path [][]byte, pubkeys []ed25519.PublicKey, amount int64, assetID bc.Hash, anchor, inputRefdata []byte, version int) *Input

AddInput adds an Input to the template.

func (*Template) AddIssuance

func (tpl *Template) AddIssuance(version int, blockchainID []byte, assetTag []byte, quorum int, keyHashes [][]byte, path [][]byte, pubkeys []ed25519.PublicKey, amount int64, refData, nonce []byte) *Issuance

AddIssuance adds an Issuance to the template.

func (*Template) AddOutput

func (tpl *Template) AddOutput(quorum int, pubkeys []ed25519.PublicKey, amount int64, assetID bc.Hash, refData, tags []byte) *Output

AddOutput adds an Output to the template.

func (*Template) AddRetirement

func (tpl *Template) AddRetirement(amount int64, assetID bc.Hash, refData []byte) *Retirement

AddRetirement adds a Retirement to the template.

func (*Template) Commit

func (tpl *Template) Commit() error

Commit runs any pending template callbacks.

func (*Template) Dematerialize

func (tpl *Template) Dematerialize()

Dematerialize clears any previous materialization. This is helpful when a change to the template has been made, and it needs to be recognized.

func (*Template) Materialize

func (tpl *Template) Materialize() (txid bc.Hash, prog []byte, err error)

Materialize returns the transaction's program and ID. If the transaction ID cannot be computed because the transaction is not finalized or because of an error, the last return value will be a non-nil error.

func (*Template) OnBuild

func (tpl *Template) OnBuild(buildFn func() error)

OnBuild registers a function that will be run after a successful call to Build.

func (*Template) OnRollback

func (tpl *Template) 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 that were made on UTXOs in an input 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 (*Template) RestrictMaxTime

func (tpl *Template) RestrictMaxTime(t time.Time)

RestrictMaxTime sets the template's max time to the given value if it's earlier than the maxtime already present.

func (*Template) RestrictMinTime

func (tpl *Template) RestrictMinTime(t time.Time)

RestrictMinTime sets the template's min time to the given value if it's later than the mintime already present.

func (*Template) Rollback

func (tpl *Template) Rollback()

func (*Template) SetOutputV1

func (t *Template) SetOutputV1()

SetOutputV1 causes Template.Tx to produce old-style outputs, which don't log token tags. The default is for version 2 outputs, which do.

func (*Template) SetTransactionTags

func (tpl *Template) SetTransactionTags(tags []byte)

SetTransactionTags sets the template's transaction-level tags to the given value.

func (*Template) Sign

func (tpl *Template) Sign(ctx context.Context, signFn SignFunc) error

Sign invokes a callback function to add signatures to Inputs and Issuances in the template. The callback adds as many as it can, up to the number needed for each Input or Issuance. Multiple calls to Sign might be necessary to marshal enough signatures to authorize a transaction, each with a callback invoking a different signing HSM responsible for a different subset of keys.

func (*Template) Tx

func (tpl *Template) Tx() (tx *bc.Tx, err error)

Tx produces a bc.Tx from the transaction currently described by the template. This involves rendering the transaction as txvm code, running it, and extracting various values from the result.