| title |
|---|
Transactions |
This article provides a basic understanding of what a transaction is in ICON. It defines what a transaction is and then describes its functionalities and specifications.
A “transaction” in ICON refers to a "signed" data package which is used for changing the states of a blockchain (e.g. deploying SCORE, ICX coin transfer, etc). A transaction always has to involve signature data.
"States of a blockchain" refers to all states of accounts (e.g. EOA, SCORE accounts, etc.) which are recorded on the blockchain.
- A signature prevents transaction data from forgery or falsification. For example, if transaction data is falsified during propagation, the expected valid signature data also change. As no one can generate the valid signature except the owner of the account that generated the transaction, this transaction will fail during verification due to having an incorrect signature.
- A signature guarantees that the transaction data has been generated by the owner of the appropriate account.
- ICX Coin transfer
- Record message(s) on the blockchain
- Deploy or update SCOREs
- Change SCORE's states
The table below shows the data model of a transaction and the description of each component.
| Component | Description |
|---|---|
| from | EOA address that created the transaction. |
| to | EOA or SCORE address that receives ICX coins, or SCORE address that executes the transactions. When deploying a SCORE, "to" address is a zero SCORE address (i.e. cx0000000000000000000000000000000000000000) |
| value | Amount of ICX coins to be transferred. |
| step limit | The maximum amount of step that will be consumed when executing the transaction. Users can set this amount, and if the entire amount of step a user has set is consumed while executing the transaction, this transaction will fail. |
| time stamp | Transaction creation time. An outdated time will be rejected when validating the transaction. If you use the same time stamp when creating a transaction, that transaction can be rejected as the same transaction hash can be created (see the transaction hash description below). |
| nonce | An arbitrary number used to prevent transaction hash collision (optional). |
| nid | ICON network ID. Each ICON network has different rules and configurations (e.g. governance rules, fee policies, etc.), so even if you try to request the same transaction with the same state of the account, the result of the transaction can be different according to the network. |
| data type | Type of data for executing transaction. When executing a transaction, additional data may be required depending on the purpose of the transaction. For example, when you call a SCORE method, you have to specify which method you want to call, arguments of the method, etc. Depending on the purpose, there are three types: call, deploy, and message. In the case of a simple coin transfer, the data type is omitted because there is no need for additional data.call: used when calling a function in SCOREdeploy: used when installing or updating a SCOREmessage: used when transferring a message |
| data | The detailed content of the transaction. It varies depending on the data type. The maximum size of data is 512 KB. |
| signature | The signature generated by the transaction sender. Generate transaction signature using above data (from, to, value, etc). After generating the signature, if any of the above data is changed, it must be regenerated. The specifics of generating a transaction signature is defined in How to Generate Transaction Signature. |
| transaction hash | Hash data returned after passing the validation process of the transaction (see the Life Cycle of Transaction's "Create Transaction" section below). Each transaction has a unique transaction hash. |
For specific information on transaction data, see the JSON-RPC APIs "icx_sendTransaction" section of the ICON JSON-RPC API v3 Specification documentation.
Create and propagate a transaction to the ICON network. Propagated transactions proceed with basic syntax and signature validation, and is put into the transaction pool to be recorded to a block if they are valid. At the same time, the ICON network returns the transaction hash data. If a transaction is invalid, that transaction is immediately rejected and the ICON network returns an error instead of a transaction hash. The word "rejected" refers to the transaction being removed because it can not be propagated on the ICON network.
In this stage, a transaction is waiting before being put into the block.
In this stage, a transaction is put into a generated block. If consensus is reached regarding the generated block (after the consensus process), that block is connected to the blockchain, and the transactions in the block are recorded permanently. If the consensus on the block fails, all transactions in that block are removed after a certain period of time. The word "removed" refers to ceasing to exist on the ICON network entirely. Therefore, the user who created and propagated the transaction needs to track the transaction until it is recorded on the blockchain (i.e. confirmed).
The block which contains a transaction is connected to the blockchain after the consensus process. This state of the transaction is called "confirmed". A transaction in a confirmed block is recorded permanently regardless of the transaction processing result (success or failure).
If you get the transaction hash as a response to sending a transaction to the ICON network, this means that your transaction has passed the validation. ICON network returns the transaction hash only when a transaction is valid. For specific information about this process, see the JSON-RPC APIs "icx_sendTransaction" section of the ICON JSON-RPC API v3 Specification documentation.
You can check if a transaction is confirmed or pending using "icx_getTransactionResult" JSON-RPC API. "Pending" means that a transaction is in the transaction pool or block generation stage (except in the case of consensus failure on the block, it can be temporarily marked as "pending"). For specific information about this process, see the JSON-RPC APIs "icx_getTransactionResult" section of the ICON JSON-RPC API v3 Specification documentation.