@deroll/cmio 0.1.0

package/deps/machine-guest-tools/sys-utils/libcmt/src/util.c

@@ -0,0 +1,52 @@
+#include <errno.h>
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+bool cmt_util_debug_enabled(void) {
+    static bool checked = false;
+    static bool enabled = false;
+
+    if (!checked) {
+        enabled = getenv("CMT_DEBUG") != NULL;
+        checked = true;
+    }
+
+    return enabled;
+}
+
+int cmt_util_read_whole_file(const char *name, size_t max, void *data, size_t *length) {
+    int rc = 0;
+
+    FILE *file = fopen(name, "rb");
+    if (!file) {
+        return -errno;
+    }
+    *length = fread(data, 1, max, file);
+    int eof = (fseek(file, 0, SEEK_END) == 0) && (*length == (size_t) ftell(file));
+    if (!eof) {
+        rc = -EIO;
+    }
+    if (fclose(file) != 0) {
+        rc = -errno;
+    }
+    return rc;
+}
+
+int cmt_util_write_whole_file(const char *name, size_t length, const void *data) {
+    int rc = 0;
+
+    FILE *file = fopen(name, "wb");
+    if (!file) {
+        return -errno;
+    }
+
+    if (fwrite(data, 1, length, file) != length) {
+        rc = -EIO;
+    }
+    if (fclose(file) != 0) {
+        rc = -errno;
+    }
+    return rc;
+}

package/lib/index.d.mts

@@ -0,0 +1,18 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// Types for the ESM wrapper (lib/index.mjs).
+export * from './index.js';

package/lib/index.d.ts

@@ -0,0 +1,162 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+/// <reference types="node" />
+
+/** 0x-prefixed hex string. Compatible with viem's `Hex` and `Address`. */
+export type Hex = `0x${string}`;
+
+/** Bytes input: 0x-prefixed hex string, Buffer or Uint8Array. */
+export type BytesLike = Hex | Uint8Array;
+
+/** EVM address: 0x-prefixed hex string (20 bytes), Buffer or Uint8Array. */
+export type AddressLike = Hex | Uint8Array;
+
+/** Unsigned 256-bit value: bigint, number, or 32 bytes (hex string/Uint8Array). */
+export type U256Like = bigint | number | Hex | Uint8Array;
+
+export const ADDRESS_LENGTH: 20;
+export const U256_LENGTH: 32;
+
+export interface AdvanceRequest {
+    type: 'advance';
+    /** Network chain id. */
+    chainId: bigint;
+    /** Application contract address (0x-prefixed hex). */
+    appContract: Hex;
+    /** Input sender address (0x-prefixed hex). */
+    msgSender: Hex;
+    /** Block number of this input. */
+    blockNumber: bigint;
+    /** Block timestamp of this input (UNIX epoch seconds). */
+    blockTimestamp: bigint;
+    /** RANDAO mix of the post beacon state of the previous block. */
+    prevRandao: bigint;
+    /** Input index relative to all inputs ever sent to the application. */
+    index: bigint;
+    /** Input payload. */
+    payload: Buffer;
+}
+
+export interface InspectRequest {
+    type: 'inspect';
+    /** Inspect query payload. */
+    payload: Buffer;
+}
+
+export type RollupRequest = AdvanceRequest | InspectRequest;
+
+export interface GioResponse {
+    responseCode: number;
+    responseData: Buffer;
+}
+
+/** Arguments for {@link Rollup.emitVoucher}. Encoded on-chain as `Voucher(address,uint256,bytes)`. */
+export interface Voucher {
+    /** Address the voucher executes against (20 bytes): an EOA for transfers, a contract for calls. */
+    destination: AddressLike;
+    /** Amount of wei sent with the execution. Default: `0n`. */
+    value?: U256Like;
+    /** EVM calldata to execute at `destination`. Default: empty (plain transfer). */
+    payload?: BytesLike;
+}
+
+/** Arguments for {@link Rollup.emitDelegateCallVoucher}. Encoded on-chain as `DelegateCallVoucher(address,bytes)`. */
+export interface DelegateCallVoucher {
+    /** Contract whose code runs in the application contract's storage context (20 bytes). */
+    destination: AddressLike;
+    /** Calldata for the delegate call. Default: empty. There is no `value` — `DELEGATECALL` cannot transfer ether. */
+    payload?: BytesLike;
+}
+
+/**
+ * Error thrown when a libcmt binding call fails (e.g. a too-large output, or
+ * constructing a second {@link Rollup} while one is open).
+ *
+ * Argument validation failures throw plain `TypeError`/`RangeError` instead,
+ * before anything reaches the device.
+ */
+export class RollupError extends Error {
+    readonly name: 'RollupError';
+    /** Negative errno reported by libcmt (e.g. `-16` for `EBUSY`). */
+    readonly errno: number;
+    /** Name of the libcmt call that failed (e.g. `cmt_rollup_init`). */
+    readonly syscall: string;
+}
+
+export interface RunHandlers {
+    advance?: (request: AdvanceRequest, rollup: Rollup) => boolean | void | Promise<boolean | void>;
+    inspect?: (request: InspectRequest, rollup: Rollup) => boolean | void | Promise<boolean | void>;
+}
+
+export class Rollup {
+    /**
+     * Opens the rollup device and initializes the outputs merkle tree.
+     *
+     * On riscv64 this talks to the real Cartesi Machine IO driver; on other
+     * architectures it uses the libcmt mock, driven by the CMT_INPUTS and
+     * CMT_DEBUG environment variables.
+     */
+    constructor();
+
+    /**
+     * Accept or reject the previous request and wait for the next one.
+     * Synchronous on purpose: the call yields the machine, pausing the whole
+     * guest, so nothing else could run concurrently anyway.
+     */
+    finish(options?: { accept?: boolean }): RollupRequest;
+
+    /** Emit a voucher (Voucher(address,uint256,bytes)). Returns the output index. */
+    emitVoucher(voucher: Voucher): number;
+
+    /** Emit a delegate call voucher (DelegateCallVoucher(address,bytes)). Returns the output index. */
+    emitDelegateCallVoucher(voucher: DelegateCallVoucher): number;
+
+    /** Emit a notice (Notice(bytes)). Returns the output index. */
+    emitNotice(payload: BytesLike): number;
+
+    /** Emit a report (raw bytes, not part of the outputs merkle tree). */
+    emitReport(payload: BytesLike): void;
+
+    /** Emit an exception, signaling that the request could not be processed. */
+    emitException(payload: BytesLike): void;
+
+    /** Report progress of the current request (raw uint32 value). */
+    progress(value: number): void;
+
+    /** Perform a generic IO request to the given domain. */
+    gio(request: { domain: number; id: BytesLike }): GioResponse;
+
+    /** Load the outputs merkle tree state from a file. */
+    loadMerkle(file: string): void;
+
+    /** Store the outputs merkle tree state to a file. */
+    saveMerkle(file: string): void;
+
+    /** Reset the outputs merkle tree to pristine state. */
+    resetMerkle(): void;
+
+    /** Release the underlying device. Further calls throw. */
+    close(): void;
+
+    /**
+     * Convenience request loop. Handlers receive (request, rollup), may be
+     * async, and accept the request unless they return false (exceptions
+     * reject and are reported). Runs until finish fails, rejecting with that
+     * error.
+     */
+    run(handlers?: RunHandlers): Promise<never>;
+}

package/lib/index.js

@@ -0,0 +1,230 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+'use strict';
+
+const path = require('node:path');
+const binding = require('node-gyp-build')(path.join(__dirname, '..'));
+
+const ADDRESS_LENGTH = 20;
+const U256_LENGTH = 32;
+const EMPTY = Buffer.alloc(0);
+
+/**
+ * Error thrown when a libcmt binding call fails. Carries the negative errno
+ * reported by libcmt (e.g. `-16` for `EBUSY`) in {@link RollupError.errno} and
+ * the name of the libcmt call that failed in {@link RollupError.syscall}.
+ *
+ * Argument validation failures throw plain `TypeError`/`RangeError` instead,
+ * before anything reaches the device.
+ */
+class RollupError extends Error {
+    constructor(message, { errno, syscall, cause } = {}) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'RollupError';
+        /** Negative errno reported by libcmt (e.g. `-16` for `EBUSY`). */
+        this.errno = errno;
+        /** Name of the libcmt call that failed (e.g. `cmt_rollup_init`). */
+        this.syscall = syscall;
+    }
+
+    /**
+     * Normalize an error thrown by the native addon. libcmt failures carry a
+     * numeric `errno` and the failed call name in `syscall`; those become a
+     * RollupError. Anything else (validation errors, "rollup is closed") is
+     * returned unchanged.
+     */
+    static from(error) {
+        if (error instanceof RollupError) {
+            return error;
+        }
+        if (error != null && typeof error.errno === 'number' && typeof error.syscall === 'string') {
+            return new RollupError(error.message, { errno: error.errno, syscall: error.syscall, cause: error });
+        }
+        return error;
+    }
+}
+
+// Run a libcmt binding call, normalizing its failures into RollupError.
+function bindingCall(fn) {
+    try {
+        return fn();
+    } catch (error) {
+        throw RollupError.from(error);
+    }
+}
+
+function toBytes(value, name) {
+    if (typeof value === 'string') {
+        if (!/^0x(?:[0-9a-fA-F]{2})*$/.test(value)) {
+            throw new TypeError(`${name} must be a 0x-prefixed hex string, Buffer or Uint8Array`);
+        }
+        return Buffer.from(value.slice(2), 'hex');
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.isBuffer(value) ? value : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    }
+    throw new TypeError(`${name} must be a 0x-prefixed hex string, Buffer or Uint8Array`);
+}
+
+function toAddress(value, name) {
+    const bytes = toBytes(value, name);
+    if (bytes.length !== ADDRESS_LENGTH) {
+        throw new TypeError(`${name} must be ${ADDRESS_LENGTH} bytes long`);
+    }
+    return bytes;
+}
+
+function toU256(value, name) {
+    if (typeof value === 'bigint' || typeof value === 'number') {
+        let v = BigInt(value);
+        if (v < 0n || v >= 1n << 256n) {
+            throw new RangeError(`${name} must fit in an unsigned 256-bit integer`);
+        }
+        const bytes = Buffer.alloc(U256_LENGTH);
+        for (let i = U256_LENGTH - 1; i >= 0 && v > 0n; i--) {
+            bytes[i] = Number(v & 0xffn);
+            v >>= 8n;
+        }
+        return bytes;
+    }
+    const bytes = toBytes(value, name);
+    if (bytes.length !== U256_LENGTH) {
+        throw new TypeError(`${name} must be ${U256_LENGTH} bytes long`);
+    }
+    return bytes;
+}
+
+function toHex(bytes) {
+    return `0x${bytes.toString('hex')}`;
+}
+
+class Rollup {
+    #native;
+
+    constructor() {
+        this.#native = bindingCall(() => new binding.Rollup());
+    }
+
+    /**
+     * Accept or reject the previous request and wait for the next one.
+     * Synchronous on purpose: the call yields the machine, pausing the whole
+     * guest, so nothing else could run concurrently anyway.
+     */
+    finish({ accept = true } = {}) {
+        const request = bindingCall(() => this.#native.finish(accept));
+        if (request.type === 'advance') {
+            return {
+                type: 'advance',
+                chainId: request.chainId,
+                appContract: toHex(request.appContract),
+                msgSender: toHex(request.msgSender),
+                blockNumber: request.blockNumber,
+                blockTimestamp: request.blockTimestamp,
+                prevRandao: BigInt(toHex(request.prevRandao)),
+                index: request.index,
+                payload: request.payload,
+            };
+        }
+        return { type: 'inspect', payload: request.payload };
+    }
+
+    /** Emit a voucher (Voucher(address,uint256,bytes)). Returns the output index. */
+    emitVoucher({ destination, value = 0n, payload = EMPTY }) {
+        return Number(
+            bindingCall(() =>
+                this.#native.emitVoucher(
+                    toAddress(destination, 'destination'),
+                    toU256(value, 'value'),
+                    toBytes(payload, 'payload'),
+                ),
+            ),
+        );
+    }
+
+    /** Emit a delegate call voucher (DelegateCallVoucher(address,bytes)). Returns the output index. */
+    emitDelegateCallVoucher({ destination, payload = EMPTY }) {
+        return Number(
+            bindingCall(() =>
+                this.#native.emitDelegateCallVoucher(toAddress(destination, 'destination'), toBytes(payload, 'payload')),
+            ),
+        );
+    }
+
+    /** Emit a notice (Notice(bytes)). Returns the output index. */
+    emitNotice(payload) {
+        return Number(bindingCall(() => this.#native.emitNotice(toBytes(payload, 'payload'))));
+    }
+
+    /** Emit a report (raw bytes, not part of the outputs merkle tree). */
+    emitReport(payload) {
+        bindingCall(() => this.#native.emitReport(toBytes(payload, 'payload')));
+    }
+
+    /** Emit an exception, signaling that the request could not be processed. */
+    emitException(payload) {
+        bindingCall(() => this.#native.emitException(toBytes(payload, 'payload')));
+    }
+
+    /** Report progress of the current request (raw uint32 value). */
+    progress(value) {
+        bindingCall(() => this.#native.progress(value));
+    }
+
+    /** Perform a generic IO request to the given domain. */
+    gio({ domain, id }) {
+        return bindingCall(() => this.#native.gio(domain, toBytes(id, 'id')));
+    }
+
+    loadMerkle(file) {
+        bindingCall(() => this.#native.loadMerkle(String(file)));
+    }
+
+    saveMerkle(file) {
+        bindingCall(() => this.#native.saveMerkle(String(file)));
+    }
+
+    resetMerkle() {
+        bindingCall(() => this.#native.resetMerkle());
+    }
+
+    /** Release the underlying device. Further calls throw. */
+    close() {
+        bindingCall(() => this.#native.close());
+    }
+
+    /**
+     * Convenience request loop. Handlers receive (request, rollup), may be
+     * async, and accept the request unless they return false (exceptions
+     * reject and are reported). Runs until finish fails (e.g. mock inputs are
+     * exhausted, or the device is closed), which rejects with that error.
+     */
+    async run(handlers = {}) {
+        let accept = true;
+        for (;;) {
+            const request = this.finish({ accept });
+            const handler = handlers[request.type];
+            try {
+                accept = handler ? (await handler(request, this)) !== false : false;
+            } catch (error) {
+                accept = false;
+                this.emitReport(Buffer.from(String(error?.stack ?? error)));
+            }
+        }
+    }
+}
+
+module.exports = { Rollup, RollupError, ADDRESS_LENGTH, U256_LENGTH };

package/lib/index.mjs

@@ -0,0 +1,19 @@
+// Copyright Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// ESM wrapper over the CommonJS implementation, so both module systems share
+// the single native addon instance (no dual-package hazard).
+export { Rollup, RollupError, ADDRESS_LENGTH, U256_LENGTH } from './index.js';

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "@deroll/cmio",
+    "version": "0.1.0",
+    "description": "Node.js bindings for libcmt, the Cartesi Machine guest rollup library",
+    "keywords": [
+        "cartesi",
+        "rollups",
+        "libcmt",
+        "riscv64"
+    ],
+    "license": "Apache-2.0",
+    "author": "Cartesi and individual authors (see AUTHORS)",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/tuler/deroll"
+    },
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./lib/index.d.mts",
+                "default": "./lib/index.mjs"
+            },
+            "require": {
+                "types": "./lib/index.d.ts",
+                "default": "./lib/index.js"
+            }
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "AUTHORS",
+        "binding.gyp",
+        "lib/",
+        "src/",
+        "prebuilds/",
+        "deps/machine-guest-tools/sys-utils/libcmt/include/",
+        "deps/machine-guest-tools/sys-utils/libcmt/src/"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "install": "node-gyp-build",
+        "build": "node-gyp rebuild",
+        "prebuild": "prebuildify --napi --strip",
+        "test": "node --test \"test/*.test.mjs\"",
+        "check:package": "attw --pack ."
+    },
+    "dependencies": {
+        "node-addon-api": "^8.3.0",
+        "node-gyp-build": "^4.8.4"
+    },
+    "devDependencies": {
+        "@arethetypeswrong/cli": "^0.18.3",
+        "@types/node": "^25.9.2",
+        "node-gyp": "^11.0.0",
+        "prebuildify": "^6.0.1",
+        "typescript": "^6.0.3"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "binary": {
+        "napi_versions": [
+            8
+        ]
+    }
+}