From 9c8527903a69f1dbe0e0b75873e62bd9190c54ce Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Fri, 28 Aug 2026 17:24:00 -0400 Subject: [PATCH 1/2] docs: rename Protocol Overview to Base Protocol, merge into single page Combine specs/overview.mdx (design goals, lineage) and specs/protocol/overview.mdx (architecture, diagrams, user flows) into a single Base Protocol page. Promote Flashblocks from single-page group to top-level sidebar item. Co-Authored-By: Claude Opus 4.6 --- docs/.mintignore | 1 + docs/base-chain/overview.mdx | 4 +- docs/base-chain/specs/overview.mdx | 342 ++++++++++++++++++++++++++++- docs/docs.json | 19 +- docs/ia-guidelines.md | 4 +- 5 files changed, 351 insertions(+), 19 deletions(-) diff --git a/docs/.mintignore b/docs/.mintignore index 9844e52b4..11b358962 100644 --- a/docs/.mintignore +++ b/docs/.mintignore @@ -8,3 +8,4 @@ tone_of_voice.mdx base-chain/network-information/bridging-and-withdrawals.mdx base-chain/network-information/network-faucets.mdx base-chain/quickstart/connecting-to-base.mdx +base-chain/specs/protocol/overview.mdx diff --git a/docs/base-chain/overview.mdx b/docs/base-chain/overview.mdx index 08408eb1c..84b12a530 100644 --- a/docs/base-chain/overview.mdx +++ b/docs/base-chain/overview.mdx @@ -21,8 +21,8 @@ Technical specifications for how Base works at the chain level, organized by top Sub-second block building, WebSocket data, and RPC usage. - - Rollup architecture, core components, and user flows. + + Design goals, rollup architecture, and core user flows. Posting L2 sequencer data to L1 for data availability. diff --git a/docs/base-chain/specs/overview.mdx b/docs/base-chain/specs/overview.mdx index 6d4b55f61..c96ddc49a 100644 --- a/docs/base-chain/specs/overview.mdx +++ b/docs/base-chain/specs/overview.mdx @@ -1,6 +1,6 @@ --- -title: "Overview" -description: "Technical specification of the Base Chain protocol, covering block derivation, execution, transaction propagation, and state verification." +title: "Base Protocol" +description: "Design goals, rollup architecture, core components, and user flows for the Base Chain protocol." --- This specification defines the Base Chain protocol: how nodes derive and execute blocks, how @@ -25,3 +25,341 @@ Our aim is to design a protocol specification that is: Base Chain inherits Ethereum's EVM semantics, transaction rules, and L1-anchored security. It was originally built on the [OP Stack](https://specs.optimism.io). After the Jovian Hardfork, Base Chain follows this specification. + +## Network Participants + +There are three primary actors that interact with Base: users, sequencers, and validators. + +```mermaid +graph TD + EthereumL1(Ethereum L1) + + subgraph "L2 Participants" + Users(Users) + Sequencers(Sequencers) + Validators(Validators) + end + + Validators -.->|fetch transaction batches| EthereumL1 + Validators -.->|fetch deposit data| EthereumL1 + Validators -->|submit/validate/challenge output proposals| EthereumL1 + Validators -.->|fetch realtime P2P updates| Sequencers + + Users -->|submit deposits/withdrawals| EthereumL1 + Users -->|submit transactions| Sequencers + Users -->|query data| Validators + + Sequencers -->|submit transaction batches| EthereumL1 + Sequencers -.->|fetch deposit data| EthereumL1 + + classDef l1Contracts stroke:#bbf,stroke-width:2px; + classDef l2Components stroke:#333,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + + class EthereumL1 l1Contracts; + class Users,Sequencers,Validators l2Components; +``` + +### Users + +Users are the general class of network participants who: + +- Submit transactions through the sequencer or by interacting with contracts on Ethereum. +- Query transaction data from interfaces operated by validators. + +### Sequencers + +The sequencer fills the role of block producer on Base. Base currently operates with a single active sequencer. + +The Sequencer: + +- Accepts transactions directly from Users. +- Observes "deposit" transactions generated on Ethereum. +- Consolidates both transaction streams into ordered L2 blocks. +- Submits information to L1 that is sufficient to fully reproduce those L2 blocks. +- Provides real-time access to pending L2 blocks that have not yet been confirmed on L1. +- Produces Flashblocks every 200ms, committing to the ordering of transactions within the block as it is being built. + +The Sequencer serves an important role for the operation of an L2 chain but is not a trusted actor. The Sequencer is generally +responsible for improving the user experience by ordering transactions much more quickly and cheaply than would currently +be possible if users were to submit all transactions directly to L1. + +### Validators + +Validators execute the L2 state transition function independently of the Sequencer. Validators help to maintain +the integrity of the network and serve blockchain data to Users. + +Validators generally: + +- Sync rollup data from L1 and the Sequencer. +- Use rollup data to execute the L2 state transition function. +- Serve rollup data and computed L2 state information to Users. + +Validators can also act as Proposers and/or Challengers who: + +- Submit assertions about the state of the L2 to a smart contract on L1. +- Validate assertions made by other participants. +- Dispute invalid assertions made by other participants. + +## High-Level System Diagram + +The following diagram shows how the major protocol components interact across L1 and L2. + +```mermaid +graph LR + subgraph "Ethereum L1" + OptimismPortal(OptimismPortal) + BatchInbox(Batch Inbox Address) + DisputeGameFactory(DisputeGameFactory) + end + + subgraph "L2 Node" + RollupNode(Consensus) + ExecutionEngine(Execution Engine) + end + + Batcher(Batcher) + Proposers(Proposers) + Challengers(Challengers) + Users(Users) + + Users -->|deposits / withdrawals| OptimismPortal + Users -->|transactions| ExecutionEngine + + Batcher -->|post transaction batches| BatchInbox + Batcher -.->|fetch batch data| RollupNode + + RollupNode -.->|fetch batches| BatchInbox + RollupNode -.->|fetch deposit events| OptimismPortal + RollupNode -->|Engine API| ExecutionEngine + + Proposers -->|submit output proposals| DisputeGameFactory + Proposers -.->|fetch outputs| RollupNode + Challengers -->|verify / challenge games| DisputeGameFactory + OptimismPortal -.->|query state proposals| DisputeGameFactory + + classDef l1Contracts stroke:#bbf,stroke-width:2px; + classDef l2Components stroke:#333,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + + class OptimismPortal,BatchInbox,DisputeGameFactory l1Contracts; + class RollupNode,ExecutionEngine l2Components; + class Batcher,Proposers,Challengers,Users systemUser; +``` + +## Protocol Components + +### Consensus + +Consensus is responsible for deriving the canonical L2 chain from L1 data. It reads transaction batches +from the Batch Inbox and deposit events from OptimismPortal, constructs payload attributes, and drives the +execution engine via the Engine API. Unsafe (unconfirmed) blocks are gossiped to other nodes over a dedicated +P2P network to give validators low-latency access before batches land on L1. + +[Consensus →](./protocol/consensus/) + +```mermaid +graph LR + L1(Ethereum L1) + subgraph "Rollup Node" + BatchDecoding(Batch Decoding) + Derivation(Derivation Pipeline) + end + EngineAPI(Engine API) + EE(Execution Engine) + L2(L2 Blocks) + + L1 -->|batches + deposit events| BatchDecoding + BatchDecoding --> Derivation + Derivation -->|payload attributes| EngineAPI + EngineAPI --> EE + EE --> L2 + + classDef l1 stroke:#bbf,stroke-width:2px; + classDef l2 stroke:#333,stroke-width:2px; + class L1 l1; + class EE,L2 l2; +``` + +### Execution + +The execution engine is a Reth-based runtime. It exposes the standard Ethereum JSON-RPC API and +processes blocks produced by consensus. Predeploys (system contracts at fixed L2 addresses), precompiles, +and preinstalls extend the EVM for rollup-specific functionality such as fee distribution, L1 block attribute +injection, and cross-domain messaging. + +[Execution →](./protocol/execution/) + +### Bridging + +Deposits flow from the `OptimismPortal` contract on L1 into L2 as special deposit transactions included at the +start of each L2 block. Withdrawals flow in the opposite direction: a withdrawal transaction is initiated on L2, +a proposer submits an output root to `DisputeGameFactory`, and after the challenge period the user proves and +finalizes the withdrawal on L1 via `OptimismPortal`. + +[Bridging →](./protocol/bridging/deposits) + +```mermaid +graph LR + subgraph "Deposit Path" + User1(User) + OP1(OptimismPortal) + DepTx(Deposit Transaction on L2) + end + + subgraph "Withdrawal Path" + User2(User) + WdTx(Withdrawal Tx on L2) + DGF(DisputeGameFactory) + OP2(OptimismPortal) + end + + User1 -->|depositTransaction| OP1 + OP1 -->|TransactionDeposited event| DepTx + + User2 -->|initiates withdrawal| WdTx + WdTx -->|output root proposed| DGF + User2 -->|prove + finalize| OP2 + OP2 -.->|verify game| DGF + + classDef l1 stroke:#bbf,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + class OP1,OP2,DGF l1; + class User1,User2 systemUser; +``` + +### Batcher + +The batcher is a service run by the sequencer that compresses L2 transaction data into channel frames and posts +them as calldata (or blobs) to the Batch Inbox Address on L1. This is the data availability layer that allows +any validator to independently reconstruct the L2 chain from L1. + +[Batcher →](./protocol/batcher) + +```mermaid +graph LR + Sequencer(Sequencer) + Batcher(Batcher) + BatchInbox(Batch Inbox Address) + RollupNode(Rollup Node) + + Sequencer -->|L2 blocks| Batcher + Batcher -->|compressed channel frames| BatchInbox + BatchInbox -.->|fetch batches| RollupNode + + classDef l1 stroke:#bbf,stroke-width:2px; + classDef l2 stroke:#333,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + class BatchInbox l1; + class RollupNode l2; + class Batcher,Sequencer systemUser; +``` + +### Proofs + +Output proposals and proofs allow verification of the L2 state. Proposers create checkpoint games +through `DisputeGameFactory`, proof material is checked by the onchain verifier contracts, and +challengers can dispute invalid claims. Valid withdrawals can only be finalized through +`OptimismPortal` once the associated game resolves in favor of the proposer. + +[Proofs →](./protocol/proofs/) + +```mermaid +graph LR + Proposer(Proposer) + DGF(DisputeGameFactory) + Game(AggregateVerifier game) + Challengers(Challengers) + OP(OptimismPortal) + + Proposer -->|submit checkpoint proof| DGF + DGF -->|create game| Game + Challengers -->|challenge invalid claims| Game + Game -->|resolved result| OP + + classDef l1 stroke:#bbf,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + class DGF,Game,OP l1; + class Proposer,Challengers systemUser; +``` + +## Core User Flows + +### Depositing ETH to Base + +Users will often begin their L2 journey by depositing ETH from L1. +Once they have ETH to pay fees, they'll start sending transactions on L2. +The following diagram demonstrates this interaction and key Base protocol components. + +```mermaid +graph TD + subgraph "Ethereum L1" + OptimismPortal(OptimismPortal) + BatchInbox(Batch Inbox Address) + end + + Sequencer(Sequencer) + Users(Users) + + %% Interactions + Users -->|1. submit deposit| OptimismPortal + Sequencer -.->|2. fetch deposit events| OptimismPortal + Sequencer -->|3. generate deposit block| Sequencer + Users -->|4. send transactions| Sequencer + Sequencer -->|5. submit transaction batches| BatchInbox + + classDef l1Contracts stroke:#bbf,stroke-width:2px; + classDef l2Components stroke:#333,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + + class OptimismPortal,BatchInbox l1Contracts; + class Sequencer l2Components; + class Users systemUser; +``` + +### Sending Transactions on Base + +Sending transactions on Base works the same as on Ethereum. Users sign transactions and submit them via +`eth_sendRawTransaction` to any node's JSON-RPC endpoint. The sequencer picks them up from its mempool, +orders them into L2 blocks, and eventually posts the batch to L1. + +### Withdrawing from Base + +Users may also want to withdraw ETH or ERC20 tokens from Base back to Ethereum. Withdrawals are initiated +as standard transactions on L2 but are then completed using transactions on L1. Withdrawals must reference a valid +proof game contract that proposes the state of the L2 at a given point in time. + +```mermaid +graph LR + subgraph "Ethereum L1" + BatchInbox(Batch Inbox Address) + DisputeGameFactory(DisputeGameFactory) + ProofGame(AggregateVerifier game) + OptimismPortal(OptimismPortal) + ExternalContracts(External Contracts) + end + + Sequencer(Sequencer) + Proposers(Proposers) + Users(Users) + + %% Interactions + Users -->|1. send withdrawal initialization txn| Sequencer + Sequencer -->|2. submit transaction batch| BatchInbox + Proposers -->|3. submit output proposal| DisputeGameFactory + DisputeGameFactory -->|4. generate game| ProofGame + Users -->|5. submit withdrawal proof| OptimismPortal + Users -->|6. wait for finalization| ProofGame + Users -->|7. submit withdrawal finalization| OptimismPortal + OptimismPortal -->|8. check game validity| ProofGame + OptimismPortal -->|9. execute withdrawal transaction| ExternalContracts + + %% Styling + classDef l1Contracts stroke:#bbf,stroke-width:2px; + classDef l2Components stroke:#333,stroke-width:2px; + classDef systemUser stroke:#f9a,stroke-width:2px; + + class BatchInbox,DisputeGameFactory,ProofGame,OptimismPortal l1Contracts; + class Sequencer l2Components; + class Users,Proposers systemUser; +``` diff --git a/docs/docs.json b/docs/docs.json index a56be27df..9fa30a1b9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -176,6 +176,7 @@ "group": "Specifications", "pages": [ "base-chain/overview", + "base-chain/specs/overview", { "group": "B20", "pages": [ @@ -225,19 +226,7 @@ "base-chain/network-information/troubleshooting-transactions" ] }, - { - "group": "Flashblocks", - "pages": [ - "base-chain/flashblocks/faq" - ] - }, - { - "group": "Protocol Overview", - "pages": [ - "base-chain/specs/overview", - "base-chain/specs/protocol/overview" - ] - }, + "base-chain/flashblocks/faq", { "group": "Batcher", "pages": [ @@ -876,6 +865,10 @@ "source": "/base-chain/quickstart/connecting-to-base", "destination": "/get-started/connect-to-base" }, + { + "source": "/base-chain/specs/protocol/overview", + "destination": "/base-chain/specs/overview" + }, { "source": "/base-account", "destination": "/sdks/base-account/overview" diff --git a/docs/ia-guidelines.md b/docs/ia-guidelines.md index 86baf11ee..b6b64c5c0 100644 --- a/docs/ia-guidelines.md +++ b/docs/ia-guidelines.md @@ -111,9 +111,9 @@ Content is organized by topic, not by abstraction level. Each topic group flows - **Belongs**: Flashblocks reference — key concepts, architecture, and FAQ about block building, WebSocket data, RPC usage, and node setup. - **Does not belong**: Flashblocks API methods (SDKs & APIs → Base Chain API). Transaction ordering details (Transactions). -### Protocol Overview +### Base Protocol -- **Belongs**: Design philosophy and lineage (specs/overview), and the detailed protocol architecture with component diagrams and user flow walkthroughs (specs/protocol/overview). +- **Belongs**: Design goals, lineage, network participants, system architecture diagrams, protocol component summaries, and core user flows (deposits, transactions, withdrawals). Listed as a top-level page, not a dropdown group. - **Does not belong**: Per-component specs (those go in their respective topic groups: Consensus, Execution, Proofs, etc.). ### Batcher From 72f808b244b27353039756aefb31f8836abd0e12 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Fri, 28 Aug 2026 17:35:56 -0400 Subject: [PATCH 2/2] docs: nest protocol specs under Base Protocol group, split design goals Move Consensus, Execution, Bridging, Batcher, and Proofs under a Base Protocol dropdown group. Split the merged overview into a protocol overview page and a separate Design Goals page. Update IA guidelines to reflect new structure. Co-Authored-By: Claude Opus 4.6 --- docs/base-chain/specs/design-goals.mdx | 23 ++++++ docs/base-chain/specs/overview.mdx | 29 ++------ docs/docs.json | 97 +++++++++++++------------- docs/ia-guidelines.md | 46 ++++-------- 4 files changed, 92 insertions(+), 103 deletions(-) create mode 100644 docs/base-chain/specs/design-goals.mdx diff --git a/docs/base-chain/specs/design-goals.mdx b/docs/base-chain/specs/design-goals.mdx new file mode 100644 index 000000000..99e86ddcf --- /dev/null +++ b/docs/base-chain/specs/design-goals.mdx @@ -0,0 +1,23 @@ +--- +title: "Design Goals" +description: "Design philosophy and lineage of the Base Chain protocol specification." +--- + +## Design Goals + +Our aim is to design a protocol specification that is: + +- **Opinionated:** Simplicity through deliberate design choices. We identify the best solution and + commit to it. +- **Maximally Simple:** By focusing on just what Base needs, we radically simplify the stack. The + protocol spec and codebase should be understandable by a single developer. +- **Fast Cycles:** We ship upgrades frequently rather than batching risk into infrequent large ones. + We target six smaller, tightly scoped hard forks per year on a regular cadence, with fortnightly + releases. +- **Ethereum Aligned:** Base wins when Ethereum wins. We accelerate deployment of high-impact + changes ahead of L1 to provide data that informs the Ethereum roadmap. + +## Lineage + +Base Chain inherits Ethereum's EVM semantics, transaction rules, and L1-anchored security. It was +originally built on the [OP Stack](https://specs.optimism.io). After the Jovian Hardfork, Base Chain follows this specification. diff --git a/docs/base-chain/specs/overview.mdx b/docs/base-chain/specs/overview.mdx index c96ddc49a..35579e157 100644 --- a/docs/base-chain/specs/overview.mdx +++ b/docs/base-chain/specs/overview.mdx @@ -1,30 +1,11 @@ --- -title: "Base Protocol" -description: "Design goals, rollup architecture, core components, and user flows for the Base Chain protocol." +title: "Overview" +description: "High-level overview of the Base Chain protocol — network participants, system architecture, core components, and user flows." --- -This specification defines the Base Chain protocol: how nodes derive and execute blocks, how -transactions are propagated, and how state transitions are verified. It covers core protocol rules, -execution behavior, and proving. - -## Design Goals - -Our aim is to design a protocol specification that is: - -- **Opinionated:** Simplicity through deliberate design choices. We identify the best solution and - commit to it. -- **Maximally Simple:** By focusing on just what Base needs, we radically simplify the stack. The - protocol spec and codebase should be understandable by a single developer. -- **Fast Cycles:** We ship upgrades frequently rather than batching risk into infrequent large ones. - We target six smaller, tightly scoped hard forks per year on a regular cadence, with fortnightly - releases. -- **Ethereum Aligned:** Base wins when Ethereum wins. We accelerate deployment of high-impact - changes ahead of L1 to provide data that informs the Ethereum roadmap. - -## Lineage - -Base Chain inherits Ethereum's EVM semantics, transaction rules, and L1-anchored security. It was -originally built on the [OP Stack](https://specs.optimism.io). After the Jovian Hardfork, Base Chain follows this specification. +Base is a rollup built on Ethereum. L2 transaction data is posted to Ethereum for data availability, +and proofs allow anyone to challenge invalid state transitions. This page gives a high-level tour of the +protocol components and the core user flows. ## Network Participants diff --git a/docs/docs.json b/docs/docs.json index 9fa30a1b9..92bda6d42 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -176,7 +176,54 @@ "group": "Specifications", "pages": [ "base-chain/overview", - "base-chain/specs/overview", + { + "group": "Base Protocol", + "pages": [ + "base-chain/specs/overview", + { + "group": "Consensus", + "pages": [ + "base-chain/specs/protocol/consensus/index", + "base-chain/specs/protocol/consensus/derivation", + "base-chain/specs/protocol/consensus/p2p", + "base-chain/specs/protocol/consensus/rpc" + ] + }, + { + "group": "Execution", + "pages": [ + "base-chain/specs/protocol/execution/index", + "base-chain/specs/protocol/execution/evm/precompiles", + "base-chain/specs/protocol/execution/evm/predeploys", + "base-chain/specs/protocol/execution/evm/preinstalls" + ] + }, + { + "group": "Bridging", + "pages": [ + "base-chain/specs/protocol/bridging/bridges", + "base-chain/specs/protocol/bridging/deposits", + "base-chain/specs/protocol/bridging/withdrawals", + "base-chain/specs/protocol/bridging/messengers", + "base-chain/network-information/base-solana-bridge" + ] + }, + "base-chain/specs/protocol/batcher", + { + "group": "Proofs", + "pages": [ + "base-chain/specs/protocol/proofs/index", + "base-chain/specs/protocol/proofs/challenger", + "base-chain/specs/protocol/proofs/proposer", + "base-chain/specs/protocol/proofs/registrar", + "base-chain/specs/protocol/proofs/tee-prover", + "base-chain/specs/protocol/proofs/zk-prover", + "base-chain/specs/protocol/proofs/contracts" + ] + }, + "base-chain/specs/design-goals" + ] + }, { "group": "B20", "pages": [ @@ -206,16 +253,6 @@ ] }, "base-chain/specs/native-account-abstraction", - { - "group": "Bridging", - "pages": [ - "base-chain/specs/protocol/bridging/bridges", - "base-chain/specs/protocol/bridging/deposits", - "base-chain/specs/protocol/bridging/withdrawals", - "base-chain/specs/protocol/bridging/messengers", - "base-chain/network-information/base-solana-bridge" - ] - }, { "group": "Transactions", "pages": [ @@ -226,43 +263,7 @@ "base-chain/network-information/troubleshooting-transactions" ] }, - "base-chain/flashblocks/faq", - { - "group": "Batcher", - "pages": [ - "base-chain/specs/protocol/batcher" - ] - }, - { - "group": "Consensus", - "pages": [ - "base-chain/specs/protocol/consensus/index", - "base-chain/specs/protocol/consensus/derivation", - "base-chain/specs/protocol/consensus/p2p", - "base-chain/specs/protocol/consensus/rpc" - ] - }, - { - "group": "Execution", - "pages": [ - "base-chain/specs/protocol/execution/index", - "base-chain/specs/protocol/execution/evm/precompiles", - "base-chain/specs/protocol/execution/evm/predeploys", - "base-chain/specs/protocol/execution/evm/preinstalls" - ] - }, - { - "group": "Proofs", - "pages": [ - "base-chain/specs/protocol/proofs/index", - "base-chain/specs/protocol/proofs/challenger", - "base-chain/specs/protocol/proofs/proposer", - "base-chain/specs/protocol/proofs/registrar", - "base-chain/specs/protocol/proofs/tee-prover", - "base-chain/specs/protocol/proofs/zk-prover", - "base-chain/specs/protocol/proofs/contracts" - ] - } + "base-chain/flashblocks/faq" ] }, { diff --git a/docs/ia-guidelines.md b/docs/ia-guidelines.md index b6b64c5c0..df05f0f1c 100644 --- a/docs/ia-guidelines.md +++ b/docs/ia-guidelines.md @@ -95,47 +95,29 @@ Content is organized by topic, not by abstraction level. Each topic group flows - **Belongs**: Native account abstraction specification for Base. Listed as a top-level page, not a dropdown group (single-page groups should be promoted to top-level pages). - **Does not belong**: SDK integration guides for smart wallets (SDKs & APIs → Base Account SDK). -### Bridging +### Base Protocol + +A dropdown group containing the protocol overview, component specs, and design goals. Ordering: Overview → Consensus → Execution → Bridging → Batcher → Proofs → Design Goals. -- **Belongs**: Standard bridges contract spec, deposits spec, withdrawals spec, cross-domain messengers spec, Base-Solana bridge. Include a changelog summary page linking to hardfork entries that changed bridging. -- **Does not belong**: User-facing bridge route picker (that's Get Started → Quickstart). How-to guides for building bridge integrations (Build on Base). Per-hardfork changelog detail pages (Upgrades). -- **Ordering**: Standard bridges → deposits → withdrawals → cross-domain messengers → Base-Solana bridge. Protocol specs first (general to specific), then the first-party ecosystem bridge. +- **Overview**: Network participants, high-level system diagram, protocol component summaries with diagrams, and core user flows (deposits, transactions, withdrawals). +- **Consensus**: Derivation pipeline, P2P networking, RPC methods for consensus. +- **Execution**: EVM precompiles, predeploys, preinstalls. +- **Bridging**: Standard bridges contract spec, deposits spec, withdrawals spec, cross-domain messengers spec, Base-Solana bridge. Ordering: standard bridges → deposits → withdrawals → cross-domain messengers → Base-Solana bridge. +- **Batcher**: How transaction batches are compressed and posted to Ethereum for data availability. Listed as a top-level page (single-page groups should be promoted). +- **Proofs**: Challenger, proposer, registrar, TEE prover, ZK prover, proof contracts. +- **Design Goals**: Design philosophy and lineage. Listed as last item in the group. +- **Does not belong**: User-facing bridge route picker (Get Started → Quickstart). SDK integration guides (SDKs & APIs). Hardfork-specific changes (Upgrades). ### Transactions - **Belongs**: Transaction ordering, transaction finality, network fees, throughput and limits, troubleshooting transactions. Everything about how transactions work on Base, from user experience to network parameters. -- **Does not belong**: Derivation pipeline or consensus specs (Consensus). Per-hardfork changelog detail pages (Upgrades). +- **Does not belong**: Derivation pipeline or consensus specs (Base Protocol → Consensus). Per-hardfork changelog detail pages (Upgrades). ### Flashblocks -- **Belongs**: Flashblocks reference — key concepts, architecture, and FAQ about block building, WebSocket data, RPC usage, and node setup. +- **Belongs**: Flashblocks reference — key concepts, architecture, and FAQ about block building, WebSocket data, RPC usage, and node setup. Listed as a top-level page, not a dropdown group. - **Does not belong**: Flashblocks API methods (SDKs & APIs → Base Chain API). Transaction ordering details (Transactions). -### Base Protocol - -- **Belongs**: Design goals, lineage, network participants, system architecture diagrams, protocol component summaries, and core user flows (deposits, transactions, withdrawals). Listed as a top-level page, not a dropdown group. -- **Does not belong**: Per-component specs (those go in their respective topic groups: Consensus, Execution, Proofs, etc.). - -### Batcher - -- **Belongs**: Batcher specification — how transaction batches are compressed and posted to Ethereum for data availability. -- **Does not belong**: Derivation details (Consensus). Hardfork-specific batcher changes (Upgrades). - -### Consensus - -- **Belongs**: Consensus specifications: derivation pipeline, P2P networking, RPC methods for consensus. -- **Does not belong**: Batcher (separate group). Execution engine details (Execution). Hardfork-specific changes (Upgrades). - -### Execution - -- **Belongs**: Execution specifications: EVM precompiles, predeploys, preinstalls. -- **Does not belong**: Consensus or derivation details (Consensus). Hardfork-specific changes (Upgrades). - -### Proofs - -- **Belongs**: Proof system specifications: challenger, proposer, registrar, TEE prover, ZK prover, proof contracts. -- **Does not belong**: Consensus or derivation details (Consensus). Hardfork-specific changes (Upgrades). - ### Reference - **Belongs**: Builder codes, base contracts, smart contracts, configurability reference, glossary. Lookup-oriented content. @@ -216,6 +198,8 @@ Key IA decisions from past reorganizations, for context: | No per-feature upgrade groups | Feature changes (e.g., B20) go under the hardfork that introduced them (Cobalt, Beryl), not a standalone section | | Changelog summary pages in Specifications | Each topic group gets a changelog summary page that links out to detail entries in the Upgrades tab — Specifications owns the spec and the summary, Upgrades owns the migration details | | Node operators stay in Specifications | Node ops are protocol-adjacent, not SDK/API work | +| Consensus, Execution, Bridging, Batcher, Proofs nested under Base Protocol | These are all protocol-level component specs — grouping them under Base Protocol reduces top-level clutter and mirrors the protocol overview page structure | +| Base Protocol overview + design goals split into two pages | The overview covers architecture and user flows (reference material); design goals covers philosophy and lineage (background reading) — different audiences and frequencies of access | | Get Started → Solutions are entry ramps only | They link to Build on Base guides, they don't duplicate them | | Mini Apps renamed to Apps | Broader scope, `/mini-apps/` paths redirect to `/apps/` | | Tokenize Stocks renamed to Tokenize Assets | Broader scope for asset tokenization beyond equities |