# 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.) |