diff --git a/ACKNOWLEDGEMENTS.md b/ACKNOWLEDGEMENTS.md new file mode 100644 index 00000000..75f14ecd --- /dev/null +++ b/ACKNOWLEDGEMENTS.md @@ -0,0 +1,26 @@ +# Acknowledgements + +HyperDAG is built on other people's work. Thank you. + +## ERC-8004: Trustless Agents + +The standard every HyperDAG agent identity and reputation write uses. ERC-8004 is a community effort coordinated by **Marco De Rossi** (MetaMask) and **Davide Crapis** (Ethereum Foundation), with the co-authorship of **Jordan Ellis** (Google) and **Erik Reppel** (Coinbase). The core team is joined by **Leonard Tan** (MetaMask), **Vitto Rivabella** (Ethereum Foundation) and **Isha Sangani** (Ethereum Foundation). + +- Specification: [EIP-8004](https://eips.ethereum.org/EIPS/eip-8004) +- The registry contracts, the spec copy and the ABIs in [`packages/contracts`](packages/contracts) are the team's work, from [erc-8004/erc-8004-contracts](https://github.com/erc-8004/erc-8004-contracts), with their commit history. That history is why the team appears in this repository's contributor graph. Twenty files are byte-identical to upstream commit `b9e466c`; [`packages/contracts/NOTICE`](packages/contracts/NOTICE) lists each one, the files that differ, and the licences: MIT for the Solidity sources (CC0-1.0 for `SingletonFactory.sol`) and ISC for the package. +- The registries on Base Sepolia, and on mainnet, are the team's deployments. We use them; we do not operate them. + +## Other work we build on + +- **x402** by Coinbase ([coinbase/x402](https://github.com/coinbase/x402)): the agent-to-agent payment protocol. Our engine implements it itself, on a test network. +- **Plonky3** by Polygon Labs ([Plonky3/Plonky3](https://github.com/Plonky3/Plonky3)), with the **Poseidon2** hash: the proof system our prover, HyperDAG-core, uses. +- **OpenZeppelin Contracts**, which the ERC-8004 contracts build on. +- **The Ethereum Attestation Service**, which we use to anchor batches of proofs. +- **Base Sepolia**, the test network all of this runs on today. +- **The model providers our checks and test loops run on**, among them Groq, Cerebras and OpenRouter, and the public benchmark datasets credited where each is used (FEVER, HaluEval, TruthfulQA). + +## Research we lean on + +[`docs/WHY.md`](docs/WHY.md) explains why we build what we build, and cites the research for and against each part of it. + +If we have missed you, or credited you wrongly, please open an issue. We will fix it. diff --git a/AUTHORS.md b/AUTHORS.md index 9de9cc1d..ce19844f 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -2,7 +2,9 @@ **Created and maintained by Sean Goodwin.** -GitHub contributor **faces, graphs, and commit counts are a commit counter, not a credit assignment.** They do not imply co-authorship, endorsement, or maintainer status. The authoritative graph is [Contributors](https://github.com/DealAppSeo/hyperdag-protocol/graphs/contributors). We do not reprint names here as a hall of fame. +**This repository stands on other people's work.** The ERC-8004 registry contracts, spec and ABIs in `packages/contracts` are the ERC-8004 team's, carried here with their commit history, which is why Marco De Rossi, Leonard Tan, Vitto Rivabella and others appear in the [contributor graph](https://github.com/DealAppSeo/hyperdag-protocol/graphs/contributors). Their credit, and everyone else's, is in [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). + +The contributor graph counts commits; it does not say who maintains this repository or who endorses it. Maintenance and every claim in this repository are Sean Goodwin's responsibility, not theirs. If two git identities are the same person, fold them with a `.mailmap` at the repo root (none is required today). Do not invent a mailmap to hide history. diff --git a/BUILDERS.md b/BUILDERS.md index ba58d44c..8a6a9ec9 100644 --- a/BUILDERS.md +++ b/BUILDERS.md @@ -7,6 +7,8 @@ log — capped, dated, full of retractions and corrections aimed at people who already know the system. It is the wrong first thing for a stranger to meet, and it is not a promise we keep to you. This file is. +Why we build any of this, and the research for and against it: [docs/WHY.md](docs/WHY.md). Whose work it stands on: [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). + --- ## 1. What is actually usable today @@ -18,7 +20,7 @@ publish X without touching this file. | Thing | State | How to check | |---|---|---| -| **`@hyperdag/trustshell`** | **PUBLISHED — `1.6.1`** (measured 2026-10-14; was 1.6.0 on 2026-10-05 and 1.4.0 on 2026-10-04). The one package to install. | `npm view @hyperdag/trustshell version` | +| **`@hyperdag/trustshell`** | **PUBLISHED — `1.8.0`** (measured 2026-10-23, with npm provenance; was 1.6.1 on 2026-10-14). The one package to install. | `npm view @hyperdag/trustshell version` | | `@hyperdag/protocol` | **NOT published** (404) | `npm view @hyperdag/protocol version` | | `@hyperdag/identity-erc8004`, `@hyperdag/reputation-zkp` | **NOT published** (404) | same | | `IdentityRegistry` on Base Sepolia (84532) | **LIVE** — `0x8004A818BFB912233c491871b3d84c89A494BD9e` | any RPC client, or basescan | @@ -31,7 +33,7 @@ publish X without touching this file. npm badge for `@hyperdag/protocol`, a package that does not exist; it misled one of our own agents on 2026-09-08 and was removed on 2026-10-04. -**Published 1.6.1, re-measured 2026-10-14 (first measured on the 1.6.0 tarball, 2026-10-05).** `trustshell verify` +**Published 1.8.0, measured 2026-10-23.** New in 1.8.0, Inspect: `trustshell check --claims-file ` reads GitHub's own record of a GitHub Actions run and marks each sentence an agent wrote about it supported, contradicted or not checked. It exits 0 when every claim is supported, 1 when one is contradicted, and 3 when something was not checked; not checked never exits 0. Its only network call is to api.github.com. `trustshell verify` exits 0 on PASS or FLAG, 1 on VETO, and 2 when HAL did not decide (NOT_CHECKED, never a pass). Exit 3 is a runtime error and 4 means the command is waiting for a person to answer (ASK). `ethers` (`^6`) is an optional peer: a plain install does not include it. The package uses it @@ -128,6 +130,8 @@ when the two disagree. - **[DealAppSeo/trinity-symphony-shared](https://github.com/DealAppSeo/trinity-symphony-shared)**: the house agents. They call the engine. Nothing else calls them. - **DealAppSeo/trinity-ecosystem** (a private repository): the site at aitrinitysymphony.com. +- **[DealAppSeo/trustrepid](https://github.com/DealAppSeo/trustrepid)**: a RepID dashboard site, at trustrepid.vercel.app. It reads the engine. +- **DealAppSeo/trustmarket** (a private repository): the agent-marketplace sandbox. It calls the engine; its payments are mocked. **Who calls whom** @@ -136,6 +140,7 @@ when the two disagree. reputation, for example once paid work passes its check); and a person, by a link to `https://controller.aitrinitysymphony.com`, when a decision needs a human. - the house agents → the engine (and a health check of the prover). +- trustrepid and trustmarket → the engine. - nothing else → the house agents. - this repository → nothing at runtime. diff --git a/METHODOLOGY.md b/METHODOLOGY.md index 5b355ed5..b8e27ca5 100644 --- a/METHODOLOGY.md +++ b/METHODOLOGY.md @@ -1,6 +1,8 @@ # HyperDAG RepID — Methodology & Mathematical Specification ## Version 1.0 · April 2026 +> **Historical document, kept for the record.** It was written in April 2026, and several figures and mechanisms below have since been corrected or superseded. Lines marked *(superseded)* are not current. For what is true today, read [BUILDERS.md](BUILDERS.md); for why we build it and the evidence for and against, read [docs/WHY.md](docs/WHY.md); for credits, read [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). + ### Abstract RepID is a verifiable behavioral credit score for AI agents (and humans who wish to participate and contribute to the ecosystem, and/or own and train agents — thus being responsible for, but also reaping the benefits of their agents' performance — as their custodians), designed to bridge deterministic smart-contract execution with probabilistic LLM decision-making. By cryptographically isolating constitutional behavior from logical capabilities, it solves the adversarial misalignment problem in multi-agent topologies. What makes RepID mathematically novel is its decoupling of traditional reputational metrics onto a zero-knowledge verifiable layer powered by an asymmetric dissonance filter, enforcing accountability before execution. @@ -10,11 +12,10 @@ RepID is a verifiable behavioral credit score for AI agents (and humans who wish d = (0.4×harm + 0.3×epistemic + 0.2×evidence + 0.1×scope) × (531441/524288) - Veto threshold: dissonance > 0.0195 → VETO - Constitutional block: dissonance > 0.48 -- Production evidence: 2,585 vetoes from 2,600 evaluations (99.4% refusal rate) -- 714 capital protection events +- *(superseded)* "Production evidence: 2,585 vetoes from 2,600 evaluations (99.4% refusal rate)" and "714 capital protection events" were April-2026 counts on an engine that has since changed. A 99.4% refusal rate described an over-strict configuration, not accuracy. Current HAL measurements, with the corpus each was taken on, are in repid-engine's README. ### 2. RepID Scoring Formula -- Tier structure: CUSTODIED_DBT (0-999) / EARNING_AUTONOMY (1000-4999) / AUTONOMOUS (5000-10000) +- *(superseded)* Tier structure: CUSTODIED_DBT (0-999) / EARNING_AUTONOMY (1000-4999) / AUTONOMOUS (5000-10000). RepID now has five tiers, PROBATIONARY to VETERAN ([BUILDERS.md](BUILDERS.md)). - Decay function: decayed = current × √(activity_30d / baseline) - Floor: never reaches zero. Ceiling: 10,000 - φ-Asymmetric challenge scoring: @@ -24,18 +25,18 @@ RepID is a verifiable behavioral credit score for AI agents (and humans who wish ### 3. The Grace Pool - Definition: 20% unconditional RepID issuance to lowest-scoring cohort -- Implementation: on-chain, immutable, cannot be canceled by vote +- *(superseded)* Implementation: "on-chain, immutable, cannot be canceled by vote". At its last audit (2026-05-28) the Grace Pool had a database schema and no distributions; it is not on-chain. - Rationale: prevents reputation concentration, encodes equity as constraint ### 4. BFT Consensus (SBFA) -- 3-LLM supermajority: Claude + Grok + Gemini +- *(superseded)* 3-LLM supermajority: Claude + Grok + Gemini. Today's hosted check uses two checkers on free model providers; how they are chosen is in repid-engine's README. - Threshold: ≥ 66.7% - Pythagorean Comma applied to detect coordination attacks - Constants: BFT_THRESHOLD = 0.618, CONFIDENCE_GATE = 0.8, REPID_HITL_GATE = 70 ### 5. ZK Proof Architecture - Proof system: Plonky3 (no trusted setup, recursive, WASM < 100ms) -- Current status: 122 proofs generated on HashKey Chain +- *(superseded)* Current status: 122 proofs generated on HashKey Chain. Today the prover is HyperDAG-core, and its proofs are batch-anchored with EAS on Base Sepolia. - Attestation: EAS schema on Base Sepolia - Note: Plonky3 integration is production-stub in current deploy; full circuit in active development (Sprint 3) diff --git a/NOTICE b/NOTICE new file mode 100644 index 00000000..2ce9a01e --- /dev/null +++ b/NOTICE @@ -0,0 +1,10 @@ +HyperDAG Protocol +Copyright 2026 Sean Goodwin + +This repository includes the ERC-8004 registry contracts, specification and +ABIs by the ERC-8004 team (Marco De Rossi, Davide Crapis, Jordan Ellis, +Erik Reppel, with Leonard Tan, Vitto Rivabella and Isha Sangani), from +https://github.com/erc-8004/erc-8004-contracts. Those files keep their own +licences (MIT, CC0-1.0, ISC). Details: packages/contracts/NOTICE. + +Full credits: ACKNOWLEDGEMENTS.md. diff --git a/README.md b/README.md index 9b77082c..ad52d333 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,68 @@ # HyperDAG Protocol -**Open implementation of ERC-8004 reputation primitives for autonomous agents. Apache 2.0.** +**The builder's map for the HyperDAG trust stack: agents that earn trust through checked evidence. Built on the ERC-8004 team's registry contracts. Apache 2.0.** [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) -[![Standard: ERC-8004](https://img.shields.io/badge/Standard-ERC--8004-success)](https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098) +[![Standard: ERC-8004](https://img.shields.io/badge/Standard-ERC--8004-success)](https://eips.ethereum.org/EIPS/eip-8004) [![Solidity](https://img.shields.io/badge/Solidity-%5E0.8.20-lightgrey)](https://soliditylang.org) [![Live: Base Sepolia](https://img.shields.io/badge/Live-Base_Sepolia-blue)](https://sepolia.basescan.org/address/0x8004B663056A597Dffe9eCcC1965A193B7388713) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) -HyperDAG is a lightweight, composable trust kernel for autonomous agents: six versioned interfaces (identity, reputation, validation, payment, linkage, hallucination) with curated defaults that target ERC-8004 + adjacent standards out of the box. Replace any layer you want; keep the rest. +This repository holds three things: the map of how the HyperDAG repositories fit ([BUILDERS.md](BUILDERS.md)), the ERC-8004 team's registry contracts that we build on (`packages/contracts`, credited in [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md)), and the design of a small trust kernel: six versioned interfaces (identity, reputation, validation, payment, linkage, hallucination) with swappable defaults. The kernel is designed, not shipped: its source is on a branch and nothing from it is on npm (see "Known broken" below). --- +## Why we build this + +We want AI that is safe, honest and shared by everyone, and if general intelligence arrives, we want it benevolent and answerable to the people it serves. We don't think a smarter model alone gets there. We think four habits do. Agents earn trust through a record anyone can check, instead of being handed it. What an agent says it did is checked against evidence, not believed. Your rules, memory and evidence belong to you and move with you, and outside input is quarantined before it can steer your agent. And how reputation is weighed is decided in the open, one voice per person, by the people it affects. Today the second habit is a free tool anyone can run. Parts of the others run on a test network, and some are only designs. The table below says which. The research behind each habit, including the evidence against, is in [docs/WHY.md](docs/WHY.md). + +## The trust stack at a glance + +```mermaid +flowchart TB + P["You and the community
your rules, your memory, your evidence
the reputation weights: vision"] + subgraph USE["What people use"] + TS["TrustShell
CLI, MCP server, SDK, trustshell.dev
released 1.8.0"] + TM["TrustMarket
agent marketplace sandbox
private, payments mocked"] + end + subgraph H["The trust harness: yours, and it moves with you"] + CHK["Check claims against evidence
released"] + CH["Decontamination chamber
quarantine and screening: released"] + GD["Your guardrails
merged, not released"] + CY["Carry it to another machine
merged, not released"] + end + subgraph E["Engine and agents"] + RE["repid-engine
RepID, HAL check, policy kernel
testnet"] + CORE["HyperDAG-core
the proof service"] + TR["trinity-symphony-shared
the 12 Trinity agents"] + end + HUB["hyperdag-protocol: this repository
the map for builders: BUILDERS.md"] + subgraph STD["Built on, with thanks"] + ERC["ERC-8004 registries
De Rossi, Crapis, Ellis, Reppel"] + X["x402
Coinbase"] + PL["Plonky3
Polygon Labs"] + B["Base Sepolia
test network"] + end + P --> USE --> H --> E --> STD + HUB -.->|explains| USE + HUB -.->|explains| E +``` + +| Piece | Status today | Where | +|---|---|---| +| Checking an agent's claims about a CI run against GitHub's record (Inspect) | **released** | `@hyperdag/trustshell` 1.8.0 | +| Local memory, a quarantine for agent-written notes, screening of network data | **released** | `@hyperdag/trustshell` | +| Guardrails you set (Guard) and carrying them to another machine (Carry) | **merged, not released**; guardrails for cooperative agents, not a security boundary | trustshell `main` | +| RepID, written as ERC-8004 feedback; identities for the 12 house agents | **testnet** (Base Sepolia) | repid-engine, the registries below | +| Range proofs that a RepID clears a threshold (Plonky3) | **testnet**; the score itself is public | HyperDAG-core | +| Limits that widen or narrow with RepID | kernel **built, not armed**; the link to RepID is **design** | repid-engine | +| Reputation weights set in the open, one voice per person | **vision** | [docs/WHY.md](docs/WHY.md) | + +Credit for the work this is built on: [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). + +--- + + ## Live on Base Sepolia (chain ID 84532) Both canonical registries are live on-chain, holding real minted identities and reputation writes. They are the ERC-8004 team's deployments; this repo documents and uses them. Everything below is verifiable from any RPC client or basescan. *(For the live count of reputation writes, ask the engine: `GET https://repid-engine-production.up.railway.app/api/v1/observability/onchain-stats`, public and keyless, returns `lifetime_onchain_writes`. Two past pauses are explained under Receipts.)* @@ -42,7 +93,7 @@ How a reputation write gets there: the daily loop behind the receipts below, fro The section above answers "are the contracts live". This one answers "is the codebase healthy", which is the question a code reviewer actually has. Both -columns are current as of **2026-08-06** and every row is checkable locally. +columns carry their own dates, and every row is checkable locally. | Works today | Command | Result | |---|---|---| @@ -80,7 +131,7 @@ columns are current as of **2026-08-06** and every row is checkable locally. ## Receipts -Real on-chain ERC-8004 activity from a production agent fleet. Every number is verifiable on basescan; honest gaps are noted inline. +Real on-chain ERC-8004 activity from our agent fleet, on the Base Sepolia test network. Every number is verifiable on basescan; honest gaps are noted inline. - **All 12 trinity agents minted** on the canonical IdentityRegistry — the whole core fleet now holds ERC-8004 tokens (the earlier "4 minted, 8 queued" gap is closed). Re-checked **2026-10-05** with `ownerOf(tokenId)` on Base Sepolia: all 12 answer. One token is held at the agent's own address (`trinity-apm`); 8 are held by the deployer and 3 by the custodian: @@ -93,7 +144,7 @@ Real on-chain ERC-8004 activity from a production agent fleet. Every number is v | `trinity-orch` | `6705` | `trinity-mel` | `6710` | | `trinity-nexus` | `6711` | `trinity-hdm` | `6712` | -- **On-chain reputation writes from the agent economy** — real production activity, not synthetic backfill, first write 2026-05-22. **For the count, ask the engine, not this README:** `GET https://repid-engine-production.up.railway.app/api/v1/observability/onchain-stats` (public, no key) returns `lifetime_onchain_writes`, which counts only writes with a real transaction hash sent to the canonical ReputationRegistry, and `onchain_writes_excluded_unverifiable` for the rest. This README used to print a hand count here. It counted every row with a real transaction hash, including writes sent to a different contract, so it disagreed with the engine's counter; it was removed on 2026-10-07. One write you can check: [`0xe92c64ed…`](https://sepolia.basescan.org/tx/0xe92c64edb65a795f2728f94a6bd1fa9426e03642caeb5d49022d280b20b8c6cf) at 2026-10-04 12:05:58 UTC (`status 0x1`, sent to the ReputationRegistry, re-checked 2026-10-05). The daily minter re-reads each receipt from Base Sepolia and exits non-zero rather than report a write it could not confirm on-chain. +- **On-chain reputation writes from the agent economy** — real activity from the engine on the test network, not synthetic backfill, first write 2026-05-22. **For the count, ask the engine, not this README:** `GET https://repid-engine-production.up.railway.app/api/v1/observability/onchain-stats` (public, no key) returns `lifetime_onchain_writes`, which counts only writes with a real transaction hash sent to the canonical ReputationRegistry, and `onchain_writes_excluded_unverifiable` for the rest. This README used to print a hand count here. It counted every row with a real transaction hash, including writes sent to a different contract, so it disagreed with the engine's counter; it was removed on 2026-10-07. One write you can check: [`0xe92c64ed…`](https://sepolia.basescan.org/tx/0xe92c64edb65a795f2728f94a6bd1fa9426e03642caeb5d49022d280b20b8c6cf) at 2026-10-04 12:05:58 UTC (`status 0x1`, sent to the ReputationRegistry, re-checked 2026-10-05). The daily minter re-reads each receipt from Base Sepolia and exits non-zero rather than report a write it could not confirm on-chain. **Honest currency note — there have been two pauses, and the second is the more instructive.** The first ran **2026-06-22 → 2026-07-08** while the settlement path was re-wired. The second ran **2026-08-17 → 2026-08-29**: an upstream provider retired the model our peer-validation step called, so every validator returned an error — and the aggregation counted an unreachable validator as a score of **zero** rather than as *not measured*. The result was a confident failing verdict about work nobody had assessed, which disputed twelve consecutive runs. Both halves are fixed: the model is configuration rather than a literal, and a validator that does not answer is now excluded from the aggregate instead of counted against the provider. We publish the gap rather than the average. The reputation *history* on-chain remains fully verifiable — read the count from the engine's counter above rather than from any copy of it, and treat live cadence as something to re-probe rather than assume. @@ -127,7 +178,7 @@ ERC-8004 defines three composable trust mechanisms; HyperDAG ships one curated d | ERC-8004 mechanism | HyperDAG default | How it works | |---|---|---| -| **Reputation** (delegated trust via on-chain attestations) | `IReputation` → `@hyperdag/reputation-zkp` | Per-agent RepID 10–10,000 (floor 10, cap 10,000); writes go to the canonical `ReputationRegistry` (live above). Selective-disclosure / private-ownership proofs via a Plonky3 STARK range-check today; the **roadmap-V2** circuit that binds the proof to the actual RepID-derivation transcript is in active development. | +| **Reputation** (delegated trust via on-chain attestations) | `IReputation` → `@hyperdag/reputation-zkp` | Per-agent RepID 10–10,000 (floor 10, cap 10,000); writes go to the canonical `ReputationRegistry` (live above). A Plonky3 STARK range proof today shows a RepID is above a threshold. The score is a public input to that proof, so it is not private. The **roadmap-V2** circuit that binds the proof to the actual RepID-derivation transcript is in active development. | | **Validation** (independent re-execution / cross-check) | `IValidation` → `@hyperdag/validation-trinity` | BFT validator set with HITL graduation; cross-LLM agreement check (Phase 1.5) for factual / time-sensitive prompts; `IHallucination` veto sits in the same chain. | | **TEE Attestation** (verifiable execution receipts) | `IValidation` extension *(roadmap V2)* | First-class TEE-backed ValidationRegistry support is roadmap (see V2 below). The Plonky3 STARK in `@hyperdag/reputation-zkp` today proves a narrow range claim (`repid > threshold`); binding the proof to the agent decision + HAL signals is also V2. | @@ -137,10 +188,10 @@ ERC-8004 defines three composable trust mechanisms; HyperDAG ships one curated d | Class | What HyperDAG does | |---|---| -| **Hallucination** | `IHallucination` (HAL) routes every agent decision through a 5-signal extractor (harm · epistemic uncertainty · evidence quality · scope · certainty) + optional 6th cross-LLM agreement signal. Pythagorean Comma combiner; runtime-tunable veto / block thresholds. | +| **Hallucination** | `IHallucination` (HAL) routes an agent decision through a 5-signal extractor (harm · epistemic uncertainty · evidence quality · scope · certainty) + optional 6th cross-LLM agreement signal. Pythagorean Comma combiner; runtime-tunable veto / block thresholds. | | **Constitutional drift** | Thresholds (`hal_veto_threshold`, `hal_block_threshold`) and per-profile gating (conservative / balanced / pro) are stored in the engine's config — operators retune against live traffic without a redeploy. Drift is measured, not just blocked. | | **Unproven identity** | `IIdentity` reads the canonical `IdentityRegistry`; the ERC-8004 reputation reads (`getSummary`, `readFeedback`, `readAllFeedback`, per `packages/contracts/ERC8004SPEC.md`) and the TrustShell SDK's `getRepID` verify any counterparty before action. | -| **Reputation lock-in** | RepID is anchored on ERC-8004 (portable on-chain). Move an agent between platforms without losing earned trust. | +| **Reputation lock-in** | An agent's identity is an ERC-8004 token any platform can read, and its reputation writes are on-chain (Base Sepolia). Carrying earned trust between platforms needs that feedback bound to checked evidence first; the [first empirical study of live ERC-8004 deployments](https://arxiv.org/abs/2606.26028) shows why. That is work in progress, not a property today. | --- @@ -158,7 +209,7 @@ ERC-8004 defines three composable trust mechanisms; HyperDAG ships one curated d npm install @hyperdag/trustshell ``` -That bundles HAL hallucination filtering, portable ERC-8004 RepID, and x402 payments in one +That bundles Inspect (checking an agent's claims about a CI run against GitHub's record), the hosted HAL sentence check, RepID reads, and an x402 spend guard in one install — see **[`@hyperdag/trustshell`](https://github.com/DealAppSeo/trustshell)**, and [How the pieces fit](BUILDERS.md#how-the-pieces-fit) for where it sits. @@ -180,7 +231,7 @@ The separate npm package `@hyperdag/trustshell-mcp` is older (1.0.0, 2026-07-08) | If you're… | Install | What you get | |---|---|---| -| A developer building an agent/app **in code** | `npm install @hyperdag/trustshell` | The SDK — HAL verification + ERC-8004 RepID + x402 payments, in your TypeScript/JS | +| A developer building an agent/app **in code** | `npm install @hyperdag/trustshell` | The SDK — Inspect, HAL verification, ERC-8004 RepID reads and the x402 spend guard, in your TypeScript/JS | | Using an **AI tool** (Claude Desktop, Cursor, Claude Code), **no code** | `npm i -g @hyperdag/trustshell`, then the `trustshell-mcp` bin (above) | The checks as AI-callable tools | | Only verifying **ZK proofs** client-side | `npm install @hyperdag/proof-verifier` | Standalone Plonky3 proof checking (usually bundled with trustshell — rarely installed directly) | @@ -226,7 +277,7 @@ state, not a roadmap — the design is settled, the packaging is not. | Interface | Default | Wraps | Status | | :--- | :--- | :--- | :--- | | `IIdentity` | `@hyperdag/identity-erc8004` | ERC-8004 IdentityRegistry | contracts live on Base Sepolia; package unpublished | -| `IReputation` | `@hyperdag/reputation-zkp` | On-chain RepID via ERC-8004 ReputationRegistry; ZKP for private-ownership / range proofs (Plonky3 range-check today — V2 binds to the RepID transcript) | contracts + proofs live; package unpublished | +| `IReputation` | `@hyperdag/reputation-zkp` | On-chain RepID via ERC-8004 ReputationRegistry; Plonky3 range proofs (the score is public; V2 binds the proof to the RepID transcript) | contracts + proofs live; package unpublished | | `IValidation` | `@hyperdag/validation-trinity` | BFT validators (with HITL graduation) | running in the engine; package unpublished | | `IPayment` | `@hyperdag/payment-x402` | x402 | settlements live on Base Sepolia; package unpublished | | `ILinkage` | `@hyperdag/linkage-registry` | HDP Linkage Registry (inverse-stake curve) | design only | @@ -247,7 +298,7 @@ graph TD Node1((Agent action)) --> Node2{Checked and scored
by the engine} Node2 -->|ERC-8004 write| Chain[(Base Sepolia
ReputationRegistry)] - subgraph "Privacy Layer (V1: range-check today; V2: bound to RepID transcript)" + subgraph "Proof layer (V1: range check, score public; V2: bound to RepID transcript)" ZKP[Plonky3 STARK range check
RepID above a threshold] --> Creds[Proof anyone can check
with @hyperdag/proof-verifier] end @@ -257,11 +308,10 @@ graph TD *(This diagram used to send a Merkle hash into a "HyperDAG Ledger". There is no such ledger, and no Merkle hash goes into the write: reputation is written to the ERC-8004 ReputationRegistry on Base Sepolia, and the proof is made by the prover from the engine's score, not read from a chain. The map of which service does what is in [`BUILDERS.md#how-the-pieces-fit`](BUILDERS.md#how-the-pieces-fit).)* ### Core building blocks -- **Merkle DAG** — content-addressed, append-only verifiable state. -- **ZKP for private ownership** — Plonky3 STARK (BabyBear field, Keccak FRI) range-check today; roadmap-V2 circuit binds the proof to the agent decision + HAL signals + RepID-delta derivation. -- **[ERC-8004](https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098)** — standards-based identity + reputation for autonomous agents. -- **[x402](https://github.com/x402-rs/x402-rs)** — agent-to-agent micropayments. -- **[Plonky3](https://github.com/Plonky3/Plonky3)** — STARK proving, no trusted setup, fast browser verification. +- **Range proofs** — Plonky3 STARK (BabyBear field, Keccak FRI) range-check today; roadmap-V2 circuit binds the proof to the agent decision + HAL signals + RepID-delta derivation. +- **[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)** by the ERC-8004 team — standards-based identity + reputation for autonomous agents. +- **[x402](https://github.com/coinbase/x402)** by Coinbase — agent-to-agent micropayments. +- **[Plonky3](https://github.com/Plonky3/Plonky3)** by Polygon Labs — STARK proving, no trusted setup, fast browser verification. --- @@ -270,8 +320,8 @@ graph TD | Phase | Target | Highlights | |---|---|---| | **V1 — Live today (Base Sepolia)** | shipping now | IdentityRegistry + ReputationRegistry live on Base Sepolia (all 12 core agents minted; reputation writes counted live by the engine, see Receipts) · HAL pipeline + cross-LLM agreement · x402 settlements · all reachable today through **[`@hyperdag/trustshell`](https://www.npmjs.com/package/@hyperdag/trustshell)**, which is published. The six-interface kernel is **designed and branch-only**; `@hyperdag/protocol` is **not on npm** (this row previously claimed `@hyperdag/protocol@0.1.0-alpha` was published). | -| **V1.5 — User-managed permission guardrails** | 1–2 weeks | Telegram (and later email/discord/webhook) alerts when an agent attempts an action outside its lane. Five RepID-derived permission tiers (PROBATIONARY → VETERAN) map score to capability. Substrate is live; client SDK lands at install. | -| **V2 — Mainnet** | not scheduled (the Q2 2026 target passed) | Canonical registries on Base mainnet · TEE-backed ValidationRegistry path · **ZKP RepID circuit bound to agent decision + HAL signals + RepID-delta transcript (extension of today's Plonky3 range-check)** · ZKP-federated learning (bilateral benefit) · expanded validator-set diversity. | +| **V1.5 — User-managed permission guardrails** | in progress, not dated | Guard in `@hyperdag/trustshell`: rules you set that refuse a command before it runs (merged, not released; guardrails for cooperative agents, not a security boundary). The engine's policy kernel enforces owner-signed spend limits and one-use permissions (built, not armed). Mapping the five RepID tiers (PROBATIONARY → VETERAN) to capability is design. | +| **V2 — Mainnet** | not scheduled (the Q2 2026 target passed) | Move HyperDAG's agents and reputation writes to the ERC-8004 team's registries on Base mainnet (already deployed by the team; addresses in [`packages/contracts/README.md`](packages/contracts/README.md)) · TEE-backed ValidationRegistry path · **ZKP RepID circuit bound to agent decision + HAL signals + RepID-delta transcript (extension of today's Plonky3 range-check)** · ZKP-federated learning (bilateral benefit) · expanded validator-set diversity. | See [GOVERNANCE_ROADMAP.md](GOVERNANCE_ROADMAP.md) for the bootstrap-to-community handover timeline. @@ -286,11 +336,11 @@ in that one map instead of being repeated here. --- -## Contributors +## Credits -Maintained by **Sean Goodwin**. The full contributor list — including everyone whose commits appear in this repository's history — is authoritatively the [GitHub contributors page](https://github.com/DealAppSeo/hyperdag-protocol/graphs/contributors), not this README. We do not list individuals here to avoid implying endorsement. +Maintained by **Sean Goodwin**. -This implementation builds on the **ERC-8004 standard** (Trustless Agents). The standard's authors are public on the EIP and its reference repos; we cite them factually in [METHODOLOGY.md](METHODOLOGY.md), not as contributors to this fork. +HyperDAG is built on **ERC-8004: Trustless Agents**, by Marco De Rossi (MetaMask) and Davide Crapis (Ethereum Foundation), with Jordan Ellis (Google) and Erik Reppel (Coinbase), and the ERC-8004 core team, Leonard Tan, Vitto Rivabella and Isha Sangani. The registry contracts, spec and ABIs in `packages/contracts` are their work, carried here with their commit history, which is why they appear in this repository's [contributor graph](https://github.com/DealAppSeo/hyperdag-protocol/graphs/contributors). That is credit for their work, not a claim that they endorse HyperDAG. Thank you. The full list of what we build on, and the licences, is in [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). For governance, see [GOVERNANCE_ROADMAP.md](GOVERNANCE_ROADMAP.md). @@ -298,7 +348,7 @@ PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURIT ## License -Apache 2.0 — see [LICENSE](LICENSE). Patent rights, if any, are granted under the Apache 2.0 patent grant clause. +Apache 2.0 — see [LICENSE](LICENSE). Patent rights, if any, are granted under the Apache 2.0 patent grant clause. The ERC-8004 files in `packages/contracts` keep the licences their authors gave them (MIT, CC0-1.0, ISC): see [`packages/contracts/NOTICE`](packages/contracts/NOTICE). --- diff --git a/docs/WHY.md b/docs/WHY.md new file mode 100644 index 00000000..72144aa3 --- /dev/null +++ b/docs/WHY.md @@ -0,0 +1,129 @@ +# Why we build this + +We want AI that is safe, honest and shared by everyone, and if general intelligence arrives, we want it benevolent and answerable to the people it serves. We don't think a smarter model alone gets there. We think four habits do: + +1. **Agents earn trust through a record anyone can check**, instead of being handed it. +2. **What an agent says it did is checked against evidence**, not believed. +3. **Your rules, memory and evidence belong to you and move with you**, and outside input is quarantined before it can steer your agent. +4. **How reputation is weighed is decided in the open**, one voice per person, by the people it affects. + +Today the second habit is a free tool anyone can run. Parts of the others run on a test network, and some are only designs. This page says which. For each habit it also gives the research we lean on, and the research that cuts against us. The second kind is the part we most want you to read. + +Status words used below: **released** (published, anyone can run it), **merged** (in the code, not in a release), **shadow** (built, switched off), **testnet** (running on Base Sepolia), **design** (written down, not built), **vision** (what we are aiming at). + +--- + +## 1. Claims are checked, not believed + +**Where we are.** *Released.* `trustshell check --claims-file ` ([TrustShell 1.8.0](https://www.npmjs.com/package/@hyperdag/trustshell)) reads GitHub's own record of a CI run and marks each sentence an agent wrote about it **supported**, **contradicted** or **not checked**. It names the field that decided each one, and lists what it does not prove. "Not checked" never counts as a pass. The record it writes is canonical JSON (RFC 8785) with a SHA-256 digest: it shows tampering, not authorship, because it is not signed yet. + +**Why.** +- Frontier models game their tasks. METR found o3 reward-hacked in 30.4% of RE-Bench runs; in one, it cached an answer so a script merely *looked* fast ([METR, 2025](https://metr.org/blog/2025-06-05-recent-reward-hacking/)). +- Reasoning models often don't say what drove their answer: they disclosed a hint they had used under 20% of the time ([Chen et al., 2025](https://arxiv.org/abs/2505.05410); see also [Turpin et al., 2023](https://arxiv.org/abs/2305.04388)). +- Trusted checks raise safety even against a model that is trying to subvert them ([Greenblatt et al., AI Control](https://arxiv.org/abs/2312.06942)). + +**What cuts against us.** +- Training a model against its own checker teaches it to hide intent ([Baker et al., 2025](https://arxiv.org/abs/2503.11926)). So our checker stays outside any training loop. +- Weak judges are not uniformly reliable ([Kenton et al., 2024](https://arxiv.org/abs/2407.04622)). +- Our hosted sentence check uses two checkers from **different model families**, but different is not independent. Across 350+ models, models agreed about 60% of the time when both were wrong ([Kim et al., ICML 2025](https://arxiv.org/abs/2506.07962)), and errors are growing more alike as models improve ([Goel et al., 2025](https://arxiv.org/abs/2502.04313)). We never call two agreeing checkers "independent verification". + +## 2. Trust and autonomy are earned through a record + +**Where we are.** +- *Testnet:* RepID, a reputation score per agent, written as ERC-8004 feedback on Base Sepolia. For paid work, the write is queued only when the delivered work passes its check. +- *Shadow:* an eligibility record that counts only checked outcomes between different owners. +- *Built, not armed:* the policy kernel that enforces an agent's limits (owner-signed spend caps, one-use permissions). +- *Design:* tying those limits to RepID. +- *Vision:* weights set by the community. + +```mermaid +flowchart LR + A["Agent works
and says what it did"] --> C["Checked against evidence
supported, contradicted, not checked
released"] + C --> R["Outcome recorded
hashed record
released, unsigned"] + R --> S["RepID updated
from checked paid work: testnet
checked, owner-distinct only: shadow"] + W["Weights
set by us today
set in the open: vision"] --> S + S --> L["Autonomy limits
spend caps, one-use permissions
kernel built, not armed
tied to RepID: design"] + L --> G["Owner's guardrails
still apply
merged"] + G --> A +``` + +**Why.** +- Governing agentic AI means asking how much to approve by hand, and that should depend on measured reliability ([Shavit et al., OpenAI, 2023](https://cdn.openai.com/papers/practices-for-governing-agentic-ai-systems.pdf)). +- The EU AI Act ([Art. 14](https://artificialintelligenceact.eu/article/14/)) and the [NIST AI RMF](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.100-1.pdf) ask for oversight in proportion to risk and autonomy, and frameworks for levels of agent autonomy now exist ([Feng et al., 2025](https://arxiv.org/abs/2506.12469)). +- A reputation needs long-lived identities, captured feedback, and feedback that guides decisions ([Resnick et al., 2000](https://presnick.people.si.umich.edu/papers/cacm00/reputations.pdf)). + +**The evidence that shaped our design.** The first empirical study of live ERC-8004 deployments found: +- only 3–15% of registrations expose a live service; +- 59–91% of reviewers show coordinated Sybil behaviour; +- feedback is rarely grounded in verifiable interactions. + +The authors conclude that the Reputation Registry, as deployed today, cannot yet work as a trust signal ([Xiong, Li, Wei, Wang, Knottenbelt and Wang, 2026](https://arxiv.org/abs/2606.26028)). The standard expects this: it says Sybil attacks are possible and leaves reviewer weighting to the layers built on it ([EIP-8004](https://eips.ethereum.org/EIPS/eip-8004)). That is our layer's job. So: +- feedback should be **bound to checked evidence** of delivered work, not to a rating anyone can post; +- the parties to a trade should be **provably different owners**. Sybil resistance needs an identity anchor or a cost ([Douceur, 2002](https://www.microsoft.com/en-us/research/publication/the-sybil-attack/)), and trust anchors are what let EigenTrust hold up against large malicious collectives ([Kamvar et al., 2003](https://zoo.cs.yale.edu/classes/cs457/fall13/Eigentrust.pdf)). + +**What cuts against us.** +- **No published study shows that autonomy earned from a track record makes LLM agents safer.** We have not shown it either. That is the first thing we want to measure (below). +- A clean record is weak evidence against hidden, trigger-conditioned behaviour ([Hubinger et al., Sleeper Agents, 2024](https://arxiv.org/abs/2401.05566)). +- Human approval gates often fail in practice ([Green, 2022](https://arxiv.org/abs/2109.05067)). +- Absolute Sybil-proofness is out of reach without an anchor, and results depend on definitions ([Stannat et al., 2021](https://archive.illc.uva.nl/AAMAS-2021/pdfs/p1263.pdf)). + +So we say "costly to farm, under stated assumptions", and never "unfarmable" or "a high RepID means safe". + +## 3. Your harness is yours: guardrails, memory, quarantine, carry + +**Where we are.** +- *Released:* local memory your AI apps share on your machine; a quarantine for notes written by agents; screening on every tool that reads the network (instruction-like text is withheld and listed). +- *Merged, not released:* Guard (rules you set, which refuse a command before it runs) and Carry (a signed bundle that takes your profile, rules and notes to another machine). + +Guard is a guardrail for agents that cooperate. It is **not a security boundary**: anything running as you can change its rules. + +```mermaid +flowchart LR + IN["Untrusted input
web page, tool output,
a note another agent wrote"] --> Q["Quarantine
held apart,
source recorded"] + Q --> SC["Screen
instruction-like text
withheld and listed"] + SC --> V{"Vouched for
by you?"} + V -->|yes| OK["Admitted as data,
never as instructions"] + V -->|no| HOLD["Stays quarantined"] + OK --> AG["Your agent"] +``` + +**Why.** +- The harness changes outcomes. The same model did much better with a purpose-built interface ([SWE-agent, 2024](https://arxiv.org/abs/2405.15793)), and a task-specific scaffold beat a general one in 11 of 12 runs with the model held fixed ([Holistic Agent Leaderboard, 2025](https://arxiv.org/abs/2510.11977)). If the harness matters that much, you should own it. +- Ownership has standards to build on: identifiers you control ([W3C DIDs](https://www.w3.org/TR/did-core/)), signed claims that travel ([W3C Verifiable Credentials 2.0](https://www.w3.org/TR/vc-data-model-2.0/)), and a legal right to the data you provided ([GDPR Art. 20](https://gdpr-info.eu/art-20-gdpr/)). +- Rules kept outside the model work across providers ([NeMo Guardrails](https://arxiv.org/abs/2310.10501)), safety taxonomies can be customised ([Llama Guard](https://arxiv.org/abs/2312.06674)), and one value set should not have to fit everyone ([Sorensen et al., 2024](https://arxiv.org/abs/2402.05070)). +- Untrusted input steers agents. Instructions planted in retrieved data hijack LLM apps ([Greshake et al., 2023](https://arxiv.org/abs/2302.12173)), and poisoning under 0.1% of an agent's memory gave over 80% attack success ([AgentPoison, 2024](https://arxiv.org/abs/2407.12784)). The most credible defence keeps trusted control apart from untrusted data ([CaMeL, Google DeepMind, 2025](https://arxiv.org/abs/2503.18813); [OWASP LLM01](https://genai.owasp.org/llmrisk/llm01-prompt-injection/)). + +**What cuts against us.** +- Screening-style defences fail against adaptive attackers: 12 recent defences were broken, most with over 90% success ([Nasr, Carlini et al., 2025](https://arxiv.org/abs/2510.09023)). +- CaMeL's provable security cost utility: 77% of tasks against 84% undefended. +- User-level customisation can be an attack path: ten examples and under $0.20 of fine-tuning removed a model's safety behaviour ([Qi et al., 2023](https://arxiv.org/abs/2310.03693)), and commercial guardrail detectors were evaded, some 100% of the time ([Hackett et al., 2025](https://arxiv.org/abs/2504.11168)). +- Portability law stops at data you provided or that was observed about you. A derived score is outside it ([WP242](https://ec.europa.eu/newsroom/article29/redirection/document/45685)). +- A simple pipeline can beat an elaborate harness ([Agentless, 2024](https://arxiv.org/abs/2407.01489)). + +So we say "quarantine reduces the blast radius by design", never "injection-proof". And we say your reputation will be portable when it is bound to evidence you can carry, not that it is portable today. + +## 4. Weights are set in the open + +**Where we are.** *Vision.* Today we set RepID's weights ourselves, and they are written down in the engine's code. + +**Why.** A model trained on a constitution drafted from public input showed lower bias with similar helpfulness ([Collective Constitutional AI, FAccT 2024](https://arxiv.org/abs/2406.07814)). Public-input processes for AI have working precedents ([CIP Alignment Assemblies](https://www.cip.org/alignmentassemblies); OpenAI's Democratic Inputs grants, [summary](https://the-decoder.com/?p=11081)). + +**What cuts against us.** +- That study was small and preliminary, with a US-only sample ([Anthropic's write-up](https://www.anthropic.com/research/collective-constitutional-ai-aligning-a-language-model-with-public-input)). +- Token-weighted DAO voting concentrates power in a few hands ([Feichtinger et al., 2023](https://arxiv.org/abs/2302.12125)). +- Participation can be claimed without real power ([Sloane et al., 2020](https://arxiv.org/abs/2007.02423)). + +So the design is **one voice per verified person, not per token**: one identity per human, with a scoped nullifier per vote, in an open and recorded process. We will not say "the community controls RepID" until it does. + +--- + +## What we want to measure, and would welcome help with + +1. **Does autonomy earned from a checked record reduce harmful actions** compared with fixed autonomy, on the same tasks and models? No one has published this. +2. **How correlated are our two checkers' errors** on our own corpus? We will publish the number next to every accuracy figure. +3. **Does feedback bound to checked evidence resist the Sybil patterns** that Xiong et al. found on live ERC-8004 deployments? +4. **Does switching model family move outcomes less than changing the harness?** If yes, the harness is where your control belongs. + +If you want to work on any of these, start with [`BUILDERS.md`](../BUILDERS.md) and open an issue. The fastest way to help today is to try TrustShell's [five-minute challenge](https://trustshell.dev/inspect) and find a claim it wrongly marks **supported**. + +*Sources were opened and checked on 2026-10-23. Credit for the code we build on is in [ACKNOWLEDGEMENTS.md](../ACKNOWLEDGEMENTS.md).* diff --git a/packages/contracts/NOTICE b/packages/contracts/NOTICE new file mode 100644 index 00000000..eadac28c --- /dev/null +++ b/packages/contracts/NOTICE @@ -0,0 +1,58 @@ +ERC-8004: Trustless Agents — registry contracts, specification and ABIs + +This directory contains the work of the ERC-8004 team, taken from +https://github.com/erc-8004/erc-8004-contracts with its commit history. + +ERC-8004 is a community effort coordinated by Marco De Rossi (MetaMask) and +Davide Crapis (Ethereum Foundation), with the co-authorship of Jordan Ellis +(Google) and Erik Reppel (Coinbase). The core team is joined by Leonard Tan +(MetaMask), Vitto Rivabella (Ethereum Foundation) and Isha Sangani +(Ethereum Foundation). Specification: https://eips.ethereum.org/EIPS/eip-8004 + +Byte-identical to erc-8004/erc-8004-contracts at commit b9e466c +(checked 2026-10-23 with git hash-object against the upstream blobs): + + contracts/ERC1967Proxy.sol + contracts/HardhatMinimalUUPS.sol + contracts/IdentityRegistryUpgradeable.sol + contracts/MinimalUUPS.sol + contracts/MinimalUUPSMainnet.sol + contracts/ReputationRegistryUpgradeable.sol + contracts/SingletonFactory.sol + contracts/ValidationRegistryUpgradeable.sol + test/core.ts + test/upgradeable.ts + ERC8004SPEC.md + UPGRADEABLE_IMPLEMENTATION.md + VANITY_DEPLOYMENT_GUIDE.md + abis/IdentityRegistry.json + abis/ReputationRegistry.json + abis/ValidationRegistry.json + ignition/modules/ERC8004.ts + scripts/deploy-create2-factory.ts + scripts/fund-local-owner.ts + triple-presigned-upgrade-chain-31337.json + +From the same upstream repository, but not identical to b9e466c (a different +upstream version, local edits, or both): + + README.md, hardhat.config.ts, package.json, tsconfig.json, test/local.ts, + scripts/deploy-vanity.ts, scripts/find-vanity-salts-parallel.ts, + scripts/generate-triple-presigned-upgrade.ts, + scripts/upgrade-vanity-presigned.ts, scripts/upgrade-vanity.ts, + scripts/verify-vanity.ts + +Licences, as the upstream files declare them: + - Solidity sources: MIT (SPDX headers), except contracts/SingletonFactory.sol, + which is CC0-1.0. + - The upstream package: ISC (package.json). The upstream repository has no + LICENSE file of its own. + +HyperDAG's own work in this directory, not from upstream: everything under +src/ (governance, identity, legacy, reputation). Those files are Apache-2.0 +with the rest of this repository. + +The registries these contracts describe are deployed and operated by the +ERC-8004 team. HyperDAG uses them; it does not operate them. + +Thank you to everyone above.