Repository navigation
router: open decoded names from generic web3:// clients; cache store bytes (#34) - #55
Merged
Merged
Conversation
…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>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
4 tasks done
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>
4 of 5 tasks
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
EFSRouterre-encodes each path segment to EFSIndexer's canonical anchor-name form before the lookup, so generic web3:// clients (which percent-decode segments) can open names with spaces and other reserved bytes.EFSBytesStore200 responses sendCache-Control: public, max-age=31536000, immutable. The router sends no cache header, because a path's content can change when a lens re-pins it.specs/overview.mdnow says generic web3:// clients don't followmessage/external-body, so off-chain mirrors render empty there. The stance (web3:// is EFS's on-chain transport) is logged indocs/decisions.md.Why
A file stored as
my%20notes.txtreached the router asmy notes.txtfrom 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
%XXescape 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 as50 off. This is documented in specs/02.Permanence tier
Durable.
EFSRouteris a stateless, redeployable view in no schema UID.EFSBytesStoreis deployed per file; only new stores get the header. No kernel, resolver, or schema change.Deploy note
Nothing changes on Sepolia until the
EFSRouterview is redeployed (an ownerless EOA deploy viayarn deploy:efs-views) andCHAINS.md,deployedContracts.ts,deployments/sepoliaand the SDK registry are updated. That deploy is not part of this PR.Specs / ADRs touched or checked
Test plan
Decoded path segments):%, the per-byte check, and the next-chunk round-trip. All pass now.%41is not decoded asA.0x00–0x7Fplus 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.packages/hardhat/test/fixtures/anchor-names.vectors.json. All 177 cases pass: 157 accept (indexer accepts; router resolves canonical, and decoded exactly whendecodedUrlReachable), 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.yarn hardhat:lintclean;yarn docs:checkOK.Agents involved
Refs #34
🤖 Generated with Claude Code