Edit

BUMO PHP SDK

Overview

This document details the common interfaces of the BUMO IOS SDK, making it easier for developers to operate and query the BuChain.

Installation

Php5.6 or above is required.

1. Download the BUMO PHP SDK package.
2. Unzip the bumo-sdk-php-{version}.zip package.
3. Unzip the ed25519.zip package in libs.
4. Copy the corresponding version of ed25519 in the libs directory to the PHP extension directory
5. Add 'extension=ed25519.so' in php.ini
6. Execute the following commands to add to project:

   composer require bumo/bumo-sdk:^{version}
   

   Example:

   composer require bumo/bumo-sdk:^v1.0.0
   

Format of Request Parameters 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 {
    $address; // string
}

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 {
    $errorCode; // int
    $errorDesc; // string
    $result; // AccountGetNonceResult
}

Note:

• 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 {
    $nonce; // int64
}

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 Groadcasting Transaction.

Generating SDK Instance

The SDK instance is generated by calling the getInstance interface of the SDK.

Simple configure

It is used as follows:

$url = "http://seed1.bumotest.io";
$sdk = \src\SDK::getInstance($url);

Timeout configure

It is used as follows:

$url = "http://seed1.bumotest.io";
$sdkConfigure = new \src\model\request\SDKConfigure();
$sdkConfigure->setTimeOut(15000);
$sdk = \src\SDK::getInstanceWithConfigure($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 BuChain. This can be achieved by directly calling the create interface of account service. The specific call is as follows:

$account = $sdk->getAccountService();
$response = $account->create();
if (0 == $response->error_code) {
    echo $response->result->private_key . "\n";
    echo $response->result->public_key . "\n";
    echo $response->result->address . "\n";
}

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
$address = "buQemmMwmRQY1JkcU7w3nhruoX5N3j6C29uo";
$request = new \src\model\request\AccountCheckValidRequest();
$request->setAddress($address);

// Call the checkValid interface
$response = $sdk->getAccountService()->checkValid($request);
if(0 == $response->error_code) {
    echo $response->result->is_valid . "\n";
} else {
    echo "error: " . $response->error_desc . "\n";
}

Querying

The query interface is used to query data on the BuChain, 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
$accountAddress = "buQemmMwmRQY1JkcU7w3nhruo%X5N3j6C29uo";
$request = new \src\model\request\AccountGetInfoRequest();
$request->setAddress(accountAddress);

// Call the getInfo interface
$response =  $sdk->getAccountService()->getInfo($request);
if ($response->error_code == 0) {
    $result = $response->result;
    echo json_encode($result) . "\n";
}
else {
    echo "error: " . $response->error_desc . "\n";
}

Broadcasting Transactions

Broadcasting transactions refers to the initiation of a transaction by means of broadcasting. The broadcast transaction consists of the following steps:

1. Obtaining the Nonce Value of the account
2. Building Operations
3. Serializing Transactions
4. Signing Transactions
5. 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 nounce 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
$senderAddress = "buQnnUEBREw2hB6pWHGPzwanX7d28xk6KVcp";
$getNonceRequest = new \src\model\request\AccountGetNonceRequest();
$getNonceRequest->setAddress($senderAddress);

// Call the getNonce interface
$getNonceResponse =  $sdk->getAccountService()->getNonce($getNonceRequest);

// Assign the nonce value
if ($getNonceResponse->error_code == 0) {
   $result = $getNonceResponse->result;
   echo "nonce: " . $result->nonce . "\n";
}
else {
    echo "error" . $getNonceresponse->error_desc . "\n";
}

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. For example, to build an operation to send BU (BUSendOperation), the specific interface call is as follows:

// Initialize variables
$senderAddress = "buQnnUEBREw2hB6pWHGPzwanX7d28xk6KVcp";
$destAddress = "buQsurH1M4rjLkfjzkxR9KXJ6jSu2r9xBNEw";
$buAmount = \src\common\Tools::BU2MO("10.9");

// Build BUSendOperation
$operation = new \src\model\request\operation\BUSendOperation();
$operation->setSourceAddress($senderAddress);
$operation->setDestAddress($destAddress);
$operation->setAmount($buAmount);

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
$senderAddress = "buQnnUEBREw2hB6pWHGPzwanX7d28xk6KVcp";
$gasPrice = 1000;
$feeLimit = \src\common\Tools::BU2MO("0.01");

// Initialize request parameters
$buildBlobRequest = new \src\model\request\TransactionBuildBlobRequest();
$buildBlobRequest->setSourceAddress($senderAddress);
$buildBlobRequest->setNonce($nonce + 1);
$buildBlobRequest->setFeeLimit($feeLimit);
$buildBlobRequest->setGasPrice($gasPrice);
$buildBlobRequest->addOperation($operation);

// Call the buildBlob interface
$buildBlobResponse = $sdk->getTransactionService()->buildBlob($buildBlobRequest);
if ($buildBlobResponse->error_code == 0) {
    $result = $buildBlobResponse->result;
    echo "txHash: " . $result->hash . ", blob: " . $result->transaction_blob . "\n";
} else {
    echo "error: " . $buildBlobResponse->error_desc . "\n";
}

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
$senderPrivateKey = "privbyQCRp7DLqKtRFCqKQJr81TurTqG6UKXMMtGAmPG3abcM9XHjWvq";
$signRequest = new \src\model\request\TransactionSignRequest();
$signRequest->addPrivateKey($senderPrivateKey);
$signRequest->setBlob($transactionBlob);

// Call the sign interface
$signResponse = $sdk->getTransactionService()->sign($signRequest);
if ($signResponse->error_code == 0) {
    $result = $signResponse->result;
    echo json_encode($result, JSON_UNESCAPED_UNICODE) . "\n";
} else {
    echo "error: " . $signResponse->error_desc . "\n";
}

Submitting Transactions

The submit interface is used to send a transaction request to the BU blockchain, 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
$submitRequest = new \src\model\request\TransactionSubmitRequest();
$submitRequest->setTransactionBlob($transactionBlob);
$submitRequest->setSignatures($signResult->signatures);

// Call the submit interface
$response = $sdk->getTransactionService()->submit($submitRequest);
if (0 == $response->error_code) {
    echo "hash=" . $response->result->hash . "\n";
} else {
    echo "error: " . $response->error_desc . "\n";
}

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.

• Interface description

  The buildBlob interface is used to serialize transactions and generate transaction blob strings for network transmission.

• Method call

  /**
  * Serialize the transaction
  * @param TransactionBuildBlobRequest $transactionBuildBlobRequest
  * @return TransactionBuildBlobResponse
  */
  public function buildBlob($transactionBuildBlobRequest);
  

• Request parameters

  Parameter	Type	Description
  sourceAddress	String	Required, the source account address initiating the operation
  nonce	int64	Required, the transaction serial number to be initiated, add 1 in the function, size limit [1, max(int64)]
  gasPrice	int64	Required, transaction gas price, unit MO, 1 BU = 10^8 MO, size limit [1000, max(int64)]
  feeLimit	int64	Required, the minimum fees required for the transaction, unit MO, 1 BU = 10^8 MO, size limit [1, max(int64)]
  operation	BaseOperation[]	Required, list of operations to be committed which cannot be empty
  ceilLedgerSeq	int64	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_SOURCEADDRESS_ERROR	11002	Invalid sourceAddress
  INVALID_NONCE_ERROR	11048	Nonce must be between 1 and max(int64)
  INVALID_DESTADDRESS_ERROR	11003	Invalid destAddress
  INVALID_INITBALANCE_ERROR	11004	InitBalance must be between 1 and max(int64)
  SOURCEADDRESS_EQUAL_DESTADDRESS_ERROR	11005	SourceAddress cannot be equal to destAddress
  INVALID_ISSUE_AMMOUNT_ERROR	11008	AssetAmount this will be issued must be between 1 and max(int64)
  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 bigger than 0
  INVALID_MASTERWEIGHT _ERROR	11015	MasterWeight must be between 0 and max(uint32)
  INVALID_SIGNER_ADDRESS_ERROR	11016	Invalid signer address
  INVALID_SIGNER_WEIGHT _ERROR	11017	Signer weight must be between 0 and max(uint32)
  INVALID_TX_THRESHOLD_ERROR	11018	TxThreshold must be between 0 and max(int64)
  INVALID_OPERATION_TYPE_ERROR	11019	Operation type must be between 1 and 100
  INVALID_TYPE_THRESHOLD_ERROR	11020	TypeThreshold must be between 0 and max(int64)
  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 max(int64)
  INVALID_BU_AMOUNT_ERROR	11026	BuAmount must be between 0 and max(int64)
  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 max(int64)
  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 max(int64)
  SOURCEADDRESS_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 max(int64)
  INVALID_ GASPRICE_ERROR	11049	GasPrice must be between 1000 and max(int64)
  INVALID_FEELIMIT_ERROR	11050	FeeLimit must be between 1 and max(int64)
  OPERATIONS_EMPTY_ERROR	11051	Operations cannot be empty
  INVALID_CEILLEDGERSEQ_ERROR	11052	CeilLedgerSeq must be equal to or bigger 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
  METADATA_NOT_STRING_ERROR	17001	Metadata must be a string
  INPUT_NOT_STRING_ERROR	17002	Input must be a string
  INIT_INPUT_NOT_STRING_ERROR	17003	InitInput must be a string
  INVALID_REQUEST_ERROR	17004	Request is invalid
  INVALID_DELETE_FLAG_ERROR	17005	The deleteFlag is invalid
  SIGNERS_NOT_ARRAY_ERROR	17006	The signers should be an array
  INVALID_SIGNER_ERROR	17007	The signer is invalid
  TYPE_THRESHOLDS_NOT_ARRAY_ERROR	17008	The typeThresholds should be an array

• Example

  // Initialize variables
  $senderAddresss = "buQfnVYgXuMo3rvCEpKA6SfRrDpaz8D8A9Ea";
  $destAddress = "buQsurH1M4rjLkfjzkxR9KXJ6jSu2r9xBNEw";
  $buAmount = \src\common\Tools::BU2MO(10.9);
  $gasPrice = 1000;
  $feeLimit = \src\common\Tools::BU2MO(0.01);
  $nonce = 1;
  
  // Build BUSendOperation
  $operation = new \src\model\request\operation\BUSendOperation();
  $operation->setSourceAddress($senderAddresss);
  $operation->setDestAddress($destAddress);
  $operation->setAmount($buAmount);
  
  // Initialize request parameters
  $request = new \src\model\request\TransactionBuildBlobRequest();
  $request->setSourceAddress($senderAddresss);
  $request->setNonce($nonce);
  $request->setFeeLimit($feeLimit);
  $request->setGasPrice($gasPrice);
  $request->addOperation($operation);
  
  // Call the buildBlob interface
  $transactionBlob = null;
  $response = $sdk->getTransactionService()->buildBlob($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

evaluateFee

• Interface description

  The evaluateFee interface implements the cost estimate for the transaction.

• Method call

  /**
  * Evaluate the fee of a transaction
  * @param TransactionEvaluateFeeRequest $transactionEvaluateFeeRequest
  * @return TransactionEvaluateFeeResponse
  */
  public function evaluateFee($transactionEvaluateFeeRequest);
  

• Request parameters

  Parameter	Type	Description
  sourceAddress	String	Required, the source account address initiating the operation
  nonce	int64	Required, transaction serial number to be initiated, size limit [1, max(int64)]
  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, max(uint32)]
  ceilLedgerSeq	int64	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_SOURCEADDRESS_ERROR	11002	Invalid sourceAddress
  INVALID_NONCE_ERROR	11045	Nonce must be between 1 and max(int64)
  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 max(uint32)
  REQUEST_NULL_ERROR	12001	Request parameter cannot be null
  SYSTEM_ERROR	20000	System error
  INVALID_REQUEST_ERROR	17004	Request is invalid
  METADATA_NOT_STRING_ERROR	17001	Metadata must be a string

• Example

  // Initialize variables
  $senderAddresss = "buQnnUEBREw2hB6pWHGPzwanX7d28xk6KVcp";
  $destAddress = "buQfnVYgXuMo3rvCEpKA6SfRrDpaz8D8A9Ea";
  $buAmount = \src\common\Tools::BU2MO(10.9);
  $gasPrice = 1000;
  $feeLimit = \src\common\Tools::BU2MO(0.01);
  $nonce = 51;
  
  // Build BUSendOperation
  $buSendOperation = new \src\model\request\operation\BUSendOperation();
  $buSendOperation->setSourceAddress($senderAddresss);
  $buSendOperation->setDestAddress($destAddress);
  $buSendOperation->setAmount($buAmount);
  
  // Initialize request parameters for transaction evaluation
  $request = new \src\model\request\TransactionEvaluateFeeRequest();
  $request->addOperation($buSendOperation);
  $request->setSourceAddress($senderAddresss);
  $request->setNonce($nonce);
  $request->setSignatureNumber(1);
  $request->setMetadata(bin2hex("evaluate fees"));
  
  // Call the evaluateFee interface
  $response = $sdk->getTransactionService().evaluateFee($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

sign

• Interface description

  The sign interface is used to implement the signature of the transaction.

• Method call

  /**
  * Sign a transaction
  * @param TransactionSignRequest $transactionSignRequest
  * @return TransactionSignResponse
  */
  public function 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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $issuePrivateKey = "privbyQCRp7DLqKtRFCqKQJr81TurTqG6UKXMMtGAmPG3abcM9XHjWvq";
  $transactionBlob = "0A246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370102118C0843D20E8073A56080712246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370522C0A24627551426A4A443142534A376E7A41627A6454656E416870466A6D7852564545746D78481080A9E08704";
  $request = new \src\model\request\TransactionSignRequest();
  $request->setBlob($transactionBlob);
  $request->addPrivateKey($issuePrivateKey);
  $response = $sdk->getTransactionService()->sign($request);
  if(0 == $response->error_code){
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  }else{
      echo "error: " . $response->error_desc;
  }
  

submit

• Interface description

  The submit interface is used to implement the submission of the transaction.

• Method call

  /**
  * Submit a transaction to bu chain
  * @param TransactionSubmitRequest $transactionSubmitRequest
  * @return TransactionSubmitResponse
  */
  public function 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
  INVALID_REQUEST_ERROR	17004	Request is invalid
  SIGNATURES_ARRAY_ERROR	17009	The signatures should be an array
  INVALID_SIGNATURE_ERROR	17010	The signature is invalid

• Example

  // Initialize request parameters
  $transactionBlob = "0A246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370102118C0843D20E8073A56080712246275516E6E5545425245773268423670574847507A77616E5837643238786B364B566370522C0A24627551426A4A443142534A376E7A41627A6454656E416870466A6D7852564545746D78481080A9E08704";
  $signature = new Signature();
  $signature->setSignData(
  "D2B5E3045F2C1B7D363D4F58C1858C30ABBBB0F41E4B2E18AF680553CA9C3689078E215C097086E47A4393BCA715C7A5D2C180D8750F35C6798944F79CC5000A");
  $signature->setPublicKey(
  "b0011765082a9352e04678ef38d38046dc01306edef676547456c0c23e270aaed7ffe9e31477");
  $request = new \src\model\request\\src\model\request\TransactionSubmitRequest();
  $request->setTransactionBlob($transactionBlob);
  $request->addSignature($signature);
  
  // Call the submit interface
  $response = $sdk->getTransactionService()->submit($request);
  if (0 == $response->error_code) { 
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else{
      echo "error: " . $response->error_desc;
  }
  

getInfo

• Interface description

  The getInfo interface is used to implement query transactions based on transaction hashes.

• Method call

  /**
  * Get the information of specific block
  * @param TransactionGetInfoRequest $transactionGetInfoRequest
  * @return TransactionGetInfoResponse
  */
  function getInfo($transactionGetInfoRequest);
  

• Request parameters

  Parameter	Type	Description
  hash	String	Transaction hash

• Response data

  Parameter	Type	Description
  totalCount	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $txHash = "1653f54fbba1134f7e35acee49592a7c29384da10f2f629c9a214f6e54747705";
  $request = new \src\model\request\TransactionGetInfoRequest();
  $request->setHash(txHash);
  
  // Call the getInfo interface
  $response = $sdk->getTransactionService()->getInfo($request);
  if ($response->error_code == 0) {
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

Operations

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、 BUSendOperation、 ContractCreateOperation、 ContractInvokeByAssetOperation、 ContractInvokeByBUOperation、 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 BU (2018.07.26).

• Member

  Member	Type	Description
  sourceAddress	String	Optional, source account address of the operation
  destAddress	String	Required, target account address
  initBalance	int64	Required, initialize the asset, unit MO, 1 BU = 10^8 MO, size (0, max(int64)]
  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 BU (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	int64	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 BU (2018.07.26).

• Member

  Member	Type	Description
  sourceAddress	String	Optional, source account address of the operation
  masterWeight	String	Optional, account weight, size limit [0, max(uint32)]
  signers	Signer[]	Optional, signer weight list
  txThreshold	String	Optional, transaction threshold, size limit [0, max(int64)]
  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 BU (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	int64	Required, asset code, length limit [0, max(int64)]
  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 BU (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	int64	Required, asset amount, size limit [0, max(int64)]
  metadata	String	Optional, note

BUSendOperation

Note: If the destination account is not activated, this operation will activate this account.

• Function

  This operation is used to send BUs. BUSendOperation inherits from BaseOperation.

• Fee

  FeeLimit is currently fixed at 0.01 BU (2018.07.26).

• Member

  Member	Type	Description
  sourceAddress	String	Optional, source account address of the operation
  destAddress	String	Required, target account address
  buAmount	int64	Required, asset code, length limit [0, max(int64)]
  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 BU (2018.07.26).

• Member

  Member	Type	Description
  sourceAddress	String	Optional, source account address of the operation
  initBalance	int64	Required, initial asset for contract account, unit MO, 1 BU = 10^8 MO, size limit [1, max(int64)]
  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.01BU, 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	int64	Optional, asset amount, size limit[0, max(int64)]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

ContractInvokeByBUOperation

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 BUs and invoke an contract. ContractInvokeByBUOperation 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.01BU, 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
  buAmount	int64	Optional, number of asset issues, size limit [0, max(int64)], 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 BU (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

  /**
  * Check the availability of address
  * @param AccountCheckValidRequest $accountCheckValidRequest
  * @return AccountCheckValidResponse
  */
  public function checkValid($accountCheckValidRequest);
  

• Request parameters

  Parameter	Type	Description
  address	String	Required, the account address to be checked on the blockchain

• Response data

  Parameter	Type	Description
  is_valid	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $address = "buQemmMwmRQY1JkcU7w3nhruoX5N3j6C29uo";
  $request = new \src\model\request\AccountCheckValidRequest();
  $request->setAddress(address);
  
  // Call the checkValid
  $response = $sdk->getAccountService()->checkValid($request);
  if(0 == $response->error_code) {
      echo $response->result->is_valid . "\n";
  } else {
      echo "error: " . $response->error_desc . "\n";
  }
  

getInfo

• Interface description

  The getInfo interface is used to obtain the specified account information.

• Method call

  /**
  * Get account info
  * @param AccountGetInfoRequest $accountGetInfoRequest
  * @return AccountGetInfoResponse, including address，balance，nonce and privilege
  */
  public function 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	int64	Account balance, unit is MO, 1 BU = 10^8 MO, the account balance must be > 0
  nonce	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $accountAddress = "buQemmMwmRQY1JkcU7w3nhruoX5N3j6C29uo";
  $request = new \src\model\request\AccountGetInfoRequest();
  $request->setAddress($accountAddress);
  
  // Call the getInfo interface
  $response =  $sdk->getAccountService()->getInfo($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo "Account info: " . json_encode($result, JSON_UNESCAPED_UNICODE) . "\n";
  } else {
      echo "error: " . $response->error_desc . "\n";
  }
  

getNonce

• Interface description

  The getNonce interface is used to obtain the nonce value of the specified account.

• Method call

  /**
  * Get account nonce
  * @param AccountGetNonceRequest $accountGetNonceRequest
  * @return AccountGetNonceResponse
  */
  public function 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	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $accountAddress = "buQswSaKDACkrFsnP1wcVsLAUzXQsemauEjf";
  $request = new \src\model\request\AccountGetNonceRequest();
  $request->setAddress($accountAddress);
  
  // Call the getNonce interface
  $response = $sdk->getAccountService()->getNonce($request);
  if(0 == $response->error_code){
      echo "Account nonce:" . $response->result->nonce;
  } else {
      echo "error: " . $response->error_desc;
  }
  

getBalance

• Interface description

  The getBalance interface is used to obtain the BU balance of the specified account.

• Method call

  /**
  * Get account balance of BU
  * @param AccountGetBalanceRequest $accountGetBalanceRequest
  * @return AccountGetBalanceResponse
  */
  public function 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	int64	BU balance, unit MO, 1 BU = 10^8 MO

• 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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $accountAddress = "buQswSaKDACkrFsnP1wcVsLAUzXQsemauEjf";
  $request = new \src\model\request\AccountGetBalanceRequest();
  $request->setAddress($accountAddress);
  
  // Call the getBalance interface
  $response = $sdk->getAccountService()->getBalance($request);
  if(0 == $response->error_code){
      $result = $response->result;
      echo "BU balance：" . \src\common\Tools::BU2MO($result->balance) . " BU";
  } else {
      echo "error: " . $response->error_desc;
  }
  

getAssets

• Interface description

  The getAssets interface is used to get all the asset information of the specified account.

• Method call

  /**
  * Get all assets of an account
  * @param AccountGetAssetsRequest $accountGetAssetsRequest
  * @return AccountGetAssetsResponse, include code, issuer, amount
  */
  public function getAssets;
  

• 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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\AccountGetAssetsRequest();
  $request->setAddress("buQsurH1M4rjLkfjzkxR9KXJ6jSu2r9xBNEw");
  
  // Call the getAssets interface
  $response = $sdk->getAccountService()->getAssets($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getMetadata

• Interface description

  The getMetadata interface is used to obtain the metadata information of the specified account.

• Method call

  /**
  * Get the metadata of an account
  * @param AccountGetMetadataRequest $accountGetMetadataRequest
  * @return AccountGetMetadataResponse, include key and value
  */
  public function 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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $accountAddress = "buQsurH1M4rjLkfjzkxR9KXJ6jSu2r9xBNEw";
  $request = new \src\model\request\AccountGetMetadataRequest();
  $request->setAddress($accountAddress);
  $request->setKey("20180704");
  
  // Call the getMetadata interface
  $response =  $sdk->getAccountService()->getMetadata($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

Asset Service

Asset Service follow the ATP 1.0 protocol, and Account Service provide an asset-related interface. Currently there is one interface: getInfo.

getInfo

• Interface description

  The getInfo interface is used to obtain the specified asset information of the specified account.

• Method call

  /**
  * Get details of the specified asset
  * @param  AssetGetInfoRequest $assetGetInfoRequest
  * @return AssetGetInfoResponse
  */
  function 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
  NO_ASSET_ERROR	11009	The account does not have this token
  SYSTEM_ERROR	20000	System error
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\AssetGetInfoRequest();
  $request->setAddress("buQsurH1M4rjLkfjzkxR9KXJ6jSu2r9xBNEw");
  $request->setIssuer("buQBjJD1BSJ7nzAbzdTenAhpFjmxRVEEtmxH");
  $request->setCode("HNC");
  
  // Call the getInfo interface
  $response = $sdk->getAssetService()->getInfo($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

Contract Service

Contract Service provide contract-related interfaces and currently have four interfaces: checkValid, getInfo, getAddress, and call.

checkValid

• Interface description

  The checkValid interface is used to check the validity of the contract account.

• Method call

  /**
  * Check the availability of a contract
  * @param  ContractCheckValidRequest $contractCheckValidRequest
  * @return ContractCheckValidResponse
  */
  function 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
  SYSTEM_ERROR	20000	System error
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\ContractCheckValidRequest();
  $request->setContractAddress("buQfnVYgXuMo3rvCEpKA6SfRrDpaz8D8A9Ea");
  
  // Call the checkValid interface
  $response = $sdk->getContractService()->checkValid($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo result->is_valid;
  } else {
      echo "error: " . $response->error_desc;
  }
  

getInfo

• Interface description

  The getInfo interface is used to query the contract code.

• Method call

  /**
  * Get the details of contract, include type and payload
  * @param ContractGetInfoRequest $contractGetInfoRequest
  * @return ContractGetInfoResponse
  */
  function 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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\ContractGetInfoRequest();
  $request->setContractAddress("buQfnVYgXuMo3rvCEpKA6SfRrDpaz8D8A9Ea");
  
  // Call the getInfo interface
  $response = $sdk->getContractService()->getInfo($request);
  if ($response->error_code == 0) {
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getAddress

• Interface description

The getAddress interface is used to query the contract address.

• Method call

  /**
  * Get the address of a contract account
  * @param  ContractGetAddressRequest $contractGetAddressRequest
  * @return ContractGetAddressResponse
  */
  function getAddress($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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\ContractGetAddressRequest();
  $request->setHash("44246c5ba1b8b835a5cbc29bdc9454cdb9a9d049870e41227f2dcfbcf7a07689");
  
  // Call the getAddress interface
  $response = $sdk->getContractService()->getAddress($request);
  if ($response->error_code == 0) {
  echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else {
  echo "error: " . $response->error_desc;
  }
  

call

• Interface description

  The call interface is used to debug the contract code.

• Method call

  /**
  * Call contract for free
  * @param  ContractCallRequest $contractCallRequest
  * @return ContractCallResponse
  */
  function 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 BU balance given to the contract, unit MO, 1 BU = 10^8 MO, size limit [1, max(int64)]
  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	int64	Minimum fee required for the transaction, size limit [1, max(int64)]
  gasPrice	int64	Transaction fuel price, size limit [1000, max(int64)]

• 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_SOURCEADDRESS_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
  INVALID_CONTRACT_BALANCE_ERROR	11044	The contractBalance must be between 1 and max(int64)
  INVALID_GASPRICE_ERROR	11049	GasPrice must be between 1000 and max(int64)
  INVALID_REQUEST_ERROR	17004	Request is invalid
  INPUT_NOT_STRING_ERROR	17002	Input must be a string

• Example

  // Initialize request parameters
  $request = new \src\model\request\ContractCallRequest();
  $request->setCode("\"use strict\";log(undefined);function query() { getBalance(thisAddress); }");
  $request->setFeeLimit(1000000000);
  $request->setOptType(2);
  
  // Call the call interface
  $response = $sdk->getContractService()->call($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

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

  /**
  * Get the latest block number
  * @return BlockGetNumberResponse
  */
  function getNumber()
  

• Response data

  Parameter	Type	Description
  header	BlockHeader	Block head
  blockNumber	int64	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
  $response = $sdk->getBlockService()->getNumber();
  if(0 == $response->error_code){
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  }else{
      echo "error: " . $response->error_desc;
  }
  

checkStatus

• Interface description

  The checkStatus interface is used to check if the local node block is synchronized.

• Method call

  /**
  * Check the status of block synchronization
  * @return BlockCheckStatusResponse
  */
  public function 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
  $response = $sdk->getBlockService()->checkStatus();
  if(0 == $response->error_code){
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  }else{
      echo "error: " . $response->error_desc;
  }
  

getTransactions

• Interface description

  The getTransactions interface is used to query all transactions at the specified block height.

• Method call

  /**
  * Get the transactions of specific block
  * @param BlockGetTransactionsRequest $blockGetTransactionsRequest
  * @return BlockGetTransactionsResponse
  */
  function getTransactions($blockGetTransactionsRequest)
  

• Request parameters

  Parameter	Type	Description
  blockNumber	int64	Required, the height of the block to be queried must be greater than 0

• Response data

  Parameter	Type	Description
  totalCount	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $blockNumber = 617247;
  $request = new \src\model\request\BlockGetTransactionsRequest();
  $request->setBlockNumber($blockNumber);
  
  // Call the getTransactions interface
  $response = $sdk->getBlockService()->getTransactions($request);
  if(0 == $response->error_code){
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  }else{
      echo "error: " . $response->error_desc;
  }
  

getInfo

• Interface description

  The getInfo interface is used to obtain block information.

• Method call

  /**
  * Get the information of specific block
  * @param BlockGetInfoRequest $blockGetInfoRequest
  * @return BlockGetInfoResponse
  */
  function getInfo($blockGetInfoRequest)
  

• Request parameters

  Parameter	Type	Description
  blockNumber	int64	Required, the height of the block to be queried

• Response data

  Parameter	Type	Description
  closeTime	int64	Block closure time
  number	int64	Block height
  txCount	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\BlockGetInfoRequest();
  $request->setBlockNumber(629743);
  
  // Call the getInfo interface
  $response = $sdk->getBlockService()->getInfo($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getLatestInfo

• Interface description

  The getLatestInfo interface is used to get the latest block information.

• Method call

  /**
  * Get the latest information of block
  * @return BlockGetLatestInfoResponse
  */
  function getLatestInfo()
  

• Response data

  Parameter	Type	Description
  closeTime	int64	Block closure time
  number	int64	Block height,corresponding to the underlying field seq
  txCount	int64	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

  // Call the getLatestInfo interface
  $response = $sdk->getBlockService()->getLatestInfo();
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getValidators

• Interface description

  The getValidators interface is used to get the number of all the authentication nodes in the specified block.

• Method call

  /**
  * Get the validators of specific block
  * @param  BlockGetValidatorsRequest $blockGetValidatorsRequest
  * @return BlockGetValidatorsResponse
  */
  function getValidators($blockGetValidatorsRequest)
  

• Request parameters

  Parameter	Type	Description
  blockNumber	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\BlockGetValidatorsRequest();
  $request->setBlockNumber(629743);
  
  // Call the getValidators interface
  $response = $sdk->getBlockService()->getValidators($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getLatestValidators

• Interface description

  The getLatestValidators interface is used to get the number of all validators in the latest block.

• Method call

  /**
  * Get the latest validators of block
  * @return BlockGetLatestValidatorsResponse
  */
  function 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
  $response = $sdk->getBlockService()->getLatestValidators();
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getReward

• Interface description

  The getReward interface is used to retrieve the block reward and valicator node rewards in the specified block.

• Method call

  /**
  * Get the reward of specific block
  * @param  BlockGetRewardRequest $blockGetRewardRequest
  * @return BlockGetRewardResponse
  */
  function GetReward($blockGetRewardRequest)
  

• Request parameters

  Parameter	Type	Description
  blockNumber	int64	Required, the height of the block to be queried must be greater than 0

• Response data

  Parameter	Type	Description
  blockReward	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\BlockGetRewardRequest();
  $request->setBlockNumber(629743);
  
  // Call the getReward interface
  $response = $sdk->getBlockService()->getReward($request);
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getLatestReward

• Interface description

  The getLatestReward interface gets the block rewards and validator rewards in the latest block.

• Method call

  /**
  * Get the latest reward of block
  * @return BlockGetLatestRewardResponse
  */
  function GetLatestReward()
  

• Response data

  Parameter	Type	Description
  blockReward	int64	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
  $response = $sdk->getBlockService()->getLatestReward();
  if ($response->error_code == 0) {
      $result = $response->result;
      echo json_encode($result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getFees

• Interface description

  The getFees interface gets the minimum asset limit and fuel price of the account in the specified block.

• Method call

  /**
  * Get the fees of specific block
  * @param  BlockGetFeesRequest $blockGetFeesRequest
  * @return BlockGetFeesResponse
  */
  function getFees($blockGetFeesRequest)
  

• Request parameters

  Parameter	Type	Description
  blockNumber	int64	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
  INVALID_REQUEST_ERROR	17004	Request is invalid

• Example

  // Initialize request parameters
  $request = new \src\model\request\BlockGetFeesRequest();
  $request->setBlockNumber(629743L);
  
  // Call the getFees interface
  $response = $sdk->getBlockService()->getFees($request);
  if ($response->error_code == 0) {
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

getLatestFees

• Interface description

  The getLatestFees interface is used to obtain the minimum asset limit and fuel price of the account in the latest block.

• Method call

  /**
  * Get the latest fees of block
  * @return BlockGetLatestFeesResponse
  */
  function 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
  $response = $sdk->getBlockService()->getLatestFees();
  if ($response->error_code == 0) {
      echo json_encode($response->result, JSON_UNESCAPED_UNICODE);
  } else {
      echo "error: " . $response->error_desc;
  }
  

Data Object

Priv

Member	Type	Description
masterWeight	int64	Account weight, size limit [0, max(uint32)]
signers	Signer[]	Signer weight list
threshold	Threshold	Threshold

Signer

Member	Type	Description
address	String	The account address of the signer on the blockchain
weight	int64	Signer weight, size limit [0, max(uint32)]

Threshold

Member	Type	Description
txThreshold	int64	Transaction default threshold, size limit [0, max(int64)]
typeThresholds	TypeThreshold[]	Thresholds for different types of transactions

TypeThreshold

Member	Type	Description
type	int64	The operation type must be greater than 0
threshold	int64	Threshold, size limit [0, max(int64)]

AssetInfo

Member	Type	Description
key	Key	Unique identifier for asset
assetAmount	int64	Amount of assets

Key

Member	Type	Description
code	String	Asset code
issuer	String	The account address for issuing assets

MetadataInfo

Member	Type	Description
key	String	Metadata keyword
value	String	Metadata content
version	int64	Metadata version

ContractInfo

Member	Type	Description
type	Integer	Contract type, default is 0
payload	String	Contract code

ContractAddressInfo

Member	Type	Description
contractAddress	String	Contract address
operationIndex	Integer	The subscript of the operation

ContractStat

Member	Type	Description
applyTime	int64	Receipt time
memoryUsage	int64	Memory footprint
stackUsage	int64	Stack occupancy
step	int64	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	int64	Minimum fees required for the transaction
gasPrice	int64	Transaction fuel price
nonce	int64	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 BU
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	int64	Account assets, unit MO, 1 BU = 10^8 MO
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	int64	Metadata version

OperationIssueAsset

Member	Type	Description
code	String	Asset code
assetAmount	int64	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
buAmount	int64	BU 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	int64	Metadata version
deleteFlag	boolean	Whether to delete metadata

OperationSetPrivilege

Member	Type	Description
masterWeight	String	Account weight, size limit [0, max(uint32)]
signers	Signer[]	Signer weight list
txThreshold	String	Transaction threshold, size limit [0, max(int64)]
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	int64	Minimum fees required for the transaction
gasPrice	int64	Transaction fuel price

Signature

Member	Type	Description
signData	int64	Signed data
publicKey	int64	Public key

TransactionHistory

Member	Type	Description
actualFee	String	Actual transaction cost
closeTime	int64	Transaction closure time
errorCode	int64	Transaction error code
errorDesc	String	Transaction description
hash	String	Transaction hash
ledgerSeq	int64	Block serial number
transaction	TransactionInfo	List of transaction contents
signatures	Signature[]	Signature list
txSize	int64	Transaction size

ValidatorInfo

Member	Type	Description
address	String	Consensus node address
plegeCoinAmount	int64	Validators deposit

ValidatorReward

Member	Type	Description
validator	String	Validator address
reward	int64	Validator reward

Fees

Member	Type	Description
baseReserve	int64	Minimum asset limit for the account
gasPrice	int64	Transaction fuel price, unit MO, 1 BU = 10^8 MO

Error Code

Error Message	Error Code	Description
ACCOUNT_CREATE_ERROR	11001	Failed to create the account
INVALID_SOURCEADDRESS_ERROR	11002	Invalid sourceAddress
INVALID_DESTADDRESS_ERROR	11003	Invalid destAddress
INVALID_INITBALANCE_ERROR	11004	InitBalance must be between 1 and max(int64)
SOURCEADDRESS_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 max(int64)
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 bigger than 0
INVALID_MASTERWEIGHT_ERROR	11015	MasterWeight must be between 0 and max(uint32)
INVALID_SIGNER_ADDRESS_ERROR	11016	Invalid signer address
INVALID_SIGNER_WEIGHT_ERROR	11017	Signer weight must be between 0 and max(uint32)
INVALID_TX_THRESHOLD_ERROR	11018	TxThreshold must be between 0 and max(int64)
INVALID_OPERATION_TYPE_ERROR	11019	Operation type must be between 1 and 100
INVALID_TYPE_THRESHOLD_ERROR	11020	TypeThreshold must be between 0 and max(int64)
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 max(int64)
INVALID_BU_AMOUNT_ERROR	11026	BuAmount must be between 0 and max(int64)
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 max(int64)
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 max(int64)
SOURCEADDRESS_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 max(int64)
INVALID_GASPRICE_ERROR	11049	GasPrice must be between 1000 and max(int64)
INVALID_FEELIMIT_ERROR	11050	FeeLimit must be between 1 and max(int64)
OPERATIONS_EMPTY_ERROR	11051	Operations cannot be empty
INVALID_CEILLEDGERSEQ_ERROR	11052	CeilLedgerSeq must be equal to or bigger than 0
OPERATIONS_ONE_ERROR	11053	One of the operations cannot be resolved
INVALID_SIGNATURENUMBER_ERROR	11054	SignagureNumber must be between 1 and max(uint32)
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
METADATA_NOT_STRING_ERROR	17001	Metadata must be a string
INPUT_NOT_STRING_ERROR	17002	Input must be a string
INIT_INPUT_NOT_STRING_ERROR	17003	InitInput must be a string
INVALID_REQUEST_ERROR	17004	Request is invalid
INVALID_DELETE_FLAG_ERROR	17005	The deleteFlag is invalid
SIGNERS_NOT_ARRAY_ERROR	17006	The signers should be an array
INVALID_SIGNER_ERROR	17007	The signer is invalid
TYPE_THRESHOLDS_NOT_ARRAY_ERROR	17008	The typeThresholds should be an array