Home

Welcome to the sandbox wiki! package ethclient

import ( "context" "encoding/json" "fmt" "math/big"

"github.com/ethereum/go-ethereum"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/common/hexutil"
"github.com/ethereum/go-ethereum/core/types"
"github.com/ethereum/go-ethereum/rlp"
"github.com/ethereum/go-ethereum/rpc"

)

// Client defines typed wrappers for the Ethereum RPC API. type Client struct { c *rpc.Client }

// Dial connects a client to the given URL. func Dial(rawurl string) (*Client, error) { c, err := rpc.Dial(rawurl) if err != nil { return nil, err } return NewClient(c), nil }

// NewClient creates a client that uses the given RPC client. func NewClient(c *rpc.Client) *Client { return &Client{c} }

// Blockchain Access

// BlockByHash returns the given full block. // // Note that loading full blocks requires two requests. Use HeaderByHash // if you don't need all transactions or uncle headers. func (ec *Client) BlockByHash(ctx context.Context, hash common.Hash) (*types.Block, error) { return ec.getBlock(ctx, "eth_getBlockByHash", hash, true) }

// BlockByNumber returns a block from the current canonical chain. If number is nil, the // latest known block is returned. // // Note that loading full blocks requires two requests. Use HeaderByNumber // if you don't need all transactions or uncle headers. func (ec *Client) BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error) { return ec.getBlock(ctx, "eth_getBlockByNumber", toBlockNumArg(number), true) }

type rpcBlock struct { Hash common.Hash json:"hash" Transactions []*types.Transaction json:"transactions" UncleHashes []common.Hash json:"uncles" }

func (ec *Client) getBlock(ctx context.Context, method string, args ...interface{}) (*types.Block, error) { var raw json.RawMessage err := ec.c.CallContext(ctx, &raw, method, args...) if err != nil { return nil, err } else if len(raw) == 0 { return nil, ethereum.NotFound } // Decode header and transactions. var head *types.Header var body rpcBlock if err := json.Unmarshal(raw, &head); err != nil { return nil, err } if err := json.Unmarshal(raw, &body); err != nil { return nil, err } // Quick-verify transaction and uncle lists. This mostly helps with debugging the server. if head.UncleHash == types.EmptyUncleHash && len(body.UncleHashes) > 0 { return nil, fmt.Errorf("server returned non-empty uncle list but block header indicates no uncles") } if head.UncleHash != types.EmptyUncleHash && len(body.UncleHashes) == 0 { return nil, fmt.Errorf("server returned empty uncle list but block header indicates uncles") } if head.TxHash == types.EmptyRootHash && len(body.Transactions) > 0 { return nil, fmt.Errorf("server returned non-empty transaction list but block header indicates no transactions") } if head.TxHash != types.EmptyRootHash && len(body.Transactions) == 0 { return nil, fmt.Errorf("server returned empty transaction list but block header indicates transactions") } // Load uncles because they are not included in the block response. var uncles []*types.Header if len(body.UncleHashes) > 0 { uncles = make([]*types.Header, len(body.UncleHashes)) reqs := make([]rpc.BatchElem, len(body.UncleHashes)) for i := range reqs { reqs[i] = rpc.BatchElem{ Method: "eth_getUncleByBlockHashAndIndex", Args: []interface{}{body.Hash, hexutil.EncodeUint64(uint64(i))}, Result: &uncles[i], } } if err := ec.c.BatchCallContext(ctx, reqs); err != nil { return nil, err } for i := range reqs { if reqs[i].Error != nil { return nil, reqs[i].Error } if uncles[i] == nil { return nil, fmt.Errorf("got null header for uncle %d of block %x", i, body.Hash[:]) } } } return types.NewBlockWithHeader(head).WithBody(body.Transactions, uncles), nil }

// HeaderByHash returns the block header with the given hash. func (ec *Client) HeaderByHash(ctx context.Context, hash common.Hash) (*types.Header, error) { var head *types.Header err := ec.c.CallContext(ctx, &head, "eth_getBlockByHash", hash, false) if err == nil && head == nil { err = ethereum.NotFound } return head, err }

// HeaderByNumber returns a block header from the current canonical chain. If number is // nil, the latest known header is returned. func (ec *Client) HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error) { var head *types.Header err := ec.c.CallContext(ctx, &head, "eth_getBlockByNumber", toBlockNumArg(number), false) if err == nil && head == nil { err = ethereum.NotFound } return head, err }

// TransactionByHash returns the transaction with the given hash. func (ec *Client) TransactionByHash(ctx context.Context, hash common.Hash) (tx *types.Transaction, isPending bool, err error) { var raw json.RawMessage err = ec.c.CallContext(ctx, &raw, "eth_getTransactionByHash", hash) if err != nil { return nil, false, err } else if len(raw) == 0 { return nil, false, ethereum.NotFound } if err := json.Unmarshal(raw, &tx); err != nil { return nil, false, err } else if _, r, _ := tx.RawSignatureValues(); r == nil { return nil, false, fmt.Errorf("server returned transaction without signature") } var block struct{ BlockHash *common.Hash } if err := json.Unmarshal(raw, &block); err != nil { return nil, false, err } return tx, block.BlockHash == nil, nil }

// TransactionCount returns the total number of transactions in the given block. func (ec *Client) TransactionCount(ctx context.Context, blockHash common.Hash) (uint, error) { var num hexutil.Uint err := ec.c.CallContext(ctx, &num, "eth_getBlockTransactionCountByHash", blockHash) return uint(num), err }

// TransactionInBlock returns a single transaction at index in the given block. func (ec *Client) TransactionInBlock(ctx context.Context, blockHash common.Hash, index uint) (*types.Transaction, error) { var tx *types.Transaction err := ec.c.CallContext(ctx, &tx, "eth_getTransactionByBlockHashAndIndex", blockHash, hexutil.Uint64(index)) if err == nil { if tx == nil { return nil, ethereum.NotFound } else if _, r, _ := tx.RawSignatureValues(); r == nil { return nil, fmt.Errorf("server returned transaction without signature") } } return tx, err }

// TransactionReceipt returns the receipt of a transaction by transaction hash. // Note that the receipt is not available for pending transactions. func (ec *Client) TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error) { var r *types.Receipt err := ec.c.CallContext(ctx, &r, "eth_getTransactionReceipt", txHash) if err == nil { if r == nil { return nil, ethereum.NotFound } else if len(r.PostState) == 0 { return nil, fmt.Errorf("server returned receipt without post state") } } return r, err }

func toBlockNumArg(number *big.Int) string { if number == nil { return "latest" } return hexutil.EncodeBig(number) }

type rpcProgress struct { StartingBlock hexutil.Uint64 CurrentBlock hexutil.Uint64 HighestBlock hexutil.Uint64 PulledStates hexutil.Uint64 KnownStates hexutil.Uint64 }

// SyncProgress retrieves the current progress of the sync algorithm. If there's // no sync currently running, it returns nil. func (ec *Client) SyncProgress(ctx context.Context) (*ethereum.SyncProgress, error) { var raw json.RawMessage if err := ec.c.CallContext(ctx, &raw, "eth_syncing"); err != nil { return nil, err } // Handle the possible response types var syncing bool if err := json.Unmarshal(raw, &syncing); err == nil { return nil, nil // Not syncing (always false) } var progress *rpcProgress if err := json.Unmarshal(raw, &progress); err != nil { return nil, err } return &ethereum.SyncProgress{ StartingBlock: uint64(progress.StartingBlock), CurrentBlock: uint64(progress.CurrentBlock), HighestBlock: uint64(progress.HighestBlock), PulledStates: uint64(progress.PulledStates), KnownStates: uint64(progress.KnownStates), }, nil }

// SubscribeNewHead subscribes to notifications about the current blockchain head // on the given channel. func (ec *Client) SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (ethereum.Subscription, error) { return ec.c.EthSubscribe(ctx, ch, "newHeads", map[string]struct{}{}) }

// State Access

// BalanceAt returns the wei balance of the given account. // The block number can be nil, in which case the balance is taken from the latest known block. func (ec *Client) BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error) { var result hexutil.Big err := ec.c.CallContext(ctx, &result, "eth_getBalance", account, toBlockNumArg(blockNumber)) return (*big.Int)(&result), err }

// StorageAt returns the value of key in the contract storage of the given account. // The block number can be nil, in which case the value is taken from the latest known block. func (ec *Client) StorageAt(ctx context.Context, account common.Address, key common.Hash, blockNumber *big.Int) ([]byte, error) { var result hexutil.Bytes err := ec.c.CallContext(ctx, &result, "eth_getStorageAt", account, key, toBlockNumArg(blockNumber)) return result, err }

// CodeAt returns the contract code of the given account. // The block number can be nil, in which case the code is taken from the latest known block. func (ec *Client) CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error) { var result hexutil.Bytes err := ec.c.CallContext(ctx, &result, "eth_getCode", account, toBlockNumArg(blockNumber)) return result, err }

// NonceAt returns the account nonce of the given account. // The block number can be nil, in which case the nonce is taken from the latest known block. func (ec *Client) NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error) { var result hexutil.Uint64 err := ec.c.CallContext(ctx, &result, "eth_getTransactionCount", account, toBlockNumArg(blockNumber)) return uint64(result), err }

// Filters

// FilterLogs executes a filter query. func (ec *Client) FilterLogs(ctx context.Context, q ethereum.FilterQuery) ([]types.Log, error) { var result []types.Log err := ec.c.CallContext(ctx, &result, "eth_getLogs", toFilterArg(q)) return result, err }

// SubscribeFilterLogs subscribes to the results of a streaming filter query. func (ec *Client) SubscribeFilterLogs(ctx context.Context, q ethereum.FilterQuery, ch chan<- types.Log) (ethereum.Subscription, error) { return ec.c.EthSubscribe(ctx, ch, "logs", toFilterArg(q)) }

func toFilterArg(q ethereum.FilterQuery) interface{} { arg := map[string]interface{}{ "fromBlock": toBlockNumArg(q.FromBlock), "toBlock": toBlockNumArg(q.ToBlock), "address": q.Addresses, "topics": q.Topics, } if q.FromBlock == nil { arg["fromBlock"] = "0x0" } return arg }

// Pending State

// PendingBalanceAt returns the wei balance of the given account in the pending state. func (ec *Client) PendingBalanceAt(ctx context.Context, account common.Address) (*big.Int, error) { var result hexutil.Big err := ec.c.CallContext(ctx, &result, "eth_getBalance", account, "pending") return (*big.Int)(&result), err }

// PendingStorageAt returns the value of key in the contract storage of the given account in the pending state. func (ec *Client) PendingStorageAt(ctx context.Context, account common.Address, key common.Hash) ([]byte, error) { var result hexutil.Bytes err := ec.c.CallContext(ctx, &result, "eth_getStorageAt", account, key, "pending") return result, err }

// PendingCodeAt returns the contract code of the given account in the pending state. func (ec *Client) PendingCodeAt(ctx context.Context, account common.Address) ([]byte, error) { var result hexutil.Bytes err := ec.c.CallContext(ctx, &result, "eth_getCode", account, "pending") return result, err }

// PendingNonceAt returns the account nonce of the given account in the pending state. // This is the nonce that should be used for the next transaction. func (ec *Client) PendingNonceAt(ctx context.Context, account common.Address) (uint64, error) { var result hexutil.Uint64 err := ec.c.CallContext(ctx, &result, "eth_getTransactionCount", account, "pending") return uint64(result), err }

// PendingTransactionCount returns the total number of transactions in the pending state. func (ec *Client) PendingTransactionCount(ctx context.Context) (uint, error) { var num hexutil.Uint err := ec.c.CallContext(ctx, &num, "eth_getBlockTransactionCountByNumber", "pending") return uint(num), err }

// TODO: SubscribePendingTransactions (needs server side)

// Contract Calling

// CallContract executes a message call transaction, which is directly executed in the VM // of the node, but never mined into the blockchain. // // blockNumber selects the block height at which the call runs. It can be nil, in which // case the code is taken from the latest known block. Note that state from very old // blocks might not be available. func (ec *Client) CallContract(ctx context.Context, msg ethereum.CallMsg, blockNumber *big.Int) ([]byte, error) { var hex hexutil.Bytes err := ec.c.CallContext(ctx, &hex, "eth_call", toCallArg(msg), toBlockNumArg(blockNumber)) if err != nil { return nil, err } return hex, nil }

// PendingCallContract executes a message call transaction using the EVM. // The state seen by the contract call is the pending state. func (ec *Client) PendingCallContract(ctx context.Context, msg ethereum.CallMsg) ([]byte, error) { var hex hexutil.Bytes err := ec.c.CallContext(ctx, &hex, "eth_call", toCallArg(msg), "pending") if err != nil { return nil, err } return hex, nil }

// SuggestGasPrice retrieves the currently suggested gas price to allow a timely // execution of a transaction. func (ec *Client) SuggestGasPrice(ctx context.Context) (*big.Int, error) { var hex hexutil.Big if err := ec.c.CallContext(ctx, &hex, "eth_gasPrice"); err != nil { return nil, err } return (*big.Int)(&hex), nil }

// EstimateGas tries to estimate the gas needed to execute a specific transaction based on // the current pending state of the backend blockchain. 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. func (ec *Client) EstimateGas(ctx context.Context, msg ethereum.CallMsg) (*big.Int, error) { var hex hexutil.Big err := ec.c.CallContext(ctx, &hex, "eth_estimateGas", toCallArg(msg)) if err != nil { return nil, err } return (*big.Int)(&hex), nil }

// SendTransaction injects a signed transaction into the pending pool for execution. // // If the transaction was a contract creation use the TransactionReceipt method to get the // contract address after the transaction has been mined. func (ec *Client) SendTransaction(ctx context.Context, tx *types.Transaction) error { data, err := rlp.EncodeToBytes(tx) if err != nil { return err } return ec.c.CallContext(ctx, nil, "eth_sendRawTransaction", common.ToHex(data)) }

func toCallArg(msg ethereum.CallMsg) interface{} { arg := map[string]interface{}{ "from": msg.From, "to": msg.To, } if len(msg.Data) > 0 { arg["data"] = hexutil.Bytes(msg.Data) } if msg.Value != nil { arg["value"] = (*hexutil.Big)(msg.Value) } if msg.Gas != nil { arg["gas"] = (*hexutil.Big)(msg.Gas) } if msg.GasPrice != nil { arg["gasPrice"] = (*hexutil.Big)(msg.GasPrice) } return arg }