diff --git a/packages/docs-site/astro.config.ts b/packages/docs-site/astro.config.ts index 5f7c4d44faf..71087619c0d 100644 --- a/packages/docs-site/astro.config.ts +++ b/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: [ diff --git a/packages/docs-site/src/assets/content/docs/taiko-protocol/based-economics.png b/packages/docs-site/src/assets/content/docs/taiko-protocol/based-economics.png new file mode 100644 index 00000000000..e714579a595 Binary files /dev/null and b/packages/docs-site/src/assets/content/docs/taiko-protocol/based-economics.png differ diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/bridging-dest-chain.webp b/packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-dest-chain.webp similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/bridging-dest-chain.webp rename to packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-dest-chain.webp diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/bridging-source-chain.webp b/packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-source-chain.webp similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/bridging-source-chain.webp rename to packages/docs-site/src/assets/content/docs/taiko-protocol/bridging-source-chain.webp diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/proposed.png b/packages/docs-site/src/assets/content/docs/taiko-protocol/proposed.png similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/proposed.png rename to packages/docs-site/src/assets/content/docs/taiko-protocol/proposed.png diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/proved.png b/packages/docs-site/src/assets/content/docs/taiko-protocol/proved.png similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/proved.png rename to packages/docs-site/src/assets/content/docs/taiko-protocol/proved.png diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/taiko-nodes.png b/packages/docs-site/src/assets/content/docs/taiko-protocol/taiko-nodes.png similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/taiko-nodes.png rename to packages/docs-site/src/assets/content/docs/taiko-protocol/taiko-nodes.png diff --git a/packages/docs-site/src/assets/content/docs/core-concepts/verified.png b/packages/docs-site/src/assets/content/docs/taiko-protocol/verified.png similarity index 100% rename from packages/docs-site/src/assets/content/docs/core-concepts/verified.png rename to packages/docs-site/src/assets/content/docs/taiko-protocol/verified.png diff --git a/packages/docs-site/src/content/docs/core-concepts/based-sequencing.md b/packages/docs-site/src/content/docs/core-concepts/based-rollup.md similarity index 58% rename from packages/docs-site/src/content/docs/core-concepts/based-sequencing.md rename to packages/docs-site/src/content/docs/core-concepts/based-rollup.md index b431f95bc77..acf2b80380f 100644 --- a/packages/docs-site/src/content/docs/core-concepts/based-sequencing.md +++ b/packages/docs-site/src/content/docs/core-concepts/based-rollup.md @@ -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)! diff --git a/packages/docs-site/src/content/docs/core-concepts/contestable-rollups.md b/packages/docs-site/src/content/docs/core-concepts/contestable-rollup.md similarity index 100% rename from packages/docs-site/src/content/docs/core-concepts/contestable-rollups.md rename to packages/docs-site/src/content/docs/core-concepts/contestable-rollup.md diff --git a/packages/docs-site/src/content/docs/core-concepts/inception-layers.md b/packages/docs-site/src/content/docs/core-concepts/inception-layers.md index 4b7b3d99fbf..ebcc602c304 100644 --- a/packages/docs-site/src/content/docs/core-concepts/inception-layers.md +++ b/packages/docs-site/src/content/docs/core-concepts/inception-layers.md @@ -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). diff --git a/packages/docs-site/src/content/docs/core-concepts/multi-proofs.md b/packages/docs-site/src/content/docs/core-concepts/multi-proofs.md index 90e8bf3a077..84be7328275 100644 --- a/packages/docs-site/src/content/docs/core-concepts/multi-proofs.md +++ b/packages/docs-site/src/content/docs/core-concepts/multi-proofs.md @@ -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) diff --git a/packages/docs-site/src/content/docs/core-concepts/what-is-taiko.md b/packages/docs-site/src/content/docs/core-concepts/what-is-taiko.md index 2380604a9c6..41ca6aa6ddd 100644 --- a/packages/docs-site/src/content/docs/core-concepts/what-is-taiko.md +++ b/packages/docs-site/src/content/docs/core-concepts/what-is-taiko.md @@ -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 diff --git a/packages/docs-site/src/content/docs/core-concepts/block-states.mdx b/packages/docs-site/src/content/docs/taiko-protocol/block-states.mdx similarity index 100% rename from packages/docs-site/src/content/docs/core-concepts/block-states.mdx rename to packages/docs-site/src/content/docs/taiko-protocol/block-states.mdx diff --git a/packages/docs-site/src/content/docs/core-concepts/bridging.md b/packages/docs-site/src/content/docs/taiko-protocol/bridging.md similarity index 98% rename from packages/docs-site/src/content/docs/core-concepts/bridging.md rename to packages/docs-site/src/content/docs/taiko-protocol/bridging.md index d5bc0333a82..fe5926a6d67 100644 --- a/packages/docs-site/src/content/docs/core-concepts/bridging.md +++ b/packages/docs-site/src/content/docs/taiko-protocol/bridging.md @@ -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? diff --git a/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol1-contract.md b/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol1-contract.md new file mode 100644 index 00000000000..6045c4c8114 --- /dev/null +++ b/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol1-contract.md @@ -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 + +--- diff --git a/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol2-contract.md b/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol2-contract.md new file mode 100644 index 00000000000..be5cc5e5962 --- /dev/null +++ b/packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol2-contract.md @@ -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). + +--- diff --git a/packages/docs-site/src/content/docs/taiko-protocol/economics.md b/packages/docs-site/src/content/docs/taiko-protocol/economics.md new file mode 100644 index 00000000000..6f9187386c9 --- /dev/null +++ b/packages/docs-site/src/content/docs/taiko-protocol/economics.md @@ -0,0 +1,15 @@ +--- +title: Economics +description: Core concept page for "Economics". +--- + + +## taiko-economics + +Thanks to its based and multi-proof structure, Taiko has a unique economic cycle. + +This diagram illustrates Taiko's fee distribution mechanism. When users submit transactions on Taiko L2, they pay fees that are split into two components: a priority tip and a base fee. The priority tip goes to the L2 block proposer, who builds and proposes new blocks. The base fee is split between Taiko DAO Treasury (25%) and the L2 block proposer (75%). L2 block proposers have to pay two fees: L1 fee to the TaikoL1 contract on Ethereum to call `proposeBlock` function and a prover fee to the block prover. Block provers incur proof generation costs while proving the correctness of proposed blocks. + +For the current amount of the validity/contest bond on mainnet, please see [network configuration](/network-reference/network-configuration) page. + +![Economics](~/assets/content/docs/taiko-protocol/based-economics.png) diff --git a/packages/docs-site/src/content/docs/core-concepts/taiko-nodes.md b/packages/docs-site/src/content/docs/taiko-protocol/taiko-nodes.md similarity index 98% rename from packages/docs-site/src/content/docs/core-concepts/taiko-nodes.md rename to packages/docs-site/src/content/docs/taiko-protocol/taiko-nodes.md index 84a8d11589a..1db1eb3b197 100644 --- a/packages/docs-site/src/content/docs/core-concepts/taiko-nodes.md +++ b/packages/docs-site/src/content/docs/taiko-protocol/taiko-nodes.md @@ -10,7 +10,7 @@ Taiko nodes are minimally modified Ethereum [execution clients](https://ethereum You can think of it like an Ethereum mainnet node, except replacing the consensus client with `taiko-client`. `taiko-client` then drives `taiko-geth` over the [Engine API](https://github.com/ethereum/execution-apis/tree/main/src/engine). This is a modular design that allows easily plugging in other execution clients. -![Taiko nodes diagram](~/assets/content/docs/core-concepts/taiko-nodes.png) +![Taiko nodes diagram](~/assets/content/docs/taiko-protocol/taiko-nodes.png) ## taiko-geth