1  # Adding New Chains to eth-rpc-proxy
  2  
  3  This guide explains how to add new blockchain networks to the eth-rpc-proxy system, how to test them, and how to verify they're working correctly.
  4  
  5  ## Overview
  6  
  7  The eth-rpc-proxy system supports multiple blockchain networks and provides fallback functionality between different RPC providers. When adding a new chain, you need to:
  8  
  9  1. Update the `generate_providers.py` script with the new chain information
 10  2. Generate the updated providers configuration files
 11  3. Test the proxy with the new chains
 12  
 13  ```mermaid
 14  flowchart TD
 15      A[Add endpoints to generate_providers.py] --> B[Generate default_providers.json and reference_providers.json]
 16      B --> C[Run proxy locally and test with Curl]
 17  ```
 18  
 19  ## Step 1: Update the `generate_providers.py` Script
 20  
 21  The `generate_providers.py` script contains a `NETWORK_DATA` array that defines all supported chains. To add a new chain:
 22  
 23  1. Open `rpc-health-checker/generate_providers.py`
 24  2. Add new entries to the `NETWORK_DATA` array for your chain (both mainnet and testnet if applicable)
 25  3. The script will automatically generate the choices for both `--chains` and `--networks` parameters from the `NETWORK_DATA` array, and will update the help text for `--providers` to include all supported provider types
 26  
 27  Example of adding a new chain:
 28  
 29  ```python
 30  NETWORK_DATA = [
 31      # ... existing chains ...
 32      {
 33          "chain": "newchain",
 34          "network": "mainnet",
 35          "chainId": 12345,  # Replace with actual chain ID
 36          "providers": {
 37              INFURA: "https://newchain-mainnet.infura.io/v3/",
 38              GROVE: "https://newchain.rpc.grove.city/v1/",
 39              NODEFLEET: "https://newchain-mainnet.alphafleet.io/",
 40              ALCHEMY: "https://newchain-mainnet.g.alchemy.com/v2/"
 41          }
 42      },
 43      {
 44          "chain": "newchain",
 45          "network": "sepolia",  # Or other testnet
 46          "chainId": 54321,  # Replace with actual testnet chain ID
 47          "providers": {
 48              INFURA: "https://newchain-sepolia.infura.io/v3/",
 49              GROVE: "https://newchain-sepolia-testnet.rpc.grove.city/v1/",
 50              NODEFLEET: "https://newchain-sepolia.alphafleet.io/",
 51              ALCHEMY: "https://newchain-sepolia.g.alchemy.com/v2/"
 52          }
 53      },
 54  ]
 55  
 56  ```
 57  
 58  ## Step 2: Generate configuration files
 59  
 60  Here is the commands to generate the provider configuration files. Update it to include your new chain:
 61  
 62  ```bash
 63  # default_providers.json
 64  python3 rpc-health-checker/generate_providers.py \
 65     --providers grove:GROVE_TOKEN \
 66                 alchemy:ALCHEMY_TOKEN \
 67                 nodefleet:STATUS_USER:STATUS_PASSWORD \
 68                 infura:INFURA_TOKEN \
 69                 status_network \
 70     --networks mainnet sepolia \
 71     --chains ethereum optimism arbitrum base status NEW_CHAIN_HERE \
 72     --output secrets/default_providers.json
 73  
 74  
 75  # reference_providers.json 
 76  python3 rpc-health-checker/generate_providers.py \
 77     --single-provider \
 78     --providers infura:INFURA_REF_TOKEN status_network \
 79     --networks mainnet sepolia \
 80     --chains ethereum optimism arbitrum base status NEW_CHAIN_HERE \
 81     --output secrets/reference_providers.json
 82  ```
 83  
 84  Simply add your new chain name to the `--chains` parameter in both commands. If you're adding a new network type (other than mainnet or sepolia), add it to the `--networks` parameter as well.
 85  
 86  
 87  This will create or update the following files:
 88  - `secrets/default_providers.json`: Contains the multi-provider configuration
 89  - `secrets/reference_providers.json`: Contains the single-provider configuration
 90  
 91  Make sure that both filesa above contain entries for the new chains.
 92  
 93  ## Step 3: Testing with Docker Compose
 94  
 95  ### Starting the Proxy for Local Testing
 96  
 97  For local testing, use the local Docker Compose configuration:
 98  
 99  ```bash
100  docker compose -f docker-compose-local.yml up -d --build
101  ```
102  
103  This will build and start all the necessary services for local testing.
104  
105  ### Setting Up Authentication
106  
107  Before testing, you need to generate a password in the `secrets/.htpasswd` file:
108  
109  ```bash
110  # Install htpasswd if not already installed
111  # On Debian/Ubuntu: apt-get install apache2-utils
112  # On macOS: brew install httpd
113  
114  # Generate password file
115  htpasswd -c secrets/.htpasswd your_username
116  ```
117  
118  You'll be prompted to enter and confirm a password. This will be used for authenticating your requests to the proxy.
119  
120  ### Making Curl Requests to Test the Proxy
121  
122  You can test the proxy by making curl requests to localhost. Here are some examples:
123  
124  #### 1. Get the Block Number for a Chain
125  
126  ```bash
127  curl -X POST http://localhost:8080/NEW_CHAIN/mainnet \
128    -H "Content-Type: application/json" \
129    -u your_username:your_password \
130    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
131  ```
132  
133  Make sure to replace `your_username` and `your_password` with the credentials you set up in the `.htpasswd` file.
134