Merge pull request #209 from scott-klaytn/reorganize-learn-section

Reorganize learn section

docs/learn/transactions/ethereum.md → docs/build/transactions/ethereum.md

@@ -2,7 +2,6 @@
 
 Kaia provides wrapped transaction types to support Ethereum compatibility. Ethereum transaction types in Kaia have the same attributes and RLP encoding schemes with Ethereum's design except for the single-byte type delimiter called `EthereumTxTypeEnvelope`. Therefore, users can successfully deploy transactions generated by Ethereum development tools on Kaia. The type delimiter is also omitted when users use `eth` namespace APIs, so they can use Kaia just as if they were using Ethereum. Using `kaia` namespace APIs, users can deploy and retrieve Ethereum formatted transactions as a type of Kaia transactions without getting confused with the existing Kaia transaction types.  
 
-
 ## EthereumTxTypeEnvelope <a id="ethereumtxtypeenvelope"></a>
 
 EthereumTxTypeEnvelope is a single-byte prefix for raw transactions that denotes Ethereum transaction types. Ethereum has adopted an extendable transaction type scheme from [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) and it uses a type numbering system that conflicts with Kaia's. To resolve the conflict between two different transaction type schemes, Kaia has introduced `EthereumTxTypeEnvelope` which allows for separation and expansion for future Ethereum transaction types. 
@@ -12,7 +11,6 @@ EthereumTxTypeEnvelope is a single-byte prefix for raw transactions that denotes
 - TxHashRLP : EthereumTransactionType || TransactionPayload
 - RawTransaction : EthereumTxTypeEnvelope || EthereumTransactionType || TransactionPayload
 
-
 ## TxTypeEthereumAccessList <a id="txtypeethereumaccesslist"></a>
 
 `TxTypeEthereumAccessList` represents a type of Ethereum transaction specified in [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930). This transactions type contains an access list, a list of addresses and storage keys that the transaction is supposed to access. Since this transaction type exists to support compatibility, it only works with EOAs associated with [AccountKeyLegacy]. EOAs associated with other account key types should use other transaction types such as `TxTypeValueTransfer`, `TxTypeSmartContractExecution`, and so on. This transaction type can create accounts, transfer tokens, deploy/execute smart contracts or a mix of the aforementioned. 
@@ -36,7 +34,7 @@ NOTE: This transaction type only supports the format of the Ethereum transaction
 | type | uint8 \(Go\) | The type of `TxTypeEthereumAccessList` that is a concatenation of `EthereumTxTypeEnvelope` and `EthereumTransactionType`. This must be 0x7801. |  
 | chainId | \*big.Int \(Go\) | The destination chain ID. |
 | nonce | uint64 \(Go\) | A value used to uniquely identify a sender’s transaction. If two transactions with the same nonce are generated by a sender, only one is executed. |
-| gasPrice | \*big.Int \(Go\) | A multiplier to get how much the sender will pay in tokens. The amount of tokens the sender will pay is calculated via `gas` \* `gasPrice`. For example, the sender will pay 10 KAIA for a transaction fee if gas is 10 and gasPrice is 10^18. See [Unit of KAIA]. |
+| gasPrice | \*big.Int \(Go\) | A multiplier to get how much the sender will pay in tokens. The amount of tokens the sender will pay is calculated via `gas` \* `gasPrice`. For example, the sender will pay 10 KAIA for a transaction fee if gas is 10 and gasPrice is 10^18. See [Unit of KAIA](../../learn/token-economics/kaia-native-token.md#units-of-kaia). |
 | gas | uint64 \(Go\) | The maximum amount of transaction fee the transaction is allowed to use. |
 | to | \*common.Address \(Go\) | The account address that will receive the transferred value. |
 | value | \*big.Int \(Go\) | The amount of KAIA in `kei` to be transferred. |

docs/build/transactions/transactions.md

@@ -0,0 +1,49 @@
+# Implementing Transactions
+
+This guide provides a comprehensive overview of implementing transactions on the Kaia network, covering various transaction types, encoding, signing, and network interaction.
+
+## Kaia Transaction Components
+
+Kaia transactions generally include the following components:
+
+| Components | Description |
+| :--- | :--- |
+| `from` | The sender's address.  Required for most Kaia transaction types due to the decoupling of key pairs and addresses. |
+| `to` | The account address that will receive the transferred value. |
+| `value` | The amount of KAIA in `kei` to be transferred. |
+| `input` | Data attached to the transaction, used for transaction execution. |
+| `v`, `r`, `s` | The cryptographic signature generated by the sender to let the receiver obtain the sender's address. |
+| `nonce` | A value used to uniquely identify a sender’s transaction. If two transactions with the same nonce are generated by a sender, only one is executed. |
+| `gas` | The maximum amount of transaction fee the transaction is allowed to use. |
+| `gasPrice` | A multiplier to get how much the sender will pay in tokens. The amount of tokens the sender will pay is calculated via `gas` \* `gasPrice`. For example, the sender will pay 10 KAIA for a transaction fee if gas is 10 and gasPrice is 10^18. Unit of KAIA is described [here](../../learn/token-economics/kaia-native-token.md#units-of-kaia). |
+
+## Signature Validation
+
+Because Kaia decouples key pairs from addresses, signature validation differs from typical blockchains.  The `from` field is crucial, as it identifies the sender.  The [AccountKey](../../learn/accounts.md#account-key) associated with the `from` address is used to validate the signature.
+
+## Fee Delegation and SenderTxHash
+
+Kaia's fee delegation feature allows a third party to pay transaction fees.  This requires two signatures – one from the sender and one from the fee payer. The `SenderTxHash` is crucial for tracking fee-delegated transactions. It's a hash of the transaction *without* the fee payer's information, allowing the sender to track the transaction before the fee payer signs it.  The sender can use the `SenderTxHash` to retrieve the complete transaction via the [kaia_getTransactionBySenderTxHash](../../references/json-rpc/kaia/get-transaction-by-sender-tx-hash) RPC method.
+
+## Transaction Types
+
+While typical Blockchain platforms provide a single transaction type, Kaia provides multiple transaction types that empower transactions with new capabilities and optimizations for memory footprint and performance. The following table provides an overview of the transaction types available on Kaia:
+
+|  | Basic | Fee Delegation | Partial Fee Delegation |
+| :--- | :--- | :--- | :--- |
+| Legacy | [TxTypeLegacyTransaction](./basic.md#txtypelegacytransaction) | N/A | N/A |
+| ValueTransfer | [TxTypeValueTransfer](./basic.md#txtypevaluetransfer) | [TxTypeFeeDelegatedValueTransfer](./fee-delegation.md#txtypefeedelegatedvaluetransfer) | [TxTypeFeeDelegatedValueTransferWithRatio](./partial-fee-delegation.md#txtypefeedelegatedvaluetransferwithratio) |
+| ValueTransferMemo | [TxTypeValueTransferMemo](./basic.md#txtypevaluetransfermemo) | [TxTypeFeeDelegatedValueTransferMemo](./fee-delegation.md#txtypefeedelegatedvaluetransfermemo) | [TxTypeFeeDelegatedValueTransferMemoWithRatio](./partial-fee-delegation.md#txtypefeedelegatedvaluetransfermemowithratio) |
+| SmartContractDeploy | [TxTypeSmartContractDeploy](./basic.md#txtypesmartcontractdeploy) | [TxTypeFeeDelegatedSmartContractDeploy](./fee-delegation.md#txtypefeedelegatedsmartcontractdeploy) | [TxTypeFeeDelegatedSmartContractDeployWithRatio](./partial-fee-delegation.md#txtypefeedelegatedsmartcontractdeploywithratio) |
+| SmartContractExecution | [TxTypeSmartContractExecution](./basic.md#txtypesmartcontractexecution) | [TxTypeFeeDelegatedSmartContractExecution](./fee-delegation.md#txtypefeedelegatedsmartcontractexecution) | [TxTypeFeeDelegatedSmartContractExecutionWithRatio](./partial-fee-delegation.md#txtypefeedelegatedsmartcontractexecutionwithratio) |
+| AccountUpdate | [TxTypeAccountUpdate](./basic.md#txtypeaccountupdate) | [TxTypeFeeDelegatedAccountUpdate](./fee-delegation.md#txtypefeedelegatedaccountupdate) | [TxTypeFeeDelegatedAccountUpdateWithRatio](./partial-fee-delegation.md#txtypefeedelegatedaccountupdatewithratio) |
+| Cancel | [TxTypeCancel](./basic.md#txtypecancel) | [TxTypeFeeDelegatedCancel](./fee-delegation.md#txtypefeedelegatedcancel) | [TxTypeFeeDelegatedCancelWithRatio](./partial-fee-delegation.md#txtypefeedelegatedcancelwithratio) |
+| ChainDataAnchoring | [TxTypeChainDataAnchoring](./basic.md#txtypechaindataanchoring) | [TxTypeFeeDelegatedChainDataAnchoring](./fee-delegation.md#txtypefeedelegatedchaindataanchoring) | [TxTypeFeeDelegatedChainDataAnchoringWithRatio](./partial-fee-delegation.md#txtypefeedelegatedchaindataanchoringwithratio)|
+
+## Implementation Details
+
+* **RLP Encoding:** Transactions are serialized using Recursive Length Prefix (RLP) encoding before submission.
+* **Signatures:**  Transactions are signed using [Specify signature algorithm, e.g., ECDSA] to ensure authenticity.
+* **Examples and RPC Outputs:**  This section will provide practical examples and expected RPC outputs for each transaction type.  (Note:  `TxTypeValueTransfer` sends KAIA without any additional data, while `TxTypeValueTransferMemo` allows for including a short memo field along with the transfer.)
+
+By understanding these components and implementation details, developers can effectively build applications on the Kaia network.

docs/learn/accounts.md

@@ -181,7 +181,8 @@ In order for a transaction to be valid for an account associated with AccountKey
 
 :::note
 
-The following multiSig validation logic has been added with the [IstanbulEVM](docs/misc/klaytn-history.md#istanbul-evm) hardfork.
+The following multiSig validation logic has been added with the [IstanbulEVM](../misc/klaytn-history.md#istanbul-evm) hardfork.
+
 * The invalid signature should not be included in the transaction.
 * The number of signed public keys should be less than the number of weightedPublicKeys.
 

docs/learn/computation/computation-cost.md

@@ -12,7 +12,7 @@ Limiting the execution time of a transaction was not feasible either because the
 
 The last approach is to limit the computation cost of a transaction. We modelled the computation cost of each EVM opcode based on its actual execution time and limit the sum of computation cost of a transaction. With this approach, we eliminate other factors and only count the normalized execution time unit, and nodes can reach a consensus as well.
 
-Therefore, we chose the third option for Kaia. The computation cost limit was 100,000,000, but as CPU computing performance has increased, the limit has been raised to 150,000,000 after Cancun EVM hardfork. This limit value is determined by the platform, so the developers should be aware of the computation cost of a transaction. To calculate the computation cost of a transaction, Kaia provides [kaia_estimateComputationCost](../../../references/json-rpc/klay/estimate-computation-cost). The usage is almost the same as [kaia_estimateGas](../../../references/json-rpc/klay/estimate-gas).
+Therefore, we chose the third option for Kaia. The computation cost limit was 100,000,000, but as CPU computing performance has increased, the limit has been raised to 150,000,000 after Cancun EVM hardfork. This limit value is determined by the platform, so the developers should be aware of the computation cost of a transaction. To calculate the computation cost of a transaction, Kaia provides [kaia_estimateComputationCost](../../../references/json-rpc/kaia/estimate-computation-cost). The usage is almost the same as [kaia_estimateGas](../../../references/json-rpc/kaia/estimate-gas).
 
 :::note
 
@@ -23,7 +23,7 @@ Computation cost related hardfork changes can be found at the bottom of this pag
 ## Computation Cost Limit <a id="coputation-cost-limit"></a>
 A series of opcodes or precompiled contracts are executed sequentially when executing a transaction. To limit the execution time of a transaction, we have made a deterministic execution time calculation model for opcodes and precompiled contracts based on real execution time.
 
-Based on this model, predetermined computation cost values for opcodes and precompiled contracts are added to the total computation cost. If the total value exceeds computation cost limit, transaction execution is aborted and returns [ComputationCostLimitReached(0x0a)](../../references/sdk/transaction-error-codes.md) error.
+Based on this model, predetermined computation cost values for opcodes and precompiled contracts are added to the total computation cost. If the total value exceeds computation cost limit, transaction execution is aborted and returns [ComputationCostLimitReached(0x0a)](../../references/transaction-error-codes.md) error.
 
 When setting the computation cost limit value, we set `--opcode-computation-cost-limit` flag value as a limit if it is set as a non-zero value. If it's zero, the limit is set to the default computation cost limit defined for each specific hardfork.
 Exceptionally, the limit for call/estimateGas/estimateComputationCost is always set to unlimited and is not influenced by flag or hardfork values. However, execution still can be aborted due to other limits such as gas cap.

docs/learn/computation/computation.md

@@ -1,7 +1,9 @@
-# Computation
+# Transaction Execution
 
-```mdx-code-block
-import DocCardList from '@theme/DocCardList';
+This section provides a comprehensive guide to how transactions are processed, executed, and analyzed on the Kaia blockchain. Understanding these processes is critical for developers building applications on Kaia, as it directly impacts performance, cost, and debugging strategies.
 
-<DocCardList />
-```
+- [Execution Model](./execution-model.md) details the complete lifecycle of a Kaia transaction, from its initial submission to its final inclusion in a block. Learn how transactions are validated by Consensus Nodes (CNs), the process of block creation, and the role of the BFT consensus mechanism in finalizing transactions. This includes details on Kaia's enhanced randomness for block proposer selection, as well as crucial restrictions on both transaction execution and smart contract deployment. Understanding these limitations is essential for avoiding unexpected transaction failures.
+
+- [Computation Cost](./computation-cost.md) explains the mechanics of transaction costs on the Kaia network. Dive into the gas mechanism, including how gas pricing is determined, the network's computation cost limit, and the gas costs associated with specific EVM operations. This section also details the additional gas costs incurred for contract creation based on initcode length, introduced with the Shanghai hardfork, enabling developers to accurately estimate and manage transaction expenses.
+
+- [Debug Tracing](debug-tracing.md) explores the tools and techniques available for monitoring and debugging transaction execution. Gain insights into how to identify and resolve issues within your Kaia applications, ensuring smooth operation and efficient resource utilization. This includes information on how to trace the execution flow of transactions and pinpoint potential bottlenecks or errors.

docs/learn/computation/execution-model.md

@@ -4,7 +4,7 @@ This page describes the execution model, the data structures, and the life cycle
 
 ## Execution Model <a id="execution-model"></a>
 
-Transactions can be generated by platform APIs as described in [Platform API Specification](../../../references/json-rpc/klay/account-created). These transactions are sent to _Consensus Nodes \(CNs\)_ to be stored in a block. The CNs check whether each received transaction is valid. Valid transactions are stored in the transaction pool; otherwise, they are discarded. A CN selects the executable transactions in the current block in its transaction pool and executes them one by one.
+Transactions can be generated by platform APIs as described in [Platform API Specification](../../../references/json-rpc/kaia/account-created). These transactions are sent to _Consensus Nodes \(CNs\)_ to be stored in a block. The CNs check whether each received transaction is valid. Valid transactions are stored in the transaction pool; otherwise, they are discarded. A CN selects the executable transactions in the current block in its transaction pool and executes them one by one.
 
 To execute a transaction, the sender must pay some amount of KAIA as a transaction fee. This transaction fee in KAIA is calculated based on gas and a multiplier, _i.e._, unit price. A gas is the fundamental unit of computation. Every operation executed on a Kaia node consumes a predefined amount of gas. The exact amount of KAIA required for the transaction is calculated by the formula illustrated in [Transaction Fees](../transaction-fees/transaction-fees.md). The transaction can fail if the sender submits a transaction accompanied by insufficient gas. A transaction can also fail if the sender's account has an insufficient balance.
 
@@ -60,7 +60,7 @@ An account in Kaia blockchain platform is a data structure containing informatio
 
 ### Transaction <a id="transaction"></a>
 
-A transaction in a blockchain platform is a message sent between nodes that changes the state of the blockchain. Kaia also redesigns its transaction model. Transactions are separated into various types according to their own purposes to find chances of performance optimization and to support the redesigned account model. Detailed information about the transaction model can be found [here](../transactions/transactions.md).
+A transaction in a blockchain platform is a message sent between nodes that changes the state of the blockchain. Kaia also redesigns its transaction model. Transactions are separated into various types according to their own purposes to find chances of performance optimization and to support the redesigned account model. Detailed information about the transaction model can be found [here](../../build/transactions/transactions.md).
 
 ### State <a id="state"></a>
 
@@ -101,7 +101,7 @@ A block is a crucial element of the Kaia blockchain because the blockchain liter
 | transactions | Array of transaction objects, or 32-byte transaction hashes depending on the last given parameter. |
 | voteData | RLP encoded governance vote of the proposer |
 
-## Smart Contract <a id="smart-contract"></a>
+## Smart Contract Lifecycle <a id="smart-contract-lifecycle"></a>
 
 A _smart contract_ consists of a collection of code \(functions\) and data \(state\) that resides at a specific address on the Kaia blockchain. Contract accounts are able to pass messages between each other as well as perform practically Turing complete computation. Contracts exist on the blockchain in Kaia-specific binary formats. Currently, Kaia supports one binary format --Ethereum Virtual Machine \(EVM\) bytecode; however, other formats will be supported in the future.