mirror of https://github.com/ethereum/go-ethereum
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.pull/2930/head
Felix Lange
8 years ago
parent
8d9141ed9a
commit
46621fd2c3
@ -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 |
||||||
|
} |
||||||
@ -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{}) |
||||||
|
) |
||||||
Loading…
Reference in new issue