Wire Message Catalog & DIDComm Protocols ========================================== Fleetmesh nodes exchange authenticated, point-to-point and routed messages using the **DIDComm Messaging v2** specification. Every message is encapsulated in an envelope specifying a cryptographic sender DID (``from``), recipient DID (``to``), message ID (``id``), and an explicit protocol URI (``type``). Wire definitions are centrally documented in ``schema/messages.json``. Protocol Message Families ------------------------- peering/1.0 ^^^^^^^^^^^ Handles bilateral peering negotiation, shard interest alignment, and session lifecycle: - **``https://fleetmesh.org/peering/1.0/propose``**: Initiates a peering negotiation declaring node ``class``, ``protocol`` digest, supported ``protocols``, desired shard filters (``want``), offered coverage shards (``offer``), ``transports``, ``budget_self``, ``policy``, and ``pow``. - **``https://fleetmesh.org/peering/1.0/offer``**: Responds with counter-proposed terms, transport rungs, and initial grant parameters. - **``https://fleetmesh.org/peering/1.0/accept``**: Accepts the peering terms and activates the bilateral session. - **``https://fleetmesh.org/peering/1.0/decline``**: Rejects a peering proposal with an explicit reason code. - **``https://fleetmesh.org/peering/1.0/amend``**: Proposes in-flight updates to shard filters, transport endpoints, or rate ceilings on an active peering session. - **``https://fleetmesh.org/peering/1.0/terminate``**: Gracefully closes an active peering relationship. sync/1.0 ^^^^^^^^ Provides range-based NIP-77 Negentropy set reconciliation, provenance-signed event delivery, and shard coverage handover: - **``https://fleetmesh.org/sync/1.0/open``**: Opens a reconciliation session for a ``shard`` and ``filter`` over ``[since, until]`` with an ``initial_frame`` (hex-encoded Negentropy frame). - **``https://fleetmesh.org/sync/1.0/range``**: Exchanges recursive range-split frames (``range_id``, ``since``, ``until``, ``frame``). - **``https://fleetmesh.org/sync/1.0/have``** / **``https://fleetmesh.org/sync/1.0/need``**: Communicates held and missing event IDs isolated during reconciliation. - **``https://fleetmesh.org/sync/1.0/deliver``**: Delivers missing events inside a ``delivery-envelope`` attachment carrying hop-signed provenance over each event ID. - **``https://fleetmesh.org/sync/1.0/done``**: Closes the sync round with ``status`` (``complete`` | ``in_sync`` | ``aborted``) and ``events_transferred``. - **``https://fleetmesh.org/sync/1.0/handover``**: Transfers a signed first-hand coverage ``chain`` after an ``in_sync`` or ``complete`` reconciliation so the replica can publish an ``asserted`` Kind 30803 coverage claim. budget/1.0 ^^^^^^^^^^ Governs bilateral capacity micro-accounting, chained receipts, and window evaluation: - **``https://fleetmesh.org/budget/1.0/receipt``**: Submits a BIP-340 signed consumption receipt (``grant``, ``window``, ``seq``, ``prev``, ``counters``, ``forwarded_for``, ``at``, ``sig``). - **``https://fleetmesh.org/budget/1.0/receipt-ack``**: Acknowledges a receipt link with ``seq``, ``head``, and ``status`` (``accepted`` | ``divergent`` | ``final``). - **``https://fleetmesh.org/budget/1.0/close``**: Optionally finalizes a window with ``final_receipt_head`` and aggregate ``counters``. - **``https://fleetmesh.org/budget/1.0/dispute``**: Flags counter or signature divergence across receipt heads. complaint/1.0 ^^^^^^^^^^^^^ Mandatory pre-report dispute resolution workflow for ``S1`` and ``S2`` divergences: - **``https://fleetmesh.org/complaint/1.0/notice``**: Notifies a peer of an observed divergence (``outcome``, ``grant``, ``window``, ``metric``, ``observed``, ``claimed``, ``limit``, ``deadline``). - **``https://fleetmesh.org/complaint/1.0/evidence``**: Supplies cryptographic evidence artefacts (``evidence_type``, ``proof_hash``, ``payload``). - **``https://fleetmesh.org/complaint/1.0/remedy``**: Submits corrective action or counter-evidence before the notice deadline lapses. - **``https://fleetmesh.org/complaint/1.0/appeal``** / **``https://fleetmesh.org/complaint/1.0/withdraw``**: Appeals a complaint with audit logs or withdraws a notice upon resolution. compute/1.0 & compute/1.1 ^^^^^^^^^^^^^^^^^^^^^^^^^ Manages accountable compute quoting, sealed execution delivery, and streaming incremental outputs: - **``https://fleetmesh.org/compute/1.0/quote``** / **``https://fleetmesh.org/compute/1.0/accept``**: Quotes and locks execution pricing against a Kind 30810 compute ask commitment. - **``https://fleetmesh.org/compute/1.0/sealed``**: Delivers ``ciphertext``, ``payment_hash``, ``result`` hash, and ``fuel_used`` signed before payment so an invalid decryption key is provably refutable. - **``https://fleetmesh.org/compute/1.0/settled``** / **``https://fleetmesh.org/compute/1.0/refute``**: Completes settlement or challenges a bad preimage/key disclosure. - **``https://fleetmesh.org/compute/1.1/stream``** / **``progress``** / **``cancel``**: Additive streaming extension within the same thread carrying ordered output chunks (``seq``, ``delta``), execution state updates, or job cancellation. blob/1.0 ^^^^^^^^ Provides pull-driven content-addressed blob replication directly over peering transports: - **``https://fleetmesh.org/blob/1.0/have``**: Probes whether a peer holds a given ``sha256`` digest. - **``https://fleetmesh.org/blob/1.0/offer``**: Announces a replicable blob (``sha256``, ``size``, ``type``, ``chunk_bytes``). - **``https://fleetmesh.org/blob/1.0/pull``** / **``https://fleetmesh.org/blob/1.0/chunk``**: Requests and streams byte ranges (``sha256``, ``offset``, ``length`` / ``data``), verified against ``sha256`` before pinning. - **``https://fleetmesh.org/blob/1.0/refuse``**: Declines a blob offer or pull with an explicit reason (``why``). gossip/1.0 ^^^^^^^^^^ Implements admin-authorized epidemic broadcast meshes (gossipsub style) over existing peering grants: - **``https://fleetmesh.org/gossip/1.0/graft``** / **``https://fleetmesh.org/gossip/1.0/prune``**: Joins or prunes a per-topic mesh path, presenting the current Kind 30804 ``membership`` event. - **``https://fleetmesh.org/gossip/1.0/publish``**: Floods an already-sealed NIP-59 ``envelope`` keyed by ``event_id`` with strict seen-ID loop prevention. - **``https://fleetmesh.org/gossip/1.0/ihave``** / **``https://fleetmesh.org/gossip/1.0/iwant``**: Lazy gossip advertisements and pull requests for recent message IDs across non-mesh topic members. standing/1.0 ^^^^^^^^^^^^ Facilitates discretionary third-party standing queries: - **``https://fleetmesh.org/standing/1.0/ask``**: Queries a peer's local observation history for a ``target`` identity. - **``https://fleetmesh.org/standing/1.0/tell``**: Returns ``target``, ``tier``, ``clean_windows``, ``evaluated_windows``, and ``has_adverse_reports``. - **``https://fleetmesh.org/standing/1.0/decline``**: Declines to answer a standing query (non-adverse). Wire Message Format Example --------------------------- Below is an annotated example of a ``peering/1.0/propose`` wire message: .. code-block:: json { "id": "6f2b1234", "type": "https://fleetmesh.org/peering/1.0/propose", "from": "did:nostr:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "to": ["did:nostr:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"], "created_time": 1787000123, "expires_time": 1787003723, "body": { "class": "edge", "protocol": [ "fleetmesh/0.1-draft", "81d909663c01e4280f6699723ceb396349fa8fd480b343efdbbf063e34b9c481" ], "protocols": [ "https://fleetmesh.org/budget/1.0", "https://fleetmesh.org/peering/1.0", "https://fleetmesh.org/sync/1.0" ], "want": [ { "shard": "bristol-meetup-2026H2", "filter": {"kinds": [0, 1, 3, 7, 10002], "#t": ["bristol"]}, "mode": "pull", "since": 1751328000 } ], "offer": [ { "shard": "bristol-meetup-2026H2", "completeness": "asserted", "fingerprint": "9999999999999999999999999999999999999999999999999999999999999999" } ], "transports": ["iroh", "libp2p", "wss"], "budget_self": { "events_in": 600, "bytes_in": 8388608, "window": 3600 }, "policy": "0000000000000000000000000000000000000000000000000000000000000000", "pow": { "bits": 20, "event": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" } } }