Documentation
¶
Index ¶
- Constants
- type AppKVPairs
- type AppsInitialStates
- type EvalFailureError
- type ExecTraceConfig
- type InvalidRequestError
- type OpcodeTraceUnit
- type Request
- type ResourceTracker
- type ResourcesInitialStates
- type Result
- type ResultEvalOverrides
- type ScratchChange
- type Simulator
- type SimulatorError
- 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
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppKVPairs ¶
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
}
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 ¶
ReturnScratchChange tells if the simulation runs with scratch-change enabled.
func (Result) ReturnStackChange ¶
ReturnStackChange reads from Result object and decides if simulation return stack changes.
func (Result) ReturnStateChange ¶
ReturnStateChange tells if the simulation runs with state-change enabled.
func (Result) ReturnTrace ¶
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
}
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 ¶
MakeSimulator creates a new simulator from a ledger.
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
}
TxnResult contains the simulation result for a single transaction
Source Files
Directories