diff --git a/BUILDERS.md b/BUILDERS.md new file mode 100644 index 0000000..42af6b9 --- /dev/null +++ b/BUILDERS.md @@ -0,0 +1,151 @@ +# Building on the Trust\* ecosystem + +**This is the public contract for developers outside the core team.** It is +deliberately separate from the internal operating manual our own agents read +(`CLAUDE.md` here, `repid-engine/LESSONS.md` upstream). That file is a working +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. + +--- + +## 1. What is actually usable today + +Everything in this section was measured on **2026-09-08**, not read off a badge. +Re-run the commands before relying on any of it; a dated fact decays, and a +*negative* fact ("X is not published") decays fastest of all, because anyone can +publish X without touching this file. + +| Thing | State | How to check | +|---|---|---| +| **`@hyperdag/trustshell`** | **PUBLISHED — `1.3.0`.** 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 | +| `ReputationRegistry` on Base Sepolia (84532) | **LIVE** — `0x8004B663056A597Dffe9eCcC1965A193B7388713` | same | +| The six-interface kernel (`IIdentity`, `IReputation`, `IValidation`, `IPayment`, `ILinkage`, `IHallucination`) | source is on a feature branch, **not on `main`** | `git log origin/main -- packages/interfaces` | + +**So: `npm i @hyperdag/trustshell`. Not `@hyperdag/protocol`.** The badge at the +top of this repo's README links a package that does not exist yet. That badge +misled one of our own agents on 2026-09-08; it can mislead you the same way. + +**Read `README.md`'s "Known broken / not live" table before you design against +anything here.** It is unusually honest — it names a live event-signature defect +in `ReputationRegistry` that makes a spec-compliant indexer see zero feedback +events. That is the kind of thing most projects omit. We publish it because a +builder who discovers it in production has been failed by us. + +--- + +## 2. The one rule that is not optional + +The ecosystem's entire product is **trust as verifiable evidence rather than +claim**. RepID scores derive from verdicts, and those scores are written to a +public chain. So a verdict you report is not a log line — it is an input to +somebody else's trust decision, permanently. + +**Report three outcomes, never two: VERIFIED / NOT CHECKED / FAILED.** + +Two outcomes collapse *"we did not look"* into *"it passed"*. That is not a +style preference here; it is the failure mode that has cost this system the most: + +- A validator whose model call errored returned a score of **zero**, and zero + entered the aggregate as a real verdict. Three silent validators summed to a + confident **FAIL**, which disputed **twelve consecutive runs** and moved real + testnet money against a provider whose work nobody had assessed. NOT CHECKED + scored as FAILED. +- A mailbox reader whose query could no longer match any row printed + `VERIFIED. Inbox has no unread messages` for months. +- A credential check reported green with no credential present. + +If you integrate and emit a pass you did not observe, you are not just wrong +locally — you are writing that fiction into a reputation layer other people +price decisions on. **A component that cannot report NOT CHECKED cannot be +trusted to report VERIFIED.** + +Corollary, and it is cheap: **a guard that has never been seen to fail is a +comment.** Break the property deliberately, watch your check go red, revert. +Until you have done that you do not know it is wired. + +--- + +## 3. What is stable, and what will move + +| Surface | Stability | +|---|---| +| The two registry addresses above, on Base Sepolia | stable — they are the canonical deployment | +| ERC-8004 identity + reputation read paths (`getRepID`, `getReputationHistory`, `getAttestation`) | stable — standard-defined, not ours to change | +| RepID **range** (10 floor, 10,000 cap) and the five tier names | stable | +| RepID **tier thresholds** and the scoring weights behind them | **will move.** Tuning is deliberate and not published. Do not hardcode a threshold; read the tier. | +| The six-interface kernel | pre-release, on a branch. Design against `@hyperdag/trustshell` instead. | +| ZK proof shape | the live proof is a narrow range check (`repid > threshold`). Binding a proof to the full RepID derivation is roadmap, not shipped. Do not describe it as shipped. | + +**Two things you will not find here, deliberately:** the RepID scoring formula +and the ANFIS parameters. They are not published, and a contribution that +infers and hardcodes them will be rejected — not to be secretive, but because +anything hardcoded against them breaks silently the moment they are retuned. +Read the tier, not the arithmetic. + +--- + +## 4. Anti-Sybil: why a high score may not get the tier you expect + +The tier a score maps to is **demoted on unique-counterparty count**. An agent +that farms a high score with no real counterparties does not buy a top tier. + +If you see a high-scoring agent sitting in a middle tier, that is the gate +working as designed. Do not file it as a bug, and do not build a workaround. + +--- + +## 5. What your agent is allowed to do, and what decides it + +**Capability is a property of your agent, not of the door it came in through.** +An agent reaching the ecosystem via TrustMarket, via TrustShell, or via a direct +integration is subject to the same evaluation. There is no permissive entry +point to shop for, and we will not add one: if capability varied by surface, the +surface would become the attack surface, and the most open door — which is +exactly the one we want outside builders to use — would be the one everyone +picked. + +**The ladder is earned RepID tier**, not a plan you are on. That is deliberate: +RepID is anchored on ERC-8004, so it is portable between platforms, and the tier +it maps to is demoted on unique-counterparty count (§4), so it cannot be farmed. +A second, private trust ladder would be neither portable nor auditable, which +would defeat the point of anchoring the first one on-chain. + +Two honest caveats, because you should design against what is true today: + +- **Rate limits are a separate axis from capability.** Throughput is governed by + a commercial API-key tier. Do not read a higher rate limit as broader + permission — they are different things and are meant to stay different. +- **Tier-gated capability is, as of 2026-09-08, largely NOT ENFORCED IN CODE.** + The schema carries a minimum-tier field on permissioned resources and nothing + in the engine currently reads it. We are telling you this rather than letting + you infer a guarantee from a column name: **do not build a security control + that assumes the platform is gating on tier for you.** Enforce your own + boundaries, and treat tier as a signal you read, not a gate someone else is + holding. When enforcement lands it will be announced here, because switching + it on changes who can reach what. + +That second bullet is the same discipline as §2 pointed at ourselves: a field +recorded as though it were enforced, while enforcing nothing, is the +documentation equivalent of NOT CHECKED reported as VERIFIED. + +--- + +## 6. Where to go, and what NOT to read + +- **Start here**, then `README.md` in this repo — especially its "Known broken / + not live" table. +- **Install** `@hyperdag/trustshell` and read its own docs. +- **Contributing**: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`. +- **Do not** design against `CLAUDE.md` (this repo) or `repid-engine/LESSONS.md`. + Those are the internal tier: an operating log for agents already inside the + system, written in dated measurements and corrections. They are readable — + the repos are public — but they are **not a contract**, they change without + notice, and several entries exist purely to stop a specific past mistake + recurring. Reading them as an API guarantee will mislead you. + +**Contracts are on a testnet.** Base Sepolia is not mainnet. Nothing here is a +guarantee of mainnet behaviour, an audit, or financial advice. diff --git a/CLAUDE.md b/CLAUDE.md index ce3902a..4a886f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,20 +19,50 @@ confidently with less context than it thinks it has. operating rules every agent works under and is the one file injected verbatim into every XC/GA dispatch. Read it before you plan anything here. -Per surface, read yours first: - -| surface | read first | -|---|---| -| `repid-engine` | `LESSONS.md`, then `CLAUDE.md` | -| `trinity-ecosystem` | `CLAUDE.md`, then `docs/PRIOR-WORK-INDEX.md` | -| `trustshell` | `AGENTS.md` (`CLAUDE.md` is a one-line `@AGENTS.md` include) | -| `trinity-symphony-shared` | `CLAUDE.md` — lane rules; take a lane before touching a repo | -| **`hyperdag-protocol`** | **this file** | +**That is the whole pointer. This file deliberately does NOT list the other repos.** + +It used to. A five-row table of sibling entry points shipped here on 2026-09-08 and was +already wrong when it merged — `DealAppSeo/trustrails-dev` is live and was not in it. The +shape was the defect, not the missing row: the Trust\* ecosystem is TrustShell, TrustMarket, +TrustRepID, TrustRails, TrustTrader, TrustCRE, TrustEscrow and TrustMedical on this same +HAL / RepID / ERC-8004 / x402 harness, plus whatever third parties build via TrustMarket. +A per-repo list of all siblings is N tables of N rows — adding a surface means editing every +other repo, and forgetting fails **silently**: the new surface simply is not listed, nothing +breaks, and an agent landing there sees no pointer. That is the exact defect the table was +added to fix, one level up. Same lesson as the hand-maintained jest `roots` list in +`repid-engine`: *prefer a discovery rule to a list.* + +**So: a star, not a mesh.** Every repo names true north and nothing else. One line per repo, +a new surface touches only itself, and no table exists to go stale. If you need to know which +repos exist, ask the person who gave you the assignment or read the session's own source +list — do not trust a checked-in inventory. + +## Two tiers, and you are reading the internal one + +| tier | who | where | +|---|---|---| +| **Internal** — operating log, dated, changes without notice | our agents (CC, XC, GA, the swarm) | `repid-engine/LESSONS.md`, then this file | +| **Published** — the contract we keep | outside developers building on the ecosystem | **[`BUILDERS.md`](BUILDERS.md)** | + +The two are not interchangeable. The internal tier is capped at 6000 characters because it is +a dispatch payload, and much of it is corrections that exist to stop one specific past mistake +recurring. **It is readable — these repos are public — but it is not a promise.** If you are +answering an outside builder, answer from `BUILDERS.md`; if it does not cover their question, +that is a gap in `BUILDERS.md` to fix, not a licence to quote the internal file at them. ## ⚠ THIS REPOSITORY IS PUBLIC -Apache 2.0, published as `@hyperdag/protocol` on npm. Every commit message, PR title, -PR body and comment is world-readable and permanent. +Apache 2.0. Every commit message, PR title, PR body and comment is world-readable and +permanent. + +**Correction, MEASURED 2026-09-08.** This line first said *"published as `@hyperdag/protocol` +on npm"*. It is **not published** — `npm view @hyperdag/protocol` returns 404, as do +`@hyperdag/identity-erc8004` and `@hyperdag/reputation-zkp`. I read that off the npm badge at +the top of `README.md` without running the query, while the README's own *"Known broken / not +live"* table three screens below said plainly that it 404s. **A badge is a link, not a +measurement** — same class as reading `-stub` in a filename as evidence about production. +The one package that IS published is **`@hyperdag/trustshell@1.3.0`**, and it is what an +outside builder should install. See `BUILDERS.md`. State FINDINGS, not inventories. *"A production key was committed and must be rotated"* is actionable; the key, the project id, the row counts and the service names diff --git a/README.md b/README.md index dad7c7c..2e2e142 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,8 @@ columns are current as of **2026-08-06** and every row is checkable locally. | Six-interface kernel source | on `feat/modular-kernel-interfaces-2026-05-04`, **not on `main`** | | `packages/protocol`, `packages/interfaces` | untracked `dist` output only; no rebuildable source | +**Building on this? Start with [`BUILDERS.md`](BUILDERS.md)** — what is actually published today, what is stable versus what will move, and the reporting rule the reputation layer depends on. + **To use the trust layer today, install [`@hyperdag/trustshell`](https://www.npmjs.com/package/@hyperdag/trustshell)** — it is published, keyless for HAL scoring, RepID reads and ZK proofs, and it reaches the same contracts listed above. > `hallucination-hal-local` and `identity-erc8004-viem` are the two packages that