Developer Tools

mero-abi (calimero-abi) + mero-sign + merodb — CLI utilities for ABI, signing, and database inspection

Overview

Three tools live in the tools/ directory. They are not part of the runtime — these are developer and operator utilities for working with WASM artifacts, bundle signing, and database debugging.

CLI tools

tools/

Tool Suite

Each tool is a standalone binary crate excluded from workspace versioning.

calimero-abi

mero-abi

Extract, inspect, and validate WASM ABI artifacts. Reads abi.json produced at build time, inspects WASM binary structure via wasmparser.

mero-sign

CLI

Ed25519 bundle manifest signing with did:key identifiers. Uses RFC 8785 JSON Canonicalization Scheme for deterministic signing.

merodb

CLI

RocksDB debug, inspect, export, and migrate tool. YAML-driven migration plans, DAG export, column-level data inspection, optional GUI.

calimero-abi (mero-abi)

CLI for working with Calimero WASM ABI artifacts. Reads abi.json produced at build time, inspects WASM binary structure via wasmparser.

CLI Commands

extract WASM_FILE [-o OUTPUT] [--verify]

Copies ABI from resolved abi.json to output file (default: same basename .abi.json). --verify kept for API compat but unused.

types WASM_FILE [-o OUTPUT]

Writes only the types field from abi.json (default: .types.json).

state WASM_FILE [-o OUTPUT]

Parses manifest, extracts state schema, sets schema_version to "wasm-abi/1", writes JSON.

inspect WASM_FILE

Parses WASM sections, export count, checks for get_abi_ptr / get_abi_len / get_abi exports, custom sections, calimero_abi_v1 presence.

Key Files

extract.rs

Core extraction logic — find_and_read_abi_json, extract_abi, extract_types_schema, extract_state_schema.

inspect.rs

WASM binary parser — inspect_wasm walks sections, identifies exports and custom sections.

Extract Flow

Locate abi.json

find_and_read_abi_json resolves the ABI file path relative to the WASM file, reading the JSON into memory.

Parse & Validate

Deserialize into ABI structure via serde_json. The manifest includes method signatures, types, and state schema.

Write Output

Depending on subcommand, write the full ABI, types-only, or state schema to the output path. State output includes schema_version: "wasm-abi/1".

wasmparser 0.118 clap serde_json eyre calimero-wasm-abi

tools/calimero-abi

mero-sign

Sign Calimero bundle manifest.json files with Ed25519. Uses RFC 8785 JSON Canonicalization Scheme (JCS) via serde_json_canonicalizer. Signer IDs are did:key identifiers derived from the public key (multicodec 0xed01 + base58btc multibase z).

CLI Commands

sign manifest -k KEY

Load key file, set signerId, strip signature and _-prefixed fields from canonicalization, SHA-256 of canonical bytes, Ed25519 sign, write signature object in-place.

generate-key [-o OUTPUT]

Generate new Ed25519 keypair. Writes JSON with private_key, public_key, signer_id.

derive-signer-id -k KEY

Print did:key signer_id from key file.

Signing Flow

Key Types

struct KeyFile {
    private_key: String, // hex-encoded Ed25519 secret
    public_key: String, // hex-encoded Ed25519 public
    signer_id: String, // did:key multibase identifier
}

struct SignatureObject {
    algorithm: String, // "Ed25519"
    publicKey: String, // hex-encoded public key
    signature: String, // base64url-encoded signature
}

did:key Derivation

Multicodec Prefix

Prepend the Ed25519 multicodec prefix 0xed01 to the raw 32-byte public key.

Base58btc Encode

Encode the prefixed bytes using base58btc (Bitcoin alphabet).

Multibase Wrap

Prepend multibase prefix z → final identifier: did:key:z6Mk...

ed25519-dalek clap serde_json serde_json_canonicalizer bs58 base64 sha2

tools/mero-sign

merodb

Debug and inspect Calimero's RocksDB layout. Export column data, validate integrity, export DAG, run YAML-driven migrations, optional GUI.

CLI Commands

schema [-o FILE]

Emit JSON schema of DB structure (stdout if no -o).

export --db-path PATH [--all | --columns COLS] [--state-schema-file SCHEMA] [-o FILE]

Opens DB read-only, exports selected columns. State decoding uses schema file or infers from DB.

validate --db-path PATH [-o FILE]

Validate database integrity — checks column families, key structure, value deserialization.

export-dag --db-path PATH [-o FILE]

Export context DAG as JSON — traverses the Delta column to reconstruct the full DAG structure.

migrate --plan PLAN --db-path PATH [--target-db] [--backup-dir] [--dry-run] [--apply] [--report FILE]

YAML migration plan with copy / delete / upsert / verify steps. Default is dry-run; --apply writes.

gui [--port 8080]

Local HTTP UI for DB exploration (requires --features gui).

Column Support

Core columns (Meta / Config / Identity)

State columns (State / Delta)

Data columns (Blobs / Application)

Auxiliary columns (Alias / Generic)

Key Functions

open_database

Opens RocksDB in read-only mode, discovers column families, returns CF handles for selective access.

parse_key / parse_value

Decode raw byte keys to JSON. parse_value dispatches to typed parsers like parse_context_meta, parse_dag_delta, etc.

Migration Plan Format

# migration.yaml
version: 1
steps:
  - action: copy
    from_column: State
    to_column: State_v2
    transform: null
  - action: delete
    column: State
    key_prefix: "0x..."
  - action: upsert
    column: Meta
    key: "version"
    value: "2"
  - action: verify
    column: Meta
    expect_key: "version"

Default mode is --dry-run — logs actions without writing. Use --apply to execute. --backup-dir creates a snapshot before applying. --report writes a JSON summary.

rocksdb clap serde_json serde_yaml borsh sha2 jaq-* calimero-primitives calimero-storage calimero-store calimero-wasm-abi

tools/merodb

Dependencies

All three tools are excluded from workspace versioning. They depend on shared Calimero crates but do not participate in the runtime dependency graph.

Primary / unique dependency

Shared external dependency

calimero-primitives

calimero-store

calimero-storage

merod

Node daemon binary. Initializes configuration, manages the datastore, and runs all actors (Node, Context, Network, Server).

Commands

merod init — Initialize node: config.toml, identity, datastore merod config — Modify config.toml fields (dot-path syntax) merod run — Start the node (all actors, server, P2P)

Init options

merod --home /data --node mynode init \ --server-port 2428 \ --swarm-port 2528 \ --boot-network calimero-dev \ --group-governance local

--group-governance local is the default (and only) governance mode.

For read-only nodes, add --mode read-only.

TEE Mode

When [tee] configuration is present, merod fetches a storage encryption key from a KMS at startup using TDX attestation. See TEE Mode for full details.

meroctl

Operator CLI for managing a running merod node. Connects via the admin API.

Command Groups

app

install, list, get — manage applications (bundles and raw WASM).

context

create, list, invite, join, update, delete — context lifecycle.

group

create (with --parent-group-id), list, get, delete, invite, join, members (add/remove/list/set-role/set-caps/get-caps), contexts, join-context.

call

Execute a WASM method: meroctl call METHOD --context ID --as KEY --args JSON

blob

upload, get, delete — binary large object management.

peers

List connected P2P peers.

node

Node identity and status information.

Usage Example

# Install an application bundle meroctl --node mynode app install --path app.mpk # Create a context meroctl --node mynode context create --application-id APP_ID # Call a method meroctl --node mynode call set_item \ --context CTX_ID --as MEMBER_KEY \ --args '{"key": "hello", "value": "world"}'