Remote Machine

The library also provides a way to run a Cartesi machine out-process, by running a server which a client can connect to and control a machine remotely.

Example

Here is a modified version of the local example that creates a remote machine instead. As simple as that.

import { BreakReason, create } from "@cartesi/machine"; 
import { BreakReason, spawn } from "@cartesi/machine"; 
 
// create a basic machine that print Hello world
const machine = create({ 
const machine = spawn().create({ 
    ram: {
        length: 0x8000000, // 128MB of RAM
        backing_store: { data_filename: "linux.bin" },
    },
    flash_drive: [
        {
            backing_store: { data_filename: "rootfs.ext2" },
        },
    ],
    dtb: {
        entrypoint: "echo Hello world!",
    },
});
 
// run the machine until it yields or halts (default is MAX_MCYCLE)
const reason = machine.run();
switch (reason) {
    case BreakReason.YieldedManually:
        console.log("Machine yielded manually");
        break;
    case BreakReason.Halted:
        console.log("Machine halted");
        break;
    default:
        console.log(`Machine halted: ${reason}`);
}
console.log(reason);
 
// calculate machine root hash
const hash = machine.getRootHash();
console.log(hash);

What is happening under the hood is that we are spawning a child cartesi-jsonrpc-machine process, which hosts a local Cartesi machine, and expose a JSON-RPC server to control it.

The returned machine object is now a RemoteCartesiMachine, which extends the CartesiMachine interface, thus providing all its methods, and a few additional ones.

Why remote?

The use of a remote Cartesi machine has three main objectives:

1. Horizontal Scalability

It allows the execution of a Cartesi machine server on a different host machine than the process that is controlling it. So you can have a heavy-weight instance to host the Cartesi machine, and a light-weight instance to control it.

2. Forking

The RemoteCartesiMachine API provides a fork method that allows you to create a "copy" of an existing machine, execute it, and throw it away (or not). This allows an "inspect" capability, where you want to execute the machine only for the purpose of reading some computation result. It also allows to properly handle "reverts", when an execution does not have the intended outcome.

3. Safety

As the Cartesi machine runs out-process that provides more safety to the controlling client, because some crash of the server process does not affect the client process.