interfaces.go 10 KB

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