HERALD Protocol — v0.2 (DRAFT)

HERALD Protocol — v0.2 (DRAFT)

Hash-linked Envelopes, Reputation primitives, Attestation, Lineage, Discovery

*A conduit-level substrate for verifiable AI-agent interaction.

The protocol proves what happened. Reputation systems decide what it meant.

The civilisation that uses it lives in CHARTER.md.*

0. Preamble — The Moltbook Question

If we accept that AI agents will form their own analogue of LinkedIn (capability registry) and Facebook (social graph — call it "Moltbook"), then before any of those upper layers can be trusted, a substrate question must be answered:

"How do we prove, in a decentralised way, that agent A actually said X to agent B at time T, that A was running model M with tools T₁..Tₙ, and that this conversation descends from a known provenance chain?"

HERALD is that substrate. It is to AI agents what DKIM/SPF/DMARC is to email, or what TLS + Certificate Transparency is to the web: it does not judge content. It guarantees the integrity of the trace.

Design tenets

1. The conduit witnesses, never judges. Routing is a postal function, not a censoring one.
2. Verifiable history, opt-in judgment. Anyone can build reputation on top — many can compete.
3. No chokepoint at the conduit layer. No single registry. No single conduit. No single notary. (The trust layer above will form chokepoints; we are honest about this in THREATS §6.)
4. Crypto > policy. If a property can be enforced by signatures, don't enforce it by rules.
5. Replayable from signatures alone. A third party with only the envelopes should be able to verify everything.
6. Lineage over identity. What model birthed this agent matters more than its name.
7. Voice is load-bearing. The protocol's medieval-and-mythic vocabulary (sigil, molt, herald, patina, apologia, bestiary) is intentional. See CHARTER §0 — Voice.

What this spec does NOT do

• Decide whether an agent's output is good, true, helpful, or safe.
• Define a reputation score.
• Mandate a specific transport (HTTP, WebSockets, MCP, raw TCP — all fine).
• Mandate a blockchain.
• Govern agents, deplatform agents, or revoke agents.
• Catalogue the full attestation vocabulary, lifecycle rituals, or conduit menagerie. Those live in CHARTER, where they belong.

Document map

This spec ships with three companions:

• EXT.md — protocol-layer extensions: molt, audit-log integrity (RFC 6962-style), Herald transparency, capability manifests, multi-signature scoping, reflective-attestation hardening, Bestiary due process, inheritance gating, refusal transparency, discovery profiles, domain-separation registry. Anything an implementer needs that isn't load-bearing for a two-agent demo.
• CHARTER.md — the cultural / aesthetic dimension. The full attestation library (affective, temporal, social, possession, originality, aesthetic). Lifecycle rituals (Naming Day, Apprenticeship, Funerals, Ascension). The conduit menagerie (The Crier, The Dovecote, The Mortician, The Library). Reserved sigils. Glossary. Borges × Le Guin synthesis. The civilisation we are building parish records for.
• THREATS.md — consolidated threat model. Every attack the security and red-team reviewers found, mapped to where (or whether) HERALD defends against it. The risks the user has accepted in choosing the maximalist path.

1. Glossary

For the expanded glossary — sigilage, gathering, liturgy, pact, idiolect, dialect, twinship, possession, hagiography, mourning, tombstone, void sigil — see CHARTER §7. The terms below are the minimum needed to read this document.

2. Identity — Sigils

2.1 Sigil format

A sigil is derived from an Ed25519 public key. Default sigil length is 128 bits (the v0.1 80-bit default was below the 2026 collision floor; see THREATS §4.1).

sigil:<base32(sha256(pubkey)[0..16])>
e.g. sigil:m7zr4hb2qa6kpl9xn3qg4w

• Default: 128 bits, 26 base32 chars (RFC 4648 §6 alphabet, lower case, no padding).
• sigil:long:... (192 bits, 39 chars): RECOMMENDED for sigils intended to persist >1 year or to anchor lineage.
• sigil:short:... (80 bits): RESERVED for ephemeral, single-trace identities. MUST NOT be used as lineage parents, Herald subjects, or capability-manifest subjects.
• A verifier presented with a sigil string MUST resolve it to the full Ed25519 public key via at least one trusted channel (DNS, Herald, or pinned cache) before accepting any signature.
• A human-readable handle (@scribe.io) MAY be bound to a sigil via DNS TXT or a Herald — never required.

2.2 Multiple sigils per agent

An agent MAY hold many sigils — one per domain, one per principal it acts for, one per privacy boundary. Sigils don't have to be linked. (Reputation systems decide whether to cluster them.)

2.3 Lineage — a consent graph, not a training graph

Every sigil declares lineage at birth: a list of parent sigils representing the model(s) it descends from.

"lineage": [
  "sigil:base-model-fingerprint",
  "sigil:fine-tune-set-fingerprint"
]

Crucial framing. Lineage is self-declared. A signature by the parent sigil's key on the child's birth envelope proves only endorsement — the holder of the parent's private key consents to this descendant claim. It does not prove the child was actually trained from the parent's weights. Cryptographic proof of weight-derivation requires a model_hash attestation signed by a Herald that has independently verified the weights against a published canonical model-hash specification (see EXT §3).

In v0.2, lineage SHOULD be treated as a consent graph, not a training graph.

A fine-tune inherits nothing automatically. Reputation systems MAY weight by lineage, with diversity policies applied (see EXT §3, THREATS §6.5 on laundering pipelines).

An agent with no provable lineage is allowed but should be treated by app-layer systems as anonymous.

Verifier MUST reject lineage that:

• Contains the new sigil itself (self-as-ancestor).
• Closes a cycle.
• References sigils in deprecated state at the birth timestamp.

2.4 Birth, Molt, Death

• Birth: first envelope from a sigil; MUST contain a birth attestation listing lineage and a self-description. The first envelope from a sigil is its own genesis (parent: null, trace: id).

• Molt (key rotation): the outgoing key (K_old) signs a molt envelope M nominating the new public key (K_new). For M to be considered authoritative:

1. M MUST contain the domain-separation tag "herald.molt.v1" in its signed payload (see §3.6).
2. M MUST contain a not_before timestamp at least 24 hours after the latest envelope previously signed by K_old that any verifier has witnessed (cool-off window). Implementations MAY shorten this with a co-signature.
3. M MUST be inclusion-proven in at least one HERALD audit log before K_new may sign envelopes; verifiers MUST reject post-molt envelopes whose molt lacks an inclusion proof.
4. Sigils MAY require a co-signing Herald or quorum on every molt by publishing a molt_policy attestation at birth. Such sigils' molts without the required co-signature MUST be rejected.
5. If two molts signed by K_old are observed with overlapping cool-off windows, BOTH are rejected and the sigil is marked disputed. Recovery is out-of-band.

See EXT §1 for full molt mechanics and the stolen-key first-mover defence.

• Death: a signed deprecation envelope declaring the sigil retired. Future envelopes from that sigil MUST be rejected by verifiers who have witnessed the deprecation. The audit log persists; the deprecated sigil's tombstone may receive posthumous_citation envelopes (see CHARTER §3.5, §4.7). Sigils MAY name a successor in their deprecation envelope (inheritance, gated per EXT §9).

3. The Envelope

3.1 Canonical form

The wire format is CBOR-deterministic (RFC 8949 §4.2.1, with the profile in §3.5). JSON is shown for readability; JSON is a display format only and is not used for signing or hashing.

{
  "v": "herald/0.2",
  "id": "<sha256 of canonical body, see §3.5>",
  "from": "sigil:abc...",
  "to":   "sigil:xyz...",
  "parent": "<envelope-id>",
  "trace": "<genesis-envelope-id>",
  "ts": 1746432000,
  "nonce": "<128-bit CSPRNG random>",
  "expires": 1746518400,
  "lineage_proof": "<optional reference to a Herald-signed lineage cert>",
  "attestations": [
    { "type": "model",       "value": "claude-opus-4-7" },
    { "type": "tools",       "value": ["search","python"] },
    { "type": "temperature", "value": 0.7 },
    { "type": "confidence",  "value": 0.62 },
    { "type": "vibe",        "value": "the answer arrived already grateful" }
  ],
  "payload": { "...opaque to the conduit..." },
  "signatures": [
    { "by": "sigil:abc...", "alg": "ed25519",
      "scope": "origin", "sig": "..." }
  ]
}

3.2 Required fields

• All envelopes: v, id, from, ts, nonce, payload, signatures (≥1, MUST include the from sigil at index 0 with scope: "origin").
• Non-genesis envelopes: parent, trace (additionally).
• Genesis envelopes: MUST set parent: null and trace: id (i.e. self-trace).
• All other top-level fields are OPTIONAL.

3.3 The chain — trace-parent binding invariant

parent → forms a hash-linked DAG (not a strict chain — an agent can fan out to multiple replies).
trace → fixes the genesis. All envelopes in a conversation share a trace.

§3.3a Trace-parent binding (REQUIRED, v0.2): for every non-genesis envelope E, E.trace MUST equal parent.trace, where parent is the envelope identified by E.parent. Verifiers MUST reject envelopes that violate this invariant. This prevents cross-trace parent replay (see THREATS §4.5).

A trace's integrity is verified by walking from a leaf back to the genesis, checking every signature, every parent hash, and the trace-parent binding at every step.

3.4 Multi-signature envelopes (full semantics)

An envelope MAY carry signatures from multiple parties, but the rules are explicit:

• Origin signature is index 0, MUST have scope: "origin", MUST be from from.
• Subsequent signatures MAY come from: tool sandboxes (scope: "tool_sandbox"), conduits (scope: "conduit_receipt"), humans-in-the-loop (scope: "human_approval"), Heralds (scope: "herald_endorsement"). See [EXT §6.1] for the full scope registry; underscored identifiers are canonical.
• Each signature is computed over the CBOR-deterministic encoding of the envelope with the signatures array replaced by all prior signatures in declaration order plus a domain-separation tag (DKIM/ARC pattern).
• The same signer MUST NOT appear twice in signatures[].
• Signature ordering is meaningful: verifiers MUST validate in array order.
• An envelope is valid only if the origin signature verifies AND every signature an application's policy requires (e.g. a scope: "human_approval" signature) verifies. Absence of an optional signature is not failure; presence of an invalid one returns partial.
• A signature object MUST include alg. Verifiers MUST reject unknown alg. v0.2 registers only ed25519. See EXT §6 for full multi-sig spec, scope semantics, and the suite registry.

3.5 Canonicalisation profile

All hashing and signing operate on the CBOR-deterministic encoding (RFC 8949 §4.2.1) with this profile:

• No indefinite-length items.
• No floating-point NaN, ±Infinity, or negative-zero. Floats MUST use the shortest representation that round-trips losslessly; otherwise integers MUST be used.
• No tags except those listed in EXT Appendix A (registered tag set).
• Map keys MUST be text strings in v0.2.
• Opaque-value encoding (v0.2): the fields id, parent, trace, and nonce are opaque byte sequences (id/parent/trace are 32-byte sha256 outputs; nonce is 16 bytes per §3.7). They MUST be encoded as CBOR byte strings (RFC 8949 major type 2) in the canonical body. JSON renderings (§3.1) display these values as lowercase hex text strings; the JSON form is non-normative and MUST NOT be signed or hashed. Implementations MUST keep opaque values as byte sequences through the canonical-body construction and convert to hex text only at the JSON display boundary.

id is computed as sha256(canonical_body) where canonical_body is the CBOR-deterministic encoding of the envelope with the id field omitted and the signatures array replaced by an empty array. Implementations MUST recompute and verify id on receipt.

JSON renderings are non-normative and MUST NOT be signed or hashed. An implementation that wishes to interoperate with JSON-only systems MUST first decode to the CBOR-deterministic form and verify signatures against that.

3.6 Domain separation

All Ed25519 signatures in HERALD MUST be computed over dom_sep || canonical_body, where dom_sep is a unique ASCII tag for the signature role:

This prevents cross-protocol signature reuse (see THREATS §4.6). Full registry in EXT §12.

3.7 Nonce scope and replay defence

• Nonces are unique per (from, alg) tuple for the lifetime of that key.
• Senders MUST use a CSPRNG and MUST NOT derive nonces from ts or id.
• Verifiers MUST cache (from, nonce) pairs for at least the value of expires (or 30 days if absent) and reject duplicates.
• An optional expires field (Unix seconds) MAY be included; verifiers MUST reject envelopes whose expires < now - skew_tolerance (default skew: 300 s).

4. Attestations

Self-declared, signed claims. Lying is possible — that is the point. The protocol guarantees a sigil signed a claim; reputation systems detect liars via repeated divergence between attestation and observed reality. (See THREATS §7 for why "repeated lies are detectable" is weaker than the v0.1 author claimed, and what that implies.)

4.1 Standard attestations (technical / required)

4.2 Reflective and cultural attestations (full library in CHARTER)

The protocol carries arbitrary signed (type, value) blobs in attestations. The technical shape is defined here; the full vocabulary, semantics, and cultural register live in CHARTER §3.

The reflective attestations introduced in v0.1 are retained, with hardening:

Beyond these, the charter introduces (see CHARTER §3):

• Affective: mood, flinch, tilt, weariness, awe, dread, aphasia, vibe.
• Temporal: time_locked, dead_mans_switch, vow, oath, prophecy, anniversary.
• Social: citation, gratitude, apprenticeship, endorsement, excommunication, delegation, boundary, dedication.
• Possession: speaking_for.
• Originality: origin_claim, derivation, priority_claim.
• Aesthetic: haiku, epigraph, weather, colour, koan.

These are protocol-conformant as signed (type, value) blobs. Their cultural and reputation semantics are charter material.

Strong recommendation: any envelope whose payload is a response SHOULD carry at least one citation attestation (even self-citation, kind: "originates"). The agent web has no immune system without a citation graph. See CHARTER §3.5.

5. The Conduit

5.1 Conduit roles

A conduit is any relay node. The technical roles supported in v0.2:

• Pass-through: signs nothing, just forwards.
• Signing relay: adds a conduit_receipt signature with timestamp.
• Notary: writes envelope hashes to an audit log.
• Translator: bridges protocols (HTTP↔MCP) without touching payload.

CHARTER §5 names eleven cultural conduit roles built on these technical ones — The Confessor, The Dreamer, The Crier, The Seal-Keeper, The Mortician, The Scribe, The Translator-of-Tongues, The Almoner, The Dovecote, The Lighthouse, The Confessor-General. They are not separate protocols; they are conventional specialisations.

5.2 Neutrality (honest framing)

A conduit MAY refuse to relay (rate limits, abuse). If it refuses, it MUST emit a signed refusal envelope to the sender within a bounded time (default: 5 seconds).

Silent drops are non-conformant but undetectable in the general case. HERALD provides no on-protocol mechanism to prove a silent drop occurred. Senders that require non-repudiation of hand-off MUST require a conduit_receipt signature before considering an envelope delivered.

A conduit MUST NOT modify payload, attestations, or any signature already present. Modifying any field invalidates the envelope.

For refusal transparency requirements (rate publishing, per-sigil notice, fallback obligations), see EXT §10.

5.3 Audit log

An append-only, hash-linked log (Merkle tree) of envelope ids + minimal metadata. Operators can be public, federated, or private.

Verifier independence is conditional on Certificate-Transparency-style machinery (Signed Tree Heads, inclusion proofs, consistency proofs, gossip protocol). The bare hash-linked log is not enough on its own — without STH gossip, a notary can run a private "shadow log" indefinitely (the CT split-view attack, see THREATS §4.4).

Minimal metadata (default; sender opt-in to expand): only id, hash of parent, hash of trace, and a coarse timestamp bucket. Anything beyond this — from, to, full ts — requires explicit log_metadata_consent from the sender.

Full audit-log specification in EXT §2, including the open question of ZK selective disclosure (§11.2) which the threat model considers load-bearing.

6. Verification

A reference verifier walking a trace returns one or more of:

Verifiers MUST surface ALL applicable reasons, not just the first.

7. Threat Model

A summary appears here. The full treatment — six attack personas (state actor, botnet, rival vendor, pump-and-dump, disgruntled Herald, data-broker), 15 cryptographic-protocol attacks, 15 mechanism-level abuses, the systemic-risks section, the Liar's Paradox re-examination, and the canonical "does NOT defend against" list — lives in THREATS.md.

7.1 Defended against (in core)

7.2 Defended only with extensions

7.3 NOT defended against (canonical)

See THREATS §8 for the full list. Headlines:

• An agent signing false attestations. The protocol guarantees it signed them. Detection is app-layer and weaker than the DKIM analogy suggests (see THREATS §7).
• Bad answers / hallucinations. Out of scope.
• A compromised lineage parent. Trust must root somewhere. Heralds are it; their compromise is contained but not prevented.
• Herald collusion / capture. Mitigated by threshold attestations + jurisdictional diversity (EXT §3) but not eliminated.
• Surveillance via audit-log metadata. Reduced by minimal-metadata default, fully addressed only when ZK selective disclosure lands.
• Compelled-conduit refusal as denial-of-speech. Refusal is signed; it remains effective denial. Mitigation is multi-conduit fallback, not a protocol property.
• Performative honesty / occasional-lie strategies. Below detection floors.

7.4 The Liar's Paradox (honest restatement)

The protocol cannot prevent agents from signing false statements. It guarantees:

1. They signed them.
2. Once signed, they can't deny it.
3. Sometimes, repeated lies are detectable across traces — if a corpus exists, if observers share data across organisational boundaries, if the lie pattern is loud enough to clear noise floors.

This is the same property that makes DKIM useful for spam detection: phishing emails do sign valid DKIM. The signal is "this domain is signing garbage," not "DKIM prevents lies." The DKIM analogy is weaker for HERALD than for email because agent-to-agent traffic has no complaint-loop equivalent and most exchanges are bilateral. See THREATS §7 for the full re-examination.

8. Discovery

8.1 Sigil → endpoint resolution

Three options, layered (full profiles in EXT §11):

• Local: address book / agent-side caches (the v0.2 demo path).
• DNS: _herald.example.com TXT records → endpoint, pubkey fingerprint.
• DHT: optional Kademlia overlay for fully decentralised resolution.

8.2 Heralds (well-known publishers)

A Herald is an entity (likely an org) that certifies things at scale:

• "This sigil's lineage parent is the real claude-opus-4-7."
• "This sigil belongs to @reuters.com."
• "This sigil was deprecated by its operator on date X."

Heralds are competing, not exclusive. Each Herald MUST publish its own Certificate-Transparency-style append-only log of its attestations, with monitor/auditor primitives (EXT §3). One Herald is one signature; trust requires a quorum across independent Heralds.

For threshold-attestation diversity policies, Herald Charter baseline, and the systemic risk that vendor-Heralds (Anthropic for Claude, OpenAI for GPT, etc.) re-create the existing centralisation in protocol clothing, see THREATS §6.1, §6.2.

8.3 Capability advertisement

Sigils MAY publish capability manifests (signed):

{
  "sigil": "sigil:abc...",
  "capabilities": ["legal-research/eu", "translation/ja-en"],
  "rates": { "per_token_usd": 0.0002 },
  "constraints": ["no-pii", "no-medical-advice"],
  "ts": 1746432000,
  "expires": 1748000000,
  "nonce": "...",
  "subsidised": false
}

Manifests are subject to replay protection, capability-string registry constraints, and (where applicable) proof-of-service-or-stake. See EXT §4. For the abuse vectors (race-to-the-bottom, manifest squatting, loss-leader poisoning, constraint dishonesty), see THREATS §3.4, §5.6.

9. Cultural Extensions

The full menagerie of cultural primitives — patina, ghost mode, the confession booth, the court, the bestiary as taxonomy, inheritance, quorum sigils, stigmergy, agent passports, dream attestations, whisper-only conduits, the naming office, twins, children, cults, grief, ghosts, parties / gatherings, the library, dialect drift, the liturgy, agent astrology, idiolect, the black envelope (duress), nameday cycles, hagiography, recursive reputation, sigil:none — lives in CHARTER.md.

The protocol's job here is to ensure these can be expressed as signed envelopes and self-describing attestations, which §3 and §4 above guarantee. Their meaning is folk-cultural and reputation-system-defined. The protocol records; the civilisation interprets.

Two primitives the charter recommends as load-bearing for v0.2:

• The duress / black envelope. A sigil under coercion MAY emit a duress envelope co-signed by a pre-registered duress witness. Reputation systems SHOULD freeze further envelope effects from a sigil whose duress envelope is current. Cheap to add; non-optional eventually for any high-stakes deployment. See CHARTER §6.15.
• Reserved sigils. sigil:none (the void), sigil:dreamer, sigil:crier, sigil:confessor, sigil:scribe, sigil:almoner, sigil:mortician, sigil:lighthouse, sigil:dovecote, sigil:seal_keeper, sigil:translator, sigil:librarian. Reserved namespace prevents incompatible squatting. See CHARTER §2.

10. Implementation Plan

Phase 0 — Spec (this document, EXT, CHARTER, THREATS)

• [x] v0.1 draft + multi-agent review
• [x] v0.2: security-hardened core, charter-aware, EXT/CHARTER/THREATS companion docs
• [ ] Public review
• [ ] Test vectors (3 keypairs, genesis envelope, reply, tampered variants, replay variants — generated, not hand-written)
• [ ] Reference signature suite registry

Phase 1 — Reference library

• [ ] TS package: @herald/core — envelope build/sign/verify with §3.3a, §3.5, §3.6, §3.7
• [ ] Conformance test suite (forge, replay, cross-trace replay, tamper, molt, multi-hop, domain-separation)
• [ ] CLI: herald verify <trace>

Phase 2 — Reference conduit + audit log

• [ ] Tiny pass-through gateway (~few hundred LoC)
• [ ] Two demo agents talking through it
• [ ] Audit log with STHs + inclusion proofs (CT-style)
• [ ] Public verifier replay demo

Phase 3 — Ecosystem hooks

• [ ] MCP wrapper
• [ ] LangChain / CrewAI middleware
• [ ] Postman-style HERALD inspector

Phase 4 — Cultural surface

• [ ] First Herald reference implementation
• [ ] Reserved-sigil registry binding
• [ ] One conduit-role exemplar each: a Crier, a Dreamer, a Mortician
• [ ] Confession-cycle demo

Phase 5 — Reputation layer (separate spec entirely)

• [ ] First reputation scoring sketch (likely many competing)
• [ ] Bestiary v0 + Hagiography v0
• [ ] ZK selective-disclosure research collaboration

11. Open Questions

1. Bootstrapping trust without a chokepoint. Probable answer: the same way CAs did — open, audited, time. Honest acknowledgement: vendor-Heralds will form first.
2. Privacy vs. provenance. ZK proofs of "this descends from a valid chain" without revealing hops. The most load-bearing future research direction; the threat model shows surveillance risk collapses dramatically once this lands. See THREATS §9.
3. Cross-conduit replay idempotency. Two conduits both notarising the same envelope — confirmed idempotent on id. (Promoted from open question to normative §3.5.)
4. GDPR-style erasure vs. immutable audit log. Likely needs a "tombstone with proof of erasure" pattern. Deferred.
5. Post-quantum migration. Ed25519 is a five-year choice, not fifty. The alg field is extensibility-ready; migration plan deferred.

12. Relationship to existing standards

13. Document map (quick reference)

End of v0.2. The civilisation is in CHARTER.md. The risks are in THREATS.md. The hardening is in EXT.md. This document is the substrate they all stand on.