feat(docs-site): add taiko-protocol section with economics and codebase analysis (#18542)

Co-authored-by: RogerLamTd <[email protected]>
Co-authored-by: swarna1101 <[email protected]>

Author: 3 people

packages/docs-site/astro.config.ts

@@ -68,34 +68,38 @@ export default defineConfig({
           label: "Core Concepts",
           items: [
             { label: "What is Taiko?", link: "/core-concepts/what-is-taiko/" },
-            {
-              label: "Based sequencing",
-              link: "/core-concepts/based-sequencing/",
-            },
             {
               label: "Contestable rollups (BCR)",
-              link: "/core-concepts/contestable-rollups/",
+              link: "/core-concepts/contestable-rollup/",
             },
             {
               label: "Booster rollups (BBR)",
               link: "/core-concepts/booster-rollups/",
             },
             { label: "Multi-proofs", link: "/core-concepts/multi-proofs/" },
-            { label: "Block states", link: "/core-concepts/block-states" },
-            {
-              label: "Taiko nodes",
-              link: "/core-concepts/taiko-nodes/",
-            },
-            {
-              label: "Bridging",
-              link: "/core-concepts/bridging/",
-            },
             {
               label: "Inception layers",
               link: "/core-concepts/inception-layers/",
             },
           ],
         },
+        {
+          label: "Taiko Protocol",
+          items: [
+            {
+              label: "Codebase Analysis",
+              collapsed: true,
+              items: [
+                {label: "TaikoL1 Contract", link: "/taiko-protocol/codebase-analysis/taikol1-contract"},
+                {label: "TaikoL2 Contract", link: "/taiko-protocol/codebase-analysis/taikol2-contract"},
+              ],
+            },
+            { label: "Block states", link: "/taiko-protocol/block-states" },
+            { label: "Bridging", link: "/taiko-protocol/bridging" },
+            { label: "Economics", link: "/taiko-protocol/economics" },
+            { label: "Taiko nodes", link: "/taiko-protocol/taiko-nodes" },
+          ]
+        },
         {
           label: "Guides",
           items: [

packages/docs-site/src/assets/content/docs/taiko-protocol/based-economics.png

@@ -1,8 +1,8 @@
 ---
-title: Based sequencing
-description: Core concept page for "Based sequencing".
+title: Based rollup
+description: Core concept page for based rollups.
 ---
 
 One of Taiko's major differentiators from other rollups is that it is a **based rollup**. That is, it's sequencing is driven by the base L1. On Taiko, there is **no centralized sequencer**. The sequencer role instead falls on the shoulders of the Ethereum L1 validator.
 
-Check out plenty of great resources on based sequencing in our [Learning resources](/resources/learning-resources)!
+Check out plenty of great resources on **based sequencing** in our [Learning resources](/resources/learning-resources)!

packages/docs-site/src/assets/content/docs/core-concepts/bridging-dest-chain.webp renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-dest-chain.webp

@@ -17,4 +17,4 @@ Further, Ethereum-equivalence across L2s, L3s, and beyond means inheriting some
 
 ![Inception layers diagram](~/assets/content/docs/core-concepts/inception-layers-diagram.png)
 
-For more information on how Taiko's message passing works see the concept page on [Bridging](/core-concepts/bridging).
+For more information on how Taiko's message passing works see the concept page on [Bridging](/taiko-protocol/bridging).

packages/docs-site/src/assets/content/docs/core-concepts/bridging-source-chain.webp renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-source-chain.webp

@@ -29,15 +29,15 @@ For the visual learners here is a visualization of the three stages (proposed ->
 
 **Proposed:**
 
-![proposed](~/assets/content/docs/core-concepts/proposed.png)
+![proposed](~/assets/content/docs/taiko-protocol/proposed.png)
 
 **Proved:**
 
-![proved](~/assets/content/docs/core-concepts/proved.png)
+![proved](~/assets/content/docs/taiko-protocol/proved.png)
 
 **Verified:**
 
-![verified](~/assets/content/docs/core-concepts/verified.png)
+![verified](~/assets/content/docs/taiko-protocol/verified.png)
 
 ## Off chain prover market (PBS style)
 

packages/docs-site/src/assets/content/docs/core-concepts/proposed.png renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/proposed.png

@@ -5,9 +5,9 @@ description: Core concept page for "What is Taiko?".
 
 Ethereum is too expensive. We believe in Ethereum's core properties (e.g., censorship-resistant, permissionless, secure). We also believe that rollups should **extend** (not augment) these properties.
 
-Taiko is a [based rollup](/core-concepts/based-sequencing) which makes Ethereum cheaper while maintaining its properties:
+Taiko is a [based rollup](/core-concepts/based-rollup) which makes Ethereum cheaper while maintaining its properties:
 
-- [Based contestable rollup](/core-concepts/contestable-rollups): A configurable rollup to reduce transaction fees on Ethereum.
+- [Based contestable rollup](/core-concepts/contestable-rollup): A configurable rollup to reduce transaction fees on Ethereum.
 - [Based booster rollup](/core-concepts/booster-rollups): An innovative approach to **native L1 scaling**.
 
 Taiko is a **highly configurable, fully open source, permissionless (based), Ethereum-equivalent rollup**.
@@ -32,7 +32,7 @@ It can be easily configured as a fully ZK rollup, optimistic rollup, or anything
 ### Non-critical infrastructure
 
 :::note
-Anyone can run these components, not just Taiko Labs. Yes you can sequence blocks on Taiko, host your own bridge using our [signal service](/core-concepts/bridging#the-signal-service), etc.
+Anyone can run these components, not just Taiko Labs. Yes you can sequence blocks on Taiko, host your own bridge using our [signal service](/taiko-protocol/bridging#the-signal-service), etc.
 :::
 
 #### Frontends

packages/docs-site/src/assets/content/docs/core-concepts/proved.png renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/proved.png

@@ -80,8 +80,8 @@ The bridge is a set of smart contracts and a frontend web app that allow you to
 
 First, here is a flowchart of how our bridge dapp implementation works, which uses the signal service:
 
-![bridging send message flowchart](~/assets/content/docs/core-concepts/bridging-source-chain.webp) \
-![bridging process message flowchart](~/assets/content/docs/core-concepts/bridging-dest-chain.webp)
+![bridging send message flowchart](~/assets/content/docs/taiko-protocol/bridging-source-chain.webp)
+![bridging process message flowchart](~/assets/content/docs/taiko-protocol/bridging-dest-chain.webp)
 
 ### How does Ether bridging work?
 

packages/docs-site/src/assets/content/docs/core-concepts/taiko-nodes.png renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/taiko-nodes.png

@@ -0,0 +1,150 @@
+---
+title: TaikoL1
+description: Taiko protocol page for "TaikoL1.sol".
+---
+
+[TaikoL1](https://github.com/taikoxyz/taiko-mono/blob/main/packages/protocol/contracts/layer1/based/TaikoL1.sol) is a smart contract that serves as the **base layer** of the Taiko protocol. It provides functionalities for **proposing, proving, and verifying blocks**, enabling the rollup's consensus and state transitions. The contract also supports **bond deposits and withdrawals** and manages state synchronization between L1 and L2.
+
+---
+
+## Core Purpose
+
+1. **Block Lifecycle Management**
+   Manages the proposal, proof, and verification of Taiko blocks, ensuring consistent state transitions.
+
+2. **Cross-Layer Synchronization**
+   Ensures the synchronization of states between Layer 1 (L1) and Layer 2 (L2).
+
+3. **Bond Management**
+   Handles the deposit and withdrawal of bonds to incentivize proposers and ensure accountability.
+
+4. **Base Layer Scalability**
+   Enables the deployment on L2 to create L3 rollups, expanding Taiko's scalability.
+
+---
+
+## Key Functions
+
+### `proposeBlockV2`
+
+- **Purpose:**
+  Proposes a single block for inclusion in the rollup.
+
+- **Parameters:**
+
+  - `_params`: Encoded block parameters.
+  - `_txList`: Transactions to include in the block.
+
+- **Returns:**
+  `TaikoData.BlockMetadataV2` containing metadata of the proposed block.
+
+---
+
+### `proposeBlocksV2`
+
+- **Purpose:**
+  Proposes multiple blocks in batch.
+
+- **Parameters:**
+
+  - `_paramsArr`: Array of encoded block parameters.
+  - `_txListArr`: Arrays of transactions for each block.
+
+- **Returns:**
+  Array of `TaikoData.BlockMetadataV2` for all proposed blocks.
+
+---
+
+### `proveBlock`
+
+- **Purpose:**
+  Proves the validity of a single block.
+
+- **Parameters:**
+  - `_blockId`: ID of the block to be proven.
+  - `_input`: Encoded proof data.
+
+---
+
+### `proveBlocks`
+
+- **Purpose:**
+  Proves multiple blocks in a single call.
+
+- **Parameters:**
+  - `_blockIds`: IDs of the blocks to be proven.
+  - `_inputs`: Proofs for each block.
+  - `_batchProof`: Batch proof covering all blocks.
+
+---
+
+### `verifyBlocks`
+
+- **Purpose:**
+  Verifies a batch of blocks after proofs are submitted.
+
+- **Parameters:**
+  - `_maxBlocksToVerify`: Maximum number of blocks to verify.
+
+---
+
+### `depositBond`
+
+- **Purpose:**
+  Deposits a bond required for proposing blocks.
+
+- **Parameters:**
+  - `_amount`: Amount of bond to deposit.
+
+---
+
+### `withdrawBond`
+
+- **Purpose:**
+  Withdraws bond deposits after successful proposals.
+
+- **Parameters:**
+  - `_amount`: Amount of bond to withdraw.
+
+---
+
+### `getLastVerifiedBlock`
+
+- **Purpose:**
+  Retrieves the details of the most recently verified block.
+
+- **Returns:**
+  - `blockId_`: ID of the last verified block.
+  - `blockHash_`: Block hash of the verified block.
+  - `stateRoot_`: State root of the verified block.
+  - `verifiedAt_`: Timestamp when the block was verified.
+
+---
+
+## Key Events
+
+1. **`DebugGasPerBlock`**
+   Provides gas usage metrics for block proposals or proofs.
+
+- `isProposeBlock`: Indicates whether the event is for proposals or proofs.
+- `gasUsed`: Gas consumed per block.
+- `batchSize`: Number of blocks in the batch.
+
+2. **`StateVariablesUpdated`**
+   Signals updates to the state variables.
+
+---
+
+## Important Data Structures
+
+1. **`state`**:
+   Tracks the rollup state, including blocks, bonds, and configurations.
+
+2. **`__gap`**:
+   Reserved storage for future upgrades.
+
+---
+
+## Design Highlights
+
+---

packages/docs-site/src/assets/content/docs/core-concepts/verified.png renamed to packages/docs-site/src/assets/content/docs/taiko-protocol/verified.png

@@ -0,0 +1,115 @@
+---
+title: TaikoL2
+description: Taiko protocol page for "TaikoL2.sol".
+---
+
+[TaikoL2](https://github.com/taikoxyz/taiko-mono/blob/main/packages/protocol/contracts/layer2/based/TaikoL2.sol) is a smart contract that handles cross-layer message verification and manages EIP-1559 gas pricing for Taiko operations. It is used to anchor the latest L1 block details to L2 for cross-layer communication, manage EIP-1559 parameters for gas pricing, and store verified L1 block information.
+
+---
+
+## Core Purpose
+
+1. **Anchor:**
+   Due to Taiko's **based rollup** nature, each L2 block requires anchoring to the latest L1 block details. The first transaction of every block must perform this anchor, or all calls will revert with `L2_PUBLIC_INPUT_HASH_MISMATCH`.
+
+2. **Gas Pricing:**
+   The contract calculates **EIP-1559 base fee** and updates gas parameters dynamically for optimal gas pricing using key inputs such as `_parentGasUsed` and `_baseFeeConfig`.
+
+3. **State Synchronization:**
+   The contract ensures L2 remains in sync with L1 by storing verified block information and updating state data like block hashes and timestamps.
+
+4. **Bridging Support:**
+   It plays a crucial role in **L1-L2 bridging**, anchoring state roots to enable secure and efficient communication between layers. For more, visit the [Bridging page](/taiko-protocol/bridging).
+
+---
+
+## Key Functions
+
+### `anchorV2`
+
+- **Purpose:**
+  Anchors the latest L1 block details to L2, enabling **cross-layer message verification**.
+
+- **Parameters:**
+
+  - `_anchorBlockId`: The L1 block ID to anchor.
+  - `_anchorStateRoot`: State root of the specified L1 block.
+  - `_parentGasUsed`: Gas usage in the parent block.
+  - `_baseFeeConfig`: Configuration for base fee calculation.
+
+- **Mechanism:**
+  Verifies and updates the `publicInputHash`, calculates the base fee and gas excess using `getBasefeeV2`, and synchronizes chain data.
+
+---
+
+### `getBasefeeV2`
+
+- **Purpose:**
+  Computes the **EIP-1559 base fee** and updates gas parameters like **gas excess** and **gas target**.
+
+- **Parameters:**
+
+  - `_parentGasUsed`: Gas used in the parent block.
+  - `_baseFeeConfig`: Configuration for EIP-1559 calculations.
+
+- **Returns:**
+
+  - `basefee_`: Calculated base fee per gas.
+  - `newGasTarget_`: Updated gas target.
+  - `newGasExcess_`: Updated gas excess.
+
+- **Technical Details:**
+  Uses `LibEIP1559.calc1559BaseFee` and `LibEIP1559.adjustExcess` for precise gas pricing dynamics.
+
+---
+
+### `getBlockHash`
+
+- **Purpose:**
+  Fetches the block hash for a specified block ID.
+
+- **Technical Note:**
+  If the block ID is too old (not in the last 256 blocks), it uses an internal mapping (`_blockhashes`) to retrieve stored hashes.
+
+---
+
+## Key Events
+
+1. **`Anchored`**
+   Emitted when L1 block details are successfully anchored to L2.
+
+   **Parameters:**
+
+   - `parentHash`: Hash of the parent block.
+   - `parentGasExcess`: Gas excess for base fee calculation.
+
+2. **`EIP1559Update`**
+   Emitted when gas parameters (e.g., target, excess, base fee) are updated.
+
+   **Parameters:**
+
+   - `oldGasTarget`: Previous gas target.
+   - `newGasTarget`: Updated gas target.
+   - `oldGasExcess`: Previous gas excess.
+   - `newGasExcess`: Updated gas excess.
+   - `basefee`: Calculated base fee.
+
+---
+
+## Important Data Structures
+
+### State Variables
+
+1. **`publicInputHash`**:
+   Validates the integrity of public inputs for block verification.
+
+2. **`parentGasExcess`**:
+   Tracks gas usage exceeding the target for dynamic base fee adjustment.
+
+3. **`lastSyncedBlock`**:
+   Stores the ID of the most recent L1 block synced with L2.
+
+4. **`l1ChainId`**:
+   Chain ID of the base layer (L1).
+
+---