v0.14.0 transactions (#1635)

* init

* cont

* finish

* minor fix

* typo fix

* invoke rebuild

* minor change

Author: LandauRaz

components/Starknet/modules/architecture/pages/transactions.adoc

@@ -1,7 +1,7 @@
 = Transactions
 
 == Overview
-Transactions are cryptographically signed instructions from accounts that update the state of the Starknet network. Starknet supports only xref:transaction_types[three types] of transactions, with each type going through the same xref:transaction_lifecycle[lifecycle] to receive its xref:transaction_statuses[execution and finality statuses]. Each transaction is issued a xref:transaction_receipt[receipt], which includes its statuses and other information about it.
+Transactions are cryptographically signed instructions from accounts that update the state of the Starknet network. Starknet supports only xref:transaction_types[three types] of transactions, with each type going through the same xref:transaction_lifecycle[lifecycle] to receive its xref:transaction_statuses[execution and finality statuses]. Every transaction that was executed successfully is issued a xref:transaction_receipt[receipt], which includes its statuses, as well as other information about it.
 
 .Additional information
 
@@ -12,40 +12,33 @@ Transactions are cryptographically signed instructions from accounts that update
 Starknet supports the following types of transactions:
 
 [horizontal,labelwidth="20"]
-`DECLARE`:: Declares new contract classes, enabling new contract instances.
-`INVOKE`:: Invokes an existing function in a contract.
-`DEPLOY_ACCOUNT`:: Deploys new account contracts in smart wallets.
+`DECLARE`:: Introduces a new contract class to Starknet, enabling other contracts to either deploy instances of it or use it via a library call
++
+[TIP]
+====
+For more information about contract classes and instances, see the https://book.cairo-lang.org/ch100-01-contracts-classes-and-instances.html[Cairo Book].
+====
 
+`INVOKE`:: Invokes a function in an existing contract instance, undergoing validation and execution initiated by the caller account's xref:accounts.adoc#starknets_account_structure[`+__validate__+` and `+__execute__+` functions] (respectively).
++
 [NOTE]
 ====
-The xref:messaging.adoc#l1_handler_transaction[`L1HandlerTransaction` type] is also a valid transaction type within Starknet, be it cannot be broadcast through the Starknet API like other transaction types, as it was specifically designed for internal Starknet operations (particularly, handling messages from L1 to L2).
-
-The `DEPLOY` transaction type existed in Starknet for deploying account before being replaced by `DEPLOY_ACCOUNT`. `DEPLOY` only had one version (v0) and is now unsupported by Starknet. 
+The validation stage verifies that the caller account approves the transaction. Because an account's `+__validate__+` and `+__execute__+` functions can contain any logic, the caller account ultimately determines how to handle the `INVOKE` transaction.
 ====
 
-// === `INVOKE`
-
-// The `INVOKE` transaction type invokes a function in an existing contract instance. The contract code of the account that sends the `INVOKE` transaction determines how to process the transaction.
-
-// [NOTE]
-// ====
-// Because an account's `+__validate__+` and `+__execute__+` functions can contain any logic, the account ultimately determines how to handle the `INVOKE` transaction.
-// ====
-
-// Every `INVOKE`  transaction in Starknet undergoes the validation and execution stages, initiated by the `+__validate__+` and `+__execute__+` functions. The validation stage verifies that the account that sent the transaction approves it.
-
-// === `DECLARE`
-
-// The `DECLARE` transaction introduces new contract classes into the state of Starknet, enabling other contracts to deploy instances of those classes or use them in a library call. For more information, see xref:architecture:smart-contracts/contract-classes.adoc[contract classes].
-
-// === `DEPLOY_ACCOUNT`
-
-// Since StarkNet v0.10.1 the `DEPLOY_ACCOUNT` transaction replaces the `DEPLOY` transaction for deploying account contracts.
+`DEPLOY_ACCOUNT`:: Deploys a new account contract to Starknet.
++
+[TIP]
+====
+For more information about deploying a new account, see xref:accounts.adoc#deploying_a_new_account[Accounts].
+====
 
-// To use it, you should first pre-fund your new account address so that you can pay the
-// transaction fee. You can then send the `DEPLOY_ACCOUNT` transaction.
+[NOTE]
+====
+The xref:messaging.adoc#l1_handler_transaction[`L1HandlerTransaction` type] is also a valid transaction type within Starknet, be it cannot be broadcast through the Starknet API like other transaction types, as it was specifically designed for internal Starknet operations (particularly, handling messages from L1 to L2).
 
-// For more information, see xref:accounts/deploying-new-accounts.adoc[].
+The `DEPLOY` transaction type existed in Starknet for deploying account before being replaced by `DEPLOY_ACCOUNT`. `DEPLOY` only had one version (v0) and is now unsupported by Starknet. 
+====
 
 Each transaction type is versioned, with versions increasing when the fields that comprise the transaction change, either with the addition of a new field or the removal of an existing field. The following table summarizes the current, deprecated, and unsupported versions of each transaction type:
 
@@ -55,18 +48,18 @@ Each transaction type is versioned, with versions increasing when the fields tha
 
 |`INVOKE`
 | v3
-| v1, v0
 | None
+| v1, v0
 
 |`DECLARE`
 | v3
-| v2, v1
-| v0
+| None
+| v2, v1, v0
 
 |`DEPLOY_ACCOUNT`
 | v3
-| v1
 | None
+| v1
 |===
 
 [IMPORTANT]
@@ -79,29 +72,55 @@ Sending transaction that use deprecated versions is still supported, but support
 == Transaction lifecycle
 The high-level steps in the Starknet transaction lifecycle are as follows:
 
-. *Transaction submission:* A transaction is submitted to one of the gateways, which functions as the mempool, and marks it as received.
+. *Transaction submission:* A transaction is submitted to a sequencer by a full node.
 
 . *Mempool validation:*
-The mempool performs preliminary validation of the transaction, such as ensuring that its invoker's balance exceeds the transaction's `max_fee` value, assuring the transaction's calldata length is within the legal limit, and more. If the transaction is invalid, it does not proceed.
-+
-[NOTE]
-====
-Mempool validation in this context is analogous to Ethereum's signature checking, and includes running the account's `+__validate__+` function for an `INVOKE` transaction, `+__validate_declare__+` for a `DECLARE` transaction, or `+__validate_deploy__+` for a `DEPLOY_ACCOUNT` transaction.
-====
+The sequencer's xref:transaction_mempool[mempool] performs preliminary validation of the transaction, such as ensuring that its invoker's balance exceeds the transaction's `max_fee` value, assuring the transaction's calldata length is within the legal limit, and more. If the transaction is invalid, it does not proceed.
+// +
+// [NOTE]
+// ====
+// Mempool validation in this context is analogous to Ethereum's signature checking, and includes running the account's `+__validate__+` function for an `INVOKE` transaction, `+__validate_declare__+` for a `DECLARE` transaction, or `+__validate_deploy__+` for a `DEPLOY_ACCOUNT` transaction.
+// ====
 . *Sequencer validation:* The sequencer performs preliminary validation of the transaction before executing it to ensure that the transaction is still valid. If the transaction is invalid, it does not proceed.
 +
+// [NOTE]
+// ====
+// The sequencer repeats the same validation performed by the mempool.
+// ====
+
+. *Execution:* The sequencer batches all transactions that passed the preliminary validation into a block, and applies them to the state sequentially. If a transaction fails during execution, it is included in the block with as reverted.
+
+. *Proof generation and verification:* The prover uses the xref:os.adoc[Starknet operating system] to computes the proof for the correct execution of all transactions in the block, and transmits it to the L1 verifier, which verifies it. At this point, the L1 state is updated to include the transaction.
+
+=== Mempools
+
+Up to and including Starknet v0.13.5, transactions were received and ordered by the sequencer in a first-in-first-out (FIFO) fashion. Starting from Starknet v0.14.0, each sequencer will instead maintain a mempool, decouping the transaction order of arrival from the transaction ordering in blocks, for which they are can decide their own policy.
+
+The introduction of mempools will have the following implications on how transactions are processed:
+
+* *Nonces*: Transactions with a nonce greater than the sender's current nonce + stem:[x] will be rejected by the mempool, where:
+** A sender's current nonce is the sender's nonce in the latest finalized state at the time the transaction is received
+** stem:[50 \leq x \leq 100] is still TBD for `INVOKE` and `DEPLOY_ACCOUNT` transactions and stem:[x = 0] for `DECLARE` transactions (i.e., no declares with future nonces)
+
+* *Fee escalation*: A transaction in the mempool can be replaced by a transaction sent from the same account with the same nonce and both `tip` and `max_l2_gas_price` increased by at least 10%
++
 [NOTE]
 ====
-The sequencer repeats the same validation performed by the mempool.
+There are unlikely edge cases in which a transaction is not replaced despite submitting a valid transaction to replace it, such as the existing transaction entering a block while the new one is still processed in the gateway.
 ====
 
-. *Execution:* The sequencer batches all transactions that passed the preliminary validation into a block, and applies them to the state sequentially. If a transaction fails during execution, it is included in the block with as reverted.
+* *Transaction time-to-live (TTL)*: Transactions that cannot be included in a block and have exceeded their TTL, currently configured to be 5 mins, are periodically evicted from the mempool
 
-. *Proof generation and verification:* The prover uses the xref:os.adoc[Starknet operating system] to computes the proof for the correct execution of all transactions in the block, and transmits it to the L1 verifier, which verifies it. At this point, the L1 state is updated to include the transaction.
+* *`DECLARE` transactions time-to-mature (TTM)*: Before being inserted into the mempool, `DECLARE` transactions are sent to a "waiting room" until they exceed their TTM, where TTM < TTL but is still TBD. While in the "waiting room", `DECLARE` transactions can't be replaced, and transactions sent with the same nonce as a transaction in the "waiting room" by the same account are rejected
+// +
+// [NOTE]
+// ====
+// The motivation for the `DECLARE` transactions "waiting room" is to impede a DoS attack where a `DECLARE` transaction is submitted and its code is compiled, but is then reaplced by sending a transaction with the same nonce while it matures.
+// ====
 
 == Transaction statuses
 
-The following are the possible statuses of a transaction from the moment a user sends it until the moment it passes the L1 verifier:
+A transaction's state is represented by the following _finality_ and _execution_ statuses:
 
 [cols="1,2,4"]
 |===
@@ -141,9 +160,54 @@ Since the `DEPLOY_ACCOUNT` and `DECLARE` transactions don't have an execution ph
 | The transaction was successfully executed by the sequencer and is included in a block.
 |===
 
-The diagram below illustrates how each transaction status fits into the overall transaction flow:
+Starting from Starknet version 0.14.0, these statuses will change to the following:
+
+[cols="1,2,4"]
+|===
+| Type | Status | Description
+
+.6+.^| *Finality*
+
+| `NOT_RECEIVED`
+| The transaction is not yet known to any sequencer.
+
+| `RECEIVED`
+a| A full node has successfully submitted the transaction to a sequencer.
+[NOTE]
+====
+As there is currently no P2P protocol between full nodes for updating on each other about received transactions, querying a different node than the one that submitted the transaction for its status will result in a `Transaction hash not found` error. 
 
-image::txn-flow.png[]
+Therefore, relying on `RECEIVED` statuses requires initiating sticky HTTP sessions with your full node provider.
+====
+
+| `PRE-CONFIRMED`
+a| The transaction was written to the feeder gateway's storage by a sequencer.
+[NOTE]
+====
+As the transaction hasn't been executed yet, no execution information is available and only the transaction hash is written to the feeder gateway's storage.
+====
+
+| `EXECUTED`
+| The transaction was successfully executed by a sequencer and its receipt was written to the feeder gateway's storage.
+
+| `ACCEPTED_ON_L2`
+| The transaction was included in a block finalized by the consensus protocol.
+
+| `ACCEPTED_ON_L1`
+| The Starknet state on L1 moved to a block height which is greater than or equal to the height of the block containing the transaction.
+
+.2+.^| *Execution*
+
+| `REVERTED`
+a| The transaction failed during execution by a sequencer, and was included in a block as reverted.
+[NOTE]
+====
+Since the `DEPLOY_ACCOUNT` and `DECLARE` transactions don't have an execution phase, they cannot be reverted.
+====
+
+| `SUCCEEDED`
+| The transaction was successfully executed by a sequencer and is included in a block.
+|===
 
 === State implications of reverted transactions