Types & Constants

Everything the package exports besides the Rollup class (the RollupError class is documented under Errors). All types are importable with import type:

import type {
    AddressLike,
    AdvanceRequest,
    AdvanceRequestHandler,
    BytesLike,
    DelegateCallVoucher,
    GioResponse,
    Hex,
    InspectRequest,
    InspectRequestHandler,
    RequestHandler,
    RollupDriver,
    RollupRequest,
    RunHandlers,
    U256Like,
    Voucher,
} from "@cartesi/rollup";

Input types

Three "like" types describe what the binding accepts and converts automatically — see byte and number conventions. Hex strings are Hex (`0x${string}`), structurally identical to viem's Hex/Address:

Output argument types

The two voucher emitters take a named options object, importable for typing helpers that build outputs:

• Voucher — argument of emitVoucher: destination (AddressLike), optional value (U256Like, default 0n) and payload (BytesLike, default empty).
• DelegateCallVoucher — argument of emitDelegateCallVoucher: destination (AddressLike) and optional payload (BytesLike). No value — DELEGATECALL cannot transfer ether.

import type { Voucher, DelegateCallVoucher } from "@cartesi/rollup";
 
const voucher: Voucher = {
    destination: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    value: 1_000_000_000_000_000_000n,
};
 
const delegateCall: DelegateCallVoucher = {
    destination: "0x5FbDB2315678afecb367f032d93F642f64180aa3",
};

Request types

finish returns RollupRequest, the discriminated union of:

• AdvanceRequest — type: "advance" plus the input metadata (chainId, appContract, msgSender, blockNumber, blockTimestamp, prevRandao, index) and payload.
• InspectRequest — type: "inspect" and payload.

const request = rollup.finish();
if (request.type === "advance") {
    request.index
Input index relative to all inputs ever sent to the application.
;
}

Handler types

RunHandlers is the parameter of run — an optional advance and inspect handler, each receiving (request, rollup) and returning boolean | void, possibly wrapped in a Promise.

RequestHandler<request> is the handler chain and broadcast compose: the same (request, rollup), but returning boolean | Promise<boolean> — inside a composition, a missing answer has no sensible meaning (why). AdvanceRequestHandler and InspectRequestHandler are it, specialized to one request kind:

import type { AdvanceRequestHandler, InspectRequestHandler } from "@cartesi/rollup";
 
const advance: AdvanceRequestHandler = (request, rollup) => {
    rollup.emitNotice(request.payload);
    return true;
};
 
const inspect: InspectRequestHandler = (request, rollup) => {
    rollup.emitReport(request.payload);
    return true;
};

boolean is assignable to boolean | void, so either of them — composed or not — can be passed to run directly.

Response types

GioResponse is returned by gio: { responseCode: number, responseData: Buffer }.

Constants

import { ADDRESS_LENGTH, U256_LENGTH } from "@cartesi/rollup";
 
ADDRESS_LENGTH
Length of an EVM address, in bytes.
;
 
U256_LENGTH
Length of an EVM word, in bytes.
;

driver (typed RollupDriver) reports which libcmt IO driver the native addon was built against — "ioctl" for the real Cartesi Machine kernel driver on riscv64, "mock" for the file-based host simulation. The choice is made at build time from the target architecture, so it is the honest answer to "am I running inside a machine?", where CMT_INPUTS being set is only a hint:

import { driver } from "@cartesi/rollup";
 
driver
The libcmt IO driver this addon was built against: "ioctl" for the real
Cartesi Machine driver (riscv64), "mock" for the file-based simulation used
on development hosts.
It is decided by binding.gyp from the target architecture, at build time —
not by the environment, so it is the truth about which half of libcmt is
running, where CMT_INPUTS being set is only a hint.
;

Errors

Failed libcmt calls throw a RollupError (a subclass of Error) with two extra properties:

RollupError is exported as a value, so it can be caught with instanceof:

import { Rollup, RollupError } from "@cartesi/rollup";
 
try {
    new Rollup();
} catch (error) {
    if (error instanceof RollupError) {
        error.errno
Negative errno reported by libcmt (e.g. -16 for EBUSY).
;
    }
}

Argument validation failures throw plain TypeError / RangeError before reaching the device.