execution

type Address [20]byte

type Block interface {
	// Number returns the block number.
	Number() *big.Int

	// Hash returns the block hash.
	Hash() Hash

	// ParentHash returns the parent block hash.
	ParentHash() Hash

	// BaseFee returns the base fee per gas (EIP-1559), or nil for pre-London blocks.
	BaseFee() *big.Int

	// Transactions returns all transactions in the block.
	Transactions() []Transaction
}

type Config struct {
	// The address of the Execution node to connect to
	NodeAddress string `yaml:"nodeAddress"`
	// NodeHeaders is a map of headers to send to the execution node.
	NodeHeaders map[string]string `yaml:"nodeHeaders"`
	// Name is the name of the execution node
	Name string `yaml:"name"`
}

type DataSource interface {
	// BlockNumber returns the current block number.
	BlockNumber(ctx context.Context) (*uint64, error)

	// BlockByNumber returns the block at the given number.
	BlockByNumber(ctx context.Context, number *big.Int) (Block, error)

	// BlocksByNumbers returns blocks at the given numbers.
	// Returns blocks up to the first not-found (contiguous only).
	BlocksByNumbers(ctx context.Context, numbers []*big.Int) ([]Block, error)

	// BlockReceipts returns all receipts for the block at the given number.
	BlockReceipts(ctx context.Context, number *big.Int) ([]Receipt, error)

	// TransactionReceipt returns the receipt for the transaction with the given hash.
	TransactionReceipt(ctx context.Context, hash string) (Receipt, error)

	// DebugTraceTransaction returns the execution trace for the transaction.
	DebugTraceTransaction(ctx context.Context, hash string, blockNumber *big.Int, opts TraceOptions) (*TraceTransaction, error)

	// ChainID returns the chain ID.
	ChainID() int64

	// ClientType returns the client type/version string.
	ClientType() string

	// IsSynced returns true if the data source is fully synced.
	IsSynced() bool
}

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

type ErigonResult struct {
	Gas         uint64  `json:"gas"`
	Failed      bool    `json:"failed"`
	ReturnValue *string `json:"returnValue"`
	// empty array on transfer
	StructLogs []ErigonStructLog `json:"structLogs"`
}

type ErigonStructLog struct {
	PC         uint32    `json:"pc"`
	Op         string    `json:"op"`
	Gas        uint64    `json:"gas"`
	GasCost    uint64    `json:"gasCost"`
	Depth      uint64    `json:"depth"`
	ReturnData []byte    `json:"returnData"`
	Refund     *uint64   `json:"refund,omitempty"`
	Error      *string   `json:"error,omitempty"`
	Stack      *[]string `json:"stack,omitempty"`
}

type Hash [32]byte

type Node interface {
	// Start initializes the node and begins any background operations.
	// For RPCNode, this establishes the RPC connection and starts health monitoring.
	// For EmbeddedNode, this is a no-op as the host controls the DataSource lifecycle.
	Start(ctx context.Context) error

	// Stop gracefully shuts down the node and releases resources.
	// Should be called when the node is no longer needed.
	Stop(ctx context.Context) error

	// OnReady registers a callback to be invoked when the node becomes ready.
	// For RPCNode, callbacks execute when the RPC connection is healthy.
	// For EmbeddedNode, callbacks execute when MarkReady is called by the host.
	// Multiple callbacks can be registered and will execute in registration order.
	OnReady(ctx context.Context, callback func(ctx context.Context) error)

	// BlockNumber returns the current block number from the execution client.
	BlockNumber(ctx context.Context) (*uint64, error)

	// BlockByNumber returns the block at the given number.
	BlockByNumber(ctx context.Context, number *big.Int) (Block, error)

	// BlocksByNumbers returns blocks at the given numbers using batch RPC.
	// Returns blocks up to the first not-found (contiguous only).
	// If a block is not found, the returned slice contains all blocks before that point.
	BlocksByNumbers(ctx context.Context, numbers []*big.Int) ([]Block, error)

	// BlockReceipts returns all receipts for the block at the given number.
	BlockReceipts(ctx context.Context, number *big.Int) ([]Receipt, error)

	// TransactionReceipt returns the receipt for the transaction with the given hash.
	TransactionReceipt(ctx context.Context, hash string) (Receipt, error)

	// DebugTraceTransaction returns the execution trace for the transaction.
	DebugTraceTransaction(ctx context.Context, hash string, blockNumber *big.Int, opts TraceOptions) (*TraceTransaction, error)

	// ChainID returns the chain ID reported by the execution client.
	ChainID() int64

	// ClientType returns the client type/version string (e.g., "geth/1.10.0").
	ClientType() string

	// IsSynced returns true if the execution client is fully synced.
	IsSynced() bool

	// Name returns the configured name for this node.
	Name() string
}

type Receipt interface {
	// Status returns the transaction status (1=success, 0=failure).
	Status() uint64

	// TxHash returns the transaction hash.
	TxHash() Hash

	// GasUsed returns the post-refund gas used by the transaction (what the user pays).
	//
	// EIP-7778 context: This remains post-refund. The EIP-7778 split between receipt gas
	// and block gas only affects ExecutionResult at the EVM layer; the Receipt's GasUsed
	// field and its derivation from CumulativeGasUsed are unchanged.
	GasUsed() uint64
}

type StructLog struct {
	// PC is the program counter. Kept for RPC backward compatibility but not
	// populated in embedded mode (always 0).
	PC uint32 `json:"pc"`

	// Op is the opcode name (e.g., "PUSH1", "CALL", "SSTORE").
	Op string `json:"op"`

	// Gas is the remaining gas before this opcode executes.
	Gas uint64 `json:"gas"`

	// GasCost is the static gas cost of the opcode (may differ from actual GasUsed).
	GasCost uint64 `json:"gasCost"`

	// GasUsed is the actual gas consumed by this opcode.
	// In embedded mode: pre-computed by tracer using gas difference to next opcode.
	// In RPC mode: computed post-hoc by ComputeGasUsed(), this field will be 0.
	GasUsed uint64 `json:"gasUsed,omitempty"`

	// Depth is the call stack depth (1 = top-level, increases with CALL/CREATE).
	Depth uint64 `json:"depth"`

	// ReturnData contains the return data from the last CALL/STATICCALL/etc.
	ReturnData *string `json:"returnData"`

	// Refund is the gas refund counter value.
	Refund *uint64 `json:"refund,omitempty"`

	// Error contains any error message if the opcode failed.
	Error *string `json:"error,omitempty"`

	// Stack contains the EVM stack state (RPC mode only).
	// In embedded mode this is nil - use CallToAddress instead.
	Stack *[]string `json:"stack,omitempty"`

	// CallToAddress is the target address for CALL/STATICCALL/DELEGATECALL/CALLCODE.
	// In embedded mode: pre-extracted by tracer from stack[len-2].
	// In RPC mode: nil, extracted post-hoc from Stack by extractCallAddress().
	CallToAddress *string `json:"callToAddress,omitempty"`

	// MemorySize is the EVM memory size in bytes at the time this opcode executes.
	// Used to compute memory expansion gas between consecutive opcodes.
	// In embedded mode: captured by tracer from scope.MemoryData().
	// In RPC mode: 0 (not available).
	MemorySize uint32 `json:"memSize,omitempty"`

	// CallTransfersValue indicates whether a CALL/CALLCODE transfers non-zero ETH value.
	// True only for CALL/CALLCODE with value > 0 on the stack.
	// Used to normalize CALL gas for cold access detection.
	CallTransfersValue bool `json:"callTransfersValue,omitempty"`

	// ExtCodeCopySize is the size parameter for EXTCODECOPY opcodes.
	// Used to compute the copy cost component for cold access detection.
	ExtCodeCopySize uint32 `json:"extCodeCopySize,omitempty"`
}

type TraceOptions struct {
	DisableStorage   bool
	DisableStack     bool
	DisableMemory    bool
	EnableReturnData bool
}

type TraceTransaction struct {
	// Gas is the post-refund gas used by this transaction (what the user pays).
	// Set by the data source from the execution result or receipt's GasUsed.
	//
	// EIP-7778 context: After EIP-7778, Ethereum splits gas accounting into:
	//   - ReceiptGasUsed (post-refund): what the user pays, stored in receipts
	//   - BlockGasUsed (pre-refund): used for block gas limit accounting
	// This field carries the receipt (post-refund) value. The computeIntrinsicGas()
	// formula in structlog_agg depends on this being post-refund.
	Gas         uint64  `json:"gas"`
	Failed      bool    `json:"failed"`
	ReturnValue *string `json:"returnValue"`

	Structlogs []StructLog
}

type Transaction interface {
	// Hash returns the transaction hash.
	Hash() Hash

	// Type returns the transaction type (0=legacy, 1=access list, 2=dynamic fee, 3=blob).
	Type() uint8

	// To returns the recipient address, or nil for contract creation.
	To() *Address

	// From returns the sender address.
	// This is computed by the data source using types.Sender() or equivalent.
	From() Address

	// Nonce returns the sender account nonce.
	Nonce() uint64

	// Gas returns the gas limit.
	Gas() uint64

	// GasPrice returns the gas price (for legacy transactions).
	GasPrice() *big.Int

	// GasTipCap returns the max priority fee per gas (EIP-1559).
	GasTipCap() *big.Int

	// GasFeeCap returns the max fee per gas (EIP-1559).
	GasFeeCap() *big.Int

	// Value returns the value transferred in wei.
	Value() *big.Int

	// Data returns the input data (calldata).
	Data() []byte

	// Size returns the encoded transaction size in bytes.
	Size() uint64

	// ChainId returns the chain ID, or nil for legacy transactions.
	ChainId() *big.Int

	// BlobGas returns the blob gas used (for blob transactions).
	BlobGas() uint64

	// BlobGasFeeCap returns the max blob fee per gas (for blob transactions).
	BlobGasFeeCap() *big.Int

	// BlobHashes returns the versioned hashes (for blob transactions).
	BlobHashes() []Hash
}