FISCO BCOS 环境接口规范

FISCO BCOS 环境接口（FISCO BCOS Environment Interface，FBEI）规范中包含区块链底层平台FISCO BCOS向 Wasm 虚拟机公开的应用程序接口（Application Programming Interface，API）。FBEI 规范中所有的 API 均由 FISCO BCOS 负责实现，运行于 Wasm 虚拟机中的程序能够直接访问这些 API 以获取区块链的环境及状态。

数据类型

在 FBEI 规范中， API 参数及返回值的数据类型会使用i32、i32ptr及i64三种类型标记，其定义如下：

类型标记定义
i3232位整数，与 Wasm 中i32类型的定义一致
i32ptr32位整数，其存储方式与 Wasm 中i32类型一致，但是用于表示虚拟机中的内存偏移量
i6464位整数，与 Wasm 中i64类型的定义一致

API 列表

setStorage

描述

将键值对数据写入至区块链底层存储中以实现持久化存储。使用时需要先将表示键及值的字节序列存储在虚拟机内存中。

参数

参数名类型描述
keyOffseti32ptr键在虚拟机内存中的存储位置的起始地址
keyLengthi32键的长度
valueOffseti32ptr值在虚拟机内存中的存储位置的起始地址
valueLengthi32值的长度

返回值

无。

注解

调用setStorage时，若提供的valueLength参数为0，则表示从区块链底层存储中删除键所对应的数据。在这种情况下，API的实现将直接跳过值的读取，因此valueOffset参数不用赋予有效值，一般直接置为0即可。

getStorage

描述

根据所提供的键，将区块链底层存储中对应的值读取至虚拟机内存中。使用时需要先将表示键的字节序列存储在虚拟机内存中，并提前分配好存储值的内存区域。

参数

参数名类型描述
keyOffseti32ptr键在虚拟机内存中的存储位置的起始地址
keyLengthi32键的长度
valueOffseti32ptr用于存放值的虚拟机内存起始地址

返回值

类型描述
i32值的长度

getCallData

描述

将当前交易的输入数据拷贝至虚拟机内存中，使用时需要提前分配好存储交易输入数据的内存区域。

参数

参数名类型描述
resultOffseti32ptr用于存放当前交易输入数据的虚拟机内存起始地址

返回值

无。

getCallDataSize

描述

获取当前交易输入数据的长度。

参数

无。

返回值

类型描述
i32当前交易输入数据的长度

getCaller

描述

获取发起合约调用的调用方地址，使用时需要提前分配好存储调用方地址的内存区域。

参数

参数名类型描述
resultOffseti32ptr用于存放调用方地址的虚拟机内存起始地址

返回值

无。

finish

描述

将表示返回值的字节序列传递至宿主环境并结束执行流程，宿主环境会将该其作为交易回执的一部分返回至调用方。

参数

参数名类型描述
dataOffseti32ptr用于存放返回值的虚拟机内存起始地址
dataLengthi32返回值的长度

返回值

无。

revert

描述

将表示异常信息的字节序列抛出至宿主环境，宿主环境会将其作为交易回执的一部分返回至调用者。调用此接口后，交易回执中的状态将会被标记为“已回滚”。

参数

参数名类型描述
dataOffseti32ptr异常信息在虚拟机内存中的存储位置的起始地址
dataLengthi32异常信息的长度

返回值

无。

注解

异常信息需要为人类可读的字符串，以方便快速定位异常原因。

log

描述

创建一条交易日志。可以至多为该日志创建 4 个日志索引。使用时需要先将表示日志数据及其索引的字节序列存储在虚拟机内存中。

参数

参数名类型描述
dataOffseti32ptr日志数据在虚拟机内存中的存储位置的起始地址
dataLengthi32日志数据的长度
topic1i32ptr第 1 个日志索引的虚拟机内存起始地址，没有时置0
topic2i32ptr第 2 个日志索引的虚拟机内存起始地址，没有时置0
topic3i32ptr第 3 个日志索引的虚拟机内存起始地址，没有时置0
topic4i32ptr第 4 个日志索引的虚拟机内存起始地址，没有时置0

返回值

无。

注解

日志索引的长度需要为恰好为32字节。

getTxOrigin

描述

获取调用链中最开始发起合约调用的调用方地址，使用时需要提前分配好存储调用方地址的内存区域。与getCaller接口不同，本接口获取到的调用方地址一定为外部账户地址。

参数

参数名类型描述
resultOffseti32ptr用于存放调用方地址的虚拟机内存起始地址

返回值

无。

getBlockNumber

描述

获取当前块高。

参数

无。

返回值

类型描述
i64当前块高

getBlockTimestamp

描述

获取当前块的时间戳。

参数

无。

返回值

类型描述
i64当前块的时间戳

call

描述

发起外部合约调用，使用时需要先将表示调用参数的字节序列存储在虚拟机内存中。调用此接口后执行流程会陷入阻塞，直至外部合约调用结束或发生异常。

参数

参数名类型描述
addressOffseti32ptr被调用合约地址在虚拟机内存中的存储位置的起始地址
dataOffseti32ptr调用参数在虚拟机内存中的存储位置的起始地址
dataLengthi32调用参数的长度

返回值

类型描述
i32调用状态，0表示成功，否则表示失败

getReturnDataSize

描述

获取外部合约调用的返回值长度，此接口仅能在外部合约调用成功后调用。

参数

无。

类型描述
i32外部合约调用的返回值长度

getReturnData

获取外部合约调用的返回值，使用时需要根据getReturnDataSize的返回结果提前分配好存储返回值内存区域。

参数

参数名类型描述
resultOffseti32ptr用于存放返回值的虚拟机内存起始地址

返回值

无。