Skip to content

Bump libcartesi to v0.20.0 and add bindings for new root-hash collection APIs #724

@vfusco

Description

@vfusco

Context

rollups-node uses CGO bindings to libcartesi (emulator C API), currently pinned to v0.19.0. The Machine team provided a v0.20.0 preview/test release and asked us to validate it in the node before they cut the final release.

This task is not about adopting new emulator features in the node. The goal is to bump to the preview build, ensure the node still works end-to-end, and add minimal bindings for two newly introduced C APIs so we can exercise them in tests/prototypes.

Relevant binding location:

  • pkg/emulator (CGO binding to libcartesi / libcartesi_jsonrpc)

Proposed change

  1. Update the pinned libcartesi version from 0.19.0 → 0.20.0 (preview) in all build/install paths used by CI/dev (Docker images, scripts, docs, etc. as applicable).

  2. Extend the CGO bindings to expose the newly added APIs:

CM_API cm_error cm_collect_mcycle_root_hashes(
    cm_machine *m,
    uint64_t mcycle_end,
    uint64_t mcycle_period,
    uint64_t mcycle_phase,
    int32_t log2_bundle_mcycle_count,
    const char *previous_back_tree,
    const char **result
);

CM_API cm_error cm_collect_uarch_cycle_root_hashes(
    cm_machine *m,
    uint64_t mcycle_end,
    int32_t log2_bundle_uarch_cycle_count,
    const char **result
);

Notes:

  • Keep the scope minimal: expose the functions + basic error handling + memory management for returned strings.
  • Do not refactor the emulator package unless required by the bump.
  1. Update the Rust prototype node to use the same preview version and run its test flow, so we can compare resulting machine hashes and the computation hashes (hash parity).

Deliverables

  • Dependency bump:
    • Pin libcartesi to v0.20.0 preview (exact preview identifier/commit as provided by Machine team)
    • Ensure local dev + CI build paths fetch/install the preview version consistently
  • Go bindings:
    • Add CGO wrappers in pkg/emulator for the new APIs
    • Add small Go-level helpers for decoding/freeing returned strings (as required by the C API contract)
  • Tests / validation:
    • Run the existing rollups-node test suite against the preview build (CI + local as needed)
    • Add at least one focused test (or a small harness) that calls the new APIs on a known machine and validates the output is well-formed JSON / parsable (without asserting exact values unless we already have fixtures)
  • Rust prototype alignment:
    • Bump libcartesi to the same preview version in the Rust prototype node
    • Run the Rust prototype’s test flow and capture machine hashes / computation hashes for comparison
  • Feedback:
    • Summarize results (pass/fail + any breaking changes encountered) and send to the Machine team so they can proceed with the final 0.20.0 release

Acceptance criteria

  • rollups-node builds and links successfully against libcartesi v0.20.0 preview on CI-supported platforms.
  • Core node workflows and the existing test suite pass with the preview dependency (no regressions vs 0.19.0).
  • The new CGO bindings are available from Go code and:
    • Return a non-error result on a valid machine instance
    • Return a clear error on invalid inputs (non-zero exit / error propagated), without crashing or leaking memory
  • Rust prototype node runs against the same preview version and produces matching hashes between:
    • machine hashes
    • computation hashes
  • Give feedback to the Machine unit

Out of scope

  • Implementing or exposing all new emulator features introduced in 0.20.x.
  • Changing CLI/JSON-RPC surfaces unless strictly required for compatibility.

Follow-up (after Machine team releases 0.20.0)

  • Replace the preview pin with the final released v0.20.0 and open/merge the PR.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Status

No status

Relationships

None yet

Development

No branches or pull requests

Issue actions