数据结构与编码协议

交易结构及其RLP编码描述

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

nametypedescriptionRLP index RC1RLP index RC2
typeenum交易类型,表明该交易是创建合约还是调用合约交易,初始为空合约--
nonceu256消息发送方提供的随机数,用于唯一标识交易00
valueu256转账数额,目前去币化的FISCO BCOS不使用该字段55
receiveAddressh160交易接收方地址,type为创建合约时该地址为0x044
gasPriceu256本次交易的gas的单价,FISCO BCOS中为固定值30000000011
gasu256本次交易允许最多消耗的gas数量,FISCO BCOS可配置该值22
datavector< byte >与交易相关的数据,或者是创建合约时的初始化参数66
chainIdu256记录本次交易所属的链信息/业务信息-7
groupIdu256记录本次交易所属的群组-8
extraDatavector< byte >预留字段,记录交易信息,内部使用“#”分割信息-9
vrsSignatureStruct交易发送方对交易7字段RLP编码后的哈希值签名生成的数据7,8,910,11,12
hashWithh256交易结构所有字段(含签名信息)RLP编码后的哈希值--
senderh160交易发送方地址,基于vrs生成--
blockLimitu256交易生命周期,该交易最晚被处理的块高,FISCO BCOS新增字段33
importTimeu256交易进入交易池的unix时间戳,FISCO BCOS新增字段--
rpcCallbackfunction交易出块后RPC回调,FISCO BCOS新增字段--

RC1的hashWith字段(也称交易hash/交易唯一标识)的生成流程如下:

../../_images/generate_hash_process.png

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

区块结构及其RLP编码描述

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

rc1版本

namedescriptionRLP index
blockHeader区块头RLP编码0
transactions交易列表RLP编码1
transactionReceipts交易回执列表RLP编码2
hash区块头RLP编码后的哈希值3
sigListPBFT共识落盘阶段收集到的节点签名信息,Raft不使用4

rc2、rc3、2.0及以上版本

namedescriptionRLP index
blockHeader区块头RLP编码0
transactions交易列表RLP编码1
hash区块头RLP编码后的哈希值2
sigListPBFT共识落盘阶段收集到的节点签名信息,Raft不使用3
transactionReceipts交易回执列表RLP编码4

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

nametypedescriptionRLP index
parentHashh256父区块的哈希值0
stateRooth256状态树的根哈希值1
transactionsRooth256交易树的根哈希值2
receiptsRooth256收据树的根哈希值3
dbHashh256分布式存储通过计算哈希值来记录一区块中写入的数据,FISCO BCOS新增字段4
logBloomLogBloom交易收据日志组成的Bloom过滤器,FISCO BCOS目前尚未使用5
numberint64_t本区块的块号,块号从0号开始计算6
gasLimitu256本区块中所有交易消耗的Gas上限7
gasUsedu256本区块中所有交易使用的Gas之和8
timestampint64_t打包区块的unix时间戳9
extraDatavector区块的附加数据,FISCO BCOS目前只用于在第0块中记录群组genesis文件信息10
sealeru256打包区块的节点在共识节点列表中的索引,FISCO BCOS新增字段11
sealerListvector区块的共识节点列表(不含观察节点),FISCO BCOS新增字段12
hashh256区块头前13个字段RLP编码后的哈希值,FISCO BCOS新增字段-

交易收据

nametypedescriptionRLP index
stateRooth256区块状态根0
gasUsedu256交易消耗的gas1
contractAddressAddress部署合约的地址2
bloomh2048布隆滤波器3
statush256交易执行结果的状态码4
outputLogBloom交易返回值5
logsLogEntry[]event logs6

网络传输协议

FISCO BCOS 目前有两类数据包格式,节点与节点间通信的数据包为P2PMessage格式,节点与SDK间通信的数据包为ChannelMessage格式。

../../_images/message_type.png

P2PMessage

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

../../_images/network_packet1.png

nametypedescription
Lengthuint32_t数据包长度,含包头和数据
Versionuint16_t记录数据包版本和特性信息,目前最高位0x8000用于记录数据包是否压缩
groupID (GID)int16_t群组ID,范围1-32767
ModuleID (MID)uint16_t模块ID,范围1-65535
PacketTypeuint16_t数据包类型,同一模块ID下的子协议标识
Sequint32_t数据包序列号,每个数据包自增
Datavector数据本身,长度为lenght-12

v2.0.0-rc2以前的P2PMessage定义请参考这里

补充

  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

ChannelMessage v1 请参考这里

字段类型长度(Byte)描述
lengthuint32_t4数据包长度,含包头和数据,大端
typeuint16_t2数据包类型,大端
seqstring32数据包序列号,32字节uuid
resultint32_t4错误码,大端
databyteslength-42数据包体,字节流

AMOP消息包

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

长度Byte说明
length1Topic的长度
topiclengthtopic名

消息包类型

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

类型包体描述解释
0x12JSONRPC 2.0格式RPC接口消息包SDK->节点
0x13json格式心跳包{“heartbeat”:”0”}心跳包0:SDK->节点,1:节点->SDK
0x14SDK->节点的包体{“minimumSupport”:version,”maximumSupport”:version,”clientType”:”client type”},节点->SDK的包体{“protocol”:version,”nodeVersion”:”fisco-bcos version”握手包,json格式的协议版本协商SDK<->节点,双向
0x30AMOP消息包包体AMOP请求包SDK<->节点,双向
0x31失败的AMOP消息的包体AMOP失败响应包节点->SDK或节点->节点
0x32json数组,存储SDK监听的Topics上报Topic信息SDK->节点
0x35AMOP消息包包体AMOP多播消息节点->节点
0x1000json格式的交易上链通知交易上链回调节点->SDK
0x1001json格式的区块上链通知{“groupID”:”groupID”,”blockNumber”:”blockNumber”}区块高度通知节点->SDK

错误码

codemessage
0成功
100节点不可达
101SDK不可达
102超时