FISCO BCOS Wasm 合约接口规范

FISCO BCOS Wasm 合约接口(FISCO BCOS Wasm Contract Interface,FBWCI)规范中包含关于合约文件格式及内容的约定。符合 FBWCI 规范要求合约文件能够在区块链底层平台FISCO BCOS内置的 Wasm 虚拟机中运行。

传输格式

所有的合约件必须以WebAssembly 二进制编码格式保存及传输。

符号导入

合约文件仅能导入在BCOS 环境接口规范中规定的接口,所有的接口都需要从名为bcos的命名空间中导入,且签名必须与 BCOS 环境接口规范中所声明的接口签名保持一致。除bcos命令空间外,还有一个名为debug的特殊命名空间。debug命名空间中所声明的函数的主要用于虚拟机的调试模式,在正式的生产环境中该命名空间不会被启用,详情请参考调试模式

符号导出

合约文件必须恰好导出下列 3 个符号:

符号名 描述
memory 共享线性内存,用于与宿主环境交换数据
deploy 初始化入口,无参数且无返回值,用于完成状态初始化的工作。当合约被初次部署至链上时,宿主环境会主动调用该函数
main 执行入口,无参数且无返回值,用于执行具体的合约逻辑。当有发往该合约的交易时,宿主环境会主动调用该函数。当交易成功执行时,该函数正常退出;否则向宿主环境抛出异常原因并回滚交易

调试模式

调试模式是一种用于调试虚拟机的特殊模式,通过debug命名空间为合约提供了一组额外调试接口。但是在正式的生产环境中,若合约字节码尝试从debug命名空间中导入符号,则会被拒绝部署。debug命名空间中可用的接口如下所示,所有接口均没有返回值:

print32

描述

在区块链底层的日志中输出一个 32 位整数值。

参数

参数名 类型 描述
value i32 32位整数值

print64

描述

在区块链底层的日志中输出一个 64 位整数值。

参数

参数名 类型 描述
value i64 64位整数值

printMem

描述

以可打印字符的形式在区块链底层的日志中输出一段虚拟机内存中的内容。

参数

参数名 类型 描述
offset i32 内存区域的起始地址
len i32 内存区域的长度

printMemHex

以 16 进制字符串的形式在区块链底层的日志中输出一段虚拟机内存中的内容。

参数

参数名 类型 描述
offset i32 内存区域的起始地址
len i32 内存区域的长度

Start function

Start function 会在虚拟机载入合约字节码时自动执行,而此时宿主环境尚无法获得虚拟机提供的共享内存的访问权限,因而可能会导致引发运行时异常,因此 FBWCI 规范规定合约文件中不允许存在 start function。