rollups

The rollups function is the main entry point for creating a RollupsMachine instance. It supports three forms:

From a Remote Machine

const rollup = rollups(machine: RemoteCartesiMachine, options?: { noRollback?: boolean }): RollupsMachine;

• machine: An instance of RemoteCartesiMachine.
• options.noRollback (default: false): If true, disables rollback/forking for performance, but makes state changes permanent.

From a Store Directory

const rollup = rollups(dir: string, options?: {
    noRollback?: boolean;
    runtimeConfig?: MachineRuntimeConfig;
    address?: string;
    timeout?: number;
}): RollupsMachine;

• dir: Path to the store directory.
• options.runtimeConfig: Runtime configuration for the machine.
• options.address: Address for the remote machine server.
• options.timeout: Timeout for the remote machine server.
• options.noRollback: See above.

From a Local Machine

You can also create a rollups machine from a local CartesiMachine instance — including the WebAssembly one, which is the only form available in a browser.

const rollup = rollups(machine: CartesiMachine, options?: {
    noRollback?: boolean;
    snapshotDir?: string;
}): RollupsMachine;

• machine: An instance of CartesiMachine.
• options.snapshotDir (default: /tmp/cartesi-rollups): Where the per-input snapshots are stored. There is no server to fork here, so the machine stores itself before each input and loads that snapshot back if the input is rejected. See Rollback.
• options.noRollback: See above.

import { rollups, create } from "@cartesi/machine";
 
// create a local Cartesi machine
const config = { ram: { length: 1048576 } };
const localMachine = create(config);
 
// create a rollups machine from it
const machine = rollups(localMachine);

Rolling back through a snapshot writes the machine's memory ranges to disk, which a fork does not, so a remote machine is still the faster choice where a process can be forked.

For the full interface and available methods, see RollupsMachine.

Advance and Inspect Methods

The RollupsMachine exposes two main methods for interacting with the machine:

advance

Preferred usage (generator-based, most flexible):

for (const event of machine.advance(input)) {
    switch (event.type) {
        case "output":
            // handle output
            break;
        case "report":
            // handle report
            break;
        case "progress":
            // handle progress
            break;
    }
}

You can also use the collect option to get all outputs and reports as collections:

const { outputs, reports, outputsMerkleRoot } = machine.advance(input, { collect: true });
// outputs: Uint8Array[]
// reports: Uint8Array[]
// outputsMerkleRoot: Uint8Array

• Throws RollupsInputRejectedError if the input is rejected.
• Throws RollupsFatalError for fatal machine errors.

inspect

Preferred usage (generator-based):

for (const report of machine.inspect(query)) {
    // handle report (Uint8Array)
}

You can also use the collect option to get all reports as an array:

const reports = machine.inspect(query, { collect: true });
// reports: Uint8Array[]

• Throws RollupsInputRejectedError if the query is rejected.
• Throws RollupsFatalError for fatal machine errors.