FISCO BCOS 数据结构与编码协议交易结构区块结构

爱被打了一巴掌 2022-09-07 14:53 143阅读 0赞

## 一、交易结构及其RLP编码描述 ##

FISCO BCOS的交易结构在原以太坊的交易结构的基础上，有所增减字段。FISCO BCOS 2.0+的交易结构字段如下：

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>type</th> 
   <th>description</th> 
   <th>RLP index RC1</th> 
   <th>RLP index RC2</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>type</td> 
   <td>enum</td> 
   <td><span style="color:#fe2c24;">交易类型</span>，表明该交易是<span style="color:#fe2c24;">创建</span>合约还是<span style="color:#fe2c24;">调用</span>合约交易，初始为空合约</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>nonce</td> 
   <td>u256</td> 
   <td>消息发送方提供的随机数，用于<span style="color:#fe2c24;">唯一标识交易</span></td> 
   <td>0</td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>u256</td> 
   <td><span style="color:#fe2c24;">转账数额</span>，目前去币化的FISCO BCOS不使用该字段</td> 
   <td>5</td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td>receiveAddress</td> 
   <td>h160</td> 
   <td>交易<span style="color:#fe2c24;">接收方地址</span>，type为创建合约时该地址为0x0</td> 
   <td>4</td> 
   <td>4</td> 
  </tr> 
  <tr> 
   <td>gasPrice</td> 
   <td>u256</td> 
   <td>本次交易的<span style="color:#fe2c24;">gas的单价</span>，FISCO BCOS中为固定值300,000,000</td> 
   <td>1</td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>gas</td> 
   <td>u256</td> 
   <td>本次交易允许<span style="color:#fe2c24;">最多消耗的gas数量</span>，FISCO BCOS可配置该值</td> 
   <td>2</td> 
   <td>2</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>vector&lt; byte &gt;</td> 
   <td>与交易相关的数据，或者是创建合约时的初始化参数</td> 
   <td>6</td> 
   <td>6</td> 
  </tr> 
  <tr> 
   <td>chainId</td> 
   <td>u256</td> 
   <td>记录本次交易<span style="color:#fe2c24;">所属的链</span>信息/业务信息</td> 
   <td>-</td> 
   <td>7</td> 
  </tr> 
  <tr> 
   <td>groupId</td> 
   <td>u256</td> 
   <td>记录本次交易<span style="color:#fe2c24;">所属的群组</span></td> 
   <td>-</td> 
   <td>8</td> 
  </tr> 
  <tr> 
   <td>extraData</td> 
   <td>vector&lt; byte &gt;</td> 
   <td><span style="color:#fe2c24;">预留字段</span>，记录交易信息，内部使用<span style="color:#fe2c24;">“#”分割</span>信息</td> 
   <td>-</td> 
   <td>9</td> 
  </tr> 
  <tr> 
   <td>vrs</td> 
   <td>SignatureStruct</td> 
   <td>交易发送方对<span style="color:#fe2c24;">交易7字段RLP编码</span>后的哈希值签名生成的数据</td> 
   <td>7,8,9</td> 
   <td>10,11,12</td> 
  </tr> 
  <tr> 
   <td>hashWith</td> 
   <td>h256</td> 
   <td>交易结构<span style="color:#fe2c24;">所有字段（含签名信息）RLP编码</span>后的哈希值</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>sender</td> 
   <td>h160</td> 
   <td>交易<span style="color:#fe2c24;">发送方地址</span>，基于vrs生成</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>blockLimit</td> 
   <td>u256</td> 
   <td>交易生命周期，该交易<span style="color:#fe2c24;">最晚被处理的块高</span>，FISCO BCOS新增字段</td> 
   <td>3</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td>importTime</td> 
   <td>u256</td> 
   <td>交易<span style="color:#fe2c24;">进入交易池的unix时间戳</span>，FISCO BCOS新增字段</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>rpcCallback</td> 
   <td>function</td> 
   <td>交易<span style="color:#fe2c24;">出块后RPC回调</span>，FISCO BCOS新增字段</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
 </tbody> 
</table>

RC1的hashWith字段（也称交易hash/交易唯一标识）的生成流程如下：

![../../\_images/generate\_hash\_process.png][.._.._images_generate_hash_process.png]

RC2的生成流程也类似，只是在第一步`rlp+hash`的transaction结构体中增加chainId、groupId和extraData三个字段。

## 二、区块结构及其RLP编码描述 ##

FISCO BCOS的区块由以下五部分组成

**rc1版本**

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>description</th> 
   <th>RLP index</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>blockHeader</td> 
   <td>区块头RLP编码</td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>transactions</td> 
   <td>交易列表RLP编码</td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>transactionReceipts</td> 
   <td>交易回执列表RLP编码</td> 
   <td>2</td> 
  </tr> 
  <tr> 
   <td>hash</td> 
   <td>区块头RLP编码后的哈希值</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td>sigList</td> 
   <td>PBFT共识落盘阶段收集到的节点签名信息，Raft不使用</td> 
   <td>4</td> 
  </tr> 
 </tbody> 
</table>

**rc2、rc3、2.0及以上版本**

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>description</th> 
   <th>RLP index</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>blockHeader</td> 
   <td><span style="color:#fe2c24;">区块头</span>RLP编码</td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>transactions</td> 
   <td><span style="color:#fe2c24;">交易列表</span>RLP编码</td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>hash</td> 
   <td><span style="color:#fe2c24;">区块头</span>RLP编码后的<span style="color:#fe2c24;">哈希值</span></td> 
   <td>2</td> 
  </tr> 
  <tr> 
   <td>sigList</td> 
   <td>PBFT共识落盘阶段收集到的<span style="color:#fe2c24;">节点签名信息</span>，Raft不使用</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td>transactionReceipts</td> 
   <td><span style="color:#fe2c24;">交易回执</span>列表RLP编码</td> 
   <td>4</td> 
  </tr> 
 </tbody> 
</table>

FISCO BCOS的区块头中每个字段意义如下：

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>type</th> 
   <th>description</th> 
   <th>RLP index</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>parentHash</td> 
   <td>h256</td> 
   <td><span style="color:#fe2c24;">父区块</span>的哈希值</td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>stateRoot</td> 
   <td>h256</td> 
   <td><span style="color:#fe2c24;">状态树</span>的根哈希值</td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>transactionsRoot</td> 
   <td>h256</td> 
   <td><span style="color:#fe2c24;">交易树</span>的根哈希值</td> 
   <td>2</td> 
  </tr> 
  <tr> 
   <td>receiptsRoot</td> 
   <td>h256</td> 
   <td><span style="color:#fe2c24;">收据树</span>的根哈希值</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td>dbHash</td> 
   <td>h256</td> 
   <td>分布式存储通过计算哈希值来记录<span style="color:#fe2c24;">一区块中写入的数据</span>，FISCO BCOS新增字段</td> 
   <td>4</td> 
  </tr> 
  <tr> 
   <td>logBloom</td> 
   <td>LogBloom</td> 
   <td>交易<span style="color:#fe2c24;">收据日志</span>组成的Bloom过滤器，FISCO BCOS目前尚未使用</td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td>number</td> 
   <td>int64_t</td> 
   <td>本区块的<span style="color:#fe2c24;">块号</span>，块号从0号开始计算</td> 
   <td>6</td> 
  </tr> 
  <tr> 
   <td>gasLimit</td> 
   <td>u256</td> 
   <td>本区块中<span style="color:#fe2c24;">所有交易消耗的Gas上限</span></td> 
   <td>7</td> 
  </tr> 
  <tr> 
   <td>gasUsed</td> 
   <td>u256</td> 
   <td>本区块中<span style="color:#fe2c24;">所有交易使用的Gas之和</span></td> 
   <td>8</td> 
  </tr> 
  <tr> 
   <td>timestamp</td> 
   <td>int64_t</td> 
   <td>打包区块的unix<span style="color:#fe2c24;">时间戳</span></td> 
   <td>9</td> 
  </tr> 
  <tr> 
   <td>extraData</td> 
   <td>vector</td> 
   <td>区块的<span style="color:#fe2c24;">附加数据</span>，FISCO BCOS目前只用于在第0块中记录群组genesis文件信息</td> 
   <td>10</td> 
  </tr> 
  <tr> 
   <td>sealer</td> 
   <td>u256</td> 
   <td><span style="color:#fe2c24;">打包区块的节点</span>在共识节点列表中的<span style="color:#fe2c24;">索引</span>，FISCO BCOS新增字段</td> 
   <td>11</td> 
  </tr> 
  <tr> 
   <td>sealerList</td> 
   <td>vector</td> 
   <td>区块的<span style="color:#fe2c24;">共识节点列表</span>（不含观察节点），FISCO BCOS新增字段</td> 
   <td>12</td> 
  </tr> 
  <tr> 
   <td>hash</td> 
   <td>h256</td> 
   <td>区块头<span style="color:#fe2c24;">前13个字段</span>RLP编码后的<span style="color:#fe2c24;">哈希值</span>，FISCO BCOS新增字段</td> 
   <td>-</td> 
  </tr> 
 </tbody> 
</table>

## 三、交易收据 ##

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>type</th> 
   <th>description</th> 
   <th>RLP index</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>stateRoot</td> 
   <td>h256</td> 
   <td>区块<span style="color:#fe2c24;">状态根</span></td> 
   <td>0</td> 
  </tr> 
  <tr> 
   <td>gasUsed</td> 
   <td>u256</td> 
   <td>交易<span style="color:#fe2c24;">消耗的gas</span></td> 
   <td>1</td> 
  </tr> 
  <tr> 
   <td>contractAddress</td> 
   <td>Address</td> 
   <td>部署<span style="color:#fe2c24;">合约的地址</span></td> 
   <td>2</td> 
  </tr> 
  <tr> 
   <td>bloom</td> 
   <td>h2048</td> 
   <td>布隆滤波器</td> 
   <td>3</td> 
  </tr> 
  <tr> 
   <td>status</td> 
   <td>h256</td> 
   <td>交易<span style="color:#fe2c24;">执行结果的状态码</span></td> 
   <td>4</td> 
  </tr> 
  <tr> 
   <td>output</td> 
   <td>LogBloom</td> 
   <td>交易<span style="color:#fe2c24;">返回值</span></td> 
   <td>5</td> 
  </tr> 
  <tr> 
   <td>logs</td> 
   <td>LogEntry[]</td> 
   <td>event logs</td> 
   <td>6</td> 
  </tr> 
 </tbody> 
</table>

##  ##

## 四、网络传输协议 ##

FISCO BCOS 目前有两类数据包格式，

*  节点与节点间通信的数据包为P2PMessage格式，
 *  节点与SDK间通信的数据包为ChannelMessage格式。

![../../\_images/message\_type.png][.._.._images_message_type.png]

###  ###

### 1. P2PMessage ###

v2.0.0-rc2扩展了**群组ID和模块ID**范围，**最多支持32767个群组**，且新增了**Version**字段来支持其他特性(如网络压缩)，包头大小为16字节，v2.0.0-rc2的网络数据包结构如下：

![../../\_images/network\_packet1.png][.._.._images_network_packet1.png]

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>type</th> 
   <th>description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Length</td> 
   <td>uint32_t</td> 
   <td>数据包长度，含包头和数据</td> 
  </tr> 
  <tr> 
   <td>Version</td> 
   <td>uint16_t</td> 
   <td>记录数据包版本和特性信息，目前最高位0x8000用于记录数据包是否压缩</td> 
  </tr> 
  <tr> 
   <td>groupID (GID)</td> 
   <td>int16_t</td> 
   <td>群组ID，范围1-32767</td> 
  </tr> 
  <tr> 
   <td>ModuleID (MID)</td> 
   <td>uint16_t</td> 
   <td>模块ID，范围1-65535</td> 
  </tr> 
  <tr> 
   <td>PacketType</td> 
   <td>uint16_t</td> 
   <td>数据包类型，同一模块ID下的子协议标识</td> 
  </tr> 
  <tr> 
   <td>Seq</td> 
   <td>uint32_t</td> 
   <td>数据包序列号，每个数据包自增</td> 
  </tr> 
  <tr> 
   <td>Data</td> 
   <td>vector</td> 
   <td>数据本身，长度为lenght-12</td> 
  </tr> 
 </tbody> 
</table>

**补充**

1.  P2PMessage不限制包大小，由上层调用模块（共识/同步/AMOP等)进行包大小管理；
2.  群组ID和模块ID可唯一标识协议ID（protocolID），三者关系为`protocolID = (groupID << sizeof(groupID)*8) | ModuleID`；
3.  数据包通过protocolID所在的16位二进制数值来区分请求包和响应包，大于0为请求包，小于0为相应包。
4.  目前AMOP使用的packetType有`SendTopicSeq = 1，RequestTopics = 2，SendTopics = 3`。

### ChannelMessage v2 ###

<table> 
 <thead> 
  <tr> 
   <th>字段</th> 
   <th>类型</th> 
   <th>长度(Byte)</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>length</td> 
   <td>uint32_t</td> 
   <td>4</td> 
   <td>数据包长度，含包头和数据，大端</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>uint16_t</td> 
   <td>2</td> 
   <td>数据包类型，大端</td> 
  </tr> 
  <tr> 
   <td>seq</td> 
   <td>string</td> 
   <td>32</td> 
   <td>数据包序列号，32字节uuid</td> 
  </tr> 
  <tr> 
   <td>result</td> 
   <td>int32_t</td> 
   <td>4</td> 
   <td>错误码，大端</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>bytes</td> 
   <td>length-42</td> 
   <td>数据包体，字节流</td> 
  </tr> 
 </tbody> 
</table>

AMOP消息包

AMOP消息包继承ChannelMessage包结构，在data字段添加了自定义内容。包括`0x30,0x31,0x35,0x1001`

<table> 
 <thead> 
  <tr> 
   <th></th> 
   <th>长度Byte</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>length</td> 
   <td>1</td> 
   <td>Topic的长度</td> 
  </tr> 
  <tr> 
   <td>topic</td> 
   <td>length</td> 
   <td>topic名</td> 
  </tr> 
 </tbody> 
</table>

# 五、消息包类型 #

数据包类型枚举值及其对应的含义如下：

<table> 
 <thead> 
  <tr> 
   <th>类型</th> 
   <th>包体</th> 
   <th style="width:140px;">描述</th> 
   <th style="width:160px;">解释</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>0x12</td> 
   <td>JSONRPC 2.0格式</td> 
   <td style="width:140px;">RPC接口消息包</td> 
   <td style="width:160px;">SDK-&gt;节点</td> 
  </tr> 
  <tr> 
   <td>0x13</td> 
   <td>json格式心跳包<code>{"heartbeat":"0"}</code></td> 
   <td style="width:140px;">心跳包</td> 
   <td style="width:160px;"> <p>0:SDK-&gt;节点，</p> <p>1:节点-&gt;SDK</p> </td> 
  </tr> 
  <tr> 
   <td>0x14</td> 
   <td> <p>SDK-&gt;节点的包体<code>{"minimumSupport":version,"maximumSupport":version,"clientType":"client type"}</code>,</p> <p>节点-&gt;SDK的包体</p> <p><code>{"protocol":version,"nodeVersion":"fisco-bcos version"</code></p> </td> 
   <td style="width:140px;">握手包，json格式的协议版本协商</td> 
   <td style="width:160px;">SDK&lt;-&gt;节点，双向</td> 
  </tr> 
  <tr> 
   <td>0x30</td> 
   <td>AMOP消息包包体</td> 
   <td style="width:140px;">AMOP请求包</td> 
   <td style="width:160px;">SDK&lt;-&gt;节点，双向</td> 
  </tr> 
  <tr> 
   <td>0x31</td> 
   <td>失败的AMOP消息的包体</td> 
   <td style="width:140px;">AMOP失败响应包</td> 
   <td style="width:160px;">节点-&gt;SDK或节点-&gt;节点</td> 
  </tr> 
  <tr> 
   <td>0x32</td> 
   <td>json数组，存储SDK监听的Topics</td> 
   <td style="width:140px;">上报Topic信息</td> 
   <td style="width:160px;">SDK-&gt;节点</td> 
  </tr> 
  <tr> 
   <td>0x35</td> 
   <td>AMOP消息包包体</td> 
   <td style="width:140px;">AMOP多播消息</td> 
   <td style="width:160px;">节点-&gt;节点</td> 
  </tr> 
  <tr> 
   <td>0x1000</td> 
   <td>json格式的交易上链通知</td> 
   <td style="width:140px;">交易上链回调</td> 
   <td style="width:160px;">节点-&gt;SDK</td> 
  </tr> 
  <tr> 
   <td>0x1001</td> 
   <td>json格式的区块上链通知<code>{"groupID":"groupID","blockNumber":"blockNumber"}</code></td> 
   <td style="width:140px;">区块高度通知</td> 
   <td style="width:160px;">节点-&gt;SDK</td> 
  </tr> 
 </tbody> 
</table>

错误码

<table> 
 <thead> 
  <tr> 
   <th>code</th> 
   <th>message</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>0</td> 
   <td>成功</td> 
  </tr> 
  <tr> 
   <td>100</td> 
   <td>节点不可达</td> 
  </tr> 
  <tr> 
   <td>101</td> 
   <td>SDK不可达</td> 
  </tr> 
  <tr> 
   <td>102</td> 
   <td>超时</td> 
  </tr> 
 </tbody> 
</table>

[https://fisco-bcos-documentation.readthedocs.io/zh\_CN/latest/docs/design/protocol\_description.html][https_fisco-bcos-documentation.readthedocs.io_zh_CN_latest_docs_design_protocol_description.html]

[.._.._images_generate_hash_process.png]: /images/20220829/1b04c168cc0745cf91a5a69ef655142b.png
[.._.._images_message_type.png]: /images/20220829/90c71641ad3c40e4b23a2289f210d145.png
[.._.._images_network_packet1.png]: /images/20220829/a1887945caaf483d9af16dec0c4d72bb.png
[https_fisco-bcos-documentation.readthedocs.io_zh_CN_latest_docs_design_protocol_description.html]: https://fisco-bcos-documentation.readthedocs.io/zh_CN/latest/docs/design/protocol_description.html