以太坊RPC机制与API实例

上一篇文章介绍了以太坊的基础知识，我们了解了web3.js的调用方式是通过以太坊RPC技术，本篇文章旨在研究如何开发、编译、运行与使用以太坊RPC接口。

关键字：以太坊，RPC，JSON-RPC，client，server，api，web3.js，api实例，Postman

以太坊JSON RPC API

geth命令api相关

之前介绍过这些API都可以在geth console中调用，而在实际应用中，纯正完整的RPC的调用方式，

geth --rpc --rpcapi "db,eth,net,web3,personal"

这个命令可以启动http的rpc服务，当然他们都是geth命令下的，仍旧可以拼接成一个多功能的命令串，可以了解一下上一篇介绍的geth的使用情况。下面介绍一下api相关的选项参数：

API AND CONSOLE OPTIONS:
  --rpc                  启动HTTP-RPC服务（基于HTTP的）
  --rpcaddr value        HTTP-RPC服务器监听地址(default: "localhost")
  --rpcport value        HTTP-RPC服务器监听端口(default: 8545)
  --rpcapi value         指定需要调用的HTTP-RPC API接口，默认只有eth,net,web3
  --ws                   启动WS-RPC服务（基于WebService的）
  --wsaddr value         WS-RPC服务器监听地址(default: "localhost")
  --wsport value         WS-RPC服务器监听端口(default: 8546)
  --wsapi value          指定需要调用的WS-RPC API接口，默认只有eth,net,web3
  --wsorigins value      指定接收websocket请求的来源
  --ipcdisable           禁掉IPC-RPC服务
  --ipcpath              指定IPC socket/pipe文件目录（明确指定路径）
  --rpccorsdomain value  指定一个可以接收请求来源的以逗号间隔的域名列表（浏览器访问的话，要强制指定该选项）
  --jspath loadScript    JavaScript根目录用来加载脚本 (default: ".")
  --exec value           执行JavaScript声明
  --preload value        指定一个可以预加载到控制台的JavaScript文件，其中包含一个以逗号分隔的列表

我们在执行以上启动rpc命令时可以同时指定网络，指定节点，指定端口，指定可接收域名，甚至可以同时打开一个console，这也并不产生冲突。

geth --rpc --rpcaddr <ip> --rpcport <portnumber>

我们可以指定监听地址以及端口，如果不谢rpcaddr和rpcport的话，就是默认的http://localhost:8545。

geth --rpc --rpccorsdomain "http://localhost:3000"

如果你要使用浏览器来访问的话，就要强制指定rpccorsdomain选项，否则的话由于JavaScript调用的同源限制，请求会失败。

admin.startRPC(addr, port)

如果已进入geth console，也可以通过这条命令添加地址和端口。

Postman，HTTP请求api

Postman是一个可以用来测试各种http请求的客户端工具，它还有其他很多用途，但这里只用它来测试上面的HTTP-RPC服务。

看图说话，我们指定了请求地址端口，指定了HTTP POST请求方式，设置好请求为原始Json文本，请求内容为：

{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":67}

是用来请求服务器当前web3客户端版本的，然后点击"Send"，得到请求结果为：

{
    "jsonrpc": "2.0",
    "id": 67,
    "result": "Geth/v0.0.1-stable-930fa051/linux-amd64/go1.9.2"
}

以太坊Go源码调用rpc

我们就以最常用的api：eth_getBalance为例，它的参数要求为：

Parameters
- DATA, 20 Bytes - address to check for balance.
- QUANTITY|TAG - integer block number, or the string "latest", "earliest" or "pending", see the default block parameter

该api要求的参数：

第一个参数为需检查余额的地址
第二个参数为整数区块号，或者是字符串“latest","earliest"以及"pending"指代某个特殊的区块。

在go-ethereum项目中查找到使用位置ethclient/ethclient.go：

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
}

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
}

结合上面的RPC API和下面的go源码的调用，可以看到在go语言中的调用方式：要使用客户端指针类型变量调用到上下文Call的方法，传入第一个参数为上下文实例，第二个参数为一个hexutil.Big类型的结果接收变量的指针，第三个参数为调用的rpc的api接口名称，第四个和第五个为该api的参数，如上所述。

跟踪到ec.c.CallContext，CallContext方法是ec.c对象的。

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

可以看到ethclient/ethclient.go文件中将原rpc/client.go的Client结构体进行了一层包裹，这样就可以区分出来属于ethclient的方法和底层rpc/client的方法。下面贴出原始的rpc.client的结构体定义：

// Client represents a connection to an RPC server.
type Client struct {
    idCounter   uint32
    connectFunc func(ctx context.Context) (net.Conn, error)
    isHTTP      bool

    // writeConn is only safe to access outside dispatch, with the
    // write lock held. The write lock is taken by sending on
    // requestOp and released by sending on sendDone.
    writeConn net.Conn

    // for dispatch
    close       chan struct{}
    didQuit     chan struct{}                  // closed when client quits
    reconnected chan net.Conn                  // where write/reconnect sends the new connection
    readErr     chan error                     // errors from read
    readResp    chan []*jsonrpcMessage         // valid messages from read
    requestOp   chan *requestOp                // for registering response IDs
    sendDone    chan error                     // signals write completion, releases write lock
    respWait    map[string]*requestOp          // active requests
    subs        map[string]*ClientSubscription // active subscriptions
}

ethclient经过包裹以后，可以使用本地Client变量调用rpc.client的指针变量c，从而调用其CallContext方法：

func (c *Client) CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error {
    msg, err := c.newMessage(method, args...) // 看来CallContext还不是终点，TODO:进到newMessage方法内再看看。
    // 结果处理
    if err != nil {
        return err
    }
    // requestOp又一个结构体，封装响应参数的，包括原始请求消息，响应信息jsonrpcMessage，jsonrpcMessage也是一个结构体，封装了响应消息标准内容结构，包括版本，ID，方法，参数，错误，返回值，其中RawMessage在go源码位置json/stream.go又是一个自定义类型，属于go本身封装好的，类型是字节数组[]byte，也有自己的各种功能的方法。
    op := &requestOp{ids: []json.RawMessage{msg.ID}, resp: make(chan *jsonrpcMessage, 1)}

    // 通过rpc不同的渠道发送响应消息：这些渠道在上面命令部分已经介绍过，有HTTP，WebService等。
    if c.isHTTP {
        err = c.sendHTTP(ctx, op, msg)
    } else {
        err = c.send(ctx, op, msg)
    }
    if err != nil {
        return err
    }

    // TODO:对wait方法的研究
    // 对wait方法返回结果的处理
    switch resp, err := op.wait(ctx); {
    case err != nil:
        return err
    case resp.Error != nil:
        return resp.Error
    case len(resp.Result) == 0:
        return ErrNoResult
    default:
        return json.Unmarshal(resp.Result, &result)// 顺利将结果数据编出
    }
}

先看wait方法，它仍旧在rpc/client.go中：

func (op *requestOp) wait(ctx context.Context) (*jsonrpcMessage, error) {
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    case resp := <-op.resp:
        return resp, op.err
    }
}

select的使用请参考这里。继续正题，进入ctx.Done()，Done属于Go源码context/context.go:

// See https://blog.golang.org/pipelines for more examples of how to use
// a Done channel for cancelation.
Done() <-chan struct{}

想知道Done()咋回事，请转到我写的另一篇博文Go并发模式：管道与取消，那里仔细分析了这一部分内容。

从上面的源码分析我感觉go语言就是一个网状结构，从一个结构体跳进另一个结构体，它们之间谁也不属于谁，谁调用了谁就可以使用，没有显式继承extends和显式实现implements，go就是不断的封装结构体，然后增加该结构体的方法，有时候你甚至都忘记了自己程序的结构体和Go源码封装的结构体之间的界限。这就类似于面向对象分析的类，定义一个类，定义它的成员属性，写它的成员方法。

web3与rpc的关系

这里再多啰嗦一句，重申一下web3和rpc的关系：

To make your app work on Ethereum, you can use the web3 object provided by the web3.js library. Under the hood it communicates to a local node through RPC calls. web3.js works with any Ethereum node, which exposes an RPC layer.

翻译过来就是为了让你的api工作在以太坊，你可以使用由web3.js库提供的web3对象。底层通过RPC调用本地节点进行通信。web3.js可以与以太坊任何一个节点通信，这一层就是暴露出来的RPC层。

开发自己的api

设定一个小需求：就是将余额数值乘以指定乘数，这个乘数是由另一个接口的参数来指定的。

在ethapi中加入

var rateFlag uint64 = 1
// Start forking command.
// Rate is the fork coin's exchange rate.
func (s *PublicBlockChainAPI) Forking(ctx context.Context, rate uint64) (uint64) {
    // attempt: store the rate info in context.
    // context.WithValue(ctx, "rate", rate)
    rateFlag = rate
    rate = rate + 1
    return rate
}

然后在ethclient中加入

// Forking tool's client for the Ethereum RPC API
func (ec *Client) ForkingAt(ctx context.Context, account common.Address, rate uint64)(uint64, error){
    var result hexutil.Uint64
    err := ec.c.CallContext(ctx, &result, "eth_forking", account, rate)
    return uint64(result), err
}

保存，make geth编译，然后在节点目录下启动

geth --testnet --rpc console --datadir node0

然后进入到Postman中测试，可以看到

乘数已经改为3（输出4是为了测试，实际上已在局部变量rateFlag保存了乘数3）

然后我们再发送请求余额测试，

可以看到返回值为一串16进制数，通过转换结果为:417093750000000000000，我们原始余额为:139031250000000000000，正好三倍。

rpc客户端

我们上面已经在rpc服务端对api进行了增加，而客户端调用采用的是Postman发送Post请求。而rpc客户端在以太坊实际上有两种：一个是刚才我们实验的，在网页中调用JSON-RPC；另一种则是geth console的形式，而关于这种形式，我还没真正搞清楚它部署的流程，只是看到了在源代码根目录下build/_workspace会在每一次make geth被copy进去所有的源码作为编译后环境，而我修改了源码文件，_workspace下文件，均未生效，可能还存在一层运行环境，我并没有修改到。但这无所谓了，因为实际应用中，我们很少去该console的内容，直接修改web3.js引入到网页即可。下面介绍一下配合上面自己的api，如何修改web3.js文件：

上面讲过了web3.js的结构，是一个node.js的module结构，因此我们先决定将这个api放到eth对象下，检查eth对应的id为38，找到对象体，在methods中增加对应api调用操作，

var forking = new Method({
    name: 'forking',
    call: 'eth_forking',
    params: 1,
    inputFormatter: [null],
    outputFormatter: formatters.outputBigNumberFormatter
});

然后在对象体返回值部分将我们新构建的method添加进去，

return [
    forking,
    ...

改好以后，我们将该文件引用到页面中去，即可通过web3.eth.forking(3)进行调用了。

总结

本文介绍了rpc的概念，rpc的流行框架，以太坊使用的rpc框架为JSON-RPC。接着描述了如何启动JSON-RPC服务端，然后使用Postman来请求JSON-RPC服务端api。通过这一流程，我们仔细分析并跟踪了源码中的实现，抽丝剥茧，从最外层的JSON-RPC的调用规范到源码中外层封装的引用，到内部具体实现，期间对各种自定义结构体进行了跟踪研究，直到Go源码库中的结构体，研究了服务端从接收客户端请求到发送响应的过程。最后我们仔细研究了web3.js文件的结构并且做了一个小实验，从服务端到客户端模仿者增加了一个自定义的api。希望本文对您有所帮助。