neo-go/pkg/smartcontract/builder.go

package smartcontract

import (
	"github.com/nspcc-dev/neo-go/pkg/io"
	"github.com/nspcc-dev/neo-go/pkg/smartcontract/callflag"
	"github.com/nspcc-dev/neo-go/pkg/util"
	"github.com/nspcc-dev/neo-go/pkg/vm/emit"
	"github.com/nspcc-dev/neo-go/pkg/vm/opcode"
)

// Builder is used to create arbitrary scripts from the set of methods it provides.
// Each method emits some set of opcodes performing an action and (in most cases)
// returning a result. These chunks of code can be composed together to perform
// several actions in the same script (and therefore in the same transaction), but
// the end result (in terms of state changes and/or resulting items) of the script
// totally depends on what it contains and that's the responsibility of the Builder
// user. Builder is mostly used to create transaction scripts (also known as
// "entry scripts"), so the set of methods it exposes is tailored to this model
// of use and any calls emitted don't limit flags in any way (always use
// callflag.All).
//
// When using this API keep in mind that the resulting script can't be larger than
// 64K (transaction.MaxScriptLength) to be used as a transaction entry script and
// it can't have more than 2048 elements on the stack. Technically, this limits
// the number of calls that can be made to a lesser value because invocations use
// the same stack too (the exact number depends on methods and parameters).
//
// This API is not (and won't be) suitable to create complex scripts that use
// returned values as parameters to other calls or perform loops or do any other
// things that can be done in NeoVM. This hardly can be expressed in an API like
// this, so if you need more than that and if you're ready to work with bare
// NeoVM instructions please refer to [emit] and [opcode] packages.
type Builder struct {
	bw *io.BufBinWriter
}

// NewBuilder creates a new Builder instance.
func NewBuilder() *Builder {
	return &Builder{bw: io.NewBufBinWriter()}
}

// InvokeMethod is the most generic contract method invoker, the code it produces
// packs all of the arguments given into an array and calls some method of the
// contract. The correctness of this invocation (number and type of parameters) is
// out of scope of this method, as well as return value, if contract's method returns
// something this value just remains on the execution stack.
func (b *Builder) InvokeMethod(contract util.Uint160, method string, params ...any) {
	emit.AppCall(b.bw.BinWriter, contract, method, callflag.All, params...)
}

// Assert emits an ASSERT opcode that expects a Boolean value to be on the stack,
// checks if it's true and aborts the transaction if it's not.
func (b *Builder) Assert() {
	emit.Opcodes(b.bw.BinWriter, opcode.ASSERT)
}

// InvokeWithAssert emits an invocation of the method (see InvokeMethod) with
// an ASSERT after the invocation. The presumption is that the method called
// returns a Boolean value signalling the success or failure of the operation.
// This pattern is pretty common, NEP-11 or NEP-17 'transfer' methods do exactly
// that as well as NEO's 'vote'. The ASSERT then allow to simplify transaction
// status checking, if action is successful then transaction is successful as
// well, if it went wrong than whole transaction fails (ends with vmstate.FAULT).
func (b *Builder) InvokeWithAssert(contract util.Uint160, method string, params ...any) {
	b.InvokeMethod(contract, method, params...)
	b.Assert()
}

// Len returns the current length of the script. It's useful to perform script
// length checks (wrt transaction.MaxScriptLength limit) while building the
// script.
func (b *Builder) Len() int {
	return b.bw.Len()
}

// Script return current script, you can't use Builder after invoking this method
// unless you Reset it.
func (b *Builder) Script() ([]byte, error) {
	err := b.bw.Err
	return b.bw.Bytes(), err
}

// Reset resets the Builder, allowing to reuse the same script buffer (but
// previous script will be overwritten there).
func (b *Builder) Reset() {
	b.bw.Reset()
}