simulation

Documentation

Index

• Constants
• type AppKVPairs
• type AppsInitialStates
• type EvalFailureError
• type ExecTraceConfig
• type InvalidRequestError
• type OpcodeTraceUnit
• type Request
• type ResourceTracker
  • func (a *ResourceTracker) HasResources() bool
• type ResourcesInitialStates
• type Result
  • func (r Result) ReturnScratchChange() bool
  • func (r Result) ReturnStackChange() bool
  • func (r Result) ReturnStateChange() bool
  • func (r Result) ReturnTrace() bool
• type ResultEvalOverrides
  • func (eo ResultEvalOverrides) AllowMoreLogging(allow bool) ResultEvalOverrides
  • func (eo ResultEvalOverrides) LogicEvalConstants() logic.EvalConstants
• type ScratchChange
• type Simulator
  • func MakeSimulator(ledger *data.Ledger, developerAPI bool) *Simulator
  • func (s Simulator) Simulate(simulateRequest Request) (Result, error)
• type SimulatorError
  • func (s SimulatorError) Error() string
  • func (s SimulatorError) Unwrap() error
• type SingleAppInitialStates
• type StateOperation
• type TransactionTrace
• type TxnGroupResult
• type TxnPath
• type TxnResult

Constants

const LogBytesLimit = uint64(65536)

LogBytesLimit hardcode limit of how much bytes one can log per transaction during simulation (with AllowMoreLogging)

const MaxExtraOpcodeBudget = uint64(20000 * 16)

MaxExtraOpcodeBudget hardcode limit of how much extra budget one can add to one transaction group (which is group-size * logic-sig-budget)

const ResultLatestVersion = uint64(2)

ResultLatestVersion is the latest version of the Result struct

Types

type AppKVPairs

type AppKVPairs map[string]basics.TealValue

AppKVPairs constructs a KV pair between state key and state value

type AppsInitialStates

type AppsInitialStates map[basics.AppIndex]SingleAppInitialStates

AppsInitialStates maintains a map from basics.AppIndex to SingleAppInitialStates

type EvalFailureError

type EvalFailureError struct {
	SimulatorError
}

EvalFailureError represents an error that occurred during evaluation.

type ExecTraceConfig

type ExecTraceConfig struct {
	Enable  bool `codec:"enable"`
	Stack   bool `codec:"stack-change"`
	Scratch bool `codec:"scratch-change"`
	State   bool `codec:"state-change"`
	// contains filtered or unexported fields
}

ExecTraceConfig gathers all execution trace related configs for simulation result

type InvalidRequestError

type InvalidRequestError struct {
	SimulatorError
}

InvalidRequestError occurs when an invalid transaction group was submitted to the simulator.

type OpcodeTraceUnit

type OpcodeTraceUnit struct {
	// The PC of the opcode being evaluated
	PC uint64

	// SpawnedInners contains the indexes of traces for inner transactions spawned by this opcode,
	// if any. These indexes refer to the InnerTraces array of the TransactionTrace object containing
	// this OpcodeTraceUnit.
	SpawnedInners []int

	// what has been added to stack
	StackAdded []basics.TealValue

	// deleted element number from stack
	StackPopCount uint64

	// ScratchSlotChanges stands for write operations into scratch slots
	ScratchSlotChanges []ScratchChange

	// StateChanges stands for the creation/reading/writing/deletion operations to app's state
	StateChanges []StateOperation
}

OpcodeTraceUnit contains the trace effects of a single opcode evaluation.

type Request

type Request struct {
	Round                 basics.Round
	TxnGroups             [][]transactions.SignedTxn
	AllowEmptySignatures  bool
	AllowMoreLogging      bool
	AllowUnnamedResources bool
	ExtraOpcodeBudget     uint64
	TraceConfig           ExecTraceConfig
	FixSigners            bool
}

Request packs simulation related txn-group(s), and configurations that are overlapping the ones in real transactions.

type ResourceTracker

type ResourceTracker struct {
	Accounts    map[basics.Address]struct{}
	MaxAccounts int

	Assets    map[basics.AssetIndex]struct{}
	MaxAssets int

	Apps    map[basics.AppIndex]struct{}
	MaxApps int

	// The map value is the size of the box loaded from the ledger prior to any writes. This is used
	// to track the box read budget.
	Boxes           map[logic.BoxRef]uint64
	MaxBoxes        int
	NumEmptyBoxRefs int

	MaxTotalRefs int

	AssetHoldings             map[ledgercore.AccountAsset]struct{}
	AppLocals                 map[ledgercore.AccountApp]struct{}
	MaxCrossProductReferences int
	// contains filtered or unexported fields
}

ResourceTracker calculates the additional resources that a transaction or group could use, and it tracks any referenced unnamed resources that fit within those limits.

func (*ResourceTracker) HasResources

func (a *ResourceTracker) HasResources() bool

HasResources returns true if the tracker has any resources.

type ResourcesInitialStates

type ResourcesInitialStates struct {
	// AllAppsInitialStates gathers all initial states of apps that were touched (but not created) during simulation
	AllAppsInitialStates AppsInitialStates
	// CreatedApp gathers all created applications by appID, blocking initial app states in these apps being recorded
	CreatedApp util.Set[basics.AppIndex]
}

ResourcesInitialStates gathers all initial states of resources that were accessed during simulation

type Result

type Result struct {
	Version       uint64
	LastRound     basics.Round
	TxnGroups     []TxnGroupResult // this is a list so that supporting multiple in the future is not breaking
	EvalOverrides ResultEvalOverrides
	Block         *ledgercore.ValidatedBlock
	TraceConfig   ExecTraceConfig
	InitialStates *ResourcesInitialStates
}

Result contains the result from a call to Simulator.Simulate

func (Result) ReturnScratchChange

func (r Result) ReturnScratchChange() bool

ReturnScratchChange tells if the simulation runs with scratch-change enabled.

func (Result) ReturnStackChange

func (r Result) ReturnStackChange() bool

ReturnStackChange reads from Result object and decides if simulation return stack changes.

func (Result) ReturnStateChange

func (r Result) ReturnStateChange() bool

ReturnStateChange tells if the simulation runs with state-change enabled.

func (Result) ReturnTrace

func (r Result) ReturnTrace() bool

ReturnTrace reads from Result object and decides if simulation returns PC. It only reads Enable for any option combination must contain Enable field, or it won't make sense. The other invalid options would be eliminated in validateSimulateRequest early.

type ResultEvalOverrides

type ResultEvalOverrides struct {
	AllowEmptySignatures  bool
	AllowUnnamedResources bool
	MaxLogCalls           *uint64
	MaxLogSize            *uint64
	ExtraOpcodeBudget     uint64
	FixSigners            bool
}

ResultEvalOverrides contains the limits and parameters during a call to Simulator.Simulate

func (ResultEvalOverrides) AllowMoreLogging

func (eo ResultEvalOverrides) AllowMoreLogging(allow bool) ResultEvalOverrides

AllowMoreLogging method modify the log limits from lift option: - if lift log limits, then overload result from local Config - otherwise, set `LogLimits` field to be nil

func (ResultEvalOverrides) LogicEvalConstants

func (eo ResultEvalOverrides) LogicEvalConstants() logic.EvalConstants

LogicEvalConstants method infers the logic.EvalConstants from Result.EvalOverrides (*ResultEvalOverrides) and generate appropriate parameters to override during simulation runtime.

type ScratchChange

type ScratchChange struct {
	// Slot stands for the scratch slot id get written to
	Slot uint64

	// NewValue is the stack value written to scratch slot
	NewValue basics.TealValue
}

ScratchChange represents a write operation into a scratch slot

type Simulator

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

Simulator is a transaction group simulator for the block evaluator.

func MakeSimulator

func MakeSimulator(ledger *data.Ledger, developerAPI bool) *Simulator

MakeSimulator creates a new simulator from a ledger.

func (Simulator) Simulate

func (s Simulator) Simulate(simulateRequest Request) (Result, error)

Simulate simulates a transaction group using the simulator. Will error if the transaction group is not well-formed.

type SimulatorError

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

SimulatorError is the base error type for all simulator errors.

func (SimulatorError) Error

func (s SimulatorError) Error() string

func (SimulatorError) Unwrap

func (s SimulatorError) Unwrap() error

type SingleAppInitialStates

type SingleAppInitialStates struct {
	AppBoxes     AppKVPairs
	CreatedBoxes util.Set[string]

	AppGlobals     AppKVPairs
	CreatedGlobals util.Set[string]

	AppLocals     map[basics.Address]AppKVPairs
	CreatedLocals map[basics.Address]util.Set[string]
}

SingleAppInitialStates gathers all relevant application on-chain states, including - Application Box states - Application Global states - Application Local states (which is tied to basics.Address)

type StateOperation

type StateOperation struct {
	// AppStateOp is one of logic.AppStateOpEnum, standing for either write or delete.
	AppStateOp logic.AppStateOpEnum

	// AppState is one of logic.AppStateEnum, standing for one of global/local/box.
	AppState logic.AppStateEnum

	// AppID is the current app's ID.
	AppID basics.AppIndex

	// Key is the app state kv-pair's key, directly casting byte slice to string.
	Key string

	// NewValue is the value write to the app's state.
	// NOTE: if the current app state operation is del, then this value is basics.TealValue{}.
	NewValue basics.TealValue

	// Account is the account associated to the local state an app writes to.
	// NOTE: if the current app state is not local, then this value is basics.Address{}.
	Account basics.Address
}

StateOperation represents an operation into an app local/global/box state

type TransactionTrace

type TransactionTrace struct {
	// ApprovalProgramTrace stands for a slice of OpcodeTraceUnit over application call on approval program
	ApprovalProgramTrace []OpcodeTraceUnit
	// ApprovalProgramHash stands for the hash digest of approval program bytecode executed during simulation
	ApprovalProgramHash crypto.Digest

	// ClearStateProgramTrace stands for a slice of OpcodeTraceUnit over application call on clear-state program
	ClearStateProgramTrace []OpcodeTraceUnit
	// ClearStateProgramHash stands for the hash digest of clear state program bytecode executed during simulation
	ClearStateProgramHash crypto.Digest
	// ClearStateRollback, if true, indicates that the clear state program failed and any persistent state changes
	// it produced should be reverted once the program exits.
	ClearStateRollback bool
	// ClearStateRollbackError contains the error message explaining why the clear state program failed. This
	// field will only be populated if ClearStateRollback is true and the failure was due to an execution error.
	ClearStateRollbackError string

	// LogicSigTrace contains the trace for a logicsig evaluation, if the transaction is approved by a logicsig.
	LogicSigTrace []OpcodeTraceUnit
	// LogicSigHash stands for the hash digest of logic sig bytecode executed during simulation
	LogicSigHash crypto.Digest

	// InnerTraces contains the traces for inner transactions, if this transaction spawned any. This
	// object only contains traces for inners that are immediate children of this transaction.
	// Grandchild traces will be present inside the TransactionTrace of their parent.
	InnerTraces []TransactionTrace
	// contains filtered or unexported fields
}

TransactionTrace contains the trace effects of a single transaction evaluation (including its inners)

type TxnGroupResult

type TxnGroupResult struct {
	Txns []TxnResult
	// FailureMessage will be the error message for the first transaction in the group which errors.
	// If the group succeeds, this will be empty.
	FailureMessage string
	// FailedAt is the path to the txn that failed inside of this group
	FailedAt TxnPath
	// AppBudgetAdded is the total opcode budget for this group
	AppBudgetAdded uint64
	// AppBudgetConsumed is the total opcode cost used for this group
	AppBudgetConsumed uint64

	// UnnamedResourcesAccessed will be present if AllowUnnamedResources is true. In that case, it
	// will be populated with the unnamed resources accessed by this transaction group from
	// transactions which can benefit from shared resources (v9 or higher programs).
	//
	// Any unnamed resources accessed from transactions which cannot benefit from shared resources
	// will be placed in the corresponding `UnnamedResourcesAccessed` field in the appropriate
	// TxnResult struct.
	UnnamedResourcesAccessed *ResourceTracker
}

TxnGroupResult contains the simulation result for a single transaction group

type TxnPath

type TxnPath []uint64

TxnPath is a "transaction path": e.g. [0, 0, 1] means the second inner txn of the first inner txn of the first txn. You can use this transaction path to find the txn data in the `TxnResults` list.

type TxnResult

type TxnResult struct {
	Txn                    transactions.SignedTxnWithAD
	AppBudgetConsumed      uint64
	LogicSigBudgetConsumed uint64
	Trace                  *TransactionTrace

	// UnnamedResourcesAccessed is present if all of the following are true:
	//  * AllowUnnamedResources is true
	//  * The transaction cannot use shared resources (pre-v9 program)
	//  * The transaction accessed unnamed resources.
	//
	// In that case, it will be populated with the unnamed resources accessed by this transaction.
	UnnamedResourcesAccessed *ResourceTracker

	// If the signer needed to be changed, this will be the address of the required signer
	// This will only be present if FixSigners is true in the EvalOverrides
	FixedSigner basics.Address
}

TxnResult contains the simulation result for a single transaction