Repository navigation
docs(specs): specify the ENS integration - #93
Open
SupremaLex wants to merge 18 commits into
Open
SupremaLex wants to merge 18 commits into
SupremaLex wants to merge 18 commits into
Conversation
Move design/ens-integration.md to docs/pages, where the Starlight site publishes it at /docs/ens-integration/. The heading becomes the page's title frontmatter; the text is unchanged. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Wondertan
reviewed
Oct 2, 2026
Wondertan
left a comment
Wondertan
left a comment
Member
There was a problem hiding this comment.
If we move this doc, I think we need to update the shape of the doc and clean it up a little bit, currently it is indeed a design doc.
| description: How libID handles resolve as ENS names in wallets. | ||
| --- | ||
|
|
||
| **Status: design proposal.** Nothing here is built. It is not a protocol spec in |
Member
There was a problem hiding this comment.
is it still proposal tho? I thought it was implemented.
SupremaLex
marked this pull request as draft
October 2, 2026 13:25
Rewrite the ENS integration design as a normative spec chapter, with assumptions, security properties, requirements and conformance vectors, and link it from the specification index. Where the design and the deployed resolver and gateway disagree, the spec follows the code: an EVM chain the gateway does not index gets an unsigned 503 rather than a signed null, the resolver also announces ERC-165, and the platform id is the registry's for the platform key. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
SupremaLex
changed the title
Keep main's browser-ceremony chapters and the ENS chapter side by side in the specification index and its ownership table. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Drop REQ-ENS-KEY-02. The digest covers no chain ID, so an answer replays across resolvers at one address that trust the same signer; Security Considerations states when that replay is wrong. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The digest binds an answer to its resolver's address, not its chain, so one Signer may serve several chains while their resolvers' addresses differ (REQ-ENS-KEY-02); SP-ENS-01 says so. Removing a Signer takes effect at once on each chain, since the callback checks it when it runs. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Coin type 60 matches the chain whose ENS registry holds the Parent Name, which the Gateway is configured with, not always chain 1. A coin type at or above 2^64 names no EVM chain and gets a Signed Null. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The Gateway answers under a configured domain: handles.link in production, a name under it such as testnet.handles.link for a test deployment. The grammar, the right-to-left parse and the foreign-name 400 refer to the Parent Name rather than the literal handles.link, and TEST-ENS-06 covers a subname Parent Name. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The Gateway checks an inverted handle against the rules built into it, the same for every chain, so a binding admitted only under wider rules on a chain gets a Signed Null; SP-ENS-03 now depends on the rules agreeing. A Workspace label with '-' at its third and fourth characters, IDNA domain labels among them, is refused, since ENSIP-15 refuses it. The Security Considerations say plainly that the Gateway reads names outside the transform's image, among them _at followed by gmail.com. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The node/name comparison applies to addr calls only; any other record gets the signed empty result once the name is wire-valid and under the Parent Name. A label that is not UTF-8 is a wire error and gets HTTP 400. REQ-ENS-GW-11 lists the steps in the order the Gateway takes them: the Signed Nulls of REQ-ENS-GW-05 come before the staleness check and the handle rules after it, and the consequence is stated. TEST-ENS-07 covers the order and the 400s. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
REQ-ENS-RES-03 names the encoding OpenZeppelin ECDSA.recover accepts and
the other ways a malformed answer reverts; REQ-ENS-GW-08 requires the
Gateway to sign the digest unprefixed in that encoding. REQ-ENS-RES-05
requires every resolver URL to carry {sender} and {data}, since a URL
without {data} is fetched by POST and the Gateway serves GET only.
Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The current deployment holds the Handle Resolver's owner, the deployer and the Parent Name's owner as one key, so it does not meet REQ-ENS-KEY-01; Security Considerations say so. Provenance records the forward transform in @libid/ens (libID PR #109, unmerged) and what it lacks, the unimplemented SHOULD of REQ-ENS-LABEL-05, where REQ-ENS-RES-05 is enforced, and the new REQ-ENS-GW-11. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
REQ-ENS-GW-06 applies before the handle rules and the holder, not before every answer from the selected chain, matching REQ-ENS-GW-11. Reflows two paragraphs. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
An uppercase label reaches REQ-ENS-GW-05 only for an addr call. Drops a TEST-ENS-01 vector no normalized handle can produce: every platform's rules keep a handle under 63 bytes. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
SupremaLex
added a commit
that referenced
this pull request
Oct 5, 2026
That revision has the Workspace refusal and the Parent Name parameter the package implements. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
An X handle containing '-' has no name, since the '_' to '-' substitution reverses only while no handle holds '-'; a GitHub handle containing '_' or '--' at its third and fourth characters has no name. Both match @libid/ens. A Chain Label is at most 63 bytes and has no '--' at its third and fourth characters; Provenance records that the indexer's ChainName::parse does not check either. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
REQ-ENS-NAME-05 keeps production Chain Labels off the first label of a deployment under handles.link, such as testnet. REQ-ENS-GW-12 requires the ENS Chain to be indexed for coin type 60 to answer, and REQ-ENS-GW-13 requires Gateways in one URL list to map Chain Labels alike, since an unmapped label gets a Signed Null. ASM-ENS-01 no longer claims a client never receives another chain's address; Security Considerations describe MetaMask's fallback to addr(bytes32) and how a Chain Label defeats it. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
…t rules
TEST-ENS-08 to -12 cover the interface set, the OffchainLookup shape and
NoUrls, two-step non-renounceable ownership, the URL placeholders, and
{data} parsing. TEST-ENS-13 is a deployment check for REQ-ENS-KEY-02 and
the Chain Label, ENS Chain and shared-label rules. The ERC-7996 rationale
of REQ-ENS-RES-01 rests on the deployed Gateway refusing a mismatched
{sender}, which REQ-ENS-GW-08 permits. Step 3 of REQ-ENS-GW-11 includes an
addr call whose arguments do not decode. §4 points at §11.
Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
REQ-ENS-KEY-01 requires the owner key to be held cold, so the online KMS deployer key that owns the current deployment visibly fails it. Its necessity no longer says a URL buys nothing: a URL holder can serve a signed answer until it expires and end lookups, which Security Considerations now describe. Provenance records that nothing enforces REQ-ENS-KEY-02 and that @libid/ens carries the refusals and a parent option. libid.md names the Parent Name as a deployment parameter and lists the ENS principals and trust roots. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
SP-ENS-03 also depends on REQ-ENS-GW-13. The KEY-01 consideration describes what the deploy workflow does per environment, and the REQ-ENS-RES-05 Provenance row names the workflow's placeholder check beside the script's. Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
SupremaLex
added a commit
that referenced
this pull request
Oct 5, 2026
Assisted-by: Claude Opus 5.5 Signed-off-by: SupremaLex <georglutsenko@gmail.com>
SupremaLex
marked this pull request as ready for review
October 6, 2026 08:16
This branch has not been deployed
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
2 participants
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.
Rewrites the ENS integration design (
design/ens-integration.md) as a normative spec chapter,specs/ens-integration.md, and links it from the specification index (specs/libid.md).The chapter follows the other specs:
ASM-ENS-*) and security properties (SP-ENS-*);REQ-ENS-*);TEST-ENS-01to-13), security considerations, and a provenance table that says what is implemented where.The design's reasoning survives as each requirement's "Necessity". Its open decisions are listed under "Not specified".
The spec follows the deployed code
Where the design and the deployed resolver and gateway disagreed, the spec says what the code does:
ENS_CHAIN_ID), not always chain 1handles.linkin production, a name under it such astestnet.handles.linkaddraddronlyDecisions recorded
@libid/ens(feat(ens): @libid/ens, the ENS name of a handle #109):__at the third and fourth characters, or any-;_, or--at the third and fourth characters;--at the third and fourth characters (xn--domains),_atas a piece, an empty piece;testnet(REQ-ENS-NAME-05).Not met or not enforced today
forge create.ab--cd.xand_at.gmail.com.ChainName::parseaccepts labels the spec refuses (over 63 bytes,--).@libid/ens(libID feat(ens): @libid/ens, the ENS name of a handle #109, open), and the HandleResolver NatSpec pointer moves to this spec in libID-contracts popup: mobile-WebKit flake in close-right-after-navigate (CI only) #86.0xc09b…74CE, with the Gateway atnames.handles.linkserving chain 1. Sepolia's resolver points at the same Gateway, which by design does not serve it.Checks
REQ/SP/ASM/TEST-ENSid is defined once, and every reference resolves.pnpm -C site install --frozen-lockfile,buildandtestpass. The chapter publishes under/specs/ens-integration/.🤖 Generated with Claude Code
https://claude.ai/code/session_01Ar21wPcHzNprswTzLJd3MA