BubiChain JAVA SDK
Overview
This document details the common interfaces of the Bubichain JAVA SDK, making it easier for developers to operate and query the BubiChain.
Environment
JDK 8 or above is required.
Installation
You have to complete the following steps. And the following 4.1.1 is an example.
- First add the following remote repository of BubiChain in Maven's configuration file.
<repository>
<id>releases</id>
<url>http://maven.bubidev.cn/content/repositories/releases/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
- Add the corresponding version of dependency packages to the configuration file of pom.xml
<dependency>
<groupId>cn.bubi.sdk</groupId>
<artifactId>bubichain-sdk</artifactId>
<version>4.1.1</version>
</dependency>
Format of Request and Response Data
This section details the format of the request parameters and response data.
Request Parameters
The class name of the request parameter of the interface is composed of Service Name + Method Name + Request. For example, the request parameter format of the getInfo interface in Account Service is AccountGetInfoRequest
.
The member of the request parameter is the member of the input parameter of each interface. For example, if the input parameter of the getInfo interface in Account Service is address, the complete structure of the request parameters of the interface is as follows:
Class AccountGetInfoRequest {
String address;
}
Response Data
The class name of the response data of the interface is composed of Service Name + Method Name + Response. For example, the response data format of the getNonce interface in Account Service is AccountGetNonceResponse
.
The members of the response data include error codes, error descriptions, and return results. For example, the members of the response data of the getNonce interface in Assets Services are as follows:
Class AccountGetNonceResponse {
Integer errorCode;
String errorDesc;
AccountGetNonceResult result;
}
Explain:
- errorCode: Error code. 0 means no error, greater than 0 means there is an error.
- errorDesc: Error description.
- result: Return the result. A structure whose class name is Service Service Name + Method Name + Result, whose members are members of the return value of each interface. For example, the result class name of the getNonce interface in Account Service is
AccountGetNonceResult
, and the member has a nonce. The complete structure is as follows:
Class AccountGetNonceResult {
Long nonce;
}
Quick Usage
This section describes the process of using the SDK. First you need to generate the SDK implementation and then call the interface of the corresponding service. Services include Account Service, Asset Service, Contract Service, Transaction Service, and Block Service. Interfaces are classified into Generating Public-Private Keys and Addresses, Checking Validity, Querying, and Broadcasting Transaction.
Generating SDK Instance
The SDK instance is generated by calling the getInstance
interface of the SDK. The specific call is as follows:
Simple configuration
It is used as follows:
String url = "http://seed1-node.bubi.cn";
SDK sdk = SDK.getInstance(url);
Timeout configuration
It is used as follows:
SDKConfigure sdkConfigure = new SDKConfigure();
sdkConfigure.setHttpConnectTimeOut(5000);
sdkConfigure.setHttpReadTimeOut(5000);
sdkConfigure.setUrl("http://seed1-node.bubi.cn");
sdk = SDK.getInstance(sdkConfigure);
Generating Public-Private Keys and Addresses
The public-private key address interface is used to generate the public key, private key, and address for the account on the BubiChain. This can be achieved by directly calling the Keypair.generator
interface. The specific call is as follows:
Keypair keypair = Keypair.generator();
System.out.println(keypair.getPrivateKey());
System.out.println(keypair.getPublicKey());
System.out.println(keypair.getAddress());
Checking Validity
The validity check interface is used to verify the validity of the information, and the information validity check can be achieved by directly invoking the corresponding interface. For example, to verify the validity of the account address, the specific call is as follows:
// Initialize request parameters
String address = "adxSdV6qWfyhJAmzrPbv3btsPPT6aFrqBku3C";
AccountCheckValidRequest request = new AccountCheckValidRequest();
request.setAddress(address);
// Call the checkValid interface
AccountCheckValidResponse response =
sdk.getAccountService().checkValid(request);
if(0 == response.getErrorCode()) {
System.out.println(response.getResult().isValid());
} else {
System.out.println("error: " + response.getErrorDesc());
}
Querying
The query
interface is used to query data on the BubiChain, and data query can be implemented by directly invoking the corresponding interface. For example, to query the account information, the specific call is as follows:
// Initialize request parameters
String accountAddress = "adxSdV6qWfyhJAmzrPbv3btsPPT6aFrqBku3C";
AccountGetInfoRequest request = new AccountGetInfoRequest();
request.setAddress(accountAddress);
// Call the getInfo interface
AccountGetInfoResponse response = sdk.getAccountService().getInfo(request);
if (response.getErrorCode() == 0) {
AccountGetInfoResult result = response.getResult();
System.out.println(JSON.toJSONString(result,true));
}
else {
System.out.println("error: " + response.getErrorDesc());
}
Broadcasting Transactions
Broadcasting transactions refers to the initiation of a transaction by means of broadcasting. The broadcast transaction consists of the following steps:
- Obtaining the Nonce Value of the account
- Building Operations
- Serializing Transactions
- Signing Transactions
- Submitting Transactions
Obtaining the Nonce Value of the Account
The developer can maintain the nonce
value of each account, and automatically increments by 1 for the nonce
value after submitting a transaction, so that multiple transactions can be sent in a short time; otherwise, the nonce
value of the account must be added 1 after the execution of the previous transaction is completed. For interface details, see getNonce, which calls as follows:
// Initialize request parameters
String senderAddress = "adxSa4oENoQCc66JRouZu1rKu4RWjgS69YD4S";
AccountGetNonceRequest getNonceRequest = new AccountGetNonceRequest();
getNonceRequest.setAddress(senderAddress);
// Call thegetNonce interface
AccountGetNonceResponse getNonceResponse = sdk.getAccountService().getNonce(getNonceRequest);
// Assign the nonce value
if (getNonceResponse.getErrorCode() == 0) {
AccountGetNonceResult result = getNonceResponse.getResult();
System.out.println("nonce: " + result.getNonce());
}
else {
System.out.println("error" + getNonceResponse.getErrorDesc());
}
Building Operations
The operation refers to some of the actions that are done in the transaction to facilitate serialization of transactions and evaluation of fees. For more details, see Operations Structure. For example, to build an operation to send Gas (GasSendOperation
), the specific interface call is as follows:
// Initialize variables
String senderAddress = "adxSa4oENoQCc66JRouZu1rKu4RWjgS69YD4S";
String destAddress = "adxSgTxU1awVzNUeR8xcnd3K75XKU8ziNHcWW";
Long gasAmount = ToBaseUnit.ToUGas("10.9");
// Build GasSendOperation
GasSendOperation operation = new GasSendOperation();
operation.setSourceAddress(senderAddress);
operation.setDestAddress(destAddress);
operation.setAmount(gasAmount);
Serializing Transactions
The transaction serialization
interface is used to serialize transactions and generate transaction blob strings for network transmission. The nonce value and operation are obtained from the interface called. For interface details, see buildBlob, which calls as follows:
// Initialize variables
String senderAddress = "adxSa4oENoQCc66JRouZu1rKu4RWjgS69YD4S";
Long gasPrice = 1000L;
Long feeLimit = ToBaseUnit.ToUGas("0.01");
// Initialize request parameters
TransactionBuildBlobRequest buildBlobRequest = new TransactionBuildBlobRequest();
buildBlobRequest.setSourceAddress(senderAddress);
buildBlobRequest.setNonce(nonce + 1);
buildBlobRequest.setFeeLimit(feeLimit);
buildBlobRequest.setGasPrice(gasPrice);
buildBlobRequest.addOperation(operation);
// Call the buildBlob interface
TransactionBuildBlobResponse buildBlobResponse = sdk.getTransactionService().buildBlob(buildBlobRequest);
if (buildBlobResponse.getErrorCode() == 0) {
TransactionBuildBlobResult result = buildBlobResponse.getResult();
System.out.println("txHash: " + result.getHash() + ", blob: " + result.getTransactionBlob());
} else {
System.out.println("error: " + buildBlobResponse.getErrorDesc());
}
Signing Transactions
The signature transaction
interface is used by the transaction initiator to sign the transaction using the private key of the account. The transactionBlob is obtained from the interface called. For interface details, see sign, which calls as follows:
// Initialize request parameters
String senderPrivateKey = "privbyQCRp7DLqKtRFCqKQJr81TurTqG6UKXMMtGAmPG3abcM9XHjWvq";
String []signerPrivateKeyArr = {senderPrivateKey};
TransactionSignRequest signRequest = new TransactionSignRequest();
signRequest.setBlob(transactionBlob);
for (int i = 0; i < signerPrivateKeyArr.length; i++) {
signRequest.addPrivateKey(signerPrivateKeyArr[i]);
}
// Call the sign interface
TransactionSignResponse signResponse = sdk.getTransactionService().sign(signRequest);
if (signResponse.getErrorCode() == 0) {
TransactionSignResult result = signResponse.getResult();
System.out.println(JSON.toJSONString(result, true));
} else {
System.out.println("error: " + signResponse.getErrorDesc());
}
Submitting Transactions
The submit
interface is used to send a transaction request to the BubiChain, triggering the execution of the transaction. transactionBlob and signResult are obtained from the interfaces called. For interface details, see submit, which calls as follows:
// Initialize request parameters
TransactionSubmitRequest submitRequest = new TransactionSubmitRequest();
submitRequest.setTransactionBlob(transactionBlob);
submitRequest.setSignatures(signResult.getSignatures());
// Call thesubmit interface
TransactionSubmitResponse response = sdk.getTransactionService().submit(submitRequest);
if (0 == response.getErrorCode()) {
System.out.println("交易广播成功,hash=" + response.getResult().getHash());
} else {
System.out.println("error: " + response.getErrorDesc());
}
Specific Methods
Method services include account service, asset service, contract service, transaction service, block service.
Transaction Service
Transaction Service provide transaction-related interfaces and currently have five interfaces: buildBlob, evaluateFee, sign, submit, and getInfo.
buildBlob
Note: Before you call buildBlob, you shold make some operations, details for Operations Structure.
Interface description
The
buildBlob
interface is used to serialize transactions and generate transaction blob strings for network transmission.Method call
TransactionBuildBlobResponse buildBlob(TransactionBuildBlobRequest);
Request parameters
Parameter Type Description sourceAddress String Required, the source account address initiating the operation nonce Long Required, the transaction serial number to be initiated, add 1 in the function, size limit [1, Long.MAX_VALUE] gasPrice Long Required, transaction gas price, unit UGas, 1 Gas = 10^8 UGas, size limit [1000, Long.MAX_VALUE] feeLimit Long Required, the minimum fees required for the transaction, unit UGas, 1 Gas = 10^8 UGas, size limit [1, Long.MAX_VALUE] operation BaseOperation[] Required, list of operations to be committed which cannot be empty ceilLedgerSeq long Optional, set a value which will be combined with the current block height to restrict transactions. If transactions do not complete within the set value plus the current block height, the transactions fail. The value you set must be greater than 0. If the value is set to 0, no limit is set. metadata String Optional, note Response data
Parameter Type Description transactionBlob String Serialized transaction hex string hash String Transaction hash Error code
Error Message Error Code Description INVALID_SOURCGasDDRESS_ERROR 11002 Invalid sourceAddress INVALID_NONCE_ERROR 11048 Nonce must be between 1 and Long.MAX_VALUE INVALID_DESTADDRESS_ERROR 11003 Invalid destAddress INVALID_INITBALANCE_ERROR 11004 InitBalance must be between 1 and Long.MAX_VALUE SOURCGasDDRESS_EQUAL_DESTADDRESS_ERROR 11005 SourceAddress cannot be equal to destAddress INVALID_ISSUE_AMOUNT_ERROR 11008 AssetAmount this will be issued must be between 1 and Long.MAX_VALUE INVALID_DATAKEY_ERROR 11011 The length of key must be between 1 and 1024 INVALID_DATAVALUE_ERROR 11012 The length of value must be between 0 and 256000 INVALID_DATAVERSION_ERROR 11013 The version must be equal to or greater than 0 INVALID_MASTERWEIGHT _ERROR 11015 MasterWeight must be between 0 and (Integer.MAX_VALUE * 2L + 1) INVALID_SIGNER_ADDRESS_ERROR 11016 Invalid signer address INVALID_SIGNER_WEIGHT _ERROR 11017 Signer weight must be between 0 and (Integer.MAX_VALUE * 2L + 1) INVALID_TX_THRESHOLD_ERROR 11018 TxThreshold must be between 0 and Long.MAX_VALUE INVALID_OPERATION_TYPE_ERROR 11019 Operation type must be between 1 and 100 INVALID_TYPE_THRESHOLD_ERROR 11020 TypeThreshold must be between 0 and Long.MAX_VALUE INVALID_ASSET_CODE _ERROR 11023 The length of key must be between 1 and 64 INVALID_ASSET_AMOUNT_ERROR 11024 AssetAmount must be between 0 and Long.MAX_VALUE INVALID_GAS_AMOUNT_ERROR 11026 GasAmount must be between 0 and Long.MAX_VALUE INVALID_ISSUER_ADDRESS_ERROR 11027 Invalid issuer address NO_SUCH_TOKEN_ERROR 11030 No such token INVALID_TOKEN_NAME_ERROR 11031 The length of token name must be between 1 and 1024 INVALID_TOKEN_SYMBOL_ERROR 11032 The length of symbol must be between 1 and 1024 INVALID_TOKEN_DECIMALS_ERROR 11033 Decimals must be between 0 and 8 INVALID_TOKEN_TOTALSUPPLY_ERROR 11034 TotalSupply must be between 1 and Long.MAX_VALUE INVALID_TOKENOWNER_ERRPR 11035 Invalid token owner INVALID_CONTRACTADDRESS_ERROR 11037 Invalid contract address CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR 11038 ContractAddress is not a contract account INVALID_TOKEN_AMOUNT_ERROR 11039 Token amount must be between 1 and Long.MAX_VALUE SOURCGasDDRESS_EQUAL_CONTRACTADDRESS_ERROR 11040 SourceAddress cannot be equal to contractAddress INVALID_FROMADDRESS_ERROR 11041 Invalid fromAddress FROMADDRESS_EQUAL_DESTADDRESS_ERROR 11042 FromAddress cannot be equal to destAddress INVALID_SPENDER_ERROR 11043 Invalid spender PAYLOAD_EMPTY_ERROR 11044 Payload cannot be empty INVALID_LOG_TOPIC_ERROR 11045 The length of a log topic must be between 1 and 128 INVALID_LOG_DATA_ERROR 11046 The length of one piece of log data must be between 1 and1024 INVALID_CONTRACT_TYPE_ERROR 11047 Type must be equal or bigger than 0 INVALID_NONCE_ERROR 11048 Nonce must be between 1 and Long.MAX_VALUE INVALID_ GASPRICE_ERROR 11049 GasPrice must be between 1000 and Long.MAX_VALUE INVALID_FEELIMIT_ERROR 11050 FeeLimit must be between 1 and Long.MAX_VALUE OPERATIONS_EMPTY_ERROR 11051 Operations cannot be empty INVALID_CEILLEDGERSEQ_ERROR 11052 CeilLedgerSeq must be equal to or greater than 0 OPERATIONS_ONE_ERROR 11053 One of the operations cannot be resolved REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize variables String senderAddresss = "adxSYQ8iMyZ7Dkj1oX1kjGMV55WXvoPKcLEK3"; String destAddress = "adxSgTxU1awVzNUeR8xcnd3K75XKU8ziNHcWW"; Long gasAmount = ToBaseUnit.ToUGas("10.9"); Long gasPrice = 1000L; Long feeLimit = ToBaseUnit.ToUGas("0.01"); Long nonce = 1L; // Build GasSendOperation GasSendOperation operation = new GasSendOperation(); operation.setSourceAddress(senderAddresss); operation.setDestAddress(destAddress); operation.setAmount(gasAmount); // Initialize request parameters TransactionBuildBlobRequest request = new TransactionBuildBlobRequest(); request.setSourceAddress(senderAddresss); request.setNonce(nonce); request.setFeeLimit(feeLimit); request.setGasPrice(gasPrice); request.addOperation(operation); // Call the buildBlob interface String transactionBlob = null; TransactionBuildBlobResponse response = sdk.getTransactionService().buildBlob(request); if (response.getErrorCode() == 0) { TransactionBuildBlobResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
evaluateFee
Interface description
The
evaluateFee
interface implements the cost estimate for the transaction.Method call
TransactionEvaluateFeeResponse evaluateFee (TransactionEvaluateFeeRequest);
Request parameters
Parameter Type Description sourceAddress String Required, the source account address initiating the operation nonce Long Required, transaction serial number to be initiated, size limit [1, Long.MAX_VALUE] operation BaseOperation[] Required, list of operations to be committed which cannot be empty signtureNumber Integer Optional, the number of people to sign, the default is 1, size limit [1, Integer.MAX_VALUE] ceilLedgerSeq Long Optional, set a value which will be combined with the current block height to restrict transactions. If transactions do not complete within the set value plus the current block height, the transactions fail. The value you set must be greater than 0. If the value is set to 0, no limit is set. metadata String Optional, note Response data
Parameter Type Description txs TestTx[] Evaluation transaction set Error code
Error Message Error Code Description INVALID_SOURCGasDDRESS_ERROR 11002 Invalid sourceAddress INVALID_NONCE_ERROR 11048 Nonce must be between 1 and Long.MAX_VALUE OPERATIONS_EMPTY_ERROR 11051 Operations cannot be empty OPERATIONS_ONE_ERROR 11053 One of the operations cannot be resolved INVALID_SIGNATURENUMBER_ERROR 11054 SignagureNumber must be between 1 and Integer.MAX_VALUE REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize variables String senderAddresss = "adxSa4oENoQCc66JRouZu1rKu4RWjgS69YD4S"; String destAddress = "adxSYQ8iMyZ7Dkj1oX1kjGMV55WXvoPKcLEK3"; Long gasAmount = ToBaseUnit.ToUGas("10.9"); Long gasPrice = 1000L; Long feeLimit = ToBaseUnit.ToUGas("0.01"); Long nonce = 51L; // Build GasSendOperation GasSendOperation gasSendOperation = new GasSendOperation(); gasSendOperation.setSourceAddress(senderAddresss); gasSendOperation.setDestAddress(destAddress); gasSendOperation.setAmount(gasAmount); // Initialize request parameters for transaction evaluation TransactionEvaluateFeeRequest request = new TransactionEvaluateFeeRequest(); request.addOperation(gasSendOperation); request.setSourceAddress(senderAddresss); request.setNonce(nonce); request.setSignatureNumber(1); request.setMetadata(HexFormat.byteToHex("evaluate fees".getBytes())); // Call the evaluateFee interface TransactionEvaluateFeeResponse response = sdk.getTransactionService().evaluateFee(request); if (response.getErrorCode() == 0) { TransactionEvaluateFeeResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
sign
Interface description
The
sign
interface is used to implement the signature of the transaction.Method call
TransactionSignResponse sign(TransactionSignRequest);
Request parameters
Parameter Type Description blob String Required, pending transaction blob to be signed privateKeys String[] Required, private key list
Response data
Parameter Type Description signatures Signature[] Signed data list Error code
Error Message Error Code Description INVALID_BLOB_ERROR 11056 Invalid blob PRIVATEKEY_NULL_ERROR 11057 PrivateKeys cannot be empty PRIVATEKEY_ONE_ERROR 11058 One of privateKeys is invalid REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String issuePrivateKey = "privbyQCRp7DLqKtRFCqKQJr81TurTqG6UKXMMtGAmPG3abcM9XHjWvq"; String []signerPrivateKeyArr = {issuePrivateKey}; String transactionBlob = "0A246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370102118C0843D20E8073A56080712246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370522C0A24627551426A4A443142534A376E7A41627A6454656E416870466A6D7852564545746D78481080A9E08704"; TransactionSignRequest request = new TransactionSignRequest(); request.setBlob(transactionBlob); for (int i = 0; i < signerPrivateKeyArr.length; i++) { request.addPrivateKey(signerPrivateKeyArr[i]); } TransactionSignResponse response = sdk.getTransactionService().sign(request); if(0 == response.getErrorCode()){ System.out.println(JSON.toJSONString(response.getResult(), true)); }else{ System.out.println("error: " + response.getErrorDesc()); }
submit
Interface description
The
submit
interface is used to implement the submission of the transaction.Method call
TransactionSubmitResponse submit(TransactionSubmitRequest);
Request parameters
Parameter Type Description blob String Required, transaction blob signature Signature[] Required, signature list Response data
Parameter Type Description hash String Transaction hash Error code
Error Message Error Code Description INVALID_BLOB_ERROR 11056 Invalid blob SIGNATURE_EMPTY_ERROR 11067 The signatures cannot be empty REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String transactionBlob = "0A246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370102118C0843D20E8073A56080712246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370522C0A24627551426A4A443142534A376E7A41627A6454656E416870466A6D7852564545746D78481080A9E08704"; Signature signature = new Signature(); signature.setSignData("D2B5E3045F2C1B7D363D4F58C1858C30ABBBB0F41E4B2E18AF680553CA9C3689078E215C097086E47A4393BCA715C7A5D2C180D8750F35C6798944F79CC5000A"); signature.setPublicKey("b0011765082a9352e04678ef38d38046dc01306edef676547456c0c23e270aaed7ffe9e31477"); TransactionSubmitRequest request = new TransactionSubmitRequest(); request.setTransactionBlob(transactionBlob); request.addSignature(signature); // Call the submit interface TransactionSubmitResponse response = sdk.getTransactionService().submit(request); if (0 == response.getErrorCode()) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else{ System.out.println("error: " + response.getErrorDesc()); }
getInfo
Interface description
The
getInfo
interface is used to implement query transactions based on transaction hashes.Method call
TransactionGetInfoResponse getInfo (TransactionGetInfoRequest);
Request parameters
Parameter Type Description hash String Transaction hash Response data
Parameter Type Description totalCount Long Total number of transactions returned transactions TransactionHistory[] Transaction content Error code
Error Message Error Code Description INVALID_HASH_ERROR 11055 Invalid transaction hash REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String txHash = "1653f54fbba1134f7e35acee49592a7c29384da10f2f629c9a214f6e54747705"; TransactionGetInfoRequest request = new TransactionGetInfoRequest(); request.setHash(txHash); // Call the getInfo interface TransactionGetInfoResponse response = sdk.getTransactionService().getInfo(request); if (response.getErrorCode() == 0) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else { System.out.println("error: " + response.getErrorDesc()); }
Operations Structure
Operations refer to the things that are to be done in a transaction, and the operations that need to be built before the operations are to be built. At present, there are 10 kinds of operations, which include AccountActivateOperation、AccountSetMetadataOperation、 AccountSetPrivilegeOperation、 AssetIssueOperation、 AssetSendOperation、 GasSendOperation、 ContractCreateOperation、 ContractInvokeByAssetOperation、 ContractInvokeByGasOperation、 LogCreateOperation.
BaseOperation
BaseOperation is the base class for all operations in the buildBlob interface. The following table describes BaseOperation:
Member | Type | Description |
---|---|---|
sourceAddress | String | Optional, source account address of the operation |
metadata | String | Optional, note |
AccountActivateOperation
Function
This operation is used to activate an account. AccountActivateOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation destAddress String Required, target account address initBalance Long Required, initialize the asset, unit UGas, 1 Gas = 10^8 UGas, size (0, Long.MAX_VALUE] metadata String Optional, note
AccountSetMetadataOperation
Function
This operation is used to set the metadata of an account. AccountSetMetadataOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation key String Required, metadata keyword, length limit [1, 1024] value String Required, metadata content, length limit [0, 256000] version Long Optional, metadata version deleteFlag Boolean Optional, whether to delete metadata metadata String Optional, note
AccountSetPrivilegeOperation
Function
This operation is used to set the privilege of an account. AccountSetPrivilegeOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation masterWeight String Optional, account weight, size limit [0, (Integer.MAX_VALUE * 2L + 1)] signers Signer[] Optional, signer weight list txThreshold String Optional, transaction threshold, size limit [0, Long.MAX_VALUE] typeThreshold TypeThreshold[] Optional, specify transaction threshold metadata String Optional, note
AssetIssueOperation
Function
This operation is used to issue assets. AssetIssueOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 50.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation code String Required, asset code, length limit [1, 64] assetAmount Long Required, asset code, length limit [0, Long.MAX_VALUE] metadata String Optional, note
AssetSendOperation
Note: If the destination account is not activated, the activation account operation must be invoked first.
Function
This operation is used to send assets. AssetSendOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation destAddress String Required, target account address code String Required, asset code, length limit [1, 64] issuer String Required, the account address for issuing assets assetAmount Long Required, asset amount, size limit [0, Long.MAX_VALUE] metadata String Optional, note
GasSendOperation
Note: If the destination account is not activated, this operation will activate this account.
Function
This operation is used to send Gas. GasSendOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation destAddress String Required, target account address gasAmount Long Required, asset code, length limit [0, Long.MAX_VALUE] metadata String Optional, note
ContractCreateOperation
Function
This operation is used to create a contract. ContractCreateOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 10.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation initBalance Long Required, initial asset for contract account, unit UGas, 1 Gas = 10^8 UGas, size limit [1, Long.MAX_VALUE] type Integer Optional, the language of the contract, the default is payload String Required, contract code for the corresponding language initInput String Optional, the input parameters of the init method in the contract code metadata String Optional, note
ContractInvokeByAssetOperation
Note: If the destination account is not activated, the activation account operation must be invoked first.
Function
This operation is used to send assets and invoke a contract. ContractInvokeByAssetOperation inherits from BaseOperation.
Fee
FeeLimit requires to add fees according to the execution of the transaction in the contract. First, the transaction fee is initiated. At present the fee (2018.07.26) is 0.01Gas, and then the transaction in the contract also requires the transaction initiator to add the transaction fees.
Member
Member Type Description sourceAddress String Optional, source account address of the operation contractAddress String Required, contract account address code String Optional, asset code, length limit [0, 1024]; when it is empty, only the contract is triggered issuer String Optional, the account address issuing assets; when it is null, only trigger the contract assetAmount Long Optional, asset amount, size limit[0, Long.MAX_VALUE]when it is 0, only trigger the contract input String Optional, the input parameter of the main() method for the contract to be triggered metadata String Optional, note
ContractInvokeByGasOperation
Note: If the destination account is not a contract and it is not activated, this operation will activate this account.
Function
This operation is used to send Gas and invoke an contract. ContractInvokeByGasOperation inherits from BaseOperation.
Fee
FeeLimit requires to add fees according to the execution of the transaction in the contract. First, the transaction fee is initiated. At present the fee (2018.07.26) is 0.01Gas, and then the transaction in the contract also requires the transaction initiator to add the transaction fees.
Member
Member Type Description sourceAddress String Optional, source account address of the operation contractAddress String Required, contract account address gasAmount Long Optional, number of asset issues, size limit [0, Long.MAX_VALUE], when it is 0 only triggers the contract input String Optional, the input parameter of the main() method for the contract to be triggered metadata String Optional, note
LogCreateOperation
Function
This operation is used to record a log. LogCreateOperation inherits from BaseOperation.
Fee
FeeLimit is currently fixed at 0.01 Gas (2018.07.26).
Member
Member Type Description sourceAddress String Optional, source account address of the operation topic String Required, Log theme,length limit [1, 128] datas List Required, Log content,length limit of each string [1, 1024] metadata String Optional, note
Account Service
Account Service provide account-related interfaces, which include six interfaces: checkValid, getInfo, getNonce, getBalance, getAssets, and getMetadata.
checkValid
Interface description
The checkValid interface is used to check the validity of the account address on the blockchain.
Method call
AccounCheckValidResponse checkValid(AccountCheckValidRequest)
Request parameters
Parameter Type Description address String Required, the account address to be checked on the blockchain Response data
Parameter Type Description isValid Boolean Whether the response data is valid Error code
Error Message Error Code Description REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String address = "adxSdV6qWfyhJAmzrPbv3btsPPT6aFrqBku3C"; AccountCheckValidRequest request = new AccountCheckValidRequest(); request.setAddress(address); // Call the checkValid AccountCheckValidResponse response = sdk.getAccountService().checkValid(request); if(0 == response.getErrorCode()) { System.out.println(response.getResult().isValid()); } else { System.out.println("error: " + response.getErrorDesc()); }
getInfo-Account
Interface description
The
getInfo
interface is used to obtain the specified account information.Method call
AccountGetInfoResponse GetInfo(AccountGetInfoRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried on the blockchain Response data
Parameter Type Description address String Account address balance Long Account balance, unit is UGas, 1 Gas = 10^8 UGas, the account balance must be > 0 nonce Long Account transaction serial number must be greater than 0 priv Priv Account privilege Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String accountAddress = "adxSdV6qWfyhJAmzrPbv3btsPPT6aFrqBku3C"; AccountGetInfoRequest request = new AccountGetInfoRequest(); request.setAddress(accountAddress); // Call thegetInfo interface AccountGetInfoResponse response = sdk.getAccountService().getInfo(request); if (response.getErrorCode() == 0) { AccountGetInfoResult result = response.getResult(); System.out.println("Account info: \n" + JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getNonce
Interface description
The
getNonce
interface is used to obtain the nonce value of the specified account.Method call
AccountGetNonceResponse getNonce(AccountGetNonceRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried on the blockchain Response data
Parameter Type Description nonce Long Account transaction serial number Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String accountAddress = "adxSk9MTT6aGoMxjAxuEGt1agRvWWnng25RF2"; AccountGetNonceRequest request = new AccountGetNonceRequest(); request.setAddress(accountAddress); // Call thegetNonce interface AccountGetNonceResponse response = sdk.getAccountService().getNonce(request); if(0 == response.getErrorCode()){ System.out.println("Account nonce:" + response.getResult().getNonce()); } else { System.out.println("error: " + response.getErrorDesc()); }
getBalance
Interface description
The
getBalance
interface is used to obtain the Gas balance of the specified account.Method call
AccountGetBalanceResponse getBalance(AccountGetBalanceRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried on the blockchain Response data
Parameter Type Description balance Long Gas balance, unit UGas, 1 Gas = 10^8 UGas Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters String accountAddress = "adxSk9MTT6aGoMxjAxuEGt1agRvWWnng25RF2"; AccountGetBalanceRequest request = new AccountGetBalanceRequest(); request.setAddress(accountAddress); // Call thegetBalance interface AccountGetBalanceResponse response = sdk.getAccountService().getBalance(request); if(0 == response.getErrorCode()){ AccountGetBalanceResult result = response.getResult(); System.out.println("Gas balance:" + ToBaseUnit.ToUGas(result.getBalance().toString()) + " Gas"); } else { System.out.println("error: " + response.getErrorDesc()); }
getAssets
Interface description
The
getAssets
interface is used to get all the asset information of the specified account.Method call
AccountGetAssets getAssets(AccountGetAssetsRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried Response data
Parameter Type Description asset AssetInfo[] Account asset Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network NO_ASSET_ERROR 11009 The account does not have the asset SYSTEM_ERROR 20000 System error Example
// Initialize request parameters AccountGetAssetsRequest request = new AccountGetAssetsRequest(); request.setAddress("adxSmZHjDopQam2y5ntvHhGk4XEkiXc9MnFWZ"); // Call thegetAssets interface AccountGetAssetsResponse response = sdk.getAccountService().getAssets(request); if (response.getErrorCode() == 0) { AccountGetAssetsResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getMetadata
Interface description
The
getMetadata
interface is used to obtain the metadata information of the specified account.Method call
AccountGetMetadataResponse getMetadata(AccountGetMetadataRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried key String Optional, metadata keyword, length limit [1, 1024] Response data
Parameter Type Description metadata MetadataInfo Account Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network NO_METADATA_ERROR 11010 The account does not have the metadata INVALID_DATAKEY_ERROR 11011 The length of key must be between 1 and 1024 SYSTEM_ERROR 20000 System error
Example
// Initialize request parameters String accountAddress = "adxSmZHjDopQam2y5ntvHhGk4XEkiXc9MnFWZ"; AccountGetMetadataRequest request = new AccountGetMetadataRequest(); request.setAddress(accountAddress); request.setKey("20180704"); // Call the getMetadata interface AccountGetMetadataResponse response = sdk.getAccountService().getMetadata(request); if (response.getErrorCode() == 0) { AccountGetMetadataResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
Asset Service
Asset Servicess and Account Service provide an asset-related interface. Currently there is one interface: getInfo.
getInfo-Asset
Interface description
The
getInfo
interface is used to obtain the specified asset information of the specified account.Method call
AssetGetInfoResponse getInfo(AssetGetInfoRequest);
Request parameters
Parameter Type Description address String Required, the account address to be queried code String Required, asset code, length limit [1, 64] issuer String Required, the account address for issuing assets Response data
Parameter Type Description asset AssetInfo[] Account asset Error code
Error Message Error Code Description INVALID_ADDRESS_ERROR 11006 Invalid address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network INVALID_ASSET_CODE_ERROR 11023 The length of asset code must be between 1 and 64 INVALID_ISSUER_ADDRESS_ERROR 11027 Invalid issuer address SYSTEM_ERROR 20000 System error Example
// Initialize request parameters AssetGetInfoRequest request = new AssetGetInfoRequest(); request.setAddress("adxSmZHjDopQam2y5ntvHhGk4XEkiXc9MnFWZ"); request.setIssuer("adxSdV6qWfyhJAmzrPbv3btsPPT6aFrqBku3C"); request.setCode("HNC"); // Call the getInfo interface AssetGetInfoResponse response = sdk.getAssetService().getInfo(request); if (response.getErrorCode() == 0) { AssetGetInfoResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
Contract Service
Contract Service provide contract-related interfaces and currently have four interfaces: checkValid, getInfo, getAddress, and call.
checkValid-Contract
Interface description
The checkValid interface is used to check the validity of the contract account.
Method call
ContractCheckValidResponse checkValid(ContractCheckValidRequest)
Request parameters
Parameter Type Description contractAddress String Contract account address to be tested Response data
Parameter Type Description isValid Boolean Whether the response data is valid Error code
Error Message Error Code Description INVALID_CONTRACTADDRESS_ERROR 11037 Invalid contract address REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR 11038 ContractAddress is not a contract account SYSTEM_ERROR 20000 System error Example
// Initialize request parameters ContractCheckValidRequest request = new ContractCheckValidRequest(); request.setContractAddress("adxSYQ8iMyZ7Dkj1oX1kjGMV55WXvoPKcLEK3"); // Call the checkValid interface ContractCheckValidResponse response = sdk.getContractService().checkValid(request); if (response.getErrorCode() == 0) { ContractCheckValidResult result = response.getResult(); System.out.println(result.getValid()); } else { System.out.println("error: " + response.getErrorDesc()); }
getInfo-Contract
Interface description
The
getInfo
interface is used to query the contract code.Method call
ContractGetInfoResponse getInfo (ContractGetInfoRequest);
Request parameters
Parameter Type Description contractAddress String Contract account address to be queried Response data
Parameter Type Description contract ContractInfo Contract info Error code
Error Message Error Code Description INVALID_CONTRACTADDRESS_ERROR 11037 Invalid contract address CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR 11038 contractAddress is not a contract account NO_SUCH_TOKEN_ERROR 11030 No such token GET_TOKEN_INFO_ERROR 11066 Failed to get token info REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize request parameters ContractGetInfoRequest request = new ContractGetInfoRequest(); request.setContractAddress("adxSYQ8iMyZ7Dkj1oX1kjGMV55WXvoPKcLEK3"); // Call the getInfo interface ContractGetInfoResponse response = sdk.getContractService().getInfo(request); if (response.getErrorCode() == 0) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getAddress
Interface description
The
getAddress
interface is used to query the contract address.Method call
ContractGetAddressResponse getInfo (ContractGetAddressRequest);
Request parameters
Parameter Type Description hash String The hash used to create a contract transaction Response data
Parameter Type Description contractAddressList List<ContractAddressInfo> Contract address list Error code
Error Message Error Code Description INVALID_HASH_ERROR 11055 Invalid transaction hash CONNECTNETWORK_ERROR 11007 Failed to connect to the network REQUEST_NULL_ERROR 12001 Request parameter cannot be null SYSTEM_ERROR 20000 System error Example
// Initialize request parameters ContractGetAddressRequest request = new ContractGetAddressRequest(); request.setHash("44246c5ba1b8b835a5cbc29bdc9454cdb9a9d049870e41227f2dcfbcf7a07689"); // Call the getAddress interface ContractGetAddressResponse response = sdk.getContractService().getAddress(request); if (response.getErrorCode() == 0) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else { System.out.println("error: " + response.getErrorDesc()); }
call
Interface description
The
call
interface is used to debug the contract code.Method call
ContractCallesponse call(ContractCallRequest);
Request parameters
Parameter Type Description sourceAddress String Optional, the account address to trigger the contract contractAddress String Optional, the contract account address and code cannot be empty at the same time code String Optional, the contract code and contractAddress cannot be empty at the same time, length limit [1, 64] input String Optional, input parameter for the contract contractBalance String Optional, the initial Gas balance given to the contract, unit UGas, 1 Gas = 10^8 UGas, size limit [1, Long.MAX_VALUE] optType Integer Required, 0: Call the read/write interface of the contract init, 1: Call the read/write interface of the contract main, 2: Call the read-only interface query feeLimit Long Minimum fee required for the transaction, size limit [1, Long.MAX_VALUE] gasPrice Long Transaction fee unit price, chared by byte, size limit [1000, Long.MAX_VALUE]
Response data
Parameter Type Description logs JSONObject Log information queryRets JSONArray Query the result set stat ContractStat Contract resource occupancy txs TransactionEnvs[] Transaction set Error code
Error Message Error Code Description INVALID_SOURCGasDDRESS_ERROR 11002 Invalid sourceAddress INVALID_CONTRACTADDRESS_ERROR 11037 Invalid contract address CONTRACTADDRESS_CODE_BOTH_NULL_ERROR 11063 ContractAddress and code cannot be empty at the same time INVALID_OPTTYPE_ERROR 11064 OptType must be between 0 and 2 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters ContractCallRequest request = new ContractCallRequest(); request.setCode("\"use strict\";log(undefined);function query() { getBalance(thisAddress); }"); request.setFeeLimit(1000000000L); request.setOptType(2); // Call the call interface ContractCallResponse response = sdk.getContractService().call(request); if (response.getErrorCode() == 0) { ContractCallResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
Block Service
Block Service provide block-related interfaces. There are currently 11 interfaces: getNumber, checkStatus, getTransactions, getInfo, getLatestInfo, getValidators, getLatestValidators, getReward, getLatestReward, getFees, and getLatestFees.
getNumber
Interface description
The
getNumber
interface is used to query the latest block height.Method call
BlockGetNumberResponse getNumber();
Response data
Parameter Type Description blockNumber Long The latest block height,corresponding to the underlying field sequence Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Call the getNumber interface BlockGetNumberResponse response = sdk.getBlockService().getNumber(); if(0 == response.getErrorCode()){ System.out.println(JSON.toJSONString(response.getResult(), true)); }else{ System.out.println("error: " + response.getErrorDesc()); }
checkStatus
Interface description
The
checkStatus
interface is used to check if the local node block is synchronized.Method call
BlockCheckStatusResponse checkStatus();
Response data
Parameter Type Description isSynchronous Boolean Whether the block is synchronized Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Call the checkStatus BlockCheckStatusResponse response = sdk.getBlockService().checkStatus(); if(0 == response.getErrorCode()){ System.out.println(JSON.toJSONString(response.getResult(), true)); }else{ System.out.println("error: " + response.getErrorDesc()); }
getTransactions
Interface description
The
getTransactions
interface is used to query all transactions at the specified block height.Method call
BlockGetTransactionsResponse getTransactions(BlockGetTransactionsRequest);
Request parameters
Parameter Type Description blockNumber Long Required, the height of the block to be queried must be greater than 0 Response data
Parameter Type Description totalCount Long Total number of transactions returned transactions TransactionHistory[] Transaction content Error code
Error Message Error Code Description INVALID_BLOCKNUMBER_ERROR 11060 BlockNumber must bigger than 0 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters Long blockNumber = 617247L; BlockGetTransactionsRequest request = new BlockGetTransactionsRequest(); request.setBlockNumber(blockNumber); // Call the getTransactions interface BlockGetTransactionsResponse response = sdk.getBlockService().getTransactions(request); if(0 == response.getErrorCode()){ System.out.println(JSON.toJSONString(response.getResult(), true)); }else{ System.out.println("error: " + response.getErrorDesc()); }
getInfo-Block
Interface description
The
getInfo
interface is used to obtain block information.Method call
BlockGetInfoResponse getInfo(BlockGetInfoRequest);
Request parameters
Parameter Type Description blockNumber Long Required, the height of the block to be queried Response data
Parameter Type Description closeTime Long Block closure time number Long Block height txCount Long Total transactions amount version String Block version Error code
Error Message Error Code Description INVALID_BLOCKNUMBER_ERROR 11060 BlockNumber must bigger than 0 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters BlockGetInfoRequest request = new BlockGetInfoRequest(); request.setBlockNumber(629743L); // Call the getInfo interface BlockGetInfoResponse response = sdk.getBlockService().getInfo(request); if (response.getErrorCode() == 0) { BlockGetInfoResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getLatestInfo
Interface description
The
getLatestInfo
interface is used to get the latest block information.Method call
BlockGetLatestInfoResponse getLatestInfo();
Response data
Parameter Type Description closeTime Long Block closure time number Long Block height,corresponding to the underlying field seq txCount Long Total transactions amount version String Block version
Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// 调用getLatestInfo接口 BlockGetLatestInfoResponse response = sdk.getBlockService().getLatestInfo(); if (response.getErrorCode() == 0) { BlockGetLatestInfoResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getValidators
Interface description
The
getValidators
interface is used to get the number of all the authentication nodes in the specified block.Method call
BlockGetValidatorsResponse getValidators(BlockGetValidatorsRequest);
Request parameters
Parameter Type Description blockNumber Long Required, the height of the block to be queried must be greater than 0 Response data
Parameter Type Description validators ValidatorInfo[] Validators list Error code
Error Message Error Code Description INVALID_BLOCKNUMBER_ERROR 11060 BlockNumber must bigger than 0 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters BlockGetValidatorsRequest request = new BlockGetValidatorsRequest(); request.setBlockNumber(629743L); // Call the getValidators interface BlockGetValidatorsResponse response = sdk.getBlockService().getValidators(request); if (response.getErrorCode() == 0) { BlockGetValidatorsResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getLatestValidators
Interface description
The
getLatestValidators
interface is used to get the number of all validators in the latest block.Method call
BlockGetLatestValidatorsResponse getLatestValidators();
Response data
Parameter Type Description validators ValidatorInfo[] Validators list Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Call the getLatestValidators interface BlockGetLatestValidatorsResponse response = sdk.getBlockService().getLatestValidators(); if (response.getErrorCode() == 0) { BlockGetLatestValidatorsResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getReward
Interface description
The
getReward
interface is used to retrieve the block reward and valicator node rewards in the specified block.Method call
BlockGetRewardResponse getReward(BlockGetRewardRequest);
Request parameters
Parameter Type Description blockNumber Long Required, the height of the block to be queried must be greater than 0 Response data
Parameter Type Description blockReward Long Block rewards validatorsReward ValidatorReward[] Validator rewards
Error code
Error Message Error Code Description INVALID_BLOCKNUMBER_ERROR 11060 BlockNumber must bigger than 0 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters BlockGetRewardRequest request = new BlockGetRewardRequest(); request.setBlockNumber(629743L); // Call the getReward interface BlockGetRewardResponse response = sdk.getBlockService().getReward(request); if (response.getErrorCode() == 0) { BlockGetRewardResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getLatestReward
Interface description
The
getLatestReward
interface gets the block rewards and validator rewards in the latest block. The method call is as follows:Method call
BlockGetLatestRewardResponse getLatestReward();
Response data
Parameter Type Description blockReward Long Block rewards validatorsReward ValidatorReward[] Validator rewards Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Call the getLatestReward interface BlockGetLatestRewardResponse response = sdk.getBlockService().getLatestReward(); if (response.getErrorCode() == 0) { BlockGetLatestRewardResult result = response.getResult(); System.out.println(JSON.toJSONString(result, true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getFees
Interface description
The
getFees
interface gets the minimum asset limit and fee unit price, chared by byte of the account in the specified block.Method call
BlockGetFeesResponse getFees(BlockGetFeesRequest);
Request parameters
Parameter Type Description blockNumber Long Required, the height of the block to be queried must be greater than 0 Response data
Parameter Type Description fees Fees Fees Error code
Error Message Error Code Description INVALID_BLOCKNUMBER_ERROR 11060 BlockNumber must bigger than 0 REQUEST_NULL_ERROR 12001 Request parameter cannot be null CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Initialize request parameters BlockGetFeesRequest request = new BlockGetFeesRequest(); request.setBlockNumber(629743L); // Call the getFees interface BlockGetFeesResponse response = sdk.getBlockService().getFees(request); if (response.getErrorCode() == 0) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else { System.out.println("error: " + response.getErrorDesc()); }
getLatestFees
Interface description
The
getLatestFees
interface is used to obtain the minimum asset limit and fee unit price, chared by byte of the account in the latest block.Method call
BlockGetLatestFeesResponse getLatestFees();
Response data
Parameter Type Description fees Fees Fees Error code
Error Message Error Code Description CONNECTNETWORK_ERROR 11007 Failed to connect to the network SYSTEM_ERROR 20000 System error Example
// Call the getLatestFees interface BlockGetLatestFeesResponse response = sdk.getBlockService().getLatestFees(); if (response.getErrorCode() == 0) { System.out.println(JSON.toJSONString(response.getResult(), true)); } else { System.out.println("error: " + response.getErrorDesc()); }
Data Object
Priv
Member | Type | Description |
---|---|---|
masterWeight | Long | Account weight, size limit [0, (Integer.MAX_VALUE * 2L + 1)] |
signers | Signer[] | Signer weight list |
threshold | Threshold | Threshold |
Signer
Member | Type | Description |
---|---|---|
address | String | The account address of the signer on the blockchain |
weight | Long | Signer weight, size limit [0, (Integer.MAX_VALUE * 2L + 1)] |
Threshold
Member | Type | Description |
---|---|---|
txThreshold | Long | Transaction default threshold, size limit [0, Long.MAX_VALUE] |
typeThresholds | TypeThreshold[] | Thresholds for different types of transactions |
TypeThreshold
Member | Type | Description |
---|---|---|
type | Long | The operation type must be greater than 0 |
threshold | Long | Threshold, size limit [0, Long.MAX_VALUE] |
AssetInfo
Member | Type | Description |
---|---|---|
key | Key | Unique identifier for asset |
assetAmount | Long | Amount of assets |
Key
Member | Type | Description |
---|---|---|
code | String | Asset code |
issuer | String | The account address for issuing assets |
ContractInfo
Member | Type | Description |
---|---|---|
type | Integer | Contract type, default is 0 |
payload | String | Contract code |
MetadataInfo
Member | Type | Description |
---|---|---|
key | String | Metadata keyword |
value | String | Metadata content |
version | Long | Metadata version |
ContractAddressInfo
Member | Type | Description |
---|---|---|
contractAddress | String | Contract address |
operationIndex | Integer | The subscript of the operation |
ContractStat
Member | Type | Description |
---|---|---|
applyTime | Long | Receipt time |
memoryUsage | Long | Memory footprint |
stackUsage | Long | Stack occupancy |
step | Long | Steps needed |
TransactionEnvs
Member | Type | Description |
---|---|---|
transactionEnv | TransactionEnv | Transaction |
TransactionEnv
Member | Type | Description |
---|---|---|
transaction | TransactionInfo | Transaction content |
trigger | ContractTrigger | Contract trigger |
TransactionInfo
Member | Type | Description |
---|---|---|
sourceAddress | String | The source account address initiating the transaction |
feeLimit | Long | Minimum fees required for the transaction |
gasPrice | Long | Transaction fee unit price, chared by byte |
nonce | Long | Transaction serial number |
operations | Operation[] | Operations list |
ContractTrigger
Member | Type | Description |
---|---|---|
transaction | TriggerTransaction | Trigger transactions |
Operation
Member | Type | Description |
---|---|---|
type | Integer | Operation type |
sourceAddress | String | The source account address initiating operations |
metadata | String | Note |
createAccount | OperationCreateAccount | Operation of creating accounts |
issueAsset | OperationIssueAsset | Operation of issuing assets |
payAsset | OperationPayAsset | Operation of transferring assets |
payCoin | OperationPayCoin | Operation of sending Gas |
setMetadata | OperationSetMetadata | Operation of setting metadata |
setPrivilege | OperationSetPrivilege | Operation of setting account privilege |
log | OperationLog | Record log |
TriggerTransaction
Member | Type | Description |
---|---|---|
hash | String | Transaction hash |
OperationCreateAccount
Member | Type | Description |
---|---|---|
destAddress | String | Target account address |
contract | Contract | Contract info |
priv | Priv | Account privilege |
metadata | MetadataInfo[] | Account |
initBalance | Long | Account assets, unit UGas, 1 Gas = 10^8 UGas, |
initInput | String | The input parameter for the init function of the contract |
Contract
Member | Type | Description |
---|---|---|
type | Integer | The contract language is not assigned value by default |
payload | String | The contract code for the corresponding language |
MetadataInfo
Member | Type | Description |
---|---|---|
key | String | Metadata keyword |
value | String | Metadata content |
version | Long | Metadata version |
OperationIssueAsset
Member | Type | Description |
---|---|---|
code | String | Asset code |
assetAmount | Long | Amount of assets |
OperationPayAsset
Member | Type | Description |
---|---|---|
destAddress | String | The target account address to which the asset is transferred |
asset | AssetInfo | Account asset |
input | String | Input parameters for the main function of the contract |
OperationPayCoin
Member | Type | Description |
---|---|---|
destAddress | String | The target account address to which the asset is transferred |
gasAmount | Long | Gas amounts to be transferred |
input | String | Input parameters for the main function of the contract |
OperationSetMetadata
Member | Type | Description |
---|---|---|
key | String | Metadata keyword |
value | String | Metadata content |
version | Long | Metadata version |
deleteFlag | boolean | Whether to delete metadata |
OperationSetPrivilege
Member | Type | Description |
---|---|---|
masterWeight | String | Account weight, size limit [0, (Integer.MAX_VALUE * 2L + 1)] |
signers | Signer[] | Signer weight list |
txThreshold | String | Transaction threshold, size limit [0, Long.MAX_VALUE] |
typeThreshold | TypeThreshold | Threshold for specified transaction type |
OperationLog
Member | Type | Description |
---|---|---|
topic | String | Log theme |
data | String[] | Log content |
TestTx
Member | Type | Description |
---|---|---|
transactionEnv | TestTransactionFees | Assess transaction costs |
TestTransactionFees
Member | Type | Description |
---|---|---|
transactionFees | TransactionFees | Transaction fees |
TransactionFees
Member | Type | Description |
---|---|---|
feeLimit | Long | Minimum fees required for the transaction |
gasPrice | Long | Transaction fee unit price, chared by byte |
Signature
Member | Type | Description |
---|---|---|
signData | Long | Signed data |
publicKey | Long | Public key |
TransactionHistory
Member | Type | Description |
---|---|---|
actualFee | String | Actual transaction cost |
closeTime | Long | Transaction closure time |
errorCode | Long | Transaction error code |
errorDesc | String | Transaction description |
hash | String | Transaction hash |
ledgerSeq | Long | Block serial number |
transaction | TransactionInfo | List of transaction contents |
signatures | Signature[] | Signature list |
txSize | Long | Transaction size |
ValidatorReward
Member | Type | Description |
---|---|---|
validator | String | Validator address |
reward | Long | Validator reward |
ValidatorInfo
Parameter | Type | Description |
---|---|---|
address | String | Consensus node address |
plegeCoinAmount | Long | Validators deposit |
Fees
Member | Type | Description |
---|---|---|
baseReserve | Long | Minimum asset limit for the account |
gasPrice | Long | Transaction fee unit price, chared by byte, unit UGas, 1 Gas = 10^8 UGas |
Error Code
Error Message | Error Code | Description |
---|---|---|
ACCOUNT_CREATE_ERROR | 11001 | Failed to create the account |
INVALID_SOURCGasDDRESS_ERROR | 11002 | Invalid sourceAddress |
INVALID_DESTADDRESS_ERROR | 11003 | Invalid destAddress |
INVALID_INITBALANCE_ERROR | 11004 | InitBalance must be between 1 and Long.MAX_VALUE |
SOURCGasDDRESS_EQUAL_DESTADDRESS_ERROR | 11005 | SourceAddress cannot be equal to destAddress |
INVALID_ADDRESS_ERROR | 11006 | Invalid address |
CONNECTNETWORK_ERROR | 11007 | Failed to connect to the network |
INVALID_ISSUE_AMOUNT_ERROR | 11008 | Amount of the token to be issued must be between 1 and Long.MAX_VALUE |
NO_ASSET_ERROR | 11009 | The account does not have the asset |
NO_METADATA_ERROR | 11010 | The account does not have the metadata |
INVALID_DATAKEY_ERROR | 11011 | The length of key must be between 1 and 1024 |
INVALID_DATAVALUE_ERROR | 11012 | The length of value must be between 0 and 256000 |
INVALID_DATAVERSION_ERROR | 11013 | The version must be equal to or greater than 0 |
INVALID_MASTERWEIGHT_ERROR | 11015 | MasterWeight must be between 0 and (Integer.MAX_VALUE * 2L + 1) |
INVALID_SIGNER_ADDRESS_ERROR | 11016 | Invalid signer address |
INVALID_SIGNER_WEIGHT_ERROR | 11017 | Signer weight must be between 0 and (Integer.MAX_VALUE * 2L + 1) |
INVALID_TX_THRESHOLD_ERROR | 11018 | TxThreshold must be between 0 and Long.MAX_VALUE |
INVALID_OPERATION_TYPE_ERROR | 11019 | Operation type must be between 1 and 100 |
INVALID_TYPE_THRESHOLD_ERROR | 11020 | TypeThreshold must be between 0 and Long.MAX_VALUE |
INVALID_ASSET_CODE_ERROR | 11023 | The length of key must be between 1 and 64 |
INVALID_ASSET_AMOUNT_ERROR | 11024 | AssetAmount must be between 0 and Long.MAX_VALUE |
INVALID_GAS_AMOUNT_ERROR | 11026 | GasAmount must be between 0 and Long.MAX_VALUE |
INVALID_ISSUER_ADDRESS_ERROR | 11027 | Invalid issuer address |
NO_SUCH_TOKEN_ERROR | 11030 | No such token |
INVALID_TOKEN_NAME_ERROR | 11031 | The length of token name must be between 1 and 1024 |
INVALID_TOKEN_SIMBOL_ERROR | 11032 | The length of symbol must be between 1 and 1024 |
INVALID_TOKEN_DECIMALS_ERROR | 11033 | Decimals must be between 0 and 8 |
INVALID_TOKEN_TOTALSUPPLY_ERROR | 11034 | TotalSupply must be between 1 and Long.MAX_VALUE |
INVALID_TOKENOWNER_ERRPR | 11035 | Invalid token owner |
INVALID_CONTRACTADDRESS_ERROR | 11037 | Invalid contract address |
CONTRACTADDRESS_NOT_CONTRACTACCOUNT_ERROR | 11038 | contractAddress is not a contract account |
INVALID_TOKEN_AMOUNT_ERROR | 11039 | TokenAmount must be between 1 and Long.MAX_VALUE |
SOURCGasDDRESS_EQUAL_CONTRACTADDRESS_ERROR | 11040 | SourceAddress cannot be equal to contractAddress |
INVALID_FROMADDRESS_ERROR | 11041 | Invalid fromAddress |
FROMADDRESS_EQUAL_DESTADDRESS_ERROR | 11042 | FromAddress cannot be equal to destAddress |
INVALID_SPENDER_ERROR | 11043 | Invalid spender |
PAYLOAD_EMPTY_ERROR | 11044 | Payload cannot be empty |
INVALID_LOG_TOPIC_ERROR | 11045 | The length of a log topic must be between 1 and 128 |
INVALID_LOG_DATA_ERROR | 11046 | The length of one piece of log data must be between 1 and1024 |
INVALID_CONTRACT_TYPE_ERROR | 11047 | Invalid contract type |
INVALID_NONCE_ERROR | 11048 | Nonce must be between 1 and Long.MAX_VALUE |
INVALID_GASPRICE_ERROR | 11049 | GasPrice must be between 1000 and Long.MAX_VALUE |
INVALID_FEELIMIT_ERROR | 11050 | FeeLimit must be between 1 and Long.MAX_VALUE |
OPERATIONS_EMPTY_ERROR | 11051 | Operations cannot be empty |
INVALID_CEILLEDGERSEQ_ERROR | 11052 | CeilLedgerSeq must be equal to or greater than 0 |
OPERATIONS_ONE_ERROR | 11053 | One of the operations cannot be resolved |
INVALID_SIGNATURENUMBER_ERROR | 11054 | SignagureNumber must be between 1 and Integer.MAX_VALUE |
INVALID_HASH_ERROR | 11055 | Invalid transaction hash |
INVALID_BLOB_ERROR | 11056 | Invalid blob |
PRIVATEKEY_NULL_ERROR | 11057 | PrivateKeys cannot be empty |
PRIVATEKEY_ONE_ERROR | 11058 | One of privateKeys is invalid |
SIGNDATA_NULL_ERROR | 11059 | SignData cannot be empty |
INVALID_BLOCKNUMBER_ERROR | 11060 | BlockNumber must be bigger than 0 |
PUBLICKEY_NULL_ERROR | 11061 | PublicKey cannot be empty |
URL_EMPTY_ERROR | 11062 | Url cannot be empty |
CONTRACTADDRESS_CODE_BOTH_NULL_ERROR | 11063 | ContractAddress and code cannot be empty at the same time |
INVALID_OPTTYPE_ERROR | 11064 | OptType must be between 0 and 2 |
GET_ALLOWANCE_ERROR | 11065 | Failed to get allowance |
GET_TOKEN_INFO_ERROR | 11066 | Failed to get token info |
SIGNATURE_EMPTY_ERROR | 11067 | The signatures cannot be empty |
REQUEST_NULL_ERROR | 12001 | Request parameter cannot be null |
CONNECTN_BLOCKCHAIN_ERROR | 19999 | Failed to connect to the blockchain |
SYSTEM_ERROR | 20000 | System error |