@corpus-core/colibri-stateless 0.7.6 → 0.7.7

package/chains.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { Config as C4Config, ChainConfig } from './types.js';
+export declare const default_config: {
+    [key: string]: {
+        alias: string[];
+        beacon_apis: string[];
+        rpcs: string[];
+        prover: string[];
+        checkpointz: string[];
+        pollingInterval: number;
+    };
+};
+export declare function get_chain_id(chain_id: string): number;
+export declare function chain_conf(config: C4Config, chainId: number | string): ChainConfig | undefined;
+export declare const defaultChainConfig: {
+    [key: string]: {
+        alias: string[];
+        beacon_apis: string[];
+        rpcs: string[];
+        prover: string[];
+        checkpointz: string[];
+        pollingInterval: number;
+    };
+};
+export declare const resolveChainId: typeof get_chain_id;
+export declare const getChainConfig: typeof chain_conf;

package/chains.js

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+export const default_config = {
+    '1': {
+        alias: ["mainnet", "eth", "0x1"],
+        beacon_apis: ["https://lodestar-mainnet.chainsafe.io"],
+        rpcs: ["https://rpc.ankr.com/eth"],
+        prover: ["https://mainnet1.colibri-proof.tech"],
+        checkpointz: [], //"https://sync-mainnet.beaconcha.in", "https://beaconstate.info", "https://sync.invis.tools", "https://beaconstate.ethstaker.cc"],
+        pollingInterval: 12000,
+    },
+    '11155111': {
+        alias: ["sepolia", "0xaa36a7"],
+        beacon_apis: ["https://ethereum-sepolia-beacon-api.publicnode.com"],
+        rpcs: ["https://ethereum-sepolia-rpc.publicnode.com"],
+        prover: ["https://sepolia.colibri-proof.tech"],
+        checkpointz: [], // No public checkpointz for Sepolia yet
+        pollingInterval: 12000,
+    },
+    '100': {
+        alias: ["gnosis", "xdai", "0x64"],
+        beacon_apis: ["https://gnosis.colibri-proof.tech"],
+        rpcs: ["https://rpc.ankr.com/gnosis"],
+        prover: ["https://gnosis.colibri-proof.tech"],
+        checkpointz: [], // TODO: Add Gnosis checkpointz servers
+        pollingInterval: 5000,
+    },
+    '10200': {
+        alias: ["chiado", "0x27d8"],
+        beacon_apis: ["https://gnosis-chiado-beacon-api.publicnode.com"],
+        rpcs: ["https://gnosis-chiado-rpc.publicnode.com"],
+        prover: ["https://chiado.colibri-proof.tech"],
+        checkpointz: [], // No public checkpointz for Chiado yet
+        pollingInterval: 5000,
+    },
+};
+export function get_chain_id(chain_id) {
+    const chain_id_num = parseInt(chain_id);
+    if (!isNaN(chain_id_num))
+        return chain_id_num;
+    for (const chain in default_config) {
+        if (default_config[chain].alias.includes(chain_id))
+            return parseInt(chain);
+    }
+    throw new Error("Invalid chain id: " + chain_id);
+}
+export function chain_conf(config, chainId) {
+    const k = config?.chains?.[chainId];
+    if (k)
+        return k;
+    const k2 = default_config[chainId + ''];
+    if (k2)
+        return k2;
+    return undefined;
+}
+// Friendly aliases (optional, keep compatibility with planned naming)
+export const defaultChainConfig = default_config;
+export const resolveChainId = get_chain_id;
+export const getChainConfig = chain_conf;

package/http.d.ts

@@ -0,0 +1,30 @@
+import { Config as C4Config, DataRequest } from './types.js';
+export type AcceptKind = 'json' | 'octet';
+/**
+ * @param servers List of base URLs
+ * @param path Optional path to append to server URL
+ * @param method HTTP method
+ * @param payload Optional JSON payload (POST)
+ * @param accept Response type hint
+ * @param excludeMask Bitmask to skip servers by index
+ * @return Uint8Array of response bytes and nodeIndex used
+ */
+export declare function fetch_from_servers(servers: string[], path: string, method: 'GET' | 'POST', payload?: any, accept?: AcceptKind, excludeMask?: number): Promise<{
+    data: Uint8Array;
+    nodeIndex: number;
+}>;
+/**
+ * Posts a JSON-RPC payload across multiple URLs and returns result or proof bytes.
+ * @param urls Ordered list of RPC endpoints
+ * @param payload JSON-RPC payload (id will be set to 1 if not provided)
+ * @param as_proof Expect octet-stream (true) or JSON result (false)
+ * @return result value for JSON or raw bytes for proofs
+ */
+export declare function fetch_rpc(urls: string[], payload: any, as_proof?: boolean): Promise<any>;
+/**
+ * Handles a C4 data request by fetching from configured servers, setting the
+ * response or error back into the C context, and leveraging cache if present.
+ * @param req DataRequest descriptor from C
+ * @param conf Colibri configuration
+ */
+export declare function handle_request(req: DataRequest, conf: C4Config): Promise<void>;

package/http.js

@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { getC4w, as_char_ptr, copy_to_c } from './wasm.js';
+function joinPath(base, path) {
+    if (!path)
+        return base;
+    if (!path.length)
+        return base;
+    return base + (path.startsWith('/') ? path : '/' + path);
+}
+/**
+ * @param servers List of base URLs
+ * @param path Optional path to append to server URL
+ * @param method HTTP method
+ * @param payload Optional JSON payload (POST)
+ * @param accept Response type hint
+ * @param excludeMask Bitmask to skip servers by index
+ * @return Uint8Array of response bytes and nodeIndex used
+ */
+export async function fetch_from_servers(servers, path, method, payload, accept = 'json', excludeMask = 0) {
+    let lastError = 'All nodes failed';
+    let nodeIndex = 0;
+    for (const server of servers) {
+        if (excludeMask & (1 << nodeIndex)) {
+            nodeIndex++;
+            continue;
+        }
+        try {
+            const response = await fetch(joinPath(server, path), {
+                method,
+                body: payload ? JSON.stringify(payload) : undefined,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': accept === 'json' ? 'application/json' : 'application/octet-stream',
+                },
+            });
+            if (!response.ok) {
+                lastError = `HTTP error! Status: ${response.status}, Details: ${await response.text()}`;
+                nodeIndex++;
+                continue;
+            }
+            const bytes = await response.blob().then(b => b.arrayBuffer());
+            return { data: new Uint8Array(bytes), nodeIndex };
+        }
+        catch (e) {
+            lastError = (e instanceof Error) ? e.message : String(e);
+        }
+        nodeIndex++;
+    }
+    throw new Error(lastError);
+}
+// --- Higher level helpers used by Colibri client ---
+function log(msg) {
+    console.error(msg);
+}
+/**
+ * Posts a JSON-RPC payload across multiple URLs and returns result or proof bytes.
+ * @param urls Ordered list of RPC endpoints
+ * @param payload JSON-RPC payload (id will be set to 1 if not provided)
+ * @param as_proof Expect octet-stream (true) or JSON result (false)
+ * @return result value for JSON or raw bytes for proofs
+ */
+export async function fetch_rpc(urls, payload, as_proof = false) {
+    let last_error = 'All nodes failed';
+    for (const url of urls) {
+        const response = await fetch(url, {
+            method: 'POST',
+            body: JSON.stringify({ id: 1, jsonrpc: '2.0', ...payload }),
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': as_proof ? 'application/octet-stream' : 'application/json',
+            },
+        });
+        if (response.ok) {
+            if (!as_proof) {
+                const res = await response.json();
+                if (res.error) {
+                    last_error = res.error?.message || res.error;
+                    continue;
+                }
+                return res.result;
+            }
+            const bytes = await response.blob().then(blob => blob.arrayBuffer());
+            return new Uint8Array(bytes);
+        }
+        else {
+            last_error = `HTTP error! Status: ${response.status}, Details: ${await response.text()}`;
+        }
+    }
+    throw new Error(last_error);
+}
+/**
+ * Handles a C4 data request by fetching from configured servers, setting the
+ * response or error back into the C context, and leveraging cache if present.
+ * @param req DataRequest descriptor from C
+ * @param conf Colibri configuration
+ */
+export async function handle_request(req, conf) {
+    const free_buffers = [];
+    let servers = [];
+    switch (req.type) {
+        case 'checkpointz':
+            servers = [...(conf.checkpointz || []), ...(conf.beacon_apis || []), ...(conf.prover || [])];
+            break;
+        case 'beacon_api':
+            servers = [...(conf.beacon_apis || []), ...(conf.prover || [])];
+            break;
+        case 'prover':
+            servers = [...(conf.prover || [])];
+            break;
+        default:
+            servers = conf.rpcs || [];
+            break;
+    }
+    const c4w = await getC4w();
+    let path = (req.type == 'eth_rpc' && req.payload)
+        ? `rpc: ${req.payload?.method}(${req.payload?.params.join(',')})`
+        : req.url;
+    let cacheable = conf.cache && conf.cache.cacheable(req);
+    if (cacheable && conf.cache) {
+        const data = conf.cache.get(req);
+        if (data) {
+            if (conf.debug)
+                log(`::: ${path} (len=${data.length} bytes) CACHED`);
+            c4w._c4w_req_set_response(req.req_ptr, copy_to_c(data, c4w), data.length, 0);
+            return;
+        }
+    }
+    try {
+        const accept = req.encoding == 'json' ? 'json' : 'octet';
+        const { data, nodeIndex } = await fetch_from_servers(servers, req.url || '', req.method, req.payload, accept, req.exclude_mask);
+        c4w._c4w_req_set_response(req.req_ptr, copy_to_c(data, c4w), data.length, nodeIndex);
+        if (conf.debug)
+            log(`::: ${path} (len=${data.length} bytes) FETCHED`);
+        if (conf.cache && cacheable)
+            conf.cache.set(req, data);
+    }
+    catch (e) {
+        const last_error = (e instanceof Error) ? e.message : String(e);
+        c4w._c4w_req_set_error(req.req_ptr, as_char_ptr(last_error, c4w, free_buffers), 0);
+        if (conf.debug)
+            log(`::: ${path} (Error: ${last_error})`);
+    }
+    finally {
+        free_buffers.forEach(ptr => c4w._free(ptr));
+    }
+}

package/index.d.ts

@@ -27,31 +27,43 @@ import Strategy from './strategy.js';
 export { Strategy };
 export { ProviderRpcError, RequestArguments, Cache, C4Config, DataRequest, C4MethodType as MethodType, ProviderMessage, EthSubscribeSubscriptionType, EthNewFilterType };
 export { TransactionVerifier, PrototypeProtection } from './transactionVerifier.js';
-export declare function handle_request(req: DataRequest, conf: C4Config): Promise<void>;
 export default class C4Client {
     config: C4Config;
     private eventEmitter;
     private connectionState;
     private subscriptionManager;
+    private initMap;
+    private flags;
     private static readonly CRITICAL_METHODS;
+    /**
+     * Creates a new Colibri client instance.
+     *
+     * Example:
+     * ```ts
+     * import Colibri from '@corpus-core/colibri-stateless';
+     * const client = new Colibri({ chainId: 1 });
+     * const blockNumber = await client.request({ method: 'eth_blockNumber' });
+     * ```
+     *
+     * @param config Optional partial configuration; user config overrides defaults.
+     */
     constructor(config?: Partial<C4Config>);
-    private getProverConfig;
-    private get flags();
+    private fetch_checkpointz;
     /**
-     * checks, whether the rpc-method is supported or proofable.
+     * Checks whether the RPC method is supported or proofable.
      * @param method - The method to check
      * @returns The method type
      */
     getMethodSupport(method: string): Promise<C4MethodType>;
     /**
-     * creates a proof for the given method and arguments
+     * Creates a proof for the given method and arguments.
      * @param method - The method to create a proof for
      * @param args - The arguments to create a proof for
      * @returns The proof
      */
     createProof(method: string, args: any[]): Promise<Uint8Array>;
     /**
-     * verifies a proof for the given method and arguments
+     * Verifies a proof for the given method and arguments.
      * @param method - The method to verify the proof for
      * @param args - The arguments to verify the proof for
      * @param proof - The proof to verify
@@ -59,10 +71,10 @@ export default class C4Client {
      */
     verifyProof(method: string, args: any[], proof: Uint8Array): Promise<any>;
     /**
-     * executes a rpc-method, which includes
-     * -creating or fetching the proof
-     * -verifying the proof
-     * -returning the result
+     * Executes an RPC method. This includes:
+     * - Creating or fetching the proof
+     * - Verifying the proof
+     * - Returning the result
      * @param method - The method to execute
      * @param args - The arguments to execute the method with
      * @returns The result
@@ -70,6 +82,18 @@ export default class C4Client {
     rpc(method: string, args: any[], method_type?: C4MethodType): Promise<any>;
     static register_storage(storage: C4Storage): Promise<void>;
     request(args: RequestArguments): Promise<unknown>;
+    /**
+     * Registers an event listener on the Colibri client.
+     * @param event Event name (e.g. 'connect', 'disconnect', 'message')
+     * @param callback Callback invoked with event data
+     * @return This client for chaining
+     */
     on(event: string, callback: (data: any) => void): this;
+    /**
+     * Removes a previously registered event listener from the Colibri client.
+     * @param event Event name
+     * @param callback Same function reference passed to on()
+     * @return This client for chaining
+     */
     removeListener(event: string, callback: (data: any) => void): this;
 }