evm/iface/types.go

// Copyright (C) 2020-2025, Lux Industries Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package iface

import (
	"context"
	"math/big"

	"github.com/luxfi/geth/common"
	"github.com/luxfi/evm/ids"
)

// Size constants
const (
	KiB = 1024       // 1 kibibyte
	MiB = 1024 * KiB // 1 mebibyte
	GiB = 1024 * MiB // 1 gibibyte
)

// ID is an alias to ids.ID
type ID = ids.ID

// BlockID is an alias to ids.BlockID
type BlockID = ids.BlockID

// Status represents the status of a block
type Status int

// Timestamp represents a block timestamp
type Timestamp struct {
	Unix int64
}

// SendConfig configures message sending
type SendConfig struct {
	NodeIDs       Set
	Validators    int
	NonValidators int
	Peers         int
}

// Set represents a set of node IDs
type Set interface {
	Contains(NodeID) bool
	Len() int
	List() []NodeID
	Add(...NodeID)
	Remove(...NodeID)
}

// CallMsg contains parameters for contract calls.
type CallMsg struct {
	From        common.Address   // the sender of the 'transaction'
	To          *common.Address  // the destination contract (nil for contract creation)
	Gas         uint64           // if 0, the call executes with near-infinite gas
	GasPrice    *big.Int         // wei <-> gas exchange ratio
	GasFeeCap   *big.Int         // EIP-1559 fee cap per gas.
	GasTipCap   *big.Int         // EIP-1559 tip per gas.
	Value       *big.Int         // amount of wei sent along with the call
	Data        []byte           // input data, usually an ABI-encoded contract method invocation
	BlobGasFeeCap *big.Int       // EIP-4844 blob gas fee cap
	BlobHashes  []common.Hash    // EIP-4844 blob hashes

	AccessList AccessList // EIP-2930 access list.
}

// FilterQuery contains options for contract log filtering.
type FilterQuery struct {
	BlockHash *common.Hash     // used by eth_getLogs, return logs only from block with this hash
	FromBlock *big.Int         // beginning of the queried range, nil means genesis block
	ToBlock   *big.Int         // end of the range, nil means latest block
	Addresses []common.Address // restricts matches to events created by specific contracts

	// The Topic list restricts matches to particular event topics. Each event has a list
	// of topics. Topics matches a prefix of that list. An empty element slice matches any
	// topic. Non-empty elements represent an alternative that matches any of the
	// contained topics.
	//
	// Examples:
	// {} or nil          matches any topic list
	// {{A}}              matches topic A in first position
	// {{}, {B}}          matches any topic in first position AND B in second position
	// {{A}, {B}}         matches topic A in first position AND B in second position
	// {{A, B}, {C, D}}   matches topic (A OR B) in first position AND (C OR D) in second position
	Topics [][]common.Hash
}

// ChainReader provides access to the blockchain. The methods in this interface access raw
// data from either the canonical chain (when requesting by block number) or any
// blockchain fork that was previously downloaded and processed by the node. The block
// number argument can be nil to select the latest canonical block. Reading block headers
// should be preferred over full blocks whenever possible.
//
// The returned error is NotFound if the requested item does not exist.
type EVMChainReader interface {
	BlockByHash(ctx context.Context, hash common.Hash) (*ETHBlock, error)
	BlockByNumber(ctx context.Context, number *big.Int) (*ETHBlock, error)
	HeaderByHash(ctx context.Context, hash common.Hash) (*Header, error)
	HeaderByNumber(ctx context.Context, number *big.Int) (*Header, error)
	TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error)
	TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*Transaction, error)

	// This method subscribes to notifications about changes of the head block of
	// the canonical chain.
	SubscribeNewHead(ctx context.Context, ch chan<- *Header) (Subscription, error)
}

// TransactionReader provides access to past transactions and their receipts.
// Implementations may impose arbitrary restrictions on the transactions and receipts
// that can be retrieved. Historic transactions may not be available.
//
// Avoid relying on this interface if possible. Contract logs (through the LogFilterer
// interface) are more reliable and usually safer in the presence of chain
// reorganisations.
//
// The returned error is NotFound if the requested item does not exist.
type TransactionReader interface {
	// TransactionByHash checks the pool of pending transactions in addition to the
	// blockchain. The isPending return value indicates whether the transaction has been
	// mined yet. Note that the transaction may not be part of the canonical chain even if
	// it's not pending.
	TransactionByHash(ctx context.Context, txHash common.Hash) (tx *Transaction, isPending bool, err error)
	// TransactionReceipt returns the receipt of a mined transaction. Note that the
	// transaction may not be included in the current canonical chain even if a receipt
	// exists.
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*Receipt, error)
}

// ChainStateReader wraps access to the state trie of the canonical blockchain. Note that
// implementations of the interface may be unable to return state values for old blocks.
// In many cases, using CallContract can be preferable to reading raw contract storage.
type ChainStateReader interface {
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
	StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error)
	CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error)
	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
}

// SyncProgress gives progress indications when the node is synchronising with
// the Ethereum network.
type SyncProgress struct {
	StartingBlock uint64 // Block number where sync began
	CurrentBlock  uint64 // Current block number where sync is at
	HighestBlock  uint64 // Highest alleged block number in the chain
}

// ChainSyncReader wraps access to the node's current sync status. If there's no
// sync currently running, it returns nil.
type ChainSyncReader interface {
	SyncProgress(ctx context.Context) (*SyncProgress, error)
}

// CallContract executes an Ethereum contract call with the specified data as the
// input.
type ContractCaller interface {
	CallContract(ctx context.Context, call CallMsg, blockNumber *big.Int) ([]byte, error)
}

// FilterLogs executes a log filter operation, blocking during execution and
// returning all the results in one batch.
//
// TODO(karalabe): Deprecate when the subscription one can return past data too.
type LogFilterer interface {
	FilterLogs(ctx context.Context, q FilterQuery) ([]Log, error)
	SubscribeFilterLogs(ctx context.Context, q FilterQuery, ch chan<- Log) (Subscription, error)
}

// TransactionSender wraps transaction sending. The SendTransaction method injects a
// signed transaction into the pending transaction pool for execution. If the transaction
// was a contract creation, the TransactionReceipt method can be used to retrieve the
// contract address after the transaction has been mined.
//
// The transaction must be signed and have a valid nonce.
type TransactionSender interface {
	SendTransaction(ctx context.Context, tx *Transaction) error
}

// GasPricer wraps the gas price oracle, which monitors the blockchain to determine the
// optimal gas price given current fee market conditions.
type GasPricer interface {
	SuggestGasPrice(ctx context.Context) (*big.Int, error)
}

// GasPricer1559 provides access to the EIP-1559 gas price oracle.
type GasPricer1559 interface {
	SuggestGasTipCap(ctx context.Context) (*big.Int, error)
}

// FeeHistoryReader provides access to the fee history oracle.
type FeeHistoryReader interface {
	FeeHistory(ctx context.Context, blockCount uint64, lastBlock *big.Int, rewardPercentiles []float64) (*FeeHistory, error)
}

// FeeHistory provides recent fee market data that consumers can use to determine
// a reasonable maxPriorityFeePerGas value.
type FeeHistory struct {
	OldestBlock       *big.Int     // block corresponding to first response value
	Reward            [][]*big.Int // list every txs priority fee per block
	BaseFee           []*big.Int   // list of each block's base fee
	GasUsedRatio      []float64    // ratio of gas used out of the total available limit
	BlobBaseFee       []*big.Int   // list of each block's blob base fee
	BlobGasUsedRatio  []float64    // ratio of blob gas used out of the total available limit
	NextBaseFee       *big.Int     // base fee for the next block
	NextBlobBaseFee   *big.Int     // blob base fee for the next block
}

// A PendingStateReader provides access to the pending state, which is the result of all
// known executable transactions which have not yet been included in the blockchain. It is
// commonly used to display the result of 'unconfirmed' actions (e.g. wallet value
// transfers) initiated by the user. The PendingNonceAt operation is a good way to
// retrieve the next available transaction nonce for a specific account.
type PendingStateReader interface {
	PendingBalanceAt(ctx context.Context, account common.Address) (*big.Int, error)
	PendingStorageAt(ctx context.Context, account common.Address, key common.Hash) ([]byte, error)
	PendingCodeAt(ctx context.Context, account common.Address) ([]byte, error)
	PendingNonceAt(ctx context.Context, account common.Address) (uint64, error)
	PendingTransactionCount(ctx context.Context) (uint, error)
}

// PendingContractCaller can be used to perform calls against the pending state.
type PendingContractCaller interface {
	PendingCallContract(ctx context.Context, call CallMsg) ([]byte, error)
}

// GasEstimator wraps EstimateGas, which tries to estimate the gas needed to execute a
// specific transaction based on the pending state. There is no guarantee that this is the
// true gas limit requirement as other transactions may be added or removed by miners, but
// it should provide a basis for setting a reasonable default.
type GasEstimator interface {
	EstimateGas(ctx context.Context, call CallMsg) (uint64, error)
}

// A PendingStateEventer provides access to real time notifications about changes to the
// pending state.
type PendingStateEventer interface {
	SubscribePendingTransactions(ctx context.Context, ch chan<- *Transaction) (Subscription, error)
}

// Subscription represents an event subscription where events are
// delivered on a data channel.
type Subscription interface {
	// Unsubscribe cancels the sending of events to the data channel
	// and closes the error channel.
	Unsubscribe()
	// Err returns the subscription error channel. The error channel receives
	// a value if there is an issue with the subscription (e.g. the network connection
	// delivering the events has been closed). Only one value will ever be sent.
	// The error channel is closed by Unsubscribe.
	Err() <-chan error
}

// AcceptedStateReader wraps access to the accepted state.
type AcceptedStateReader interface {
	AcceptedCodeAt(ctx context.Context, address common.Address) ([]byte, error)
	AcceptedNonceAt(ctx context.Context, address common.Address) (uint64, error)
}

// AcceptedContractCaller can be used to perform calls against the accepted state.
type AcceptedContractCaller interface {
	AcceptedCallContract(ctx context.Context, call CallMsg) ([]byte, error)
}