Version: v1.1.1 Latest Latest

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

Go to latest
Published: Dec 23, 2020 License: AGPL-3.0 Imports: 21 Imported by: 0



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



This section is empty.


View Source
var (
	//ChainTxUtxoNum maximum utxo quantity in a tx
	ChainTxUtxoNum = 5
	//ChainTxMergeGas chain tx gas
	ChainTxMergeGas = uint64(6000000)
View Source
var (
	// ErrRejected means the network rejected a tx (as a double-spend)
	ErrRejected = errors.New("transaction rejected")
	// ErrMissingRawTx means missing transaction
	ErrMissingRawTx = errors.New("missing raw tx")
	// ErrBadInstructionCount means too many signing instructions compare with inputs
	ErrBadInstructionCount = errors.New("too many signing instructions in template")
	// ErrOrphanTx means submit transaction is orphan
	ErrOrphanTx = errors.New("finalize can't find transaction input utxo")
	// ErrExtTxFee means transaction fee exceed max limit
	ErrExtTxFee = errors.New("transaction fee exceed max limit")
	// ErrNoGasInput means transaction has no gas input
	ErrNoGasInput = errors.New("transaction has no gas input")
View Source
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")
View Source
var (
	//ErrBadRefData means invalid reference data
	ErrBadRefData = errors.New("transaction reference data does not match previous template's reference data")
	//ErrBadTxInputIdx means unsigned tx input
	ErrBadTxInputIdx = errors.New("unsigned tx missing input")
	//ErrBadWitnessComponent means invalid witness component
	ErrBadWitnessComponent = errors.New("invalid witness component")
	//ErrBadAmount means invalid asset amount
	ErrBadAmount = errors.New("bad asset amount")
	//ErrBlankCheck means unsafe transaction
	ErrBlankCheck = errors.New("unsafe transaction: leaves assets free to control")
	//ErrAction means errors occurred in actions
	ErrAction = errors.New("errors occurred in one or more actions")
	//ErrMissingFields means missing required fields
	ErrMissingFields = errors.New("required field is missing")
	//ErrBadContractArgType means invalid contract argument type
	ErrBadContractArgType = errors.New("invalid contract argument type")


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

ErrEmptyProgram is a type of error


func AddContractArgs added in v1.0.5

func AddContractArgs(sigInst *SigningInstruction, arguments []ContractArgument) error

AddContractArgs add contract arguments

func CalculateTxFee added in v1.0.7

func CalculateTxFee(tx *types.Tx) (fee uint64)

CalculateTxFee calculate transaction fee

func FinalizeTx

func FinalizeTx(ctx context.Context, c *protocol.Chain, tx *types.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, auth string, signFn SignFunc) error

Sign will try to sign all the witness

func SignProgress added in v0.4.1

func SignProgress(txTemplate *Template) bool

SignProgress check is all the sign requirement are satisfy


type Action

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

Action is a interface

func DecodeControlAddressAction added in v0.3.0

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

DecodeControlAddressAction convert input data to action struct

func DecodeControlProgramAction

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

DecodeControlProgramAction convert input data to action struct

func DecodeRetireAction

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

DecodeRetireAction convert input data to action struct

type BoolArgument added in v1.0.7

type BoolArgument struct {
	Value bool `json:"value"`

BoolArgument is the boolean argument for run contract

type ContractArgument added in v1.0.5

type ContractArgument struct {
	Type    string          `json:"type"`
	RawData json.RawMessage `json:"raw_data"`

ContractArgument for smart contract

type DataArgument added in v1.0.5

type DataArgument struct {
	Value chainjson.HexBytes `json:"value"`

DataArgument is the other argument for run contract

type DataWitness added in v0.3.0

type DataWitness chainjson.HexBytes

DataWitness used sign transaction

func (DataWitness) MarshalJSON added in v0.3.0

func (dw DataWitness) MarshalJSON() ([]byte, error)

MarshalJSON marshal DataWitness

type EstimateTxGasInfo added in v1.0.9

type EstimateTxGasInfo struct {
	TotalNeu    int64 `json:"total_neu"`
	FlexibleNeu int64 `json:"flexible_neu"`
	StorageNeu  int64 `json:"storage_neu"`
	VMNeu       int64 `json:"vm_neu"`
	ChainTxNeu  int64 `json:"chain_tx_neu"`

EstimateTxGasInfo estimate transaction consumed gas

func EstimateChainTxGas added in v1.0.10

func EstimateChainTxGas(templates []Template) (*EstimateTxGasInfo, error)

func EstimateTxGas added in v0.4.7

func EstimateTxGas(template Template) (*EstimateTxGasInfo, error)

EstimateTxGas estimate consumed neu for transaction

type IntegerArgument added in v1.0.7

type IntegerArgument struct {
	Value int64 `json:"value"`

IntegerArgument is the integer argument for run contract

type RawTxSigArgument added in v1.0.5

type RawTxSigArgument struct {
	RootXPub chainkd.XPub         `json:"xpub"`
	Path     []chainjson.HexBytes `json:"derivation_path"`

RawTxSigArgument is signature-related argument for run contract

type RawTxSigWitness added in v0.3.0

type RawTxSigWitness struct {
	Quorum int                  `json:"quorum"`
	Keys   []keyID              `json:"keys"`
	Sigs   []chainjson.HexBytes `json:"signatures"`

RawTxSigWitness is like SignatureWitness but doesn't involve signature programs.

func (RawTxSigWitness) MarshalJSON added in v0.3.0

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

MarshalJSON convert struct to json

type Receiver

type Receiver struct {
	ControlProgram chainjson.HexBytes `json:"control_program,omitempty"`
	Address        string             `json:"address,omitempty"`

Receiver encapsulates information about where to send assets.

type SignFunc

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

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

type SignatureWitness added in v0.3.0

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"`

SignatureWitness is a sign struct

func (SignatureWitness) MarshalJSON added in v0.3.0

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

MarshalJSON convert struct to json

type SigningInstruction

type SigningInstruction struct {
	Position          uint32             `json:"position"`
	WitnessComponents []witnessComponent `json:"witness_components,omitempty"`

SigningInstruction gives directions for signing inputs in a TxTemplate.

func (*SigningInstruction) AddRawWitnessKeys added in v0.3.0

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

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

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

UnmarshalJSON unmarshal SigningInstruction

type StrArgument added in v1.0.7

type StrArgument struct {
	Value string `json:"value"`

StrArgument is the string argument for run contract

type Template

type Template struct {
	Transaction         *types.Tx             `json:"raw_transaction"`
	SigningInstructions []*SigningInstruction `json:"signing_instructions"`
	Fee                 uint64                `json:"fee"`
	// 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 *types.TxData, actions []Action, maxTime time.Time, timeRange uint64) (*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

Hash return sign hash

type TemplateBuilder

type TemplateBuilder struct {
	// contains filtered or unexported fields

TemplateBuilder is struct of building transactions

func NewBuilder

func NewBuilder(maxTime time.Time) *TemplateBuilder

NewBuilder return new TemplateBuilder instance

func (*TemplateBuilder) AddInput

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

AddInput add inputs of transactions

func (*TemplateBuilder) AddOutput

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

AddOutput add outputs of transactions

func (*TemplateBuilder) Build

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

Build build transactions with template

func (*TemplateBuilder) InputCount added in v1.0.7

func (b *TemplateBuilder) InputCount() int

InputCount return number of input in the template builder

func (*TemplateBuilder) MaxTime

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

MaxTime return maxTime

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)

RestrictMaxTime set maxTime

func (*TemplateBuilder) RestrictMinTime

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

RestrictMinTime set minTime

func (*TemplateBuilder) Rollback added in v1.0.7

func (b *TemplateBuilder) Rollback()

Rollback action for handle fail build

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL