node Documentation

1. Project Overview & Quickstart (base/node) Copy Chapter

Base Node

Base is a secure, low-cost, developer-friendly Ethereum L2 built on Optimism's OP Stack. This repository contains a Docker build for running a Base node with base-reth-node and base-consensus.

Quick Start Copy Chapter

1. Ensure you have an Ethereum L1 full node RPC and beacon endpoint available.

2. Choose your network:

   • For mainnet: use .env.mainnet
   • For testnet: use .env.sepolia

3. Configure your L1 endpoints in the appropriate .env file:

   bash Copy

   BASE_NODE_L1_ETH_RPC=<your-preferred-l1-rpc>
   BASE_NODE_L1_BEACON=<your-preferred-l1-beacon>

4. Start the node:

   bash Copy

   # For mainnet (default):
   docker compose up --build
   
   # For testnet:
   NETWORK_ENV=.env.sepolia docker compose up --build

Supported Clients Copy Chapter

• Execution: base-reth-node
• Consensus: base-consensus

Requirements Copy Chapter

Minimum Requirements Copy Section

• Modern multicore CPU
• 32GB RAM (64GB recommended)
• NVMe SSD drive
• Storage: (2 * current chain size + snapshot size + 20% buffer) to accommodate future growth
• Docker and Docker Compose

Production Hardware Specifications Copy Section

The following are the hardware specifications we use in production:

Reth Archive Node (recommended)

• Instance: AWS i7i.12xlarge
• Storage: RAID 0 of all local NVMe drives (/dev/nvme*)
• Filesystem: ext4

Configuration Copy Chapter

Required Settings Copy Section

• BASE_NODE_L1_ETH_RPC: your Ethereum L1 node RPC endpoint
• BASE_NODE_L1_BEACON: your L1 beacon node endpoint
• BASE_NODE_NETWORK: base or base-sepolia
• RETH_CHAIN: base or base-sepolia

Network Settings Copy Section

• Mainnet:
  • RETH_CHAIN=base
  • BASE_NODE_NETWORK=base
  • Sequencer: https://mainnet-sequencer.base.org
• Sepolia:
  • RETH_CHAIN=base-sepolia
  • BASE_NODE_NETWORK=base-sepolia
  • Sequencer: https://sepolia-sequencer.base.org

Optional Features Copy Section

• Flashblocks: set RETH_FB_WEBSOCKET_URL. When set, the execution client runs in Flashblocks mode; otherwise it runs in vanilla mode.
• Follow mode: set BASE_NODE_SOURCE_L2_RPC
• Pruning: set RETH_PRUNING_ARGS

For full configuration options, see .env.mainnet or .env.sepolia.

Testing Flashblocks RPC Methods Copy Section

When running in Flashblocks mode, you can query a pending block using the Flashblocks RPC:

curl -X POST \
  --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \
  http://localhost:8545

Snapshots Copy Chapter

Snapshots are available to help you sync your node more quickly. See docs.base.org for links and more details on how to restore from a snapshot.

Supported Networks Copy Chapter

Troubleshooting Copy Chapter

For support please join our Discord and post in 🛠｜node-operators. You can alternatively open a new GitHub issue.

Disclaimer Copy Chapter

THE NODE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. We make no guarantees about asset protection or security. Usage is subject to applicable laws and regulations.

For more information, visit docs.base.org.

2. Official Technical Reference & Guides (base/docs) Copy Chapter

Base Docs are community-managed. We welcome and encourage contributions from everyone to keep these docs accurate, helpful, and up to date.

Note: This repository powers the public Base documentation site. Content lives under docs/.

Local development Copy Chapter

Prerequisite: Node.js v19+.

1. Clone the repository.
2. Install the Mint CLI to preview documentation changes locally:

npm i mint

3. Preview locally (run from the docs/ directory where docs.json lives):

cd docs
mint dev

Alternatively, without a global install:

npx mint dev

Troubleshooting Copy Section

• Ensure Node.js v19+ is installed and that you run mint dev from the directory containing docs.json (usually docs/).
• Local preview differs from production: run mint update to update the CLI.

How to contribute Copy Chapter

1. Fork and branch: Fork base/docs and create a descriptive branch for your change.
2. Edit content in docs/: Follow the structure and style guidelines below. Preview locally with the Mint CLI.
3. Open a pull request: Provide a clear summary and links to related pages. The docs team and community will review.

Tip: Prefer small, focused PRs. Link related guides and references directly in your content.

Documentation structure Copy Chapter

Core principle: maintain existing structure Copy Section

Warning: Do not create new top-level sections. Place all new content within existing folders under docs/.

The Base documentation is organized into established sections (for example: get-started/, learn/, base-account/, base-app/, base-chain/, cookbook/, mini-apps/, onchainkit/). Fit new content into the most relevant existing section.

Navigation policy Copy Section

Note: We generally do not change the global navigation (top-level tabs) or sidebar sections unless there is a clear, broadly beneficial need. Contributions should focus on improving existing pages and adding new pages within current sections.

Section purpose and placement Copy Section

• Quickstart: End-to-end setup to first success. Keep concise and current.
• Concepts: Explanations of components, architecture, and design philosophy.
• Guides: Step-by-step, action-oriented tutorials for specific tasks.
• Examples: Complete, runnable examples demonstrating real-world usage.
• Technical Reference: API/method/component specs with parameters and return types.
• Contribute: Information for contributors and process updates.

Cookbook scope

• The cookbook/ section hosts use case-focused guides and patterns, not product-specific documentation.
• Prefer cross-cutting solutions that illustrate how to build on Base across tools and scenarios.

Warning: Avoid subsection proliferation:

• Put all guides at the same level within the Guides section.
• Organize Reference by component/feature, not per use case.
• Use cross-links instead of adding new structural layers.

Style and formatting Copy Chapter

Writing style Copy Section

1. Be concise and consistent; use active voice and second person.
2. Focus on the happy path; mention alternatives briefly where relevant.
3. Use explicit, descriptive headings and filenames.
4. Maintain consistent terminology; introduce abbreviations on first use.

AI-friendly content Copy Section

• Use clear, explicit language and link related pages directly.
• Prefer bulleted lists for options/steps when not sequential.
• Name and reference libraries and tools explicitly.
• Use semantic, readable URLs and avoid ambiguous abbreviations.

Checklist:

• Would a Large Language Model understand and follow this content?
• Can an engineer copy, paste, and run the examples as-is?

Mintlify formatting Copy Section

• Start main sections with H2 (##) and subsections with H3 (###).
• Use fenced code blocks with language and optional filename.
• Wrap images in <Frame> and include alt text.
• Use callouts for emphasis: <Note>, <Tip>, <Warning>, ``, <Check>.
• For procedures, prefer <Steps> / <Step>.
• For alternatives, use <Tabs> / <Tab>.
• For API docs, use ``, <ResponseField>, and request/response examples.

Code examples Copy Section

• Provide complete, runnable examples with realistic data.
• Include proper error handling and edge cases.
• Specify language and filename when helpful.
• Show expected output or verification steps.

Third-party guides policy Copy Chapter

Warning: We generally do not accept guides that primarily document a third-party product. Exceptions require a clear Base-focused use case and a tight integration with Base products. Simply deploying on Base or connecting to Base Account/Base App is not sufficient.

If your goal is to increase discoverability of your product, please request inclusion on the Base Ecosystem page instead. See the instructions for updating the Base Ecosystem page.

Review checklist (before submitting a PR) Copy Chapter

• Fits within existing structure (no new top-level sections)
• Minimal, necessary subsections only
• Consistent terminology; abbreviations introduced on first use
• Code examples are complete, runnable, and validated
• Cross-links to related guides/examples/references are included
• Uses Mintlify components and heading hierarchy correctly
• Accessible images with descriptive alt text and frames
• AI-friendly: explicit, link-rich, and easy to follow

Submission process Copy Chapter

1. Create a PR to https://github.com/base/docs with your changes.
2. Include a clear description of the change and impacted pages.
3. Request review from the docs team.
4. Address feedback and iterate.
5. Once approved, changes will be merged and published.

Publishing changes Copy Chapter

The core team will review opened PRs. The SLA is 2 weeks, generally on a first-come, first-served basis outside of urgent changes.

Storybook for UI components Copy Chapter

See storybook/README.md for details on local Storybook and component docs.