From 12843f002c882086e3ffa384a3826f6caa144002 Mon Sep 17 00:00:00 2001
From: Joel Willmore <95916148+jlwllmr@users.noreply.github.com>
Date: Mon, 30 Sep 2024 11:26:37 +0100
Subject: [PATCH] Add module limits explainer (#746)

* Initial draft

* Updates

* Expand with detail about relevant API methods

* Add sidebar link

* Update project-words.txt

* Address comments

* Address comment

* Addressing comments

* Address comments
---
 .../trace-expansion-proving/prover-limits.mdx | 39 +++++++++++++++++++
 .../reference/api/eth-sendrawtransaction.mdx  |  2 +-
 project-words.txt                             |  1 +
 sidebars.js                                   |  1 +
 4 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 docs/architecture/stack/trace-expansion-proving/prover-limits.mdx

diff --git a/docs/architecture/stack/trace-expansion-proving/prover-limits.mdx b/docs/architecture/stack/trace-expansion-proving/prover-limits.mdx
new file mode 100644
index 000000000..cc1543083
--- /dev/null
+++ b/docs/architecture/stack/trace-expansion-proving/prover-limits.mdx
@@ -0,0 +1,39 @@
+---
+title: Module limits
+description: How module limits ensure the prover can generate proofs.
+sidebar_position: 3
+---
+
+Linea uses module limits to keep proof complexity manageable and ensure that the prover can
+generate proofs efficiently without overwhelming the infrastructure. 
+
+Linea's arithmetization specification is divided into modules, and each module represents a collection
+of EVM or Linea zkEVM operations (opcodes). Modules can:
+- Process transaction data.
+- Manage zkEVM memory.
+- Coordinate interactions between modules.
+
+Each module has a specific limit on the number of lines of data its operations can generate, 
+regardless of its purpose. You can view these limits in the 
+[Linea source code](https://github.com/Consensys/linea-monorepo/blob/main/config/common/traces-limits-besu-v2.toml). 
+Additional lines are generated each time unique instructions are provided to a module's operations, 
+but repeat calls with the same arguments do not generate new lines.
+
+High-complexity transactions that repeatedly use a large volume of operations may generate too many 
+lines of data and exceed a module's limit. Transactions that reach this point are rejected by the 
+[sequencer](../sequencer/index.mdx) to ensure that the trace data passed to the prover is of a 
+manageable scope, and that a proof can be generated.
+
+Transactions rejected for exceeding module limits can be identified through the following
+methods, which return an error:
+
+- [`linea_estimateGas`](../../../developers/reference/api/linea-estimategas.mdx)
+- [`eth_sendRawTransaction`](../../../developers/reference/api/eth-sendrawtransaction.mdx)
+
+Use [`linea_getTransactionExclusionStatusV1`](../../../developers/reference/api/linea-gettransactionexclusionstatusv1.mdx)
+to get the rejection status of a transaction hash, if it was sent and didn't get rejected directly, 
+nor included in a block.
+
+This API method can be used to query the reason for transaction rejection in edge cases where
+`linea_estimateGas` or `eth_sendRawTransaction` did not return an error. It's intended to be used 
+only in cases the transaction execution differs between an RPC node and the sequencer.
diff --git a/docs/developers/reference/api/eth-sendrawtransaction.mdx b/docs/developers/reference/api/eth-sendrawtransaction.mdx
index 4daf78ed5..59e643874 100644
--- a/docs/developers/reference/api/eth-sendrawtransaction.mdx
+++ b/docs/developers/reference/api/eth-sendrawtransaction.mdx
@@ -31,7 +31,7 @@ On Linea, each transaction is represented by a sequence of lines representing th
 happening at the EVM level. These lines are grouped by modules and are used as inputs to the prover. 
 In order to limit the resources required to generate proofs, limits are enforced on the maximum 
 number of lines each module can have. Hence, when a transaction is considered for inclusion in a 
-block, a line count check is perform to ensure it conforms to the requirements.
+block, a [line count check is performed to ensure it conforms to the requirements](../../../architecture/stack/trace-expansion-proving/prover-limits.mdx).
 
 ## Parameters
 
diff --git a/project-words.txt b/project-words.txt
index 320ea0e4e..68dfc0b7c 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -301,6 +301,7 @@ gcsize
 gctime
 genkey
 getopts
+gettransactionexclusionstatusv
 gitgraph
 gitpod
 Gizathon
diff --git a/sidebars.js b/sidebars.js
index f1c76d230..882f4fc09 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -523,6 +523,7 @@ const sidebars = {
           items: [
             "architecture/stack/trace-expansion-proving/proving",
             "architecture/stack/trace-expansion-proving/trace-expansion",
+            "architecture/stack/trace-expansion-proving/prover-limits"
           ],
         },
       ],