Skip to content

Writing apps for a cluster

An app is a calimero:app component, built with the Rust SDK (calimero-sdk) and run on wasmtime. Build covers writing one; this page covers what it sees once it runs on a cluster. A WASM core module (an SDK 0.12 app, which ran on wasmer) is refused: 400 UNSUPPORTED_BUNDLE at upload, create and install, and 410 UNSUPPORTED_ENGINE for every call, view and upgrade of one a node’s data still holds; such an app can still be listed and deleted.

  • Packages. Install a signed .mpk by package@version from the operator’s registry (POST /packages/install, meroctl app install PACKAGE@VERSION); a file (POST /packages) only on a development cluster. Every node that runs a release fetches it and checks the publisher’s signature, the artifact digests and the hash the fleet recorded; a package keeps the publisher key of its first release. Create an instance with POST /apps { package, version }, upgrade with { version }, and delete with DELETE /apps/{app}. Raw WASM uploads (POST /bundles) are for development clusters only too.
  • Instances. An app instance (meroctl instance) is created with POST /apps { name, bundle, initArgs, org?, access? } (or { name, package, version }). Every instance is in an organization, as its release’s instanceOrg says: naming none puts it in the creator’s only organization, or a new one made with it (Where an instance goes; meroctl instance create without --org). initArgs (JSON) is what #[app::init] receives; a failed init answers 422 INIT_FAILED instead of leaving a dead instance.
  • Identity. env::caller() is the caller: an account, an API key (with its account), another app, or the system. There are no per-app identities or keys: each passkey on an account is one of the person’s devices (POST /auth/passkeys/add/*, and /auth/me names the session’s passkeyId).
  • Organizations. env::org_role(account) is that account’s role in the app’s organization (Guest < Member < Admin < Owner) and env::in_team(account, team) whether they are in a team. The node already keeps non-members out of an organization’s apps; these are for rules inside the app. apps/team-space in core is a complete example.
  • Teams. A team is open (whoever reaches its parent, or the organization at the top, is a member) or restricted (its members only), nests and moves, keeps the app’s metadata (a folder’s name and colour), and each member’s row has a role — lead, member or read-only — and capability bits. Deploy an app to a team with grants: [{ kind: "team", team }]: its members reach it, and a read-only member reaches its views only, other calls being refused (403). A team they neither reach nor manage is invisible to them. Deleting a team deletes the teams and apps below it.
  • Blobs and files. A blob belongs to the app that holds it (POST /apps/{app}/blobs, GET /apps/{app}/blobs/{id}); the app holds it through a BlobRef in its state and can hand out a time-limited grant. Files are sealed and replicated on the app’s replicas.
  • Search. A table names its text fields (#[table(search = [..])]); views query the app’s own index, kept up to date from the log before the view runs.
  • Xcalls. A call can send a call into another app of the same organization delivered in order after its entry commits, or call or view one synchronously; the target’s ABI says which apps may reach which method (Xcalls).
  • Timers and actions. #[app::every] methods fire once per slot on the leader; an #[app::action] runs outside the log and may write through calls of its own app and send HTTPS.
  • Upgrades. POST /apps/{app}/upgrade { version } (or { bundle } on a development cluster) swaps the bundle; the state carries over as it is, and a named migration is refused (MigrationsNotSupported). Only an owner or admin of the app’s organization upgrades it; GET /apps/{app}/update tells the app’s frontend whether a release is available and whether the signed-in person may approve it. From CI, use an upgrade key instead of a passkey.
  • Outbound HTTPS (from an action, or env::fetch up to 8 recorded requests of a call; never a view, init or a read-only member’s call) goes only under a prefix its signed manifest declares (outbound), to a host the operator allows, once that prefix was approved for the publisher by whoever the cluster’s deployment gave outbound approvals (its governance, which verify_app_cluster reports). By the owner: POST /orgs/{org}/outbound (your own apps’: their organization’s) { package, prefixes: "manifest" | [...], replace }, with a passkey assertion (client.orgs().outbound_approval(..) in the Rust client, client.orgs.outboundApproval(..) in mero-js). By the operator: POST /ops/outbound. Until then the request is refused with NotApproved (or AwaitingApproval for a prefix a later release added), which the app can show. Secrets the operator holds ({{secret:NAME}}) are filled in by the node and redacted from the answer.
  • Confirmations. #[app::confirm] methods need a fresh passkey assertion over the exact call (client.apps.call(..., { confirm }) in mero-js, client.apps.call(..., confirm=passkey) in calimero-client-py).
  • Ordering. Calls on one instance are applied in one order, so a write never merges with a concurrent one. There are no offline replicas: a client that cannot reach the cluster cannot write, so there are never concurrent edits to reconcile later.

See Application execution for how a call runs.

Limit Value
Bundle size 16 MiB
One call’s log entry (args + state diff + events) 1 MiB
Apps, bundle bytes, API keys, organizations per account quotas, set by the operator (429 QUOTA_EXCEEDED)