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