github.com/cgcardona/r-subnet-evm@v0.1.5/interfaces/interfaces.go (about) 1 // (c) 2019-2020, Ava Labs, Inc. 2 // 3 // This file is a derived work, based on the go-ethereum library whose original 4 // notices appear below. 5 // 6 // It is distributed under a license compatible with the licensing terms of the 7 // original code from which it is derived. 8 // 9 // Much love to the original authors for their work. 10 // ********** 11 // Copyright 2016 The go-ethereum Authors 12 // This file is part of the go-ethereum library. 13 // 14 // The go-ethereum library is free software: you can redistribute it and/or modify 15 // it under the terms of the GNU Lesser General Public License as published by 16 // the Free Software Foundation, either version 3 of the License, or 17 // (at your option) any later version. 18 // 19 // The go-ethereum library is distributed in the hope that it will be useful, 20 // but WITHOUT ANY WARRANTY; without even the implied warranty of 21 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 // GNU Lesser General Public License for more details. 23 // 24 // You should have received a copy of the GNU Lesser General Public License 25 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>. 26 27 // Package ethereum defines interfaces for interacting with Ethereum. 28 package interfaces 29 30 import ( 31 "context" 32 "errors" 33 "math/big" 34 35 "github.com/cgcardona/r-subnet-evm/core/types" 36 "github.com/ethereum/go-ethereum/common" 37 ) 38 39 // NotFound is returned by API methods if the requested item does not exist. 40 var NotFound = errors.New("not found") 41 42 // TODO: move subscription to package event 43 44 // Subscription represents an event subscription where events are 45 // delivered on a data channel. 46 type Subscription interface { 47 // Unsubscribe cancels the sending of events to the data channel 48 // and closes the error channel. 49 Unsubscribe() 50 // Err returns the subscription error channel. The error channel receives 51 // a value if there is an issue with the subscription (e.g. the network connection 52 // delivering the events has been closed). Only one value will ever be sent. 53 // The error channel is closed by Unsubscribe. 54 Err() <-chan error 55 } 56 57 // ChainReader provides access to the blockchain. The methods in this interface access raw 58 // data from either the canonical chain (when requesting by block number) or any 59 // blockchain fork that was previously downloaded and processed by the node. The block 60 // number argument can be nil to select the latest canonical block. Reading block headers 61 // should be preferred over full blocks whenever possible. 62 // 63 // The returned error is NotFound if the requested item does not exist. 64 type ChainReader interface { 65 BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error) 66 BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error) 67 HeaderByHash(ctx context.Context, hash common.Hash) (*types.Header, error) 68 HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error) 69 TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error) 70 TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*types.Transaction, error) 71 72 // This method subscribes to notifications about changes of the head block of 73 // the canonical chain. 74 SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (Subscription, error) 75 } 76 77 // TransactionReader provides access to past transactions and their receipts. 78 // Implementations may impose arbitrary restrictions on the transactions and receipts that 79 // can be retrieved. Historic transactions may not be available. 80 // 81 // Avoid relying on this interface if possible. Contract logs (through the LogFilterer 82 // interface) are more reliable and usually safer in the presence of chain 83 // reorganisations. 84 // 85 // The returned error is NotFound if the requested item does not exist. 86 type TransactionReader interface { 87 // TransactionByHash checks the pool of pending transactions in addition to the 88 // blockchain. The isPending return value indicates whether the transaction has been 89 // mined yet. Note that the transaction may not be part of the canonical chain even if 90 // it's not pending. 91 TransactionByHash(ctx context.Context, txHash common.Hash) (tx *types.Transaction, isPending bool, err error) 92 // TransactionReceipt returns the receipt of a mined transaction. Note that the 93 // transaction may not be included in the current canonical chain even if a receipt 94 // exists. 95 TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error) 96 } 97 98 // ChainStateReader wraps access to the state trie of the canonical blockchain. Note that 99 // implementations of the interface may be unable to return state values for old blocks. 100 // In many cases, using CallContract can be preferable to reading raw contract storage. 101 type ChainStateReader interface { 102 BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error) 103 StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error) 104 CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error) 105 NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error) 106 } 107 108 // CallMsg contains parameters for contract calls. 109 type CallMsg struct { 110 From common.Address // the sender of the 'transaction' 111 To *common.Address // the destination contract (nil for contract creation) 112 Gas uint64 // if 0, the call executes with near-infinite gas 113 GasPrice *big.Int // wei <-> gas exchange ratio 114 GasFeeCap *big.Int // EIP-1559 fee cap per gas. 115 GasTipCap *big.Int // EIP-1559 tip per gas. 116 Value *big.Int // amount of wei sent along with the call 117 Data []byte // input data, usually an ABI-encoded contract method invocation 118 119 AccessList types.AccessList // EIP-2930 access list. 120 } 121 122 // A ContractCaller provides contract calls, essentially transactions that are executed by 123 // the EVM but not mined into the blockchain. ContractCall is a low-level method to 124 // execute such calls. For applications which are structured around specific contracts, 125 // the abigen tool provides a nicer, properly typed way to perform calls. 126 type ContractCaller interface { 127 CallContract(ctx context.Context, call CallMsg, blockNumber *big.Int) ([]byte, error) 128 } 129 130 // FilterQuery contains options for contract log filtering. 131 type FilterQuery struct { 132 BlockHash *common.Hash // used by eth_getLogs, return logs only from block with this hash 133 FromBlock *big.Int // beginning of the queried range, nil means genesis block 134 ToBlock *big.Int // end of the range, nil means latest block 135 Addresses []common.Address // restricts matches to events created by specific contracts 136 137 // The Topic list restricts matches to particular event topics. Each event has a list 138 // of topics. Topics matches a prefix of that list. An empty element slice matches any 139 // topic. Non-empty elements represent an alternative that matches any of the 140 // contained topics. 141 // 142 // Examples: 143 // {} or nil matches any topic list 144 // {{A}} matches topic A in first position 145 // {{}, {B}} matches any topic in first position AND B in second position 146 // {{A}, {B}} matches topic A in first position AND B in second position 147 // {{A, B}, {C, D}} matches topic (A OR B) in first position AND (C OR D) in second position 148 Topics [][]common.Hash 149 } 150 151 // LogFilterer provides access to contract log events using a one-off query or continuous 152 // event subscription. 153 // 154 // Logs received through a streaming query subscription may have Removed set to true, 155 // indicating that the log was reverted due to a chain reorganisation. 156 type LogFilterer interface { 157 FilterLogs(ctx context.Context, q FilterQuery) ([]types.Log, error) 158 SubscribeFilterLogs(ctx context.Context, q FilterQuery, ch chan<- types.Log) (Subscription, error) 159 } 160 161 // TransactionSender wraps transaction sending. The SendTransaction method injects a 162 // signed transaction into the pending transaction pool for execution. If the transaction 163 // was a contract creation, the TransactionReceipt method can be used to retrieve the 164 // contract address after the transaction has been mined. 165 // 166 // The transaction must be signed and have a valid nonce to be included. Consumers of the 167 // API can use package accounts to maintain local private keys and need can retrieve the 168 // next available nonce using AcceptedNonceAt. 169 type TransactionSender interface { 170 SendTransaction(ctx context.Context, tx *types.Transaction) error 171 } 172 173 // GasPricer wraps the gas price oracle, which monitors the blockchain to determine the 174 // optimal gas price given current fee market conditions. 175 type GasPricer interface { 176 SuggestGasPrice(ctx context.Context) (*big.Int, error) 177 } 178 179 // FeeHistory provides recent fee market data that consumers can use to determine 180 // a reasonable maxPriorityFeePerGas value. 181 type FeeHistory struct { 182 OldestBlock *big.Int // block corresponding to first response value 183 Reward [][]*big.Int // list every txs priority fee per block 184 BaseFee []*big.Int // list of each block's base fee 185 GasUsedRatio []float64 // ratio of gas used out of the total available limit 186 } 187 188 // An AcceptedStateReceiver provides access to the accepted state ie. the state of the 189 // most recently accepted block. 190 type AcceptedStateReader interface { 191 AcceptedCodeAt(ctx context.Context, account common.Address) ([]byte, error) 192 AcceptedNonceAt(ctx context.Context, account common.Address) (uint64, error) 193 } 194 195 // AcceptedContractCaller can be used to perform calls against the accepted state. 196 type AcceptedContractCaller interface { 197 AcceptedCallContract(ctx context.Context, call CallMsg) ([]byte, error) 198 } 199 200 // GasEstimator wraps EstimateGas, which tries to estimate the gas needed to execute a 201 // specific transaction based on the pending state. There is no guarantee that this is the 202 // true gas limit requirement as other transactions may be added or removed by miners, but 203 // it should provide a basis for setting a reasonable default. 204 type GasEstimator interface { 205 EstimateGas(ctx context.Context, call CallMsg) (uint64, error) 206 } 207 208 // A PendingStateEventer provides access to real time notifications about changes to the 209 // pending state. 210 type PendingStateEventer interface { 211 SubscribePendingTransactions(ctx context.Context, ch chan<- *types.Transaction) (Subscription, error) 212 }