Cartesi Machine
The Cartesi machine emulator is a C++ library with a C API. This package binds it to TypeScript — in Node.js, and in the browser — providing a fully typed and ergonomic API to create, manage and interact with Cartesi machines.
There are three ways to reach a machine, and they share one API:
| how it gets there | where it runs | |
|---|---|---|
@cartesi/machine | native N-API addon, linked against the emulator distribution | Node.js |
@cartesi/machine/wasm | libcartesi compiled to WebAssembly by Emscripten | browsers, Node.js, Deno, workers |
connectHttp() | JSON-RPC over fetch, to a cartesi-jsonrpc-machine server | anywhere with fetch |
The Node.js binding links against the static libraries of the official emulator distribution (currently 0.21.0). Prebuilt platform packages bundle everything — including the cartesi-jsonrpc-machine server executable used by spawn — so no emulator installation is required for the supported platforms.
The WebAssembly build is the same emulator compiled for a different target, so it is the same machine: identical root hashes, proofs and access logs, at roughly the speed of the native build.
Features
- Self-contained: prebuilt binaries per platform, no emulator installation needed;
- Runs in a browser: the same API over WebAssembly, off the main thread in a worker;
- Comprehensive: Complete API, for any use case, including local and remote machines;
- Full Type Safety: Complete TypeScript definitions for all C API functions and types;
- High-Level Wrapper: Easy-to-use CartesiMachine and RemoteCartesiMachine interfaces that wraps the C API;
- Error Handling: Easy error handling with detailed error messages.
Installation
On Linux (x64, arm64) and macOS (x64, arm64) this installs a prebuilt platform package (@cartesi/machine-<platform>-<arch>) containing the native addon and the JSON-RPC server executable — no compiler needed.
On other platforms the install script compiles the addon from source, which requires a C++ compiler and an installed cartesi-machine emulator distribution (the machine-emulator .deb from the official releases on Debian/Ubuntu, or brew install cartesi/tap/cartesi-machine-emulator on macOS).
Nothing extra is needed for the browser: the WebAssembly module ships inside the same package, and bundlers pick it up through the browser condition. See Browser.
Check the troubleshooting section in case of problems.