rollup.run

Convenience request loop: repeatedly finishes the previous request and dispatches the next one to your handlers.

Usage

import { Rollup } from "@cartesi/rollup";
 
const rollup = new Rollup();
 
await rollup.run({
    advance(request, rollup) {
        rollup.emitNotice(request.payload);
        return true;
    },
    inspect(request, rollup) {
        rollup.emitReport(request.payload);
    },
});

Returns

Promise<void>, and where it settles depends on which side you are running:

• Inside a Cartesi Machine the loop never ends on its own — the application is meant to keep serving requests forever. The promise only settles if finish fails (for example the device was closed), and then it rejects with that error.
• On the host mock it also resolves once the inputs listed in CMT_INPUTS run out, which is the natural end of a test session. Any other finish failure still rejects.

So a host test can simply await rollup.run(...) and then assert on the outputs, with no catch in the way.

Parameters

handlers

• Type: RunHandlers

An object with an optional handler per request type. Both receive (request, rollup) and may be synchronous or async:

type RunHandlers = {
    advance?: (
        request: AdvanceRequest,
        rollup: Rollup,
    ) => boolean | void | Promise<boolean | void>;
    inspect?: (
        request: InspectRequest,
        rollup: Rollup,
    ) => boolean | void | Promise<boolean | void>;
};

The handler's result decides the request's fate:

See Handling Requests for the semantics of accept/reject.

run takes exactly one handler per request type. To split a request kind across several independently written handlers, fold them with chain or broadcast — see Composing Handlers. Those compose handlers that must return a real boolean, which is assignable here.