Skip to content
Calimero CoreCalimero CoreCalimero Core

App interface (ABI)

Every app carries an ABI: a JSON description of its surface, generated by #[app::logic] at compile time and embedded in the component as the custom section calimero:abi. It is part of the component’s bytes, so it is covered by the bundle’s hash and cannot drift from the code it describes.

The node reads it to dispatch and gate calls (calimero_app_host::Abi::from_json); clients read it to learn the methods, arguments and results.

The format

Section titled “The format”
{
  "abiVersion": 1,
  "world": "calimero:app@0.5.1",
  "state": {
    "fields": { "bookings": "table", "titles": "unorderedMap", "nextId": "counter" },
    "search": { "bookings": [] },
    "version": 3
  },
  "methods": {
    "book": {
      "kind": "call",
      "params": [["roomId", "string"], ["start", "u64"], ["title", "string"]],
      "returns": "string",
      "confirm": false, "public": false, "allowSystem": false
    },
    "roomCount": {
      "kind": "view",
      "params": [["roomId", "string"]],
      "returns": "u64",
      "confirm": false, "public": true, "allowSystem": false
    },
    "heartbeat": {
      "kind": "timer", "params": [], "returns": "unit",
      "every": "30s", "confirm": false, "public": false, "allowSystem": true
    }
  },
  "errors": { "NotFound": {}, "Taken": { "start": "u64" }, "Invalid": { "0": "string" } },
  "events": { "Booked": { "id": "string", "roomId": "string", "start": "u64" } }
}
  • methods, by camelCase name. kind is init, call, view, timer or action. params are ordered [name, type] pairs. The flags come from the method attributes: confirm, public (and rate), allowSystem, every on timers, allowApps, allowAction.
  • state: each field’s kind, the search fields of each table, and the #[app::state(version = N)].
  • errors and events: each code or name with its fields.
  • Types: Rust integer, float and bool names, string, bytes, option<T>, list<T>, tuple<..>, unit, else the Rust type’s name. u64, i64 and bytes are strings on the wire.

Every object’s keys are written in sorted order, so the same source always produces the same bytes.

What the node enforces

Section titled “What the node enforces”

The host reads abiVersion (and refuses one it does not support), the method kinds, and the flags: a view never runs as a write, confirm needs a fresh passkey assertion, public admits callers who are not signed in, allowSystem, allowApps and allowAction admit the node, other apps and the app’s own actions. Free-form keys (params, returns, errors, events) describe the app to clients; nodes ignore them. A field the host enforces is added only with an abiVersion bump.

Read it

Section titled “Read it”
  • GET /apps/{app}/abi returns an installed app’s ABI (Node API); meroctl context abi prints it.
  • mero-js and calimero-client-py read it to build typed calls.