文档

合约接口

更新时间:

部署合约

deployContract

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

  • 函数原型
  1. public MychainBaseResult<ReplyTransactionReceipt> deployContract(DeployContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true DeployContractRequest 部署合约的请求
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<ReplyTransactionReceipt> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. MychainParams params = new MychainParams.Builder()
  3. .gas(BigInteger.valueOf(4000000))
  4. .privateKeyList(adminPrivateKeys)
  5. .build();
  6. ContractParameters contractParameters = new ContractParameters();
  7. //deploy contract
  8. MychainBaseResult<ReplyTransactionReceipt> result = sdk.getContractService().deployContract(
  9. DeployContractRequest.build(
  10. adminAccount.getIdentity(),
  11. Utils.getIdentityByName(testContractId),
  12. contractCode,
  13. VMTypeEnum.EVM,
  14. contractParameters,
  15. BigInteger.ZERO,
  16. params
  17. )
  18. );

asyncDeployContract

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

  • 函数原型
  1. public MychainBaseResult<Response> asyncDeployContract(DeployContractRequest request, ICallback callback)
  • 请求参数
参数 必选 类型 说明
request true DeployContractRequest 部署合约的请求
callback true ICallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<Response> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. MychainParams params = new MychainParams.Builder()
  3. .gas(BigInteger.valueOf(4000000))
  4. .privateKeyList(adminPrivateKeys)
  5. .build();
  6. ContractParameters contractParameters = new ContractParameters();
  7. //deploy contract
  8. MychainBaseResult<Response> result = sdk.getContractService().asyncDeployContract(
  9. DeployContractRequest.build(
  10. adminAccount.getIdentity(),
  11. Utils.getIdentityByName(testContractId),
  12. contractCode,
  13. VMTypeEnum.EVM,
  14. contractParameters,
  15. BigInteger.ZERO,
  16. params
  17. ),
  18. (txHash, response) -> {
  19. System.out.println("async deploy contract, txHash:"+txHash+", result: "+ response.getErrorCode());
  20. }
  21. );

DeployContractRequest

下面是部署合约所需要的参数。

参数 类型 说明
acctId Identity 部署合约的账户 ID
contractId Identity 合约 ID
code byte[] 合约代码
vmTypeEnum VMTypeEnum 虚拟机类型,默认使用 EVM 虚拟机,后续将支持其它虚拟机类型。
parameters Parameters 合约参数
value BigInteger 合约金额
mychainParams MychainParams 接口通用扩展参数

调用合约

callContract

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

  • 函数原型
  1. public MychainBaseResult<ReplyTransactionReceipt> callContract(CallContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true CallContractRequest 调用合约的请求
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<ReplyTransactionReceipt> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. MychainParams params = new MychainParams.Builder()
  3. .gas(BigInteger.valueOf(4000000))
  4. .privateKeyList(adminPrivateKeys)
  5. .build();
  6. ContractParameters parameters = new ContractParameters("set(uint256)");
  7. parameters.addUint(new BigInteger("100"));
  8. BigInteger value = new BigInteger("0");
  9. //call contract
  10. MychainBaseResult<ReplyTransactionReceipt> replyTransactionReceipt = sdk.getContractService().callContract(
  11. CallContractRequest.build(
  12. adminAccount.getIdentity(),
  13. Utils.getIdentityByName(testContractId),
  14. parameters,
  15. value,
  16. params
  17. )
  18. );

asyncCallContract

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

  • 函数原型
  1. public MychainBaseResult<Response> asyncCallContract(CallContractRequest request, ICallback callback)
  • 请求参数
参数 必选 类型 说明
request true CallContractRequest 调用合约的请求
callback true ICallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<Response> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. MychainParams params = new MychainParams.Builder()
  3. .gas(BigInteger.valueOf(4000000))
  4. .privateKeyList(adminPrivateKeys)
  5. .build();
  6. ContractParameters parameters = new ContractParameters("set(uint256)");
  7. parameters.addUint(new BigInteger("100"));
  8. // call contract
  9. MychainBaseResult<Response> replyTransactionReceipt = sdk.getContractService().asyncCallContract(
  10. CallContractRequest.build(
  11. adminAccount.getIdentity(),
  12. Utils.getIdentityByName(testContractId),
  13. parameters,
  14. value,
  15. params
  16. ),
  17. (txHash, response) -> {
  18. System.out.println("async call contract, txHash:"+txHash+", result: "+ response.getErrorCode());
  19. }
  20. );

CallContractRequest

调用合约所需要的参数:

参数 类型 说明
acctId Identity 提交交易的账户 ID
contractId Identity 合约 ID
parameters Parameters 合约参数
value BigInteger 合约金额
mychainParams MychainParams 接口通用扩展参数

升级合约

updateContract

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

  • 函数原型
  1. public MychainBaseResult<ReplyTransactionReceipt> updateContract(UpdateContractRequest request)
  • 请求参数
参数 必选 类型 说明
request true UpdateContractRequest 升级合约的请求
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<ReplyTransactionReceipt> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. MychainParams params = new MychainParams.Builder()
  3. .gas(BigInteger.valueOf(40000))
  4. .privateKeyList(adminPrivateKeys)
  5. .build();
  6. ContractParameters contractParameters = new ContractParameters();
  7. //update contract
  8. MychainBaseResult<ReplyTransactionReceipt> result = sdk.getContractService()
  9. .updateContract(
  10. UpdateContractRequest.build(Utils.getIdentityByName(testContractId), newContractCode, VMTypeEnum.EVM, params));

asyncUpdateContract

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

  • 函数原型
  1. public MychainBaseResult<Response> asyncUpdateContract(UpdateContractRequest request, ICallback callback)
  • 请求参数
参数 必选 类型 说明
request true UpdateContractRequest 升级合约的请求
callback true ICallback 回调函数
  • 返回字段
返回字段 字段类型 说明
result MychainBaseResult<Response> MychainBaseResult 持有所有 response 类型。
  • 示例
  1. // build params
  2. // build params
  3. MychainParams params = new MychainParams.Builder()
  4. .gas(BigInteger.valueOf(40000))
  5. .privateKeyList(adminPrivateKeys)
  6. .build();
  7. ContractParameters contractParameters = new ContractParameters();
  8. //update contract
  9. MychainBaseResult<Response> result = sdk.getContractService().asyncUpdateContract(
  10. UpdateContractRequest.build(contractId, newContractCode, VMTypeEnum.EVM, params),
  11. new ICallback() {
  12. @Override
  13. public void onResponse(String txHash, Response response) {
  14. System.out.println("async update contract, txHash:" + txHash + ", result: "
  15. + response.getErrorCode());
  16. assertTrue(response.isSuccess());
  17. assertEquals("0", response.getErrorCode().getErrorCode());
  18. }
  19. });

UpdateContractRequest

升级合约所需要的参数:

参数 类型 说明
contractId Identity 合约 ID
code byte[] 目标合约的字节码,为 16 进制表示,无需“0x”作为前缀
vmTypeEnum VMTypeEnum 虚拟机类型
mychainParams MychainParams 接口通用扩展参数

说明:升级合约时,传入的 bytecode 字节码是 runtime 字节码,使用二进制 solc 编译工具的 —bin-runtime 参数可以直接得到,是正常 —bin 参数编译的字节码的子集。runtime 字节码通过本地执行合约部署操作也可获取到。

合约参数对象

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

EVM 合约参数对象

  • ContractParameters
函数名称 参数类型 参数说明
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 数组类型的数据。
  • 代码示例

    1. //JAVA 示例代码
    2. MychainParams params = new MychainParams();
    3. params.setGas(BigInteger.valueOf(4000000));
    4. params.setPrivateKeyList(adminPrivateKeys);
    5. BigInteger value = new BigInteger("0");
    6. ContractParameters parameters = new ContractParameters("set(uint256)");
    7. parameters.addUint(new BigInteger("100"));
    8. CallContractRequest request = CallContractRequest.build(adminAccount.getIdentity(),
    9. Utils.getIdentityByName(testContractId,env), parameters, value, params, 0, 0,
    10. BaseFixedSizeUnsignedInteger.Fixed64BitUnsignedInteger.valueOf(BigInteger.ONE));
    11. assertNotNull(request);
    12. MychainBaseResult<ReplyTransactionReceipt> replyTransactionReceipt = sdk
    13. .getContractService().callContract(request);

EVM 数据解析

  • ContractReturnValues
函数名称 参数类型 参数说明
ContractReturnValues() String 虚拟机返回的字符串。
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。

  • 303132333435363738396162636465666768696a6b6c6d6e6f707172737475767778797a00000000000000000000000000000000000000000000000000000000 为“0123456789abcdefghijklmnopqrstuvwxyz”的实际数据编码。

  1. // 获取返回值解码示例
  2. ContractReturnValues contractReturnValues = new ContractReturnValues(ByteUtils.toHexString(replyTransactionReceipt.getData().getTransactionReceipt().getOutput()));
  3. //按顺序获得返回值
  4. BigInteger bigInteger = contractReturnValues.getUint(); // 100
  5. String string = contractReturnValues.getString(); // "abc"
  6. // "0123456789abcdefghijklmnopqrstuvwxyz"
  7. String string1 = contractReturnValues.getString();
  8. boolean b = contractReturnValues.getBoolean(); // true
  9. // "1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b"
  10. Identity id = contractReturnValues.getIdentity();
  • 本页导读 (0)
文档反馈