refactor(protocol,taiko-client-rs,taiko-client): move LibManifest constants to Derivation.md (#20545)

Co-authored-by: Claude <noreply@anthropic.com>

Author: dantaik

packages/protocol/contracts/layer1/core/libs/LibManifest.sol

@@ -4,38 +4,9 @@ pragma solidity ^0.8.24;
 /// @title LibManifest
 /// @custom:security-contact security@taiko.xyz
 library LibManifest {
-    // ---------------------------------------------------------------
-    // Constants
-    // ---------------------------------------------------------------
-    /// @notice The maximum number of blocks allowed in a proposal. If we assume block time is as
-    /// small as one second, 384 blocks will cover an Ethereum epoch.
-    uint256 internal constant PROPOSAL_MAX_BLOCKS = 384;
-
-    /// @notice The maximum anchor block number offset from the proposal origin block number.
-    uint256 internal constant ANCHOR_MAX_OFFSET = 128;
-
-    /// @notice The minimum anchor block number offset from the proposal origin block number.
-    uint256 internal constant ANCHOR_MIN_OFFSET = 2;
-
-    /// @notice The maximum number timestamp offset from the proposal origin timestamp.
-    uint256 internal constant TIMESTAMP_MAX_OFFSET = 12 * 32;
-
-    /// @notice The maximum block gas limit change per block, in millionths (1/1,000,000).
-    /// @dev For example, 10 = 10 / 1,000,000 = 0.001%.
-    uint256 internal constant BLOCK_GAS_LIMIT_MAX_CHANGE = 10;
-
-    /// @notice The minimum block gas limit.
-    /// @dev This ensures block gas limit never drops below a critical threshold.
-    uint256 internal constant MIN_BLOCK_GAS_LIMIT = 15_000_000;
-
-    /// @notice The delay in processing bond instructions relative to the current proposal. A value
-    /// of 1 signifies that the bond instructions of the immediate parent proposal will be
-    /// processed.
-    uint256 internal constant BOND_PROCESSING_DELAY = 6;
-
     // ---------------------------------------------------------------
     // Structs
-    // ---------------------------------------------------------------
+     // ---------------------------------------------------------------
 
     /// @notice Represents a signed Ethereum transaction
     /// @dev Follows EIP-2718 typed transaction format with EIP-1559 support

packages/protocol/docs/Derivation.md

@@ -277,8 +277,8 @@ Anchor block validation ensures proper L1 state synchronization and may trigger
 **Invalidation conditions** (sets `anchorBlockNumber` to `parent.metadata.anchorBlockNumber`):
 
 - **Non-monotonic progression**: `manifest.blocks[i].anchorBlockNumber < parent.metadata.anchorBlockNumber`
-- **Future reference**: `manifest.blocks[i].anchorBlockNumber >= proposal.originBlockNumber - ANCHOR_MIN_OFFSET`
-- **Excessive lag**: `manifest.blocks[i].anchorBlockNumber < proposal.originBlockNumber - ANCHOR_MAX_OFFSET`
+- **Future reference**: `manifest.blocks[i].anchorBlockNumber >= proposal.originBlockNumber - MIN_ANCHOR_OFFSET`
+- **Excessive lag**: `manifest.blocks[i].anchorBlockNumber < proposal.originBlockNumber - MAX_ANCHOR_OFFSET`
 
 **Forced inclusion protection**: For non-forced derivation sources (`derivationSource.isForcedInclusion == false`), if no blocks have valid anchor numbers greater than its parent's, the entire source manifest is replaced with the default source manifest (single block with only an anchor transaction), penalizing proposers that fail to provide proper L1 anchoring. Forced inclusion sources are exempt from this penalty.
 
@@ -564,8 +564,26 @@ The anchor transaction executes a carefully orchestrated sequence of operations:
 - Gas limit: Exactly 1,000,000 gas (enforced by the Taiko node software)
 - Caller restriction: Golden touch address (system account) only
 
-### Transaction Execution
 
 ## Base Fee Calculation
 
 The calculation of block base fee shall follow [EIP-4396](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4396.md#specification).
+
+
+## Constants
+
+The following constants govern the block derivation process:
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| **PROPOSAL_MAX_BLOCKS** | `384` | The maximum number of blocks allowed in a proposal. If we assume block time is as small as one second, 384 blocks will cover an Ethereum epoch. |
+| **MAX_ANCHOR_OFFSET** | `128` | The maximum anchor block number offset from the proposal origin block number. |
+| **MIN_ANCHOR_OFFSET** | `2` | The minimum anchor block number offset from the proposal origin block number. |
+| **TIMESTAMP_MAX_OFFSET** | `384` (12 * 32) | The maximum number timestamp offset from the proposal origin timestamp. |
+| **BLOCK_GAS_LIMIT_MAX_CHANGE** | `10` | The maximum block gas limit change per block, in millionths (1/1,000,000). For example, 10 = 10 / 1,000,000 = 0.001%. |
+| **MIN_BLOCK_GAS_LIMIT** | `15,000,000` | The minimum block gas limit. This ensures block gas limit never drops below a critical threshold. |
+| **BOND_PROCESSING_DELAY** | `6` | The delay in processing bond instructions relative to the current proposal. A value of 1 signifies that the bond instructions of the immediate parent proposal will be processed. |
+| **INITIAL_BASE_FEE** | `0.025 gwei` (25,000,000 wei) | The initial base fee for the first Shasta block. |
+| **MIN_BASE_FEE** | `0.005 gwei` (5,000,000 wei) | The minimum base fee (inclusive) after Shasta fork. |
+| **MAX_BASE_FEE** | `1 gwei` (1,000,000,000 wei) | The maximum base fee (inclusive) after Shasta fork. |
+| **BLOCK_TIME_TARGET** | `2 seconds` | The block time target. |

packages/taiko-client-rs/crates/driver/src/derivation/pipeline/shasta/validation.rs

@@ -2,7 +2,7 @@ use alethia_reth_consensus::validation::ANCHOR_V3_GAS_LIMIT;
 use alloy_primitives::Address;
 use protocol::shasta::{
     constants::{
-        ANCHOR_MAX_OFFSET, ANCHOR_MIN_OFFSET, BLOCK_GAS_LIMIT_MAX_CHANGE, MIN_BLOCK_GAS_LIMIT,
+        MAX_ANCHOR_OFFSET, MIN_ANCHOR_OFFSET, BLOCK_GAS_LIMIT_MAX_CHANGE, MIN_BLOCK_GAS_LIMIT,
         TIMESTAMP_MAX_OFFSET,
     },
     manifest::DerivationSourceManifest,
@@ -118,13 +118,13 @@ fn adjust_anchor_numbers(
             block.anchor_block_number = parent_anchor;
         }
 
-        let future_reference_limit = origin_block_number.saturating_sub(ANCHOR_MIN_OFFSET);
+        let future_reference_limit = origin_block_number.saturating_sub(MIN_ANCHOR_OFFSET);
         if block.anchor_block_number >= future_reference_limit {
             block.anchor_block_number = parent_anchor;
         }
 
-        if origin_block_number > ANCHOR_MAX_OFFSET {
-            let min_allowed = origin_block_number - ANCHOR_MAX_OFFSET;
+        if origin_block_number > MAX_ANCHOR_OFFSET {
+            let min_allowed = origin_block_number - MAX_ANCHOR_OFFSET;
             if block.anchor_block_number < min_allowed {
                 block.anchor_block_number = parent_anchor;
             }

packages/taiko-client-rs/crates/proposer/src/transaction_builder.rs

@@ -16,7 +16,7 @@ use bindings::codec_optimized::{IInbox::ProposeInput, LibBlobs::BlobReference};
 use event_indexer::{indexer::ShastaEventIndexer, interface::ShastaProposeInputReader};
 use protocol::shasta::{
     BlobCoder,
-    constants::ANCHOR_MIN_OFFSET,
+    constants::MIN_ANCHOR_OFFSET,
     manifest::{BlockManifest, DerivationSourceManifest, ProposalManifest},
 };
 use rpc::client::ClientWithWallet;
@@ -67,10 +67,10 @@ impl ShastaProposalTransactionBuilder {
 
         // Ensure the current L1 head is sufficiently advanced.
         let current_l1_head = self.rpc_provider.l1_provider.get_block_number().await?;
-        if current_l1_head <= ANCHOR_MIN_OFFSET {
+        if current_l1_head <= MIN_ANCHOR_OFFSET {
             return Err(ProposerError::L1HeadTooLow {
                 current: current_l1_head,
-                minimum: ANCHOR_MIN_OFFSET,
+                minimum: MIN_ANCHOR_OFFSET,
             });
         }
 
@@ -83,7 +83,7 @@ impl ShastaProposalTransactionBuilder {
                     .unwrap_or_default()
                     .as_secs(),
                 coinbase: self.l2_suggested_fee_recipient,
-                anchor_block_number: current_l1_head - (ANCHOR_MIN_OFFSET + 1),
+                anchor_block_number: current_l1_head - (MIN_ANCHOR_OFFSET + 1),
                 gas_limit: 0, /* Use 0 for gas limit as it will be set as its parent's gas
                                * limit during derivation. */
                 transactions: txs.iter().map(|tx| tx.clone().into()).collect(),

packages/taiko-client-rs/crates/protocol/src/shasta/constants.rs

@@ -8,12 +8,12 @@ use alloy_eips::eip4844::{FIELD_ELEMENTS_PER_BLOB, USABLE_BITS_PER_FIELD_ELEMENT
 pub const PROPOSAL_MAX_BLOCKS: usize = 384;
 
 /// The maximum anchor block number offset from the proposal origin block number.
-/// NOTE: Should be same with `ANCHOR_MAX_OFFSET` in contracts/layer1/libs/LibManifest.sol.
-pub const ANCHOR_MAX_OFFSET: u64 = 128;
+/// NOTE: Should be same with `MAX_ANCHOR_OFFSET` in contracts/layer1/libs/LibManifest.sol.
+pub const MAX_ANCHOR_OFFSET: u64 = 128;
 
 /// The minimum anchor block number offset from the proposal origin block number.
-/// NOTE: Should be same with `ANCHOR_MIN_OFFSET` in contracts/layer1/libs/LibManifest.sol.
-pub const ANCHOR_MIN_OFFSET: u64 = 2;
+/// NOTE: Should be same with `MIN_ANCHOR_OFFSET` in contracts/layer1/libs/LibManifest.sol.
+pub const MIN_ANCHOR_OFFSET: u64 = 2;
 
 /// The maximum timestamp offset from the proposal origin timestamp.
 /// NOTE: Should be same with `TIMESTAMP_MAX_OFFSET` in

packages/taiko-client/bindings/manifest/manifest.go

@@ -15,9 +15,9 @@ const (
 	ProposalMaxBlocks = 384
 	// TimestampMaxOffset The maximum number timestamp offset from the proposal origin timestamp, refer to LibManifest.TIMESTAMP_MAX_OFFSET.
 	TimestampMaxOffset = 12 * 32
-	// AnchorMinOffset The minimum anchor block number offset from the proposal origin block number, refer to LibManifest.ANCHOR_MIN_OFFSET.
+	// AnchorMinOffset The minimum anchor block number offset from the proposal origin block number, refer to LibManifest.MIN_ANCHOR_OFFSET.
 	AnchorMinOffset = 2
-	// AnchorMaxOffset The maximum anchor block number offset from the proposal origin block number, refer to LibManifest.ANCHOR_MAX_OFFSET.
+	// AnchorMaxOffset The maximum anchor block number offset from the proposal origin block number, refer to LibManifest.MAX_ANCHOR_OFFSET.
 	AnchorMaxOffset = 128
 	// MaxBlockGasLimitChangePermyriad The maximum block gas limit change per block, in millionths (1/1,000,000), refer to LibManifest.MAX_BLOCK_GAS_LIMIT_CHANGE_PERMYRIAD.
 	MaxBlockGasLimitChangePermyriad = 10 // 0.1%

packages/taiko-client/driver/chain_syncer/event/manifest/shasta.go

@@ -378,7 +378,7 @@ func validateAnchorBlockNumber(
 			continue
 		}
 
-		// 2. Future reference: manifest.blocks[i].anchorBlockNumber >= proposal.originBlockNumber - ANCHOR_MIN_OFFSET
+		// 2. Future reference: manifest.blocks[i].anchorBlockNumber >= proposal.originBlockNumber - MIN_ANCHOR_OFFSET
 		if sourcePayload.BlockPayloads[i].AnchorBlockNumber >= originBlockNumber-manifest.AnchorMinOffset {
 			log.Info(
 				"Invalid anchor block number: future reference",
@@ -391,7 +391,7 @@ func validateAnchorBlockNumber(
 			continue
 		}
 
-		// 3. Excessive lag: manifest.blocks[i].anchorBlockNumber < proposal.originBlockNumber - ANCHOR_MAX_OFFSET
+		// 3. Excessive lag: manifest.blocks[i].anchorBlockNumber < proposal.originBlockNumber - MAX_ANCHOR_OFFSET
 		if originBlockNumber > manifest.AnchorMaxOffset &&
 			sourcePayload.BlockPayloads[i].AnchorBlockNumber < originBlockNumber-manifest.AnchorMaxOffset {
 			log.Info(