Skip to content

router: open decoded names from generic web3:// clients; cache store bytes (#34) - #55

Merged
JamesCarnley merged 4 commits into
mainfrom
claude/router-web3-fixes
Nov 12, 2026
Merged

JamesCarnley merged 4 commits into
mainfrom
claude/router-web3-fixes

Conversation

@JamesCarnley

@JamesCarnley JamesCarnley commented Oct 27, 2026 •

Copy link
Copy Markdown
Member

Summary

Why

A file stored as my%20notes.txt reached the router as my notes.txt from w3link, eth.limo or web3protocol-js, and 404'd. Only the SDK and explorer could open it, because they send the canonical form.

The re-encode is idempotent on canonical input: a %XX escape of a reserved byte passes through unchanged. Existing SDK and explorer requests behave exactly as before. Any other % (lowercase hex, an escape of an unreserved byte, a bare %) is literal text and becomes %25.

The one ambiguity: a human name that literally contains a canonical escape (50%20off) is reached by URL as 50 off. This is documented in specs/02.

Permanence tier

Durable. EFSRouter is a stateless, redeployable view in no schema UID. EFSBytesStore is deployed per file; only new stores get the header. No kernel, resolver, or schema change.

Deploy note

Nothing changes on Sepolia until the EFSRouter view is redeployed (an ownerless EOA deploy via yarn deploy:efs-views) and CHAINS.md, deployedContracts.ts, deployments/sepolia and the SDK registry are updated. That deploy is not part of this PR.

Specs / ADRs touched or checked

  • specs/02 (updated: how the router reads a name from a URL)
  • specs/overview.md (updated: read-flow steps 3 and 7)
  • docs/decisions.md (updated: off-chain mirror stance)
  • ADR-0058 / ADR-0057 / ADR-0025: confirmed in force. The router change sits inside ADR-0058's serving path; the kernel's validation (ADR-0025 / ADR-0048 canonical form) is unchanged.

Test plan

  • New router tests (Decoded path segments):
    • Five failed on main with 404: spaces, reserved bytes in intermediate folders, a literal %, the per-byte check, and the next-chunk round-trip. All pass now.
    • Two passed on main and still pass: canonical input stays idempotent, and %41 is not decoded as A.
  • Per-byte check: creates a folder for every ASCII byte 0x00–0x7F plus a UTF-8 name. EFSIndexer must accept the test's canonical encoder, and the router must find each folder from the decoded name. This keeps the router's reserved table byte-aligned with the kernel's.
  • Shared golden vectors with the SDK codec (efs-project/sdk 78551f8, sdk PR Chunk manager v2: support large on-chain file uploads #7), vendored verbatim at packages/hardhat/test/fixtures/anchor-names.vectors.json. All 177 cases pass: 157 accept (indexer accepts; router resolves canonical, and decoded exactly when decodedUrlReachable), 18 reject (indexer reverts), 2 SDK-only NFC rejects (indexer accepts).
  • EFSBytesStore: new test asserts the immutable header on every 200 (first chunk, later chunk, empty store) and its absence on 404. Header-count assertions updated.
  • Full hardhat suite before the vector tests: 667 passing; router file with them: 78 passing, 23 pending (fork-only). yarn hardhat:lint clean; yarn docs:check OK.

Agents involved

  • Dev: Claude Opus 5.5
  • Review: none yet
  • Orchestrator: James

Refs #34

🤖 Generated with Claude Code

…bytes

Generic web3:// clients (web3protocol-js, w3link, eth.limo)
percent-decode each path segment before calling request(), so a file
stored as `my%20notes.txt` arrived as `my notes.txt` and 404'd. Any
name with a space or other reserved byte was unreachable outside the
SDK and explorer (issue #34 item 1).

EFSRouter now re-encodes each walked segment to EFSIndexer's canonical
anchor-name form before the lookup. It is idempotent on canonical input
(a `%XX` escape of a reserved byte passes through), so the SDK and
explorer, which send canonical names, are unaffected. Any other `%` is
literal text and becomes `%25`. The one ambiguity is a human name that
literally contains a canonical escape (`50%20off`), which a URL reaches
as `50 off`; that is documented in specs/02.

EFSBytesStore 200 responses now carry `Cache-Control: public,
max-age=31536000, immutable` (item 3): a store's chunks and content type
are fixed at construction. The router sends no cache header because a
lens can re-point a path.

Docs (item 4): the overview read flow now says generic web3:// clients
do not follow `message/external-body`, so off-chain mirrors render
empty there; web3:// is EFS's on-chain transport. Logged in
decisions.md.

Verified: new router tests reproduce the 404 before the fix, and a
per-byte test creates a folder for every ASCII byte plus a UTF-8 name,
proving EFSIndexer accepts the test's encoder and the router finds each
from the decoded name. Full hardhat suite: 667 passing, 23 pending
(fork-only). hardhat lint clean.

Takes effect on Sepolia only after the stateless EFSRouter view is
redeployed; existing byte stores keep their old bytecode.

Refs: #34
Permanence-tier: Durable
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T21:23:57.578533Z c90bda8 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

The SDK's name codec and this router's re-encoding have to produce the
same bytes, or a name written via the SDK won't resolve through a
web3:// URL. Vendor the SDK's golden file verbatim
(efs-project/sdk 78551f8, sdk PR #7) and run all 177 cases:
- accept (157): EFSIndexer accepts `canonical`; the router resolves
  it both canonical and, exactly when `decodedUrlReachable`, decoded.
  The three unreachable cases (`%2F`, `50%20off`, `100%25`) are the
  documented ambiguity; each vector gets its own parent folder, so a
  decoded lookup can only hit that vector's anchor.
- reject (18): EFSIndexer reverts.
- sdkOnlyReject (2): EFSIndexer accepts (it cannot check NFC).

All pass with no change to the router or the vectors.

Refs: #34
Permanence-tier: Durable
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
JamesCarnley and others added 2 commits October 27, 2026 17:55
Per the SDK session (James approved the move): this repo now owns
`test/fixtures/anchor-names.vectors.json`; efs-project/sdk keeps a
byte-identical copy that its CI checks against contracts main (sdk PR
#9, which needs this PR merged first). Re-copied from sdk e55362a:
only the `$comment` header changed (it names this copy canonical); all
177 vectors are byte-identical. specs/02 now points at the file as the
normative test set.

Also fixes a backwards sentence in specs/02 and the router NatSpec. A
file named `50%20off` is stored `50%2520off`. Its plain URL
`…/50%2520off` decodes to `50%20off`, which the router keeps as an
escape, so it reaches the file named `50 off`. The literal-named file
is reachable only via the SDK or a doubly-encoded URL. Two new tests
pin this, and that a still-encoded non-ASCII segment (`caf%C3%A9`) is
not decoded (conforming clients decode first).

Router suite: 80 passing. hardhat lint and docs:check clean.

Refs: #34
Permanence-tier: Durable
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the two overlaps with #53: keep both new decisions.md entries,
and in specs/overview.md read-flow keep this branch's step 3 (segment
re-encoding) with main's step 4 (WHITEOUT terminal not yet live on
Sepolia).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@JamesCarnley
JamesCarnley merged commit 1664224 into main Nov 12, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants