holdge-rpc 0.2.1

package/README.md

@@ -0,0 +1,50 @@
+# @holdge/rpc
+
+Provider RPC **resiliente** pras apps Holdge (comcripto, grouppay, swap.holdge, agent.holdge).
+Uma camada só, em vez de cada app reimplementar fallback de RPC.
+
+```
+HTTP  →  Rabby (grátis)  →  públicos (grátis)  →  Alchemy (pago, último recurso)   (FailoverProvider estrito)
+WSS   →  Alchemy (se key)  →  público                                              (Rabby não tem WebSocket)
+```
+
+- **Ordenado por CUSTO:** Rabby e públicos são grátis e vêm primeiro; o **Alchemy (pago) só é tocado
+  quando TODOS os grátis falham**. Isso evita queimar CU à toa.
+- **Failover ESTRITO por-erro** (`FailoverProvider`, não o `FallbackProvider` do ethers). O FallbackProvider
+  é latência-based: ele raceia e prefere o mais *rápido* (Alchemy direto), queimando CU. O nosso só cai pro
+  próximo quando o atual **lança** (erro de transporte). Todas as ops passam por `_perform` → cobre o caminho
+  inteiro (getLogs, getBalance, call, estimateGas, broadcastTransaction, getTransactionCount…).
+
+## ⚠️ Rabby exige `node:https` (NÃO `fetch`)
+
+A `api.rabby.io` (server `dbkserver` atrás de CloudFront) **bloqueia (403) o `fetch` do Node (undici)** por
+fingerprint TLS/HTTP — **independe de User-Agent/headers**. O módulo **`https` nativo do Node passa (200)**.
+Verificado empiricamente: `curl` e `https` nativo → 200+JSON; `fetch`/undici → 403 página de bloqueio.
+
+Por isso o `RabbyProvider` usa `node:https` (com keep-alive), e **a lib é server-side (Node) apenas** — não
+roda em browser/edge runtime. (O GroupPay usa `fetch` e por isso está com Rabby OFFLINE; esta lib o supera.)
+
+> Nota: BSC no proxy Rabby costuma dar **429** (rate-limit) sob carga — o failover cobre caindo pro público.
+
+## Uso
+
+```ts
+import { httpProvider, wssProvider } from "@holdge/rpc";
+
+const http = httpProvider("polygon", { alchemyKey: process.env.ALCHEMY_API_KEY });
+await http.getBalance("0x...");          // Rabby → públicos → Alchemy (pago só em último caso)
+
+const ws = wssProvider("polygon", { alchemyKey: process.env.ALCHEMY_API_KEY });
+ws.on("block", (n) => console.log("novo bloco", n));   // Alchemy/público (Rabby não faz WSS)
+```
+
+Sem `alchemyKey` → roda **Rabby → públicos** ($0, sem provedor pago). `useRabby: false` desliga a Rabby.
+
+## Redes
+ethereum · polygon · base · arbitrum · bsc (extensível em `src/chains.ts` — Rabby cobre ~103 EVMs).
+
+## Instalação (consumidor)
+Use `--install-links` pra copiar (deduplica o `ethers` via peer dep, evita tipos duplicados):
+```bash
+npm install file:../holdge-rpc --install-links
+```

package/dist/chains.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Config das redes EVM suportadas. Rabby cobre ~103 EVMs via proxy; aqui ficam as que as apps Holdge usam.
+ * Pra adicionar rede: descubra o `rabbyId` (chain_id da Rabby, ex.: eth/bsc/matic/arb/base/op/avax) e o
+ * subdomínio Alchemy + RPC/WSS público. `publicHttp` é o último fallback; `publicWss` cobre o que a Rabby não faz.
+ */
+export type HoldgeChainKey = "ethereum" | "polygon" | "base" | "arbitrum" | "bsc";
+export type HoldgeChain = {
+    key: HoldgeChainKey;
+    chainId: number;
+    rabbyId: string;
+    alchemyNet: string;
+    publicHttp: string[];
+    publicWss: string;
+};
+export declare const HOLDGE_CHAINS: Record<HoldgeChainKey, HoldgeChain>;
+export declare const HOLDGE_CHAIN_KEYS: HoldgeChainKey[];

package/dist/chains.js

@@ -0,0 +1,23 @@
+export const HOLDGE_CHAINS = {
+    ethereum: {
+        key: "ethereum", chainId: 1, rabbyId: "eth", alchemyNet: "eth-mainnet",
+        publicHttp: ["https://ethereum-rpc.publicnode.com"], publicWss: "wss://ethereum-rpc.publicnode.com",
+    },
+    polygon: {
+        key: "polygon", chainId: 137, rabbyId: "matic", alchemyNet: "polygon-mainnet",
+        publicHttp: ["https://polygon-bor-rpc.publicnode.com", "https://polygon-rpc.com"], publicWss: "wss://polygon-bor-rpc.publicnode.com",
+    },
+    base: {
+        key: "base", chainId: 8453, rabbyId: "base", alchemyNet: "base-mainnet",
+        publicHttp: ["https://base-rpc.publicnode.com", "https://mainnet.base.org"], publicWss: "wss://base-rpc.publicnode.com",
+    },
+    arbitrum: {
+        key: "arbitrum", chainId: 42161, rabbyId: "arb", alchemyNet: "arb-mainnet",
+        publicHttp: ["https://arbitrum-one-rpc.publicnode.com", "https://arb1.arbitrum.io/rpc"], publicWss: "wss://arbitrum-one-rpc.publicnode.com",
+    },
+    bsc: {
+        key: "bsc", chainId: 56, rabbyId: "bsc", alchemyNet: "bnb-mainnet",
+        publicHttp: ["https://bsc-rpc.publicnode.com", "https://bsc-dataseed.binance.org"], publicWss: "wss://bsc-rpc.publicnode.com",
+    },
+};
+export const HOLDGE_CHAIN_KEYS = Object.keys(HOLDGE_CHAINS);

package/dist/failover.d.ts

@@ -0,0 +1,9 @@
+import { AbstractProvider, Network } from "ethers";
+import type { PerformActionRequest } from "ethers";
+export declare class FailoverProvider extends AbstractProvider {
+    #private;
+    constructor(subs: AbstractProvider[], network: Network);
+    _detectNetwork(): Promise<Network>;
+    _perform<T = unknown>(req: PerformActionRequest): Promise<T>;
+    destroy(): void;
+}

package/dist/failover.js

@@ -0,0 +1,77 @@
+import { AbstractProvider } from "ethers";
+/**
+ * Failover ESTRITO por-erro, ordenado por CUSTO — substitui o `FallbackProvider` do ethers.
+ *
+ * O `FallbackProvider` é latência-based: ele raceia os providers e penaliza (backoff) o mais lento,
+ * então acaba preferindo o mais RÁPIDO (tipicamente o Alchemy direto) em vez do mais BARATO (Rabby/público).
+ * Isso queima CU pago à toa. Aqui a regra é estrita por prioridade:
+ *
+ *   tenta subs[0]; só cai pro próximo se ele LANÇAR um erro de TRANSPORTE (403/429/timeout/socket).
+ *
+ * REGRAS (review adversarial do money-path):
+ *  - Erro SEMÂNTICO do nó (revert/CALL_EXCEPTION, nonce too low, fundos insuf., já conhecido…) é uma resposta
+ *    DEFINITIVA — re-lança IMEDIATAMENTE, sem failover. Tentar outro provider só mascararia o erro real
+ *    (todos responderiam igual) e desperdiçaria chamadas.
+ *  - `broadcastTransaction` é SINGLE-SHOT no provider primário (subs[0]): re-enviar a MESMA tx assinada noutro
+ *    provider é idempotente por hash, mas um "already known" lançado como erro faria um broadcast bem-sucedido
+ *    PARECER falha → o chamador re-tentaria (no deploy: colisão CREATE2; no swap: nonce já gasto). Em "speed",
+ *    subs[0] é o pago/confiável (Alchemy); deploy/swap re-tentam em ciclos futuros se ele estiver fora.
+ *
+ * Resultado: Rabby (grátis) → públicos (grátis) → Alchemy (pago) só quando os grátis dão erro de TRANSPORTE.
+ * Todas as ops passam por `_perform` (getLogs, getBalance, call, estimateGas, getTransactionCount…) → cobertas.
+ */
+// Códigos de erro ethers v6 que são resposta DEFINITIVA do nó — NÃO faz failover (re-lança).
+const NO_FAILOVER_CODES = new Set([
+    "CALL_EXCEPTION", // revert / execução falhou
+    "INSUFFICIENT_FUNDS",
+    "NONCE_EXPIRED", // "nonce too low" — a tx provavelmente já entrou
+    "REPLACEMENT_UNDERPRICED",
+    "TRANSACTION_REPLACED",
+    "UNCONFIGURED_NAME",
+    "ACTION_REJECTED",
+]);
+function shouldFailover(e) {
+    const code = e?.code;
+    // Sem code (ex.: Error cru do RabbyProvider em 429/timeout) = transporte → failover.
+    return !(code && NO_FAILOVER_CODES.has(code));
+}
+export class FailoverProvider extends AbstractProvider {
+    #subs;
+    #net;
+    constructor(subs, network) {
+        super(network);
+        this.#subs = subs;
+        this.#net = network;
+    }
+    // staticNetwork: nunca faz eth_chainId — todos os subs são da mesma rede, fixada na construção.
+    async _detectNetwork() {
+        return this.#net;
+    }
+    async _perform(req) {
+        // Escrita on-chain: single-shot no primário (ver doc acima) — nunca re-broadcast por failover.
+        if (req.method === "broadcastTransaction") {
+            return (await this.#subs[0]._perform(req));
+        }
+        let lastErr;
+        for (const s of this.#subs) {
+            try {
+                return (await s._perform(req));
+            }
+            catch (e) {
+                lastErr = e;
+                if (!shouldFailover(e))
+                    throw e; // erro semântico definitivo → re-lança já, sem tentar outro provider
+            }
+        }
+        throw lastErr;
+    }
+    destroy() {
+        for (const s of this.#subs) {
+            try {
+                s.destroy();
+            }
+            catch { /* ignore */ }
+        }
+        super.destroy();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { WebSocketProvider } from "ethers";
+import type { AbstractProvider } from "ethers";
+import { HOLDGE_CHAINS, HOLDGE_CHAIN_KEYS, type HoldgeChainKey } from "./chains.js";
+import { RabbyProvider } from "./rabby.js";
+import { FailoverProvider } from "./failover.js";
+export type HoldgeRpcProfile = "cost" | "speed";
+export type HoldgeRpcOptions = {
+    /** Se setado, Alchemy entra na cadeia (pago). Em "cost" é o ÚLTIMO recurso; em "speed" é o PRIMEIRO. */
+    alchemyKey?: string;
+    /** Rabby na cadeia HTTP. Default true. */
+    useRabby?: boolean;
+    /**
+     * "cost" (default): grátis primeiro — Rabby → públicos → Alchemy(pago último). Pra reads de ALTO VOLUME
+     *   (detecção/scan, polling de saldo) onde queimar CU pago seria caro.
+     * "speed": pago/confiável primeiro — Alchemy → Rabby (SEM públicos por default). Pra ops RARAS, urgentes e
+     *   money-critical (deploy de contrato, swap de emergência) onde ms e correção importam mais que custo, e um
+     *   RPC público flaky (nonce/recibo stale) seria perigoso. Deploys/swaps são poucos → custo desprezível.
+     */
+    profile?: HoldgeRpcProfile;
+    /** Inclui os RPCs públicos na cadeia. Default: true em "cost", false em "speed". */
+    includePublic?: boolean;
+};
+/**
+ * Provider HTTP resiliente com `FailoverProvider` (estrito por-erro), NÃO o `FallbackProvider` do ethers
+ * (latência-based, racea e prefere o mais rápido = Alchemy pago). Só cai pro próximo quando o atual LANÇA.
+ *
+ * Dois perfis (ver `HoldgeRpcOptions.profile`):
+ *   - "cost"  → Rabby (grátis) → públicos (grátis) → Alchemy (pago, último). Reads de alto volume.
+ *   - "speed" → Alchemy (pago/confiável) → Rabby → (públicos só se includePublic). Deploy/swap urgente.
+ */
+export declare function httpProvider(key: HoldgeChainKey, opts?: HoldgeRpcOptions): AbstractProvider;
+/**
+ * Provider WSS (newHeads / subscriptions): Alchemy (se `alchemyKey`) senão público.
+ * Rabby NÃO tem WebSocket — pra detecção on-chain ao vivo use isto + `httpProvider` pra getLogs.
+ */
+export declare function wssProvider(key: HoldgeChainKey, opts?: HoldgeRpcOptions): WebSocketProvider;
+export { HOLDGE_CHAINS, HOLDGE_CHAIN_KEYS, RabbyProvider, FailoverProvider };
+export type { HoldgeChainKey, HoldgeChain } from "./chains.js";

package/dist/index.js

@@ -0,0 +1,45 @@
+import { JsonRpcProvider, WebSocketProvider, Network } from "ethers";
+import { HOLDGE_CHAINS, HOLDGE_CHAIN_KEYS } from "./chains.js";
+import { RabbyProvider } from "./rabby.js";
+import { FailoverProvider } from "./failover.js";
+/**
+ * Provider HTTP resiliente com `FailoverProvider` (estrito por-erro), NÃO o `FallbackProvider` do ethers
+ * (latência-based, racea e prefere o mais rápido = Alchemy pago). Só cai pro próximo quando o atual LANÇA.
+ *
+ * Dois perfis (ver `HoldgeRpcOptions.profile`):
+ *   - "cost"  → Rabby (grátis) → públicos (grátis) → Alchemy (pago, último). Reads de alto volume.
+ *   - "speed" → Alchemy (pago/confiável) → Rabby → (públicos só se includePublic). Deploy/swap urgente.
+ */
+export function httpProvider(key, opts = {}) {
+    const c = HOLDGE_CHAINS[key];
+    const useRabby = opts.useRabby !== false;
+    const profile = opts.profile ?? "cost";
+    // públicos: default true em "cost"; em "speed" default false (pago/Rabby bastam) — MAS se NÃO houver Alchemy,
+    // inclui os públicos mesmo em "speed", pra não degradar pra single-provider sem failover (resiliência > pureza).
+    const includePublic = opts.includePublic ?? (profile === "cost" || !opts.alchemyKey);
+    const rabby = useRabby ? new RabbyProvider(c.rabbyId, c.chainId) : null;
+    const alchemy = opts.alchemyKey
+        ? new JsonRpcProvider(`https://${c.alchemyNet}.g.alchemy.com/v2/${opts.alchemyKey}`, c.chainId, { batchMaxCount: 1, staticNetwork: true })
+        : null;
+    const publics = includePublic
+        ? c.publicHttp.map((url) => new JsonRpcProvider(url, c.chainId, { batchMaxCount: 1, staticNetwork: true }))
+        : [];
+    // "speed": pago/confiável primeiro. "cost": grátis primeiro, pago por último.
+    const ordered = profile === "speed" ? [alchemy, rabby, ...publics] : [rabby, ...publics, alchemy];
+    const subs = ordered.filter((p) => p !== null);
+    if (subs.length === 0)
+        throw new Error(`holdge-rpc: sem provider HTTP p/ ${key} (profile=${profile})`);
+    if (subs.length === 1)
+        return subs[0]; // 1 só → sem overhead do failover
+    return new FailoverProvider(subs, Network.from(c.chainId));
+}
+/**
+ * Provider WSS (newHeads / subscriptions): Alchemy (se `alchemyKey`) senão público.
+ * Rabby NÃO tem WebSocket — pra detecção on-chain ao vivo use isto + `httpProvider` pra getLogs.
+ */
+export function wssProvider(key, opts = {}) {
+    const c = HOLDGE_CHAINS[key];
+    const url = opts.alchemyKey ? `wss://${c.alchemyNet}.g.alchemy.com/v2/${opts.alchemyKey}` : c.publicWss;
+    return new WebSocketProvider(url, c.chainId);
+}
+export { HOLDGE_CHAINS, HOLDGE_CHAIN_KEYS, RabbyProvider, FailoverProvider };

package/dist/rabby.d.ts

@@ -0,0 +1,7 @@
+import { JsonRpcProvider } from "ethers";
+import type { JsonRpcPayload, JsonRpcResult } from "ethers";
+export declare class RabbyProvider extends JsonRpcProvider {
+    readonly rabbyId: string;
+    constructor(rabbyId: string, chainId: number);
+    _send(payload: JsonRpcPayload | JsonRpcPayload[]): Promise<JsonRpcResult[]>;
+}

package/dist/rabby.js

@@ -0,0 +1,70 @@
+import { JsonRpcProvider, Network } from "ethers";
+import https from "node:https";
+/**
+ * Provider ethers v6 que fala com a API Rabby (proxy de RPC, cobre ~103 EVMs incl. ETH/Polygon/Base/Arbitrum).
+ *
+ * A Rabby NÃO é um endpoint JSON-RPC padrão: o `chain_id` vai no CORPO (não na URL). Por isso sobrescrevemos
+ * `_send` pra montar `{ chain_id, method, params, jsonrpc, id }` em cada chamada.
+ *
+ * IMPORTANTE — POR QUE `node:https` E NÃO `fetch`:
+ *   O WAF da Rabby (server `dbkserver` atrás de CloudFront) BLOQUEIA (403) o `fetch` do Node (undici) por
+ *   fingerprint TLS/HTTP — independe de User-Agent/headers. O módulo `https` nativo do Node passa (200).
+ *   Verificado empiricamente: `curl` e `https` nativo → 200+JSON; `fetch`/undici → 403 página de bloqueio.
+ *   (O GroupPay usa `fetch` e por isso está com Rabby OFFLINE — este provider o supera.)
+ *   CONSEQUÊNCIA: este provider é **server-side (Node) apenas** — não roda em browser/edge runtime.
+ *
+ * `batchMaxCount: 1` desliga o batch (a Rabby aceita 1 chamada por POST). `staticNetwork` evita um
+ * eth_chainId na construção. NÃO suporta WebSocket (use o wssProvider pra newHeads/subscriptions).
+ */
+const RABBY_URL = "https://api.rabby.io/v1/wallet/eth_rpc";
+const RABBY_HOST = "api.rabby.io";
+const RABBY_PATH = "/v1/wallet/eth_rpc";
+const TIMEOUT_MS = 15_000;
+// keep-alive: o watcher faz muitas chamadas; reusar a conexão TLS evita handshake por request.
+const agent = new https.Agent({ keepAlive: true, maxSockets: 8 });
+function rabbyPost(bodyObj) {
+    const body = JSON.stringify(bodyObj);
+    return new Promise((resolve, reject) => {
+        const req = https.request({ host: RABBY_HOST, path: RABBY_PATH, method: "POST", agent, timeout: TIMEOUT_MS,
+            headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body) } }, (res) => {
+            let buf = "";
+            res.on("data", (c) => (buf += c));
+            res.on("end", () => {
+                if (res.statusCode !== 200)
+                    return resolve({ status: res.statusCode ?? 0, json: null });
+                try {
+                    resolve({ status: 200, json: JSON.parse(buf) });
+                }
+                catch {
+                    reject(new Error(`Rabby resposta inválida (${RABBY_HOST})`));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.on("timeout", () => req.destroy(new Error("Rabby timeout")));
+        req.write(body);
+        req.end();
+    });
+}
+export class RabbyProvider extends JsonRpcProvider {
+    rabbyId;
+    constructor(rabbyId, chainId) {
+        super(RABBY_URL, Network.from(chainId), { batchMaxCount: 1, staticNetwork: true });
+        this.rabbyId = rabbyId;
+    }
+    // ethers tipa o retorno como JsonRpcResult[], mas em runtime aceita {id,error} (ele checa .error e lança).
+    async _send(payload) {
+        const reqs = Array.isArray(payload) ? payload : [payload];
+        const out = [];
+        for (const p of reqs) {
+            const { status, json } = await rabbyPost({ chain_id: this.rabbyId, method: p.method, params: p.params ?? [], jsonrpc: "2.0", id: p.id });
+            if (status !== 200 || !json)
+                throw new Error(`Rabby proxy HTTP ${status} (${this.rabbyId})`);
+            if (json.error)
+                out.push({ id: p.id, error: json.error });
+            else
+                out.push({ id: p.id, result: json.result });
+        }
+        return out;
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "holdge-rpc",
+  "version": "0.2.1",
+  "description": "RPC provider resiliente para apps Holdge (server-side): Rabby via node:https → públicos → Alchemy. Failover estrito por-erro + perfis cost/speed. HTTP + WSS.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "ethers": "^6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "ethers": "^6.13.4",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samyrwendel/holdge-rpc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/samyrwendel/holdge-rpc/issues"
+  },
+  "homepage": "https://github.com/samyrwendel/holdge-rpc#readme"
+}