From 959cde2193de224125264f8edbd5aee749f62910 Mon Sep 17 00:00:00 2001 From: "Claude Opus 4.8" Date: Thu, 23 Jul 2026 23:02:08 -0500 Subject: [PATCH] docs: retire stale v1 launch guidance Mark the contracts repository as the deployed v1/Sepolia reference while EFS is redesigned from scratch as v2. Retire the April launch checklist and close the two repo-local questions already settled by the Sepolia deployment and ADR-0031. Permanence-tier: Ephemeral Co-authored-by: GPT-5 --- AGENTS.md | 40 ++++++++-- docs/LAUNCH_CHECKLIST.md | 155 ++++++++++----------------------------- docs/QUESTIONS.md | 76 +++++++------------ 3 files changed, 96 insertions(+), 175 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e0c13e2..815ae806 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,18 @@ # AGENTS.md -EFS — Ethereum File System. On-chain file system built on EAS attestations. Pre-launch, devnet target April 19, 2026. Breaking changes are acceptable for now as there's no real data created yet. Good design and future proofing is key. +EFS — Ethereum File System. -**Production web client** (Vite/Lit, separate repo): https://github.com/efs-project/client. The internal UI at `packages/nextjs/` in this repo is a Scaffold-ETH-based devtools/debug interface — not the production client. Don't apply Scaffold-ETH patterns (`useScaffoldReadContract` etc.) to the production client. +> **Repository status (2026-07-23): deployed v1 reference implementation.** +> The EAS-based v1 system is live on Sepolia with registered schemas and real +> test data. It is not deployed to mainnet. EFS is now being redesigned from +> scratch as v2, so this repository remains authoritative for **v1 behavior** +> only. Do not extend a v1 mechanism or present it as the v2 baseline without a +> current planning-vault decision that explicitly carries it forward. + +**Legacy Vite/Lit client** (separate repo): +https://github.com/efs-project/client. The internal UI at `packages/nextjs/` +is the newer v1 explorer/debug interface. Neither is the Client v2 +implementation target unless the current design process explicitly chooses it. ## Read on init @@ -19,23 +29,36 @@ EFS — Ethereum File System. On-chain file system built on EAS attestations. Pr - **[specs/README.md](./specs/README.md)** — index of detailed specs (authoritative current behavior) - **[docs/adr/](./docs/adr/)** — past decisions and reasoning - **[docs/FUTURE_WORK.md](./docs/FUTURE_WORK.md)** — backlog -- **[docs/LAUNCH_CHECKLIST.md](./docs/LAUNCH_CHECKLIST.md)** — pre-launch blockers +- **[docs/LAUNCH_CHECKLIST.md](./docs/LAUNCH_CHECKLIST.md)** — retired v1 launch posture and the gate for creating a future checklist - **[reference/README.md](./reference/README.md)** — EAS, EIP, Scaffold-ETH docs (indexed by task) ## Cross-repo coordination — the planning vault -EFS uses a separate **planning vault** as the cross-repo coordination point across this repo, the production client (`efs-project/client`), and the future SDK. Repo: [efs-project/planning](https://github.com/efs-project/planning); typically cloned alongside this one (target layout: `/efs/{contracts,client,sdk,planning}/`). +EFS uses a separate **planning vault** as the cross-repo coordination point +across this repo, the legacy client (`efs-project/client`), the pre-v2 SDK +(`efs-project/sdk`), and the v2 redesign. Repo: +[efs-project/planning](https://github.com/efs-project/planning). The vault holds: - **Cross-repo designs** with a name-first → numbered-at-promotion lifecycle. Designs that span multiple repos are tracked there; per-repo decisions stay here as ADRs. -- **Cross-repo Kanban board**, milestones (e.g., OnionDAO hackathon 2026-06-01), and an append-only decisions log. +- **Cross-repo Kanban board**, live milestones, and an append-only decisions log. - **Glossary** of cross-cutting EFS terms. - **Onboarding** for AI agents (start-here, conventions, escalation, write-a-design walkthrough). -Read the vault's [`AGENTS.md`](https://github.com/efs-project/planning/blob/main/AGENTS.md) on init when your task is cross-repo. **A landed cross-repo design typically produces one or more ADRs here** — the planning design is the cross-cutting proposal; the resulting ADR(s) in this repo's `docs/adr/` are the per-repo decision artifacts. Don't duplicate substantive content; the design tombstones to point at the per-repo ADRs once implementation lands. +Read the vault's +[`AGENTS.md`](https://github.com/efs-project/planning/blob/main/AGENTS.md) on +init when your task is cross-repo. During the v2 redesign, start with the +[`efsv2` current spine](https://github.com/efs-project/planning/blob/main/Designs/efsv2/README.md) +before proposing architectural work here. **A landed cross-repo design +typically produces one or more ADRs here** — the planning design is the +cross-cutting proposal; the resulting ADR(s) in this repo's `docs/adr/` are the +per-repo decision artifacts. Don't duplicate substantive content; the design +tombstones to point at the per-repo ADRs once implementation lands. -For tasks fully scoped to this repo, the planning vault is optional context. For tasks spanning repos or unblocking a milestone, it's required reading. +For maintenance of the deployed v1 implementation, repo-local specs and ADRs +remain authoritative. For architecture, v2 work, cross-repo work, or milestone +work, the planning vault is required reading. ## PR review quick start @@ -259,7 +282,8 @@ cd packages/hardhat && npx hardhat test test/EFSIndexer.test.ts --network hardha ## Invariants -**Hardened (load-bearing — don't violate without writing a superseding ADR):** +**Hardened v1 invariants (load-bearing for the deployed Sepolia system — don't +violate without writing a superseding ADR):** - **Cardinality is declared at the schema level (PIN vs TAG), not per-attestation.** The schema UID is the only permanent, globally-coordinated, machine-readable slot in EFS. PIN = cardinality 1 (file placement, PROPERTY value binding); TAG = cardinality N with an `int256 weight` (folder visibility, descriptive labels, schema-alias discovery). See ADR-0041. - **Active TAG** (kernel) = unrevoked edge exists. Weight does not affect kernel activity. Use this definition in contracts, resolver helpers, and any non-filter code path. diff --git a/docs/LAUNCH_CHECKLIST.md b/docs/LAUNCH_CHECKLIST.md index f7113b50..881c51ed 100644 --- a/docs/LAUNCH_CHECKLIST.md +++ b/docs/LAUNCH_CHECKLIST.md @@ -1,130 +1,53 @@ # Launch Checklist -Two distinct launches: -- **Devnet (April 19, 2026)** — bicycle day. Forked Sepolia on a VPS, weekly reset, upgradeable contracts allowed for iteration. -- **Mainnet (target ~April 22, 2026 → likely later)** — permanent contracts (ADR-0030), no second chances. +> **Status: retired v1 checklist.** The April 2026 devnet/mainnet schedule was +> not the plan EFS ultimately followed. Do not use its dates, unchecked items, +> or architecture assumptions to plan current work. -Update statuses with `[x]` as items land. Add notes inline if blocked. +## Current launch posture ---- +- The EAS-based v1 system is deployed to Sepolia. Nine schemas were registered + and the initial scaffolding was sealed on 2026-06-19; current addresses and + authority state live in `docs/CHAINS.md`. +- Mainnet has not been deployed and has no active launch date. +- The project is redesigning EFS from scratch as v2. The carrier, identity, + authority, record, lens, query, privacy, filesystem, SDK, and client + boundaries are being reconsidered together. +- Existing v1 contracts, deployment tooling, explorer, SDK branch, and client + are evidence and reference implementations. They are not a mainnet release + candidate by default. -## Devnet (April 19, 2026) +The active project milestone surface is the planning vault's `Milestones.md`. +The current v2 architecture and sequencing live under +`planning/Designs/efsv2/`. -### Infrastructure +## Historical v1 outcome -- [ ] VPS provisioned with forked Sepolia (anvil/hardhat fork) -- [ ] IPFS node running (kubo or similar) for devnet file hosting -- [ ] Arweave gateway/uploader available (testnet or hosted) -- [ ] Magnet/torrent seed infrastructure (webtorrent tracker?) -- [ ] HTTPS test endpoint(s) for HTTP transport testing -- [ ] Weekly reset cron job (Sunday 00:00 UTC?) -- [ ] DNS / public URL for the devnet +The old checklist mixed three different efforts: -### Contracts +1. an April forked devnet; +2. the later Sepolia deployment and buildathon; +3. a proposed immutable v1 mainnet launch. -- [ ] Devnet contracts deployed behind upgradeable proxy (resolved in `docs/QUESTIONS.md`: which proxy pattern) -- [ ] Upgrade procedure documented (storage layout enforcement via OpenZeppelin's `hardhat-upgrades`) -- [ ] Reset procedure includes redeploying all contracts and clearing all on-chain state -- [ ] EFSIndexer wired to EdgeResolver, MirrorResolver, EFSSortOverlay -- [ ] System anchors created: root plus default `/transports/*` children (`onchain`, `data`, `ipfs`, `arweave`, `magnet`, `https`, `ftp`, `s3`, `gs`, `dat`, `rsync`, `bittorrent`) -- [ ] `setTransportsAnchor()` called on MirrorResolver +Sepolia shipped. The buildathon wound down with low participation. The v1 +mainnet launch did not happen, and the v2 redesign superseded the old delivery +plan before its unchecked items were reconciled. -### Frontend / Client +Git history preserves the detailed April checklist. It remains historical +evidence, not an active work queue. -- [ ] Production EFS Client (Vite/Lit, separate repo) reviewed for devnet readiness -- [ ] Internal devtools UI (`packages/nextjs/`) confirmed working against devnet -- [ ] Client knows how to construct `web3://` URLs pointing at the devnet router -- [ ] "DEVNET — RESETS WEEKLY" warning banner in client UI -- [ ] **Empty lens list = "show all data" (still filtered + paged).** Intended model: - a lens of `vitalik.eth` means "only vitalik's data", "me/my address" means "only - mine", and an EMPTY list means "all data from everyone" (the system/nsfw exclusion - and pagination still apply). Today an empty/absent lens chain shows nothing, and - `defaultLensesForContainer` backfills `systemLenses` so it's rarely empty. Needs: - **(a)** an ADR superseding the relevant ADR-0031/0039 viewer-sovereignty + - systemLenses-tail semantics; **(b)** a CONTRACT path for an unscoped-but-filtered - directory page — e.g. `EFSFileView.getDirectoryPageFiltered` treating an empty - `attesters[]` as "all attesters" while still applying the exclude filter + cursor - (this MUST land before the Sepolia contract freeze — EFSFileView is redeployable - but the model should be settled); **(c)** client wiring so an empty - `lensAddresses` routes to that path instead of rendering blank. Deferred from - PR #27 (the on-chain tag-filter PR). Design notes in `docs/FUTURE_WORK.md`. +## Gate for a future launch checklist -### Communication +Create a new dated checklist only after James has explicitly set a launch +milestone and all of the following exist: -- [ ] Devnet announcement post drafted (positioning: "early access, expect breakage, don't store anything you care about") -- [ ] Discord/Telegram/community channel for devnet feedback ready -- [ ] Bug report / feedback flow documented +- an adopted v2 constitution and support matrix; +- an implementation target with current specs and ADR boundaries; +- a deployment and migration posture; +- explicit security-review and audit requirements; +- a client/SDK release surface; +- honest data-durability, authority, privacy, and operational claims. ---- - -## Pre-Mainnet (target April 22, 2026 — likely slips) - -### Pre-Mainnet Architectural Conversations - -These are open architectural conversations identified during the ADR-0041 PIN/TAG schema split (PR #10) that are out of scope for that change but become much harder to revisit after mainnet. Each deserves its own focused session and ADR — list each conversation as `[ ]` until either an ADR lands or an explicit "no change for v1" decision is recorded in `docs/decisions.md`. - -- [ ] **DATA schema deprecation conversation.** A suggestion surfaced in PR #10's review to remove the DATA schema entirely and replace file placement with `PIN(definition="storageURI", value=BLOB)`. Touches ADR-0001 (three-layer model), ADR-0002 (DATA standalone non-revocable), ADR-0004 (content dedup via `dataByContentKey`), ADR-0011 (transports), ADR-0012 (transport priority), ADR-0013 (lens-scoped mirror selection). The proposal removes the content-addressing layer that lets multiple uploaders converge on the same identity; that layer needs to be replaced by something equivalent or explicitly given up — not just deleted. Decision needed pre-mainnet: keep DATA as-is, redesign, or remove. Default if not addressed: keep DATA (record explicit "no change" decision). -- [ ] **Kernel layer-2 / layer-3 split conversation.** Today `EFSIndexer.sol` does both layer 2 ("I received an attestation; route to handler" — use-case-neutral EAS indexing) and layer 3 ("edges, nodes, paths, active sets" — the graph DB). The two are conceptually separable per the working sketch in `specs/01-System-Architecture.md`. Pre-mainnet split would let layer 2 be reused by other EAS-based projects and let layer 3 stand alone as a graph DB; post-mainnet split is much harder because ADR-0030 freezes EFSIndexer's interface. Cost: cross-contract calls in resolver hot paths add ≥2.6k gas per attestation, so the split must be designed deliberately. Decision needed pre-mainnet: split now, defer to v2 with an explicit migration story, or commit to the combined kernel forever. -- [ ] **Layer-3 audit of `_containsAttestations` (and similar) for file-system bleed.** Some indexes in `EFSIndexer.sol` may be more file-system-specific than graph-generic (the qualifying-folder write-time index from ADR-0008, `_containsAttestations` propagation from ADR-0010). A focused audit would catalog which storage maps belong to layer 3 (graph kernel) vs which should migrate to a layer-4 file-system overlay contract. Output feeds both the kernel split above and any future use-case overlays (social graph, knowledge base, lists). Decision needed pre-mainnet: audit + document layer assignment, even if no code moves; post-mainnet the layer assignment is locked into permanent storage shapes. - -### External Audit - -- [ ] **External audit pass on EFSIndexer** — single most important item. Engage Trail of Bits, OpenZeppelin, or run a Code4rena contest. Two-week minimum engagement. Treat critical findings as launch-blocking. -- [ ] All audit findings resolved or documented as accepted-risk (with reasoning) -- [ ] Audit report published - -### Internal Review - -- [ ] Final agent-review pass after all audit-driven fixes (Claude + Codex + Gemini cross-review) -- [ ] All P1/P2 items in PR review history confirmed resolved -- [ ] Test suite >270 passing (current state preserved) -- [ ] Gas snapshot captured for hot paths (upload, directory listing, web3:// resolution) — baseline for regression detection -- [ ] **Classifier parity test** — off-chain URL classifier (`packages/nextjs/utils/efs/containers.ts#classifyTopLevelSegment` and the production Vite/Lit client's equivalent) produces byte-identical `(flavor, uid)` tuples to `EFSRouter.classifyTopLevel(string)` across a fixture table: valid 40-hex address, all-zero address, ENS name (off-chain only — contract rejects), unregistered 64-hex, registered schema UID, attestation UID, malformed hex (odd-length, non-hex chars), empty string, plain anchor name, and anchor name that happens to look like `0x…`. ADR-0030 locks classifier semantics at mainnet deploy, so any off-chain drift becomes a permanent interop bug. `classifyTopLevel` is a pure external view — the parity test can run against a local hardhat deployment with no state required. Tracked as review comment #8 on PR #9. - -### Mainnet Deploy Readiness - -- [ ] Deploy script tested end-to-end on a fresh fork (not just incremental deploys) -- [ ] All `setTransportsAnchor`, `wireContracts`, etc. one-time calls verified to land in correct order -- [ ] Address mismatch assertions in deploy script confirmed working (revert on bad nonce prediction) -- [ ] `yarn hardhat:simulate` passes against the would-be mainnet config -- [ ] **Recovery plan documented**: if EFSIndexer has a bug post-deploy, what's the migration path? Even if the answer is "redeploy everything," the dependency graph must be written down. -- [ ] Deployer key custody plan (multisig, hardware wallet, etc.) - -### Production UI - -- [ ] Production EFS Client (external Vite/Lit repo) reviewed end-to-end -- [ ] Lenses UX is intuitive — naive user understands "whose content am I seeing?" -- [ ] Gas costs surfaced upfront in upload flow (not post-hoc) -- [ ] "Permanent archive, not a Dropbox" positioning crystal clear in UI copy -- [ ] Mirror unavailability surfaced gracefully (not just blank previews) - -### Ecosystem - -- [ ] At least one compelling curator account seeded (Wikipedia snapshot, Project Gutenberg, government records, etc.) -- [ ] Mirror stewardship plan: who pins IPFS content, who funds Arweave uploads -- [ ] Public web3:// gateway compatibility verified (w3link.io, wevm.dev) -- [ ] Subgraph or off-chain indexer running (or external partner committed to running one) - -### Strategic / Comms - -- [ ] Launch positioning finalized: "permanent record" not "file service" -- [ ] EAS dependency communicated honestly (we are betting on EAS as foundation) -- [ ] Mainnet permanence communicated (no upgrades, no admin override) — this is a feature, market it -- [ ] Press / community announcement drafted - ---- - -## Post-Launch (Week 1) - -- [ ] Monitor gas costs on real usage vs. test estimates -- [ ] Mirror availability monitoring — flag when published content becomes unfetchable -- [ ] Bug-bounty program live (or contracts immutable enough that bounty is "publish a finding for fame") -- [ ] First post-mortem if anything broke - ---- - -## Notes - -- The devnet → mainnet timeline (April 19 → April 22) is tight. Slipping mainnet for the audit is the right call if pressure comes; devnet learnings will feed into mainnet adjustments anyway. -- "Bicycle day" (April 19) is the symbolic launch date — no real reason to slip it for technical issues; the devnet is meant to be rough. -- Mainnet date should be governed by audit completion, not the calendar. ADR-0030 is unforgiving. +Until then, track research and implementation in the planning vault and +repo-local PRs. Do not convert design hypotheses into launch blockers or +calendar commitments. diff --git a/docs/QUESTIONS.md b/docs/QUESTIONS.md index ccd4e91c..cd700735 100644 --- a/docs/QUESTIONS.md +++ b/docs/QUESTIONS.md @@ -1,72 +1,46 @@ # Open Questions -Questions agents have flagged for human decision. Review and resolve before agents continue work in those areas. +Tier 1 and Tier 2 questions blocking work in this repository. -> **For agents:** see `docs/agent-workflow.md` for the full escalation tier system. This file holds **Tier 1 and Tier 2 blocking questions only** — it is auto-loaded at session start and must stay sharp. -> -> Routing: -> - **Tier 1** — belong in chat first (blocking). Add here only after the human acknowledges, for tracking. -> - **Tier 2** — belong in chat AND here. -> - **Tier 3** (task-specific questions) — do NOT go here. Use inline `// AGENT-Q:` code comments, or `decisions.md` if you made a call, or `FUTURE_WORK.md` if it's a nice-to-have. -> -> When resolved, move the entry to `docs/decisions.md` as a one-liner. Don't let this file grow past ~10 items; resolve or reroute. +> **Current state (2026-07-23): no active repo-local blockers.** The questions +> previously listed here were settled for v1. EFS v2 architecture questions +> belong in the planning vault's owner-decision inboxes, not in this file. -> **Format:** newest at top. When resolved, move to `docs/decisions.md` (one-liner) and either delete from this file OR mark resolved in-place. Promote to an ADR if the decision is durable and architectural. - ---- +See `docs/agent-workflow.md` for escalation rules. ## Open -### [tier-2, 2026-04-16, claude] Devnet upgradeability proxy pattern - -You said you plan to add upgradeability for devnet/Sepolia. Which proxy pattern? - -- **TransparentUpgradeableProxy (OpenZeppelin)**: well-documented, proven, but adds ~2,600 gas per call (delegatecall + impl SLOAD). -- **UUPS (OpenZeppelin)**: cheaper per-call, upgrade logic lives in the implementation (more flexible, slightly more risk). -- **Beacon proxy**: shared upgrade target across many proxies; overkill for EFS. - -For EFS the gas-sensitive path is the EFSIndexer hot path (every attestation). Worth the per-call overhead for devnet flexibility? - -**Default if not answered:** TransparentUpgradeableProxy with `hardhat-upgrades` plugin (storage layout enforced). Devnet only — mainnet stays direct deploy per ADR-0030. - -**Blocks:** any work on the devnet upgradeability branch. - -### [tier-2, 2026-04-16, claude] Multi-lens merge semantics +None. -ADR-0031 establishes first-attester-wins fallback semantics. Holistic review noted that for `?lenses=alice,bob,carol` users may expect "merge by newest timestamp across all lenses" rather than strict precedence. +## Recently resolved -Should we: -- **A**: keep first-wins as the only model, document it loudly in the production UI ("attesters are tried in order"). -- **B**: add a second router function `_findDataAtPathMerge()` that returns newest-by-timestamp across all lenses; UI offers a toggle. -- **C**: add a query param `?merge=newest` that switches the existing function's behavior. +### Devnet and Sepolia proxy pattern -C is cleanest for URLs. B is cleanest for code. A is cheapest. +Resolved by ADR-0048 and the Sepolia deployment: the v1 schema resolvers use +`TransparentUpgradeableProxy` plus `ProxyAdmin`. The deployed contracts are +Safe-owned and remain upgradeable; no burn timeline is active. See +`docs/CHAINS.md`. -**Default if not answered:** A for v1; revisit based on production UI feedback. +### Multi-lens merge semantics -**Blocks:** anything that depends on multi-lens resolution semantics being final. Doesn't block this PR. +Resolved for v1 by ADR-0031: ordered, first-attester-wins fallback. A +newest-across-lenses merge mode was not added. ---- +### Production EFS client repository -## Resolved (recent — keep for context) - -### [resolved 2026-04-16] Production EFS Client repo path -URL: https://github.com/efs-project/client — recorded inline in `AGENTS.md`. Production client review is still deferred to a dedicated session (tracked in `docs/LAUNCH_CHECKLIST.md` under Pre-Mainnet → Production UI). - ---- +The separate `efs-project/client` repository exists but is a legacy v1 client, +not the implementation target for Client v2. ## How to add a question +Add only a Tier 1 or Tier 2 blocker after surfacing it in chat: + ```markdown ### [tier-N, YYYY-MM-DD, agent-name] Short title -What's the question? Be specific. - -Options if applicable: -- **A**: option with trade-offs. -- **B**: another option with trade-offs. - -**Default if not answered:** what the agent will do otherwise (so blocked work isn't fully blocked — there's a default position). - -**Blocks:** what other work this affects. +State the concrete fork, options, default, and exactly what it blocks. ``` + +Task-local questions belong in code comments. Nice-to-have work belongs in +`docs/FUTURE_WORK.md`. Cross-repo and v2 architecture choices belong in the +planning vault.