feat(adapter-evm): opt-in mainnet-L1 fallback for forward & reverse ENS resolution

[pasevin]

Summary

Adds an opt-in enableMainnetL1MissFallback seam to the EVM adapter that consults Ethereum mainnet L1 as a fallback for both forward and reverse ENS resolution when the bound chain returns a definitive empty result. Display-only, never-silent, and provenance-honest.

• Never-silent: fallback fires only on a definitive bound-chain miss — never on errors. Failures surface as typed NameResolutionError.
• Provenance triplet (resolvedViaNetworkFallback, queriedOnNetworkId, resolvedOnNetworkId) is emitted only on a bound-empty-miss that resolved on L1, so non-UR direct-L1 reverse is not mislabeled as a fallback (avoids a misleading UIKit disclaimer).
• Wiring fix: the opt-in is threaded through adapter-evm createRuntime → capability factory so it actually reaches the runtime.
• Requires @openzeppelin/ui-types ^3.3.0 (carries the triplet fields); floor bumped on adapter-evm + adapter-evm-core.

Release

• Changeset bumps both @openzeppelin/adapter-evm and @openzeppelin/adapter-evm-core (minor). adapter-evm-core is private and bundled into adapter-evm, so adapter-evm must bump for the fix to reach npm (guards against the shipped-nothing trap).
• Test-infra: vitest resolve.dedupe(@openzeppelin/ui-types) so the multi-version workspace loads a single RuntimeDisposedError class in tests.

Test plan

• pnpm -r typecheck — green
• pnpm -r lint + pnpm format:check — green
• pnpm -r test — all 8 packages green (adapter-evm-core 1167, adapter-evm incl. new SF-5 release-correctness probes)
• pnpm build — green
• pnpm install --frozen-lockfile — clean (resolves published [email protected])

Made with Cursor

[Copilot]

Pull request overview

Adds an opt-in mainnet L1 ENS miss-fallback to the EVM adapter’s name-resolution capability, with provenance triplet fields to accurately signal cross-network fallback, and threads the option through runtime creation so it’s actually honored at runtime.

Changes:

• Implement opt-in L1 fallback for forward + reverse ENS resolution on definitive bound-chain misses, plus shared mayConsultL1ForMissFallback() gating.
• Emit cross-network provenance triplet (resolvedViaNetworkFallback, queriedOnNetworkId, resolvedOnNetworkId) only for bound-empty → L1 success scenarios.
• Bump @openzeppelin/ui-types floor to ^3.3.0, add Vitest dedupe, and add release-correctness probes/docs/changeset.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
vitest.shared.config.ts	Dedupes @openzeppelin/ui-types/@openzeppelin/ui-renderer in Vitest to avoid multi-version class identity issues.
pnpm-lock.yaml	Updates lockfile to reflect dependency/version floor changes and dedupe effects.
packages/adapter-evm/test/sf-5-published-release.test.ts	Adds “published tarball contains the delta” probes to prevent core-only release regressions.
packages/adapter-evm/src/profiles/shared.ts	Threads runtime opt-in through capability factory wiring; refactors name-resolution option building.
packages/adapter-evm/src/tests/profile-runtime.test.ts	Verifies createRuntime forwards the opt-in flag into createNameResolution options.
packages/adapter-evm/package.json	Raises @openzeppelin/ui-types peer/dev dependency floor to ^3.3.0.
packages/adapter-evm-core/src/name-resolution/service.ts	Implements opt-in-gated L1 miss-fallback for forward+reverse and composes fallback provenance.
packages/adapter-evm-core/src/name-resolution/provenance.ts	Adds triplet builders + canonical MAINNET_NETWORK_ID constant for fallback provenance.
packages/adapter-evm-core/src/name-resolution/index.ts	Re-exports new provenance helpers and service options type.
packages/adapter-evm-core/src/name-resolution/tests/service.reverse-l1.test.ts	Updates reverse ladder tests to reflect opt-in gating and triplet emission rules.
packages/adapter-evm-core/src/name-resolution/tests/service.mainnet-l1-opt-in.test.ts	New suite pinning default-OFF behavior and strict === true enablement.
packages/adapter-evm-core/src/name-resolution/tests/service.forward-l1.test.ts	New suite covering opt-in-gated forward L1 fallback behavior + error discipline.
packages/adapter-evm-core/src/name-resolution/tests/provenance.test.ts	Extends provenance tests to cover new triplet builders and constant.
packages/adapter-evm-core/src/name-resolution/tests/network-fallback-provenance.test.ts	Integration tests for when triplet is present/absent across paths and errors.
packages/adapter-evm-core/src/name-resolution/tests/helpers/fallback-provenance.ts	Shared test helpers for triplet completeness and chain-agnostic classification.
packages/adapter-evm-core/src/name-resolution/tests/fixtures.ts	Adds reusable opt-in options bag fixture for tests.
packages/adapter-evm-core/src/index.ts	Re-exports new provenance helpers and service options type at package root.
packages/adapter-evm-core/src/capabilities/name-resolution.ts	Extends capability options with opt-in flag and threads it to the service.
packages/adapter-evm-core/package.json	Raises @openzeppelin/ui-types peer/dev dependency floor to ^3.3.0.
packages/adapter-evm-core/docs/name-resolution/README.md	Documents opt-in behavior, forward+reverse ladders, and triplet semantics.
packages/adapter-evm-core/docs/name-resolution/integration-guide.md	Adds explicit opt-in wiring guidance + patterns for triplet-based disclaimers.
packages/adapter-evm-core/docs/name-resolution/examples/reverse-miss-fallback/resolve-miss-fallback.ts	Updates example to pass opt-in and print triplet fields.
packages/adapter-evm-core/docs/name-resolution/examples/reverse-miss-fallback/README.md	Updates example README for 003 opt-in + triplet expectations.
packages/adapter-evm-core/docs/name-resolution/examples/README.md	Updates examples index to reflect 003 behavior.
packages/adapter-evm-core/docs/name-resolution/api-reference.md	Updates API reference for new options and exported provenance helpers.
docs/releases/003-ens-mainnet-l1-opt-in-fallback/README.md	Adds release overview and consumer quickstart for the 003 feature.
docs/releases/003-ens-mainnet-l1-opt-in-fallback/integration-guide.md	Adds release-specific migration/verification steps (dist grep, pin ui-types).
docs/releases/003-ens-mainnet-l1-opt-in-fallback/CHANGELOG.md	Draft release notes for Changesets version PR.
.changeset/ens-mainnet-l1-opt-in-fallback.md	Dual-package changeset bumping adapter-evm + adapter-evm-core (minor).

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.