# Agent instructions

You are advising on UX and product design for **ERC-5267: Retrieval of EIP-712 Domain**.
This document is editorial design guidance from EIPs for Designers. Official specifications control protocol facts.

- **Spec Constraints** quote the official specification. Preserve the stated audience, conditions, and source classification. Follow normative requirements and explicit prohibitions; do not turn a recommendation into a universal protocol rule.
- **Anti-Patterns** and design implications are editorial UX guidance. Apply judgment and resolve factual conflicts in favor of the official specification.
- Use the **Vocabulary** section as editorial copy guidance without hiding permissions, risks, or account authority.
- Cite the canonical source URL when giving recommendations.
- Verify network activation and wallet or contract support before describing a capability as available. Specification status alone does not establish deployment.

---

# ERC-5267: Retrieval of EIP-712 Domain

Source: https://www.eipsfordesigners.com/standards/ERC-5267
Agent brief: https://www.eipsfordesigners.com/standards/ERC-5267/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/ERC-5267
Last reviewed: 2026-09-18
Last updated: 2026-09-18

| Field | Value |
| --- | --- |
| Status | Final |
| Chain | ethereum |
| Category | Security & Trust |
| Journey stages | Reading & Understanding, Approving & Permissioning |
| Detailed guide | Yes |
| Official specification | https://ercs.ethereum.org/ERCS/erc-5267 |
| Discussion search | https://ethereum-magicians.org/search?q=ERC-5267 |

## UX Impact

ERC-5267 adds eip712Domain(), a contract interface that publishes the fields and values used by its EIP-712 signing domain. Compatible applications can retrieve and validate the domain before showing a typed-data request; the interface is optional and is not a safety, trust, replay, or wallet-rendering certificate.

## Summary

ERC-5267 adds eip712Domain(), a contract interface that publishes the fields and values used by its EIP-712 signing domain. Compatible applications can retrieve and validate the domain before showing a typed-data request; the interface is optional and is not a safety, trust, replay, or wallet-rendering certificate.

## What does not work everywhere yet

OpenZeppelin Contracts 5.x implements IERC5267 in its EIP712 base contracts, giving builders a concrete implementation path. Contracts may be immutable or use a different domain, and wallets or dapps may not query the interface. Detect support and retain a verified domain fallback for contracts that cannot expose it.

## For Designers

- Fetch the domain from the target contract before presenting a typed-data authorization, then compare chain ID and verifying contract with the actual request.
- Show which domain fields are present and treat extensions as unsupported until the application can decode them.
- Keep domain retrieval separate from replay protection, contract safety, signer identity, and wallet clear-signing.

## Applicability

### When to Use

- A product signs EIP-712 messages for permits, orders, approvals, votes, or other authorizations.
- The application integrates many contracts and wants a common domain-discovery path.
- The product can validate the retrieved values against its own action, chain, and contract policy.

### When to Avoid

- The action is not an EIP-712 signature or the target contract does not verify EIP-712 domains.
- The application cannot handle an unsupported extension or a domain that changes over time.
- The UI would turn a retrieved domain into an unconditional trust badge.

## Problems It Solves

### Users cannot tell which contract context a signature uses

Impact: critical

Old way: Show a generic typed-data approval without independently checking the target domain.

New way: Compare the retrieved domain with the requested contract and chain before signing.

### Each integration hard-codes a different EIP-712 domain adapter

Impact: high

Old way: Guess name, version, chain ID, and verifying contract from token-specific code.

New way: Query a common eip712Domain() interface when the contract supports it.

### Domain changes are hidden behind stale app data

Impact: high

Old way: Continue showing a cached name, version, or chain after an upgrade or domain change.

New way: Refresh on EIP712DomainChanged or before a high-risk signature.

## Spec Constraints

Quotes retain their source section and scope. Normative requirements, rationale, compatibility changes, and security recommendations are not interchangeable. Design implications are editorial guidance.

### A compliant contract must expose eip712Domain with the declared fields and return every specified value for reliable client decoding.

Applies to: account-implementation
Source classification: normative

> Compliant contracts MUST define `eip712Domain` exactly as declared below. All specified values MUST be returned even if they are not used, to ensure proper decoding on the client side.

Source: [Specification](https://ercs.ethereum.org/ERCS/erc-5267#specification)

Design implication (editorial): Build signing and verification flows around the declared domain fields, and show an explicit unavailable or malformed-domain state when a contract does not return the expected shape.

### The returned domain values must describe the domain separator used to verify EIP-712 signatures.

Applies to: wallet
Source classification: normative

> The return values of this function MUST describe the domain separator that is used for verification of EIP-712 signatures in the contract.

Source: [Specification](https://ercs.ethereum.org/ERCS/erc-5267#specification)

Design implication (editorial): Render the retrieved domain as signing context and validate it before asking users to approve a typed-data signature; do not replace it with a display-only label.

### Each declared domain extension must identify an EIP-712 extension that defines how its fields and values are obtained.

Applies to: wallet
Source classification: normative

> `extensions`: A list of EIP numbers, each of which MUST refer to an EIP that extends EIP-712 with new domain fields, along with a method to obtain the value for those fields, and potentially conditions for inclusion.

Source: [Specification](https://ercs.ethereum.org/ERCS/erc-5267#specification)

Design implication (editorial): Treat extension fields as separately specified signing context, and do not silently ignore an extension identifier that the wallet cannot resolve or render.

### A contract's EIP-712 domain may change over its lifetime, so applications should refresh it and should not assume frequent changes are impossible.

Applies to: wallet
Source classification: normative

> The return values of this function (equivalently, its EIP-712 domain) MAY change throughout the lifetime of a contract, but changes SHOULD NOT be frequent. The `chainId` field, if used, SHOULD change to mirror the [EIP-155](./eip-155.md) id of the underlying chain. Contracts MAY emit the event `EIP712DomainChanged` defined below to signal that the domain could have changed.

Source: [Specification](https://ercs.ethereum.org/ERCS/erc-5267#specification)

Design implication (editorial): Refresh cached signing context after a domain-change signal or relevant contract update, and keep chainId-aware confirmation tied to the current network.

### User-agents should support immutable contracts that cannot add the interface by using a cautious address-and-chain domain fallback.

Applies to: wallet
Source classification: backwards-compatibility

> User-agents or applications that use this EIP SHOULD additionally support those contracts that due to their immutability cannot be upgraded to implement it.

Source: [Backwards Compatibility](https://ercs.ethereum.org/ERCS/erc-5267#backwards-compatibility)

Design implication (editorial): Offer a clearly labeled legacy-domain path for known immutable contracts, but do not guess a domain or silently skip typed-data context when it cannot be established.

### Before requesting a signature, applications should generally validate that verifyingContract and chainId match the contract and current chain.

Applies to: wallet
Source classification: security-considerations

> user-agents and applications should in general validate that these do match the contract and chain before requesting any user signatures for the domain.

Source: [Security Considerations](https://ercs.ethereum.org/ERCS/erc-5267#security-considerations)

Design implication (editorial): Make domain mismatches blocking or unmistakably exceptional in signing UI, and explain when a contract intentionally uses a different verifyingContract or chainId.

## Anti-Patterns (editorial)

- **Calling a domain match a security certificate** (critical)
  - Why: The interface reports what a contract uses; it does not prove the contract or publisher is trustworthy.
  - Instead: Label the exact match and provide independent contract, source, and authorization review.

- **Treating domain retrieval as replay protection** (critical)
  - Why: Replay prevention still requires contract and application rules such as nonce consumption and deadlines.
  - Instead: Show and validate the domain alongside the actual authorization and replay policy.

- **Assuming every EIP-712 contract implements ERC-5267** (high)
  - Why: The interface is an optional extension and many immutable contracts predate it.
  - Instead: Feature-detect the call and use a verified contract-specific fallback when appropriate.

- **Showing all returned fields as active domain fields** (high)
  - Why: Fields not marked in the bit map are unspecified and should not be presented as part of the domain.
  - Instead: Decode the fields bit map and display only fields that are present.

- **Ignoring unknown domain extensions** (high)
  - Why: The client may show an incomplete domain and let the user sign a request it cannot interpret.
  - Instead: Block or explicitly mark unsupported extensions until the client can decode them.

## Design Decisions

### Should a domain match show a safety badge?

Recommendation: Use a narrow label such as Domain matches this contract and chain.

Rationale: ERC-5267 describes the verifier's domain; it does not audit code, authenticate a publisher, or make the requested authorization harmless.

### What should be cached?

Recommendation: Cache only with a contract, chain, and freshness policy, and invalidate on EIP712DomainChanged.

Rationale: The specification allows domain values to change during a contract's lifetime.

### What happens when the interface is absent?

Recommendation: Use a contract-specific verified fallback or block high-risk signing rather than guessing the domain.

Rationale: Many immutable or older contracts cannot be upgraded to expose ERC-5267.

### How do domain and message details share the hierarchy?

Recommendation: Lead with the user action, then show domain and raw fields as a reviewable context layer.

Rationale: The domain matters for authorization boundaries, but it should not hide the amount, recipient, allowance, or order terms.

## States to Design

### Domain retrieved and matches

Trigger: The contract returns a supported domain whose chain and verifying contract match the action.

User need: Know the signature context before approving the concrete action.

Design response: Show the present fields and human action together; label the result as a domain match, not a safety guarantee.

### Domain mismatch

Trigger: Retrieved chain ID or verifying contract differs from the intended target, or the domain uses a policy-disallowed value.

User need: Avoid authorizing an action in another context.

Design response: Block signing, identify the mismatched field, and offer a refresh or safe cancellation path.

### Interface unsupported

Trigger: The target contract does not implement eip712Domain().

User need: Understand why the app cannot verify a generic domain.

Design response: Use a separately verified domain registry or contract-specific adapter when available; otherwise show an unverified-domain warning and do not imply ERC-5267 support.

### Extension unsupported

Trigger: The returned extensions array contains an EIP the client cannot decode.

User need: Know that the displayed domain is incomplete.

Design response: Do not construct or request the signature until the extension is understood; expose the extension number for debugging.

### Domain changed

Trigger: The contract emits EIP712DomainChanged or a fresh read returns different values.

User need: Avoid signing against stale context.

Design response: Invalidate cached domain data, re-render the review, and explain which fields changed.

## Vocabulary

- Use "Signing domain" instead of "Verified app": The domain describes signature context; it does not authenticate the publisher or code.

- Use "Matches this contract and chain" instead of "Safe to sign": A context match says nothing about the requested authorization's consequences.

- Use "Domain unavailable" instead of "No domain": The contract may still use an EIP-712 domain even when it does not expose the retrieval interface.

## UX Patterns

### Domain Verification Layer

Retrieve and compare the signing domain before rendering a typed-data confirmation.

Components: Domain field table, Contract and chain matcher, Unsupported-extension state, Refresh control

User flow:

- Identify target contract and chain
- Call eip712Domain() when supported
- Decode fields and supported extensions
- Compare values with the requested domain
- Render human action and domain context
- Block, refresh, or continue based on policy

### Unverified Domain Fallback

Keep signing understandable when the contract is immutable or does not expose ERC-5267.

Components: Unverified-domain warning, Verified adapter source, Raw contract and chain fields, Cancel action

User flow:

- Detect missing ERC-5267 support
- Look up a separately verified domain only when policy allows
- Show the source and freshness of that fallback
- Keep concrete authorization terms visible
- Require explicit consent or stop

## What to Prototype First

### Domain-aware signing review

The domain determines which contract, chain, and application context the signature is intended for.

Covers: Domain matches, Domain mismatch, Domain unavailable

- Present fields only
- Chain and verifying contract comparison
- Retrieval timestamp or block context
- Raw data disclosure

### Permit or order authorization

Users need to distinguish the signing domain from the concrete allowance, order, or permission they are granting.

Covers: Valid domain, Stale domain, Replay or nonce failure

- Human action summary
- Domain details
- Nonce and deadline
- Reject and refresh paths

## Mental Model

### Typed message

The application asks the user to sign structured fields such as an amount, recipient, nonce, or deadline.

### Signing domain

EIP-712 domain fields describe the context in which the contract verifies the typed message.

### Domain retrieval

The application calls eip712Domain() to learn which optional fields and values the contract declares, when the contract implements ERC-5267.

### Independent validation

The app compares the returned domain to the intended chain and contract and still applies its own nonce, expiry, authorization, and trust policy.

## UI Components

### Eip712DomainTable

Shows only the fields declared by the contract, with chain and verifying-contract comparison.
Kind: list
States: loading, matched, mismatch, unsupported, extension-unsupported, changed
Props: fields, expectedDomain, extensions, sourceBlock

### DomainTrustNotice

Clarifies the boundary between a retrieved domain, application validation, and broader contract trust.
Kind: status
States: verified-context, unverified, blocked
Props: verifyingContract, chainId, fallbackSource, reason

## Key Takeaways

- ERC-5267 makes an EIP-712 domain queryable when a contract opts in.
- Decode the fields bitmap and supported extensions before rendering the domain.
- A domain match is contextual evidence, not a safety or replay guarantee.
- Keep a verified fallback or a blocked state for contracts without the interface.

## Related Standards

- EIP-712: Defines typed structured data and the domain separator described by ERC-5267. — https://www.eipsfordesigners.com/standards/EIP-712/agent.md

- ERC-2612: A permit use case whose domain can be discovered or checked. — https://www.eipsfordesigners.com/standards/ERC-2612/agent.md

## Technical Notes

ERC-5267 requires eip712Domain() to return a bytes1 fields bitmap, name, version, chainId, verifyingContract, salt, and an extensions array. The bitmap identifies which of the five standard EIP-712 fields are present. The returned values describe the domain separator used for signature verification and may change over the contract lifetime; EIP712DomainChanged can signal a change. Contracts may use a chainId or verifyingContract different from the current chain or contract, so applications should validate those values for their policy. ERC-5267 does not define wallet rendering or application replay protection.

## Official specification (reference only)

https://ercs.ethereum.org/ERCS/erc-5267