Deploy a contract
deployContract
This API is called synchronously to deploy a contract.
public DeployContractResponse deployContract(DeployContractRequest request)
Parameter |
Required |
Type |
Description |
request |
true |
DeployContractRequest |
The contract deployment request. |
Response field |
Field type |
Description |
response |
DeployContractResponse |
The contract deployment response. |
DeployContractRequest request = new DeployContractRequest(acctId, contractId, code,
vmType, parameters, value);
// Refer to the error message description document to check the returned data.
DeployContractResponse response = sdk.getContractService().deployContract(request);
asyncDeployContract
This API is called asynchronously to deploy a contract.
public int asyncDeployContract(DeployContractRequest request, IAsyncCallback callback)
Parameter |
Required |
Type |
Description |
request |
true |
DeployContractRequest |
The contract deployment request. |
callback |
true |
IAsyncCallback |
The callback function. |
Response field |
Field type |
Description |
result |
int |
The return value. |
DeployContractRequest request = new DeployContractRequest(acctId, contractId, code,
vmType, parameters, value);
//deploy contract
int result = sdk.getContractService().asyncDeployContract(
request,
new IAsyncCallback() {
@Override
public void onResponse(int errorCode, Response response) {
// Refer to the error message description document to check the returned data.
System.out.println("async deploy contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
}
});
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.
public CallContractResponse callContract(CallContractRequest request)
Parameter |
Required |
Type |
Description |
request |
true |
CallContractRequest |
The contract calling request. |
Response field |
Field type |
Description |
result |
CallContractResponse |
The contract calling response. |
CallContractRequest request = new CallContractRequest();
// Refer to the error message description document to check the returned data.
CallContractResponse response = sdk.getContractService().callContract(request);
asyncCallContract
This API is called asynchronously to call a contract.
public int asyncCallContract(CallContractRequest request, IAsyncCallback callback)
Parameter |
Required |
Type |
Description |
request |
true |
CallContractRequest |
The contract calling request. |
callback |
true |
IAsyncCallback |
The callback function. |
Response field |
Field type |
Description |
result |
int |
The return value. |
CallContractRequest request = new CallContractRequest();
int result = sdk.getContractService().asyncCallContract(
request,
new IAsyncCallback() {
@Override
public void onResponse(int errorCode, Response response) {
// Refer to the error message description document to check the returned data.
System.out.println("async call contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
}
);
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.
public UpdateContractResponse updateContract(UpdateContractRequest request)
Parameter |
Required |
Type |
Description |
request |
true |
UpdateContractRequest |
The contract update request. |
Response field |
Field type |
Description |
response |
UpdateContractResponse |
The contract update response. |
UpdateContractRequest request = new UpdateContractRequest(contractId, code, vmTypeEnum);
// Refer to the error message description document to check the returned data.
UpdateContractResponse response = sdk.getContractService().updateContract(request);
asyncUpdateContract
This API is called asynchronously to update a contract.
public int asyncUpdateContract(UpdateContractRequest request, IAsyncCallback callback)
Parameter |
Required |
Type |
Description |
request |
true |
UpdateContractRequest |
The contract update request. |
callback |
true |
IAsyncCallback |
The callback function. |
Response field |
Field type |
Description |
result |
int |
The return value. |
UpdateContractRequest request = new UpdateContractRequest(contractId, code, vmTypeEnum);
int result = sdk.getContractService().asyncUpdateContract(
request,
new IAsyncCallback() {
@Override
public void onResponse(int errorCode, Response response) {
// Refer to the error message description document to check the returned data.
System.out.println("async update contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
}
});
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.
public FreezeContractResponse freezeContract(FreezeContractRequest request)
Parameter |
Required |
Type |
Description |
request |
true |
FreezeContractRequest |
The request for freezing a contract. |
Response field |
Field type |
Description |
response |
FreezeContractResponse |
The response for freezing a contract. |
FreezeContractRequest request = new FreezeContractRequest(from, to);
// Refer to the error message description document to check the returned data.
FreezeContractResponse result = sdk.getContractService().freezeContract(request)
asyncFreezeContract
This API is called asynchronously to freeze a contract.
public int asyncFreezeContract(FreezeContractRequest request,IAsyncCallback callback)
Parameter |
Required |
Type |
Description |
request |
true |
FreezeContractRequest |
The request for freezing a contract. |
callback |
true |
IAsyncCallback |
The callback function. |
Response field |
Field type |
Description |
result |
int |
The return value. |
FreezeContractRequest request = new FreezeContractRequest(from, to);
int result = sdk.getContractService().asyncFreezeContract(
request
, new IAsyncCallback() {
@Override
public void onResponse(int errorCode, Response response) {
// Refer to the error message description document to check the returned data.
System.out.println("async freeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
}
});
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.
public UnFreezeContractResponse unFreezeContract(UnFreezeContractRequest request)
Parameter |
Required |
Type |
Description |
request |
true |
UnFreezeContractRequest |
The request for unfreezing a contract. |
Response field |
Field type |
Description |
response |
UnFreezeContractResponse |
The response for unfreezing a contract. |
UnFreezeContractRequest request = new UnFreezeContractRequest(id, frozenId);
// Refer to the error message description document to check the returned data.
UnFreezeContractResponse response = sdk.getContractService().unFreezeContract(request);
asyncUnFreezeContract
This API is called asynchronously to unfreeze a contract.
public int asyncUnFreezeContract(UnFreezeContractRequest request,IAsyncCallback callback)
Parameter |
Required |
Type |
Description |
request |
true |
UnFreezeContractRequest |
The request for unfreezing a contract. |
callback |
true |
IAsyncCallback |
The callback function. |
Response field |
Field type |
Description |
result |
int |
The return value. |
UnFreezeContractRequest request = new UnFreezeContractRequest(id, frozenId);
int result = sdk.getContractService().asyncUnFreezeContract(
request,
new IAsyncCallback() {
@Override
public void onResponse(int errorCode, Response response) {
// Refer to the error message description document to check the returned data.
System.out.println("async unFreeze contract, errorCode:" + errorCode + ", response: " + response.getErrorCode());
}
});
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
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” |
0000000000000000000000000000000000000000000000000000000000000064
00000000000000000000000000000000000000000000000000000000000000a0
00000000000000000000000000000000000000000000000000000000000000e0
0000000000000000000000000000000000000000000000000000000000000001
e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b
0000000000000000000000000000000000000000000000000000000000000003
6162630000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000024
303132333435363738396162636465666768696a6b6c6d6e6f70717273747576
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”.
// Obtains a return value decoding example.
EVMOutput evmOutput = new EVMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
// Obtains return values in sequence.
BigInteger bigInteger = evmOutput.getUint(); // 100
String string = evmOutput.getString(); // "abc"
// "0123456789abcdefghijklmnopqrstuvwxyz"
String string1 = evmOutput.getString();
boolean b = evmOutput.getBoolean(); // true
// "1e7d3e769f3f593dadcb8634cc5b09fc90dd3a61c4a06a79cb0923662fe6fae6b"
Identity id = evmOutput.getIdentity();
WASM contract parameter objects
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).
SERIALIZE(structure name, (member variable 1)(member variable 2)...(member variable n))
Example:
struct Foo {
int32_t x;
std::string y;
bool z;
int32_t tmp_value; // If tmp_value is not written in SERIALIZE, tmp_value will not participate in the serialization.
SERIALIZE(Foo, (y)(x)(z))
};
Foo f;
f.x = -1234567890;
f.y = "hello world";
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
.
// 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.
WASMOutput wasmOutput = new WASMOutput(ByteUtils.toHexString(transactionReceipt.getOutput()));
String string = wasmOutput.getString(); // "hello world"
BigInteger integer1 = wasmOutput.getInt32(); // -1234567890
boolean b = wasmOutput.getBoolean(); // true