# Java SDK

# Quick Start

Instantiate "topj".

package org.sawyer;

import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.procotol.http.HttpService;
import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        String serverUrl = topj.getDefaultServerUrl();
        HttpService httpService = new HttpService(serverUrl);
        topj = Topj.build(httpService);
    }
}

# Network

  • RPC API
HttpService httpService = new HttpService(serverUrl);
  • Restful API
HttpService httpService = new HttpService(serverUrl);

# Interface Overview

Interface Description
topj.setTransactionReceiptProcessor() Transaction initialization settings.
topj.genAccount() Generate an account object by the private key.
topj.passport() Get an on-chain access identity token.
topj.getChainInfo() Get mainchain informaiton.
topj.getAllStandBys Get all nodes in the candidate pool.
topj.getStandBys() Get individual candidate node.
topj.getCGP() Get on-chain governance parameters.
topj.getLastUnitBlock() or topj.getUnitBlockByHeight() Get unit block by block height.
topj.getLastTableBlock() or topj.getTableBlockByHeight() Get table block by block height.
topj.getAccount() Get account information on the chain.
topj.transfer() Send TOP to another account address.
topj.getTransaction() Query account transaction details.
topj.stakeGas() Lock TOP to get gas.
topj.unStakeGas() Unlock the TOP used to get gas.
topj.registerNode() Register miner.
topj.queryNodeInfo() Get miner information.
topj.updateNodeType() Update miner type.
topj.setNodeName() Set miner name.
topj.stakeDeposit() Increase miner deposit.
topj.unStakeDeposit() Decrease miner deposit.
topj.setDividendRate() Advance node sets dividend ratio.
topj.listVoteUsed() Get account's votes distribution.
topj.unRegisterNode() Unregister miner.
topj.redeemNodeDeposit() Redeem the miner deposit after the miner is cancelled.
topj.stakeVote() Lock TOP to get votes.
topj.unStakeVote() Unlock the TOP used to get votes.
topj.voteNode() Vote on nodes.
topj.unVoteNode() Cancel voting on miners.
topj.queryVoterDividend() Get voter dividend details.
topj.claimVoterDividend() Claim voter dividend.
topj.queryNodeReward() Query the individual miner’s reward.
topj.queryAllNodeReward() Query all miners‘ reward.
topj.claimNodeReward() Claim miner reward.
topj.submitProposal() Submit proposals.
topj.withdrawProposal() Withdraw proposals.
topj.queryProposal() Query proposal details.
topj.tccVote() TCC vote on proposals.
Tools Description
transferActionParam.decode Parse out the amount and note in the transfer transaction body.
xTransaction.isSuccess Determine whether the transaction is successful.
Transaction Object All transaction requests return this object.

# Transaction Initialization Settings

After the SDK sends a transaction request, the program cannot directly return the transaction execution result, so you need to loop to the chain to query whether the transaction is successful. The default query is once every 3 seconds, and the loop is 100 times for a total of 5 minutes. If the transaction still cannot be queried at this time, the program returns the transaction hash.

he "setTransactionReceiptProcessor" method can modify the cycle query interval and the number of cycles. For example, the sample code is modified to query once every 5 seconds and cycle 3 times for a total of 15 seconds.

Request Method

topj.setTransactionReceiptProcessor

Request Parameters

"TransactionReceiptProcessor" is an abstract class. There are two implementation classes, "PollingTransactionReceiptProcessor" and "NoOpProcessor", which can be instantiated and passed in.

"PollingTransactionReceiptProcessor" means that it will poll "attempts" times with an interval of "sleepDuration" milliseconds. The parameters required for instantiation are shown in the following table.

Parameter Name Required Default Value Parameter Type Description
sleepDuration Yes - Long Waiting interval, in "ms".
attempts Yes - Int Cycles.

You can also set it to not loop, return the transaction hash directly, and pass in the "NoOpProcessor" object interface. The code is:

topj.setTransactionReceiptProcessor(new NoOpProcessor())

"NoOpProcessor" means to return the hash directly without parameters.

Request Sample

package org.sawyer;

import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
    }
}

# Chain Basic Operations

# Generate Account Object By Private key

The account object is generated locally based on the private key, and the object contains parameters such as private key, public key, and account address.

Request Method

topj.genAccount

Request Parameters

Parameter Name Required Default Value Parameter Type Description
privateKey Yes - String Private Key.

Response Parameters

Parameter Name Parameter Type Description
address String Account address/
addressType String Account address type: 0--ordinary account address;1--sub account address;2--platform smart account address;3--application smart account address.
balance Uint64 Account balance.
lastUnitHeight Uint64 The unit block height of the latest consensus successful transaction.
netType Integer Net type: "0"--mainnet, "1"--testnet.
nonce Uint64 The latest consensus and successful transaction nonce of this account and it is unique.
privateKey String The private key is used for decryption and signing transaction. Please do not share your private key with other people, so as not to cause asset loss!
privateKeyBytes String The Byte format of the private key.
publicKey String The public key and the private key always appear in pairs.
Used to encrypt and verify signature.
sequenceId String The number of client sessions, increasing.
identityToken String Before interacting with the chain, you first need to obtain a chain access identity token. The identity token varies from account to account. This field is not currently checked.

Locally generated account is mainly used to generate public and private keys and addresses. Other parameters, except "token", are all initial values. You need to run the topjs.getAccount method to get the real value on the chain.

Request Sample

package org.test;

import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.procotol.http.HttpService;

public class main {
    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args){
        HttpService httpService = new HttpService("http://localhost:19081");
        topj = Topj.build(httpService);
        account = topj.genAccount();
    }
}

Response Schema

{
    "address":"T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
    "addressType":"0",
    "balance":0,
    "lastUnitHeight":0,
    "netType":0,
    "nonce":0,
    "privateKey":"ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321",
    "privateKeyBytes":"7IUZxyNkmrIXCAfTmp0BvhphlyZs/jm0zGbAQz34UyE=",
    "publicKey":"04ba6f20d132c94044fb0dd36035c3a9fc11ce30d6f3252e16083add3c78a76fe692d980754d77ba06594e70dfa51dbfe87832e5b38c91a03fdeae80ed0b414f65",
    "sequenceId":"1600657385123",
    "identityToken": ""
}

# Get On-chain Access Identity Token

According to the account to obtain the identity token, each account token is different. In all subsequent requests, the token parameter is required.

Request Method

topj.passport

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

The return value contains the token field, which has been directly put into the account object for use in subsequent calls.

Parameter Name Parameter Type Description
secret_key String Secret key.
signature_method String Signature method.
signature_ver_code String Signature method version.
identity_token String identity token, used to interact with the chain. This parameter is required for all subsequent requests.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.PassportResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        ResponseBase<PassportResponse> token =topj.passport(account);
        System.out.println(JSONObject.toJSONText(token));
    }
}

Response Schema

{
    "data":{
        "identity_token":"c139fb51-d541-41f5-9d9d-4e6c083766f1",
        "secret_key":"fc06ccea-c34d-40b5-8b93-f985c6f3ecee",
        "signature_method":"hmac_sha2",
        "signature_ver_code":"1.0"
    },
    "errmsg":"ok",
    "errno":0,
    "sequence_id":"1600657932853"
}

# Get Mainchain Information

Request Method

topj.getChainInfo

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account Object.

Response Parameters

Parameter Name Parameter Type Description
first_timerblock_hash String Hash of the first clock block.
first_timerblock_stamp Uint64 Generation time of the first clock block.
init_total_locked_token Uint64 Total TOP Token initially locked by the system. The system initializes the exchange rate of gas = total gas/ total locked amount of the system to avoid the system initialized exchange rate of gas to be 0.
token_price Uint64 Exchange rate of locking TOP Token for gas, measured in tgas/top, which changes dynamically with the change of locked TOP token in the system.
total_gas_shard Uint32 Total gas per shard for 24 hours.
validator_group_count Uint32 Number of validator group.
version String Mainchain version.

Request Parameters

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ChainInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<ChainInfoResponse> chainInfo = topj.getChainInfo(account);
        System.out.println(JSONObject.toJSONText(chainInfo));
    }
}

Response Schema

{
   "data" : {
      "first_timerblock_hash" : "0b98350d3e8ec4511ec1720bff0c6d6205519ffa90a879a65eed23e9312b21de",
      "first_timerblock_stamp" : 1573189200,
      "init_total_locked_token" : 10000000000000,
      "token_price" : 432000,
      "total_gas_shard" : 2160000000000,
      "validator_group_count" : 2,
      "version" : "0.0.0.1"
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "10"
}

# Get All Candidate Nodes

Get information of all nodes in the candidate pool contract on the Beacon, including information of nodes those have been elected as the edge, archive, validator, auditor, Beacon and Beacon.

Request Method

topj.getAllStandBys

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Parameter Name Parameter Type Description
consensus_public_key String The key used when the node is working. Account public-private key pair or non-asset public-private key pair.
node_id String Node account address.
stake Uint64 Node stake.

Request Sample

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.StandBysResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<StandBysResponse> sb = topj.getAllStandBys(account);
        System.out.println(JSONObject.toJSONText(sb));
    }
}

Response Schema

{
	 "data" : {
      "archive" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
      ],
      "auditor" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
         {
            "consensus_public_key" : "BFyUBEG/eO5SomaDQZidofp7n0s0eq/9scRAxWp8w+fbb3CnOSffdN3CeNHzJKYgBBmK5anXtvXkkBYCmW7+tiU=",
            "node_id" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
            "stake" : 0
         }
      ],
      "edge" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
         {
            "consensus_public_key" : "BFyUBEG/eO5SomaDQZidofp7n0s0eq/9scRAxWp8w+fbb3CnOSffdN3CeNHzJKYgBBmK5anXtvXkkBYCmW7+tiU=",
            "node_id" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
            "stake" : 0
         }
      ],
      "root_beacon" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
         {
            "consensus_public_key" : "BFyUBEG/eO5SomaDQZidofp7n0s0eq/9scRAxWp8w+fbb3CnOSffdN3CeNHzJKYgBBmK5anXtvXkkBYCmW7+tiU=",
            "node_id" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
            "stake" : 0
         }
      ],
      "validator" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
         {
            "consensus_public_key" : "BFyUBEG/eO5SomaDQZidofp7n0s0eq/9scRAxWp8w+fbb3CnOSffdN3CeNHzJKYgBBmK5anXtvXkkBYCmW7+tiU=",
            "node_id" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
            "stake" : 0
         }
      ],
      "sub_beacon" : [
         {
            "consensus_public_key" : "BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36Kz MOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
            "node_id" : "T8000066ab344963eaa071f9636faac26b0d1a39900325",
            "stake" : 0
         },
         {
            "consensus_public_key" : "BFyUBEG/eO5SomaDQZidofp7n0s0eq/9scRAxWp8w+fbb3CnOSffdN3CeNHzJKYgBBmK5anXtvXkkBYCmW7+tiU=",
            "node_id" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
            "stake" : 0
         }
      ]
   }
}
	"errmsg": "ok",
	"errno": 0,
	"sequence_id": "49"
}

# Get Single Candidate Node

Get information about a single node in the candidate pool.

Request Method

topj.getStandBys

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
nodeAddr Yes -

Response Parameters

Parameter Name Parameter Type Description
consensus_public_key String The key used when the node is working. Account public-private key pair or non-asset public-private key pair.
node_id String Node account address.
stake Uint64 Node stake.

Request Sample

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.StandBysDetail;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<StandBysDetail> sb = topj.getStandBys(account, "T8000066ab344963eaa071f9636faac26b0d1a39900325");
        System.out.println(JSONObject.toJSONText(sb));
    }
}

Response Schema

{
    "data":{
        "consensus_public_key":"T8000066ab344963eaa071f9636faac26b0d1a39900325",
        "node_id":"BFFVnheBS2yJLwlb+q6xH/DL+RotbvRdd9YeJKug1tP+WppTdB36KzMOHxmHTsh5u9BKgPDgXppFvyBeqYUxoTU=",
        "stake":0
    },
    "errmsg":"ok",
    "errno":0,
    "sequence_id":"1600658014340"
}

# Get On-chain Governance Parameters

Request Method

topj.getCGP

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Please refer to On-chain Governance Parameters.

Request Sample

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ChainInfoResponse;
import org.topj.methods.response.CGPResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<CGPResponse> cgp = topj.getCGP(account);
        System.out.println(JSONObject.toJSONText(cgp));
    }
}

Response Schema

{
   "data" : {
      "additional_issue_year_ratio" : "8",
      "application_contract_code_max_len" : "32768",
      "archive_election_interval" : "360",
      "archive_reward_ratio" : "4",
      "auditor_group_count" : "2",
      "auditor_nodes_per_segment" : "27",
      "auditor_reward_ratio" : "10",
      "award_auditor_credit" : "30000",
      "award_validator_credit" : "30000",
      "backward_auditor_slash_credit" : "100000",
      "backward_node_lock_duration_increment" : "103680",
      "backward_validator_slash_credit" : "100000",
      "beacon_tx_fee" : "100000000",
      "cluster_election_interval" : "60",
      "cluster_election_minimum_rotation_ratio" : "66",
      "cluster_zero_workload" : "0",
      "contract_call_contracts_num" : "25",
      "cpu_gas_exchange_ratio" : "40",
      "cross_reading_rec_reg_contract_height_step_limitation" : "12",
      "cross_reading_rec_reg_contract_logic_timeout_limitation" : "60",
      "cross_reading_rec_standby_pool_contract_height_step_limitation" : "12",
      "cross_reading_rec_standby_pool_contract_logic_timeout_limitation" : "67",
      "custom_property_max_number" : "128",
      "custom_property_name_max_len" : "16",
      "dividend_ratio_change_interval" : "120960",
      "edge_election_interval" : "360",
      "edge_reward_ratio" : "2",
      "election_rotation_count_ratio" : "16",
      "free_gas" : "25000",
      "fullunit_contain_of_unit_num" : "21",
      "governance_reward_ratio" : "4",
      "initial_total_locked_token" : "1000000000000000",
      "max_archive_group_size" : "512",
      "max_auditor_group_size" : "64",
      "max_auditor_rotation_count" : "2",
      "max_edge_group_size" : "512",
      "max_election_committee_size" : "256",
      "max_gas_account" : "1000000",
      "max_gas_contract" : "50000000",
      "max_nodedeposit_lock_duration" : "3110400",
      "max_validator_group_size" : "128",
      "max_validator_stake" : "5000",
      "max_vote_nodes_num" : "10000",
      "min_archive_deposit" : "1000000000000",
      "min_auditor_deposit" : "1000000000000",
      "min_auditor_group_size" : "6",
      "min_credit" : "100000",
      "min_edge_deposit" : "200000000000",
      "min_election_committee_size" : "32",
      "min_free_gas_balance" : "100000000",
      "min_mainnet_active_archives" : "1",
      "min_mainnet_active_auditors" : "128",
      "min_mainnet_active_edges" : "1",
      "min_mainnet_active_validators" : "512",
      "min_mainnet_active_votes" : "384000000",
      "min_node_reward" : "0",
      "min_ratio_annual_total_reward" : "2",
      "min_stake_votes_num" : "1",
      "min_table_block_report" : "32",
      "min_tcc_proposal_deposit" : "0",
      "min_tx_deposit" : "100000",
      "min_validator_deposit" : "500000000000",
      "min_validator_group_size" : "6",
      "min_voter_dividend" : "0",
      "min_votes_num" : "1",
      "punish_interval_table_block" : "368640",
      "punish_interval_time_block" : "8640",
      "rec_election_interval" : "259201",
      "rec_standby_pool_update_interval" : "11",
      "reward_issue_interval" : "8640",
      "shard_zero_workload" : "0",
      "sign_block_publishment_threshold_value" : "0",
      "sign_block_ranking_publishment_threshold_value" : "10",
      "sign_block_ranking_reward_threshold_value" : "0",
      "sign_block_reward_threshold_value" : "80",
      "tableslash_report_schedule_interval" : "1",
      "tableworkload_report_schedule_interval" : "1",
      "task_num_per_round" : "16",
      "tcc_member_number" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87,T8000066ab344963eaa071f9636faac26b0d1a39900325",
      "tcc_proposal_expire_time" : "259200",
      "toggle_whitelist" : "0",
      "total_gas_shard" : "2160000000000",
      "tx_deposit_gas_exchange_ratio" : "20",
      "tx_send_timestamp_tolerance" : "300",
      "unlock_gas_staked_delay_time" : "8640",
      "usedgas_decay_cycle" : "8640",
      "validator_group_count" : "4",
      "validator_reward_ratio" : "60",
      "vote_reward_ratio" : "20",
      "votes_report_interval" : "30",
      "whitelist" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba,T80000fd4f433c036268f17a1b4204ea907e70618d030e,T8000066ab344963eaa071f9636faac26b0d1a39900325,T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "workload_per_tableblock" : "2",
      "workload_per_tx" : "1",
      "workload_report_min_table_block_num" : "32",
      "workload_timer_interval" : "17",
      "zec_election_interval" : "120977",
      "zec_standby_pool_update_interval" : "31",
      "zone_election_trigger_interval" : "31"
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "1"
}

# Get Unit Block

  • Get the latest height unit block.

Request Method

topj.getLastUnitBlock

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
address Yes - String Account address.
  • Get the specified height unit block

Request Method

topj.getUnitBlockByHeight

Request Method

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
address Yes - String Account address.
height Yes - Integer Block height.

Response Parameters

Parameter Name Parameter Name Description
body Object
fullunit Object To save data storage space, every 21 lightunits are packaged as a fullunit.
lightunit Object
lightunit_input Object Transaction information in lightunit.
txs Object The transaction information packaged in this block, the structured is a map array, and the key of the map is a transaction hash, such as: 6e734fed40b907bb64d257968e6a46a79c4ca144088d330b674cc8b545350324
recv_tx_exec_status Uint8 Consensus status of the transaction receiver: 1-- success; 2--failure.The second round of consensus fails or refuses to execute, which usually occurs when the in contract transaction fails.
send_tx_lock_gas Uint64 In a application contract transaction, the gas that the transaction sender can pay for the transaction receiver.
tx_exec_status Uint8 Sender's transaction consensus status, 1-- success; 2 - failure.
tx_consensus_phase Uint8 Transaction consensus phase:1--self;2--send;3--recv。
enum_transaction_subtype_self = 1, // self operate
enum_transaction_subtype_send = 2, // send to other account
enum_transaction_subtype_recv = 3, // receive from other account
enum_transaction_subtype_recv_ack = 4(confirm), // receive ack from other account
used_tx_deposit Uint32 Consumed transaction deposit,the unit is uTOP。
used_disk Uint32 Consumed disk resource.
used_gas Uint32 Consumed gas resource,the unit is Tgas。
lightunit_state Object Changes in status caused by transactions in the lightunit block.
balance_change Uint64 Balance change.
native_property Key-value Array Account native property. If the property is null, it indicates that the property has not been set this time, and is equivalent to 0 in calculation.
custom_property_key String Array Get the list of custom property names with changes,only returning keys.
hash String The hexadecimal String of this block hash.
header Object
auditor_xip String Auditor leader node of this block(xip).
timerblock_height Uint64 Clock block height.
validator String The validator leader miner account address that generated this block.
The validator and auditor nodes take turns as the consensus leader node. When the returned field contains account address information, for example, in the following response example, the value of the validator field is "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba", which proves that the block generated is the validator node and the miner account address is " T8000085a8e8acd53c72dca85dcb002a6710796975b4ba".
validator_xip String Validator leader node of this block(xip).
height Uint64 Block height.
owner String The unit block owner.
prev_hash String The hexadecimal of the hash of the previous block.
timestamp Uint64 Block time stamp(GMT).

Account Native Property

Property Code Field Property Name Property Type Description
XPROPERTY_CONTRACT_CODE "@1" String The specific code for contract execution.
XPROPERTY_LOCK_TOKEN_KEY "@4" Map Set of locked TOP tokens by transactions under an account.
XPROPERTY_LOCK_TOKEN_SUM_KEY "@5" String Total amount of locked TOP tokens.
XPORPERTY_SUB_ACCOUNT_KEY "@13" Llist List of sub account.
XPORPERTY_CONTRACT_SUB_ACCOUNT_KEY "@14" List List of contract sub account.
XPORPERTY_CONTRACT_PARENT_ACCOUNT_KEY "@15" String Parent account of contract account.
XPROPERTY_USED_TGAS_KEY "@30" String Value of gas attenuation.
XPROPERTY_LAST_TX_HOUR_KEY "@32" String The logical clock at @30 was last updated.
XPROPERTY_USED_DISK_KEY "@34" String Disk used, which is useless temporarily this period.
XPROPERTY_CONTRACT_TGAS_LIMIT_KEY "@37" String gas_limit: The upper limit of the gas fee that the user is willing to pay for the transaction.
XPROPERTY_PLEDGE_VOTE_KEY "@45" List Used for exchanging votes, unlocking the TOP tokens used for exchanging votes, storing all votes exchanging transactions of account.
XPROPERTY_EXPIRE_VOTE_TOKEN_KEY "@46" String All the TOP tokens that have expired when exchanging votes.

Request Sample

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.UnitBlockResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<UnitBlockResponse> sb = topj.getLastUnitBlock(account, account.getAddress());
        System.out.println(JSONObject.toJSONText(sb));
    }
}

Response Schema

{
    "data":{
        "value":{
            "body":{
                "fullunit":null,
                "lightunit":{
                    "lightunit_input":{
                        "txs":[
                            {
                                "0xe9033212399f946abd947f5684956b40e0b70539f29b643e55be315823768d42":{
                                    "recv_tx_exec_status":1,
                                    "send_tx_lock_gas":0,
                                    "tx_consensus_phase":"confirm",
                                    "tx_exec_status":1,
                                    "used_disk":0,
                                    "used_gas":0,
                                    "used_tx_deposit":0
                                }
                            }
                        ]
                    },
                    "lightunit_state":{
                        "balance_change":100000,
                        "burned_amount_change":0,
                        "custom_property_key":null,
                        "native_property":null
                    }
                }
            },
            "hash":"41b5cea651bc7402164a7adebaa1204fc63d39decd002a657f7c8f96d08235b7",
            "header":{
                "auditor_xip":"100000000000031:f6c00000000407ff",
                "timerblock_height":948,
                "validator":"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba",
                "validator_xip":"100000000000031:f6c0000000050000"
            },
            "height":3,
            "owner":"T80000fd4f433c036268f17a1b4204ea907e70618d030e",
            "prev_hash":"ad3c5654d77a81f9e7fbb5c154f0670d9ee99c6d49e4a0e32ee75b455a898d14",
            "timestamp":1604502026
        }
    },
    "errmsg":"ok",
    "errno":0,
    "sequence_id":"1604502074025"
}

# Get Table Block

  • Get the latest height table block.

Request Method

topj.getLastTableBlock

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
address Yes - String Account address.
  • Get the specified height unit block

Request Method

topj.getTableBlockByHeight

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
address Yes - String Account address.
height Yes - Integer Block height.

Response Parameters

Parameter Name Parameter Type Description
tableblock Object The tableblock contains multiple units. When there is no new transaction on the chain for a long time, the latest height data of the tableblock is "null".
units lightunit_input Object Tableblock stores information of unit blocks.
is_contract_create Bool Transactions created by contract.
last_tx_nonce String Nonce of previous transaction.
tx_sender_locked_gas Uint64 In a application contract transaction, the gas that the transaction sender can pay for the transaction receiver.
tx_consensus_phase Uint8 Transaction consensus phase:1(self),2(send),3(recv)
enum_transaction_subtype_self = 1, // self operate
enum_transaction_subtype_send = 2, // send to other account
enum_transaction_subtype_recv = 3, // receive from other account
enum_transaction_subtype_recv_ack = 4(confirm), // receive ack from other account
lightunit_state Object Please refer to the unit block parameter description.
unit_height Uint64 Unit block height.
hash String The hexadecimal String of this block hash.
header Object
auditor_xip String Auditor leader node of this block(xip).
timerblock_height Uint64 Clock block height.
validator String The validator leader miner account address that generated this block.
The validator and auditor nodes take turns as the consensus leader node. When the returned field contains account address information, for example, in the following response example, the value of the validator field is "T800002276a7d58218ac4978733e5cca927a7d86cb7c87", which proves that the block generated is the validator node and the miner account address is " T800002276a7d58218ac4978733e5cca927a7d86cb7c87".
validator_xip String Validator leader node of this block(xip).
height Uint64 Block height.
owner String The table block owner.
prev_hash String The hexadecimal of the hash of the previous block.
timestamp Uint64 Block time stamp(GMT).

Request Sample

package org.sawyer;


import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.TableBlockResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {

    private static Topj topj = null;
    private static Account account = null;

    public static void main(String[] args) throws IOException {

        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount();
        topj.passport(account);
        ResponseBase<TableBlockResponse> sb = topj.getLastTableBlock(account, account.getAddress());
        System.out.println(JSONObject.toJSONText(sb));
    }
}

Response Schema

{
   "data" : {
      "value" : {
         "body" : {
            "tableblock" : {
               "units" : {
                  "T8000066ab344963eaa071f9636faac26b0d1a39900325" : {
                     "lightunit_input" : {
                        "0xe31fbabe30ae6c06bf6f5fc54bec44295bf2efa749ac82b97b63565804383e42" : {
                           "is_contract_create" : 0,
                           "last_tx_nonce" : 0,
                           "send_tx_lock_gas" : 0,
                           "tx_consensus_phase" : "confirm"
                        }
                     },
                     "lightunit_state" : {
                        "balance_change" : 0,
                        "burned_amount_change" : 0,
                        "custom_property_key" : null,
                        "native_property" : null
                     },
                     "unit_height" : 3
                  }
               }
            }
         },
         "hash" : "f260ae40f5ea129a7f22b36b6abe8e46bb0058114af7390d54261e0db513e462",
         "header" : {
            "auditor_xip" : "100000000000001:f6000000000407ff",
            "timerblock_height" : 7929,
            "validator" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
            "validator_xip" : "100000000000001:f600000000050003"
         },
         "height" : 9,
         "owner" : "T-a-gRD2qVpp2S7UpjAsznRiRhbE1qNnhMbEDp@146",
         "prev_hash" : "1d69844c0efec8fb56df7bb38ff9080251fb2b3fd62e3d6a961779ca3e3820d4",
         "table_id" : 146,
         "timestamp" : 1594882650
      }
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "17"
}

# Account Management

# Query Account Information On The Chain

The account’s latest "nonce" and "last_hash_xxhash64" are used When sending a transaction to the chain. These two attributes can be obtained from the return value of this method.

Request Method

topj.getAccount

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Parameters Name Parameter Type Description
account_addr String Normal user account address or contract account address.
available_gas Uint64 The available gas of the account address. The unit is Tgas.
If the return value is negative, there may be two reasons: 1. The account balance after obtaining free gas is less than 100*10^6 uTOP; 2. Unlock the TOP Token after running out the gas exchanged.
balance Uint64 The balance of the account address. The unit is uTOP.
burned_token Uint64 All burned TOP tokens of the account address. The unit is uTOP.
cluster_id Uint8 cluster ID。
contract_address List If a application contract is deployed by a ordinary account, the application contract account address will be returned.
created_time Uint64 The clock height when the account created on the blockchain.
disk_staked_token Uint64 The amount of locked TOP tokens to exchange disk. The unit is uTOP.
gas_staked_token Uint64 The amount of locked TOP tokens to exchange gas. The unit is uTOP.
group_id Uint8 group ID。
latest_tx_hash String The hash of the latest successful transaction.
latest_tx_hash_xxhash64 String The xx64hash of the latest successful transaction.
latest_unit_height Uint64 The unit block height of the latest successful transaction.
lock_balance Uint64 Locked TOP tokens used for application contract transactions. Unit of measurement is uTOP
When running applicaiton contract, the transaction sender can transfer TOP tokens to the contract account at the same time. If the contract fails to execute, the transferred TOP tokens needs to be returned to the sender. Therefore, the transferred money should be locked before running the contract successfully.
lock_deposit_balance Uint64 Application contract transaction costs are related to the CPU time and transaction size.The costs of the application contract transactions cannot be determined at the beginning of the transaction. The method is to lock part of the transaction deposit of the transaction sender. At the third round of consensus of the transaction, according to the final execution of the application contract, the transaction deposit of the sender is deducted to pay for the costs. Measured in uTOP.
lock_gas Uint64 Application contract transaction costs are related to the CPU time and transaction size.The costs of the application contract transactions cannot be determined at the beginning of the transaction. The method adopted is to freeze part of the gas of the transaction sender. At the third round of consensus of the transaction, according to the final execution of the application contract, the gas of the sender is deducted to pay for the costs. Measured in Tgas.
nonce Uint64 The nonce of the latest successful transaction. Unique in the global network.
total_free_gas Uint64 Total free gas of the account address. Measured in Tgas.
At present, when the account balance ≥100*10^6 uTOP, the system will give the account 25,000 Tgas for free. This value changes along with the on-chain governance parameters changes.
total_gas Uint64 Total gas of the account address. Measured in Tgas.
total_stake_gas Uint64 Total gas obtained by locking TOP Tokens. Measured in Tgas.
unlock_disk_staked Uint64 TOP tokens to exchange disk in unlock. After initiating the unlock, we need to wait 24 hours for the unlocked amount to arrive in the account.
unlock_gas_staked Uint64 TOP tokens to exchange gas in unlock. After initiating the unlock, we need to wait 24 hours for the unlocked amount to arrive in the account.
unused_vote_amount Uint64 Unused vote amount of the account.
vote_staked_token Uint64 TOP tokens to exchange votes in lock.
zone_id Uint8 zone ID.

Shard to which the account belongs:

ID Shard
zone_id, cluster_id, group_id, are 1, 0, 0 Beacon Network
zone_id, cluster_id, group_id, are 2, 0, 0 Beacon Network
zone_id, cluster_id, group_id, are 14, 1, 1 Archive Network
zone_id, cluster_id, group_id, are 15, 1, 1 Edge Network
zone_id, cluster_id, are 0, 1, group_id∈[1,63] Audit Network
zone_id, cluster_id, are 0, 1, group_id∈[64,126] Validate Network

To query application contract account information, return the following two parameters in addition to the above parameters.

Parameter Name Parameter Name Description
contract_code String Application contract code.
contract_parent_account String Contract parent account that deployed the application contract.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.AccountInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 3));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        ResponseBase<AccountInfoResponse>  accountInfoResponse = topj.getAccount(account);
        System.out.println(JSONObject.toJSONText(accountInfoResponse));
    }
}

Response Sample

{
   "data" : {
      "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "available_gas" : 25000,
      "balance" : 100000000000000,
      "burned_token" : 0,
      "cluster_id" : 1,
      "contract_address" : [T30000MaSkcvg2iyqMRDRMFnTQ8o5237Xs1dT9TR],
      "created_time" : 1596520429,
      "disk_staked_token" : 0,
      "group_id" : 64,
      "gas_staked_token" : 0,
      "latest_tx_hash" : "0xfcd8843c36b1c8fee81bcac7e7cf2b38682deef723e9a237918b70b3a6dfc4c9",
      "latest_tx_hash_xxhash64" : "0xdb73d04d0f5daa84",
      "latest_unit_height" : 1,
      "lock_balance" : 0,
      "lock_deposit_balance" : 0,
      "lock_gas" : 0,
      "nonce" : 1,
      "total_free_gas" : 25000,
      "total_gas" : 25000,
      "total_stake_gas" : 0,
      "unlock_disk_staked" : 0, 
      "unlock_gas_staked" : 0,
      "unused_free_gas" : 25000,
      "unused_stake_gas" : 0,
      "unused_vote_amount" : 0,
      "vote_staked_token" : 0,
      "zone_id" : 0
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "5"
}

# Transfer

Request Method

topj.transfer

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Object Before sending the transaction, you need to get the latest nonce and last_hash_xxhash64, and assign them to the account object to be used. You can directly run the "topjs.updateNonceAndLastHash" method, and these two parameters will be automatically put into the account object.
to Yes - String The address of the transaction receiving account, either an ordinary account or a contract account.
The receiver address is in the "account_addr" attribute under the "target_action" object.
note No Empty String String Transfer note.
amount Yes - Uint64 Transfer amount. The unit is uTOP.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.47:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.transfer(account,"T8000066ab344963eaa071f9636faac26b0d1a39900325", BigInteger.valueOf(140), "");
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
    "data":{
        "original_tx_info":{
            "authorization":"0x01ecc8e94deb97155f078a5d15ca982d7d67395787be17b53f6a3ad649cf5075ad13a8af3bf58a4c36e48f428dc160af5b41d5a3db648e05ba7ea06fc0f7241eb3",
            "challenge_proof":"",
            "ext":"",
            "from_ledger_id":0,
            "last_tx_hash":"8953296047531467839",
            "last_tx_nonce":19,
            "note":"",
            "premium_price" : 0,
            "send_timestamp":1600671092,
            "to_ledger_id":0,
            "tx_action" : {
               "receiver_action":{
                  "action_authorization":"",
                  "action_ext":"",
                  "action_hash":0,
                  "action_name":"",
                  "action_param":"0x000000008c0000000000000000000000",
                  "action_size":82,
                  "action_type":6,
                  "tx_receiver_account_addr":"T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"
               },
               "sender_action":{
                  "action_authorization":"",
                  "action_ext":"",
                  "action_hash":0,
                  "action_name":"",
                  "action_param":"0x000000008c0000000000000000000000",
                  "action_size":82,
                  "action_type":0,
                  "tx_sender_account_addr":"T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "tx_deposit":300000,
            "tx_expire_duration":100,
            "tx_hash":"0xd0a468822f5d983f468947b70a48489e90e5ff2806190f7ec16fe157662a8f53",
            "tx_len":323,
            "tx_random_nonce":0,
            "tx_structure_version":0,
            "tx_type":4,
            "xx64Hash":"0x412da7bf7cf8f4"
        },
        "tx_consensus_state":{
            "confirm_unit_info":{
                "exec_status":"success",
                "height":0,
                "recv_tx_exec_status" : "success",
                "tx_exec_status":"success",
                "unit_hash":"d47bc0df7cfc9d92b5d00ac71cd3a1cedfdf7956d55abd247304d678a87b5292",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":0
            },
            "recv_unit_info":{
                "height":0,
                "unit_hash":"073922013d27e7bc27cb5536ad2151472d5a7cca591087049493fdaf49fc1ee4",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":0
            },
            "send_unit_info":{
                "height":39,
                "tx_fee":0,
                "unit_hash":"98eebc38b0d6b38d9a935feb8bcf0c0d1219acaabcd22980e8042e0e17343bb7",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":798
            }
        }
    },
    "errmsg":"ok",
    "errno":0,
    "sequence_id":"1600671092156"
}

# Query Transaction

Request Method

topj.getTransaction

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
txHash Yes - String Transaction hash.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.47:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.getTransaction(account,"0xd0a468822f5d983f468947b70a48489e90e5ff2806190f7ec16fe157662a8f53");
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

Different transaction information is returned according to the different status of the transaction, as follows.

If the transaction is a single-account transaction, there is only one round of consensus under the transaction sender. Only the information of "confirm_unit_info" is returned in the result.

If the transaction is an across-account transaction, there are three rounds of consensus in total. The information of the three consensus, including "confirm_unit_info (the second round of consensus under the sender) ", "recv_unit_info(consensus under the receiver)" and "send_unit_info" (the first round of consensus under the sender) are returned in the result.

1.The transaction is in the block, but not in the transaction pool, and the transaction status is "confirmed", returning the original transaction information and all block information, as shown below.

Determine whether the transaction is successful or not according to the parameter "exec_status":

(1)When the value of exec_status is "success", it proves that the transaction is finally successful.

(2)When the value of exec_status is "failure", the transaction fails. At this time, the value of recv_tx_exec_status is "failure", indicating that the consensus under the receiver is failed.

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x005d19e04e77e99a0b9c029b0a247fe30009b3cc543db18bdb503b37e7d0788d50530437ef65583da62454bb4eafe2cf5e03952134a2ba08e84565e3d8e0aa893e",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 1,
         "last_tx_nonce" : 15813211746016799364,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1596523599,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000001027000000000000",
               "action_size" : 78,
               "action_type" : 6,
               "tx_receiver_account_addr" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000001027000000000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x0e4bcb020f2fdf6ed4105385a2d564b6ae33f7ae8d85563d471c7240713d8c5b",
         "tx_len" : 315,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 4
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 3,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "bd47732e8d959846c0302ab3582632e6c11e19c1d30f6578213fc4342de95b01",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 1,
            "unit_hash" : "f75ea49c50f4fe151931bc782468e0243880994393f0a8c30e8179597aaa5389",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 2,
            "tx_fee" : 0"unit_hash" : "80e4029f0ce8c2861ac89b5b9394ced6cf80161ebc899d22cb6d1a4afc8616b9",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 774
         }
      }
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "8"
}

2.The transaction is both in the block and the transaction pool, and the transaction status is "pending". The original transaction information and some valid block information are returned by the query.

As shown below, the transaction completes the first round of consensus and returns a valid information of "send_unit_info" when the second and third rounds of consensus have not yet been successful.

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01e561ef402c741267205afcef44c55dd4b63d8bd3541865ed54bab899e8bb4a14561c3023e018a887f39b11991ef80fb00e26ae646f09f4fffa0b95c1d3354896",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 626445491935432046,
         "last_tx_nonce" : 3,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1600856931,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000006400000000000000",
               "action_size" : 78,
               "action_type" : 6,
               "tx_receiver_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000006400000000000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xe4d16d17fba819fe2fe66172f354f5f37b8ffa02f28c15b0cade0356948fa660",
         "tx_len" : 315,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 4
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "height" : 0,
            "unit_hash" : "6a7801c5c10a093d0f5ce8e44eda97e6948e8cd79dc6264722fd6309d9a795b9"
         },
         "recv_unit_info" : {
            "height" : 0,
            "unit_hash" : "8c9ff2688d524c9e319e13bb3276b61f0fd0737bc2a8d8ae11ac423d9edb6e1a"
         },
         "send_unit_info" : {
            "height" : 6,
            "tx_fee" : 0,
            "unit_hash" : "4c973bf24d97dea94fbbd22a9271619a4a11bca5e0e04f0deff1587160aba9e4",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 945
         }
      }
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "18"
}

3.The transaction is not in the block, but in the transaction pool, the transaction status is "pending", only the original transaction information is returned, and the transaction consensus status is "null", as shown below.

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01e561ef402c741267205afcef44c55dd4b63d8bd3541865ed54bab899e8bb4a14561c3023e018a887f39b11991ef80fb00e26ae646f09f4fffa0b95c1d3354896",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 626445491935432046,
         "last_tx_nonce" : 3,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1600856931,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000006400000000000000",
               "action_size" : 78,
               "action_type" : 6,
               "tx_receiver_account_addr" : "T8000066ab344963eaa071f9636faac26b0d1a39900325"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000006400000000000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xe4d16d17fba819fe2fe66172f354f5f37b8ffa02f28c15b0cade0356948fa660",
         "tx_len" : 315,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 4
      },
      "tx_consensus_state" : null
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "17"
}

# Lock TOP For Gas

Snap56

Request Method

topj.stakeGas

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
locked_utop Yes - Uint64 Locked TOP token. The unit is "uTOP".

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.AccountInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.stakeGas(account, BigInteger.valueOf(4000));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x0072596cc19750c3f818b22058c201d06579a67f4ee9324789e359b31091c238634aea2cd31abc9e6418e071d184f4566b02d0d976e17110aa0823656c68156344",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 4806684555991511788,
         "last_tx_nonce" : 1,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603781915,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x00000000a00f000000000000",
               "action_size" : 78,
               "action_type" : 23,
               "tx_receiver_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x85f712cb3fcb55a710e58897df16184550c107704119a74c4ae26cece5d1b81c",
         "tx_len" : 303,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 22
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 3,
            "tx_exec_status" : "success",
            "unit_hash" : "049742dd5652884811573af3823704c704a01642920c810b5c08c486a95f7222",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 303
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "31"
}

# Unlock TOP For Gas

After initiating the unlock, you have to wait 24 hours and send a transaction (not a query) before the unlocked TOP tokens are received.

Request Method

topj.unStakeGas

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
unlocked_utop Yes - Uint64 Unlocked amount. The unit is "uTOP".

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.AccountInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;
import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.unStakeGas(account, BigInteger.valueOf(2000));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x014ebe3ec669f3a7a02a8d0de29ed7bc5e1a8b357d3fd4244e313110815a1ac2543e58b911b30c04e27b74ab601e512ac19ee51b8903ebfb7b635a69f17c637995",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 15658795022171383253,
         "last_tx_nonce" : 2,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603782021,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x00000000d007000000000000",
               "action_size" : 78,
               "action_type" : 24,
               "tx_receiver_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xc3cf9b1894b96eef6fe941235801f0a31dcfd8fbf7aee461ab3bb1b6bed93f22",
         "tx_len" : 303,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 23
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 4,
            "tx_exec_status" : "success",
            "unit_hash" : "507a149cdf7e96c40346eb71503d71ecc6880907f5b5397b67b111a8ce6e8895",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 303
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "35"
}

# Miner Operations

# Register Miner

TOP Network currently has three types of miners: edge miner, validator miner, and advance miner. You can register as one of these three types of miners.

Advance miner can serve as multiple nodes in different networks: validator, auditor, archive.

The minimum registration deposit of each node is shown in the table below.

Node Type Minimum Registration Deposit
edge 100,000*10^6 uTOP token
validator 500,000*10^6 uTOP token
advance 1,000,000*10^6 uTOP token
Full Node 0 uTOP token

Request Method

topj.registerNode

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
mortgage Yes - Uint64 Miner registration deposit, the unit is uTOP.
nodeType Yes - String There are four types of miners in TOP Network: edge, validator, advance, and Full node.
You can register as one of the types of miners.
After registering as an advance miner, what kind of node the mine is elected depends on the votes it receives:
If the advance miner is to be elected as auditor or archive node, the votes must be greater than or equal to the actual registration deposit of the miner (Here, the node deposit is calculated by TOP, not uTOP).
When the votes falls below the actual pledge deposit, the advance miner can only be elected as validator.
Caution:
Miner's votes must be voted by other nodes or by this node himself.
After registering as the advance miner, if you increase the miner deposit, the miner needs to increase the corresponding votes if it wants to be elected as audtior or archive.
nickName Yes - String Miner nick name, 4-16 characters, letters, Numbers or underscores.
node_sign_key Yes - String The account key pair is used as node_sign_key by default.
It is recommended that you use a asset-free public-private key pair to protect your account assets better, the private key is used to sign the node when it is working after they have been elected into the network.
Please enter the corresponding public key (Base64), which can be used by other nodes for decryption.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.registerNode(account, BigInteger.valueOf(1000000000000l), NodeType.advance, "topNode1", "BLpvINEyyUBE+w3TYDXDqfwRzjDW8yUuFgg63Tx4p2/mktmAdU13ugZZTnDfpR2/6Hgy5bOMkaA/3q6A7QtBT2U=");
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x016d9e819838f607969077eeff315affeda3bd394ae260a02dc12a5a063822c9f972eaa830eee4f0d7001b72e07322bfdc233e4401c7ec508c9bebd87a943ef364",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 1340984652899591420,
         "last_tx_nonce" : 3,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603783299,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "registerNode",
               "action_param" : "0x07000000616476616e636508000000746f704e6f64653158000000424c7076494e4579795542452b77335459445844716677527a6a445738795575466767363354783470322f6d6b746d416455313375675a5a546e44667052322f3648677935624f4d6b61412f33713641375174425432553d",
               "action_size" : 197,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000000010a5d4e8000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x5d89dc0e829f6f417133221794a276e9ca296beac4af70288fb1be4955648dcc",
         "tx_len" : 434,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 6,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "1a9c329fdd6e020f665a68e13d8a856a1554c7ce833cf8913cfb5fb187cd3d9c",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 9,
            "unit_hash" : "6bdf470bb218110f98de71e9dbfcd0bb68fa1dd069d2498b799a3484076f99e3",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 5,
            "tx_fee" : 100000000,
            "unit_hash" : "a5f110954666990a7da1e08ecd877b8b471ed93999fa9eff4e56cac60b1117cb",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 1302
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "40"
}

# Query Miner Information

Request Method

topj.queryNodeInfo

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
nodeAddress Yes - String Node account address.

Response Parameters

Parameter Name Parameter Type Description
account_addr String Miner account address.
auditor_credit String Auditor credit.
auditor_stake Uint64 Auditor stake: auditor stake=(miner deposit+vote amount/2)*auditor credit
dividend_ratio Integer Dividend ratio, percentage%, value[0,100]。
network_id String A value of 0 indicates that the node joins the mainchain network.
node_deposit Uint64 Miner registration deposit(uTOP).
nodename String Miner name.
registered_node_type String Registered miner type:
edge, validator, advance.
node_sign_key String Public key used in registering miner.
validator_credit String Validator credit.
validator_stake Uint64 Validator stake: validator stake=sqrt[(miner deposit+vote amount/2)*validator credit]
vote_amount Uint64 Total number of votes received from voting.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
       ResponseBase<NodeInfoResponse> nodeInfo = topj.queryNodeInfo(account, account.getAddress());
       System.out.println("node info > " + JSON.toJSONText(nodeInfo));
    }
}

Response Schema

{
   "data" : {
      "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "auditor_credit" : "0.100000",
      "auditor_stake" : 100000,
      "dividend_ratio" : 0,
      "network_id" : "0 ",
      "node_deposit" : 1000000000000,
      "node_sign_key" : "BLpvINEyyUBE+w3TYDXDqfwRzjDW8yUuFgg63Tx4p2/mktmAdU13ugZZTnDfpR2/6Hgy5bOMkaA/3q6A7QtBT2U=",
      "nodename" : "topNode1",
      "rec_stake" : 1000000,
      "registered_node_type" : "advance",
      "validator_credit" : "0.100000",
      "validator_stake" : 100000,
      "vote_amount" : 0,
      "zec_stake" : 1000000
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "41"
}

# Update Miner Type

Request Method

topj.updateNodeType

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
mortgage Yes - BigInteger Miner deposit.
nodeType Yes - String Miner type, all types are under the NodeType object.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.updateNodeType(account, BigInteger.valueOf(1000000000000l), NodeType.advance);
        System.out.println(JSONObject.toJSONText(result));
    }
}

# Set Miner Name

Request Method

topj.setNodeName

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
nickname Yes - String Miner nick name.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ff867b2ceb48f6bfc8a93d6c6aac05a29baad5da18ab5fb2bb9758379475fad8");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.setNodeName(account, "nick2");
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x0052387abd649c692a3b968afa9405ddcebfd9b376d2c61647b02321f181c722a74acfdd427e7af26012399b9b2211bbcdb2a680723effe3bd696565100a97146e",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 528724356827322285,
         "last_tx_nonce" : 9,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604058625,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "setNodeName",
               "action_param" : "0x050000006e69636b32",
               "action_size" : 90,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x775be6c8a765fda54e9a29755bd86d319b71cff03aa60b72ad7d68ea4962bca1",
         "tx_len" : 315,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 23,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "78d0b23386123461f58a99c9ad1f67802474e47360f0e1633002010ee5cc822f",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 5,
            "unit_hash" : "a36bf3cb8614e84976435787544af37bee582bdb3b411e20de1734d942623d92",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 22,
            "tx_fee" : 100000000,
            "unit_hash" : "99c518d9ba7689bf93cf63116f7e055cf023405ae93dad8b8de1f79052ee9559",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 945
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "21"
}

# Stake Deposit

You can increase the miner deposit to improve your comprehensive stake at any time.

Increasing the miner deposit does not change the type of miner you have registered.

Request Method

topj.stakeDeposit

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
mortgage Yes - BigInteger Increased miner deposit.

Response Parameter

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.stakeDeposit(account, BigInteger.valueOf(5000));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01a53df280500486c19d15eb045deec9fd0e8234ada70c1f81f3b0d1e53f989fb1696e20cede596cdf6ab68956b86b44b9278814635db0d37d2d997c2586341674",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 1109214534265249366,
         "last_tx_nonce" : 7,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604057962,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "stakeDeposit",
               "action_param" : "",
               "action_size" : 82,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x000000008813000000000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x9275db84b0add95ef74ea3a9e96439e91719063cacff58e4f24919b1008539d9",
         "tx_len" : 319,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 18,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "942847c62b996034ae5fd0f8580a5f2af22f71180ef9e5c2d500fefa963226b8",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 3,
            "unit_hash" : "525ad899919f1f07d1c262c34fa02b1980425e6b41908cda28126cc06ad5e9b1",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 17,
            "tx_fee" : 100000000,
            "unit_hash" : "66ae53aca7cf9c1c7f98630d7b33eac40981897a6490f4e4788f497b1c9c59b8",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 957
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "13"
}

# Unstake Deposit

You can reduce the miner deposit at any time. Reducing the deposit will not change the type of miner you registered. But the reduction of the deposit will fail if the miner's deposit balance is lower than the minimum deposit requirement for the current type of miner.

Request Method

topj.unStakeDeposit

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
mortgage Yes - BigInteger Decreased miner deposit.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.unStakeDeposit(account, BigInteger.valueOf(3500));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01ffcb1b559f27098874a202bb180be13e6c70c9afb2aff8d0a4a4b45e14a44fb8446f84f6c58efcd1784a4da70081d6f7836dfdfd42f7bc7fab652d7eedde3d2b",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 7431771654725850424,
         "last_tx_nonce" : 10,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604058791,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "unstakeDeposit",
               "action_param" : "0xac0d000000000000",
               "action_size" : 92,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xbbee57e4d8af13c82683859e315c53ba5b323867e550aa9a3a7010687f312eaa",
         "tx_len" : 317,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 25,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "a64aed635209481487f5ce1b1a5954962ba914dde5e1cde3553b93f7e2146bdf",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 6,
            "unit_hash" : "fc2db79b768197918f3f468e570fb3fbbaaa62e42edcf9d7e3db5f15d1feda34",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 24,
            "tx_fee" : 100000000,
            "unit_hash" : "d414220d54bda29d0570bfdd77a0f291fe6297293c61a968d8b39b56c73a9a83",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 951
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "31"
}

# Set Dividend Ratio

Request Method

topj.setDividendRate

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
dividendRate Yes - BigInteger Dividend ratio∈ [0 ~ 100].

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.setDividendRate(account, BigInteger.valueOf(95));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x00617e9af79871f205facea1579a631bba0a9489f314eebd86919fc78e69427d4c365731e88be1b86b51712727223fbc340af794f19f2aed61cee4b842320aee48",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 15638817897079963913,
         "last_tx_nonce" : 8,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604058128,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "setDividendRatio",
               "action_param" : "0x3200000000000000",
               "action_size" : 94,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xb1fea03a8bb5c46fedc52ec7a578d64ec519e51ed54358e2c9c326869787cc12",
         "tx_len" : 319,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 20,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "2e94fcb1d732d2efb2c8c23511dd368202d12fa555744b6774ec3cf104dec67f",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 4,
            "unit_hash" : "98b9ec8231b5da2baa3a5907f4aaf9f63bf2dbc9ff6d481384ec5fbe51ec4a47",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 19,
            "tx_fee" : 100000000,
            "unit_hash" : "236eb20d76cfd9167ac234b1d36babb521068e372941eddc76a779794dc4186d",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 957
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "17"
}

# List Votes Used

Request Method

topj.listVoteUsed

**Request Parameters **

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
voterAddress Yes - String Voter account address.

Response Parameters

Parameter Name Parameter Type Description
vote_infos Map Array Account address of node be voted(String); Amount of votes(Integer).

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.VoteUsedResponse;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<VoteUsedResponse> result = topj.listVoteUsed(account, "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba");
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
    "data":{
        "vote_infos":{
            "T80000fd4f433c036268f17a1b4204ea907e70618d030e":10000,
            "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba":5000
        }
    },
    "errmsg":"OK",
    "errno":0,
    "sequence_id":"1603877877200"
}

# Unregister Miner

The TOP Network miners need to unregister first before exiting the network.

  • Miner unregistration needs to initiate by the miner voluntarily.
  • After the unregistration , the miner registration deposit will not be immediately returned to the miner account and will be locked for a period of time.
  • After the expiration of the locked registration deposit, the miner shall redeem the deposit voluntarily, and the system will not automatically return it.

Request Method

topj.unRegisterNode

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.unRegisterNode(account);
        
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x0184836e54ed29d37e0a0a0b3d9199ddf2a60ed2cd23016a0f223bbd5d9d3bccb206666b7053dab3acc69734bcca23ea62bab7279b999ec8ed2211e8d529cd7af6",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 17668198504909011542,
         "last_tx_nonce" : 4,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603783750,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "unregisterNode",
               "action_param" : "",
               "action_size" : 84,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xb765e6331af2ba4976541f35c2f9b36fc576b2e437844261d49bd3d6d2f7b89b",
         "tx_len" : 309,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 8,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "d26ebb72b19c348ba30ebccfbc7f1e525f7836064468013b43b43f01f11c36e4",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 10,
            "unit_hash" : "44f8364e97ee330dac3fe9283abec1e2071095dd6a08d186862831d63580d00e",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 7,
            "tx_fee" : 100000000,
            "unit_hash" : "8a28431ebb29853edddaa32c78c1bd672b5b1a80619afaca19f2a4168aa94d13",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 927
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "46"
}

# Redeem Miner Deposit

After the unregistration , the miner registration deposit will not be immediately returned to the miner account and will be locked for 72 hours.

After the expiration of the locked registration deposit, the miner shall redeem the deposit voluntarily, and the system will not automatically return it.

Request Method

topj.redeemNodeDeposit

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.property.NodeType;
import org.topj.methods.response.NodeInfoResponse;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.redeemNodeDeposit(account);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01ace90aad93209164cc3976520d2393043b88e8ba151c69f4c0ff79caabd586b60cf5887b99db8cf3729e0e6e84d443ae3bc859fad75f44a1200d18e164db8258",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 5154942665457376997,
         "last_tx_nonce" : 5,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603783905,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "redeemNodeDeposit",
               "action_param" : "",
               "action_size" : 87,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x22e076b89df6795434e8dc86460b5e6157642a906d83b1eec8d2fac1d522d9fd",
         "tx_len" : 312,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 10,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "b4d2d5ed1eb7a29a706eafaba69fded704a1b2155757598f9adec45eaa4d043e",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 11,
            "unit_hash" : "b14b2f771b6b8311fb6aa86288dd8069ad729ceccd355aa702c237de170684dc",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 9,
            "tx_fee" : 100000000,
            "unit_hash" : "73f642b73ec9bc7ac27032261d921b04dabb9fb6ab2561baa7ba2a9a928d1db5",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 936
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "51"
}

# staking

# Lock TOP For Votes

Rules for exchanging votes:

locked TOP token=votes_amount / [ 1.04^(lock_duration / 30 - 1) ], lock_duration<570;

locked TOP token=vote_amount / 2, lock_duration>=570。

The longer the lock duration is, the fewer TOP tokens are locked for the same number of votes.

Request Method

topj.stakeVote

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
amount Yes - Uint64 Amount of votes to be exchanged.
lockTime Yes - String TOP token lock duration. The the unit is "day".
The lock duration must be at least 30 days and must be an integer multiple of 30.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.stakeVote(account, BigInteger.valueOf(4000), BigInteger.valueOf(30));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x00b32a8919897bf831e5b170433d1ea94b3d0ede691351f69a21f50b4330185aaa26020efe06d3db0c921b9fb511512a4452f80f7c5824489d565b3e908bf39dcf",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 17575575409295805570,
         "last_tx_nonce" : 6,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603784377,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0xa00f0000000000001e00",
               "action_size" : 76,
               "action_type" : 21,
               "tx_receiver_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x4944c384a7b0cb848ed6790a4692c298544f3eebf71622d312892cbdd18a186f",
         "tx_len" : 301,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 27
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 12,
            "tx_exec_status" : "success",
            "unit_hash" : "b7e8bd018a26c5f71e39c601703c02e66944e9493ff789735fdb7a7e75e8a4c3",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 301
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "55"
}

# Unlock TOP For Votes

During the lock duration, the TOP tokens cannot be unlocked, only the TOP tokens at its expiry can be unlocked.

The TOP tokens that are locked corresponding votes that are already in use cannot be unlocked.

After initiating the unlock process, we have to wait 24 hours for the TOP token to return to the account.

Request Method

topj.unStakeVote

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
amount Yes - Uint64 Votes amount, unlock the corresponding TOP token.
note Yes - String Transaction note.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.193:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.unStakeVote(account, BigInteger.valueOf(1998));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x00dbb57645b28dc9261bc89c3b403f219c68b00da07d673d5ccb1930f042b8b75e62950579327682a79184e8cb502a5d9639a6d53e5293f52a47842ef965fdd98e",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 7288822057977092395,
         "last_tx_nonce" : 7,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603784708,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0xce07000000000000",
               "action_size" : 74,
               "action_type" : 22,
               "tx_receiver_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x6245bed2227b7ff56d5bf6ae239685993f81b65990fe55f2b686e0d189ba50b1",
         "tx_len" : 299,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 28
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 13,
            "tx_exec_status" : "success",
            "unit_hash" : "c192c146d659f023a79eade70b513ec05def9e75a47f3309d7885f2f746fefd2",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 299
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "59"
}

# Vote On Miners

Please make sure that you have enough unused votes in your miner account before voting. You can use topj.getAccoun to query. If you do not have enough votes in your account, you can exchange votes by command topj.stakeVote.

Accounts on the block chain can vote for miners to obtain rewards:

  • An account can vote for up to 10,000 miners currently.

  • After voting on a miner, a portion of the reward won by the miner will be given to the voter.

Request Method

topj.voteNode

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Voter account object.
voteInfo Yes - Map<String, BigInteger> key: miner account address; value: votes number.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;
import java.util.HashMap;
import java.util.Map;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        Map<String, BigInteger> voteInfo = new HashMap<>();
        String nodeAddress = "T80000fd4f433c036268f17a1b4204ea907e70618d030e";
        voteInfo.put(nodeAddress, BigInteger.valueOf(500));
        ResponseBase<XTransactionResponse> result = topj.voteNode(account, voteInfo);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x00423255bcc2eebb0812a7fe1b329a1a5e34f4638c04f74867d77fd8a3db5ebffc6b9aff9a9a0644facc4330919b6741ff48e4fcc1088161238300ad8ecf6355d7",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 13426001444774114246,
         "last_tx_nonce" : 9,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603785283,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "voteNode",
               "action_param" : "0x0100000026000000542d302d4c62754b6844477246474266744863616e4e4c425975756a646d4a4c625548766337f401000000000000",
               "action_size" : 128,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T20000MVfDLsBKVcy1wMp4CoEHWxUeBEAVBL9ZEa@228"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xa6f7fe89494e09e559a08b2b3a5b0add4870fe64a1ee27ef0f5769a6e3875a19",
         "tx_len" : 353,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 20
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 17,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "2dff0df66b5183abd6676c97e515119a0222ff5aa2bd800110b6706a1b33d443",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 2,
            "unit_hash" : "f31af4661755eaf356828a9af2a6ab1a4c1efc12719752b291eb84b59ed65112",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 16,
            "tx_fee" : 0,
            "unit_hash" : "d91e29ea0323dd3f214740c225f31a209ea69562b135891675fc059521c88c33",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 1059
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "76"
}

# Unvote On Miners

A voter may cancel votes at any time that has already been vote on a miner.

The number of votes for each cancellation operation is unlimited, but cannot exceed the total number of votes vote on the nodes, otherwise the cancellation operation will fail.

After voting for the miner, even if the miner is unregistered, the votes will not be returned to your account. You need to initiate the cancellation operation.

You can cancel voting for miners in bulk.

Request Method

topj.unVoteNode

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Voter account address.
voteInfo Yes - Map<String, BigInteger> key: Miner account address; value: votes number.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;
import java.util.HashMap;
import java.util.Map;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        Map<String, BigInteger> voteInfo = new HashMap<>();
        String nodeAddress = "T80000fd4f433c036268f17a1b4204ea907e70618d030e";
        voteInfo.put(nodeAddress, BigInteger.valueOf(500));
        ResponseBase<XTransactionResponse> result = topj.unVoteNode(account, voteInfo);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01d30d6a07bdf731d9f2dc474ad0859b5943fc5716245e49d34e42cc89fc16110824166ab6b0fee7f97144b71a29bffc12ae947a180882fb2516d3e461f5fc474a",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 13503167813048190902,
         "last_tx_nonce" : 10,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603785648,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "unvoteNode",
               "action_param" : "0x0100000026000000542d302d4c62754b6844477246474266744863616e4e4c425975756a646d4a4c625548766337f401000000000000",
               "action_size" : 130,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T20000MVfDLsBKVcy1wMp4CoEHWxUeBEAVBL9ZEa@228"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 1,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x6de1eccd314530f0b3a50154c18d63e441943c419a8395d6012e518bcdea77a9",
         "tx_len" : 355,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 21
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 19,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "edd8f2edc551fc1608f3bb0a6f39a594061b7fc04cac635fdbb010a834711b7f",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 5,
            "unit_hash" : "12d058cdd0351048812672b44bb1d0b53e1353c48904d13381026928c0628a49",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 18,
            "tx_fee" : 0,
            "unit_hash" : "71136c6c1c3db2a54c36996a5a16b110759f0a5bef1fd962d9fffb1bced1f28c",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 1065
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "80"
}

# Query Voter Dividend

After you vote on the miners, you can get the corresponding voting dividends, and the dividend ratio is set by the miners being voted.

Voter dividend is not immediately searchable and can be queried 6 hours after voting.

Request Method

topj.queryVoterDividend

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Voter account object.
nodeAddress Yes - String Voter account address.

Request Parameters

Parameter Name Parameter Type Description
accumulated Uint64 Total amount of voter dividend.The unit is uTOP.
last_claim_time Uint64 Clock height of the last time to claim voter dividend.
node_dividend List Dividend information of the miner.
account_addr String Account address of the miner.
accumulated Uint64 The dividend given to the voter by the miner. The unit is uTOP.
last_claim_time Uint64 The height of the clock at which the dividend of the miner was last claimed.
unclaimed Uint64 The unclaimed dividend given to the voter by the miner. The unit is uTOP.
unclaimed Uint64 The total amount of dividends the voter has not claimed. The unit is uTOP.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.reward.VoterDividendResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<VoterDividendResponse> result = topj.queryVoterDividend(account, account.getAddress());
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
         "accumulated" : 6994245799976,
         "accumulated_decimals" : 419004,
         "issue_time" : 3535500,
         "last_claim_time" : 0,
         "node_dividend" : [
            {
               "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
               "accumulated" : 6994245799976,
               "accumulated_decimals" : 419004,
               "issue_time" : 3535500,
               "last_claim_time" : 0,
               "unclaimed" : 6994245799976,
               "unclaimed_decimals" : 419004
            }
         ],
         "unclaimed" : 6994245799976,
         "unclaimed_decimals" : 419004
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "1"
}

# Claim Voter Dividend

The system will issue voter dividends every 24 hours and automatically distribute voter dividends to the dividend pool.

The voter can apply for withdrawal once within 24 hours, and the withdrawal will be received immediately after the application is initiated.

Request Method

topj.claimVoterDividend

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Voter account object.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.claimVoterDividend(account);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x015e5aea769d3731c859ecccce438a9f32a38500c50601682ad1b0ce9d7adec60a216c460f52742e4000cd802cae7875058f77b2a71119012c00c36fadd5e11466",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 8346055492206021528,
         "last_tx_nonce" : 11,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603788080,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "claimVoterDividend",
               "action_param" : "",
               "action_size" : 84,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T20000MT3itmNbWs4XYn8R1NUcoucmppJwN7qE69@228"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x015ccae65496623557522ea5553db507f5c81ee854046d207f5cfd38bd04ab1d",
         "tx_len" : 309,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 21,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "52b68c8db349e20199be2afbe9e78938f1f31ea75e73695fac3e0dd8bf28f1d8",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 3,
            "unit_hash" : "20fac0960687f4d70ed4c124daa785891d3935377daae758d58240e94a9398ff",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 20,
            "tx_fee" : 0,
            "unit_hash" : "2e859716a101520de03ffd09181c64d8482f380fe6da959105d99ab1982d72db",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 927
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "86"
}

# Query Miner Reward

Miner reward includes workload reward and votes reward.

Request Method

topj.queryNodeReward

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
nodeAddress Yes - String Miner account address.

Response Parameters

Parameter Name Parameter Type Description
accumulated Uint64 Total amount of miner reward. The unit is uTOP.
issue_time Uint64 The clock height when each miner's reward is issued.
last_claim_time Uint64 Clock height of the last time to claim miner reward.
unclaimed Uint64 Unclaimed reward. The unit is uTOP.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.reward.NodeRewardResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<NodeRewardResponse> result = topj.queryNodeReward(account, account.getAddress());
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
         "accumulated" : 188072630515731,
         "accumulated_decimals" : 209604,
         "issue_time" : 3533760,
         "last_claim_time" : 0,
         "unclaimed" : 188072630515731,
         "unclaimed_decimals" : 209604
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "49"
}

# Query All Miner Reward

Miner reward includes workload reward and votes reward.

Request Method

topj.queryAllNodeReward

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.

Response Parameters

Parameter Name Parameter Type Description
accumulated Uint64 Total amount of miner reward. The unit is uTOP.
issue_time Uint64 The clock height when each miner's reward is issued.
last_claim_time Uint64 Clock height of the last time to claim miner reward.
unclaimed Uint64 Unclaimed reward. The unit is uTOP.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.reward.NodeRewardResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ff867b2ceb48f6bfc8a93d6c6aac05a29baad5da18ab5fb2bb9758379475fad8");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<Map<String, NodeRewardResponse>> result = topj.queryAllNodeReward(account);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "T8000066ab344963eaa071f9636faac26b0d1a39900325" : {
         "accumulated" : 188072630515731,
         "accumulated_decimals" : 209604,
         "issue_time" : 3533760,
         "last_claim_time" : 0,
         "unclaimed" : 188072630515731,
         "unclaimed_decimals" : 209604
      },
      "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba" : {
         "accumulated" : 135157655656316,
         "accumulated_decimals" : 441988,
         "issue_time" : 3533760,
         "last_claim_time" : 0,
         "unclaimed" : 135157655656316,
         "unclaimed_decimals" : 441988
      }
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "49"
}

# Claim Miner Reward

Miner reward can be received at most once every 24 hours.

Request Method

topj.claimNodeReward

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Miner account object.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> result = topj.claimNodeReward(account);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01a28b0ed68e2ead15083616945a92e737be520eb73ab4bb8700d9e16b0f5d4d797068762f3fc5ea060064f5e0694b139a57a5cc96a898f60b2bcae2344b4f3775",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 2325913416141072335,
         "last_tx_nonce" : 4,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603797213,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "claimNodeReward",
               "action_param" : "",
               "action_size" : 81,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T20000MT3itmNbWs4XYn8R1NUcoucmppJwN7qE69@155"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T8000085a8e8acd53c72dca85dcb002a6710796975b4ba"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x92a7f8d2456d063ff772a97e4432481d28f9d2e9b3c876cf8e3ccbfa8cdf5c96",
         "tx_len" : 306,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 11,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "287bbf07214842d62c6239747c7168b941c46dbf6aa6e84d9de2b80668533cba",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 70,
            "unit_hash" : "00f4f97eaa3d080d05d6103540c4022f93789af7315db03505f71848fddb0d90",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 10,
            "tx_fee" : 0,
            "unit_hash" : "34ee08c46b7501a859f45bb057e58d8a1d2a73a26d2ca778dbcaed0892d2f751",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 918
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "26"
}

# Proposal

# Submit Proposals

When governing on the chain, you first need to submit an on-chain governance proposal.

Any user can submit a proposal as long as a certain TOP tokens are pledged.

In addition to the minimum transaction deposit of 100,000 uTOP token, the transaction fee of 100*10^6 uTOP token shall be deducted for running Beacon system contract transaction.

So make sure you have at least 100.1*10^6 uTOP balance in your account before submitting your proposal.

# On-Chain Governance Parameter Modification Proposals

Support the modification of Beacon transaction fees, account free gas, transaction margin and other On-chain Governance Parameters through proposals.

The system will issue governance rewards and zero workload rewards to the community fund account, community users can transfer these rewadrs to the burn account via community fund management proposal. Once the proposal has been voted through by TCC, the burn will take effect.

community fund account address: T2000138QMHWxXshXyZa1E48JU1LREu3UrT5KGD2U@0.

burn account address: T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug.

Request Method

topj.submitProposal

Request Parameters

Parameter Name Required Default Value Parameter Type Description
proposal_type Yes - Uint8 Proposal Type:1--on-chain governance parameter modification proposal;2--community fund management proposal.
target Yes - String On-Chain Parameter Modification Proposal: Target is on-chain governance parameter, more about on-chain governance parameter please refer to On-Chain Governance Prarameters . Community Fund Management Proposal: Target is burn account address: target is T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug.
value Yes - String When target is on-chain governance parameter, value=new parameter value. When target is burn account address, value=transferd amount, the unit is uTOP.
proposal_deposit Yes - Uint64 Proposal deposit, current is "0".
effective_timer_height Yes - Uint64 Proposal effective clock height. If the clock height is less than the clock height at which the proposal was approved, the proposal will take effect immediately.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.Model.Proposal;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);

        ResponseBase<XTransactionResponse> result = topj.submitProposal(account, BigInteger.TWO, "T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug", "T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ua", BigInteger.valueOf(100000000l), BigInteger.valueOf(18400));
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x00055639267a80ec634048de50017a194407e092a849f3689fb4a907d4787ad3da3a0c99344f19366204a45cb4c0acd456d95a63f5c5671fc6e4efb75cd0591074",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 17353520882089532145,
         "last_tx_nonce" : 5,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1603797973,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "submitProposal",
               "action_param" : "0x0d0000006d696e5f766f7465735f6e756d010000003101e803000000000000",
               "action_size" : 115,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138QMHWxXshXyZa1E48JU1LREu3UrT5KGD2U@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "0x0000000000e1f50500000000",
               "action_size" : 78,
               "action_type" : 0,
               "tx_sender_account_addr" : "T80000fd4f433c036268f17a1b4204ea907e70618d030e"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x7d46fcbf2932605d06a83249a73843f2429b7f681fb3a1b39aff6d5378c557e6",
         "tx_len" : 352,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 14,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "92e0cc560569c3fef734e30e228528d59dbed054b68964dd9fb5e1c358acb82f",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 54,
            "unit_hash" : "80bb6ada286f4ffc1235fef5151a82ff8fad78ee797af6d064d0827d60827d90",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 13,
            "tx_fee" : 100000000,
            "unit_hash" : "c9aadf4688b1bce6337ffd77b1ef06edb148cda682e7b5cac750bb8e4064c5bb",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 1056
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "31"
}

# Withdraw Proposal

A proposal can only be withdrawn by it's sponsor.

Request Method

topj.withdrawProposal

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
proposalId Yes - String Proposal ID.

Response Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.Model.Proposal;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);

        Proposal proposal = new Proposal();
        proposal.setProposalId("sss");
        ResponseBase<XTransactionResponse> result = topj.withdrawProposal(account, proposal.getProposalId());
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x01cea8b3328ae1bc2c4ced3a584d2acb895938754859e46a89fbdd954e2488947e12ab0732457ed9ccfc91e2ba23bee2e1b96df3d8c6625143a33c6353d897fe9b",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 1339320303636985063,
         "last_tx_nonce" : 5,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604047180,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "withdrawProposal",
               "action_param" : "0x0100000031",
               "action_size" : 91,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138QMHWxXshXyZa1E48JU1LREu3UrT5KGD2U@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0xbeb7b03488646c051485b5979cba9ab2c30a75d568677c30182d1db932fa4763",
         "tx_len" : 316,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 9,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "0392946766b6a9908afb1950a71d9e25ede336d3bfb18bd8c5afc23c197acd76",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 2,
            "unit_hash" : "2326f7ff4d666fbc1a21125ccd90d11f36db47ef8f2eb4938a13155418b25b4a",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 8,
            "tx_fee" : 100000000,
            "unit_hash" : "a310bca7c898a0417fc34730a1e22595d3f2c5186f133a4018105e28faaa79a6",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 948
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "27"
}

# Query Proposal

Request Method

topj.queryProposal

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Account object.
proposalId Yes - String Proposal ID.

Response Parameters

Parameter Name Parameter Type Description
effective_timer_height Uint64 Proposal effective clock height. If the clock height is less than the clock height at which the proposal was voted through, the proposal will take effect immediately.
expire_time String Proposal expiration time. If the proposal is not approved or rejected by TCC within 259,200 clock height, the proposal will become invalid.
priority Uint8 Proposal priority: 1--Normal;2--Important;3--Critical. Only the TCC members have the right to vote on a proposal.
proposal_account_addr String The account address of the initiator of proposal.
proposal_deposit Uint64 Proposal deposit, the minimum is 100*10^6 uTOP.
proposal_id String Proposal ID, automatically generated by the system, unique.
proposal_type Uint8 Proposal Type: 1--on-chain parameter modification proposal;2--community fund management proposal.
target String On-Chain Governance Parameter Modification Proposal: Target is on-chain governance parameter, more about on-chain governance parameter please refer to On-Chain Governance Prarameters. Community Fund Management Proposal: Target is burn account address: T!0001Ebj8hBvoLdvcEEUwNZ423zM3Kh9d4nL1Ug.
value String When target is on-chain governance parameter,value=new parameter value. When target is burn account address,value=transfer amount, the unit is uTOP.
voting_status Uint16 Voting status of the proposal: 0-- not begun; 8-- In progress; 9 - failure; 10 - success.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.Model.Proposal;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);

        Proposal proposal = new Proposal();
        proposal.setProposalId("sss");
        ResponseBase<Proposal> result = topj.queryProposal(account, proposal.getProposalId());
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
    "data" : {
       "effective_timer_height": 1010110,
       "expire_time": 1000
       "priority": 3,
       "proposal_deposit": 400,
       "proposal_id": 1,
       "proposal_type": 1,
       "proposal_account_addr": "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
       "target": min_stake_votes_num
       "value": 1
       "voting_status": 0
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "3"
}

# TCC Vote On Proposals

You can get detailed information about the proposal before you vote on a proposal.

Only the TCC members have the right to vote on a proposal. Rules for voting on proposals:

The approval of 2/3 of the members is required, and no more than 1/5 of the opposition members.

After the proposal is voted through, a legislative order will be formed and sent to all nodes of the network.

After a proposal is voted through, the system will automatically delete the proposal, unable to query the proposal.

Request Method

topj.tccVote

Request Parameters

Parameter Name Required Default Value Parameter Type Description
account Yes - Account Voter account object.
proposalId Yes - String Proposal ID.
proposalClientAddress Yes - String Proposer account address.
option Yes - Boolean Voting opinion: true or false.

Request Parameters

Please refer to Description of Transaction Body Object.

Request Sample

package org.sawyer;

import com.alibaba.fastjson.JSONObject;
import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.Model.Proposal;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);

        Proposal proposal = new Proposal();
        proposal.setProposalId("sss");
        String clientAddress3 = "T80000fd4f433c036268f17a1b4204ea907e70618d030e";
        ResponseBase<XTransactionResponse> result = topj.tccVote(account, proposal.getProposalId(), clientAddress3, true);
        System.out.println(JSONObject.toJSONText(result));
    }
}

Response Schema

{
   "data" : {
      "original_tx_info" : {
         "authorization" : "0x011ba5097a4b5a1f54776ec20bf2ca002fe259c51ff9f72a36882e1985239008e97ac8d49d12f768c1a2abadaf3b5e368a4ffeb6ab64c68f323192155fd1116409",
         "challenge_proof" : "",
         "ext" : "",
         "from_ledger_id" : 0,
         "last_tx_hash" : 11205396108775716568,
         "last_tx_nonce" : 6,
         "note" : "",
         "premium_price" : 0,
         "send_timestamp" : 1604050651,
         "to_ledger_id" : 0,
         "tx_action" : {
            "receiver_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "tccVote",
               "action_param" : "0x010000003501",
               "action_size" : 83,
               "action_type" : 5,
               "tx_receiver_account_addr" : "T2000138QMHWxXshXyZa1E48JU1LREu3UrT5KGD2U@0"
            },
            "sender_action" : {
               "action_authorization" : "",
               "action_ext" : "",
               "action_hash" : 0,
               "action_name" : "",
               "action_param" : "",
               "action_size" : 66,
               "action_type" : 0,
               "tx_sender_account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87"
            }
         },
         "tx_deposit" : 100000,
         "tx_expire_duration" : 100,
         "tx_hash" : "0x3ba14855d285087e60f257f703c1b9f070afa7d1a81c05a5662b4a2fe9f0320e",
         "tx_len" : 308,
         "tx_random_nonce" : 0,
         "tx_structure_version" : 0,
         "tx_type" : 3
      },
      "tx_consensus_state" : {
         "confirm_unit_info" : {
            "exec_status" : "success",
            "height" : 14,
            "recv_tx_exec_status" : "success",
            "tx_exec_status" : "success",
            "unit_hash" : "540746c16ac538de15f3d1f1a734ead7576fbd94dd99a5b8e5706efbe3aa49b5",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "recv_unit_info" : {
            "height" : 452,
            "unit_hash" : "5089993bf9ea2c74e5d82fd6ab19fa0dd13a56b7e506abd17aca2645f655f21e",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 0
         },
         "send_unit_info" : {
            "height" : 13,
            "tx_fee" : 100000000,
            "unit_hash" : "113cd7f87440097999b01e54aba194d94d8784bba49f3cd4b40f86a05c10fa78",
            "used_deposit" : 0,
            "used_disk" : 0,
            "used_gas" : 924
         }
      }
   },
   "errmsg" : "OK",
   "errno" : 0,
   "sequence_id" : "11"
}

# Tools

# Parse Out The amount and note In The Transfer Transaction Body

Parse out the "amount" and "note" in the transfer transaction body and assign them to the "TransferActionParam" object.

Request Method

TransferActionParam.decode

Request Parameters

Parameter Name Required Default Value Parameter Type Description
actionParam Yes - String Action parameters.

Response Parameters

None.

Request Sample

package org.sawyer;

import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.Model.TransferActionParam;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> transferResponseBase = topj.transfer(account,"T800002276a7d58218ac4978733e5cca927a7d86cb7c87", BigInteger.valueOf(140), "hello top");
        TransferActionParam transferActionParam = new TransferActionParam();
        transferActionParam.decode(transferResponseBase.getData().getOriginalTxInfo().getReceiverAction().getActionParam());
    }
}

Response Schema

None.

# Check Whether The Transaction Is Successful

Take the transfer transaction as an example:

  • Get XTransaction object and transaction hash from transaction object;
  • Call topj.getTxStatus(), "success" means the transaction is successful, "failure" means the transaction is failed; "pending" means the transaction is still being executed, "null means the transaction cannot be found.
package org.sawyer;

import org.topj.account.Account;
import org.topj.core.Topj;
import org.topj.methods.response.ResponseBase;
import org.topj.methods.response.tx.XTransactionResponse;
import org.topj.procotol.http.HttpService;
import org.topj.tx.PollingTransactionReceiptProcessor;

import java.io.IOException;
import java.math.BigInteger;

public class main {
    private static Topj topj = null;
    private static Account account = null;
    public static void main(String[] args) throws IOException {
        HttpService httpService = new HttpService("http://192.168.50.26:19081");
        topj = Topj.build(httpService);
        topj.setTransactionReceiptProcessor(new PollingTransactionReceiptProcessor(5000, 10));
        account = topj.genAccount("ec8519c723649ab2170807d39a9d01be1a6197266cfe39b4cc66c0433df85321");
        topj.passport(account);
        topj.getAccount(account);
        ResponseBase<XTransactionResponse> transferResponseBase = topj.transfer(account,"T800002276a7d58218ac4978733e5cca927a7d86cb7c87", BigInteger.valueOf(140), "hello top");
        String txHash = transferResponseBase.getData().getOriginalTxInfo().getTxHash();
        String isSuccess = topj.getTxStatus(account, txHash);
        System.out.println("transfer hash >> " + txHash + " >> is success > " + isSuccess);
    }
}

# Transaction Body Data Structure

{
    "data":{
        "original_tx_info":{
            "authorization":"0x01aefd0a118c48fd7846f3ee05a2728a55141ebf3fe94e6076cd1fd1bef295140f356bb10a12dd6731d8ab50332d57ced26f6379162d0eb8fd87871603d8380056",
            "challenge_proof":"",
            "ext":"",
            "from_ledger_id":0,
            "last_tx_hash":"11448926042541027033",
            "last_tx_nonce":3,
            "note":"",
            "premium_price" : 0,
            "receiver_action":{
                "action_authorization":"",
                "action_ext":"",
                "action_hash":0,
                "action_name":"registerNode",
                "action_param":"0x040000006564676508000000746f704e6f6465310a0000007075626c6963206b6579",
                "action_size":116,
                "action_type":5,
                "tx_receiver_account_addr":"T2000138DSqqwBWkHKxkVuCq3htW47BGtJRCM2paf@0"
            },
            "send_timestamp":1600766121,
            "sender_action":{
                "action_authorization":"",
                "action_ext":"",
                "action_hash":0,
                "action_name":"",
                "action_param":"0x000000000010a5d4e800000000000000",
                "action_size":82,
                "action_type":0,
                "tx_sender_account_addr":"T8000066ab344963eaa071f9636faac26b0d1a39900325"
            },
            "to_ledger_id":0,
            "tx_deposit":300000,
            "tx_expire_duration":100,
            "tx_hash":"0x4ce54b11e728fbd65745873a9e831d39516fd0ea326ef055de76a9efd8d25783",
            "tx_len":357,
            "tx_random_nonce":0,
            "tx_structure_version":0,
            "tx_type":3,
            "xx64Hash":"0xa1b759352d90776c"
        },
        "tx_consensus_state":{
            "confirm_unit_info":{
                "exec_status":"",
                "height":0,
                "tx_exec_status":"",
                "unit_hash":"f45195cc04590c98aa12d8676bd5585de291620e1b76377ec46d0f1d8376a302",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":0
            },
            "recv_unit_info":{
                "height":3,
                "unit_hash":"b76a433d5a53392cd811f4d2ae06f357c49fd89cf97efdb955033723aaea1c4f",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":0
            },
            "send_unit_info":{
                "height":6,
                "tx_fee":100000000,
                "unit_hash":"a39ef9be02b3c301f50aeeddc1c474871f47104dbc4ef063fda9892a51dc99b3",
                "used_deposit":0,
                "used_disk":0,
                "used_gas":1071
            }
        }
    },
    "errmsg":"ok",
    "errno":0,
    "sequence_id":"1600766121429"
}

# Description of Transaction Body Object

Parameter Name Parameter Name Description
original_tx_info Object Original transaction information.
authorization String Transaction body signature.
challenge_proof String The reserve parameter, default to empty String.
ext String The reserve parameter, default to empty String.
from_ledger_id Uint16 The reserve parameter, default to "0".
last_tx_hash String The hash of the previous transaction ,used for transaction sorting and removing duplicates.
last_tx_nonce Uint64 The nonce of the previous transaction ,used for transaction sorting and removing duplicates.
note String Transaction note.
premium_price Uint32 The reserve parameter, default to "0".
send_timestamp Uint64 Transaction send timestamp.
to_ledger_id Uint16 The reserve parameter, default to "0".
tx_action Object Transaction action, including "source_action" and "target_action"。
receiver_action Object Transaction receiver action.
action_authorization String Action signature, JSON structure. When the transaction is deploying application contract, the public key of the contract is displayed here. The public key is used to verify whether the contract account matches the account of the transaction sender.
action_ext String The reserve parameter, default to empty String.
action_hash Uint32 xxhash32 of the action.Default to "0".Temporary unused.
action_name String The name of contract function.
The system smart contract function,please refer to Platform Smart Contract API.
action_param String The transaction receiver action.The parameter serialization of different action,please refer to Action Param Serialization.
action_size Uint16 Action size.
action_type Uint16 Different transaction type correspond to different receiver action type, please refer to "TX Type and Action Type" in Transaction Protocol.
<!-- xaction_type_create_contract_account = 3,
tx_receiver_account_addr String Transaction receiver account address.
sender_action Object Transaction sender action.
action_authorization String Action signature, JSON structure.
action_ext String The reserve parameter, default to empty String.
action_hash Uint32 xxhash32 of the action. Default to "0".Temporary unused.
action_name String The reserve parameter, default to empty String.
action_param String The transaction sender action.The parameter serialization of different action,please refer to Action Param Serialization.
action_size Uint16 Action size.
action_type Uint16 Different transaction types correspond to different sender action types, please refer to "TX Type and Action Type" in Transaction Protocol.
xaction_type_asset_out = 0,
xaction_type_source_null =1,
tx_sender_account_addr String Transaction sender account address.
tx_deposit Uint32 Transaction deposit. The unit is uTOP.
tx_expire_duration Uint16 If the transaction expires, it will be discarded with the default time of 100s.
tx_hash String The hexadecimal of the transaction hash.
tx_len Uint16 Transaction size.
tx_random_nonce Uint32 Random nonce. Default to "0".Temporary unused.
tx_structure_version String Transaction structure version.Default to "0". Temporary unused.
tx_type Uint16 Transaction type.
Different transaction types have different action param and action type in action.
<!-- xtransaction_type_create_contract_account = 1,
tx_consensus_state Object Transaction consensus status.
confirm_unit_info Object Unit block generated in the third round of consensus.
exec_status String Final consensus status of the transaction: success or failure.
height Uint64 The height of the unit block which is generated in the third round of consensus.
recv_tx_exec_status String Consensus status of transaction receiver: success/failure.
Fail or refuse to consensus, usually occurs in contract transaction.
tx_exec_status String Consensus status of transaction sender: success/failure.
unit_hash String The hash of the unit block which is generated in the third round of consensus.
used_deposit Uint32 After the third round of consensus, the transaction deposit of the sender's account will be deducted if the gas is not enough. The unit is uTOP.
used_disk Uint32 Default to "0".
used_gas Uint32 Deducted gas from sender account after the third round of consensus. The unit is Tgas.
If the contract account has paid part of the gas, then the rest of the whole gas consumed by the transaction is deducted after this round of consensus; If the contract account is unable to pay its share of gas, then the whole gas consumed by the transaction is deducted.
recv_unit_info Object Unit block generated in the second round of consensus.
height Uint64 The height of the unit block which is generated in the second round of consensus.
unit_hash String The hash of the unit block which is generated in the second round of consensus.
used_deposit Uint32 Default to "0".
used_disk Uint32 Default to "0".
used_gas Uint32 Deducted gas after the second round of consensus. The unit is Tgas.
send_unit_info Object Unit block generated in the round of consensus.
height Uint64 The height of the unit block which is generated in the first round of consensus.
tx_fee Uint64 The system will automatically deduct 100*10^6 uTOP tokens from the transaction sender's account as the transaction fee for running Beacon system contract (registration miner related, proposal related, starting node process) and burn it.
unit_hash String The hash of the unit block which is generated in the first round of consensus.
used_deposit Uint32 Default to "0".
used_disk Uint32 Default to "0".
used_gas Uint32 Deducted gas after the first round of consensus. The unit is Tgas.
For cross-account transactions that do not run application contract, the gas consumed by the transaction shall be borne by the sender. If the sender account gas is sufficient, the gas required by the transaction will be deducted after the first round of consensus. If the sender account gas is insufficient, the system will deduct all the gas available in the sender's account after first round of consensus, and the system will deduct the sender transaction deposit to exchange gas to pay the remaining cost after the third round of consensus.

# Demo Code

Contract demo code:

function init()
    create_key('temp_1')
    create_key('temp_2')
    hcreate('hmap')
    set_key('temp_1', '0')
    set_key('temp_2', '0')
    hset('hmap', 'key', 'val')
    hcreate('empty_map')
    create_key('map_len')
    create_key('map_str')

    lcreate('mlist')
    rpush('mlist', '44')
end

function opt_map(key, value)
    hset('hmap', toText(key), toText(value))
    lpush("mlist", toText(value))
end

function check_map(key)
    local map_len = hlen('hmap')
    set_key('temp_1', toText(map_len))
    local map_str = hget('hmap', toText(key))
    set_key('temp_2', toText(map_str))
    hdel('hmap', toText(key))
end

function get_empty_map()
    set_key('map_len', toText(hlen('empty_map')))
    set_key('map_str', toText(hget('empty_map', 'unexist')))
end

function get_empty_key()
    set_key('map_str', toText(hget('empty_map', '')))
end

function del_empty_key()
    hdel('hmap', '')
    set_key('map_len', toText(hlen('empty_map')))
end

function del_not_exist_key()
    hdel('hmap', 'unexist')
    set_key('map_len', toText(hlen('empty_map')))
end