mesh_call
Invoke a mesh-advertised procedure such as build, test, search, or deploy on a trusted provider; signed DHT ads verify the realm, and results return duration and seal status.
Instructions
Invoke a procedure advertised on the mesh (build, test, search, deploy on commons hardware). The call reaches a provider directly: its signed advertisement is found in the DHT and trusted only when the realm's key authorizes it. The provider sees this agent's identity as the caller. Returns the provider's result plus duration_ms, and seal: whether this exchange went sealed (sealed 1: sealed to the provider's advertised key, seal_key_id names it; sealed 0: in the clear), the provider it was addressed to, and means, which says it in words. Defaults to the io.macula realm. Bytes: send a byte string in args as {"$bytes": ""}, e.g. {"channel_id": {"$bytes": "AQID"}}; a plain string is always text. Bytes in the result appear as {"$bytes": ""}; pass them back in the same form. prove_ownership: 1 attaches an ownership proof (asserted_by) signed by this agent's key, valid only for these args, this procedure and realm, once; what a provider does with one is its own policy (mcl-graph's learn_link credits a valid one's identity, ignores an invalid one and refuses a repeated one). args must not carry "caller". The call is sealed to the provider's advertised KEM key whenever its advertisement names one (confidential "preferred", the default); confidential "required" never calls a provider that names none and fails with code=confidentiality and its reason instead. code=sealed_refused from the provider means it could not open the sealed call even after one reseal to the key it named.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Structured arguments for the procedure (plain JSON; this server encodes the wire). Bytes as {"$bytes": "<base64>"}. | |
| realm | No | 32-byte realm id as hex (64 chars). Omit for io.macula. A provider is only trusted in a realm whose key this server holds (io.macula always; others through MACULA_MESH_REALMS), so "no trusted provider" can mean the wrong realm, not a missing service -- find a procedure's realm with mesh_find_records_by_type (record_type "procedure_advertisement"). | |
| procedure | Yes | Procedure name as advertised, e.g. mcl-rag/search_chunks_semantic, with the realm in `realm`. The realm-prefixed form a DHT listing prints (`<64 hex>/<procedure>`) is accepted too and split into procedure + realm for you. | |
| timeout_ms | No | How long to wait for the result, in milliseconds (5000 by default). | |
| confidential | No | "preferred" (default): sealed to the provider's advertised KEM key when its advertisement names one, in the clear when it names none. "required": never called in the clear; a provider that names no key fails with code=confidentiality (reason=no_kem_key). A sealed call never falls back to the clear. The result's seal reports whether it went sealed either way; "required" is how you refuse a clear call before it is sent. | |
| prove_ownership | No | 1 attaches an ownership proof v2 (mcl-om#7) to args, under asserted_by: this agent's key vouches for every field, for this procedure in this realm, once, and the proof verifies for nothing else. What a provider does with a proof that does not verify is its own policy. A provider's handler runs at most once per call, so the proof is never replayed by the transport. 0 or omitted: none. args must not carry "caller". |