@lidofinance/api-rpc-proxy 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,62 @@
1
- # Temporary Holding Version
1
+ # @lidofinance/api-rpc-proxy
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Building blocks for a Fastify JSON-RPC proxy: method/address allowlisting, per-IP rate limiting,
4
+ chain health probing and prom-client metrics. Extracted from
5
+ [lido-consolidation-ui](https://github.com/lidofinance/lido-consolidation-ui)'s `server/`.
6
+
7
+ ## Installation
8
+
9
+ `yarn add @lidofinance/api-rpc-proxy`
10
+
11
+ ## Getting started
12
+
13
+ `registerRpcProxyRoutes` wires up `/health`, `/metrics` and `/rpc` on a Fastify instance. Everything
14
+ app-specific — allowed contract addresses, chain ids, RPC provider URLs — is passed in by the caller;
15
+ the package has no opinion on where those come from.
16
+
17
+ ```ts
18
+ import Fastify from 'fastify'
19
+ import { createRpcProxyMetrics, registerRpcProxyRoutes } from '@lidofinance/api-rpc-proxy'
20
+
21
+ const metrics = createRpcProxyMetrics({ prefix: 'my_app_' })
22
+
23
+ const app = Fastify()
24
+
25
+ registerRpcProxyRoutes(app, {
26
+ providers: { '1': ['https://mainnet.example/rpc'] },
27
+ defaultChain: '1',
28
+ fetchRPC: metrics.fetchRPC,
29
+ metrics,
30
+ validation: {
31
+ allowedRPCMethods: ['eth_call', 'eth_getLogs', 'eth_chainId'],
32
+ allowedCallAddresses: { 1: ['0x...'] },
33
+ allowedLogsAddresses: { 1: ['0x...'] },
34
+ // the method list and both address lists are required; each can be 'any' to allow every
35
+ // method / address deliberately (e.g. user-deployed contracts)
36
+ blockEmptyAddressGetLogs: true,
37
+ maxBatchCount: 20,
38
+ maxResponseSize: 1_000_000,
39
+ },
40
+ rateLimit: { max: 300, windowSec: 60 },
41
+ // optional: how long (ms) a /health probe result is reused, so repeated GETs do not each call
42
+ // every provider. 5 000 by default, 0 probes on every request.
43
+ healthCacheMs: 5_000,
44
+ // optional: per-provider time limit (ms) for the provider to start answering; a provider that
45
+ // exceeds it counts as failed and the next URL is tried. 10 000 by default, 0 turns it off.
46
+ upstreamTimeoutMs: 10_000,
47
+ })
48
+
49
+ await app.listen({ port: 3002 })
50
+ ```
51
+
52
+ ## What's included
53
+
54
+ - `rpcFactory` — validates and forwards JSON-RPC requests, streaming the upstream response back.
55
+ - `createRateLimitHook` — fixed-window per-IP rate limiter as a Fastify preHandler.
56
+ - `probeChains` — probes every configured RPC URL per chain, healthy if at least one responds.
57
+ - `createRpcProxyMetrics` — prom-client counters/histograms/gauge for requests, blocks and chain
58
+ reachability, plus a metrics-tracked `fetchRPC` (via `@lidofinance/api-rpc`).
59
+ - `registerRpcProxyRoutes` — wires the above into `/health`, `/metrics`, `/rpc` on a Fastify app.
60
+
61
+ Anything app-specific — which contracts are callable, CSP reporting, the actual `fastify()` bootstrap —
62
+ stays in the consuming app.