defi

README

DeFi Simplify

defi-simplify is a Go SDK for composing static DeFi flows and executing them from the user's own EOA.

The SDK turns protocol-level steps such as ERC20 approval, Aave supply, and Aave borrow into an ordered execution plan. On Base, that plan can be executed atomically through an EIP-7702 delegated EOA backed by Simple7702Account. Downstream protocols continue to observe the user's EOA as the caller and position owner.

The project is intended for Go services, bots, and infrastructure that manage their own keys and transaction submission.

Supported Scope

Area	Current support
Network	Base
Protocols	Aave V3 and ERC20
Composition	Ordered static Flow values with exact amounts
EOA-native execution	EIP-7702 with Simple7702Account from account-abstraction v0.9.0
Results	Typed ERC20, Aave Pool, gateway, and credit-delegation events
Strategies	Static Aave supply/borrow and single-reserve close flows

Static flows require every call target and amount to be known before the transaction is built. Using a swap result or runtime token balance as the input to a later step is not supported yet.

Installation

go get github.com/tn606024/defi-simplify

The module currently requires Go 1.23.5 or later.

Quick Start

The primary SDK path is:

FlowStep -> ExecutionPlan -> Runner -> Executor -> Receipt -> Validator

The example below assumes client is a connected ethclient.Client, opts is a bind.TransactOpts for user, and the EOA has already delegated to the configured Simple7702Account implementation.

supplyAmount := decimal.NewFromInt(100)
borrowAmount := decimal.RequireFromString("0.01")

market, err := aave.BaseV3Market()
if err != nil {
	return err
}
registry, err := aave.NewRegistry(client, market)
if err != nil {
	return err
}
snapshot, err := registry.Load(ctx)
if err != nil {
	return err
}
usdc, err := snapshot.Reserve(base.USDC)
if err != nil {
	return err
}
weth, err := snapshot.Reserve(base.WETH)
if err != nil {
	return err
}

flow := defi.NewFlow(user, defi.WithChain(market.Chain())).
	Add(aave.ApproveSupply(usdc, supplyAmount)).
	Add(aave.Supply(usdc, supplyAmount)).
	Add(aave.Borrow(weth, borrowAmount))

result, err := defi.NewRunner(client, opts, config.Base).
	ExecuteWithResult(ctx, flow, defi.ExecutionAtomicEOA)
if result != nil {
	log.Printf("transaction: %s", result.Receipt.TxHash.Hex())
}
if err != nil {
	return err
}

supplies := defi.EventsOf[*aave.SupplyEvent](result)
borrows := defi.EventsOf[*aave.BorrowEvent](result)

ExecutionAtomicEOA executes the three calls as one transaction. If a call fails, protocol and asset changes made by the batch revert atomically. Gas and nonces are still consumed.

EIP-7702 Delegation

Atomic EOA execution requires the EOA to delegate to the configured Simple7702Account implementation. The SDK provides a lifecycle manager for installing, inspecting, changing, and clearing that delegation.

For a same-signer setup, create the manager with the EOA key and submit the delegation transaction once:

chainID, err := config.Base.ChainID()
if err != nil {
	return err
}

manager, err := eip7702.NewManager(
	client,
	opts,
	privateKey,
	big.NewInt(int64(chainID)),
)
if err != nil {
	return err
}

tx, err := manager.DelegateToSimple7702(ctx, config.Base)
if err != nil {
	return err
}

receipt, err := bind.WaitMined(ctx, client, tx)
if err != nil {
	return err
}
if receipt.Status != types.ReceiptStatusSuccessful {
	return fmt.Errorf("delegation transaction reverted")
}

EIP-7702 delegation is persistent. It remains installed until the EOA changes or clears it, and a later execution revert does not roll it back. Clear it explicitly when it is no longer required:

tx, err := manager.Clear(ctx)

Use State, AssertClean, and AssertDelegatedTo to verify lifecycle state before submitting account-sensitive transactions.

Execution Modes

ExecutionEOA

Executes exactly one call as a normal EOA transaction. The protocol observes the EOA as msg.sender, but multiple calls cannot be combined atomically.

ExecutionAtomicEOA

Executes an ordered static batch through the EOA's delegated Simple7702Account code. Protocols still observe the EOA as the downstream caller. The runner verifies the expected delegation before submission.

For both modes, the Flow account must match the transaction signer when the step derives owner, sender, recipient, or onBehalfOf fields from the account.

Flow Steps

Protocol packages expose public FlowStep builders. They resolve calldata and typed event expectations from the same account, chain, asset, and amount data.

The ERC20 package includes:

• Approve
• Transfer
• TransferFrom
• Permit

The Aave package includes:

• supply: ApproveSupply, Supply, SupplyWithPermit
• position management: Borrow, Repay, RepayAll, Withdraw, WithdrawAll
• credit delegation: ApproveDelegation, DelegationWithSig
• native ETH gateway: DepositETH, BorrowETH, WithdrawETH, WithdrawETHWithPermit

Permit and delegation signatures are prepared before Flow.Build; building a Flow is deterministic and does not own a signer. Permit-capable tokens and credit-delegation debt tokens require explicit erc20.PermitCapability or aave.DelegationCapability values with a reviewed EIP-712 domain version. The SDK does not infer signature support from symbols or the presence of a nonces() method.

RepayAll and WithdrawAll encode Aave's uint256.max sentinel while receipt validation checks the actual positive amount emitted by Aave. RepayAll requires enough token balance and allowance to cover the debt at execution time, including accrued interest and protocol rounding.

Built-in Strategies

Strategies are thin templates over public FlowSteps. They validate static inputs and return *defi.Flow; they do not read chain state, sign, submit, or execute transactions.

Open an exact Aave supply and borrow position:

flow, err := strategy.AaveSupplyBorrow(strategy.AaveSupplyBorrowParams{
	Account:       user,
	SupplyReserve: usdc,
	SupplyAmount:  decimal.NewFromInt(100),
	BorrowReserve: weth,
	BorrowAmount:  decimal.RequireFromString("0.01"),
})

Close one variable-debt and collateral reserve pair:

flow, err := strategy.AaveClosePosition(strategy.AaveClosePositionParams{
	Account:                 user,
	DebtReserve:             usdc,
	TemporaryRepayAllowance: decimal.NewFromInt(102),
	CollateralReserve:       weth,
})

The close strategy builds:

Approve(temporary allowance) -> RepayAll -> Approve(0) -> WithdrawAll

The temporary allowance is an upper bound rather than the actual debt. The final approval clears any unused allowance. The first version assumes standard ERC20 allowance replacement semantics and closes only the selected reserve pair. If another debt makes WithdrawAll unsafe, the atomic transaction reverts.

Execution Results

Runner.ExecuteWithResult validates the mined receipt against expectations produced by the same FlowSteps that built the calls.

Result behavior is explicit:

• failures before submission or mining return result == nil and an error;
• a mined transaction revert returns both the receipt-bearing result and an error;
• semantic event validation failure returns a partial result and an error;
• successful execution and validation return the complete result and no error.

Always inspect a non-nil result before returning the error when the transaction hash is operationally important. Wrapped execution and validation errors retain their errors.Is and errors.As chains.

Typed events can be selected without parsing raw logs:

approvals := defi.EventsOf[*erc20.ApprovalEvent](result)
repayments := defi.EventsOf[*aave.RepayEvent](result)
withdrawals := defi.EventsOf[*aave.WithdrawEvent](result)

Aave Market Discovery

Applications can resolve Aave reserve membership and reserve-token roles from a trusted market definition instead of maintaining a symbol-keyed token map:

market, err := aave.BaseV3Market()
if err != nil {
	return err
}
registry, err := aave.NewRegistry(client, market)
if err != nil {
	return err
}

snapshot, err := registry.Load(ctx)
if err != nil {
	return err
}
usdc, err := snapshot.Reserve(base.USDC)

The reviewed assets/base catalog provides convenient token.Ref values such as base.USDC and base.WETH. Each value contains only the Base chain and underlying contract address. Catalog membership is not an execution allowlist or a promise that an asset is currently active in Aave. Applications can use an uncatalogued asset by constructing token.NewRef(config.Base, address) and resolving it through the snapshot.

base.Lookup accepts exact, case-sensitive SDK catalog IDs. These IDs are not ERC20 symbols and are never matched against on-chain display metadata.

One discovery load resolves a block number and hash, pins every Pool, DataProvider, ERC20 metadata, and contract-code read to that block, validates the market's PoolAddressesProvider relationships, and returns an immutable MarketSnapshot. Address is the execution identity; symbols and names are display metadata only.

Load caches the first successful snapshot for that registry. It never refreshes implicitly. Call Refresh when the application intentionally wants a newer block; a failed refresh leaves the previous snapshot cached. Flow building does not own or trigger registry refreshes.

Architecture

The public composition and execution boundary is:

Flow
  -> FlowStep.Build
  -> BuiltStep { Calls, EventExpectations }
  -> ExecutionPlan
  -> Executor
  -> Receipt

ExecutionPlan + Receipt
  -> Validator
  -> ExecutionResult

Protocol packages own calldata, decoded event types, and semantic expectations. The root package owns neutral Flow, plan, validation, and result types. Executors know how to submit calls but do not import protocol packages.

Low-level Actions and Calls remain reusable implementation primitives under the public FlowStep API. Application code should normally begin with FlowSteps or a built-in strategy. The config.Coin-based protocol clients under client/contract remain available for migration but are deprecated; they are not the source of truth for executable Flow assets.

Repository Layout

Path	Responsibility
/	Flow, execution plan, runner, validator, constraints, and results
assets/	Chain-neutral catalog runtime and chain-specific reviewed asset packages
aave/	Aave FlowSteps, typed events, and event expectations
erc20/	ERC20 FlowSteps, typed events, and event expectations
strategy/	Opinionated Flow compositions over protocol FlowSteps
client/account/eip7702/	Delegation authorization, transactions, state, and lifecycle manager
client/account/simple7702/	Simple7702Account ABI, calldata, and executor
client/contract/	Low-level Actions, Calls, protocol clients, and executor primitives
config/	Supported chains and legacy static SDK configuration
integration/	Ginkgo tests against an Anvil Base mainnet fork

Deployment and Asset Trust

The Aave registry starts from a checked-in Base V3 deployment manifest under aave/manifests/. It contains only reviewed deployment anchors such as the Pool, PoolAddressesProvider, AaveProtocolDataProvider, and wrapped-token gateway. Dynamic reserve membership and reserve-token addresses are not copied into the manifest.

The root assets package provides the chain-neutral immutable catalog runtime. Each chain has its own thin package, such as assets/base, so token names remain unambiguous: future catalogs can expose ethereum.USDC or arbitrum.USDC without introducing a global symbol registry.

Each chain package keeps its loader in catalog.go. Named references such as base.USDC are generated from the reviewed manifest into catalog_gen.go; the generated file must not be edited by hand. New public references therefore appear as ordinary, reviewable Go diffs alongside the manifest update without duplicating the asset list in hand-written code.

The assets/base/manifest.json file is the first reviewed convenience catalog. It copies only chain-scoped underlying identities from the pinned AaveV3Base.ASSETS export. It does not copy decimals, symbols, aToken or debt token addresses, or protocol capabilities. Those values remain runtime-owned metadata and Aave registry relationships. Provider-specific extraction is kept in an internal adapter; neutral manifest validation and catalog lookup do not assume Aave, Base, or chain ID 8453.

Both manifests record the exact official @aave-dao/aave-address-book release and commit that produced it. SDK runtime code reads the embedded manifest only; it never fetches a mutable remote branch or npm package. A scheduled workflow can propose an upstream update as a draft pull request, but deployment and catalog changes always require human review. Routine updates may add reviewed catalog candidates, but they fail closed if an existing public catalog ID disappears, changes upstream key, or points at a new address. Such a change requires an explicit migration and deprecation decision.

Maintainers can reproduce the checked-in manifests with:

make update-aave-manifests

This update-only command installs the exact npm package pinned under tools/aave-address-book/, extracts the Base deployment anchors and underlying asset identities, and passes the normalized export through strict Go validators and canonical JSON generators. It also generates the chain package's named Go references from the validated asset manifest. The singular make update-aave-manifest target remains as an alias. Ordinary SDK builds and tests do not require Node.js or network access.

Adding another chain requires registering the SDK chain, adding a thin assets/<chain> package with its reviewed manifest and named references, and connecting an internal source adapter to the shared manifest generator. Lookup, ordering, immutability, strict parsing, and fail-closed evolution rules are shared and must not be copied into the new chain package. See Adding an Asset Chain for the complete source, generation, validation, integration, and automation workflow.

Development

Run unit tests and whitespace checks:

make check

Compile integration tests without connecting to an RPC endpoint:

go test -count=1 -run '^$' -tags=integration ./integration/...

Run the Base fork suite with Foundry's anvil installed:

BASE_RPC_URL=<base-mainnet-rpc-url> make anvil-base

In a second terminal:

BASE_RPC_URL=http://127.0.0.1:8545 make test-integration

The Anvil target selects a hardfork that supports EIP-7702 set-code transactions. Integration tests execute public Flow and strategy APIs against real Base Aave and ERC20 state.

Contributor references:

• Adding an Asset Chain
• Migrating from config.Coin to Resolved Assets
• Phase 1 MVP Spec and Glossary
• Static Flow Builder API

Changes should preserve the Flow -> ExecutionPlan -> Executor -> Validator boundaries. Protocol-specific calldata and event semantics belong in their protocol package; generic execution code must remain protocol-neutral.

Current Limitations

• Base is the only configured network.
• Aave V3 and ERC20 are the only public protocol step packages.
• Flow amounts are static and known before Build.
• Call return values and runtime balances cannot feed later calls.
• There is no built-in swap routing, slippage guard, health-factor guard, or dynamic leverage-loop execution.
• Strategy builders do not discover positions or simulate protocol state.

Future dynamic execution should extend the plan model without changing the ownership boundaries of protocol builders, executors, and validators.

Security

This project is experimental and has not been independently audited as a complete SDK and execution system. EIP-7702 delegation grants code execution in the EOA's context, so use a dedicated operation account with limited funds, verify the configured implementation, test against a fork, and keep a tested clear or redelegation path.

Protocol and asset changes made by a reverted batch are atomic, but gas and nonces are consumed and a newly processed delegation may remain installed. Start with small values and independently verify every transaction before using real funds.

License

This project is licensed under the MIT License. See LICENSE.

Documentation

Index

• Variables
• func EventsOf[T DecodedEvent](result *ExecutionResult) []T
• type Action
• type AmountConstraint
  • func AtLeast(minimum *big.Int) AmountConstraint
  • func AtMost(maximum *big.Int) AmountConstraint
  • func Exact(expected *big.Int) AmountConstraint
  • func Positive() AmountConstraint
• type BuildEnv
• type BuiltStep
• type Call
• type CallExecutor
• type DecodedEvent
• type EthereumClient
• type EventExpectation
• type EventMetadata
• type ExecutionError
  • func (e *ExecutionError) Error() string
  • func (e *ExecutionError) Unwrap() error
• type ExecutionMode
• type ExecutionPlan
  • func (p *ExecutionPlan) Calls() []Call
• type ExecutionResult
  • func ValidateExecution(plan *ExecutionPlan, receipt *types.Receipt) (*ExecutionResult, error)
• type ExecutionStage
• type ExpectationResult
• type FieldMismatch
• type Flow
  • func NewFlow(account common.Address, opts ...FlowOption) *Flow
  • func (f *Flow) Add(step FlowStep) *Flow
  • func (f *Flow) Build(ctx context.Context, conn EthereumClient) (*ExecutionPlan, error)
  • func (f *Flow) Execute(ctx context.Context, conn EthereumClient, executor CallExecutor) (*types.Receipt, error)
• type FlowOption
  • func WithChain(chain config.Chain) FlowOption
• type FlowStep
  • func ActionStep(name string, action Action) FlowStep
• type MatchContext
• type MatchDecision
• type MatchResult
  • func MatchAmountConstraints(field string, actual *big.Int, ctx MatchContext, ...) (MatchResult, error)
• type Runner
  • func NewRunner(conn EthereumClient, opts *bind.TransactOpts, chain config.Chain) *Runner
  • func (r *Runner) Execute(ctx context.Context, flow *Flow, mode ExecutionMode) (*types.Receipt, error)
  • func (r *Runner) ExecuteWithResult(ctx context.Context, flow *Flow, mode ExecutionMode) (*ExecutionResult, error)
• type SkipReason
• type StepID
• type StepResult
• type ValidationStatus

Variables

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")
	ErrMissingExecutor = errors.New("flow executor is required")
)

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.

Functions

func EventsOf

func EventsOf[T DecodedEvent](result *ExecutionResult) []T

EventsOf returns every validated event assignable to T in execution order.

Types

type Action

type Action = contract.Action

Action is an existing protocol action that can encode itself into a Call.

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 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        []Call
	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 Call

type Call = contract.Call

Call is the neutral contract call model shared by flow builders and executors.

type CallExecutor

type CallExecutor = contract.CallExecutor

CallExecutor executes Flow-built calls.

type DecodedEvent

type DecodedEvent interface {
	EventMetadata() EventMetadata
}

DecodedEvent is implemented by protocol-specific event result types.

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

type EventMetadata struct {
	Protocol string
	Name     string
	Emitter  common.Address
	LogIndex uint
}

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 ExecutionMode

type ExecutionMode string

ExecutionMode describes user-facing execution semantics.

const (
	// ExecutionEOA executes a one-call Flow as a normal EOA transaction.
	ExecutionEOA ExecutionMode = "eoa"
	// ExecutionAtomicEOA executes a Flow atomically through a delegated EOA.
	ExecutionAtomicEOA ExecutionMode = "atomic_eoa"
)

type ExecutionPlan

type ExecutionPlan struct {
	Account common.Address
	Steps   []BuiltStep
}

ExecutionPlan is the ordered, executor-neutral result of building a Flow. Account is the semantic caller identity for steps that derive owner, sender, or onBehalfOf values from BuildEnv.Account. Executors used with semantic validation must preserve it as the protocol-visible call origin.

func (*ExecutionPlan) Calls

func (p *ExecutionPlan) Calls() []Call

Calls returns the plan's calls in step order.

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

type FieldMismatch struct {
	Field    string
	Expected string
	Actual   string
}

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 a static ordered composition of DeFi steps.

func NewFlow

func NewFlow(account common.Address, opts ...FlowOption) *Flow

NewFlow creates an empty static flow for account.

func (*Flow) Add

func (f *Flow) Add(step FlowStep) *Flow

Add appends a step and returns the flow for fluent composition.

func (*Flow) Build

func (f *Flow) Build(ctx context.Context, conn EthereumClient) (*ExecutionPlan, error)

Build compiles all Flow steps into an ordered execution plan.

func (*Flow) Execute

func (f *Flow) Execute(ctx context.Context, conn EthereumClient, executor CallExecutor) (*types.Receipt, error)

Execute builds the flow and executes the resulting calls through executor.

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

type FlowStep interface {
	Build(ctx context.Context, env BuildEnv) (BuiltStep, error)
}

FlowStep builds one named step from shared Flow context.

func ActionStep

func ActionStep(name string, action Action) FlowStep

ActionStep adapts an existing Action into a FlowStep.

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 Runner

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

Runner executes Flows using user-facing execution modes.

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

func (r *Runner) Execute(ctx context.Context, flow *Flow, mode ExecutionMode) (*types.Receipt, error)

Execute builds and executes flow using mode.

func (*Runner) ExecuteWithResult

func (r *Runner) ExecuteWithResult(ctx context.Context, flow *Flow, mode ExecutionMode) (*ExecutionResult, error)

ExecuteWithResult 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 StepID

type StepID string

StepID identifies one built occurrence of a named Flow step.

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