Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/.mintignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,8 @@ writing.md
API_MIGRATION_PLAN.md

tone_of_voice.mdx

# Pages removed from nav and redirected elsewhere
base-chain/network-information/bridging-and-withdrawals.mdx
base-chain/network-information/network-faucets.mdx
base-chain/quickstart/connecting-to-base.mdx
33 changes: 7 additions & 26 deletions docs/base-chain/overview.mdx
Original file line number Diff line number Diff line change
@@ -1,48 +1,32 @@
---
title: "Overview"
description: "Base protocol specifications, core primitives, and network systems."
description: "Base protocol specifications — tokens, bridging, transactions, consensus, execution, and proofs."
---

Technical specifications for how Base works at the chain level. Core Primitives covers what developers interact with directly — tokens, accounts, bridging, fees, and transactions. Network Systems covers protocol internals — the batcher, consensus, execution, and proof system.

### Core Primitives
Technical specifications for how Base works at the chain level, organized by topic from user-facing primitives to protocol internals.

<CardGroup cols={2}>
<Card title="B20" icon="coin" href="/base-chain/specs/reference/b20/index">
Native token standard with compliance, memos, and supply controls.
</Card>
<Card title="Native Account Abstraction" icon="key" href="/base-chain/specs/native-account-abstraction">
<Card title="Account Abstraction" icon="key" href="/base-chain/specs/native-account-abstraction">
Smart accounts that send ordinary transactions with no bundlers or relays.
</Card>
<Card title="Bridging" icon="bridge" href="/base-chain/network-information/ecosystem-bridges">
Move ETH, stablecoins, and tokens to and from Base.
</Card>
<Card title="Network Fees" icon="receipt" href="/base-chain/network-information/network-fees">
L2 execution fees, L1 security fees, and cost-saving strategies.
Move assets to and from Base — ecosystem bridges, Solana bridge, and protocol specs.
</Card>
<Card title="Transaction Ordering" icon="arrow-down-1-9" href="/base-chain/network-information/transaction-ordering">
How transactions are ordered by priority fee and arrival time.
</Card>
<Card title="Transaction Finality" icon="check-double" href="/base-chain/network-information/transaction-finality">
Confirmation stages from unsafe through finalized.
<Card title="Transactions" icon="arrow-down-1-9" href="/base-chain/network-information/transaction-ordering">
Ordering, finality, fees, throughput, and troubleshooting.
</Card>
<Card title="Flashblocks" icon="bolt" href="/base-chain/flashblocks/faq">
Sub-second block building, WebSocket data, and RPC usage.
</Card>
</CardGroup>

### Network Systems

<CardGroup cols={2}>
<Card title="Protocol" icon="diagram-project" href="/base-chain/specs/protocol/overview">
<Card title="Protocol Overview" icon="diagram-project" href="/base-chain/specs/protocol/overview">
Rollup architecture, core components, and user flows.
</Card>
<Card title="Batcher" icon="layer-group" href="/base-chain/specs/protocol/batcher">
Posting L2 sequencer data to L1 for data availability.
</Card>
<Card title="Standard Bridges" icon="right-left" href="/base-chain/specs/protocol/bridging/bridges">
Cross-domain ETH and ERC-20 transfers between L1 and L2.
</Card>
<Card title="Consensus" icon="handshake" href="/base-chain/specs/protocol/consensus/index">
L2 block derivation, P2P networking, and RPC specification.
</Card>
Expand All @@ -52,7 +36,4 @@ Technical specifications for how Base works at the chain level. Core Primitives
<Card title="Proofs" icon="shield-check" href="/base-chain/specs/protocol/proofs/index">
Multi-proof checkpoint verification with TEE and ZK provers.
</Card>
<Card title="Throughput and Limits" icon="gauge-high" href="/base-chain/network-information/throughput-and-limits">
Gas limits and throughput-related network parameters.
</Card>
</CardGroup>
13 changes: 5 additions & 8 deletions docs/base-chain/specs/protocol/bridging/bridges.mdx
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
---
title: "Standard Bridges"
description: "Specification of the standard bridges enabling cross-domain ETH and ERC20 token transfers between L1 and L2 on Base."
description: "Specification of the standard bridge contracts enabling cross-domain ETH and ERC-20 token transfers between L1 and L2 on Base."
---

The standard bridges support cross-domain ETH and ERC-20 transfers between Ethereum (L1) and Base (L2). They are built on top of the [cross-domain messenger contracts](/base-chain/specs/protocol/bridging/messengers) and provide a standard interface for moving tokens between domains.

For the underlying transaction mechanisms, see [Deposits](/base-chain/specs/protocol/bridging/deposits) and [Withdrawals](/base-chain/specs/protocol/bridging/withdrawals).

## Overview

The standard bridges are responsible for allowing cross domain
Expand Down Expand Up @@ -35,13 +39,6 @@ interface StandardBridge {
}
```

## Token Depositing

The `bridgeERC20` function is used to send a token from one domain to another
domain. An `OptimismMintableERC20` token contract must exist on the remote
domain to be able to deposit tokens to that domain. One of these tokens can be
deployed using the `OptimismMintableERC20Factory` contract.

## Upgradability

Both the L1 and L2 standard bridges should be behind upgradable proxies.
8 changes: 7 additions & 1 deletion docs/base-chain/specs/protocol/bridging/deposits.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Deposits"
description: "Specification of the deposit mechanism for Base, detailing how L1 transactions are converted into L2 deposit transactions."
description: "How deposits work on Base — from user experience to the protocol-level deposit transaction type and guaranteed gas market."
---

[g-transaction-type]: ../../reference/glossary#transaction-type
Expand All @@ -12,6 +12,12 @@ description: "Specification of the deposit mechanism for Base, detailing how L1
[g-eoa]: ../../reference/glossary#eoa
[g-exec-engine]: ../../reference/glossary#execution-engine

A deposit is a transaction initiated outside Base that becomes a transaction on Base. For Ethereum deposits, the L1 transaction emits data that Base nodes use to derive a corresponding L2 deposit transaction.

Deposit transactions are included as part of the protocol. They do not use the same signature, nonce, or fee fields as ordinary L2 transactions because they are authorized by the L1 deposit event and pay for L2 gas on L1. For most users, the practical result is simple: after the source-chain transaction is confirmed and processed, the asset or message appears on Base.

For available bridge routes, see [Bridge to Base](/base-chain/network-information/ecosystem-bridges).

## Overview

[Deposited transactions][g-deposited], also known as [deposits][g-deposits] are transactions which
Expand Down
14 changes: 13 additions & 1 deletion docs/base-chain/specs/protocol/bridging/withdrawals.mdx
Original file line number Diff line number Diff line change
@@ -1,13 +1,25 @@
---
title: "Withdrawals"
description: "Specification of the withdrawal mechanism for Base, describing how L2 state is proven on L1 and funds are released from the bridge."
description: "How withdrawals work on Base — the standard 3-step flow, the 7-day challenge period, faster options, and the full protocol specification."
---

[g-deposits]: ../../reference/glossary#deposits
[g-withdrawal]: ../../reference/glossary#withdrawal
[g-relayer]: ../../reference/glossary#withdrawals
[g-execution-engine]: ../../reference/glossary#execution-engine

A standard withdrawal is a cross-domain transaction initiated on Base and finalized on Ethereum. Standard withdrawals can transfer ETH, bridge supported ERC-20 tokens, or send a message from Base to an L1 contract. The flow has three stages:

1. **Initiate on Base:** the withdrawal transaction is sent on Base. This records the withdrawal message in the `L2ToL1MessagePasser` contract.
2. **Prove on Ethereum:** after the relevant Base state has been posted to Ethereum, anyone can submit a proof to the `OptimismPortal` contract showing that the withdrawal message exists on Base.
3. **Finalize on Ethereum:** after the 7-day challenge period has passed, anyone can finalize the withdrawal on Ethereum. Finalization releases the assets or relays the message to the target contract.

<Note>
Standard withdrawals to Ethereum must wait 7 days before they can be finalized. Base uses fault proofs to secure withdrawals — the challenge period gives network participants time to dispute an invalid output root before withdrawals that depend on it can be finalized. See [Transaction Finality](/base-chain/network-information/transaction-finality#finality-for-withdrawal-transactions) for how withdrawal finality differs from ordinary Base transaction finality.
</Note>

Some bridge providers offer faster withdrawals by using liquidity, relayers, or market makers to give users funds before the standard withdrawal has fully finalized. See [Bridge to Base](/base-chain/network-information/ecosystem-bridges) for available routes.

## Overview

[Withdrawals][g-withdrawal] are cross domain transactions which are initiated on L2, and finalized by a transaction
Expand Down
11 changes: 3 additions & 8 deletions docs/content-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,11 +95,11 @@ description: "Concise description explaining page purpose and value"

## Specification Pages

Content structure and writing guidelines for Base Protocol specification pages — Core Primitives and Network Systems.
Content structure and writing guidelines for Specifications pages.

### Page Types

Every feature or subsystem in Core Primitives and Network Systems uses a combination of these page types:
Every feature or subsystem in the Specifications tab uses a combination of these page types:

| Page type | Purpose | Example |
|-----------|---------|---------|
Expand Down Expand Up @@ -162,12 +162,7 @@ Not every feature needs all four types. A single-page feature (e.g., network fee

A feature gets a nested group in the sidebar (like B20, Bridging, Proofs) when it has 3+ pages. Features with 1–2 pages sit as flat entries in the parent group.

| Core Primitives | Network Systems |
|-----------------|-----------------|
| Things developers interact with directly | Protocol internals that power the chain |
| User-facing behavior: tokens, transactions, fees, bridges | Infrastructure: batcher, derivation, execution, proofs |
| "What can I do on Base?" | "How does Base work under the hood?" |
| Audience: app developers, integrators | Audience: protocol engineers, node operators, researchers |
Content is organized by topic (B20, Bridging, Transactions, Consensus, Execution, Proofs, etc.), not by abstraction level. Each topic group flows from user-facing overview to deep protocol spec. A feature gets a nested group in the sidebar when it has 3+ pages; features with 1–2 pages sit as flat entries or single-page groups.

---

Expand Down
83 changes: 46 additions & 37 deletions docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@
"get-started/base",
"get-started/connect-to-base",
"get-started/get-funds",
"get-started/make-a-transaction"
"get-started/make-a-transaction",
"base-chain/network-information/ecosystem-bridges"
]
},
{
Expand Down Expand Up @@ -175,13 +176,6 @@
"group": "Specifications",
"pages": [
"base-chain/overview",
"base-chain/quickstart/connecting-to-base",
"base-chain/network-information/network-faucets"
]
},
{
"group": "Core Primitives",
"pages": [
{
"group": "B20",
"pages": [
Expand Down Expand Up @@ -214,36 +208,40 @@
{
"group": "Bridging",
"pages": [
"base-chain/network-information/ecosystem-bridges",
"base-chain/network-information/base-solana-bridge",
"base-chain/network-information/bridging-and-withdrawals"
"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/network-information/network-fees",
{
"group": "Transactions",
"pages": [
"base-chain/network-information/transaction-ordering",
"base-chain/network-information/transaction-finality",
"base-chain/network-information/network-fees",
"base-chain/network-information/throughput-and-limits",
"base-chain/network-information/troubleshooting-transactions"
]
},
"base-chain/flashblocks/faq"
]
},
{
"group": "Network Systems",
"pages": [
"base-chain/specs/overview",
"base-chain/specs/protocol/overview",
"base-chain/specs/protocol/batcher",
{
"group": "Bridging",
"group": "Flashblocks",
"pages": [
"base-chain/specs/protocol/bridging/bridges",
"base-chain/specs/protocol/bridging/deposits",
"base-chain/specs/protocol/bridging/messengers",
"base-chain/specs/protocol/bridging/withdrawals"
"base-chain/flashblocks/faq"
]
},
{
"group": "Protocol Overview",
"pages": [
"base-chain/specs/overview",
"base-chain/specs/protocol/overview"
]
},
{
"group": "Batcher",
"pages": [
"base-chain/specs/protocol/batcher"
]
},
{
Expand Down Expand Up @@ -275,8 +273,7 @@
"base-chain/specs/protocol/proofs/zk-prover",
"base-chain/specs/protocol/proofs/contracts"
]
},
"base-chain/network-information/throughput-and-limits"
}
]
},
{
Expand Down Expand Up @@ -867,6 +864,18 @@
]
},
"redirects": [
{
"source": "/base-chain/network-information/bridging-and-withdrawals",
"destination": "/base-chain/specs/protocol/bridging/withdrawals"
},
{
"source": "/base-chain/network-information/network-faucets",
"destination": "/get-started/get-funds"
},
{
"source": "/base-chain/quickstart/connecting-to-base",
"destination": "/get-started/connect-to-base"
},
{
"source": "/base-account",
"destination": "/sdks/base-account/overview"
Expand Down Expand Up @@ -1957,7 +1966,7 @@
},
{
"source": "/base-chain/tools/network-faucets",
"destination": "/base-chain/network-information/network-faucets"
"destination": "/get-started/get-funds"
},
{
"source": "/base-chain/tools/node-providers",
Expand Down Expand Up @@ -2317,7 +2326,7 @@
},
{
"source": "/chain/connecting-to-base",
"destination": "/base-chain/quickstart/connecting-to-base"
"destination": "/get-started/connect-to-base"
},
{
"source": "/chain/cross-chain",
Expand Down Expand Up @@ -2361,11 +2370,11 @@
},
{
"source": "/chain/network-faucets",
"destination": "/base-chain/network-information/network-faucets"
"destination": "/get-started/get-funds"
},
{
"source": "/chain/network-information",
"destination": "/base-chain/quickstart/connecting-to-base"
"destination": "/get-started/connect-to-base"
},
{
"source": "/chain/node-performance",
Expand Down Expand Up @@ -2425,7 +2434,7 @@
},
{
"source": "/chain/using-base",
"destination": "/base-chain/quickstart/connecting-to-base"
"destination": "/get-started/connect-to-base"
},
{
"source": "/chain/wallet",
Expand Down Expand Up @@ -2533,11 +2542,11 @@
},
{
"source": "/docs/network-information",
"destination": "/base-chain/quickstart/connecting-to-base"
"destination": "/get-started/connect-to-base"
},
{
"source": "/docs/tools/network-faucets",
"destination": "/base-chain/network-information/network-faucets"
"destination": "/get-started/get-funds"
},
{
"source": "/feedback",
Expand Down Expand Up @@ -2885,7 +2894,7 @@
},
{
"source": "/network-information",
"destination": "/base-chain/quickstart/connecting-to-base"
"destination": "/get-started/connect-to-base"
},
{
"source": "/quickstart",
Expand All @@ -2901,7 +2910,7 @@
},
{
"source": "/tools/network-faucets",
"destination": "/base-chain/network-information/network-faucets"
"destination": "/get-started/get-funds"
},
{
"source": "/tutorials/deploy-with-foundry",
Expand Down
Loading
Loading