diff --git a/geth/README.md b/geth/README.md new file mode 100644 index 00000000..c0d21d85 --- /dev/null +++ b/geth/README.md @@ -0,0 +1,152 @@ +# 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: + +```bash +# Run Geth node (default when no CLIENT is specified) +docker-compose up + +# Or explicitly specify Geth +CLIENT=geth docker-compose up +``` + +## 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_GETH_ETH_STATS=nodename:secret@host:port +``` + +### Snap Sync (Experimental) + +For faster initial sync, enable snap sync by uncommenting the bootnode configuration and setting sync mode: + +```bash +OP_GETH_SYNCMODE=snap +OP_GETH_BOOTNODES=enode://... +``` + +> [!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) +- [op-geth Documentation](https://github.com/ethereum-optimism/op-geth) \ No newline at end of file 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