# Transaction Protocol

# Overview

A transaction refers to an instruction that initiates an asset transfer from one account to another. A transaction can also contain an action that will be triggered when the transaction is being processed.

Action: An action provides flexible processing capabilities for a property. An action can be a built-in system function such as Hash and Vote, or a user-defined smart contract. Users can trigger an action by sending a transaction or a message.

Message: A message is an instruction that initiates an action on a property of an account. Data attached to a message contains the property, action, input parameters and output parameters. For security purposes, a message cannot alter the account balance.

A message is a special kind of transaction. An account sending high-frequency messages is subject to flow control and has to pay gas fees, or the account owner may be forced to perform proof of work (POW).

# Transaction Structure

Parameter Name Parameter Name Description
authorization String Transaction body signature.
challenge_proof String The reserve filed, default to empty String.
ext String The reserve filed, default to empty String.
from_ledger_id Uint16 The reserve filed, 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 filed, default to "0".
to_ledger_id Uint16 The reserve filed, default to "0".
receiver_action Object Transaction receiver action.
action_authorization String Action signature, JSON structure. When the transaction is application contract deployment, 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 filed, 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 serialization of different action perform content 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".
xaction_type_asset_out = 0,
xaction_type_create_contract_account = 3,
xaction_type_run_contract = 5,
xaction_type_asset_in = 6,
xaction_type_pledge_token_vote = 21,
xaction_type_redeem_token_vote = 22,
xaction_type_pledge_token = 23,
xaction_type_redeem_token = 24,
tx_receiver_account_addr String Transaction receiver account address.
send_timestamp Uint64 Transaction send timestamp.
sender_action Object Transaction sender action.
action_authorization String Action signature, JSON structure.
action_ext String The reserve filed, default to empty String.
action_hash Uint32 xxhash32 of the action. Default to "0".Temporary unused.
action_name String The reserve filed, default to empty String.
action_param String The transaction sender action.The serialization of different action perform content 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".
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,
xtransaction_type_run_contract = 3,
xtransaction_type_transfer = 4,
xtransaction_type_vote = 20,
xtransaction_type_abolish_vote = 21,
xtransaction_type_pledge_token_gas = 22,
xtransaction_type_redeem_token_gas = 23,
xtransaction_type_pledge_token_vote = 27,
xtransaction_type_redeem_token_vote = 28,

# tx_type and action_type

The action_type in the sender action and receiver action for each transaction type is different when creating the transaction.

WARNING

When creating a transaction, make sure that tx_type, sender action_type and receiver action_type are configured according to the following, otherwise the transaction will fail.

Transaction Name tx_type sender_action action_type receiver_action action_type Note
Create contract account. 1: xtransaction_type_create_contract_account 0: xaction_type_asset_out 3: xaction_type_create_contract_account
Run contract. 3: xtransaction_type_run_contract 0: xaction_type_asset_out 5: xaction_type_run_contract Running contract transactions includes:
Running application smart contract, Register node, Ungister node, Redeem node deposit, Update node type, Unstake deposit, Stake deposit, Set node name, Set dividend ratio, Claim node reward, Claim node dividend, Submit proposal, Withdraw proposal, TCC vote on proposal.
Transfer 4: xtransaction_type_transfer 0: xaction_type_asset_out 6: xaction_type_asset_in
Vote node. 20: xtransaction_type_vote 1: xaction_type_source_null 5: xaction_type_run_contract
Unvote node. 21: xtransaction_type_abolish_vote 1: xaction_type_source_null 5: xaction_type_run_contract
Stake gas. 22: xtransaction_type_pledge_token_gas 1: xaction_type_source_null 23: xaction_type_pledge_token
Unstake gas. 23: xtransaction_type_redeem_token_gas 1: xaction_type_source_null 24: xaction_type_redeem_token
Stake votes. 27: xtransaction_type_pledge_token_vote 1: xaction_type_source_null 21: xaction_type_pledge_token_vote
Unstake votes. 28: xtransaction_type_redeem_token_vote 1: xaction_type_source_null 22: xaction_type_redeem_token_vote

Action

Action Name Functions Parameters
xaction_type_source_null The source side does not perform operations. None.
xaction_type_asset_out Assets off. symbol, amount
xaction_type_create_contract_account Create application contract account. gas_limit(The upper limit of the gas fee that the user is willing to pay for the transaction.), contract code
xaction_type_run_contract Run contract(include platform contract and appliacation contract) action_name(function name), action_param
xaction_type_asset_in Assets in. symbol, amount
xaction_type_pledge_token Lock TOP tokens to get gas. symbol, amount(Locked TOP tokens)
xaction_type_redeem_token Unlock TOP tokens for getting gas. symbol, amount(Unlocked TOP tokens)
xaction_type_pledge_token_vote Lock TOP toeks to get votes. vote_amount, lock_duration
xaction_type_redeem_token_vote Unlock TOP tokens for getting votes. vote_amount(Amount of redeemed votes.)