All Products
Search
Document Center

Blockchain as a Service:Contract interface

Last Updated:May 08, 2020

Deploy a contract

deployContract

This API is called synchronously to deploy a contract.

  • Function prototype
  1. public DeployContractResponse deployContract(DeployContractRequest request)
  • Request parameter
Parameter Required Type Description
request true DeployContractRequest The contract deployment request.
  • Response field
Response field Field type Description
response DeployContractResponse The contract deployment response.
  • Example
  1. DeployContractRequest request = new DeployContractRequest(acctId, contractId, code,
  2. vmType, parameters, value);
  3. // Refer to the error message description document to check the returned data.
  4. DeployContractResponse response = sdk.getContractService().deployContract(request);

asyncDeployContract

This API is called asynchronously to deploy a contract.

  • Function prototype
  1. public int asyncDeployContract(DeployContractRequest request, IAsyncCallback callback)
  • Request parameter
Parameter Required Type Description
request true DeployContractRequest The contract deployment request.
callback true IAsyncCallback The callback function.
  • Response field
Response field Field type Description
result int The return value.
  • Example
  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. // Refer to the error message description document to check the returned data.
  10. System.out.println("async deploy contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  11. }
  12. });

DeployContractRequest

The following table describes parameters for deploying a contract.

Parameter Type Description
acctId Identity The ID of the account for deploying the contract.
contractId Identity The contract ID.
code byte[] The contract code.
vmTypeEnum VMTypeEnum The virtual machine (VM) type. The EVM is used by default. More VM types will be available.
parameters Parameters The contract parameters.
value BigInteger The contract amount.

DeployContractResponse

The following table describes response parameters for deploying a contract.

Parameter Type Description
transactionReceipt TransactionReceipt The transaction receipt.
blockNumber BigInteger The block number.

Call a contract

callContract

This API is called synchronously to call a contract.

  • Function prototype
  1. public CallContractResponse callContract(CallContractRequest request)
  • Request parameter
Parameter Required Type Description
request true CallContractRequest The contract calling request.
  • Response field
Response field Field type Description
result CallContractResponse The contract calling response.
  • Example
  1. CallContractRequest request = new CallContractRequest();
  2. // Refer to the error message description document to check the returned data.
  3. CallContractResponse response = sdk.getContractService().callContract(request);

asyncCallContract

This API is called asynchronously to call a contract.

  • Function prototype
  1. public int asyncCallContract(CallContractRequest request, IAsyncCallback callback)
  • Request parameter
Parameter Required Type Description
request true CallContractRequest The contract calling request.
callback true IAsyncCallback The callback function.
  • Response field
Response field Field type Description
result int The return value.
  • Example
  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. // Refer to the error message description document to check the returned data.
  8. System.out.println("async call contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9. }
  10. );

CallContractRequest

The following table describes parameters for calling a contract.

Parameter Type Description
acctId Identity The ID of the account for submitting a transaction.
contractId Identity The contract ID.
parameters Parameters The contract parameters.
vmTypeEnum VMTypeEnum The VM type.
value BigInteger The contract amount.

CallContractResponse

The following table describes response parameters for calling a contract.

Parameter Type Description
transactionReceipt TransactionReceipt The transaction receipt.
blockNumber BigInteger The block number.

Update a contract

updateContract

This API is called synchronously to update a contract.

  • Function prototype
  1. public UpdateContractResponse updateContract(UpdateContractRequest request)
  • Request parameter
Parameter Required Type Description
request true UpdateContractRequest The contract update request.
  • Response field
Response field Field type Description
response UpdateContractResponse The contract update response.
  • Example
  1. UpdateContractRequest request = new UpdateContractRequest(contractId, code, vmTypeEnum);
  2. // Refer to the error message description document to check the returned data.
  3. UpdateContractResponse response = sdk.getContractService().updateContract(request);

asyncUpdateContract

This API is called asynchronously to update a contract.

  • Function prototype
  1. public int asyncUpdateContract(UpdateContractRequest request, IAsyncCallback callback)
  • Request parameter
Parameter Required Type Description
request true UpdateContractRequest The contract update request.
callback true IAsyncCallback The callback function.
  • Response field
Response field Field type Description
result int The return value.
  • Example
  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. // Refer to the error message description document to check the returned data.
  8. System.out.println("async update contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9. }
  10. });

UpdateContractRequest

The following table describes parameters for updating a contract.

Parameter Type Description
contractId Identity The contract ID.
code byte[] The bytecode of the target contract, which is in hexadecimal format without a “0x” prefix.
vmTypeEnum VMTypeEnum The VM type.

During a contract update, the runtime bytecode is loaded. With a binary solc compiler, you can directly obtain the --bin-runtime parameter or a subset of bytecodes compiled with the normal --bin parameter. You can also obtain the runtime bytecode by locally deploying a contract.

UpdateContractResponse

The following table describes response parameters for updating a contract.

Parameter Type Description
transactionReceipt TransactionReceipt The transaction receipt.
blockNumber BigInteger The block number.

Freeze a contract

freezeContract

This API is called synchronously to freeze a contract.

  • Function prototype
  1. public FreezeContractResponse freezeContract(FreezeContractRequest request)
  • Request parameter
Parameter Required Type Description
request true FreezeContractRequest The request for freezing a contract.

  • Response field
Response field Field type Description
response FreezeContractResponse The response for freezing a contract.

  • Example
  1. FreezeContractRequest request = new FreezeContractRequest(from, to);
  2. // Refer to the error message description document to check the returned data.
  3. FreezeContractResponse result = sdk.getContractService().freezeContract(request)

asyncFreezeContract

This API is called asynchronously to freeze a contract.

  • Function prototype
  1. public int asyncFreezeContract(FreezeContractRequest request,IAsyncCallback callback)

  • Request parameter
Parameter Required Type Description
request true FreezeContractRequest The request for freezing a contract.
callback true IAsyncCallback The callback function.

  • Response field
Response field Field type Description
result int The return value.

  • Example
  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. // Refer to the error message description document to check the returned data.
  8. System.out.println("async freeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9. }
  10. });

FreezeContractRequest

The following table describes parameters for freezing a contract.

Parameter Type Description
from Identity The ID of the operator who freezes the contract.
to Identity The ID of the contract to be frozen.

FreezeContractResponse

The following table describes response parameters for freezing a contract.

Parameter Type Description
transactionReceipt TransactionReceipt The transaction receipt.
blockNumber BigInteger The block number.

Unfreeze a contract

unFreezeContract

This API is called synchronously to unfreeze a contract.

  • Function prototype
  1. public UnFreezeContractResponse unFreezeContract(UnFreezeContractRequest request)

  • Request parameter
Parameter Required Type Description
request true UnFreezeContractRequest The request for unfreezing a contract.

  • Response field
Response field Field type Description
response UnFreezeContractResponse The response for unfreezing a contract.

  • Example
  1. UnFreezeContractRequest request = new UnFreezeContractRequest(id, frozenId);
  2. // Refer to the error message description document to check the returned data.
  3. UnFreezeContractResponse response = sdk.getContractService().unFreezeContract(request);

asyncUnFreezeContract

This API is called asynchronously to unfreeze a contract.

  • Function prototype
  1. public int asyncUnFreezeContract(UnFreezeContractRequest request,IAsyncCallback callback)

  • Request parameter
Parameter Required Type Description
request true UnFreezeContractRequest The request for unfreezing a contract.
callback true IAsyncCallback The callback function.

  • Response field
Response field Field type Description
result int The return value.

  • Example
  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. // Refer to the error message description document to check the returned data.
  8. System.out.println("async unFreeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
  9. }
  10. });

UnfreezeContractRequest

The following table describes parameters for unfreezing a contract.

Parameter Type Description
from Identity The ID of the operator who unfreezes the contract.
to Identity The ID of the contract to be unfrozen.

UnFreezeContractResponse

The following table describes response parameters for unfreezing a contract.

Parameter Type Description
transactionReceipt TransactionReceipt The transaction receipt.
blockNumber BigInteger The block number.

Contract parameter objects

Parameter objects are used to encode contract methods and parameters.

EVM contract parameter objects

  • EVMParameter
Function name Parameter type Description
setMethodSignature() String Adds a function selector or a string composed of a list of methods and parameters.
getEncodedData() String The EVM parameter bytecode.
addInt() BigInteger Adds static int data.
addUInt() BigInteger Adds static uint data.
addBool() boolean Adds static boolean data.
addIdentity() Identity Adds static identity data.
addString () String Adds dynamic string data.
addBytes() byte[] Adds dynamic bytes data.
addBytesN() byte[] Adds static bytes data.
addIntArray() List<BigInteger> Adds dynamic int array data.
addUIntArray() List<BigInteger> Adds dynamic uint array data.
addBytesNArray() byte[] value Adds dynamic bytes array data.
addBooleanArray() List<Boolean> Adds dynamic boolean array data.

EVM data parsing

EVMOutput is used to parse the logData and output of transaction receipts. For more information, see the script example in EVM contract code description.

Function name Parameter type Description
getInt() BigInteger Obtains static int data.
getUInt() BigInteger Obtains static uint data.
getBool() boolean Obtains boolean data.
getIdentity() Identity Obtains identity data.
getString () String Obtains string data.
getBytes() byte[] Obtains bytes data.
getBytesN() byte[] Obtains bytes data.
getIntArray() List<BigInteger> Obtains int array data.
getUIntArray() List<BigInteger> Obtains uint array data.
getBytesNArray() byte[] value Obtains bytes array data.
getBooleanArray() List<Boolean> Obtains boolean array data.

EVM contract code description

EVM parameters and return values comply with the same coding rules as those for the Solidity contract. A static variable is encoded directly into 32 bytes that are spliced in sequence. For corresponding dynamic data, a 32-byte offset is used as a placeholder, and all real dynamic data follows it in LV format in sequence. L indicates the actual data length and occupies 32 bytes. V indicates the actual data.

The following describes an example in detail.

  • Multiple values to be returned
Type Value
uint 100
String “abc”
String “0123456789abcdefghijklmnopqrstuvwxyz”
boolean true
Identity “1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b”
  • Coding result
  1. 0000000000000000000000000000000000000000000000000000000000000064
  2. 00000000000000000000000000000000000000000000000000000000000000a0
  3. 00000000000000000000000000000000000000000000000000000000000000e0
  4. 0000000000000000000000000000000000000000000000000000000000000001
  5. e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b
  6. 0000000000000000000000000000000000000000000000000000000000000003
  7. 6162630000000000000000000000000000000000000000000000000000000000
  8. 0000000000000000000000000000000000000000000000000000000000000024
  9. 303132333435363738396162636465666768696a6b6c6d6e6f70717273747576
  10. 7778797a00000000000000000000000000000000000000000000000000000000
  • Detailed parsing

    • 0000000000000000000000000000000000000000000000000000000000000064: The big-endian code for “100”, which is uint data with a fixed length of 32 bytes.
    • 00000000000000000000000000000000000000000000000000000000000000a0: The code for “abc”, which is dynamic data. a0 indicates the offset position of the actual data code. There are five variables here, each occupying 0x20 bytes. Therefore, the offset position of the first piece of dynamic data is 5*0x20 = 0xA0. The offset complies with the same coding rules as uint data.

    • 000000000000000000000000000000000000000000000000000000000000000e0: The code for “0123456789abcdefghijklmopqrstuvwxyz”, which is dynamic data. e0 indicates the offset position of the actual data code. This piece of data follows “abc”, and its position is 0xA0 + 0x40 = 0xE0 because the length and data of “abc” each occupy 0x20 bytes.

    • 00000000000000000000000000000000000000000000000000000000000000001: The code for “true”, which is boolean data with a fixed length of 32 bytes. The last byte of “true” and “false” is 01 and 00, respectively.

    • 1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b: The code for a piece of identity data, which is completely the same as the source data.

    • 00000000000000000000000000000000000000000000000000000000000000003: The length of “abc”, which complies with the same coding rules as uint data.

    • 61626300000000000000000000000000000000000000000000000000000000000: The actual data of “abc”, which is string data with a length that is an integer multiple of 32. The actual data is encoded on the left, followed by “00”.

    • 00000000000000000000000000000000000000000000000000000000000000024: The length of “0123456789abcdefghijklmnopqrstuvwxyz”, which is 36 (0x24).

    • 303132333435363738396162636465666768696a6b6c6d6e6f70717273747576,7778797a00000000000000000000000000000000000000000000000000000000: The code for the actual data “0123456789abcdefghijklmnopqrstuvwxyz”.

  1. // Obtains a return value decoding example.
  2. EVMOutput evmOutput = new EVMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
  3. // Obtains return values in sequence.
  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 contract parameter objects

  • WASMParameter
Function name Parameter type Description
setMethodSignature() String Adds a function selector or a string composed of a list of methods and parameters.
getEncodedData() String The WASM parameter bytecode.
addInt8() BigInteger Adds static int_8 data.
addInt16() BigInteger Adds static int_16 data.
addInt32() BigInteger Adds static int_32 data.
addInt64() BigInteger Adds static int_64 data.
addUInt8() BigInteger Adds static uint_8 data.
addUInt16() BigInteger Adds static uint_16 data.
addUInt32() BigInteger Adds static uint_32 data.
addUInt64() BigInteger Adds static uint_64 data.
addBool() boolean Adds static boolean data.
addIdentity() Identity Adds static identity data.
addString() String Adds dynamic string data.
addBytes() byte[] Adds dynamic bytes data.
addInt8Array() List<BigInteger> Adds dynamic int_8 array data.
addInt16Array() List<BigInteger> Adds dynamic int_16 array data.
addInt32Array() List<BigInteger> Adds dynamic int_32 array data.
addInt64Array() List<BigInteger> Adds dynamic int_64 array data.
addUInt8Array() List<BigInteger> Adds dynamic uint_8 array data.
addUInt16Array() List<BigInteger> Adds dynamic uint_16 array data.
addUInt32Array() List<BigInteger> Adds dynamic uint_32 array data.
addUInt64Array() List<BigInteger> Adds dynamic uint_64 array data.
addBooleanArray() List<Boolean> Adds dynamic boolean array data.
addUtfStringArray() List<String> Adds dynamic string array data.

WASM data parsing

WasmOutput is used to parse the logData and output of transaction receipts. For more information, see the example.

Function name Parameter type Description
getInt8() BigInteger Obtains static int_8 data.
getInt16() BigInteger Obtains static int_16 data.
getInt32() BigInteger Obtains static int_32 data.
getInt64() BigInteger Obtains static int_64 data.
getUInt8() BigInteger Obtains static uint_8 data.
getUInt16() BigInteger Obtains static uint_16 data.
getUInt32() BigInteger Obtains static uint_32 data.
getUInt64() BigInteger Obtains static uint_64 data.
getBool() boolean Obtains static boolean data.
getString() String Obtains dynamic string data.
getBytes() byte[] Obtains dynamic bytes data.
getIntAndUintDynamicArray(Class type) <T extends Type> List<BigInteger> Obtains a dynamic int or uint array.
getBooleanDynamicArray() List<Boolean> Obtains a dynamic boolean array.
getStringDynamicArray() List<String> Obtains a dynamic string array.

WASM contract code description

The pack function in the C++ contract is serialized based on the following rules.
Code table (little-endian byte orders)

Type Code Number of bytes Code example (hexadecimal) C++ type Java SDK/JavaScript SDK type
bool Original code 1 false=>00
true=>01
bool Bool
uint8 Original code 1 123=>7B uint8_t Uint8
uint16 Original code 2 12345=>39,30 uint16_t Uint16
uint32 Original code 4 1234567890=>D2,02,96,49 uint32_t Uint32
uint64 Original code 8 1234567890123ull=>CB,04,FB,71,1F,01,00,00 uint64_t Uint64
int8 Complementary code 1 -123=>85 int8_t Int8
int16 Complementary code 2 -12345=>C7,CF int16_t Int16
int32 Complementary code 4 -1234567890=>2E,FD,69,B6 int32_t Int32
int64 Complementary code 8 -1234567890123=>35,FB,04,8E,E0,FE,FF,FF int64_t Int64
Any pointer An error is generated during compiling. T *
string: Each element is of a character type. Element characters are encoded in UTF-8 format. An LEB128-encoded uint32 value is loaded to express the number of elements, and the elements are then placed through traversal. "hello world"=>0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C std::string Utf8String
array: The elements must be of the above built-in integer or string type. An LEB128-encoded uint32 value is loaded to express the number of elements, and the elements are then placed through traversal. int32 array:
{10, 20, 30}=>03,0A,00,00,00,14,00,00,00,1E,00,00,00
string array:
{"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:
The operation API is the same as that for an array.
An LEB128-encoded uint32 value is loaded to express the number of elements, and the elements are then placed through traversal. bytes:
{10, 20, 30}=>03,0A,14,1E
std::vector Bytes
Custom serializable types

The SERIALIZE macro in the C++ contract can be used to serialize custom data types (struct/class).

  1. SERIALIZE(structure name, (member variable 1)(member variable 2)...(member variable n))

Example:

  1. struct Foo {
  2. int32_t x;
  3. std::string y;
  4. bool z;
  5. int32_t tmp_value; // If tmp_value is not written in SERIALIZE, tmp_value will not participate in the serialization.
  6. SERIALIZE(Foo, (y)(x)(z))
  7. };
  8. Foo f;
  9. f.x = -1234567890;
  10. f.y = "hello world";
  11. f.z = true;

Based on the code for basic types in the Code table, the code for the f variable of the Foo type can be obtained by encoding all members in the sequence specified by SERIALIZE but not undeclared members. In the preceding example, y, x, and z are encoded in sequence end to end, and the result is 0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C,2E,FD,69,B6,01.

  1. // Obtains a return value decoding example. The following shows that "0B,68,65,6C,6C,6F,E4,B8,96,E7,95,8C,2E,FD,69,B6,01" is returned.
  2. WASMOutput wasmOutput = new WASMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
  3. String string = wasmOutput.getString(); // "hello world"
  4. BigInteger integer1 = wasmOutput.getInt32(); // -1234567890
  5. boolean b = wasmOutput.getBoolean(); // true