# RPC 模块

## 1 模块介绍

> RPC，即 Remote Procedure Call（远程过程调用）

- chain33中的rpc模块主要为外部程序提供交易构造及发送，区块、交易以及其他信息查询接口。
- rpc模块同时支持grpc和jsonrpc两种接口，其他进程既可以调用grpc接口，也可以调用jrpc接口，一般地，如果某进程能够访问chain33内部数据结构构造数据，优先采用grpc接口，反之，推荐使用jrpc接口。

## 2 逻辑架构及上下文

> rpc模块引用了”grpc”和”net/rpc”包，在系统初始化时，注册了服务处理server，对所有的rpc调用方法进行注册
>
> rpc模块根据配置文件，绑定相应的端口，在底层，实际是对tcp端口进行监听，一旦收到请求消息，根据消息数据里的方法名，调用之前注册的方法进行响应
>
> rpc模块实例化了一个QueueProtocol，来实现与chain33中其他模块交互，例如实际的区块/交易查询都是通过消息与BlockChain模块交互实现的，关于消息队列可以参考Queue模块介绍

## 3 数据结构

> rpc定义了GrpcServer和JSONRPCServer两个结构，分别为grpc和jrpc服务，从以下结构中可以看出，在chain33内部，仍然是通过Queue来交互的

```

type channelClient struct {
    client.QueueProtocolAPI
    accountdb *account.DB
}
type Chain33 struct {
    cli channelClient
}
type Grpc struct {
    cli channelClient
}
type Grpcserver struct {
    grpc Grpc
    s    *grpc.Server
    l    net.Listener
    //addr string
}
type JSONRPCServer struct {
    jrpc Chain33
    s    *rpc.Server
    l    net.Listener
    //addr string
}
```

- grpc提供的各项接口，通过rpc.proto定义，与一般数据有别的是，这里定义的数据类型为service， 而非message
- jrpc提供的各项接口，在jrpchandler.go中单独定义。

## 4 优化功能

> rpc提供了remoteIP白名单和调用方法白名单/黑名单的功能，在rpc响应请求数据时，能够根据各项白名单/黑名单配置对请求进行过滤

## 5 配置文件

```
[rpc]
jrpcBindAddr="localhost:8801"
grpcBindAddr="localhost:8802"
whitelist=["127.0.0.1"]
jrpcFuncWhitelist=["*"]
grpcFuncWhitelist=["*"]
```

- 配置文件中[rpc]子项用于配置rpc，
- 目前使用的配置主要有jrpc和grpc的绑定地址，在实际环境中需要保证地址及端口正确配置
- whitelist/jrpcFuncWhitelist/grpcFuncWhitelist用于配置各项白/黑名单，无特殊需求时保持默认即可

## 6 jrpc接口列表

> 如上所述，DAPP推荐使用jrpc接口，chain33目前已经支持大量jrpc接口，基本能够满足日常开发的各类需求，由于数据很多，在此列出接口名，具体参数及说明请参照jrpc接口文档

### 6.1 钱包接口

- 上锁 Lock
- 解锁 UnLock
- 设置/修改密码 SetPasswd
- 设置标签 SetLabl
- 创建账户 NewAccount
- 获取账户列表 GetAccounts
- 合并账户余额 MergeBalance
- 设置交易费用 SetTxFee
- 交易 SendToAddress
- 导入私钥 ImportPrivKey
- 获取钱包交易列表 WalletTxList
- 获取Ticket 的数量 GetTicketCount
- 导出私钥 dumpprivkey
- 交易签名 SignRawTx
- 创建绑定挖矿交易 CreateBindMiner
- 获取钱包状态 GetWalletStatus

### 6.2 mempool接口

- 获取 GetMempool

### 6.3 交易接口

- 发送交易 SendTransaction
- 构造交易 CreateTransaction
- 发送签名后的交易 SendRawTransaction
- 构造并发送不收手续费交易CreateNoBalanceTransaction
- 根据哈希查询交易信息 QueryTransaction
- 根据地址获取交易信息 GetTxByAddr
- 根据哈希数组批量获取交易信息 GetTxByHashes
- 根据哈希获取交易的字符串 GetHexTxByHash
- 获取地址相关摘要信息 GetAddrOverview
- 将合约名转化成chain33中的实际地址ConvertExectoAddr
- 构造交易组 CreateRawTxGroup

### 6.4 区块链接口

- 获取版本 Version
- 获取区间区块 GetBlocks
- 获取最新的区块头 GetLastHeader
- 获取区间区块头 GetHeaders
- 获取区块的 hash 值 GetBlockHash
- 获取区块的详细信息 GetBlockOverview
- 获取最新区块序号 GetLastBlockSequence
- 获取区间区块序号 GetBlockSequences
- 获取Hash列表区块 GetBlockByHashes

### 6.5 同步状态接口

- 获取远程节点列表 GetPeerInfo
- 查询节点状态 GetNetInfo
- 查询时间状态 GetTimeStatus
- 查询同步状态 IsSync

### 6.6 钱包SEED

- 生成随机的seed GenSeed
- 保存seed并用密码加密 SaveSeed
- 通过钱包密码获取钱包的seed原文 GetSeed

### 6.7 查询余额

- 查询地址余额 GetBalance
- 查询地址token余额 GetTokenBalance
- 查询地址所有合约地址余额 GetAllExecBalance