@1delta/providers 0.0.52 → 0.0.54

package/README.md

@@ -0,0 +1,188 @@
+# @1delta/providers
+
+Resilient EVM provider infrastructure: chain mapping, RPC management, transport creation, and batched multicall with automatic retry/rotation.
+
+## Module Reference
+
+| Module | README | Purpose |
+|---|---|---|
+| `chains/` | [chains/README.md](src/chains/README.md) | Chain enum → viem `Chain` mapping, custom chain definitions |
+| `client/` | [client/README.md](src/client/README.md) | `PublicClient` creation with RPC fallback/rotation |
+| `rpc/` | [rpc/README.md](src/rpc/README.md) | Default RPC URL pools per chain (`LIST_OVERRIDES`) |
+| `transport/` | [transport/README.md](src/transport/README.md) | HTTP/WebSocket viem transport factory |
+| `multicall/` | [multicall/README.md](src/multicall/README.md) | Batched multicall with retry, RPC rotation, revert isolation |
+| `utils/` | [utils/README.md](src/utils/README.md) | Shared constants and helpers |
+
+Everything is re-exported from the package root via `src/index.ts → src/evm.ts`.
+
+---
+
+## Building Efficient Batched Multicalls
+
+The core pattern used across this repo is: **build a flat call array from heterogeneous sources, fire one multicall, then walk the results array using tracked offsets.** This minimizes RPC round-trips by packing as many reads as possible into a single `multicall3` invocation.
+
+### 1. Define the Call Shape
+
+Each call is a plain object:
+
+```ts
+interface Call {
+  address: string       // target contract
+  name: string          // function name (must match ABI)
+  params?: any[]        // function arguments (alias: args)
+}
+```
+
+### 2. Build Calls — Track Lengths per Source
+
+The key insight is to **concatenate calls from different protocols into one flat array** while recording how many calls each source contributed, so you can slice the results later.
+
+From [`margin-fetcher/src/flash-liquidity/fetchLiquidity.ts`](../margin-fetcher/src/flash-liquidity/fetchLiquidity.ts):
+
+```ts
+let callLengths: { [protocol: string]: number } = {}
+let aaveCalls: Call[] = []
+
+// Aave forks: 2 calls per asset (balanceOf + getConfiguration) + 1 premium call
+aaveProtocols.forEach((aaveFork) => {
+  const underlyingsAndATokens = Object.entries(
+    getAaveStyleProtocolTokenMap(chain, aaveFork),
+  )
+  const pool = getAaveTypePoolAddress(chain, aaveFork)
+
+  const tokenCalls = underlyingsAndATokens.flatMap(
+    ([underlying, tokens]: [string, any]) => [
+      { name: 'balanceOf', address: underlying, params: [tokens.aToken] },
+      { name: 'getConfiguration', address: pool, params: [underlying] },
+    ],
+  )
+
+  // Track length so we know how many results belong to this fork
+  callLengths[aaveFork] = tokenCalls.length + 1
+
+  aaveCalls.push(...tokenCalls, {
+    name: 'FLASHLOAN_PREMIUM_TOTAL',
+    address: pool,
+  })
+})
+```
+
+For uniform sources (same call per asset), a helper keeps it concise:
+
+```ts
+const buildBalanceCalls = (
+  forks: { pool: string; address: string }[],
+): Call[] => {
+  const result: Call[] = []
+  for (const fork of forks) {
+    callLengths[fork.pool] = unifiedAssets.length
+    for (const address of unifiedAssets) {
+      result.push(
+        address === zeroAddress
+          ? { name: 'getEthBalance', address: MULTICALL_ADDRESS[chain], params: [fork.address] }
+          : { name: 'balanceOf', address, params: [fork.address] },
+      )
+    }
+  }
+  return result
+}
+```
+
+### 3. Concatenate and Fire
+
+Merge all sub-arrays into one flat call list and execute a single multicall:
+
+```ts
+const calls = [
+  ...aaveCalls,
+  ...balancerV2Calls,
+  ...morphoCalls,
+  ...balancerV3Calls,
+  ...uniswapV4Calls,
+]
+
+const rawResults = await multicallRetryUniversal({
+  chain,
+  calls,
+  abi: FlashAbi,          // single ABI covering all function signatures
+  batchSize: 4096,
+  allowFailure: true,     // failed calls return '0x' instead of throwing
+})
+```
+
+**ABI tip:** When all calls use functions from the same ABI (or a merged superset ABI), pass a single ABI. When calls target different contracts with different ABIs, pass an array of ABIs (one per call) — see [multicall/README.md](src/multicall/README.md).
+
+### 4. Unwrap Results with Offset Walking
+
+The results array is **positionally aligned** with the calls array. Use the tracked lengths to slice each source's chunk:
+
+```ts
+let currentOffset = 0
+
+aaveProtocols.forEach((aave) => {
+  const callLen = aaveAssets[aave].length * 2 + 1    // 2 calls per asset + 1 premium
+
+  // Slice this fork's results
+  const data = rawResults.slice(currentOffset, currentOffset + callLen)
+  currentOffset += callLen                            // advance the cursor
+
+  // Last result is the premium call
+  const fee = data[callLen - 1]
+  if (typeof fee !== 'bigint') return                 // skip fork if premium call failed
+
+  // Walk interleaved results: [balance, config, balance, config, ...]
+  aaveAssets[aave].forEach((asset, i) => {
+    const rawAmount = data[2 * i]       // balanceOf result
+    const config = data[2 * i + 1]      // getConfiguration result
+
+    if (typeof rawAmount !== 'bigint' || typeof config !== 'bigint') return
+    // ... process asset
+  })
+})
+
+// Uniform sources are simpler — one result per asset
+balancerV2s.forEach((balancer) => {
+  const data = rawResults.slice(currentOffset, currentOffset + unifiedAssets.length)
+  currentOffset += unifiedAssets.length
+
+  unifiedAssets.forEach((asset, i) => {
+    const rawAmount = data[i]
+    if (typeof rawAmount === 'bigint' && rawAmount > 0n) {
+      // ... process asset
+    }
+  })
+})
+```
+
+### 5. Handling Failed Calls
+
+With `allowFailure: true`, failed calls return `'0x'`. Guard with type checks:
+
+```ts
+// For bigint returns (balances, configs, etc.)
+const isValidResult = (v: any): v is bigint => typeof v === 'bigint'
+
+if (!isValidResult(rawAmount)) return  // skip this entry
+```
+
+---
+
+## Quick Reference
+
+```ts
+import { multicallRetryUniversal } from '@1delta/providers'
+
+// Minimal call
+const results = await multicallRetryUniversal({
+  chain: '8453',
+  calls: [
+    { address: tokenAddr, name: 'balanceOf', params: [account] },
+    { address: tokenAddr, name: 'decimals' },
+  ],
+  abi: ERC20_ABI,
+})
+
+const [balance, decimals] = results
+```
+
+For custom RPCs or factory usage, see [multicall/README.md](src/multicall/README.md) and [client/README.md](src/client/README.md).

package/dist/index.js

@@ -25099,10 +25099,13 @@ var LIST_OVERRIDES = {
     "https://avax-rpc.gateway.pokt.network"
   ],
   [import_chain_registry2.Chain.CELO_MAINNET]: [
+    "https://celo-mainnet.gateway.tatum.io",
+    "https://celo-json-rpc.stakely.io",
     "https://forno.celo.org",
     "https://1rpc.io/celo",
     "https://celo.drpc.org",
-    "https://celo-rpc.publicnode.com"
+    "https://celo-rpc.publicnode.com",
+    "https://rpc.ankr.com/celo"
   ],
   [import_chain_registry2.Chain.BLAST]: [
     "https://rpc.blast.io",
@@ -25198,6 +25201,10 @@ var LIST_OVERRIDES = {
     "https://tac.therpc.io",
     "https://ws.rpc.tac.build"
   ],
+  [import_chain_registry2.Chain.BOTANIX_MAINNET]: [
+    "https://rpc.botanixlabs.com",
+    "https://rpc.ankr.com/botanix_mainnet"
+  ],
   [import_chain_registry2.Chain.UNICHAIN]: [
     "https://mainnet.unichain.org",
     "https://rpc.sentio.xyz/unichain-mainnet",
@@ -25394,14 +25401,14 @@ function isHttpError(e) {
       const status = current.status;
       if (status && status >= 400) return true;
       const details = current.details ?? "";
-      const message = current.message ?? "";
+      const message = current.message ?? current.shortMessage ?? "";
       const combined = `${message} ${details}`;
       if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true;
       current = current.cause ?? null;
     }
   }
   if (e instanceof Error) {
-    const combined = `${e.message ?? ""} ${e.details ?? ""}`;
+    const combined = `${e.message ?? e.shortMessage ?? ""} ${e.details ?? ""}`;
     if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true;
   }
   return false;
@@ -25444,9 +25451,24 @@ function createMulticallRetry(customRpcs = LIST_OVERRIDES) {
         })),
         allowFailure
       });
-      const resolvedData = allowFailure ? data.map(
-        ({ result, status }) => status !== "success" ? "0x" : result
-      ) : data;
+      let resolvedData;
+      if (allowFailure) {
+        const mapped = data.map(
+          ({ result, status, error }) => ({
+            ok: status === "success",
+            result: status !== "success" ? "0x" : result,
+            error
+          })
+        );
+        const allFailed = mapped.length > 0 && mapped.every((m) => !m.ok);
+        if (allFailed) {
+          const firstError = mapped[0]?.error;
+          throw firstError ?? new Error("All multicall results failed");
+        }
+        resolvedData = mapped.map((m) => m.result);
+      } else {
+        resolvedData = data;
+      }
       if (revertedIndices.size > 0) {
         const finalResults = [];
         let filteredIndex = 0;
@@ -25518,7 +25540,10 @@ function createMulticallRetry(customRpcs = LIST_OVERRIDES) {
       if (maxSkips > 0) {
         if (logErrors) {
           const tag = isHttpError(e) ? "HTTP" : "unknown-transient";
-          console.debug(`[multicall] ${tag} error on provider ${providerId}, skipping`, e);
+          console.debug(
+            `[multicall] ${tag} error on provider ${providerId}, skipping`,
+            e
+          );
         }
         return await multicallRetry2(
           chain,

package/dist/index.mjs

@@ -11338,10 +11338,13 @@ var LIST_OVERRIDES = {
     "https://avax-rpc.gateway.pokt.network"
   ],
   [Chain2.CELO_MAINNET]: [
+    "https://celo-mainnet.gateway.tatum.io",
+    "https://celo-json-rpc.stakely.io",
     "https://forno.celo.org",
     "https://1rpc.io/celo",
     "https://celo.drpc.org",
-    "https://celo-rpc.publicnode.com"
+    "https://celo-rpc.publicnode.com",
+    "https://rpc.ankr.com/celo"
   ],
   [Chain2.BLAST]: [
     "https://rpc.blast.io",
@@ -11437,6 +11440,10 @@ var LIST_OVERRIDES = {
     "https://tac.therpc.io",
     "https://ws.rpc.tac.build"
   ],
+  [Chain2.BOTANIX_MAINNET]: [
+    "https://rpc.botanixlabs.com",
+    "https://rpc.ankr.com/botanix_mainnet"
+  ],
   [Chain2.UNICHAIN]: [
     "https://mainnet.unichain.org",
     "https://rpc.sentio.xyz/unichain-mainnet",
@@ -11633,14 +11640,14 @@ function isHttpError(e) {
       const status = current.status;
       if (status && status >= 400) return true;
       const details = current.details ?? "";
-      const message = current.message ?? "";
+      const message = current.message ?? current.shortMessage ?? "";
       const combined = `${message} ${details}`;
       if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true;
       current = current.cause ?? null;
     }
   }
   if (e instanceof Error) {
-    const combined = `${e.message ?? ""} ${e.details ?? ""}`;
+    const combined = `${e.message ?? e.shortMessage ?? ""} ${e.details ?? ""}`;
     if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true;
   }
   return false;
@@ -11683,9 +11690,24 @@ function createMulticallRetry(customRpcs = LIST_OVERRIDES) {
         })),
         allowFailure
       });
-      const resolvedData = allowFailure ? data.map(
-        ({ result, status }) => status !== "success" ? "0x" : result
-      ) : data;
+      let resolvedData;
+      if (allowFailure) {
+        const mapped = data.map(
+          ({ result, status, error }) => ({
+            ok: status === "success",
+            result: status !== "success" ? "0x" : result,
+            error
+          })
+        );
+        const allFailed = mapped.length > 0 && mapped.every((m) => !m.ok);
+        if (allFailed) {
+          const firstError = mapped[0]?.error;
+          throw firstError ?? new Error("All multicall results failed");
+        }
+        resolvedData = mapped.map((m) => m.result);
+      } else {
+        resolvedData = data;
+      }
       if (revertedIndices.size > 0) {
         const finalResults = [];
         let filteredIndex = 0;
@@ -11757,7 +11779,10 @@ function createMulticallRetry(customRpcs = LIST_OVERRIDES) {
       if (maxSkips > 0) {
         if (logErrors) {
           const tag = isHttpError(e) ? "HTTP" : "unknown-transient";
-          console.debug(`[multicall] ${tag} error on provider ${providerId}, skipping`, e);
+          console.debug(
+            `[multicall] ${tag} error on provider ${providerId}, skipping`,
+            e
+          );
         }
         return await multicallRetry2(
           chain,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1delta/providers",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,7 +19,7 @@
   "dependencies": {
     "vitest": "^4.0.18",
     "@1delta/chain-registry": "0.0.4",
-    "@1delta/data-sdk": "0.0.17"
+    "@1delta/data-sdk": "0.0.21"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/chains/README.md

@@ -0,0 +1,45 @@
+# Chains Module
+
+Maps chain identifiers to viem `Chain` objects, including custom chain definitions for networks not yet in viem.
+
+## Exported Functions
+
+### `getEvmChain(chain: string): Chain`
+
+Resolves a chain enum string (from `@1delta/chain-registry`) to a viem `Chain` object.
+
+```ts
+import { getEvmChain } from '@1delta/providers'
+
+const chain = getEvmChain('BASE')           // returns viem's base chain
+const chain = getEvmChain('MONAD_MAINNET')  // returns custom-defined chain
+```
+
+Throws `"Not in VIEM: <chain>"` if the chain is unrecognized.
+
+Supports 80+ chains including Ethereum, Arbitrum, Base, Polygon, Optimism, BSC, Avalanche, Scroll, Linea, Mantle, zkSync, Sonic, Kaia, Blast, and many more. Some viem-native chains get patched with custom `multicall3` contract addresses (e.g. Hemi, Degen, Ink, Story).
+
+### Custom Chains
+
+Chains not available in viem are defined via `defineChain()` in `customChains.ts`:
+
+| Export | Chain | ID |
+|---|---|---|
+| `katana` | Katana | 747474 |
+| `plasma` | Plasma Mainnet | 9745 |
+| `customChains.artela` | Artela | 11820 |
+| `customChains.botanix` | Botanix | 3637 |
+| `customChains.crossfi` | CrossFi | 4158 |
+| `customChains.GraphLinq` | GraphLinq | 614 |
+| `customChains.hyperEvm` | Hyper EVM | 999 |
+| `customChains.monadMainnet` | Monad | 143 |
+| `customChains.swellchain` | Swellchain | 1923 |
+| `customChains.tacMainnet` | TAC | 239 |
+
+All include RPC URLs, block explorers, native currency, and `multicall3` contract addresses.
+
+## Adding a New Chain
+
+1. If the chain exists in `viem/chains`, add a case to the switch in `chainMapping.ts`.
+2. If the chain does not exist in viem, define it with `defineChain()` in `customChains.ts`, add it to the `customChains` object, then add a case in `chainMapping.ts` referencing it.
+3. Add RPC URLs in `../rpc/rpcOverrides.ts` under `LIST_OVERRIDES`.

package/src/client/README.md

@@ -0,0 +1,51 @@
+# Client Module
+
+Creates viem `PublicClient` instances for any supported EVM chain, with RPC fallback and rotation.
+
+## Preferred API
+
+Use the `Universal` (object-params) variants — positional-args versions are deprecated.
+
+### `getEvmClientUniversal({ chain, rpcId }): PublicClient`
+
+Creates a `PublicClient` using default RPCs (from viem chain config + `LIST_OVERRIDES`).
+
+```ts
+import { getEvmClientUniversal } from '@1delta/providers'
+
+const client = getEvmClientUniversal({ chain: 'BASE', rpcId: 0 })
+const block = await client.getBlockNumber()
+```
+
+- `rpcId: 0` uses the viem default RPC or the first override.
+- `rpcId: N` merges override RPCs with viem defaults, deduplicates, and picks index `N`.
+
+### `getEvmClientWithCustomRpcsUniversal({ chain, rpcId, customRpcs }): PublicClient`
+
+Same as above but lets you inject your own RPC list per chain.
+
+```ts
+import { getEvmClientWithCustomRpcsUniversal } from '@1delta/providers'
+
+const client = getEvmClientWithCustomRpcsUniversal({
+  chain: 'ETHEREUM_MAINNET',
+  rpcId: 0,
+  customRpcs: {
+    ETHEREUM_MAINNET: ['https://my-rpc.example.com'],
+  },
+})
+```
+
+When `customRpcs[chain]` is provided, the RPC index wraps around with modulo (`rpcId % list.length`), enabling round-robin rotation across retries.
+
+When `customRpcs[chain]` is absent, falls back to the same logic as `getEvmClientUniversal`.
+
+## How the Multicall Uses This
+
+The multicall module calls `getEvmClientWithCustomRpcsUniversal` internally, incrementing `providerId` on each retry to rotate through available RPCs.
+
+## RPC Resolution Order
+
+1. If custom RPCs provided for the chain → use those (modulo index).
+2. Else if `rpcId === 0` → viem default RPC, falling back to `LIST_OVERRIDES[chain][0]`.
+3. Else → merge `LIST_OVERRIDES` + viem defaults, deduplicate, clamp index.

package/src/multicall/README.md

@@ -0,0 +1,104 @@
+# Multicall Module
+
+Resilient EVM multicall wrapper around viem's `multicall` with automatic retry, RPC rotation, batch splitting, and revert isolation.
+
+## Preferred API
+
+Use `multicallRetryUniversal` (params object) — the positional-args `multicallRetry` is deprecated.
+
+```ts
+import { multicallRetryUniversal } from '@1delta/providers'
+
+const results = await multicallRetryUniversal({
+  chain,        // chain ID string, e.g. '1', '8453'
+  calls,        // array of call descriptors (see below)
+  abi,          // single ABI array, or array-of-ABIs (one per call)
+  batchSize,    // optional – default 1024
+  maxRetries,   // optional – default 5
+  providerId,   // optional – starting RPC index, default 0
+  allowFailure, // optional – default false; when true, failed calls return '0x'
+  logErrors,    // optional – default false
+})
+```
+
+### Call descriptor shape
+
+```ts
+{
+  address: string       // contract address
+  name: string          // function name
+  args?: any[]          // function arguments (alias: `params`)
+}
+```
+
+Extra fields (e.g. `user` for bookkeeping) are ignored by the multicall but preserved on the input array for post-processing.
+
+### ABI modes
+
+- **Single ABI** — one ABI array shared by all calls (most common):
+  ```ts
+  { abi: MY_ABI, calls: [...] }
+  ```
+- **Per-call ABI** — array of ABIs, one per call (for heterogeneous batches):
+  ```ts
+  { abi: [ABI_A, ABI_B, ...], calls: [callA, callB, ...] }
+  ```
+
+## Error handling / retry strategy
+
+The module classifies errors into three buckets and handles each differently:
+
+| Error type | Detection | Action |
+|---|---|---|
+| **Contract revert** | viem `ContractFunctionRevertedError` or `execution reverted` in message | Identifies the reverting call(s) by matching address + function + args, excludes them, retries remaining calls. Excluded calls return `'0x'`. |
+| **Out of gas** | `out of gas` / `gas exhausted` in message | Halves `batchSize` and retries (same RPC). |
+| **Transient / HTTP** | Connection errors, rate limits, 4xx/5xx, timeouts | Skips to next RPC (`providerId + 1`) without consuming a retry. After `maxSkips` (6) exhausted, consumes a retry and resets skips. |
+
+When all retries are exhausted:
+- `allowFailure: true` → returns `Array(calls.length).fill('0x')`
+- `allowFailure: false` → throws the last error
+
+## Factory variant
+
+Use `createMulticallRetryUniversal` to inject custom RPC lists:
+
+```ts
+import { createMulticallRetryUniversal } from '@1delta/providers'
+
+const multicall = createMulticallRetryUniversal({
+  '1': ['https://rpc1.example.com', 'https://rpc2.example.com'],
+  '8453': ['https://base-rpc.example.com'],
+})
+
+const results = await multicall({ chain: '8453', calls, abi })
+```
+
+The default RPC list comes from `LIST_OVERRIDES` in `../rpc/rpcOverrides`.
+
+## Usage example
+
+```ts
+import { multicallRetryUniversal } from '@1delta/providers'
+import { POOL_ABI } from './abi'
+
+const calls = users.map((user) => ({
+  address: poolAddress,
+  name: 'getUserAccountData',
+  params: [user],
+}))
+
+const results = await multicallRetryUniversal({
+  chain: '1',
+  calls,
+  abi: POOL_ABI,
+  allowFailure: true,
+})
+
+results.forEach((res, i) => {
+  if (res === '0x') {
+    // call reverted or failed
+  } else {
+    // res is the decoded return value
+  }
+})
+```

package/src/multicall/multicall.ts

@@ -71,7 +71,7 @@ function isHttpError(e: unknown): boolean {
       const status = current.status as number | undefined
       if (status && status >= 400) return true
       const details: string = current.details ?? ''
-      const message: string = current.message ?? ''
+      const message: string = current.message ?? current.shortMessage ?? ''
       const combined = `${message} ${details}`
       if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true
       current = current.cause ?? null
@@ -80,7 +80,7 @@ function isHttpError(e: unknown): boolean {
 
   // Fallback: check message + details as strings for non-BaseError errors
   if (e instanceof Error) {
-    const combined = `${e.message ?? ''} ${(e as any).details ?? ''}`
+    const combined = `${e.message ?? (e as any).shortMessage ?? ''} ${(e as any).details ?? ''}`
     if (HTTP_ERROR_STRINGS.some((s) => combined.includes(s))) return true
   }
 
@@ -175,11 +175,30 @@ export function createMulticallRetry(
 
       // When allowFailure is true, viem returns { result, status } per call.
       // Extract results and convert failures to '0x'.
-      const resolvedData = allowFailure
-        ? (data as any[]).map(({ result, status }: any) =>
-            status !== 'success' ? '0x' : result,
-          )
-        : data
+      let resolvedData: any[]
+      if (allowFailure) {
+        const mapped = (data as any[]).map(
+          ({ result, status, error }: any) => ({
+            ok: status === 'success',
+            result: status !== 'success' ? '0x' : result,
+            error,
+          }),
+        )
+        const allFailed = mapped.length > 0 && mapped.every((m) => !m.ok)
+
+        // If EVERY call in the batch failed, the cause is almost certainly
+        // a transport-level error (429, 502, timeout) that viem caught
+        // internally instead of throwing. Re-throw so the retry logic
+        // below (skip to next RPC / consume a retry) handles it.
+        if (allFailed) {
+          const firstError = mapped[0]?.error
+          throw firstError ?? new Error('All multicall results failed')
+        }
+
+        resolvedData = mapped.map((m) => m.result)
+      } else {
+        resolvedData = data as any[]
+      }
 
       if (revertedIndices.size > 0) {
         const finalResults: any[] = []
@@ -269,7 +288,10 @@ export function createMulticallRetry(
       if (maxSkips > 0) {
         if (logErrors) {
           const tag = isHttpError(e) ? 'HTTP' : 'unknown-transient'
-          console.debug(`[multicall] ${tag} error on provider ${providerId}, skipping`, e)
+          console.debug(
+            `[multicall] ${tag} error on provider ${providerId}, skipping`,
+            e,
+          )
         }
         return await multicallRetry(
           chain,

package/src/rpc/README.md

@@ -0,0 +1,41 @@
+# RPC Module
+
+Provides default RPC URL lists per chain used as fallbacks throughout the providers package.
+
+## Exports
+
+### `LIST_OVERRIDES: Record<string, string[]>`
+
+A mapping of chain identifiers to arrays of public/semi-public RPC URLs. Used as the default RPC pool by the client and multicall modules.
+
+```ts
+import { LIST_OVERRIDES } from '@1delta/providers'
+
+// e.g. LIST_OVERRIDES['BASE'] → ['https://mainnet.base.org', 'https://base.drpc.org', ...]
+```
+
+Covered chains include: Ethereum, Base, Polygon, Arbitrum, Optimism, BSC, Avalanche, Scroll, Linea, Mantle, Sonic, Kaia, Blast, Gnosis, Mode, Metis, Fantom, opBNB, Manta, Sei, Monad, HyperEVM, Swellchain, TAC, Botanix, Unichain, and more.
+
+### `filterHttpRpcs(rpcs: string[]): string[]`
+
+Filters out WebSocket (`wss://`) URLs, returning only HTTP endpoints.
+
+```ts
+import { filterHttpRpcs } from '@1delta/providers'
+
+const httpOnly = filterHttpRpcs(['https://rpc.example.com', 'wss://ws.example.com'])
+// → ['https://rpc.example.com']
+```
+
+## Adding RPCs for a New Chain
+
+Add an entry to the `LIST_OVERRIDES` object in `rpcOverrides.ts`:
+
+```ts
+LIST_OVERRIDES['MY_NEW_CHAIN'] = [
+  'https://rpc1.mychain.io',
+  'https://rpc2.mychain.io',
+]
+```
+
+Order matters — index 0 is the default RPC used when `rpcId === 0`.

package/src/rpc/rpcOverrides.ts

@@ -175,10 +175,13 @@ export const LIST_OVERRIDES: Record<string, string[]> = {
     'https://avax-rpc.gateway.pokt.network',
   ],
   [Chain.CELO_MAINNET]: [
+    'https://celo-mainnet.gateway.tatum.io',
+    'https://celo-json-rpc.stakely.io',
     'https://forno.celo.org',
     'https://1rpc.io/celo',
     'https://celo.drpc.org',
     'https://celo-rpc.publicnode.com',
+    'https://rpc.ankr.com/celo',
   ],
   [Chain.BLAST]: [
     'https://rpc.blast.io',
@@ -274,6 +277,10 @@ export const LIST_OVERRIDES: Record<string, string[]> = {
     'https://tac.therpc.io',
     'https://ws.rpc.tac.build',
   ],
+  [Chain.BOTANIX_MAINNET]: [
+    'https://rpc.botanixlabs.com',
+    'https://rpc.ankr.com/botanix_mainnet',
+  ],
   [Chain.UNICHAIN]: [
     'https://mainnet.unichain.org',
     'https://rpc.sentio.xyz/unichain-mainnet',

package/src/transport/README.md

@@ -0,0 +1,28 @@
+# Transport Module
+
+Creates viem transports (HTTP or WebSocket) from a URL string.
+
+## Exports
+
+### `createTransport(url: string, config?: object)`
+
+Returns an `http()` or `webSocket()` viem transport based on the URL scheme.
+
+```ts
+import { createTransport } from '@1delta/providers'
+
+const t1 = createTransport('https://rpc.example.com')   // → http transport
+const t2 = createTransport('wss://ws.example.com')       // → webSocket transport
+```
+
+**Key detail:** `retryCount` defaults to `0` (no viem-level retries). This is intentional — retry logic is handled at the multicall layer, which rotates RPCs on failure. Allowing viem to retry the same failing RPC would add latency without benefit.
+
+You can override this via `config`:
+
+```ts
+createTransport('https://rpc.example.com', { retryCount: 3 })
+```
+
+### `getTransport(url: string)`
+
+Convenience wrapper — calls `createTransport(url)` with default config.

package/src/utils/README.md

@@ -0,0 +1,29 @@
+# Utils Module
+
+Internal utilities used by the providers package. All are re-exported from the package root.
+
+## Exports
+
+### `DEFAULT_BATCH_SIZE`
+
+```ts
+const DEFAULT_BATCH_SIZE = 1024
+```
+
+Default number of calls per multicall batch. Used by the multicall module when no `batchSize` is specified.
+
+### `trimTrailingSlash(url?: string): string | undefined`
+
+Removes a trailing `/` from a URL string. Returns `undefined` if input is falsy. Used to deduplicate RPC URLs that may differ only by a trailing slash.
+
+### `deepCompare(a: any, b: any): boolean`
+
+Deep equality check for objects and arrays. Used by the multicall module to match reverting calls by comparing function arguments. Note: returns `false` for `bigint` values (by design — bigint args are not compared during revert matching).
+
+### `uniq<T>(array: T[]): T[]`
+
+Returns a new array with duplicate values removed (via `Set`).
+
+### `isArray(value: any): boolean`
+
+Wrapper around `Array.isArray`. Used by the multicall module to detect whether the ABI parameter is a single ABI or an array of per-call ABIs.