|
| 1 | +# V2 Bot JSON-RPC Provider Setup |
| 2 | + |
| 3 | +With v2 detection bots, developers can scan any EVM-compatible chain by bringing their own RPC endpoints. This guide discusses a few options for setting up your bot's RPC provider for local development and production. |
| 4 | + |
| 5 | +## Public RPC URLs |
| 6 | + |
| 7 | +The simplest way to get started is to use a public RPC endpoint for your specific chain. These endpoints are free to use, but typically come with rate limits to prevent misuse. Depending on the rate limits, your bot's performance will vary. Unless you are certain that your bot will stay within the set limits, we don't recommend using public RPC URLs in production. However, you may find these convenient for local development. |
| 8 | + |
| 9 | +## Private RPC URLs |
| 10 | + |
| 11 | +Another common way to communicate with RPC providers is to create a private RPC endpoint which typically contains some sort of secret API key within the URL itself. These are usually offered through a freemium payment model with more generous rate limits. However, hardcoding the RPC URL (and secret API key) within the bot itself is a security issue because the bot Docker images are stored in a public repository which anyone can view. For this reason, private RPC URLs are better suited for local development but not for production. |
| 12 | + |
| 13 | +## JWT-Authenticated RPC URLs |
| 14 | + |
| 15 | +Certain RPC providers have the option to create a JWT-authenticated RPC endpoint that can **_only be accessed by scan nodes that are running your bot_**. Setting up this kind of RPC endpoint is easy and requires registering the Forta public key with the provider. Suggested providers that support this kind of authentication mechanism include (but are not limited to) [Alchemy](https://www.alchemy.com/), [dRPC](https://drpc.org/) and [Infura](https://www.infura.io/). The main benefit of using such a RPC endpoint is that you can hardcode the RPC URL into the bot without giving away public access to anyone who can view the bot's Docker image. |
| 16 | + |
| 17 | +### Registering the Forta public key |
| 18 | + |
| 19 | +For example, to [create a JWT-authenticated RPC URL on Alchemy](https://docs.alchemy.com/docs/how-to-use-jwts-for-api-requests) you would do the following: |
| 20 | + |
| 21 | +1. Go to the [Alchemy JWT Public Keys dashboard](https://dashboard.alchemy.com/settings/jwt-public-keys) |
| 22 | +2. Click "Import Public Key" |
| 23 | +3. Enter a name for this new key |
| 24 | +4. Select the App ID (i.e. RPC endpoint) you want to associate with the public key |
| 25 | +5. Copy and paste the Forta public key (as seen below) |
| 26 | +6. Click "Create" to register the key |
| 27 | +7. Click on the created key's name to expand it and view the key ID e.g. `67694d31-0d90-47a4-8241-0a8546958512a` |
| 28 | +8. Use the key ID inside your bot e.g. |
| 29 | + |
| 30 | +=== "Typescript/Javascript" |
| 31 | + |
| 32 | + ``` Typescript |
| 33 | + scanEthereum({ |
| 34 | + rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2', |
| 35 | + rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a', |
| 36 | + ... |
| 37 | + }) |
| 38 | + ``` |
| 39 | + |
| 40 | +=== "Python" |
| 41 | + |
| 42 | + ``` Python |
| 43 | + scan_ethereum({ |
| 44 | + 'rpc_url': 'https://eth-mainnet.g.alchemy.com/v2', |
| 45 | + 'rpc_key_id': '67694d31-0d90-47a4-8241-0a8546958512a', |
| 46 | + ... |
| 47 | + }) |
| 48 | + ``` |
| 49 | + |
| 50 | +### Forta public key |
| 51 | + |
| 52 | +``` |
| 53 | +-----BEGIN PUBLIC KEY----- |
| 54 | +MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0hsWiVoSFlrUsYPDRPjJ |
| 55 | +n9zghdlcVREmfSZgzdr5u//Y7Cv97waAhSB3xN8qjst5Uy/rD7fFD/6GN6FHMMg+ |
| 56 | +fu0f/pLPJSby/mu+YBCg1LtsAXlLub8LaY20xUb4cBNHy++SzI1cQOjkqH9/vHO7 |
| 57 | +V2aS3tc6+OS62Dy6NstB4ITskLmZdA8fJdye2LWS/DS95K37DCfIgFqxktFDovjW |
| 58 | +oCbJPTL4A/0Bs7tCEjUb4X7Z5v065W7Ly8W3W0m3oM09Bwr018WE+EzsSthE+E98 |
| 59 | +nGpOUiStgoaKlDMRY+zrcjOTCHPzLn7C5aUOsyGuRJF+vy37ouq4YZSlbg87FcGw |
| 60 | +XuLONya3ZDR0caDMFOtD+fuDmFMSKk52ua+afNTygn5jDAGr+RNWcfGx0OeSbwO0 |
| 61 | +5zmQ1FkIiqkoScunGFE74hYLcdCFx8CiwZzhKiwx2wRvgXnjzkZVCYZ6RwsyWADw |
| 62 | +MqHcc+S/+hYLUg0UNNHVSD+aJDjzneOc/DKL2h7Y3cdjX7tfJPobOaguYF+JdEzj |
| 63 | +VjL3a0dfT/2BHyzlpPBwCmSOZQwUqyzJV05rQfoVeqyZJhp6e1hTwTWi4Fff7TH5 |
| 64 | +/jtZ8cixEzCblehA3dDD5XEvaWDEG+n0Qk6ZeH016c2dkrkLMQoHR+p+p3KL6PoW |
| 65 | +0xyzcLXL4r5ALWLwpeqSaasCAwEAAQ== |
| 66 | +-----END PUBLIC KEY----- |
| 67 | +``` |
| 68 | + |
| 69 | +## Forta RPC Cache |
| 70 | + |
| 71 | +When running on scan nodes in **_production_**, v2 detection bots also have access to a RPC cache (courtesy of the Forta Network). The cache provides access to basic blockchain data including blocks, transactions and logs. The cache is _short-lived_ and only stores blockchain data for the **past 5 minutes for certain chains**. Currently the following 8 chains are supported by the cache: |
| 72 | + |
| 73 | +- Ethereum (includes trace data) |
| 74 | +- Polygon |
| 75 | +- Base |
| 76 | +- BSC |
| 77 | +- Avalanche |
| 78 | +- Arbitrum |
| 79 | +- Fantom (includes trace data) |
| 80 | +- Optimism |
| 81 | + |
| 82 | +## Local RPC URLs |
| 83 | + |
| 84 | +Note that JWT-authenticated RPC URLs can only work inside of a scan node (i.e. only in production). When developing locally, these URLs will not work as they require a scan node environment. To work around this when developing locally, you can specify a local RPC URL in your bot that will be used **_only when running locally_**. This way you can use public/private RPC URLs locally without exposing them to the world. For example, you would put the public/private URLs inside your `forta.config.json` like so: |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + ... |
| 89 | + "localRpcUrls": { |
| 90 | + "1": "https://cloudflare-eth.com/", |
| 91 | + "137": "https://polygon-rpc.com" |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +and then use them inside your bot like this: |
| 97 | + |
| 98 | +=== "Typescript/Javascript" |
| 99 | + |
| 100 | + ``` Typescript |
| 101 | + scanEthereum({ |
| 102 | + localRpcUrl: '1', |
| 103 | + rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2', // only used in prod |
| 104 | + rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a', // only used in prod |
| 105 | + ... |
| 106 | + }) |
| 107 | + ``` |
| 108 | + |
| 109 | +=== "Python" |
| 110 | + |
| 111 | + ``` Python |
| 112 | + scan_polygon({ |
| 113 | + 'local_rpc_url': '137', |
| 114 | + 'rpc_url': 'https://polygon-mainnet.g.alchemy.com/v2', # only used in prod |
| 115 | + 'rpc_key_id': '89694d31-0c50-58b4-8241-0e0543959513b', # only used in prod |
| 116 | + ... |
| 117 | + }) |
| 118 | + ``` |
0 commit comments