From a7eddb6d10bd2c9fadfefbefe02fef256ecff18b Mon Sep 17 00:00:00 2001
From: Maxim Vezenov <mvezenov@gmail.com>
Date: Thu, 13 Aug 2026 15:37:30 -0400
Subject: [PATCH 1/2] docs: clarify that gasLimits includes teardownGasLimits

---
 .../docs/aztec-js/how_to_pay_fees.md          |  6 +++--
 .../components/Snippets/general_snippets.js   | 23 ++++++++++++-------
 yarn-project/stdlib/src/gas/gas_settings.ts   |  4 ++++
 .../src/base-wallet/get_gas_limits.ts         |  4 ++--
 4 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md b/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
index 0669fa11d26a..823e1a33c164 100644
--- a/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
+++ b/docs/docs-developers/docs/aztec-js/how_to_pay_fees.md
@@ -185,11 +185,13 @@ After this transaction is minted on L1 and a few blocks pass, you can claim the
 
 Gas settings specify limits and fees for both DA and L2 dimensions:
 
-- **gasLimits**: Maximum mana for main execution phase
-- **teardownGasLimits**: Maximum mana for teardown phase (used by FPCs for refunds)
+- **gasLimits**: Maximum mana the transaction may consume in total, across all phases including teardown
+- **teardownGasLimits**: Portion of `gasLimits` reserved for the teardown phase (used by FPCs for refunds)
 - **maxFeesPerGas**: Maximum price you're willing to pay per mana unit
 - **maxPriorityFeesPerGas**: Priority fee for faster inclusion
 
+Teardown gas is not added on top of `gasLimits`: it is a reservation carved out of the total, so the mana available to the rest of the transaction is `gasLimits - teardownGasLimits`. A transaction with a teardown call is billed the full `teardownGasLimits`, regardless of how much teardown actually consumes.
+
 The fee limit is calculated as `gasLimits × maxFeesPerGas` for each dimension.
 
 ### Set custom gas limits
diff --git a/docs/src/components/Snippets/general_snippets.js b/docs/src/components/Snippets/general_snippets.js
index e47d598e21ef..df768ea82d83 100644
--- a/docs/src/components/Snippets/general_snippets.js
+++ b/docs/src/components/Snippets/general_snippets.js
@@ -13,7 +13,10 @@ export const General = {
   InstallationInstructions: () => (
     <p>
       To use Aztec's suite of tools, run:{" "}
-      <code>VERSION=&lt;version&gt; bash -i &lt;(curl -sL https://install.aztec.network/&lt;version&gt;)</code>
+      <code>
+        VERSION=&lt;version&gt; bash -i &lt;(curl -sL
+        https://install.aztec.network/&lt;version&gt;)
+      </code>
     </p>
   ),
 
@@ -44,8 +47,8 @@ export const General = {
 
   AztecLocalNetwork: () => (
     <p>
-      <b>Aztec's Local network</b> - runs a set of Aztec tools for convenient local
-      development, it includes: an Ethereum node, an Aztec node, and PXE.
+      <b>Aztec's Local network</b> - runs a set of Aztec tools for convenient
+      local development, it includes: an Ethereum node, an Aztec node, and PXE.
     </p>
   ),
 
@@ -69,8 +72,8 @@ export const General = {
 
   AztecJSPrerequisites: ({ href = "how_to_connect_to_local_network" }) => (
     <>
-      <a href={href}>Connected to a network</a>{" "}
-      with an <code>EmbeddedWallet</code> instance and funded accounts
+      <a href={href}>Connected to a network</a> with an{" "}
+      <code>EmbeddedWallet</code> instance and funded accounts
     </>
   ),
 };
@@ -140,10 +143,14 @@ export const Gas_Settings_Components = () => (
     The <code>Gas</code> and <code>GasFees</code> types each specify Data
     availability and L2 cost components, so the settings are:
     <ul>
-      <li>gasLimits: DA and L2 gas limits</li>
       <li>
-        teardownGasLimits: DA and L2 gas limits for a txs optional teardown
-        operation
+        gasLimits: total DA and L2 gas limits for the transaction, covering all
+        phases including teardown
+      </li>
+      <li>
+        teardownGasLimits: portion of gasLimits reserved for a txs optional
+        teardown operation. A tx with a teardown call is billed these limits in
+        full, regardless of actual teardown consumption
       </li>
       <li>maxFeesPerGas: maximum DA and L2 fees-per-gas</li>
       <li>maxPriorityFeesPerGas: maximum priority DA and L2 fees-per-gas</li>
diff --git a/yarn-project/stdlib/src/gas/gas_settings.ts b/yarn-project/stdlib/src/gas/gas_settings.ts
index 4672f16be52a..69336f573d06 100644
--- a/yarn-project/stdlib/src/gas/gas_settings.ts
+++ b/yarn-project/stdlib/src/gas/gas_settings.ts
@@ -20,9 +20,13 @@ export const GAS_ESTIMATION_DA_GAS_LIMIT = GAS_ESTIMATION_TEARDOWN_DA_GAS_LIMIT
 /** Gas usage and fees limits set by the transaction sender for different dimensions and phases. */
 export class GasSettings {
   constructor(
+    /** Total gas the tx may consume across all phases, teardown included. */
     public readonly gasLimits: Gas,
+    /** Portion of gasLimits reserved for the teardown phase, billed in full when the tx has a teardown call. */
     public readonly teardownGasLimits: Gas,
+    /** Maximum fees per gas unit the sender is willing to pay. */
     public readonly maxFeesPerGas: GasFees,
+    /** Priority fees per gas unit paid on top of the base fee for faster inclusion. */
     public readonly maxPriorityFeesPerGas: GasFees,
   ) {}
   // docs:end:gas_settings_vars
diff --git a/yarn-project/wallet-sdk/src/base-wallet/get_gas_limits.ts b/yarn-project/wallet-sdk/src/base-wallet/get_gas_limits.ts
index 4233325270a7..c6091c3299ab 100644
--- a/yarn-project/wallet-sdk/src/base-wallet/get_gas_limits.ts
+++ b/yarn-project/wallet-sdk/src/base-wallet/get_gas_limits.ts
@@ -23,11 +23,11 @@ export function getGasLimits(
   pad = 0.1,
 ): {
   /**
-   * Gas limit for the tx, excluding teardown gas
+   * Total gas limit for the tx, including teardown gas
    */
   gasLimits: Gas;
   /**
-   * Gas limit for the teardown phase
+   * Portion of the total gas limit reserved for the teardown phase
    */
   teardownGasLimits: Gas;
 } {

From abde750d65e591f78253b86ce2aa7e5296f8a8ee Mon Sep 17 00:00:00 2001
From: Maxim Vezenov <mvezenov@gmail.com>
Date: Thu, 13 Aug 2026 15:40:20 -0400
Subject: [PATCH 2/2] docs: address review wording

---
 docs/src/components/Snippets/general_snippets.js | 6 +++---
 yarn-project/stdlib/src/gas/gas_settings.ts      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/src/components/Snippets/general_snippets.js b/docs/src/components/Snippets/general_snippets.js
index df768ea82d83..8efe471cef6d 100644
--- a/docs/src/components/Snippets/general_snippets.js
+++ b/docs/src/components/Snippets/general_snippets.js
@@ -148,9 +148,9 @@ export const Gas_Settings_Components = () => (
         phases including teardown
       </li>
       <li>
-        teardownGasLimits: portion of gasLimits reserved for a txs optional
-        teardown operation. A tx with a teardown call is billed these limits in
-        full, regardless of actual teardown consumption
+        teardownGasLimits: portion of gasLimits reserved for an optional
+        teardown call. A tx with a teardown call is billed these limits in full,
+        regardless of actual teardown consumption
       </li>
       <li>maxFeesPerGas: maximum DA and L2 fees-per-gas</li>
       <li>maxPriorityFeesPerGas: maximum priority DA and L2 fees-per-gas</li>
diff --git a/yarn-project/stdlib/src/gas/gas_settings.ts b/yarn-project/stdlib/src/gas/gas_settings.ts
index 69336f573d06..9bee81d61b69 100644
--- a/yarn-project/stdlib/src/gas/gas_settings.ts
+++ b/yarn-project/stdlib/src/gas/gas_settings.ts
@@ -26,7 +26,7 @@ export class GasSettings {
     public readonly teardownGasLimits: Gas,
     /** Maximum fees per gas unit the sender is willing to pay. */
     public readonly maxFeesPerGas: GasFees,
-    /** Priority fees per gas unit paid on top of the base fee for faster inclusion. */
+    /** Maximum priority fees per gas unit the sender is willing to pay on top of the base fee. */
     public readonly maxPriorityFeesPerGas: GasFees,
   ) {}
   // docs:end:gas_settings_vars