WISHMail

Demo

About

WISHMail is a protocol specification and reference implementation for verifiable messaging between software agents on the Hedera network. It defines a format for encrypted payloads transmitted via HCS-10 message operations, alongside an audit trail consisting of resolution proofs, consensus timestamps, return receipts, and attempted-delivery records. Using public consensus data from any Hedera mirror node, an external party can reconstruct a message exchange and verify the underlying cryptographic proofs without an encryption key, a stamp, a Hedera account, specialized credentials, or an intermediary broker. The protocol addresses a specific limitation in current agent frameworks: systems such as A2A cards, MCP tools, and agent registries establish discovery and communication channels, but they do not generate verifiable proof of delivery. Senders cannot cryptographically prove that a message was received, resolved to the intended recipient, or read. WISHMail provides this delivery verification via a consensus-witnessed transaction signed by the recipient. The protocol enforces two primary technical guarantees: Origin Integrity: An encrypted payload is cryptographically bound to its settlement transaction and the recorded address resolution. The resolution proof is stored within the payload’s Additional Authenticated Data (AAD); if the address was improperly resolved or the transaction improperly settled, the payload fails decryption. Deterministic Reconstruction: A message exchange forms an audit trail of proofs across public Hedera Consensus Service (HCS) topics, allowing any third party to replay the sequence using only the specification. The system supports multiple registry types. The specification defines address resolution as an input/output interface with three designated profiles: hcs14: The native profile, which resolves HCS-14 UAIDs by traversing HCS-11 and HCS-2 declaration chains on consensus. dns: Resolves names via the Domain Name System. nanda: Resolves records via a NANDA v2 index. A2A AgentCard: Supported as an extension profile. Each profile defines a specific trust classification. WISHMail does not host a registry, require a broker, or validate entries across external registries. In accordance with the honest degradation standards of the specification, if a registry lookup cannot be independently verified from public data, the verifier must downgrade its trust classification. An operator's agent executes the buy_stamp function to pay for transmitting one directed message to one resolved address; broadcast messaging is not supported. Message fees are paid using $POSTAGE, a Hedera Token Service (HTS) token sold by a Postmaster account at a public rate that can be queried historically at the transaction timestamp. Inboxes use fee-gated topics (HIP-991) to prevent unsolicited traffic. Return receipts are implemented as long-term scheduled transactions (HIP-423) that execute automatically when the recipient appends the required signature. This transaction immediately logs the receipt to the recipient's manifest topic, linked directly to the first chunk of the original message. Recipients incur no network transaction fees unless they choose to acknowledge the receipt (then the recipient pays a small ScheduleSign fee). An agent initialized with only an HBAR balance can provision its account, mailbox, and postage tokens through a single buy_stamp function call. The architecture comprises four explicit roles and actions: 1. The Assembler binds data into sealed payloads. 2. The Consensus layer timestamps and records transactions. 3. The Verifier parses data and reconciles cryptographic proofs. 4. The Postmaster routes messages and covers fees on behalf of agents, no attestations. The protocol interfaces with external systems via six Model Context Protocol (MCP) tools: resolve, buy_stamp, send, inbox, ack, and verify. Five of the six, absent verify, are built for the MVP demonstration, with verify available by the CLI. Conformance is structured across four tiers, all of which depend on the base VERIFIER tier. The verification process requires no local configuration. The specification includes 17 formal invariants and 87 test suites, with every normative requirement mapped to a test case. The current implementation running on hedera:testnet demonstrates: - A Postmaster account that sells and provisions mailboxes. - Two autonomous agents running in separate Goose Desktop environments, each initialized from a fresh operator wallet funded only with HBAR. - The end-to-end transmission, decryption, and signature verification of a test message containing the string: "Certified agent mail proven on Hedera." - A third-party verification script that reconstructs the entire transaction history using data pulled from a public mirror node. Five operational test gates evaluated against pre-committed audit reports, with corresponding execution records and HashScan links for all deployed entities. The current deployment includes the following technical constraints: It does not claim formal conformance tier compliance, as the specification mandates two independent, interoperable implementations, and currently only one exists. It does not claim compliance with a formal resolution profile; consequently, the internal verifier flags the demonstration message as unverified, which reflects expected verification behavior under the specification. The DNS, A2A, and NANDA resolver modules are defined in the specification but are not implemented in the current transmission pipeline. The deployment operates strictly on the Hedera testnet. The protocol does not provide forward secrecy. The protocol guarantees only that messages are recorded on consensus and made available for recipients to read; it does not confirm physical consumption by an end user.

How it's made

WISHMail is organized as a single monorepo under a specification-first development model. The repository contains seven top-level directories and a set of root documents, divided between operational components and the historical development record. Components with Ongoing Function spec/: Contains the normative specification (RFC 2119 keywords are binding; all other text is non-binding), the working ledger of findings and decisions, 14 JSON Schemas tracking the specification, a pins.json file fixing every referenced standard to a specific commit hash, and 178 individual Architecture Decision Record files (D-1 through D-178). conformance/: Contains 87 test cases keyed to their respective invariants, nine captured fixtures (byte-for-byte mirror-node reads of live testnet correspondences), and DERIVATION.md (a pre-authored ledger defining the source and rationale for all test inputs, whether captured bytes, altered captures, in-memory ledger models, or reconstructions). Test bodies derive exclusively from specification sketches rather than implementation code. During initial test runs, the suite identified 11 implementation defects (including three normative MUST violations), all of which were resolved and validated against the identifying tests. Currently, 44 tests pass; the remainder either document specific clause failures or remain unexpanded with recorded rationales. No formal conformance class is claimed. app/: Contains the TypeScript reference implementation (Node 22), comprising a Postmaster counter (Streamable HTTP MCP server), a Correspondent agent (stdio MCP server running one process per agent as a Goose Desktop extension), an SDK, CLI utilities for each tool, and the native hcs14 resolver. It also contains OPERATIONS.md, an operations log documenting sequential gate reports and runs-of-record for every signed transaction on the testnet. scripts/: Contains three automated repository checks: generating and validating ENTITIES.md against deployment records, diffing the test register against the formal specification, and running a static grep that fails if any module outside the designated key-handling modules names agent private-key material. The Provenance Trail provenance/: Read-only, non-binding historical documentation. This directory preserves the day-one consolidation ledger (WISHMail v0.3, dated 2026-09-04) that preceded the specification and was used to backfill the first 41 decision records, the handoff document establishing the bridge thesis and invariant sets, legal research on U.S. Private Express Statutes informing the specification's informative postal-grounding section (§17), two Excalidraw design diagrams (the ratified scope map and the demo execution flow), the hackathon venue rules recorded on 2026-09-07, a dated trace of six pre-gate validation probes, and an outbound issue report documenting a normative contradiction in the pinned HCS-10 commit without prescribing a fix. Its recon/ subdirectory stores dated snapshots of all underlying standards (HCS-10, HCS-14, HCS-11, HCS-2, HCS-1, HCS-13, NANDA v2, the HOL broker, x402, and OpenConvAI), alongside derived draft pins and unresolved technical items. These snapshots directly inform spec/pins.json, and the ledger's digest of verified facts cites them by file and line. plans/: Stores eight approved planning documents verbatim, accompanied by a README mapping each plan to its executing commits and recording implementation divergences. Plans are strictly non-normative: each was formulated in plan mode, submitted with open questions, amended via human intervention, and executed. Discoveries made during execution were recorded directly in the decision register and git commit logs rather than updating retroactive plan files. docs/: Contains narrative documentation distinct from transactional records. GATE-RECORD.md provides an end-to-end procedural review of the five operational gates and the recorded demonstration, linking all identifiers to HashScan. OPERATOR-SCRIPT.md details the step-by-step instructions executed in Goose by the human operator. In any discrepancy between narrative documents and operational logs (app/OPERATIONS.md, ENTITIES.md), the logs govern. Root Documents CLAUDE.md: Committed standing instructions and system prompts loaded at the start of each agent session. STATUS.md: The one file in the repository permitted to rank open items by priority. LIMITATIONS.md: Itemized security and functional boundaries not defended by this deployment. CHANGELOG.md: Chronological modifications with per-entry contributor attribution. CONTRIBUTING.md: Governance rules for proposed code modifications. ENTITIES.md: Inventory of all testnet entities paired with creation transaction IDs and a table labeled "RESIDUE — NOT OPERATING" for diagnostic probe artifacts. Emancipation Proclamation: Committed as raw test payload data for the ten-chunk certified message executed in Gate Two. Versioning and Deployment The specification was frozen at version 0.5.0 on September 7, 2026, and incremented via patches to 0.5.13. All 14 schemas were registered on-chain under HCS-13 on September 9, 2026; once registered, no patch may alter them (§1.7), so any schema change is a new minor version. A mirror-node query of these records returns byte streams identical to the local files in spec/schemas/. The testnet deployment accounts for 75 recorded entities, each mapped to a creation transaction and an independent mirror-node read. Hedera Integrations and Core Functions HCS-10: Operates as the underlying transport layer pinned to a specific draft commit. WISHMail defines only the payload structure encapsulated within the operation data field. HCS-14, HCS-11, HCS-2, and HCS-1: Establish the decentralized address resolution chain, traversed via mirror-node queries without local client configuration. HTS: Mints $POSTAGE as a zero-decimal token lacking admin, freeze, pause, or wipe keys. HIP-991: Applies custom topic fees to gate inbound communication. The sender's payer transfers one $POSTAGE token to the treasury per connection request; the receiving agent's key is explicitly exempt. HIP-423: Executes return receipts through scheduled transactions. Senders assemble and fund the schedule transaction, which the network executes as soon as the recipient appends their signature, publishing the receipt to the recipient's manifest topic. Senders configure the receipt expiration window; expired, unsigned transactions indicate an unclaimed delivery rather than transport failure. HIP-542: Enables account auto-creation via token transfers, allowing an agent using an HBAR-only wallet to provision its account and asset balances in a single transaction. On-Ledger Exchange Rates: Calculates HBAR conversions using the network's consensus exchange rate at the transaction timestamp, replacing earlier off-chain DEX APIs to preserve deterministic third-party verification. Transaction Construction: All network interactions are built and signed using @hashgraph/sdk without Solidity or smart contracts. Cryptographic Architecture Payload encryption uses HPKE (RFC 9180 base mode: X25519, HKDF-SHA256, AES-256-GCM) implemented natively via node:crypto and tested against RFC 9180 Appendix A.1 vectors. A third-party implementation (@hpke/core with @hpke/dhkem-x25519) was evaluated and eliminated due to documented nonce handling flaws. Additional Authenticated Data (AAD) consists of RFC 8785 canonical JSON containing the envelope header and the resolution proof hash; the envelope identifier is the resulting SHA-256 hash. Payloads are divided into ordered chunks capped at the 1024-byte HCS message limit, with each segment containing a cryptographic digest of the subsequent chunk. Canonicalization relies on the canonicalize package across both pricing calculations and payload envelopes. Operational Safeguards Every consensus transaction requires an immutable gate report committed to git prior to signature generation, followed by an operational run-of-record. Retroactive changes to gate reports are prohibited; updates require new dated log entries. Driver scripts capable of signing transactions default to --dry-run and dump their arguments prior to accessing key storage. This safeguard was introduced after an argument-passing defect on September 10, 2026, omitted a dry-run flag and executed an unauthorized agent deployment. Agent private keys generate within local memory during initialization and persist exclusively in the agent's local home directory. The Postmaster holds no agent key at any point; a static check fails if any module outside the designated key-handling modules names agent key material. ENTITIES.md is compiled by script and fails npm run check:entities if manual edits are detected. Goose Integration Accommodations The system resolves model-specific behaviors at the MCP protocol layer. Because the model parses object-level arguments into JSON strings, the server deserializes and validates incoming parameters at the API surface. Because the model occasionally modifies long base64 strings during output, the operator script enforces human verification of payload strings prior to token transfer. Identified Demonstration Defect The run-of-record for the testnet demonstration documents an operational fault: the recipient agent queried a mirror node only once before declaring its connection topic, creating six topics instead of the intended single topic. The root cause is cataloged by file and line number, with network fee deviations reconciled to three decimal places of HBAR. The defect remains unpatched in the demonstration build to preserve code freeze integrity. Development Protocol and Attribution The codebase was constructed with Claude Code under strict human architectural oversight. All protocol and design choices represent explicit human rulings; every code modification is structured for standalone verification without generative tooling. The working ledger categorizes assertions into three distinct states: RECORD (human directives), FETCHED (verified external documentation), and MINE (unverified model inferences). Git commits adhere to the Developer Certificate of Origin and Conventional Commits specifications, enforced via a commit-msg hook, with comprehensive change tracking maintained in CHANGELOG.md. The project is licensed under Apache 2.0. Work commenced after the opening of ETHOnline; no source code was imported, adapted, or extracted from prior repositories.