github.com/intfoundation/intchain@v0.0.0-20220727031208-4316ad31ca73/interfaces.go (about)

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