@corpus-core/colibri-stateless 1.1.0 → 1.1.2

package/cjs/index.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrototypeProtection = exports.TransactionVerifier = exports.MethodType = exports.ProviderRpcError = exports.set_wasm_url = exports.Strategy = void 0;
+// Import the Emscripten-generated module
+const wasm_js_1 = require("./wasm.js");
+const eventEmitter_js_1 = require("./eventEmitter.js");
+const connectionState_js_1 = require("./connectionState.js");
+const types_js_1 = require("./types.js");
+Object.defineProperty(exports, "ProviderRpcError", { enumerable: true, get: function () { return types_js_1.ProviderRpcError; } });
+Object.defineProperty(exports, "MethodType", { enumerable: true, get: function () { return types_js_1.MethodType; } });
+const chains_js_1 = require("./chains.js");
+const subscriptionManager_js_1 = require("./subscriptionManager.js");
+const strategy_js_1 = require("./strategy.js");
+exports.Strategy = strategy_js_1.default;
+const transactionVerifier_js_1 = require("./transactionVerifier.js");
+const http_js_1 = require("./http.js");
+// Public helper for controlling WASM loading behavior in Node/bundlers.
+var wasm_js_2 = require("./wasm.js");
+Object.defineProperty(exports, "set_wasm_url", { enumerable: true, get: function () { return wasm_js_2.set_wasm_url; } });
+// Re-export transaction verification utilities
+var transactionVerifier_js_2 = require("./transactionVerifier.js");
+Object.defineProperty(exports, "TransactionVerifier", { enumerable: true, get: function () { return transactionVerifier_js_2.TransactionVerifier; } });
+Object.defineProperty(exports, "PrototypeProtection", { enumerable: true, get: function () { return transactionVerifier_js_2.PrototypeProtection; } });
+// 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 => ({
+            transactionIndex: arg.transactionIndex,
+            blockNumber: arg.blockNumber
+        }));
+    return args;
+}
+class C4Client {
+    config;
+    eventEmitter;
+    connectionState;
+    subscriptionManager;
+    initMap = new Map();
+    flags = 0;
+    // Protect against prototype pollution by freezing critical methods
+    static CRITICAL_METHODS = ['rpc', 'request', 'verifyProof', 'createProof'];
+    static {
+        // Apply prototype pollution protection
+        transactionVerifier_js_1.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 ? (0, chains_js_1.get_chain_id)(config?.chainId + '') : 1;
+        const chain_config = { ...chains_js_1.default_config[chainId + ''] };
+        // Protect against config manipulation (deep-freeze at sensitive boundaries)
+        const baseConfig = {
+            chains: {},
+            trusted_checkpoint: undefined,
+            rpcs: chain_config.rpcs || [],
+            beacon_apis: chain_config.beacon_apis || [],
+            prover: chain_config.prover || [],
+            checkpointz: chain_config.checkpointz || [],
+            ...config, // User config overrides defaults
+            chainId,
+        };
+        // Apply config immutability/protection
+        transactionVerifier_js_1.PrototypeProtection.protectConfig(baseConfig, ['rpcs', 'beacon_apis', 'prover', 'checkpointz']);
+        this.config = baseConfig;
+        if (!this.config.warningHandler)
+            this.config.warningHandler = async (req, message) => console.warn(message);
+        if (!this.config.proofStrategy)
+            this.config.proofStrategy = strategy_js_1.default.VerifyIfPossible;
+        this.eventEmitter = new eventEmitter_js_1.EventEmitter();
+        this.connectionState = new connectionState_js_1.ConnectionState({ chainId: parseInt(this.config.chainId + ''), debug: this.config.debug }, async () => this.rpc('eth_chainId', [], types_js_1.MethodType.LOCAL), // specific callback to detect chainId
+        this.eventEmitter);
+        this.subscriptionManager = new subscriptionManager_js_1.SubscriptionManager(async (method, params) => this.rpc(method, params), this.eventEmitter, {
+            debug: this.config.debug,
+            pollingInterval: this.config.pollingInterval || (0, chains_js_1.chain_conf)(this.config, this.config.chainId)?.pollingInterval || 12000
+        });
+    }
+    // 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 (0, wasm_js_1.set_trusted_checkpoint)(this.config.chainId, checkpoint);
+    }
+    /**
+     * Checks whether the RPC method is supported or proofable.
+     * @param method - The method to check
+     * @returns The method type
+     */
+    async getMethodSupport(method) {
+        const c4w = await (0, wasm_js_1.getC4w)();
+        const free_buffers = [];
+        const method_type = c4w._c4w_get_method_type(BigInt(this.config.chainId), (0, wasm_js_1.as_char_ptr)(method, c4w, free_buffers));
+        free_buffers.forEach(ptr => c4w._free(ptr));
+        return method_type;
+    }
+    /**
+     * 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
+     */
+    async createProof(method, args) {
+        const c4w = await (0, wasm_js_1.getC4w)();
+        const free_buffers = [];
+        let ctx = 0;
+        try {
+            // Call the C function
+            ctx = c4w._c4w_create_proof_ctx((0, wasm_js_1.as_char_ptr)(method, c4w, free_buffers), (0, wasm_js_1.as_char_ptr)(JSON.stringify(args), c4w, free_buffers), BigInt(this.config.chainId), this.flags);
+            while (true) {
+                const state = (0, wasm_js_1.as_json)(c4w._c4w_execute_proof_ctx(ctx), c4w, true);
+                switch (state.status) {
+                    case "success":
+                        return (0, wasm_js_1.as_bytes)(state.result, state.result_len, c4w);
+                    case "error":
+                        throw new Error(state.error);
+                    case "waiting": {
+                        await Promise.all(state.requests.map((req) => (0, http_js_1.handle_request)(req, this.config)));
+                        break;
+                    }
+                }
+            }
+        }
+        finally {
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            if (ctx)
+                c4w._c4w_free_proof_ctx(ctx);
+        }
+    }
+    /**
+     * 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
+     * @returns The result
+     */
+    async verifyProof(method, args, proof) {
+        const c4w = await (0, wasm_js_1.getC4w)();
+        const free_buffers = [];
+        let ctx = 0;
+        try {
+            // Call the C function
+            const checkpoint_ptr = this.config.trusted_checkpoint
+                ? (0, wasm_js_1.as_char_ptr)(this.config.trusted_checkpoint, c4w, free_buffers)
+                : 0;
+            const witness_keys_ptr = this.config.checkpoint_witness_keys
+                ? (0, wasm_js_1.as_char_ptr)(this.config.checkpoint_witness_keys, c4w, free_buffers)
+                : 0;
+            ctx = c4w._c4w_create_verify_ctx((0, wasm_js_1.copy_to_c)(proof, c4w, free_buffers), proof.length, (0, wasm_js_1.as_char_ptr)(method, c4w, free_buffers), (0, wasm_js_1.as_char_ptr)(JSON.stringify(args), c4w, free_buffers), BigInt(this.config.chainId), checkpoint_ptr, witness_keys_ptr);
+            while (true) {
+                const state = (0, wasm_js_1.as_json)(c4w._c4w_verify_proof(ctx), c4w, true);
+                switch (state.status) {
+                    case "success":
+                        return state.result;
+                    case "error":
+                        throw new Error(state.error);
+                    case "waiting": {
+                        await Promise.all(state.requests.map((req) => (0, http_js_1.handle_request)(req, this.config)));
+                        break;
+                    }
+                }
+            }
+        }
+        finally {
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            if (ctx)
+                c4w._c4w_free_verify_ctx(ctx);
+        }
+    }
+    /**
+     * 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
+     */
+    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.
+        if (!this.initMap.get(this.config.chainId)) {
+            this.initMap.set(this.config.chainId, true);
+            if (!this.config.zk_proof && this.config.checkpointz && this.config.checkpointz.length > 0 && !this.config.trusted_checkpoint && (await (0, wasm_js_1.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_js_1.TransactionVerifier.verifyAndSendTransaction(args[0], this.config, (method, args, methodType) => this.rpc(method, args, methodType), http_js_1.fetch_rpc);
+        }
+        if (method_type === undefined)
+            method_type = await this.getMethodSupport(method);
+        switch (method_type) {
+            case types_js_1.MethodType.PROOFABLE: {
+                if (this.config.verify && !this.config.verify(method, args)) {
+                    // skip verification and fetch directly
+                    return await (0, http_js_1.fetch_rpc)(this.config.rpcs, { method, params: args }, false);
+                }
+                const proof = this.config.prover && this.config.prover.length
+                    ? await (0, http_js_1.fetch_rpc)(this.config.prover, {
+                        method,
+                        params: cleanup_args(method, args),
+                        c4: await (0, wasm_js_1.get_prover_config_hex)(this.config.chainId),
+                        zk_proof: !!this.config.zk_proof,
+                        signers: this.config.checkpoint_witness_keys || '0x'
+                    }, true)
+                    : await this.createProof(method, args);
+                return this.verifyProof(method, args, proof);
+            }
+            case types_js_1.MethodType.UNPROOFABLE:
+                return await (0, http_js_1.fetch_rpc)(this.config.rpcs, { method, params: args }, false);
+            case types_js_1.MethodType.NOT_SUPPORTED:
+                throw new types_js_1.ProviderRpcError(4200, `Method ${method} is not supported by C4Client.rpc core`);
+            case types_js_1.MethodType.LOCAL:
+                return this.verifyProof(method, args, new Uint8Array());
+        }
+        // Should be unreachable if MethodType enum is comprehensive and handled
+        throw new types_js_1.ProviderRpcError(-32603, `Internal error: Unhandled method type for ${method} in C4Client.rpc core`);
+    }
+    static async register_storage(storage) {
+        const c4w = await (0, wasm_js_1.getC4w)();
+        c4w.storage = storage;
+    }
+    async request(args) {
+        if (!this.connectionState.initialConnectionAttempted) {
+            await this.connectionState.attemptInitialConnection();
+        }
+        const { method, params } = args;
+        const paramsArray = Array.isArray(params) ? params : (params ? [params] : []);
+        // Attempt to handle with SubscriptionManager first
+        const subscriptionResult = this.subscriptionManager.handleRequest(method, paramsArray);
+        if (subscriptionResult !== null) {
+            // If handleRequest returns a Promise, it means it's handling the request
+            return subscriptionResult;
+        }
+        let conf = (0, chains_js_1.chain_conf)(this.config, this.config.chainId);
+        let strategy = conf?.proofStrategy || this.config.proofStrategy;
+        // If not handled by SubscriptionManager, proceed with standard RPC call logic
+        try {
+            const result = strategy
+                ? await strategy(this, args, this.config, http_js_1.fetch_rpc)
+                : await this.rpc(method, paramsArray);
+            this.connectionState.processSuccessfulRequest(method, result);
+            return result;
+        }
+        catch (error) {
+            const providerError = types_js_1.ProviderRpcError.createError(error, args);
+            this.connectionState.processFailedRequest(providerError);
+            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) {
+            this.connectionState.attemptInitialConnection().catch(err => {
+                if (this.config.debug)
+                    console.error("[C4Client] Error during lazy initial connection attempt triggered by 'on':", err);
+            });
+        }
+        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;
+    }
+}
+exports.default = C4Client;

package/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/cjs/strategy.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_js_1 = require("./types.js");
+function argsToArray(args) {
+    return Array.isArray(args) ? args : (args ? [args] : []);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a.constructor !== b.constructor)
+        return false;
+    if (a instanceof Date)
+        return a.getTime() === b.getTime();
+    if (a instanceof RegExp)
+        return a.source === b.source && a.flags === b.flags;
+    if (a instanceof Uint8Array)
+        return a.length === b.length && a.every((value, index) => value === b[index]);
+    if (a instanceof Array)
+        return a.length === b.length && a.every((value, index) => deepEqual(value, b[index]));
+    if (a instanceof Object)
+        return Object.keys(a).every(key => b[key] === undefined || deepEqual(a[key], b[key]));
+    if (a instanceof String)
+        return a.toLowerCase() === b.toLowerCase();
+    if (a instanceof Number)
+        return a.toFixed(10) === b.toFixed(10);
+    if (a instanceof Boolean)
+        return a === b;
+    if (a instanceof BigInt)
+        return a.toString() === b.toString();
+    if (a instanceof Buffer)
+        return a.equals(b);
+    if (a instanceof Map)
+        return a.size === b.size && Array.from(a.entries()).every(([key, value]) => deepEqual(value, b.get(key)));
+    if (a instanceof Set)
+        return a.size === b.size && Array.from(a).every(value => b.has(value));
+    if (a instanceof Date)
+        return a.getTime() === b.getTime();
+    return a == b;
+}
+function fetch_unverified_rpc(config, req, fetch_rpc) {
+    const fallback_provider = config.fallback_provider;
+    if (fallback_provider)
+        return fallback_provider.request(req);
+    let conf = config.chains[config.chainId];
+    let rpcs = conf?.rpcs || config.rpcs;
+    if (!rpcs || !Array.isArray(rpcs) || rpcs.length === 0)
+        throw new Error("No RPC- Endpoint configured");
+    return fetch_rpc(rpcs, req, false);
+}
+function OnlyProofStrategy(client, req, config, fetch_rpc) {
+    return client.rpc(req.method, argsToArray(req.params));
+}
+async function ProofIfPossibleStrategy(client, req, config, fetch_rpc) {
+    const method_type = await client.getMethodSupport(req.method);
+    switch (method_type) {
+        case types_js_1.MethodType.PROOFABLE:
+        case types_js_1.MethodType.LOCAL:
+            return client.rpc(req.method, argsToArray(req.params), method_type);
+        default:
+            return fetch_unverified_rpc(config, req, fetch_rpc);
+    }
+}
+async function WarningStrategy(client, req, config, fetch_rpc) {
+    const method_type = await client.getMethodSupport(req.method);
+    switch (method_type) {
+        case types_js_1.MethodType.LOCAL:
+            return client.rpc(req.method, argsToArray(req.params), method_type);
+        case types_js_1.MethodType.UNPROOFABLE:
+        case types_js_1.MethodType.NOT_SUPPORTED:
+            return fetch_unverified_rpc(config, req, fetch_rpc);
+        case types_js_1.MethodType.PROOFABLE: {
+            const [verified_result, unverified_result] = await Promise.all([
+                client.rpc(req.method, argsToArray(req.params), types_js_1.MethodType.PROOFABLE)
+                    .catch(async (err) => {
+                    await config.warningHandler(req, `[Warning] ${req.method} failed to be verfiy: ${err.message}, falling back to Default`);
+                    return undefined;
+                }),
+                fetch_unverified_rpc(config, req, fetch_rpc)
+            ]);
+            if (verified_result !== undefined && !deepEqual(verified_result, unverified_result))
+                await config.warningHandler(req, `[Warning] ${req.method} does not match the rpc-result`);
+            return unverified_result;
+        }
+    }
+}
+exports.default = {
+    VerifiedOnly: OnlyProofStrategy,
+    VerifyIfPossible: ProofIfPossibleStrategy,
+    WarningWithFallback: WarningStrategy
+};