Skip to content

docs: improve README with prerequisites, verification steps, and configuration details#1127

Open
2TheMoom wants to merge 1 commit into
base:mainfrom
2TheMoom:main
Open

docs: improve README with prerequisites, verification steps, and configuration details#1127
2TheMoom wants to merge 1 commit into
base:mainfrom
2TheMoom:main

Conversation

@2TheMoom

@2TheMoom 2TheMoom commented Jun 9, 2026

Copy link
Copy Markdown

This PR improves the README for node operators with the following additions:

  • Prerequisites section — Docker version requirements and verification commands so operators know exactly what's needed before starting
  • Node verification steps — how to confirm the node is running correctly after startup including an eth_blockNumber health check
  • Concrete storage example — clarifies the storage formula with real numbers (e.g. 500GB chain + 200GB snapshot = ~1.44TB)
  • BASE_NODE_VERIFIER_L1_CONFS documentation — env variable introduced in v0.15.3 that was undocumented
  • Upgrading section — step-by-step upgrade commands with a note for pruned node operators
  • Troubleshooting section — three common issues with solutions

@cb-heimdall

Copy link
Copy Markdown
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/1
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 1
Sum 2

@osr21

osr21 commented Jun 10, 2026

Copy link
Copy Markdown

Great additions — the eth_blockNumber health check is exactly the kind of practical detail that saves time on first setup.

One thing worth adding to the verification section (or a gotchas note): the public http://localhost:8545 endpoint you're calling for eth_blockNumber is fine for local node operators, but if you're building an app that routes external traffic to a Base node, the free public https://mainnet.base.org endpoint rate-limits under production load.

We hit this running BasePay, a gasless relay on Base Mainnet. A relay handler that makes 7–9 sequential RPC calls per swap (balance checks, quotes, TX submits, receipt polling) trips the rate limit under modest traffic — the errors look like smart-contract failures but are actually just HTTP 429s from the RPC endpoint.

The fix is using the Coinbase Node authenticated endpoint:

# Public — rate-limited, no auth required
https://mainnet.base.org

# Authenticated — higher limits, same infrastructure
https://api.developer.coinbase.com/rpc/v1/base/<YOUR_CDP_API_KEY>

In code:

const transport = http(
  process.env.CDP_API_KEY
    ? `https://api.developer.coinbase.com/rpc/v1/base/${process.env.CDP_API_KEY}`
    : "https://mainnet.base.org" // local dev fallback
);

If the README's verification section notes this distinction — even just a line that mainnet.base.org is a shared public endpoint with rate limits — it would save builders from chasing phantom contract bugs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants