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三种类型标记，其定义如下：
.. list-table::
:header-rows: 1
* - 类型标记
- 定义
* - i32
- 32位整数，与 Wasm 中i32类型的定义一致
* - i32ptr
- 32位整数，其存储方式与 Wasm 中i32类型一致，但是用于表示虚拟机中的内存偏移量
* - i64
- 64位整数，与 Wasm 中i64类型的定义一致
描述
将键值对数据写入至区块链底层存储中以实现持久化存储。使用时需要先将表示键及值的字节序列存储在虚拟机内存中。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - keyOffset
- i32ptr
- 键在虚拟机内存中的存储位置的起始地址
* - keyLength
- i32
- 键的长度
* - valueOffset
- i32ptr
- 值在虚拟机内存中的存储位置的起始地址
* - valueLength
- i32
- 值的长度
返回值
无。
.. note::
调用setStorage时，若提供的valueLength参数为0，则表示从区块链底层存储中删除键所对应的数据。在这种情况下，API的实现将直接跳过值的读取，因此valueOffset参数不用赋予有效值，一般直接置为0即可。
描述
根据所提供的键，将区块链底层存储中对应的值读取至虚拟机内存中。使用时需要先将表示键的字节序列存储在虚拟机内存中，并提前分配好存储值的内存区域。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - keyOffset
- i32ptr
- 键在虚拟机内存中的存储位置的起始地址
* - keyLength
- i32
- 键的长度
* - valueOffset
- i32ptr
- 用于存放值的虚拟机内存起始地址
返回值
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i32
- 值的长度
描述
将当前交易的输入数据拷贝至虚拟机内存中，使用时需要提前分配好存储交易输入数据的内存区域。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - resultOffset
- i32ptr
- 用于存放当前交易输入数据的虚拟机内存起始地址
返回值
无。
描述
获取当前交易输入数据的长度。
参数
无。
返回值
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i32
- 当前交易输入数据的长度
描述
获取发起合约调用的调用方地址，使用时需要提前分配好存储调用方地址的内存区域。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - resultOffset
- i32ptr
- 用于存放调用方地址的虚拟机内存起始地址
返回值
无。
描述
将表示返回值的字节序列传递至宿主环境并结束执行流程，宿主环境会将该其作为交易回执的一部分返回至调用方。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - dataOffset
- i32ptr
- 用于存放返回值的虚拟机内存起始地址
* - dataLength
- i32
- 返回值的长度
返回值
无。
描述
将表示异常信息的字节序列抛出至宿主环境，宿主环境会将其作为交易回执的一部分返回至调用者。调用此接口后，交易回执中的状态将会被标记为“已回滚”。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - dataOffset
- i32ptr
- 异常信息在虚拟机内存中的存储位置的起始地址
* - dataLength
- i32
- 异常信息的长度
返回值
无。
.. note::
异常信息需要为人类可读的字符串，以方便快速定位异常原因。
描述
创建一条交易日志。可以至多为该日志创建 4 个日志索引。使用时需要先将表示日志数据及其索引的字节序列存储在虚拟机内存中。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - dataOffset
- i32ptr
- 日志数据在虚拟机内存中的存储位置的起始地址
* - dataLength
- i32
- 日志数据的长度
* - topic1
- i32ptr
- 第 1 个日志索引的虚拟机内存起始地址，没有时置0
* - topic2
- i32ptr
- 第 2 个日志索引的虚拟机内存起始地址，没有时置0
* - topic3
- i32ptr
- 第 3 个日志索引的虚拟机内存起始地址，没有时置0
* - topic4
- i32ptr
- 第 4 个日志索引的虚拟机内存起始地址，没有时置0
返回值
无。
.. note::
日志索引的长度需要为恰好为32字节。
描述
获取调用链中最开始发起合约调用的调用方地址，使用时需要提前分配好存储调用方地址的内存区域。与getCaller接口不同，本接口获取到的调用方地址一定为外部账户地址。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - resultOffset
- i32ptr
- 用于存放调用方地址的虚拟机内存起始地址
返回值
无。
描述
获取当前块高。
参数
无。
返回值
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i64
- 当前块高
描述
获取当前块的时间戳。
参数
无。
返回值
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i64
- 当前块的时间戳
描述
发起外部合约调用，使用时需要先将表示调用参数的字节序列存储在虚拟机内存中。调用此接口后执行流程会陷入阻塞，直至外部合约调用结束或发生异常。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - addressOffset
- i32ptr
- 被调用合约地址在虚拟机内存中的存储位置的起始地址
* - dataOffset
- i32ptr
- 调用参数在虚拟机内存中的存储位置的起始地址
* - dataLength
- i32
- 调用参数的长度
返回值
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i32
- 调用状态，0表示成功，否则表示失败
描述
获取外部合约调用的返回值长度，此接口仅能在外部合约调用成功后调用。
参数
无。
.. list-table::
:header-rows: 1
* - 类型
- 描述
* - i32
- 外部合约调用的返回值长度
获取外部合约调用的返回值，使用时需要根据getReturnDataSize的返回结果提前分配好存储返回值内存区域。
参数
.. list-table::
:header-rows: 1
* - 参数名
- 类型
- 描述
* - resultOffset
- i32ptr
- 用于存放返回值的虚拟机内存起始地址
返回值
无。