# rollups

The `rollups` function is the main entry point for creating a [RollupsMachine](/cm/api/rollups-machine) instance. It supports three forms:

## From a Remote Machine

```ts
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

```ts
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.

:::warning
When using a local machine, rejected inputs do not trigger rollback, so this mode should only be used for test scenarios.
:::

```ts
import { rollups, create } from "@deroll/cm";

// create a local Cartesi machine
const config = { ram: { length: 1048576 } };
const localMachine = create(config);

// create a rollups machine from a local machine (no rollback on rejected inputs)
const machine = rollups(localMachine);
```

This approach is useful for unit tests or simple experiments, but is not recommended for production or integration scenarios, as rejected inputs will leave the machine in an invalid state.

For the full interface and available methods, see [RollupsMachine](/cm/api/rollups-machine).

## Advance and Inspect Methods

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

### advance

Preferred usage (generator-based, most flexible):

```ts
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:

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

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

### inspect

Preferred usage (generator-based):

```ts
for (const report of machine.inspect(query)) {
    // handle report (Buffer)
}
```

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

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

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