## 1. Project Overview & Quickstart (base/node) # Base Node Base is a secure, low-cost, developer-friendly Ethereum L2 built on Optimism's [OP Stack](https://docs.optimism.io/). This repository contains a Docker build for running a Base node with `base-reth-node` and `base-consensus`. [](https://base.org) [](https://docs.base.org/) [](https://base.org/discord) [](https://x.com/Base) [](https://farcaster.xyz/base) ## Quick Start 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 BASE_NODE_L1_ETH_RPC= BASE_NODE_L1_BEACON= ``` 4. Start the node: ```bash # For mainnet (default): docker compose up --build # For testnet: NETWORK_ENV=.env.sepolia docker compose up --build ``` ## Supported Clients - Execution: `base-reth-node` - Consensus: `base-consensus` ## Requirements ### Minimum Requirements - Modern multicore CPU - 32GB RAM (64GB recommended) - NVMe SSD drive - Storage: (2 * [current chain size](https://base.org/stats) + [snapshot size](https://basechaindata.vercel.app) + 20% buffer) to accommodate future growth - Docker and Docker Compose ### Production Hardware Specifications 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 ### Required Settings - `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 - 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 - 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 When running in Flashblocks mode, you can query a pending block using the Flashblocks RPC: ```bash curl -X POST \ --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \ http://localhost:8545 ``` ## Snapshots Snapshots are available to help you sync your node more quickly. See [docs.base.org](https://docs.base.org/chain/run-a-base-node#snapshots) for links and more details on how to restore from a snapshot. ## Supported Networks | Network | Status | | ------- | ------ | | Mainnet | ✅ | | Testnet | ✅ | ## Troubleshooting For support please join our [Discord](https://discord.gg/buildonbase) and post in `🛠｜node-operators`. You can alternatively open a new GitHub issue. ## Disclaimer 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](https://docs.base.org/). ## 2. Official Technical Reference & Guides (base/docs) [](https://github.com/base/docs/graphs/contributors) [](https://github.com/base/docs/graphs/contributors) [](https://github.com/base/docs/stargazers) [](https://github.com/base/docs/blob/main/LICENSE.md) [](https://base.org) [](https://base.mirror.xyz/) [](https://docs.base.org/) [](https://base.org/discord) [](https://twitter.com/Base) [](https://github.com/base/docs/pulls) [](https://github.com/base/docs/issues) 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 Prerequisite: Node.js v19+. 1. Clone the repository. 2. Install the Mint CLI to preview documentation changes locally: ```bash npm i mint ``` 3. Preview locally (run from the `docs/` directory where `docs.json` lives): ```bash cd docs mint dev ``` Alternatively, without a global install: ```bash npx mint dev ``` ### Troubleshooting - 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 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 ### Core principle: maintain existing structure > 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 > 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 - **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 ### Writing style 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 - 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 - Start main sections with H2 (`##`) and subsections with H3 (`###`). - Use fenced code blocks with language and optional filename. - Wrap images in `` and include `alt` text. - Use callouts for emphasis: ``, ``, ``, ``, ``. - For procedures, prefer `` / ``. - For alternatives, use `` / ``. - For API docs, use ``, ``, and request/response examples. ### Code examples - 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 > 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](https://github.com/base/web?tab=readme-ov-file#updating-the-base-ecosystem-page). ## Review checklist (before submitting a PR) - [ ] 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 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 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 See `storybook/README.md` for details on local Storybook and component docs.