// Copyright 2016 The go-ethereum Authors

// (original work)

// Copyright 2024 The Erigon Authors

// (modifications)

// This file is part of Erigon.

//

// Erigon is free software: you can redistribute it and/or modify

// it under the terms of the GNU Lesser General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Erigon is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

// GNU Lesser General Public License for more details.

//

// You should have received a copy of the GNU Lesser General Public License

// along with Erigon. If not, see <http://www.gnu.org/licenses/>.

// Package ethereum defines interfaces for interacting with Ethereum.

package ethereum

import (

"context"

"errors"

"math/big"

"github.com/holiman/uint256"

"github.com/erigontech/erigon/common"

"github.com/erigontech/erigon/execution/types"

)

// NotFound is returned by API methods if the requested item does not exist.

var NotFound = errors.New("not found")

// TODO: move subscription to package event

// 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

}

// 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 ChainReader interface {

BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error)

BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error)

HeaderByHash(ctx context.Context, hash common.Hash) (*types.Header, error)

HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error)

TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error)

TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*types.Transaction, error)

// This method subscribes to notifications about changes of the head block of

// the canonical chain.

SubscribeNewHead(ctx context.Context, ch chan<- *types.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 *types.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) (*types.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 *uint256.Int) (*big.Int, error)

StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *uint256.Int) ([]byte, error)

CodeAt(ctx context.Context, account common.Address, blockNumber *uint256.Int) ([]byte, error)

NonceAt(ctx context.Context, account common.Address, blockNumber *uint256.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

PulledStates uint64 // Number of state trie entries already downloaded

KnownStates uint64 // Total number of state trie entries known about

}

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

}

// 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

MaxFeePerBlobGas *uint256.Int // EIP-4844 max_fee_per_blob_gas

GasPrice *uint256.Int // wei <-> gas exchange ratio

Value *uint256.Int // amount of wei sent along with the call

Data []byte // input data, usually an ABI-encoded contract method invocation

FeeCap *uint256.Int // EIP-1559 max_fee_per_gas

TipCap *uint256.Int // EIP-1559 max_priority_fee_per_gas

AccessList types.AccessList // EIP-2930 access list

BlobHashes []common.Hash // EIP-4844 versioned blob hashes

Authorizations []types.Authorization // EIP-3074 authorizations

}

// A ContractCaller provides contract calls, essentially transactions that are executed by

// the EVM but not mined into the blockchain. ContractCall is a low-level method to

// execute such calls. For applications which are structured around specific contracts,

// the abigen tool provides a nicer, properly typed way to perform calls.

type ContractCaller interface {

CallContract(ctx context.Context, call CallMsg, blockNumber *uint256.Int) ([]byte, error)

}

// 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

}

// LogFilterer provides access to contract log events using a one-off query or continuous

// event subscription.

//

// Logs received through a streaming query subscription may have Removed set to true,

// indicating that the log was reverted due to a chain reorganisation.

type LogFilterer interface {

FilterLogs(ctx context.Context, q FilterQuery) ([]types.Log, error)

SubscribeFilterLogs(ctx context.Context, q FilterQuery, ch chan<- types.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 to be included. Consumers of the

// API can use package accounts to maintain local private keys and need can retrieve the

// next available nonce using PendingNonceAt.

type TransactionSender interface {

SendTransaction(ctx context.Context, txn *types.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)

}

// 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<- *types.Transaction) (Subscription, error)

}