docs: link DA scalar guidance

README.md

@@ -206,7 +206,7 @@ This template is used to update the gas limit, elasticity, and DA footprint gas
 1. Fill in any task-specific variables in the `.env` file that have per-network comments (e.g., `OWNER_SAFE`, `SENDER`), using the value for your target network.
 1. Ensure the `SENDER` variable in the `.env` file is set to a signer of `OWNER_SAFE`.
 1. Set the `FROM_*` and `TO_*` values for gas limit and elasticity in the `.env` file.
-1. Calculate the DA footprint gas scalar with `make da-scalar TARGET_BLOB_COUNT=<value>` and set the `FROM_DA_FOOTPRINT_GAS_SCALAR` and `TO_DA_FOOTPRINT_GAS_SCALAR` values in the `.env` file.
+1. Calculate the DA footprint gas scalar using the DA limits runbook at `go/base-da-config`. `make da-scalar TARGET_BLOB_COUNT=<value>` is the source of truth for the standard soft-cap policy and calculates `gas_limit / (elasticity * da_soft_cap_blob_count * 32,000)`. Since BPO2, Base has used a DA soft-cap blob count of 21, passed as `TARGET_BLOB_COUNT=21`, to allow the chain to use all L1 DA before raising the L2 base fee. The command prints the `.env` value and the DA table to copy into the task README. Pass `BUILDER_HARD_CAP=<value>` after checking the target network's `op_batcher_throttle_block_size_upper_limit` Config Service value. The task README includes links for the standard network scopes. Set the `FROM_DA_FOOTPRINT_GAS_SCALAR` and `TO_DA_FOOTPRINT_GAS_SCALAR` values in the `.env` file.
 1. Build the contracts with `forge build`.
 1. Generate the validation file for signers with `make gen-validation`.
 1. Generate the rollback validation file for signers with `make gen-validation-rollback`.

setup-templates/template-gas-and-elasticity-increase/.env

@@ -20,7 +20,7 @@ TO_ELASTICITY=TODO
 FROM_DA_FOOTPRINT_GAS_SCALAR=TODO
 
 # Required: New DA footprint gas scalar to set
-# Formula: gas_limit / (elasticity * target_blob_count * 32,000)
+# Use `make da-scalar TARGET_BLOB_COUNT=<value>` to calculate expected value
 TO_DA_FOOTPRINT_GAS_SCALAR=TODO
 
 # Required: Address of a signer on OWNER_SAFE (used for simulation)

setup-templates/template-gas-and-elasticity-increase/Makefile

@@ -12,6 +12,7 @@ endif
 
 RPC_URL = $(L1_RPC_URL)
 SCRIPT_NAME = IncreaseEip1559ElasticityAndIncreaseGasLimitScript
+BUILDER_HARD_CAP ?= TODO
 
 # Validate required configuration before execution
 .PHONY: validate-config
@@ -29,7 +30,7 @@ validate-config:
 	@echo "Configuration validated successfully"
 
 # Calculate the DA footprint gas scalar based on the formula:
-# da_footprint_gas_scalar = gas_limit / (elasticity * target_blob_count * 32,000)
+# da_footprint_gas_scalar = gas_limit / (elasticity * da_soft_cap_blob_count * 32,000)
 # Uses TO_GAS_LIMIT and TO_ELASTICITY from .env
 .PHONY: da-scalar
 da-scalar:
@@ -42,8 +43,24 @@ endif
 ifeq ($(TO_ELASTICITY),TODO)
 	$(error TO_ELASTICITY is not set. Please set it in .env before running this command.)
 endif
-	@echo "$(TO_GAS_LIMIT) / ($(TO_ELASTICITY) * $(TARGET_BLOB_COUNT) * 32000) ="
-	@echo "TO_DA_FOOTPRINT_GAS_SCALAR=$$(( $(TO_GAS_LIMIT) / ($(TO_ELASTICITY) * $(TARGET_BLOB_COUNT) * 32000) ))"
+	@scalar=$$(( $(TO_GAS_LIMIT) / ($(TO_ELASTICITY) * $(TARGET_BLOB_COUNT) * 32000) )); \
+	soft_cap=$$(( $(TARGET_BLOB_COUNT) * 32000 )); \
+	echo "$(TO_GAS_LIMIT) / ($(TO_ELASTICITY) * $(TARGET_BLOB_COUNT) * 32000) = $$scalar"; \
+	echo; \
+	echo "Set in .env:"; \
+	echo "TO_DA_FOOTPRINT_GAS_SCALAR=$$scalar"; \
+	echo; \
+	echo "Copy into README.md:"; \
+	echo "Set BUILDER_HARD_CAP=<value> from Config Service to fill the builder hard cap row."; \
+	echo; \
+	echo "| Field | Value |"; \
+	echo "|-------|-------|"; \
+	echo "| Gas limit | \`$(TO_GAS_LIMIT)\` |"; \
+	echo "| Elasticity | \`$(TO_ELASTICITY)\` |"; \
+	echo "| DA soft-cap blob count (\`TARGET_BLOB_COUNT\`) | \`$(TARGET_BLOB_COUNT)\` |"; \
+	echo "| Calculated scalar | \`$$scalar\` |"; \
+	echo "| Implied soft cap | \`$$soft_cap\` estimated DA bytes per L2 block |"; \
+	echo "| Builder hard cap | \`$(BUILDER_HARD_CAP)\` estimated DA bytes per L2 block |"
 
 .PHONY: gen-validation
 gen-validation: validate-config deps-signer-tool

setup-templates/template-gas-and-elasticity-increase/README.md

@@ -10,32 +10,30 @@ This runbook invokes the following script which allows our signers to sign the s
 
 `IncreaseEip1559ElasticityAndIncreaseGasLimitScript` -- This script will update the gas limit to our new limit of TODO gas, TODO elasticity, and TODO DA footprint gas scalar if invoked as part of the "upgrade" process, or revert to the old limit of TODO gas, TODO elasticity, and TODO DA footprint gas scalar if invoked as part of the "rollback" process.
 
-### DA Footprint Gas Scalar Formula
+### DA Footprint Gas Scalar
 
-We typically set the DA footprint gas scalar to cause base fees to rise if and only if the DA usage exceeds the L1 target blob throughput. (Below that level of DA usage, the normal base fee rules apply.) We use the following formula:
+Calculate the DA footprint gas scalar from the DA limits runbook:
 
-```
-da_footprint_gas_scalar = gas_limit / (elasticity * l2_block_time * l1_target_throughput * estimation_ratio)
-```
+`go/base-da-config`
 
-Where:
-- `gas_limit` = L2 gas limit per block
-- `elasticity` = EIP-1559 elasticity multiplier
-- `l2_block_time` = 2 seconds
-- `l1_target_throughput = (target_blob_count * 128,000 bytes/blob) / 12 sec/block`
-- `target_blob_count` = target number of blobs per L1 block
-- `estimation_ratio` = 1.5 to account for differences between compression estimates and actual usage
+`make da-scalar TARGET_BLOB_COUNT=<value>` is the source of truth for the standard soft-cap policy. Since BPO2, Base has used a DA soft-cap blob count of 21, passed as `TARGET_BLOB_COUNT=21`, to allow the chain to use all L1 DA before raising the L2 base fee. Do not read this as Ethereum's target blob count; it is the blob-count input to Base's DA footprint scalar calculation.
 
-This simplifies to:
+Record the inputs used for this task:
 
-```
-da_footprint_gas_scalar = gas_limit / (elasticity * target_blob_count * 32,000)
-```
+Use the target network's `op_batcher_throttle_block_size_upper_limit` Config Service value for the builder hard cap row.
 
-Example with gas_limit = 120,000,000, elasticity = 2, and target_blob_count = 6:
-```
-da_footprint_gas_scalar = 120,000,000 / (2 * 6 * 32,000) = 312.5 ≈ 312
-```
+- Mainnet: `https://config.cbhq.net/web3-shared-prod/protocols/base-mainnet-batcherproposer-k8s?q=op_batcher_throttle_block_size_upper_limit`
+- Sepolia: `https://config.cbhq.net/web3-shared-prod/protocols/base-sepolia-batcherproposer-k8s?q=op_batcher_throttle_block_size_upper_limit`
+- Zeronet: `https://config.cbhq.net/web3-shared-dev/protocols/base-zeronet-batcherproposer-k8s?q=op_batcher_throttle_block_size_upper_limit`
+
+| Field | Value |
+|-------|-------|
+| Gas limit | TODO |
+| Elasticity | TODO |
+| DA soft-cap blob count (`TARGET_BLOB_COUNT`) | TODO |
+| Calculated scalar | TODO |
+| Implied soft cap | TODO estimated DA bytes per L2 block |
+| Builder hard cap | TODO estimated DA bytes per L2 block |
 
 The values we are sending are statically defined in the `.env` file.