ethclient: add initial implementation of the typed RPC client

ethclient implements the proposed Ethereum Go API. There are no tests at the moment, a suite that excercises all implementations of the API will be added later.
8 years ago · 46621fd2c3
parent 8d9141ed9a
commit 46621fd2c3
2 changed files with 399 additions and 0 deletions
--- a/ethclient/ethclient.go
+++ b/ethclient/ethclient.go
@ -0,0 +1,382 @@
+// Copyright 2016 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+// Package ethclient provides a client for the Ethereum RPC API.
+package ethclient
+
+import (
+	"encoding/json"
+	"fmt"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/core/vm"
+	"github.com/ethereum/go-ethereum/rlp"
+	"github.com/ethereum/go-ethereum/rpc"
+	"golang.org/x/net/context"
+)
+
+// 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
+	}
+	// 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, fmt.Sprintf("%#x", 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
+			}
+		}
+	}
+	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)
+	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)
+	return head, err
+}
+
+// TransactionByHash returns the transaction with the given hash.
+func (ec *Client) TransactionByHash(ctx context.Context, hash common.Hash) (*types.Transaction, error) {
+	var tx *types.Transaction
+	err := ec.c.CallContext(ctx, &tx, "eth_getTransactionByHash", hash, false)
+	if err == nil {
+		if _, r, _ := tx.SignatureValues(); r == nil {
+			return nil, fmt.Errorf("server returned transaction without signature")
+		}
+	}
+	return tx, err
+}
+
+// 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 rpc.HexNumber
+	err := ec.c.CallContext(ctx, &num, "eth_getBlockTransactionCountByHash", blockHash)
+	return num.Uint(), 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, index)
+	if err == nil {
+		if _, r, _ := tx.SignatureValues(); 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 && r != nil && 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 fmt.Sprintf("%#x", number)
+}
+
+// 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, "newBlocks", 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 rpc.HexNumber
+	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 rpc.HexBytes
+	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 rpc.HexBytes
+	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 rpc.HexNumber
+	err := ec.c.CallContext(ctx, &result, "eth_getTransactionCount", account, toBlockNumArg(blockNumber))
+	return result.Uint64(), err
+}
+
+// Filters
+
+// FilterLogs executes a filter query.
+func (ec *Client) FilterLogs(ctx context.Context, q ethereum.FilterQuery) ([]vm.Log, error) {
+	var result []vm.Log
+	err := ec.c.CallContext(ctx, &result, "eth_getFilterLogs", 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<- vm.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),
+		"endBlock":  toBlockNumArg(q.ToBlock),
+		"addresses": 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 rpc.HexNumber
+	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 rpc.HexBytes
+	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 rpc.HexBytes
+	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 rpc.HexNumber
+	err := ec.c.CallContext(ctx, &result, "eth_getTransactionCount", account, "pending")
+	return result.Uint64(), err
+}
+
+// PendingTransactionCount returns the total number of transactions in the pending state.
+func (ec *Client) PendingTransactionCount(ctx context.Context) (uint, error) {
+	var num rpc.HexNumber
+	err := ec.c.CallContext(ctx, &num, "eth_getBlockTransactionCountByNumber", "pending")
+	return num.Uint(), 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 string
+	err := ec.c.CallContext(ctx, &hex, "eth_call", toCallArg(msg), toBlockNumArg(blockNumber))
+	if err != nil {
+		return nil, err
+	}
+	return common.FromHex(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 string
+	err := ec.c.CallContext(ctx, &hex, "eth_call", toCallArg(msg), "pending")
+	if err != nil {
+		return nil, err
+	}
+	return common.FromHex(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 rpc.HexNumber
+	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 rpc.HexNumber
+	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"] = fmt.Sprintf("%#x", msg.Data)
+	}
+	if msg.Value != nil {
+		arg["value"] = fmt.Sprintf("%#x", msg.Value)
+	}
+	if msg.Gas != nil {
+		arg["gas"] = fmt.Sprintf("%#x", msg.Gas)
+	}
+	if msg.GasPrice != nil {
+		arg["gasPrice"] = fmt.Sprintf("%#x", msg.GasPrice)
+	}
+	return arg
+}
--- a/ethclient/ethclient_test.go
+++ b/ethclient/ethclient_test.go
@ -0,0 +1,17 @@
+package ethclient
+
+import "github.com/ethereum/go-ethereum"
+
+// Verify that Client implements the ethereum interfaces.
+var (
+	_ = ethereum.ChainReader(&Client{})
+	_ = ethereum.ChainStateReader(&Client{})
+	_ = ethereum.ChainHeadEventer(&Client{})
+	_ = ethereum.ContractCaller(&Client{})
+	_ = ethereum.GasEstimator(&Client{})
+	_ = ethereum.GasPricer(&Client{})
+	_ = ethereum.LogFilterer(&Client{})
+	_ = ethereum.PendingStateReader(&Client{})
+	// _ = ethereum.PendingStateEventer(&Client{})
+	_ = ethereum.PendingContractCaller(&Client{})
+)