Cartesi Rollups LIBCMT Bindings

Table of Contents

• Table of Contents
• What are the libcmt bindings?
• Repository structure
• Using a binding
• Creating a new binding
• License

---

What are the libcmt bindings?

The libcmt bindings expose the Cartesi machine guest library (libcmt) C API to different programming languages. libcmt is the low level library used inside the Cartesi Rollups machine to:

• Rollup I/O — Read advance and inspect requests, and emit vouchers, notices, and reports
• ABI — Encode and decode Ethereum style ABI payloads
• Merkle trees — Build and verify Merkle proofs
• Buffers & utilities — Keccak hashing, buffers, and other helpers

Bindings let you build Cartesi dApps in your preferred language without using the HTTP rollup server. You get direct, programmatic control over the rollup loop and can implement asset handling, state, and application logic natively (e.g. for asset management libraries, game backends, or custom rollup logic).

This repository is the parent repo that brings together all language-specific bindings in one place. Each binding lives in its own submodule and can also be used independently.

---

Repository structure

libcmt-bindings/
├── README.md           # This file
├── LICENSE
├── .gitmodules         # Submodule definitions
├── go/                 # Go bindings (submodule → libcmt-binding-go)
├── python/             # Python bindings (submodule → libcmt-binding-python)
└── rust/               # Rust bindings (submodule → libcmt-binding-rust)

Directory	Binding	Description
rust/	Rust	FFI via bindgen, idiomatic Rust wrappers. Includes sample apps (echo, template) and Cartesi config.
python/	Python	Cython-based extension linking against libcmt.
go/	Go	Go bindings for libcmt.

Each submodule is a separate Git repository. To clone this repo with all bindings:

git clone --recurse-submodules https://github.com/Mugen-Builders/libcmt-bindings.git

If you already cloned without submodules:

git submodule update --init --recursive

---

Using a binding

1. Pick a language — Use the binding in rust/, python/, or go/ (see each subfolder’s README for details).
2. Add the selected bindings as a dependency — For example, in a Rust project, add the Rust binding crate to your cargo.toml file, while for python based projects, import the necessary wheels containing the bindings.
3. Implement the rollup loop — Call the binding’s API to:
   • finish the previous request and get the next request type (advance vs inspect)
   • For advance: read input payload and metadata, then optionally emit vouchers or notices
   • For inspect: read query payload and optionally emit a report
4. Build and run — Build your dApp (use cartesi build / cartesi run with the appropriate Cartesi config).

Example (Rust): The Rust binding README has full code samples for creating a Rollup, handling advance/inspect, and emitting notices, vouchers, and reports. The rust/sample_apps/echo_app is a complete example you can run and extend.

For Python and Go, see python/README.md and go/README.md for specialised installation and usage guides.

---

Creating a new binding

While we currently have the Rust, Python and Go bindings, Cartesi application's curerntly support a wide variety of languages, whose bingings are not yet available and would be necessary for building cartesi applications in these languages, so if you're interested in creating a and contributing the binding for any of these languages, the below section would serve as an over head guide to creating a binding, just make sure to go through the documentation for any autogen tool you'll be using for the bindings.

What you need

• libcmt — The C library and headers from Cartesi machine-guest-tools (e.g. sys-utils/libcmt/). You can ship it as a submodule or build artifact.
• FFI layer or AutoGen tool — A way to call C from your language (e.g. bindgen for Rust, Cython for Python, cgo for Go, N-API/node-gyp for Node, JNI for JVM, etc.).
• Wrapper header — A single C header that includes the libcmt headers you need: abi.h, buf.h, io.h, keccak.h, merkle.h, rollup.h, util.h.
• Idiomatic API — Thin wrappers in your language so users work with types and functions that feel natural (e.g. Rollup::read_advance_state() instead of raw C structs).

High-level steps

1. Get libcmt — add machine-guest-tools as a submodule in your repository, access the libcmt module at sys-utils/libcmt/include.
2. Generate or write FFI bindings — Use your language’s autogen tool to generate bindings from the libcmt headers (or from a minimal wrapper header that includes them).
3. Create Wrappers around the generated ffi bindings - Write simplified wrapper functions that appications call and pass arguments instead of interacting directly with the autogenertated bindings.
4. Test the new bindings — Create a Cartesi application that utilizes the bindings, ensure accurate functionality of the init, advance, inpect, finish and emit functions.
5. Contribute to this repo — Create a new repo for your binding (e.g. libcmt-binding-<lang>), then add it as a submodule in this parent repo and include it to this README.

For a detailed walkthrough of creating an asset management library and bindings for your Cartesi applications (including design and step-by-step instructions), see:

Creating an LIBCMT Binding for your Cartesi application (Medium)

---

License

See LICENSE.