@corpus-core/colibri-stateless 2.0.4 → 2.0.6

package/runtime.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2026 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 type { DataRequest } from './types.js';
+import type { Storage } from './wasm_shared.js';
+export type { Storage };
+/**
+ * Opaque handle for a native/WASM context (prover, verifier or rpc).
+ * WASM uses heap pointers (numbers), the native addon uses externals.
+ */
+export type CtxHandle = unknown;
+/**
+ * Parsed JSON status as returned by the C status-builder functions.
+ * For the prover, `result` is materialized as `Uint8Array` (the proof).
+ * For verify/rpc, `result` is the parsed JSON result value.
+ */
+export interface RuntimeStatus {
+    status: 'success' | 'error' | 'pending' | 'revert';
+    result?: any;
+    error?: string;
+    /** Revert data (EIP-3668 / CCIP-Read) when status is 'revert'. */
+    data?: any;
+    requests?: DataRequest[];
+}
+/**
+ * Value-level abstraction over the C core, implemented by the WASM build
+ * (`runtime_wasm.ts`) and the native Node.js addon (`runtime_node.ts`).
+ *
+ * All methods are synchronous: implementations are fully initialized when
+ * returned by `getRuntime()`.
+ */
+export interface C4Runtime {
+    readonly kind: 'wasm' | 'native';
+    getMethodType(chainId: bigint, method: string, paramsJson: string | null, flags: number): number;
+    createProverCtx(method: string, argsJson: string, chainId: bigint, flags: number): CtxHandle;
+    /** Executes one prover step. On success, `result` contains the proof bytes. */
+    executeProverCtx(ctx: CtxHandle): RuntimeStatus;
+    freeProverCtx(ctx: CtxHandle): void;
+    createVerifyCtx(proof: Uint8Array, method: string, argsJson: string, chainId: bigint, trustedCheckpoint: string | null, witnessKeys: string | null, flags: number, minLatestBlockTs: bigint): CtxHandle;
+    verifyProof(ctx: CtxHandle): RuntimeStatus;
+    freeVerifyCtx(ctx: CtxHandle): void;
+    createRpcCtx(method: string, paramsJson: string, chainId: bigint, proverFlags: number, verifyFlags: number, proverMode: number): CtxHandle;
+    executeRpcCtx(ctx: CtxHandle): RuntimeStatus;
+    freeRpcCtx(ctx: CtxHandle): void;
+    rpcCtxSetProxyUrls(ctx: CtxHandle, rpcUrls: string, beaconUrls: string): void;
+    rpcCtxSetWitnessKeys(ctx: CtxHandle, keys: string): void;
+    rpcCtxSetMinLatestBlockTs(ctx: CtxHandle, ts: bigint): void;
+    setCheckpoint(chainId: bigint, checkpoint: string): void;
+    reqSetResponse(req: DataRequest, data: Uint8Array, nodeIndex: number): void;
+    reqSetError(req: DataRequest, error: string, nodeIndex: number): void;
+    decodeProof(proof: Uint8Array): any;
+    registerStorage(storage: Storage): void;
+}
+export type RuntimeProvider = () => Promise<C4Runtime>;
+/**
+ * Replaces the runtime provider (e.g. native addon in Node.js).
+ *
+ * Intended to be called once by the entry point before the first
+ * `getRuntime()` use. Calling it later resets the cached runtime, so the
+ * next `getRuntime()` initializes the new provider - context handles
+ * created by the previous runtime must not be used afterwards.
+ * @param provider Factory returning an initialized runtime
+ */
+export declare function setRuntimeProvider(provider: RuntimeProvider): void;
+/**
+ * Returns the active runtime (initialized lazily, cached afterwards).
+ * @return The active C4Runtime instance
+ */
+export declare function getRuntime(): Promise<C4Runtime>;

package/runtime.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 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
+ */
+// The active provider defaults to the WASM runtime and is replaced by the
+// Node entry point (`index.node.ts`) with the native-first provider.
+// Lazy import keeps browser bundles free of unused code paths.
+let activeProvider = async () => (await import('./runtime_wasm.js')).getWasmRuntime();
+let cached = null;
+/**
+ * Replaces the runtime provider (e.g. native addon in Node.js).
+ *
+ * Intended to be called once by the entry point before the first
+ * `getRuntime()` use. Calling it later resets the cached runtime, so the
+ * next `getRuntime()` initializes the new provider - context handles
+ * created by the previous runtime must not be used afterwards.
+ * @param provider Factory returning an initialized runtime
+ */
+export function setRuntimeProvider(provider) {
+    activeProvider = provider;
+    cached = null;
+}
+/**
+ * Returns the active runtime (initialized lazily, cached afterwards).
+ * @return The active C4Runtime instance
+ */
+export function getRuntime() {
+    if (!cached)
+        cached = activeProvider();
+    return cached;
+}

package/runtime_node.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026 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 type { C4Runtime } from './runtime.js';
+/**
+ * Returns the (cached) Node runtime: native addon if available, otherwise WASM.
+ * @return Initialized runtime
+ */
+export declare function getNodeRuntime(): Promise<C4Runtime>;

package/runtime_node.js

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) 2026 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 { get_default_storage } from './wasm_shared.js';
+import { module_dir } from './wasm.js';
+async function loadNativeBinding() {
+    const { createRequire } = await import('node:module');
+    const { join, dirname } = await import('node:path');
+    const fs = await import('node:fs');
+    // Directory of the compiled JS: resolved by wasm.ts (ESM: import.meta.url)
+    // or wasm_cjs.ts (CJS: __dirname), which are swapped at build time.
+    const dir = await module_dir();
+    const requireNative = createRequire(join(dir, 'noop.js'));
+    const candidates = [];
+    if (process.env.C4_NATIVE_ADDON)
+        candidates.push(process.env.C4_NATIVE_ADDON);
+    const target = `${process.platform}-${process.arch}`;
+    // The CJS build lives in a `cjs/` subfolder; prebuilds sit at the package root.
+    candidates.push(join(dir, 'prebuilds', target, 'colibri_native.node'));
+    candidates.push(join(dirname(dir), 'prebuilds', target, 'colibri_native.node'));
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return requireNative(candidate);
+    }
+    throw new Error(`no native colibri addon found for ${target} (checked: ${candidates.join(', ')})`);
+}
+function createNativeRuntime(binding) {
+    // Most methods are direct pass-throughs (N-API functions don't need `this`);
+    // only status parsing and the req_ptr string conversion add logic.
+    return {
+        kind: 'native',
+        getMethodType: binding.getMethodType,
+        createProverCtx: binding.createProverCtx,
+        executeProverCtx(ctx) {
+            const state = JSON.parse(binding.executeProverCtx(ctx));
+            // The JSON status carries the proof as native pointer (unusable in JS);
+            // fetch the bytes through the dedicated accessor instead.
+            if (state.status === 'success')
+                state.result = binding.getProof(ctx);
+            return state;
+        },
+        freeProverCtx: binding.freeProverCtx,
+        createVerifyCtx: binding.createVerifyCtx,
+        verifyProof: (ctx) => JSON.parse(binding.verifyProof(ctx)),
+        freeVerifyCtx: binding.freeVerifyCtx,
+        createRpcCtx: binding.createRpcCtx,
+        executeRpcCtx: (ctx) => JSON.parse(binding.executeRpcCtx(ctx)),
+        freeRpcCtx: binding.freeRpcCtx,
+        rpcCtxSetProxyUrls: binding.rpcCtxSetProxyUrls,
+        rpcCtxSetWitnessKeys: binding.rpcCtxSetWitnessKeys,
+        rpcCtxSetMinLatestBlockTs: binding.rpcCtxSetMinLatestBlockTs,
+        setCheckpoint: binding.setCheckpoint,
+        reqSetResponse: (req, data, nodeIndex) => binding.reqSetResponse(String(req.req_ptr), data, nodeIndex),
+        reqSetError: (req, error, nodeIndex) => binding.reqSetError(String(req.req_ptr), error, nodeIndex),
+        decodeProof(proof) {
+            const json = binding.decodeProof(proof);
+            if (!json)
+                throw new Error('Unknown proof format');
+            return JSON.parse(json);
+        },
+        registerStorage: binding.registerStorage,
+    };
+}
+let runtime = null;
+async function initNodeRuntime() {
+    if (process.env.C4_DISABLE_NATIVE !== '1') {
+        try {
+            const binding = await loadNativeBinding();
+            const rt = createNativeRuntime(binding);
+            // Same default persistence behavior as the WASM runtime (fs-based in Node).
+            rt.registerStorage(await get_default_storage());
+            return rt;
+        }
+        catch (e) {
+            if (process.env.C4_FORCE_NATIVE === '1')
+                throw e;
+            if (process.env.C4_DEBUG_NATIVE === '1')
+                console.warn('colibri: native addon unavailable, falling back to WASM:', e);
+        }
+    }
+    return (await import('./runtime_wasm.js')).getWasmRuntime();
+}
+/**
+ * Returns the (cached) Node runtime: native addon if available, otherwise WASM.
+ * @return Initialized runtime
+ */
+export function getNodeRuntime() {
+    if (!runtime)
+        runtime = initNodeRuntime();
+    return runtime;
+}

package/runtime_wasm.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026 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 type { C4Runtime } from './runtime.js';
+/**
+ * Returns the (cached) WASM-backed runtime.
+ * @return Initialized WASM runtime
+ */
+export declare function getWasmRuntime(): Promise<C4Runtime>;

package/runtime_wasm.js

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2026 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 } from './wasm.js';
+import { as_bytes, as_char_ptr, as_json, copy_to_c } from './wasm_shared.js';
+// The WASM runtime wraps the pointer-level Emscripten API (`C4W`) behind the
+// value-level `C4Runtime` interface. The module is loaded once via `getC4w()`.
+// Note: the historical c4w_* exports say "proof_ctx" where the core C API
+// (and this interface) say "prover" (c4_prover_create etc.).
+function createRuntime(c4w) {
+    return {
+        kind: 'wasm',
+        getMethodType(chainId, method, paramsJson, flags) {
+            const free_buffers = [];
+            const type = c4w._c4w_get_method_type(chainId, as_char_ptr(method, c4w, free_buffers), paramsJson ? as_char_ptr(paramsJson, c4w, free_buffers) : 0, flags);
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            return type;
+        },
+        createProverCtx(method, argsJson, chainId, flags) {
+            const free_buffers = [];
+            const ctx = c4w._c4w_create_proof_ctx(as_char_ptr(method, c4w, free_buffers), as_char_ptr(argsJson, c4w, free_buffers), chainId, flags);
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            return ctx;
+        },
+        executeProverCtx(ctx) {
+            const state = as_json(c4w._c4w_execute_proof_ctx(ctx), c4w, true);
+            // On success the JSON carries the proof as heap pointer + length
+            // (owned by the prover ctx); materialize it as bytes.
+            if (state.status === 'success')
+                state.result = as_bytes(state.result, state.result_len, c4w);
+            return state;
+        },
+        freeProverCtx(ctx) {
+            c4w._c4w_free_proof_ctx(ctx);
+        },
+        createVerifyCtx(proof, method, argsJson, chainId, trustedCheckpoint, witnessKeys, flags, minLatestBlockTs) {
+            const free_buffers = [];
+            const ctx = c4w._c4w_create_verify_ctx(copy_to_c(proof, c4w, free_buffers), proof.length, as_char_ptr(method, c4w, free_buffers), as_char_ptr(argsJson, c4w, free_buffers), chainId, trustedCheckpoint ? as_char_ptr(trustedCheckpoint, c4w, free_buffers) : 0, witnessKeys ? as_char_ptr(witnessKeys, c4w, free_buffers) : 0, flags, minLatestBlockTs);
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            return ctx;
+        },
+        verifyProof(ctx) {
+            return as_json(c4w._c4w_verify_proof(ctx), c4w, true);
+        },
+        freeVerifyCtx(ctx) {
+            c4w._c4w_free_verify_ctx(ctx);
+        },
+        createRpcCtx(method, paramsJson, chainId, proverFlags, verifyFlags, proverMode) {
+            const free_buffers = [];
+            const ctx = c4w._c4w_create_rpc_ctx(as_char_ptr(method, c4w, free_buffers), as_char_ptr(paramsJson, c4w, free_buffers), chainId, proverFlags, verifyFlags, proverMode);
+            free_buffers.forEach(ptr => c4w._free(ptr));
+            return ctx;
+        },
+        executeRpcCtx(ctx) {
+            return as_json(c4w._c4w_execute_rpc_ctx(ctx), c4w, true);
+        },
+        freeRpcCtx(ctx) {
+            c4w._c4w_free_rpc_ctx(ctx);
+        },
+        rpcCtxSetProxyUrls(ctx, rpcUrls, beaconUrls) {
+            const free_buffers = [];
+            c4w._c4w_rpc_ctx_set_proxy_urls(ctx, as_char_ptr(rpcUrls, c4w, free_buffers), as_char_ptr(beaconUrls, c4w, free_buffers));
+            free_buffers.forEach(ptr => c4w._free(ptr));
+        },
+        rpcCtxSetWitnessKeys(ctx, keys) {
+            const free_buffers = [];
+            c4w._c4w_rpc_ctx_set_witness_keys(ctx, as_char_ptr(keys, c4w, free_buffers));
+            free_buffers.forEach(ptr => c4w._free(ptr));
+        },
+        rpcCtxSetMinLatestBlockTs(ctx, ts) {
+            c4w._c4w_rpc_ctx_set_min_latest_block_ts(ctx, ts);
+        },
+        setCheckpoint(chainId, checkpoint) {
+            const free_buffers = [];
+            c4w._c4w_set_checkpoint(chainId, as_char_ptr(checkpoint, c4w, free_buffers));
+            free_buffers.forEach(ptr => c4w._free(ptr));
+        },
+        reqSetResponse(req, data, nodeIndex) {
+            // ownership of the copied bytes is transferred to the C context
+            c4w._c4w_req_set_response(req.req_ptr, copy_to_c(data, c4w), data.length, nodeIndex);
+        },
+        reqSetError(req, error, nodeIndex) {
+            const free_buffers = [];
+            c4w._c4w_req_set_error(req.req_ptr, as_char_ptr(error, c4w, free_buffers), nodeIndex);
+            free_buffers.forEach(ptr => c4w._free(ptr));
+        },
+        decodeProof(proof) {
+            const free_buffers = [];
+            const ptr = copy_to_c(proof, c4w, free_buffers);
+            const resultPtr = c4w._c4w_decode_proof(ptr, proof.length);
+            free_buffers.forEach(p => c4w._free(p));
+            if (!resultPtr)
+                throw new Error('Unknown proof format');
+            return as_json(resultPtr, c4w, true);
+        },
+        registerStorage(storage) {
+            c4w.storage = storage;
+        },
+    };
+}
+let runtime = null;
+/**
+ * Returns the (cached) WASM-backed runtime.
+ * @return Initialized WASM runtime
+ */
+export function getWasmRuntime() {
+    if (!runtime)
+        runtime = getC4w().then(createRuntime);
+    return runtime;
+}

package/types.d.ts

@@ -131,7 +131,10 @@ export interface DataRequest {
     exclude_mask: number;
     url: string;
     payload: any;
-    req_ptr: number;
+    /** Opaque pointer to the underlying `data_request_t`: a heap address (number)
+     *  in the WASM runtime, or a decimal string in the native Node.js runtime
+     *  (64-bit pointers are not safely representable as JS numbers). */
+    req_ptr: number | string;
     /** Milliseconds to wait before (re-)executing this request (e.g. oblivious-node retry backoff). Optional. */
     delay?: number;
     /** Cache freshness bound in seconds. When set, forwarded as a `Cache-Control: max-age=<ttl>` request header so a shared cache/CDN never returns a response older than this bound (e.g. short bound for `latest` block proofs). Optional. */

package/wasm.d.ts

@@ -29,3 +29,10 @@ export declare const getC4w: () => Promise<C4W>;
 export declare const get_prover_config_hex: (chainId: number) => Promise<string>;
 export declare const set_trusted_checkpoint: (chainId: number, checkpoint: string) => Promise<void>;
 export declare const decode_proof: (proof: Uint8Array) => Promise<any>;
+/**
+ * Returns the directory of the compiled module. Used in Node to locate
+ * packaged assets (e.g. native addon prebuilds) relative to the package root.
+ * The CJS build swaps this file with `wasm_cjs.ts`, which uses `__dirname`.
+ * @return Absolute directory path of this module
+ */
+export declare function module_dir(): Promise<string>;

package/wasm.js

@@ -60,3 +60,14 @@ export const getC4w = api.getC4w;
 export const get_prover_config_hex = api.get_prover_config_hex;
 export const set_trusted_checkpoint = api.set_trusted_checkpoint;
 export const decode_proof = api.decode_proof;
+/**
+ * Returns the directory of the compiled module. Used in Node to locate
+ * packaged assets (e.g. native addon prebuilds) relative to the package root.
+ * The CJS build swaps this file with `wasm_cjs.ts`, which uses `__dirname`.
+ * @return Absolute directory path of this module
+ */
+export async function module_dir() {
+    const { fileURLToPath } = await new Function('return import("node:url")')();
+    const { dirname } = await new Function('return import("node:path")')();
+    return dirname(fileURLToPath(import.meta.url));
+}

package/wasm_cjs.d.ts

@@ -29,3 +29,10 @@ export declare const getC4w: () => Promise<C4W>;
 export declare const get_prover_config_hex: (chainId: number) => Promise<string>;
 export declare const set_trusted_checkpoint: (chainId: number, checkpoint: string) => Promise<void>;
 export declare const decode_proof: (proof: Uint8Array) => Promise<any>;
+/**
+ * Returns the directory of the compiled module. Used in Node to locate
+ * packaged assets (e.g. native addon prebuilds) relative to the package root.
+ * This CJS variant replaces `wasm.ts` (ESM, `import.meta.url`) at build time.
+ * @return Absolute directory path of this module
+ */
+export declare function module_dir(): Promise<string>;

package/wasm_cjs.js

@@ -57,3 +57,12 @@ export const getC4w = api.getC4w;
 export const get_prover_config_hex = api.get_prover_config_hex;
 export const set_trusted_checkpoint = api.set_trusted_checkpoint;
 export const decode_proof = api.decode_proof;
+/**
+ * Returns the directory of the compiled module. Used in Node to locate
+ * packaged assets (e.g. native addon prebuilds) relative to the package root.
+ * This CJS variant replaces `wasm.ts` (ESM, `import.meta.url`) at build time.
+ * @return Absolute directory path of this module
+ */
+export async function module_dir() {
+    return __dirname;
+}