@corpus-core/colibri-stateless 0.7.6 → 0.7.7

package/index.js

@@ -21,160 +21,22 @@
  * SPDX-License-Identifier: MIT
  */
 // Import the Emscripten-generated module
-import { as_bytes, as_char_ptr, as_json, copy_to_c, getC4w } from "./wasm.js";
+import { as_bytes, as_char_ptr, as_json, copy_to_c, getC4w, get_prover_config_hex, set_trusted_checkpoint } from "./wasm.js";
 import { EventEmitter } from './eventEmitter.js';
 import { ConnectionState } from './connectionState.js';
 import { ProviderRpcError, MethodType as C4MethodType } from './types.js';
+import { default_config, get_chain_id, chain_conf } from './chains.js';
 import { SubscriptionManager } from './subscriptionManager.js';
 import Strategy from './strategy.js';
 import { TransactionVerifier, PrototypeProtection } from './transactionVerifier.js';
+import { fetch_rpc, handle_request } from './http.js';
 export { Strategy };
 // Re-export types needed by consumers of the C4Client module
 export { ProviderRpcError, C4MethodType as MethodType };
 // Re-export transaction verification utilities
 export { TransactionVerifier, PrototypeProtection } from './transactionVerifier.js';
-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);
-}
-function log(msg) {
-    console.error(msg);
-}
-export async function handle_request(req, conf) {
-    const free_buffers = [];
-    const servers = req.type == "checkpointz"
-        ? (conf.checkpointz || [])
-        : (req.type == "beacon_api"
-            ? ((conf.prover && conf.prover.length) ? conf.prover : conf.beacon_apis)
-            : conf.rpcs);
-    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;
-        }
-    }
-    let node_index = 0;
-    let last_error = "All nodes failed";
-    for (const server of servers) {
-        if (req.exclude_mask & (1 << node_index)) {
-            node_index++;
-            continue;
-        }
-        try {
-            const response = await fetch(server + (req.url ? ('/' + req.url) : ''), {
-                method: req.method,
-                body: req.payload ? JSON.stringify(req.payload) : undefined,
-                headers: {
-                    "Content-Type": "application/json",
-                    "Accept": req.encoding == "json" ? "application/json" : "application/octet-stream"
-                }
-            });
-            if (!response.ok)
-                throw new Error(`HTTP error! Status: ${response.status}, Details: ${await response.text()}`);
-            const bytes = await response.blob().then(blob => blob.arrayBuffer());
-            const data = new Uint8Array(bytes);
-            c4w._c4w_req_set_response(req.req_ptr, copy_to_c(data, c4w), data.length, node_index);
-            if (conf.debug)
-                log(`::: ${path} (len=${data.length} bytes) FETCHED`);
-            if (conf.cache && cacheable)
-                conf.cache.set(req, data);
-            return;
-        }
-        catch (e) {
-            last_error = (e instanceof Error) ? e.message : String(e);
-        }
-        node_index++;
-    }
-    c4w._c4w_req_set_error(req.req_ptr, as_char_ptr(last_error, c4w, free_buffers), 0);
-    free_buffers.forEach(ptr => c4w._free(ptr));
-    if (conf.debug)
-        log(`::: ${path} (Error: ${last_error})`);
-}
-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,
-    },
-};
-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);
-}
-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;
-}
+// fetch_rpc und handle_request sind nach http.ts verschoben
+// default_config, get_chain_id, chain_conf ausgelagert nach ./chains.ts
 function cleanup_args(method, args) {
     if (method == "eth_verifyLogs")
         return args.map(arg => ({
@@ -188,16 +50,30 @@ export default class C4Client {
     eventEmitter;
     connectionState;
     subscriptionManager;
-    // Schutz vor Prototype Pollution durch Einfrieren kritischer Methoden
+    initMap = new Map();
+    flags = 0;
+    // Protect against prototype pollution by freezing critical methods
     static CRITICAL_METHODS = ['rpc', 'request', 'verifyProof', 'createProof'];
     static {
-        // Schutz vor Prototype Pollution anwenden
+        // Apply prototype pollution protection
         PrototypeProtection.protectClass(C4Client, C4Client.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) {
         const chainId = config?.chainId ? get_chain_id(config?.chainId + '') : 1;
         const chain_config = { ...default_config[chainId + ''] };
-        // Schutz vor Config-Manipulation durch Deep-Freeze
+        // Protect against config manipulation (deep-freeze at sensitive boundaries)
         const baseConfig = {
             chains: {},
             trusted_checkpoint: undefined,
@@ -208,7 +84,7 @@ export default class C4Client {
             ...config, // User config overrides defaults
             chainId,
         };
-        // Schutz vor Config-Manipulation anwenden
+        // Apply config immutability/protection
         PrototypeProtection.protectConfig(baseConfig, ['rpcs', 'beacon_apis', 'prover', 'checkpointz']);
         this.config = baseConfig;
         if (!this.config.warningHandler)
@@ -216,25 +92,38 @@ export default class C4Client {
         if (!this.config.proofStrategy)
             this.config.proofStrategy = Strategy.VerifyIfPossible;
         this.eventEmitter = new EventEmitter();
-        this.connectionState = new ConnectionState({ chainId: parseInt(this.config.chainId + ''), debug: this.config.debug }, async () => this.rpc('eth_chainId', [], C4MethodType.LOCAL), // Use the specific callback
+        this.connectionState = new ConnectionState({ chainId: parseInt(this.config.chainId + ''), debug: this.config.debug }, async () => this.rpc('eth_chainId', [], C4MethodType.LOCAL), // specific callback to detect chainId
         this.eventEmitter);
         this.subscriptionManager = new SubscriptionManager(async (method, params) => this.rpc(method, params), this.eventEmitter, {
             debug: this.config.debug,
             pollingInterval: this.config.pollingInterval || chain_conf(this.config, this.config.chainId)?.pollingInterval || 12000
         });
     }
-    async getProverConfig() {
-        const c4w = await getC4w();
-        if (!c4w.storage)
-            return '0x';
-        const state = c4w.storage.get('states_' + this.config.chainId);
-        return '0x' + (state ? Array.from(state).map(_ => _.toString(16).padStart(2, '0')).join('') : '');
-    }
-    get flags() {
-        return this.config.include_code ? 1 : 0;
+    // Prover config helpers are moved to wasm.ts (get_prover_config_hex)
+    async fetch_checkpointz() {
+        let checkpoint = undefined;
+        for (const url of [...(this.config.checkpointz || []), ...(this.config.beacon_apis || []), ...(this.config.prover || [])]) {
+            const response = await fetch(url + (url.endsWith('/') ? '' : '/') + 'eth/v1/beacon/states/head/finality_checkpoints', {
+                method: 'GET',
+                headers: {
+                    "Content-Type": "application/json"
+                }
+            });
+            if (response.ok) {
+                const res = await response.json();
+                checkpoint = res?.data?.finalized?.root;
+                if (checkpoint)
+                    break;
+            }
+        }
+        if (!checkpoint)
+            throw new Error('No checkpoint found');
+        this.config.trusted_checkpoint = checkpoint;
+        // set trusted checkpoint in C state so we can use it in proof calls immediately
+        await set_trusted_checkpoint(this.config.chainId, checkpoint);
     }
     /**
-     * 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
      */
@@ -246,7 +135,7 @@ export default class C4Client {
         return method_type;
     }
     /**
-     * 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
@@ -279,7 +168,7 @@ export default class C4Client {
         }
     }
     /**
-     * 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
@@ -316,10 +205,10 @@ export default class C4Client {
         }
     }
     /**
-     * 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
@@ -327,7 +216,12 @@ export default class C4Client {
     async rpc(method, args, method_type) {
         // eth_subscribe and eth_unsubscribe are handled by C4Client.request before this method is called.
         // This rpc method is for the underlying data fetching/proving.
-        // Spezielle Behandlung für eth_sendTransaction mit Verifikation
+        if (!this.initMap.get(this.config.chainId)) {
+            this.initMap.set(this.config.chainId, true);
+            if (this.config.checkpointz && this.config.checkpointz.length > 0 && !this.config.trusted_checkpoint && (await get_prover_config_hex(this.config.chainId)).length == 2)
+                await this.fetch_checkpointz();
+        }
+        // Special handling for eth_sendTransaction with verification
         if (method === 'eth_sendTransaction' && this.config.verifyTransactions) {
             return await TransactionVerifier.verifyAndSendTransaction(args[0], this.config, (method, args, methodType) => this.rpc(method, args, methodType), fetch_rpc);
         }
@@ -339,7 +233,7 @@ export default class C4Client {
                     return await fetch_rpc(this.config.rpcs, { method, params: args }, false);
                 }
                 const proof = this.config.prover && this.config.prover.length
-                    ? await fetch_rpc(this.config.prover, { method, params: cleanup_args(method, args), c4: await this.getProverConfig() }, true)
+                    ? await fetch_rpc(this.config.prover, { method, params: cleanup_args(method, args), c4: await get_prover_config_hex(this.config.chainId) }, true)
                     : await this.createProof(method, args);
                 return this.verifyProof(method, args, proof);
             }
@@ -385,6 +279,12 @@ export default class C4Client {
             throw providerError;
         }
     }
+    /**
+     * 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, callback) {
         this.eventEmitter.on(event, callback);
         if ((event === 'connect' || event === 'disconnect') && !this.connectionState.initialConnectionAttempted) {
@@ -395,6 +295,12 @@ export default class C4Client {
         }
         return 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, callback) {
         this.eventEmitter.removeListener(event, callback);
         return this;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@corpus-core/colibri-stateless",
-    "version": "0.7.6",
+    "version": "0.7.7",
     "description": "Colibri is a stateless and trustless ethereum client, which is optimized for the mobile apps or embedded devices, because it does not hols the state, but verifies on demand.",
     "main": "index.js",
     "type": "module",
@@ -10,7 +10,8 @@
         "test:webpack": "npm run webpack:install && npm run webpack:build",
         "webpack:install": "cd webpack && npm install --legacy-peer-deps",
         "webpack:build": "cd webpack && npm run build",
-        "webpack:start": "cd webpack && npm run start"
+        "webpack:start": "cd webpack && npm run start",
+        "check:cors": "node scripts/check_cors.mjs"
     },
     "repository": {
         "type": "git",

package/wasm.d.ts

@@ -48,6 +48,11 @@ export interface Storage {
 export type C4WModule = {
     then: (cb: (mod: C4W) => void) => void;
 };
+/**
+ * Optionally override the URL/path used to load the WASM binary when not embedded.
+ * @param url Absolute/relative URL in browsers, or filesystem path in Node.
+ */
+export declare function set_wasm_url(url: string): void;
 export declare function loadC4WModule(): Promise<C4W>;
 export declare function getC4w(): Promise<C4W>;
 export declare function get_default_storage(): Promise<Storage>;
@@ -55,3 +60,15 @@ export declare function as_char_ptr(str: string, c4w: C4W, free_ptrs?: number[])
 export declare function as_json(ptr: number, c4w: C4W, free_ptrs?: number[] | boolean): any;
 export declare function as_bytes(ptr: number, len: number, c4w: C4W, free_ptrs?: number[] | boolean): Uint8Array;
 export declare function copy_to_c(data: Uint8Array, c4w: C4W, free_ptrs?: number[]): number;
+/**
+ * Returns the prover config state for a given chain as hex string with 0x prefix.
+ * @param chainId Chain identifier
+ * @return Hex string (e.g. "0x...") or "0x" if no state present
+ */
+export declare function get_prover_config_hex(chainId: number): Promise<string>;
+/**
+ * Sets the trusted checkpoint inside the C context to initialize state.
+ * @param chainId Chain identifier
+ * @param checkpoint Trusted checkpoint root hex string
+ */
+export declare function set_trusted_checkpoint(chainId: number, checkpoint: string): Promise<void>;

package/wasm.js

@@ -20,9 +20,25 @@
  *
  * SPDX-License-Identifier: MIT
  */
+let wasmUrlOverride = null;
+/**
+ * Optionally override the URL/path used to load the WASM binary when not embedded.
+ * @param url Absolute/relative URL in browsers, or filesystem path in Node.
+ */
+export function set_wasm_url(url) {
+    wasmUrlOverride = url;
+}
 export async function loadC4WModule() {
     const module = (await import("./c4w.js"));
-    return module.default(); // Emscripten initializes the module
+    const args = {};
+    if (wasmUrlOverride) {
+        args.locateFile = (path) => path.endsWith('.wasm') ? wasmUrlOverride : path;
+    }
+    else if (isBrowserEnvironment()) {
+        // Default browser-friendly resolution so bundlers copy the asset without extra config
+        args.locateFile = (path) => path.endsWith('.wasm') ? new URL('./c4w.wasm', import.meta.url).toString() : path;
+    }
+    return module.default(args); // Emscripten initializes the module
 }
 let module = null;
 let modulePromise = null;
@@ -134,3 +150,26 @@ export function copy_to_c(data, c4w, free_ptrs) {
         free_ptrs.push(ptr);
     return ptr;
 }
+/**
+ * Returns the prover config state for a given chain as hex string with 0x prefix.
+ * @param chainId Chain identifier
+ * @return Hex string (e.g. "0x...") or "0x" if no state present
+ */
+export async function get_prover_config_hex(chainId) {
+    const c4w = await getC4w();
+    if (!c4w.storage)
+        return '0x';
+    const state = c4w.storage.get('states_' + chainId);
+    return '0x' + (state ? Array.from(state).map(_ => _.toString(16).padStart(2, '0')).join('') : '');
+}
+/**
+ * Sets the trusted checkpoint inside the C context to initialize state.
+ * @param chainId Chain identifier
+ * @param checkpoint Trusted checkpoint root hex string
+ */
+export async function set_trusted_checkpoint(chainId, checkpoint) {
+    const c4w = await getC4w();
+    const free_buffers = [];
+    c4w._c4w_create_verify_ctx(0, 0, 0, 0, BigInt(chainId), as_char_ptr(checkpoint, c4w, free_buffers));
+    free_buffers.forEach(ptr => c4w._free(ptr));
+}