From db2d556f211965b50d9bd065ca9255b56ec2d242 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Tue, 11 Nov 2025 17:38:28 -0500 Subject: [PATCH 01/11] feat:setting da footprint guide created --- .../guides/features/setting-da-footprint.mdx | 100 ++++++++++++++++++ docs.json | 3 +- 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 chain-operators/guides/features/setting-da-footprint.mdx diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx new file mode 100644 index 000000000..2113428a2 --- /dev/null +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -0,0 +1,100 @@ +--- +title: Set the DA Footprint +description: Learn how to set a Data Availability (DA) Footprint on your OP-Stack Chain +--- + +## Overview + +| Parameter | Type | Default | Recommended | Units | +| ---------- | ---- | -------- | ------------ | ------------ | +| `daFootprintGasScalar` | Number | 400 | 400 | unitless| + +The Data Availibility (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. +When an OP Stack chain recieves more calldata heavy transactions than can fit into the L1s availble blob space, [the Batcher](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup#understanding-the-batchers-role) +[can throttle it's capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). + +However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), +causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions. Limiting the amount of calldata taken up by transactions in an block using the DA Footprint can reduce the need for batcher throttling and the issues that come from throttling. + +For every transaction, other than [deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction), +processed by an OP Stack chain, a resource called DA Footprint is tracked alongside the transaction's gas usage. +The DA Footprint can be configured via the `daFootprintGasScalar` variable in the `SystemConfig` contract on the L1 chain. +The Da Footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction: + +```python +daUsageEstimate = max( + minTransactionSize, + (intercept + fastlzCoef * tx.fastlzSize) // 1e6 + ) +``` + +then the `daUsageEstimate` is then multiplied by the `daFootprintGasScalar` to get the `daFootprint` for that individual transaction. + +```python + daFootprint += daUsageEstimate * daFootprintGasScalar +``` + +The `daFootprint` for all the transactions in a block are then added together to calculate that blocks total `daFootprint`. +With the blocks total `daFootprint` calculated: + + +- The blocks total `daFootprint` must stay below the `gasLimit` for the chain. +- The `blobGasUsed` property of each block header is set to that block's `daFootprint` +- The base fee update calculation then uses `gasMetered := max(gasUsed, blobGasUsed)` + + +The steps below explain how to update the `daFootprintGasScalar` parameter on-chain using the `SystemConfig` contract. + + + - Setting the `daFootprintGasScalar` too high may exclude too many transactions from your blocks. + - Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against spam. + - When a chain's gas limit is changed, the DA footprint scales proportionally by design. However you want to retain the same absolute DA footprint limit, then you must the also change the `daFootprintGasScalar`. + - If no limit is set, or the value 0 is set for the daFootprintGasScalar in the SystemConfig, the default value of 400 is used + - If the feature is diabled, set the scalar to a very low value such as 1. + + + +## How to Update the daFootprintGasScalar + + + + The [SystemConfig](https://specs.optimism.io/protocol/system-config.html) contract stores configurable protocol parameters such as gas limits and fee settings. + You can find its proxy address in the [state.json generated by op-deployer](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup#deploy-l1-contracts). + + + + + Note that the owner of the `SystemConfig` contract is the [System Config Owner address](https://docs.optimism.io/chain-operators/reference/privileged-roles#system-config-owner), so this transaction must be sent from that address. + + To update the `daFootprintGasScalar`, call the following method on the `SystemConfig` contract: + + `setDAFootprintGasScalar(uint16 daFootprintGasScalar) external onlyOwner;` + + Example (using [cast](https://getfoundry.sh/cast/reference/cast/)): + + ``` + cast send "daFootprintGasScalar(uint16)" 405 + ``` + + + + After the transaction confirms, verify the current value by calling the following getter method on the `SystemConfig` contract: + + `function daFootprintGasScalar() external view returns (uint16);` + + Example (using [cast](https://getfoundry.sh/cast/reference/cast/)): + + ``` + cast call "daFootprintGasScalar()" + ``` + + + +--- + +## References + +* [DA Footprint Configuration Spec](https://specs.optimism.io/protocol/jovian/system-config.html#da-footprint-configuration) +* [Jovian Upgrade Spec](https://specs.optimism.io/protocol/jovian/overview.html) +* [SystemConfig Contract Spec](https://specs.optimism.io/protocol/system-config.html) +* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md) \ No newline at end of file diff --git a/docs.json b/docs.json index 423819ff3..325bdd948 100644 --- a/docs.json +++ b/docs.json @@ -1550,7 +1550,8 @@ "group": "Features", "pages": [ "chain-operators/guides/features/alt-da-mode", - "chain-operators/guides/features/setting-min-base-fee" + "chain-operators/guides/features/setting-min-base-fee", + "chain-operators/guides/features/setting-da-footprint" ] }, { From 62b5d8469791ee34f1755e41f28147dcf9b52204 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 13:48:44 -0500 Subject: [PATCH 02/11] Apply suggestions from code review Co-authored-by: George Knee Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- chain-operators/guides/features/setting-da-footprint.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 2113428a2..b30db152e 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -1,5 +1,5 @@ --- -title: Set the DA Footprint +title: Set the DA Footprint Gas Scalar description: Learn how to set a Data Availability (DA) Footprint on your OP-Stack Chain --- @@ -9,7 +9,7 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac | ---------- | ---- | -------- | ------------ | ------------ | | `daFootprintGasScalar` | Number | 400 | 400 | unitless| -The Data Availibility (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. +The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. When an OP Stack chain recieves more calldata heavy transactions than can fit into the L1s availble blob space, [the Batcher](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup#understanding-the-batchers-role) [can throttle it's capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). From 3fc4ac834157b9d065238e2018028353ce0feca8 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 13:49:15 -0500 Subject: [PATCH 03/11] Apply suggestions from code review Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- chain-operators/guides/features/setting-da-footprint.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index b30db152e..b18f6b509 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -10,7 +10,7 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac | `daFootprintGasScalar` | Number | 400 | 400 | unitless| The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. -When an OP Stack chain recieves more calldata heavy transactions than can fit into the L1s availble blob space, [the Batcher](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup#understanding-the-batchers-role) +When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, [the Batcher's](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup#understanding-the-batchers-role) [can throttle it's capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), @@ -19,7 +19,7 @@ causing unnecessary losses for the chain operator and negative user experiences For every transaction, other than [deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction), processed by an OP Stack chain, a resource called DA Footprint is tracked alongside the transaction's gas usage. The DA Footprint can be configured via the `daFootprintGasScalar` variable in the `SystemConfig` contract on the L1 chain. -The Da Footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction: +The DA Footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction: ```python daUsageEstimate = max( @@ -47,7 +47,7 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch - Setting the `daFootprintGasScalar` too high may exclude too many transactions from your blocks. - - Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against spam. + - Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against continuous DA heavy transactions. - When a chain's gas limit is changed, the DA footprint scales proportionally by design. However you want to retain the same absolute DA footprint limit, then you must the also change the `daFootprintGasScalar`. - If no limit is set, or the value 0 is set for the daFootprintGasScalar in the SystemConfig, the default value of 400 is used - If the feature is diabled, set the scalar to a very low value such as 1. From c7a4143a03d6c6725e749f18c9e0a1d8a573529e Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 13:49:54 -0500 Subject: [PATCH 04/11] Apply suggestions from code review Co-authored-by: George Knee Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- chain-operators/guides/features/setting-da-footprint.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index b18f6b509..7c6d0c452 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -62,9 +62,9 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch You can find its proxy address in the [state.json generated by op-deployer](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup#deploy-l1-contracts). - + - Note that the owner of the `SystemConfig` contract is the [System Config Owner address](https://docs.optimism.io/chain-operators/reference/privileged-roles#system-config-owner), so this transaction must be sent from that address. + The [SystemConfig owner](https://docs.optimism.io/chain-operators/reference/privileged-roles#system-config-owner) is the only address that can make these changes. To update the `daFootprintGasScalar`, call the following method on the `SystemConfig` contract: From 0f64cab5cda50062238be4ead5c4acae0c3ed541 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:03:23 -0500 Subject: [PATCH 05/11] fix:cleanup from review --- .../guides/features/setting-da-footprint.mdx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 7c6d0c452..31dee5095 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -7,11 +7,14 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac | Parameter | Type | Default | Recommended | Units | | ---------- | ---- | -------- | ------------ | ------------ | -| `daFootprintGasScalar` | Number | 400 | 400 | unitless| +| `daFootprintGasScalar` | Number | 0 (400) | 400 | gas per byte | + + +The default value of 0 is the same as setting the scalar to 400. In order to effectively disable this feature, set the scalar to a very low value such as 1. + The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. -When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, [the Batcher's](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup#understanding-the-batchers-role) -[can throttle it's capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). +When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions. Limiting the amount of calldata taken up by transactions in an block using the DA Footprint can reduce the need for batcher throttling and the issues that come from throttling. @@ -46,11 +49,11 @@ With the blocks total `daFootprint` calculated: The steps below explain how to update the `daFootprintGasScalar` parameter on-chain using the `SystemConfig` contract. + - If no limit is set, or the value 0 is set for the daFootprintGasScalar in the SystemConfig, the default value of 400 is used + - In order to effectively disable this feature, set the scalar to a very low value such as 1. - Setting the `daFootprintGasScalar` too high may exclude too many transactions from your blocks. - Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against continuous DA heavy transactions. - When a chain's gas limit is changed, the DA footprint scales proportionally by design. However you want to retain the same absolute DA footprint limit, then you must the also change the `daFootprintGasScalar`. - - If no limit is set, or the value 0 is set for the daFootprintGasScalar in the SystemConfig, the default value of 400 is used - - If the feature is diabled, set the scalar to a very low value such as 1. @@ -62,7 +65,7 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch You can find its proxy address in the [state.json generated by op-deployer](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup#deploy-l1-contracts). - + The [SystemConfig owner](https://docs.optimism.io/chain-operators/reference/privileged-roles#system-config-owner) is the only address that can make these changes. From 8e5c0a30c0b2c27fd78457a94d900495ee8117a9 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:10:48 -0500 Subject: [PATCH 06/11] fix:cleanup based on review --- chain-operators/guides/features/setting-da-footprint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 31dee5095..52f2a7681 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -13,7 +13,7 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac The default value of 0 is the same as setting the scalar to 400. In order to effectively disable this feature, set the scalar to a very low value such as 1. -The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of estimated compressed transaction data that can fit into a block. +The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), From 585b39642648e12bdeb6dd931bdbc3892e45cb1f Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:33:12 -0500 Subject: [PATCH 07/11] fix:clean up sentence wording --- chain-operators/guides/features/setting-da-footprint.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 52f2a7681..d8a85d981 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -13,14 +13,13 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac The default value of 0 is the same as setting the scalar to 400. In order to effectively disable this feature, set the scalar to a very low value such as 1. -The Data Availability (DA) Footprint feature was introduced in the Jovian hardfork to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. +The Data Availability (DA) Footprint feature was introduced in the [Jovian](https://docs.optimism.io/notices/upgrade-17) hardfork to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions. Limiting the amount of calldata taken up by transactions in an block using the DA Footprint can reduce the need for batcher throttling and the issues that come from throttling. -For every transaction, other than [deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction), -processed by an OP Stack chain, a resource called DA Footprint is tracked alongside the transaction's gas usage. +For all [non-deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction) processed by an OP Stack chain, a DA Footprint value is recorded alongside the transaction's gas usage The DA Footprint can be configured via the `daFootprintGasScalar` variable in the `SystemConfig` contract on the L1 chain. The DA Footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction: From 919e4fc9f523d9008c13ad8323bc98f99bece18a Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 12 Nov 2025 15:45:27 -0500 Subject: [PATCH 08/11] cleanup --- chain-operators/guides/features/setting-da-footprint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index d8a85d981..917e87079 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -13,7 +13,7 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac The default value of 0 is the same as setting the scalar to 400. In order to effectively disable this feature, set the scalar to a very low value such as 1. -The Data Availability (DA) Footprint feature was introduced in the [Jovian](https://docs.optimism.io/notices/upgrade-17) hardfork to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. +The Data Availability (DA) Footprint feature was introduced in the [Jovian hardfork](https://docs.optimism.io/notices/upgrade-17) to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), From d35bb0616cefc21feb53482b2f7df24b0b5a96f1 Mon Sep 17 00:00:00 2001 From: Sebastian Stammler Date: Thu, 13 Nov 2025 19:13:23 +0100 Subject: [PATCH 09/11] Improve DA Footprint documentation (#1864) Updated formatting and clarified descriptions for the DA Footprint feature and its parameters. --- .../guides/features/setting-da-footprint.mdx | 75 +++++++++++++------ 1 file changed, 54 insertions(+), 21 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 917e87079..e30576fee 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -7,19 +7,23 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac | Parameter | Type | Default | Recommended | Units | | ---------- | ---- | -------- | ------------ | ------------ | -| `daFootprintGasScalar` | Number | 0 (400) | 400 | gas per byte | +| `daFootprintGasScalar` | Number | `0` (`400`) | `400` | gas per byte | -The default value of 0 is the same as setting the scalar to 400. In order to effectively disable this feature, set the scalar to a very low value such as 1. +The default value of `0` is the same as setting the scalar to `400`. In order to effectively disable this feature, set the scalar to a very low value such as `1`. -The Data Availability (DA) Footprint feature was introduced in the [Jovian hardfork](https://docs.optimism.io/notices/upgrade-17) to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. -When an OP Stack chain receives more calldata heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains capacity](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). +The Data Availability (DA) Footprint Block Limit was introduced in the [Jovian hardfork](https://docs.optimism.io/notices/upgrade-17) to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. +When an OP Stack chain receives more calldata-heavy transactions than can fit into the L1s available blob space, the [Batcher can throttle the chains throughput](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling). However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee), -causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions. Limiting the amount of calldata taken up by transactions in an block using the DA Footprint can reduce the need for batcher throttling and the issues that come from throttling. +causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions. +And without throttling, the batcher runs the risk of becoming overwhelmed with chain data to batch to the blob space. +Limiting the amount of (estimated compressed) calldata taken up by transactions in a block using their total DA Footprint can reduce the need for batcher throttling and its related issues. -For all [non-deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction) processed by an OP Stack chain, a DA Footprint value is recorded alongside the transaction's gas usage +## DA Footprint Calculation + +For all [non-deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction) processed by an OP Stack chain, a DA Footprint value is recorded alongside the transaction's gas usage. The DA Footprint can be configured via the `daFootprintGasScalar` variable in the `SystemConfig` contract on the L1 chain. The DA Footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction: @@ -30,33 +34,54 @@ daUsageEstimate = max( ) ``` -then the `daUsageEstimate` is then multiplied by the `daFootprintGasScalar` to get the `daFootprint` for that individual transaction. +where the `minTransactionSize`, `intercept`, `fastlzCoef`, and `tx.fastlzSize` are as specified in the [Fjord specs](https://specs.optimism.io/protocol/fjord/exec-engine.html#fees). +Then the `daUsageEstimate` is then multiplied by the `daFootprintGasScalar` to get the `daFootprint` for that individual transaction. ```python daFootprint += daUsageEstimate * daFootprintGasScalar ``` -The `daFootprint` for all the transactions in a block are then added together to calculate that blocks total `daFootprint`. -With the blocks total `daFootprint` calculated: +The `daFootprint` for all the transactions in a block are then added together to calculate that block's total `daFootprint`. +With the block's total `daFootprint` calculated: -- The blocks total `daFootprint` must stay below the `gasLimit` for the chain. -- The `blobGasUsed` property of each block header is set to that block's `daFootprint` -- The base fee update calculation then uses `gasMetered := max(gasUsed, blobGasUsed)` +- The block's total `daFootprint` must stay below its `gasLimit`. +- The `blobGasUsed` property of each block header is set to that block's `daFootprint`. +- The base fee update calculation then uses `gasMetered := max(gasUsed, blobGasUsed)` as a replacement for the `gasUsed` variable. -The steps below explain how to update the `daFootprintGasScalar` parameter on-chain using the `SystemConfig` contract. +From Jovian, transaction receipts also record the transaction's DA Footprint in the receipt's `blobGasUsed` field, as well as the block's `daFootprintGasScalar` in a new field with the same name. + +## The DA Footprint Gas Scalar - - If no limit is set, or the value 0 is set for the daFootprintGasScalar in the SystemConfig, the default value of 400 is used - - In order to effectively disable this feature, set the scalar to a very low value such as 1. + - If no limit is set, or the value 0 is set for the `daFootprintGasScalar` in the `SystemConfig`, the default value of `400` is used + - In order to effectively disable this feature, set the scalar to a very low value such as `1`. - Setting the `daFootprintGasScalar` too high may exclude too many transactions from your blocks. - Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against continuous DA heavy transactions. - - When a chain's gas limit is changed, the DA footprint scales proportionally by design. However you want to retain the same absolute DA footprint limit, then you must the also change the `daFootprintGasScalar`. + - When a chain's gas limit is changed, the DA footprint scales proportionally by design. However, if you want to retain the same absolute DA footprint limit, then you must also scale the `daFootprintGasScalar` accordingly. +The _DA footprint gas scalar_ scales the _estimated DA usage in bytes_ to the gas dimension, and this scaled estimate of the DA usage is what we call the _DA footprint_. +This allows us to limit the estimated DA usage using the block's `gasLimit`: the effective limit of estimated DA usage per block is `gasLimit / daFootprintGasScalar` bytes. +So _increasing_ this scalar makes DA usage more gas-heavy, so _decreases_ the limit, and vice versa. + +This is closely related to how the calldata (floor) cost of `40` gas per non-zero byte limits the total amount of calldata in a block. +A DA footprint gas scalar of `400` effectively limits _incompressible_ calldata by a factor of `10` compared to its limit without a DA footprint block limit. +As such, the feature can be seen as an extension of the existing calldata limit. +But instead of repricing the calldata (floor) gas cost, the limit is accounted in parallel to EVM execution gas, and is based on the more relevant FastLZ-based DA usage estimate instead of simply counting zero and non-zero bytes. + +### Default Value `400` + +The default scalar of `400` was chosen so that it protects chains in worst-case DA spam scenarios, but has negligible to no impact during normal operation. +Careful [analyses](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md) have been done to estimate the impact on current OP Stack chains and pick the right default. +Only high-throughput chains would occasionally even see a small impact from the resulting DA footprint limit (as slightly faster rising base fees). The DA footprint limit is mostly invisible. +On mid to low-throughput chains, the feature is expected to have no impact under normal usage conditions. +It acts more like an insurance to protect against worst-case _incompressible_ DA spam. + +### How to Update the `daFootprintGasScalar` -## How to Update the daFootprintGasScalar +The steps below explain how to update the `daFootprintGasScalar` parameter on-chain using the `SystemConfig` contract. @@ -72,10 +97,10 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch `setDAFootprintGasScalar(uint16 daFootprintGasScalar) external onlyOwner;` - Example (using [cast](https://getfoundry.sh/cast/reference/cast/)): + Example (using [cast](https://getfoundry.sh/cast/reference/cast/)) to double the scalar, so lower the effective DA usage limit by half: ``` - cast send "daFootprintGasScalar(uint16)" 405 + cast send -r "daFootprintGasScalar(uint16)" 800 ``` @@ -87,11 +112,19 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch Example (using [cast](https://getfoundry.sh/cast/reference/cast/)): ``` - cast call "daFootprintGasScalar()" + cast call -r "daFootprintGasScalar()" + ``` + + And on your L2 chain you can query the scalar at the `L1Block` predeploy to confirm the new scalar has been propagated to the chain: + + ``` + cast call -r 0x4200000000000000000000000000000000000015 "daFootprintGasScalar()" ``` +### + --- ## References @@ -99,4 +132,4 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch * [DA Footprint Configuration Spec](https://specs.optimism.io/protocol/jovian/system-config.html#da-footprint-configuration) * [Jovian Upgrade Spec](https://specs.optimism.io/protocol/jovian/overview.html) * [SystemConfig Contract Spec](https://specs.optimism.io/protocol/system-config.html) -* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md) \ No newline at end of file +* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md) From bf19b9cd5069cadf842149916df745b897435b6a Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 13 Nov 2025 13:31:17 -0500 Subject: [PATCH 10/11] add hyperlink to specs for default value behavior --- chain-operators/guides/features/setting-da-footprint.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index e30576fee..0dc1b3d38 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -7,10 +7,11 @@ description: Learn how to set a Data Availability (DA) Footprint on your OP-Stac | Parameter | Type | Default | Recommended | Units | | ---------- | ---- | -------- | ------------ | ------------ | -| `daFootprintGasScalar` | Number | `0` (`400`) | `400` | gas per byte | +| `daFootprintGasScalar` | Number | `0` (`400`) | `400` | gas per byte | The default value of `0` is the same as setting the scalar to `400`. In order to effectively disable this feature, set the scalar to a very low value such as `1`. +See the [specs for more detail](https://specs.optimism.io/protocol/jovian/l1-attributes.html). The Data Availability (DA) Footprint Block Limit was introduced in the [Jovian hardfork](https://docs.optimism.io/notices/upgrade-17) to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data. From 2b78b2754ecb7d2d2dab845cf080b61862b2a8e9 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 13 Nov 2025 13:51:50 -0500 Subject: [PATCH 11/11] update code formatting --- chain-operators/guides/features/setting-da-footprint.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/chain-operators/guides/features/setting-da-footprint.mdx b/chain-operators/guides/features/setting-da-footprint.mdx index 0dc1b3d38..c996538da 100644 --- a/chain-operators/guides/features/setting-da-footprint.mdx +++ b/chain-operators/guides/features/setting-da-footprint.mdx @@ -100,7 +100,7 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch Example (using [cast](https://getfoundry.sh/cast/reference/cast/)) to double the scalar, so lower the effective DA usage limit by half: - ``` + ```bash title="Cast" cast send -r "daFootprintGasScalar(uint16)" 800 ``` @@ -112,13 +112,13 @@ The steps below explain how to update the `daFootprintGasScalar` parameter on-ch Example (using [cast](https://getfoundry.sh/cast/reference/cast/)): - ``` + ```bash title="Cast" cast call -r "daFootprintGasScalar()" ``` - And on your L2 chain you can query the scalar at the `L1Block` predeploy to confirm the new scalar has been propagated to the chain: + And on your L2 chain you can query the scalar at the [L1Block predeploy](https://specs.optimism.io/protocol/predeploys.html#l1block) to confirm the new scalar has been propagated to the chain: - ``` + ```bash title="Cast" cast call -r 0x4200000000000000000000000000000000000015 "daFootprintGasScalar()" ```