合约接口

部署合约

deployContract

部署合约，同步方式调用。

  • 函数原型
  1. public DeployContractResponse deployContract(DeployContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true DeployContractRequest 部署合约的请求
  • 返回字段
返回字段 字段类型 说明
response DeployContractResponse 部署合约的响应
  • 示例
  1. DeployContractRequest request = new DeployContractRequest(acctId, contractId, code,
  2.                                  vmType, parameters, value);
  3. // 请参考错误信息章节，检查返回的数据  
  4. DeployContractResponse response = sdk.getContractService().deployContract(request);

asyncDeployContract

部署合约，异步方式调用。

  • 函数原型
  1. public int asyncDeployContract(DeployContractRequest request, IAsyncCallback callback)
  • 请求参数
参数 必选 类型 说明
request true DeployContractRequest 部署合约的请求
callback true IAsyncCallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result int 发送返回值
  • 示例
  1. DeployContractRequest request = new DeployContractRequest(acctId, contractId, code,
  2.                                  vmType, parameters, value);
  3. //deploy contract
  4. int result = sdk.getContractService().asyncDeployContract(
  5.     request,
  6.     new IAsyncCallback() {
  7.       @Override
  8.       public void onResponse(int errorCode, Response response) {
  9.         // 请参考错误信息章节，检查返回的数据  
  10.         System.out.println("async deploy contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  11.       }
  12. });

DeployContractRequest

部署合约的参数：

参数 类型 说明
acctId Identity 部署合约的账户 ID
contractId Identity 合约 ID
code byte[] 合约代码
vmTypeEnum VMTypeEnum 虚拟机类型，默认使用 evm 虚拟机，后续支持其它虚拟机类型。
parameters Parameters 合约参数
value BigInteger 合约金额

DeployContractResponse

部署合约的返回参数：

参数 类型 说明
transactionReceipt TransactionReceipt 交易收据
blockNumber BigInteger 区块号

调用合约

callContract

调用合约，同步方式调用。

  • 函数原型
  1. public CallContractResponse callContract(CallContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true CallContractRequest 调用合约的请求
  • 返回字段
返回字段 字段类型 说明
result CallContractResponse 调用合约的响应
  • 示例
  1. CallContractRequest request = new CallContractRequest();
  2. // 请参考错误信息章节，检查返回的数据  
  3. CallContractResponse response = sdk.getContractService().callContract(request);

asyncCallContract

调用合约，异步方式调用。

  • 函数原型
  1. public int asyncCallContract(CallContractRequest request, IAsyncCallback callback)
  • 请求参数
参数 必选 类型 说明
request true CallContractRequest 调用合约的请求
callback true IAsyncCallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result int 发送返回值
  • 示例
  1. CallContractRequest request = new CallContractRequest();
  2. int result = sdk.getContractService().asyncCallContract(
  3.     request,
  4.     new IAsyncCallback() {
  5.       @Override
  6.       public void onResponse(int errorCode, Response response) {
  7.         // 请参考错误信息章节，检查返回的数据
  8.         System.out.println("async call contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9.     }
  10. );

CallContractRequest

调用合约的参数：

参数 类型 说明
acctId Identity 提交交易的账户 ID
contractId Identity 合约 ID
parameters Parameters 合约参数
vmTypeEnum VMTypeEnum 虚拟机类型
value BigInteger 合约金额

CallContractResponse

调用合约的返回参数：

参数 类型 说明
transactionReceipt TransactionReceipt 交易收据
blockNumber BigInteger 区块号

升级合约

updateContract

升级合约，同步方式调用。

  • 函数原型
  1. public UpdateContractResponse updateContract(UpdateContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true UpdateContractRequest 升级合约的请求
  • 返回字段
返回字段 字段类型 说明
response UpdateContractResponse 升级合约的响应
  • 示例
  1. UpdateContractRequest request = new UpdateContractRequest(contractId, code, vmTypeEnum);
  2. // 请参考错误信息章节，检查返回的数据  
  3. UpdateContractResponse response = sdk.getContractService().updateContract(request);

asyncUpdateContract

升级合约，异步方式调用。

  • 函数原型
  1. public int asyncUpdateContract(UpdateContractRequest request, IAsyncCallback callback)
  • 请求参数
参数 必选 类型 说明
request true UpdateContractRequest 升级合约的请求
callback true IAsyncCallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result int 发送返回值
  • 示例
  1. UpdateContractRequest request = new UpdateContractRequest(contractId, code, vmTypeEnum);
  2. int result = sdk.getContractService().asyncUpdateContract(
  3.     request,
  4.     new IAsyncCallback() {
  5.         @Override
  6.         public void onResponse(int errorCode, Response response) {
  7.              // 请参考错误信息章节，检查返回的数据 
  8.             System.out.println("async update contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9.         }
  10.     });

UpdateContractRequest

升级合约的参数：

参数 类型 说明
contractId Identity 合约 ID
code byte[] 目标合约的字节码，采用 16 进制表示，无需“0x”作为前缀。
vmTypeEnum VMTypeEnum 虚拟机类型

升级合约时，传入的 bytecode 字节码为 runtime 字节码。如果使用二进制 solc 编译工具，可直接获取 --bin-runtime 参数，即正常 --bin 参数编译的字节码的子集。runtime 字节码也可通过本地执行合约部署操作来获取。

UpdateContractResponse

部署合约的返回参数：

参数 类型 说明
transactionReceipt TransactionReceipt 交易收据
blockNumber BigInteger 区块号

冻结合约

freezeContract

冻结合约，同步方式调用。

  • 函数原型
  1. public FreezeContractResponse freezeContract(FreezeContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true FreezeContractRequest 冻结合约的请求

  • 返回字段
返回字段 字段类型 说明
response FreezeContractResponse 冻结合约的响应

  • 示例
  1. FreezeContractRequest request = new FreezeContractRequest(from, to);
  2. // 请参考错误信息章节，检查返回的数据  
  3. FreezeContractResponse result = sdk.getContractService().freezeContract(request)

asyncFreezeContract

冻结合约，异步方式调用。

  • 函数原型
  1. public int asyncFreezeContract(FreezeContractRequest request,IAsyncCallback callback)

  • 请求参数
参数 必选 类型 说明
request true FreezeContractRequest 冻结合约的请求
callback true IAsyncCallback 回调函数

  • 返回字段
返回字段 字段类型 说明
result int 发送返回值

  • 示例
  1. FreezeContractRequest request = new FreezeContractRequest(from, to);
  2. int result = sdk.getContractService().asyncFreezeContract(
  3.     request
  4.     , new IAsyncCallback() {
  5.         @Override
  6.         public void onResponse(int errorCode, Response response) {
  7.           // 请参考错误信息章节，检查返回的数据
  8.           System.out.println("async freeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9.         }
  10.     });

FreezeContractRequest

冻结合约的参数：

参数 类型 说明
from Identity 冻结合约的操作者 ID
to Identity 待冻结的合约 ID

FreezeContractResponse

冻结合约的返回参数：

参数 类型 说明
transactionReceipt TransactionReceipt 交易收据
blockNumber BigInteger 区块号

解冻合约

unFreezeContract

解除冻结合约，同步方式调用。

  • 函数原型
  1. public UnFreezeContractResponse unFreezeContract(UnFreezeContractRequest request)

  • 请求参数
参数 必选 类型 说明
request true UnFreezeContractRequest 解除冻结合约的请求

  • 返回字段
返回字段 字段类型 说明
response UnFreezeContractResponse 解除冻结合约的响应

  • 示例
  1. UnFreezeContractRequest request = new UnFreezeContractRequest(id, frozenId);
  2. // 请参考错误信息章节，检查返回的数据  
  3. UnFreezeContractResponse response = sdk.getContractService().unFreezeContract(request);

asyncUnFreezeContract

解除冻结合约，异步方式调用。

  • 函数原型
  1. public int asyncUnFreezeContract(UnFreezeContractRequest request,IAsyncCallback callback)

  • 请求参数
参数 必选 类型 说明
request true UnFreezeContractRequest 解除冻结合约的请求
callback true IAsyncCallback 回调函数

  • 返回字段
返回字段 字段类型 说明
result int 发送返回值

  • 示例
  1. UnFreezeContractRequest request = new UnFreezeContractRequest(id, frozenId);
  2. int result = sdk.getContractService().asyncUnFreezeContract(
  3.     request, 
  4.     new IAsyncCallback() {
  5.         @Override
  6.         public void onResponse(int errorCode, Response response) {
  7.           // 请参考错误信息章节，检查返回的数据
  8.           System.out.println("async unFreeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9.         }
  10. });

UnfreezeContractRequest

解冻合约的参数：

参数 类型 说明
from Identity 解冻合约的操作者 ID
to Identity 待解冻的合约 ID

UnFreezeContractResponse

解冻合约的返回参数：

参数 类型 说明
transactionReceipt TransactionReceipt 交易收据
blockNumber BigInteger 区块号

合约参数对象

参数对象用于编码合约方法和参数。

EVM 合约参数对象

  • EVMParameter
函数名称 参数类型 参数说明
setMethodSignature() String 添加函数选择器，即方法与参数列表构成的字符串
getEncodedData() String EVM 参数字节码
addInt() BigInteger 添加静态的 int 类型的数据
addUInt() BigInteger 添加静态的 uint 类型的数据
addBool() boolean 添加静态的 bool 类型的数据
addIdentity() Identity 添加静态的 identity 类型的数据
addString () String 添加动态的 string 类型的数据
addBytes() byte[] 添加动态的 bytes 类型的数据
addBytesN() byte[] 添加静态的 bytes 类型的数据
addIntArray() List<BigInteger> 添加动态的 int 数组类型的数据
addUIntArray() List<BigInteger> 添加动态的 uint 数组类型的数据
addBytesNArray() byte[] value 添加动态的 bytes数组类型的数据
addBooleanArray() List<Boolean> 添加动态的 bool 数组类型的数据

EVM 数据解析

EVMOutput，解析交易收据的 logData 和 output，可参考 EVM 合约编码说明 中的脚本示例。

函数名称 参数类型 参数说明
getInt() BigInteger 获取静态的 int 类型的数据
getUInt() BigInteger 获取静态的 uint 类型的数据
getBool() boolean 获取 bool 类型的数据
getIdentity() Identity 获取 identity 类型的数据
getString () String 获取 string 类型的数据
getBytes() byte[] 获取的 bytes 类型的数据
getBytesN() byte[] 获取 bytes 类型的数据
getIntArray() List<BigInteger> 获取 int 数组类型的数据
getUIntArray() List<BigInteger> 获取 uint 数组类型的数据
getBytesNArray() byte[] value 获取 bytes 数组类型的数据
getBooleanArray() List<Boolean> 获取 bool 数组类型的数据

EVM 合约编码说明

EVM 的参数和返回值编码规则一致，都与 Solidity 合约一样。对于静态类型的变量，直接编码为 32 字节按顺序拼接。对应动态数据类型，则用一个 32 字节偏移量占住位置，所有动态数据类型的真实数据按顺序以 LV 的格式放在后面。其中 L 表示数据的实际长度，L 占用 32 字节；V 为实际数据。

下面通过示例进行详细说明。

  • 要返回的多值结果列表：
类型 值
uint 100
String “abc”
String “0123456789abcdefghijklmnopqrstuvwxyz”
boolean true
Identity “1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b”
  • 编码结果：
  1. 0000000000000000000000000000000000000000000000000000000000000064
  2.   00000000000000000000000000000000000000000000000000000000000000a0
  3.   00000000000000000000000000000000000000000000000000000000000000e0
  4.   0000000000000000000000000000000000000000000000000000000000000001
  5.   e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b
  6.   0000000000000000000000000000000000000000000000000000000000000003
  7.   6162630000000000000000000000000000000000000000000000000000000000
  8.   0000000000000000000000000000000000000000000000000000000000000024
  9.   303132333435363738396162636465666768696a6b6c6d6e6f70717273747576
  10.   7778797a00000000000000000000000000000000000000000000000000000000

  • 具体解析如下：

    • 0000000000000000000000000000000000000000000000000000000000000064 为“100”的编码，uint 类型，定长 32 字节，是大端编码。

    • 00000000000000000000000000000000000000000000000000000000000000a0 “abc”为动态类型，这里的 a0 为其实际数据编码所处偏移位置。因为这里一共 5 个变量，每个变量占用 0x20 个字节，所以第一个动态类型的数据偏移位置就是 5*0x20=0xA0，偏移量的编码规则和 uint 一样。

    • 000000000000000000000000000000000000000000000000000000000000000e0 “0123456789abcdefghijklmopqrstuvwxyz”是动态类型，这里e0为其实际数据编码所处偏移位置。本数据在“abc”之后，由于“abc”的长度和数据各占 0x20 字节，所以本数据就在 0xA0+0x40=0xE0 的位置。

    • 00000000000000000000000000000000000000000000000000000000000000001 “true”的编码，bool型数据占用定长 32 字节，true 最后一个字节为 01，false 最后一个字节为 00。

    • 1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b 是一个”Identity”类型的编码，与源数据完全一致。

    • 00000000000000000000000000000000000000000000000000000000000000003 “abc”的长度，编码规则和uint一样。

    • 61626300000000000000000000000000000000000000000000000000000000000 “abc”的实际数据，String类型的数据占用长度为 32 的整数倍，实际数据靠左编码，后面填充 00。

    • 00000000000000000000000000000000000000000000000000000000000000024 为“0123456789abcdefghijklmnopqrstuvwxyz”的长度为 36=0x24。

    • 303132333435363738396162636465666768696a6b6c6d6e6f70717273747576，7778797a00000000000000000000000000000000000000000000000000000000 为“0123456789abcdefghijklmnopqrstuvwxyz”的实际数据编码。

  1. // 获取返回值解码示例
  2. EVMOutput evmOutput = new EVMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
  3. //按顺序获得返回值
  4.  BigInteger bigInteger = evmOutput.getUint(); // 100
  5.  String string = evmOutput.getString();       // "abc"
  6.  // "0123456789abcdefghijklmnopqrstuvwxyz"
  7.  String string1 = evmOutput.getString(); 
  8.  boolean b = evmOutput.getBoolean();          // true 
  9. // "1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b"
  10. Identity id = evmOutput.getIdentity();

WASM 合约参数对象

  • WASMParameter
函数名称 参数类型 参数说明
setMethodSignature() String 添加函数选择器，方法与参数列表构成的字符串。
getEncodedData() String WASM 参数字节码
addInt8() BigInteger 添加静态的 int_8 类型的数据
addInt16() BigInteger 添加静态的 int_16 类型的数据
addInt32() BigInteger 添加静态的 int_32 类型的数据
addInt64() BigInteger 添加静态的 int_64 类型的数据
addUInt8() BigInteger 添加静态的 uint_8 类型的数据
addUInt16() BigInteger 添加静态的 uint_16 类型的数据
addUInt32() BigInteger 添加静态的 uint_32 类型的数据
addUInt64() BigInteger 添加静态的 uint_64 类型的数据
addBool() boolean 添加静态的 bool 类型的数据
addIdentity() Identity 添加静态的 identity 类型的数据
addString() String 添加动态的 string 类型的数据
addBytes() byte[] 添加动态的 bytes 类型的数据
addInt8Array() List<BigInteger> 添加动态的 int_8 数组类型的数据
addInt16Array() List<BigInteger> 添加动态的 int_16 数组类型的数据
addInt32Array() List<BigInteger> 添加动态的 int_32 数组类型的数据
addInt64Array() List<BigInteger> 添加动态的 int_64 数组类型的数据
addUInt8Array() List<BigInteger> 添加动态的 uint_8 数组类型的数据
addUInt16Array() List<BigInteger> 添加动态的 uint_16 数组类型的数据
addUInt32Array() List<BigInteger> 添加动态的 uint_32 数组类型的数据
addUInt64Array() List<BigInteger> 添加动态的 uint_64 数组类型的数据
addBooleanArray() List<Boolean> 添加动态的 bool 数组类型的数据
addUtfStringArray() List<String> 添加动态 String 数组的数据

WASM 数据解析

WasmOutput，解析交易收据的 logData 和 output，可参考示例。

函数名称 参数类型 参数说明
getInt8() BigInteger 获取静态的 int_8 类型的数据
getInt16() BigInteger 获取静态的 int_16 类型的数据
getInt32() BigInteger 获取静态的 int_32 类型的数据
getInt64() BigInteger 获取静态的 int_64 类型的数据
getUInt8() BigInteger 获取静态的 uint_8 类型的数据
getUInt16() BigInteger 获取静态的 uint_16 类型的数据
getUInt32() BigInteger 获取静态的 uint_32 类型的数据
getUInt64() BigInteger 获取静态的 uint_64 类型的数据
getBool() boolean 获取静态的 bool 类型的数据
getString() String 获取动态的 string 类型的数据
getBytes() byte[] 获取动态的 bytes 类型的数据
getIntAndUintDynamicArray(Class type) <T extends Type> List<BigInteger> 获取 int 或者 uint 的动态数组
getBooleanDynamicArray() List<Boolean> 获取 bool 的动态数组
getStringDynamicArray() List<String> 获取 String 的动态数组

WASM 合约编码说明

C++ 合约中的 pack 函数按照下面的规则进行序列化：
编码表（字节序均为小端）

类型 编码 字节数 编码示例（编码后数据以 16 进制展示） C++ 类型 Java SDK/JS SDK 类型
bool 原码 1 false=>00
true=>01		 bool Bool
uint8 原码 1 123=>7B uint8_t Uint8
uint16 原码 2 12345=>39,30 uint16_t Uint16
uint32 原码 4 1234567890=>D2,02,96,49 uint32_t Uint32
uint64 原码 8 1234567890123ull=>CB,04,FB,71,1F,01,00,00 uint64_t Uint64
int8 补码 1 -123=>85 int8_t Int8
int16 补码 2 -12345=>C7,CF int16_t Int16
int32 补码 4 -1234567890=>2E,FD,69,B6 int32_t Int32
int64 补码 8 -1234567890123=>35,FB,04,8E,E0,FE,FF,FF int64_t Int64
任何指针 编译时报错 T *
string，字符串，每个元素为字符类型 元素字符用 utf-8 编码 先入以 LEB128 编码的 uint32 表达元素个数，然后遍历放入元素。 "hello世界"=>0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C std::string Utf8String
array，数组，元素必为上述内置整型或 string 类型 先入以 LEB128 编码的 uint32 表达元素个数，然后遍历放入元素。 int32 数组:
{10, 20, 30}=>03,0A,00,00,00,14,00,00,00,1E,00,00,00
string数组
{"hello", "smart", "world"}=>03,05,68,65,6C,6C,6F,05,73,6D,61,72,74,05,77,6F,72,6C,64		 std::vector DynamicArray
bytes，字节流，
操作接口和 array 一致		 先入以 LEB128 编码的 uint32 表达元素个数，然后遍历放入元素。 bytes:
{10, 20, 30}=>03,0A,14,1E		 std::vector Bytes
自定义可序列化的类型

C++ 合约中可以使用SERIALIZE宏将自定义数据类型（struct/class）序列化。

  1. SERIALIZE(结构体名, (成员变量1)(成员变量2)...(成员变量n))

示例:

  1. struct Foo {
  2.   int32_t x;
  3.   std::string y;
  4.   bool z;
  5.   int32_t tmp_value; //如果SERIALIZE中不写tmp_value, 则tmp_value不参与序列化
  6.   SERIALIZE(Foo, (y)(x)(z))
  7. };
  9. Foo f;
  10. f.x = -1234567890;
  11. f.y = "hello世界";
  12. f.z = true;

基于 编码表 中对基本类型的编码，Foo 类型的 f 变量的编码相当于按照SERIALIZE指定的顺序依次编码各成员，未声明的成员不参与编码。上述示例中，按 y—>x—>z 进行顺次编码，首尾相接，结果为0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C,2E,FD,69,B6,01。

  1. // 获取返回值解码示例，假设返回了“0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C,2E,FD,69,B6,01”
  2. WASMOutput wasmOutput = new WASMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
  3. String string = wasmOutput.getString();         // "hello世界"
  4. BigInteger integer1 = wasmOutput.getInt32();    // -1234567890
  5. boolean b = wasmOutput.getBoolean();            // true