Documentation
¶
Index ¶
- Variables
- func EventsOf[T DecodedEvent](result *ExecutionResult) []T
- type Action
- type AmountConstraint
- type BalanceCheckpoint
- type BalancePatch
- type BalanceSource
- type BuildEnv
- type BuiltStep
- type Call
- type CalldataPatch
- type CheckpointDeclaration
- type DecodedEvent
- type DynamicCall
- type EthereumClient
- type EventExpectation
- type EventMetadata
- type ExecutionError
- type ExecutionPlan
- type ExecutionResult
- type ExecutionStage
- type ExpectationResult
- type FieldMismatch
- type Flow
- type FlowOption
- type FlowStep
- type MatchContext
- type MatchDecision
- type MatchResult
- type PlanKind
- type PlannedCall
- type Runner
- type SkipReason
- type StepID
- type StepResult
- type ValidationStatus
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidDynamicCall = errors.New("invalid dynamic call") ErrInvalidCheckpointGraph = errors.New("invalid checkpoint graph") ErrInvalidCalldataPatch = errors.New("invalid calldata patch") ErrDynamicPlaceholderNotZero = errors.New("dynamic calldata placeholder is not zero") )
var ( // ErrInvalidExecutionPlan is returned when validation receives no usable plan. ErrInvalidExecutionPlan = errors.New("invalid execution plan") // ErrInvalidExecutionReceipt is returned when a receipt is nil, incomplete, or unsuccessful. ErrInvalidExecutionReceipt = errors.New("invalid execution receipt") // ErrInvalidEventExpectation is returned for nil or unnamed expectations. ErrInvalidEventExpectation = errors.New("invalid event expectation") // ErrMalformedExecutionEvent is returned when a candidate log cannot be decoded. ErrMalformedExecutionEvent = errors.New("malformed execution event") // ErrExpectedEventNotFound is returned when no candidate satisfies an expectation. ErrExpectedEventNotFound = errors.New("expected execution event not found") // ErrInvalidMatchResult is returned when an expectation or constraint violates the matching contract. ErrInvalidMatchResult = errors.New("invalid match result") )
var ( ErrEmptyFlow = errors.New("empty flow") ErrMissingChain = errors.New("flow chain is required") ErrInvalidAccount = errors.New("flow account is zero") )
var ErrExecutionAccountMismatch = errors.New("flow account does not match transaction signer")
ErrExecutionAccountMismatch is returned when a Flow is built for an account other than the transaction signer.
var ErrInvalidAmountConstraint = errors.New("invalid amount constraint")
ErrInvalidAmountConstraint is returned when a constraint is nil or was configured without a required bound.
var ErrPlanKindMismatch = errors.New("execution plan kind is incompatible with accessor")
Functions ¶
func EventsOf ¶
func EventsOf[T DecodedEvent](result *ExecutionResult) []T
EventsOf returns every validated event assignable to T in execution order.
Types ¶
type AmountConstraint ¶
type AmountConstraint interface {
Describe() string
Match(actual *big.Int, ctx MatchContext) (MatchResult, error)
}
AmountConstraint validates a decoded event amount. Implementations must return MatchSkip rather than panic when actual is nil.
func AtLeast ¶
func AtLeast(minimum *big.Int) AmountConstraint
AtLeast requires an amount to be greater than or equal to minimum.
func AtMost ¶
func AtMost(maximum *big.Int) AmountConstraint
AtMost requires an amount to be less than or equal to maximum.
func Exact ¶
func Exact(expected *big.Int) AmountConstraint
Exact requires an amount to equal expected.
func Positive ¶
func Positive() AmountConstraint
Positive requires an amount to be greater than zero.
type BalanceCheckpoint ¶ added in v0.4.0
BalanceCheckpoint is the materialized contract checkpoint value.
type BalancePatch ¶ added in v0.4.0
type BalancePatch struct {
Token common.Address
CheckpointID [32]byte
Offset uint32
BPS uint16
Source BalanceSource
}
BalancePatch is the materialized contract calldata patch value.
type BalanceSource ¶ added in v0.4.0
type BalanceSource uint8
BalanceSource mirrors the dynamic account contract's runtime balance source.
const ( BalanceSourceCurrentBalance BalanceSource = iota BalanceSourceCheckpointDelta )
type BuildEnv ¶
type BuildEnv struct {
Account common.Address
Chain config.Chain
Conn EthereumClient
}
BuildEnv contains shared context passed to every step during Flow.Build.
type BuiltStep ¶
type BuiltStep struct {
ID StepID
Name string
Calls []PlannedCall
Expectations []EventExpectation
}
BuiltStep contains the calls and semantic expectations produced from the same resolved Flow step data. Flow.Build owns ID assignment; step implementations must set Name and leave ID empty.
type CalldataPatch ¶ added in v0.4.0
CalldataPatch replaces one protocol-owned ABI uint256 word with a runtime amount immediately before execution.
type CheckpointDeclaration ¶ added in v0.4.0
type CheckpointDeclaration struct {
Ref amount.CheckpointRef
}
CheckpointDeclaration attaches a named token-balance checkpoint immediately before a planned call.
type DecodedEvent ¶
type DecodedEvent interface {
EventMetadata() EventMetadata
}
DecodedEvent is implemented by protocol-specific event result types.
type DynamicCall ¶ added in v0.4.0
type DynamicCall struct {
Target common.Address
Value *big.Int
Data []byte
CheckpointsBefore []BalanceCheckpoint
Patches []BalancePatch
ExpectsCallback bool
}
DynamicCall is the protocol-neutral wire model for executeBatchDynamic.
type EthereumClient ¶
type EthereumClient = contract.EthereumClient
EthereumClient is the client interface needed by steps that build calls from contract state.
type EventExpectation ¶
type EventExpectation interface {
ExpectationName() string
IsCandidate(log *types.Log) bool
Decode(log *types.Log) (DecodedEvent, error)
Match(event DecodedEvent, ctx MatchContext) (MatchResult, error)
}
EventExpectation decodes and validates one expected protocol event.
IsCandidate must only identify logs by stable source data such as emitter and topic. Decode errors and Match errors are hard failures. Ordinary decoded field mismatches must return MatchSkip with mismatch details and a nil error. Within one BuiltStep, expectations must be declared in the same order as the corresponding events are emitted on-chain; the validator scans forward and never reuses an earlier or consumed log.
type EventMetadata ¶
EventMetadata identifies a decoded protocol event without depending on its protocol-specific fields.
type ExecutionError ¶
type ExecutionError struct {
Stage ExecutionStage
StepID StepID
Expectation string
LogIndex *uint
Err error
}
ExecutionError wraps an execution or validation failure with stage and partial-result location metadata.
func (*ExecutionError) Error ¶
func (e *ExecutionError) Error() string
func (*ExecutionError) Unwrap ¶
func (e *ExecutionError) Unwrap() error
Unwrap preserves sentinel and typed errors for errors.Is and errors.As.
type ExecutionPlan ¶
type ExecutionPlan struct {
// contains filtered or unexported fields
}
ExecutionPlan is the ordered, executor-neutral result of building a Flow. Its contents are immutable to callers and exposed through defensive-copy accessors. Account is the semantic caller identity for steps that derive owner, sender, or onBehalfOf values from BuildEnv.Account.
func (*ExecutionPlan) Account ¶
func (p *ExecutionPlan) Account() common.Address
Account returns the protocol-visible caller identity.
func (*ExecutionPlan) Calls
deprecated
func (p *ExecutionPlan) Calls() []Call
Calls returns static plan calls in step order.
Deprecated: use StaticCalls, which reports an error for dynamic plans.
func (*ExecutionPlan) DynamicCalls ¶ added in v0.4.0
func (p *ExecutionPlan) DynamicCalls() ([]DynamicCall, error)
DynamicCalls returns materialized calls only when dynamic execution is required. Static calls within a dynamic plan are represented with empty checkpoint and patch metadata.
func (*ExecutionPlan) Kind ¶ added in v0.4.0
func (p *ExecutionPlan) Kind() PlanKind
Kind returns the execution capability required by the plan.
func (*ExecutionPlan) StaticCalls ¶ added in v0.4.0
func (p *ExecutionPlan) StaticCalls() ([]Call, error)
StaticCalls returns calls only when the plan has no runtime metadata.
func (*ExecutionPlan) Steps ¶
func (p *ExecutionPlan) Steps() []BuiltStep
Steps returns a defensive copy of the built steps.
type ExecutionResult ¶
type ExecutionResult struct {
Receipt *types.Receipt
Steps []StepResult
}
ExecutionResult preserves the mined receipt and all available step-level semantic validation results, including partial results on failure.
func ValidateExecution ¶
func ValidateExecution(plan *ExecutionPlan, receipt *types.Receipt) (*ExecutionResult, error)
ValidateExecution validates a mined receipt against plan expectations.
Expectations are processed in step and declaration order. Each expectation scans forward from the last accepted log. Accepted logs and all earlier logs are unavailable to later expectations, which enforces on-chain emission order and consume-once semantics structurally. Because unvalidated steps cannot consume logs, a semantic plan may only place them after all validated steps.
type ExecutionStage ¶
type ExecutionStage string
ExecutionStage identifies where execution or semantic validation failed.
const ( ExecutionStageTransaction ExecutionStage = "transaction" ExecutionStageReceipt ExecutionStage = "receipt" ExecutionStageDecode ExecutionStage = "decode" ExecutionStageMatch ExecutionStage = "match" ExecutionStageValidation ExecutionStage = "validation" )
type ExpectationResult ¶
type ExpectationResult struct {
Name string
Status ValidationStatus
SkipReason SkipReason
CandidateCount int
Mismatches []FieldMismatch
Event DecodedEvent
}
ExpectationResult reports matching details for one expected event.
type FieldMismatch ¶
FieldMismatch explains one expected field that did not match its actual decoded value.
type Flow ¶
type Flow struct {
// contains filtered or unexported fields
}
Flow is an ordered composition of DeFi steps.
func NewFlow ¶
func NewFlow(account common.Address, opts ...FlowOption) *Flow
NewFlow creates an empty flow for account.
func (*Flow) Build ¶
func (f *Flow) Build(ctx context.Context, conn EthereumClient) (*ExecutionPlan, error)
Build compiles all Flow steps into an ordered execution plan.
type FlowOption ¶
type FlowOption func(*Flow)
FlowOption configures a Flow.
func WithChain ¶
func WithChain(chain config.Chain) FlowOption
WithChain configures the chain context used when building flow steps.
type FlowStep ¶
FlowStep builds one named step from shared Flow context.
func ActionStep ¶
ActionStep adapts an existing Action into a FlowStep.
func CheckpointBefore ¶ added in v0.4.0
func CheckpointBefore(step FlowStep, checkpoints ...amount.CheckpointRef) FlowStep
CheckpointBefore declares token-balance checkpoints immediately before the wrapped step's single call. The references can later be consumed through amount.CheckpointDelta.
type MatchContext ¶
type MatchContext struct {
StepID StepID
}
MatchContext provides execution-plan context to expectation and constraint matching. It intentionally has no cross-step value resolution in Phase 1.
type MatchDecision ¶
type MatchDecision uint8
MatchDecision describes whether a decoded candidate satisfies an expectation. The zero value is MatchSkip so matching fails closed.
const ( // MatchSkip rejects the current candidate without aborting receipt scanning. MatchSkip MatchDecision = iota // MatchAccepted accepts and consumes the current candidate log. MatchAccepted )
type MatchResult ¶
type MatchResult struct {
Decision MatchDecision
Mismatches []FieldMismatch
}
MatchResult is shared by event expectations and value constraints. At the constraint level MatchSkip means the value is unsatisfied; the enclosing event expectation decides whether receipt scanning continues.
func MatchAmountConstraints ¶
func MatchAmountConstraints(field string, actual *big.Int, ctx MatchContext, constraints ...AmountConstraint) (MatchResult, error)
MatchAmountConstraints evaluates every amount constraint and aggregates all ordinary mismatches. A constraint error remains a hard failure and aborts evaluation immediately.
type PlanKind ¶ added in v0.4.0
type PlanKind uint8
PlanKind identifies the execution capability required by a built plan.
type PlannedCall ¶ added in v0.4.0
type PlannedCall struct {
Call Call
CheckpointsBefore []CheckpointDeclaration
Patches []CalldataPatch
ExpectsCallback bool
}
PlannedCall combines one neutral call with optional dynamic execution metadata. Protocol packages own all patch offsets they place here.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes Flows through the configured DefiSimplify7702Account delegation. The built plan determines the account entrypoint.
func NewRunner ¶
func NewRunner(conn EthereumClient, opts *bind.TransactOpts, chain config.Chain) *Runner
NewRunner creates a Flow runner for a chain and transaction signer.
func (*Runner) Execute ¶
Execute builds and executes flow, then validates the mined receipt against expectations generated by the same Flow steps.
Failures before a receipt exists return a nil result. Once a receipt exists, transaction and semantic validation failures return both the partial result and an error so callers retain the transaction hash and decoded progress. A plan with expectations after an unvalidated step is rejected before sending.
type SkipReason ¶
type SkipReason string
SkipReason explains why validation was not attempted.
const ( SkipExecutionFailed SkipReason = "execution_failed" SkipInvalidReceipt SkipReason = "invalid_receipt" SkipPriorValidationFailed SkipReason = "prior_validation_failed" )
type StepResult ¶
type StepResult struct {
ID StepID
Name string
Status ValidationStatus
SkipReason SkipReason
Expectations []ExpectationResult
}
StepResult reports semantic validation for one built step.
type ValidationStatus ¶
type ValidationStatus string
ValidationStatus describes the semantic validation state of a step or expectation.
const ( ValidationValidated ValidationStatus = "validated" ValidationUnvalidated ValidationStatus = "unvalidated" ValidationFailed ValidationStatus = "failed" ValidationSkipped ValidationStatus = "skipped" )
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package amount defines protocol-neutral transaction amount intent.
|
Package amount defines protocol-neutral transaction amount intent. |
|
Package assets provides protocol-neutral, chain-scoped asset catalogs.
|
Package assets provides protocol-neutral, chain-scoped asset catalogs. |
|
base
Package base provides reviewed token references for common assets on Base.
|
Package base provides reviewed token references for common assets on Base. |
|
bind
|
|
|
client
|
|
|
account/defisimplify7702
Package defisimplify7702 exposes imported Defi Simplify contract deployment identities, ABIs, parity vectors, and delegated-account execution.
|
Package defisimplify7702 exposes imported Defi Simplify contract deployment identities, ABIs, parity vectors, and delegated-account execution. |
|
account/eip7702
Package eip7702 manages EIP-7702 account delegation lifecycle.
|
Package eip7702 manages EIP-7702 account delegation lifecycle. |
|
contract/mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
cmd
|
|
|
update-aave-manifest
command
|
|
|
internal
|
|
|
aaveassetmanifest
Package aaveassetmanifest adapts official Aave Address Book market exports into the provider-neutral asset manifest model.
|
Package aaveassetmanifest adapts official Aave Address Book market exports into the provider-neutral asset manifest model. |
|
catalogcodegen
Package catalogcodegen renders reviewed manifest entries as chain-package named references.
|
Package catalogcodegen renders reviewed manifest entries as chain-package named references. |
|
catalogloader
Package catalogloader turns checked-in neutral manifests into public asset catalogs for thin chain-specific packages.
|
Package catalogloader turns checked-in neutral manifests into public asset catalogs for thin chain-specific packages. |
|
Package strategy provides opinionated Flow compositions for common DeFi workflows.
|
Package strategy provides opinionated Flow compositions for common DeFi workflows. |
|
Package token defines protocol-neutral ERC20 token identity and metadata.
|
Package token defines protocol-neutral ERC20 token identity and metadata. |
|
Package weth provides FlowSteps and typed event validation for canonical WETH deposit and withdrawal operations.
|
Package weth provides FlowSteps and typed event validation for canonical WETH deposit and withdrawal operations. |