@orbinum/sdk 0.7.6 → 0.7.7

package/dist/index.d.mts

@@ -10,6 +10,20 @@ export { base58 } from '@scure/base';
 export { getPolkadotSigner } from 'polkadot-api/signer';
 export { SignPayload, SignRaw, connectInjectedExtension, getInjectedExtensions, getPolkadotSignerFromPjs } from 'polkadot-api/pjs-signer';
 
+/**
+ * Minimal JSON-RPC 2.0 over HTTP — batch transport.
+ *
+ * Substrate and EVM nodes both serve JSON-RPC over HTTP. PAPI's WebSocket
+ * transport (used by `SubstrateClient` for everything else) does not expose
+ * batch requests, so high-throughput callers (e.g. indexer backfill) use this
+ * to fetch many results in a single round-trip instead of N.
+ */
+/** A single JSON-RPC call: method name plus positional params. */
+interface JsonRpcCall {
+    method: string;
+    params?: unknown[];
+}
+
 type ChainInfo = {
     name: string;
     version: string;
@@ -87,6 +101,7 @@ type ExtrinsicDecoder = ReturnType<typeof getExtrinsicDecoder>;
  */
 declare class SubstrateClient {
     private readonly _papi;
+    private readonly _httpUrl;
     private constructor();
     private _dynamicBuilder;
     private _extDecoder;
@@ -100,6 +115,17 @@ declare class SubstrateClient {
      * (shieldedPool_*, accountMapping_*, privacy_*, etc.).
      */
     request<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Performs multiple JSON-RPC calls in a single HTTP request (batch). Results
+     * are returned in the same order as `calls`, as a typed tuple. A `null`
+     * result (or per-call error) maps to `null` in that slot — the call itself
+     * only rejects on HTTP/transport failure.
+     *
+     * Uses the HTTP RPC endpoint (derived from the WS URL); PAPI's WS transport
+     * does not expose batching. Ideal for high-throughput backfill: fetch many
+     * block hashes / blocks / storage reads in one round-trip instead of N.
+     */
+    batchRequest<T extends unknown[]>(calls: JsonRpcCall[]): Promise<T>;
     /**
      * Returns basic chain information from the node.
      * Combines `system_name`, `system_chain`, `system_properties`, and `state_getRuntimeVersion`.
@@ -2124,6 +2150,14 @@ declare class OrbinumClientProvider {
      * Waits for the client to be ready before dispatching.
      */
     rpcSend<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Sends multiple Substrate JSON-RPC calls as a single HTTP batch request.
+     * Returns a tuple of typed results in the same order as `calls`.
+     */
+    rpcBatch<T extends unknown[]>(calls: Array<{
+        method: string;
+        params?: unknown[];
+    }>): Promise<T>;
     /**
      * Sends a single EVM JSON-RPC request and returns the typed result.
      * Throws if `evmRpc` was not configured.

package/dist/index.d.ts

@@ -10,6 +10,20 @@ export { base58 } from '@scure/base';
 export { getPolkadotSigner } from 'polkadot-api/signer';
 export { SignPayload, SignRaw, connectInjectedExtension, getInjectedExtensions, getPolkadotSignerFromPjs } from 'polkadot-api/pjs-signer';
 
+/**
+ * Minimal JSON-RPC 2.0 over HTTP — batch transport.
+ *
+ * Substrate and EVM nodes both serve JSON-RPC over HTTP. PAPI's WebSocket
+ * transport (used by `SubstrateClient` for everything else) does not expose
+ * batch requests, so high-throughput callers (e.g. indexer backfill) use this
+ * to fetch many results in a single round-trip instead of N.
+ */
+/** A single JSON-RPC call: method name plus positional params. */
+interface JsonRpcCall {
+    method: string;
+    params?: unknown[];
+}
+
 type ChainInfo = {
     name: string;
     version: string;
@@ -87,6 +101,7 @@ type ExtrinsicDecoder = ReturnType<typeof getExtrinsicDecoder>;
  */
 declare class SubstrateClient {
     private readonly _papi;
+    private readonly _httpUrl;
     private constructor();
     private _dynamicBuilder;
     private _extDecoder;
@@ -100,6 +115,17 @@ declare class SubstrateClient {
      * (shieldedPool_*, accountMapping_*, privacy_*, etc.).
      */
     request<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Performs multiple JSON-RPC calls in a single HTTP request (batch). Results
+     * are returned in the same order as `calls`, as a typed tuple. A `null`
+     * result (or per-call error) maps to `null` in that slot — the call itself
+     * only rejects on HTTP/transport failure.
+     *
+     * Uses the HTTP RPC endpoint (derived from the WS URL); PAPI's WS transport
+     * does not expose batching. Ideal for high-throughput backfill: fetch many
+     * block hashes / blocks / storage reads in one round-trip instead of N.
+     */
+    batchRequest<T extends unknown[]>(calls: JsonRpcCall[]): Promise<T>;
     /**
      * Returns basic chain information from the node.
      * Combines `system_name`, `system_chain`, `system_properties`, and `state_getRuntimeVersion`.
@@ -2124,6 +2150,14 @@ declare class OrbinumClientProvider {
      * Waits for the client to be ready before dispatching.
      */
     rpcSend<T>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Sends multiple Substrate JSON-RPC calls as a single HTTP batch request.
+     * Returns a tuple of typed results in the same order as `calls`.
+     */
+    rpcBatch<T extends unknown[]>(calls: Array<{
+        method: string;
+        params?: unknown[];
+    }>): Promise<T>;
     /**
      * Sends a single EVM JSON-RPC request and returns the typed result.
      * Throws if `evmRpc` was not configured.

package/dist/index.js

@@ -163,12 +163,59 @@ function hexToBigint(hex) {
   return BigInt(hex);
 }
 
+// src/utils/jsonRpcHttp.ts
+var DEFAULT_MAX_RETRIES = 5;
+var DEFAULT_BASE_BACKOFF_MS = 250;
+var DEFAULT_MAX_BACKOFF_MS = 4e3;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function jsonRpcBatch(httpUrl, calls, options = {}) {
+  if (calls.length === 0) return [];
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const baseBackoffMs = options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS;
+  const maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const body = calls.map((c, i) => ({
+    id: i,
+    jsonrpc: "2.0",
+    method: c.method,
+    params: c.params ?? []
+  }));
+  const payload = JSON.stringify(body);
+  let attempt = 0;
+  for (; ; ) {
+    const res = await fetch(httpUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload
+    });
+    if (res.ok) {
+      const arr = await res.json();
+      const byId = new Map(arr.map((r) => [r.id, r]));
+      return calls.map((_, i) => byId.get(i)?.result ?? null);
+    }
+    const retryable = res.status === 429 || res.status === 503;
+    if (!retryable || attempt >= maxRetries) {
+      throw new Error(`JSON-RPC HTTP ${res.status}: ${res.statusText}`);
+    }
+    const retryAfter = Number(res.headers.get("retry-after"));
+    const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : Math.min(baseBackoffMs * 2 ** attempt, maxBackoffMs);
+    await sleep(delayMs);
+    attempt++;
+  }
+}
+function wsUrlToHttp(wsUrl) {
+  if (wsUrl.startsWith("wss://")) return "https://" + wsUrl.slice("wss://".length);
+  if (wsUrl.startsWith("ws://")) return "http://" + wsUrl.slice("ws://".length);
+  return wsUrl;
+}
+
 // src/substrate/SubstrateClient.ts
 var SubstrateClient = class _SubstrateClient {
-  constructor(_papi) {
+  constructor(_papi, _httpUrl) {
     this._papi = _papi;
+    this._httpUrl = _httpUrl;
   }
   _papi;
+  _httpUrl;
   _dynamicBuilder = null;
   _extDecoder = null;
   /**
@@ -187,7 +234,7 @@ var SubstrateClient = class _SubstrateClient {
         )
       )
     ]);
-    return new _SubstrateClient(papi);
+    return new _SubstrateClient(papi, wsUrlToHttp(wsUrl));
   }
   /**
    * Performs a raw JSON-RPC request. Use this for custom Orbinum RPCs
@@ -196,6 +243,19 @@ var SubstrateClient = class _SubstrateClient {
   async request(method, params = []) {
     return this._papi._request(method, params);
   }
+  /**
+   * Performs multiple JSON-RPC calls in a single HTTP request (batch). Results
+   * are returned in the same order as `calls`, as a typed tuple. A `null`
+   * result (or per-call error) maps to `null` in that slot — the call itself
+   * only rejects on HTTP/transport failure.
+   *
+   * Uses the HTTP RPC endpoint (derived from the WS URL); PAPI's WS transport
+   * does not expose batching. Ideal for high-throughput backfill: fetch many
+   * block hashes / blocks / storage reads in one round-trip instead of N.
+   */
+  async batchRequest(calls) {
+    return jsonRpcBatch(this._httpUrl, calls);
+  }
   /**
    * Returns basic chain information from the node.
    * Combines `system_name`, `system_chain`, `system_properties`, and `state_getRuntimeVersion`.
@@ -3695,6 +3755,14 @@ var OrbinumClientProvider = class {
     const client = await this.getOrbinumClient();
     return client.substrate.request(method, params);
   }
+  /**
+   * Sends multiple Substrate JSON-RPC calls as a single HTTP batch request.
+   * Returns a tuple of typed results in the same order as `calls`.
+   */
+  async rpcBatch(calls) {
+    const client = await this.getOrbinumClient();
+    return client.substrate.batchRequest(calls);
+  }
   /**
    * Sends a single EVM JSON-RPC request and returns the typed result.
    * Throws if `evmRpc` was not configured.

package/dist/index.mjs

@@ -36,12 +36,59 @@ function hexToBigint(hex) {
   return BigInt(hex);
 }
 
+// src/utils/jsonRpcHttp.ts
+var DEFAULT_MAX_RETRIES = 5;
+var DEFAULT_BASE_BACKOFF_MS = 250;
+var DEFAULT_MAX_BACKOFF_MS = 4e3;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function jsonRpcBatch(httpUrl, calls, options = {}) {
+  if (calls.length === 0) return [];
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const baseBackoffMs = options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS;
+  const maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const body = calls.map((c, i) => ({
+    id: i,
+    jsonrpc: "2.0",
+    method: c.method,
+    params: c.params ?? []
+  }));
+  const payload = JSON.stringify(body);
+  let attempt = 0;
+  for (; ; ) {
+    const res = await fetch(httpUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload
+    });
+    if (res.ok) {
+      const arr = await res.json();
+      const byId = new Map(arr.map((r) => [r.id, r]));
+      return calls.map((_, i) => byId.get(i)?.result ?? null);
+    }
+    const retryable = res.status === 429 || res.status === 503;
+    if (!retryable || attempt >= maxRetries) {
+      throw new Error(`JSON-RPC HTTP ${res.status}: ${res.statusText}`);
+    }
+    const retryAfter = Number(res.headers.get("retry-after"));
+    const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : Math.min(baseBackoffMs * 2 ** attempt, maxBackoffMs);
+    await sleep(delayMs);
+    attempt++;
+  }
+}
+function wsUrlToHttp(wsUrl) {
+  if (wsUrl.startsWith("wss://")) return "https://" + wsUrl.slice("wss://".length);
+  if (wsUrl.startsWith("ws://")) return "http://" + wsUrl.slice("ws://".length);
+  return wsUrl;
+}
+
 // src/substrate/SubstrateClient.ts
 var SubstrateClient = class _SubstrateClient {
-  constructor(_papi) {
+  constructor(_papi, _httpUrl) {
     this._papi = _papi;
+    this._httpUrl = _httpUrl;
   }
   _papi;
+  _httpUrl;
   _dynamicBuilder = null;
   _extDecoder = null;
   /**
@@ -60,7 +107,7 @@ var SubstrateClient = class _SubstrateClient {
         )
       )
     ]);
-    return new _SubstrateClient(papi);
+    return new _SubstrateClient(papi, wsUrlToHttp(wsUrl));
   }
   /**
    * Performs a raw JSON-RPC request. Use this for custom Orbinum RPCs
@@ -69,6 +116,19 @@ var SubstrateClient = class _SubstrateClient {
   async request(method, params = []) {
     return this._papi._request(method, params);
   }
+  /**
+   * Performs multiple JSON-RPC calls in a single HTTP request (batch). Results
+   * are returned in the same order as `calls`, as a typed tuple. A `null`
+   * result (or per-call error) maps to `null` in that slot — the call itself
+   * only rejects on HTTP/transport failure.
+   *
+   * Uses the HTTP RPC endpoint (derived from the WS URL); PAPI's WS transport
+   * does not expose batching. Ideal for high-throughput backfill: fetch many
+   * block hashes / blocks / storage reads in one round-trip instead of N.
+   */
+  async batchRequest(calls) {
+    return jsonRpcBatch(this._httpUrl, calls);
+  }
   /**
    * Returns basic chain information from the node.
    * Combines `system_name`, `system_chain`, `system_properties`, and `state_getRuntimeVersion`.
@@ -3568,6 +3628,14 @@ var OrbinumClientProvider = class {
     const client = await this.getOrbinumClient();
     return client.substrate.request(method, params);
   }
+  /**
+   * Sends multiple Substrate JSON-RPC calls as a single HTTP batch request.
+   * Returns a tuple of typed results in the same order as `calls`.
+   */
+  async rpcBatch(calls) {
+    const client = await this.getOrbinumClient();
+    return client.substrate.batchRequest(calls);
+  }
   /**
    * Sends a single EVM JSON-RPC request and returns the typed result.
    * Throws if `evmRpc` was not configured.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",