From b3f28fc195c1aad6abe94de1bc538171514ba7ba Mon Sep 17 00:00:00 2001 From: Dark-Brain07 Date: Wed, 28 Jan 2026 08:31:16 +0600 Subject: [PATCH 1/3] docs(nethermind): add comprehensive README for Nethermind client setup --- nethermind/README.md | 101 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 nethermind/README.md diff --git a/nethermind/README.md b/nethermind/README.md new file mode 100644 index 00000000..b157f9be --- /dev/null +++ b/nethermind/README.md @@ -0,0 +1,101 @@ +# Running a Nethermind Node + +This is an implementation of the Nethermind node setup for running a Base node with the Nethermind execution client. + +## Overview + +[Nethermind](https://github.com/NethermindEth/nethermind) is a high-performance, enterprise-grade Ethereum client written in .NET. It provides an alternative execution client option for running Base nodes with excellent support for enterprise deployments. + +## Setup + +- See hardware requirements mentioned in the master README +- Minimum 32GB RAM (64GB recommended) +- NVMe SSD storage for optimal performance +- The Nethermind client is built using .NET SDK 9.0 + +## Configuration + +The Nethermind client is configured through environment variables in `.env.mainnet` or `.env.sepolia`. + +### Key Configuration Options + +| Setting | Description | +|---------|-------------| +| `NETHERMIND_TAG` | Version tag of Nethermind to use | +| `NETHERMIND_COMMIT` | Specific commit hash for verification | +| `OP_NETHERMIND_ETHSTATS_ENABLED` | Enable EthStats monitoring | +| `OP_NETHERMIND_ETHSTATS_NODE_NAME` | Node name for EthStats | +| `OP_NETHERMIND_BOOTNODES` | Bootnode addresses for snap sync | + +## Running the Node + +The node follows the standard `docker-compose` workflow in the master README: + +```bash +# Run Nethermind node +CLIENT=nethermind docker-compose up +``` + +## Architecture Support + +Nethermind supports multiple architectures: + +| Architecture | Identifier | +|-------------|------------| +| AMD64/x86_64 | `x64` | +| ARM64 | `arm64` | + +The Dockerfile automatically detects and builds for the appropriate architecture. + +## Exposed Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 8545 | HTTP | JSON-RPC endpoint | +| 8546 | WebSocket | WebSocket RPC endpoint | +| 8551 | HTTP | Engine API (authenticated) | +| 6060 | HTTP | Metrics endpoint | +| 30303 | TCP/UDP | P2P network | + +## Optional Features + +### EthStats Monitoring + +Enable node monitoring by uncommenting in your `.env` file: + +```bash +OP_NETHERMIND_ETHSTATS_ENABLED=true +OP_NETHERMIND_ETHSTATS_NODE_NAME=NethermindNode +OP_NETHERMIND_ETHSTATS_ENDPOINT=ethstats_endpoint +``` + +### Snap Sync + +For faster initial sync, enable snap sync by uncommenting the bootnode configuration: + +```bash +OP_NETHERMIND_BOOTNODES=enode://... +``` + +## Additional Resources + +For more information about Nethermind configuration and features, refer to: + +- [Nethermind Documentation](https://docs.nethermind.io/) +- [Standard Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) +- [Nethermind GitHub Repository](https://github.com/NethermindEth/nethermind) + +## Troubleshooting + +### Common Issues + +#### Memory Usage + +Nethermind may require adjustment of .NET runtime settings for optimal memory usage. Ensure your system has sufficient RAM (64GB recommended for production). + +#### Sync Performance + +If experiencing slow sync performance: +- Verify network bandwidth is sufficient +- Consider using snap sync with bootnodes +- Check L1 RPC rate limits From f5d78ec2f9cc14ffa74b2dabb7427ed023fb10d2 Mon Sep 17 00:00:00 2001 From: Dark-Brain07 Date: Wed, 28 Jan 2026 08:34:47 +0600 Subject: [PATCH 2/3] docs(geth): add comprehensive README for Geth client setup --- geth/README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 geth/README.md diff --git a/geth/README.md b/geth/README.md new file mode 100644 index 00000000..146a19a5 --- /dev/null +++ b/geth/README.md @@ -0,0 +1,91 @@ +# Running a Geth Node + +This is an implementation of the op-geth (optimism-geth) node setup for running a Base node with the Geth execution client. + +## Overview + +[op-geth](https://github.com/ethereum-optimism/op-geth) is the Optimism implementation of the go-ethereum client, optimized for running OP Stack rollups like Base. It's a well-tested, production-ready client suitable for full node operation. + +## Setup + +- See hardware requirements mentioned in the master README +- Minimum 32GB RAM (64GB recommended) +- NVMe SSD storage for optimal performance + +## Configuration + +The Geth client is configured through environment variables in .env.mainnet or .env.sepolia. Key settings include: + +### Cache Settings + +Optimize cache allocation based on your available RAM: + +| Setting | Default | Description | +|---------|---------|-------------| +| GETH_CACHE | 20480 | Total cache allocation in MB (20GB default) | +| GETH_CACHE_DATABASE | 20 | Percentage allocated to database cache | +| GETH_CACHE_GC | 12 | Percentage allocated to garbage collection | +| GETH_CACHE_SNAPSHOT | 24 | Percentage allocated to snapshot cache | +| GETH_CACHE_TRIE | 44 | Percentage allocated to trie cache | + +### Sync Modes + +| Mode | Environment Variable | Description | +|------|---------------------|-------------| +| Full Sync | OP_GETH_SYNCMODE=full | Download and verify all blocks (default) | +| Snap Sync | OP_GETH_SYNCMODE=snap | Faster initial sync (experimental) | + +### Network Modes + +| Mode | Environment Variable | Description | +|------|---------------------|-------------| +| Full | OP_GETH_GCMODE=full | Standard full node operation | +| Archive | OP_GETH_GCMODE=archive | Retain all historical states | + +## Running the Node + +The node follows the standard docker-compose workflow in the master README: + +\\\ash +# Run Geth node (default when no CLIENT is specified) +docker-compose up + +# Or explicitly specify Geth +CLIENT=geth docker-compose up +\\\`n +## Exposed Ports + +| Port | Protocol | Description | +|------|----------|-------------| +| 8545 | HTTP | JSON-RPC endpoint | +| 8546 | WebSocket | WebSocket RPC endpoint | +| 8551 | HTTP | Engine API (authenticated) | +| 6060 | HTTP | Metrics endpoint | +| 30303 | TCP/UDP | P2P network | + +## Optional Features + +### EthStats Monitoring + +Enable node monitoring by uncommenting in your .env file: + +\\\ash +OP_GETH_ETH_STATS=nodename:secret@host:port +\\\`n +### Snap Sync (Experimental) + +For faster initial sync, enable snap sync by uncommenting the bootnode configuration and setting sync mode: + +\\\ash +OP_GETH_SYNCMODE=snap +OP_GETH_BOOTNODES=enode://... +\\\`n +> [!WARNING] +> Snap sync is experimental and may lead to syncing issues. Use with caution in production environments. + +## Additional RPC Methods + +For a complete list of supported RPC methods, refer to: + +- [Standard Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) +- [Geth RPC Documentation](https://geth.ethereum.org/docs/rpc/server) \ No newline at end of file From a9d7b4429964b78caf1b0bc2b599f5d231cebdf2 Mon Sep 17 00:00:00 2001 From: Dark-Brain07 Date: Fri, 30 Jan 2026 06:58:29 +0600 Subject: [PATCH 3/3] docs(geth): enhance README with troubleshooting section and fix formatting - Fix markdown code block formatting (replace escaped backticks) - Add comprehensive troubleshooting section covering: - Slow sync performance issues - High memory usage solutions - Peer connection troubleshooting - Engine API authentication errors - Add peer connectivity configuration documentation - Add state scheme configuration section - Add unprotected transactions configuration - Add link to op-geth documentation --- geth/README.md | 99 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 19 deletions(-) diff --git a/geth/README.md b/geth/README.md index 146a19a5..c0d21d85 100644 --- a/geth/README.md +++ b/geth/README.md @@ -14,7 +14,7 @@ This is an implementation of the op-geth (optimism-geth) node setup for running ## Configuration -The Geth client is configured through environment variables in .env.mainnet or .env.sepolia. Key settings include: +The Geth client is configured through environment variables in `.env.mainnet` or `.env.sepolia`. Key settings include: ### Cache Settings @@ -22,37 +22,38 @@ Optimize cache allocation based on your available RAM: | Setting | Default | Description | |---------|---------|-------------| -| GETH_CACHE | 20480 | Total cache allocation in MB (20GB default) | -| GETH_CACHE_DATABASE | 20 | Percentage allocated to database cache | -| GETH_CACHE_GC | 12 | Percentage allocated to garbage collection | -| GETH_CACHE_SNAPSHOT | 24 | Percentage allocated to snapshot cache | -| GETH_CACHE_TRIE | 44 | Percentage allocated to trie cache | +| `GETH_CACHE` | 20480 | Total cache allocation in MB (20GB default) | +| `GETH_CACHE_DATABASE` | 20 | Percentage allocated to database cache | +| `GETH_CACHE_GC` | 12 | Percentage allocated to garbage collection | +| `GETH_CACHE_SNAPSHOT` | 24 | Percentage allocated to snapshot cache | +| `GETH_CACHE_TRIE` | 44 | Percentage allocated to trie cache | ### Sync Modes | Mode | Environment Variable | Description | |------|---------------------|-------------| -| Full Sync | OP_GETH_SYNCMODE=full | Download and verify all blocks (default) | -| Snap Sync | OP_GETH_SYNCMODE=snap | Faster initial sync (experimental) | +| Full Sync | `OP_GETH_SYNCMODE=full` | Download and verify all blocks (default) | +| Snap Sync | `OP_GETH_SYNCMODE=snap` | Faster initial sync (experimental) | ### Network Modes | Mode | Environment Variable | Description | |------|---------------------|-------------| -| Full | OP_GETH_GCMODE=full | Standard full node operation | -| Archive | OP_GETH_GCMODE=archive | Retain all historical states | +| Full | `OP_GETH_GCMODE=full` | Standard full node operation | +| Archive | `OP_GETH_GCMODE=archive` | Retain all historical states | ## Running the Node -The node follows the standard docker-compose workflow in the master README: +The node follows the standard `docker-compose` workflow in the master README: -\\\ash +```bash # Run Geth node (default when no CLIENT is specified) docker-compose up # Or explicitly specify Geth CLIENT=geth docker-compose up -\\\`n +``` + ## Exposed Ports | Port | Protocol | Description | @@ -67,25 +68,85 @@ CLIENT=geth docker-compose up ### EthStats Monitoring -Enable node monitoring by uncommenting in your .env file: +Enable node monitoring by uncommenting in your `.env` file: -\\\ash +```bash OP_GETH_ETH_STATS=nodename:secret@host:port -\\\`n +``` + ### Snap Sync (Experimental) For faster initial sync, enable snap sync by uncommenting the bootnode configuration and setting sync mode: -\\\ash +```bash OP_GETH_SYNCMODE=snap OP_GETH_BOOTNODES=enode://... -\\\`n +``` + > [!WARNING] > Snap sync is experimental and may lead to syncing issues. Use with caution in production environments. +### Peer Connectivity + +To improve peer connectivity, you can configure your external IP address in the `geth-entrypoint` script and ensure port 30303 is open on your firewall: + +```bash +HOST_IP="your.external.ip.address" +``` + +### State Scheme Configuration + +Configure the state storage scheme: + +```bash +OP_GETH_STATE_SCHEME=hash # or 'path' for path-based storage +``` + +### Unprotected Transactions + +Allow unprotected (non-EIP-155) transactions if needed: + +```bash +OP_GETH_ALLOW_UNPROTECTED_TXS=true +``` + +## Troubleshooting + +### Common Issues + +#### Slow Sync Performance + +If experiencing slow sync performance: +- Verify network bandwidth is sufficient (recommend 100+ Mbps) +- Consider using snap sync with bootnodes for initial sync +- Check L1 RPC rate limits and connection stability +- Ensure NVMe storage is properly configured + +#### High Memory Usage + +Geth may consume significant memory during operation: +- Adjust cache settings based on available RAM +- Reduce `GETH_CACHE` value if experiencing OOM errors +- Monitor with `--metrics` endpoint on port 6060 + +#### Peer Connection Issues + +If the node has difficulty finding peers: +- Ensure port 30303 (TCP/UDP) is open +- Configure `HOST_IP` with your external IP address +- Check that bootnodes are reachable + +#### Engine API Authentication Errors + +If seeing JWT authentication errors: +- Verify `OP_NODE_L2_ENGINE_AUTH` is correctly set +- Ensure the JWT secret matches between op-node and geth +- Check file permissions on the JWT secret file + ## Additional RPC Methods For a complete list of supported RPC methods, refer to: - [Standard Ethereum JSON-RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/) -- [Geth RPC Documentation](https://geth.ethereum.org/docs/rpc/server) \ No newline at end of file +- [Geth RPC Documentation](https://geth.ethereum.org/docs/rpc/server) +- [op-geth Documentation](https://github.com/ethereum-optimism/op-geth) \ No newline at end of file