ERC-7506 Trusted hints registry (Trusted Hint Registry)

Draft · Names & metadata · created 2023-08-31

A standard registry that stores and manages hints, which are on-chain metadata needed for interpreting and verifying claims, in a namespace and list structure. It can record revocation information, lists of trusted issuers, timestamp hashes, and similar data.

Why it is needed

Ecosystems such as companies or communities issue many assertions, or claims, about their members. Examples include whether a given credential is still valid, or which issuers can be trusted. In practice, however, verifiable claims alone are not enough; supporting information is also needed to confirm whether a claim has been revoked or whether its issuer is trustworthy. Without a standard for managing this information structurally on-chain, each ecosystem ends up building its own ad hoc approach, making it hard for participants to establish and maintain trust with one another. This standard calls this supporting information a hint and defines a common contract interface that lets anyone create and manage a hint list under their own address. It also standardizes delegating management authority to another address or allowing execution by signature alone, providing a foundation layer that lets decentralized ecosystems rely on claims.

What to implement

In depth

A namespace-centered 4-level mapping structure

The storage structure is mapping(address => mapping(bytes32 => mapping(bytes32 => bytes32))) hints. A namespace address maps to a hint list, the list to a hint key, and the key to a hint value. Because the namespace is the owner's Ethereum address itself, initial ownership of every list under that address is implicitly determined without any separate claiming process. This simplifies write-permission checks and reduces the attack surface. Features like delegate management or list ownership transfer check permissions using separate auxiliary data structures and do not affect the base namespace structure.

Distinction between required and optional functions

The contract is named TrustedHintRegistry. getHint, setHint, setHints, and setHintsSigned are core functions that MUST be implemented. setHintSigned and the delegation family (setHintDelegated, etc.), the list management family (setListStatus, setListOwner, addListDelegate, removeListDelegate, and each Signed variant), and the metadata family (getMetadata, setMetadata, etc.) are MAY (optional). Write functions may also implement overloaded versions that add a _metadata parameter. Governance is intentionally excluded from this ERC and can be implemented according to each ecosystem's needs. All five events (HintValueChanged, etc.) MUST be emitted in their corresponding situations.

EIP-712 Meta Transactions and Nonces

Signed function variants separate the transaction signer from the transaction sender. The signer only signs the data, and the sender takes that signature and submits it to the contract. The signature MUST follow the EIP-712 format and uses a type hash defined per function. For example, setHintSigned uses the keccak256 hash of SetHintSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,address signer,uint256 nonce). A signed payload must be usable only once, and a dedicated nonce mapping for meta transactions is recommended for this purpose. Once signature verification succeeds, the contract increments the signer's nonce to prevent replay of the same transaction.

Granting delegates time-limited write permission

A namespace owner can use addListDelegate to add a delegate address to a specific hint list. The _untilTimestamp parameter sets how long that permission remains valid. Delegates get write permission limited to that list through dedicated functions such as setHintDelegated, setHintsDelegated, and setMetadataDelegated. removeListDelegate can remove a delegate, and each action emits a HintListDelegateAdded or HintListDelegateRemoved event. This structure lets owners share operational responsibilities without sharing private keys.

List-level revocation and ownership transfer

setListStatus changes the overall validity status of a hint list. Revoking a list can be used to invalidate all hint values within it at once. setListOwner transfers list ownership to another address, but the namespace the list belongs to SHALL NOT change. This is to preserve path references leading all the way to the hint values. Both functions have Signed variants, and status changes emit HintListStatusChanged or HintListOwnerChanged events.

Per-hint metadata

A single hint is identified by the combination of namespace, list, key, and value, and getMetadata and setMetadata can attach bytes-format metadata to that combination. Direct calls by the owner, calls by a delegate (setMetadataDelegated), and EIP-712 signed variants of each are defined. Write functions such as setHint can also implement overloads that accept _metadata, letting the hint value and metadata be recorded in a single call, in which case a separate type hash that includes the metadata is used.

Trust Anchor via ENS

An ecosystem with an ENS domain can announce its own registry through subdomain records. This is optional. Each use-case subdomain MUST record the registry contract address (ADDRESS ETH) and the namespace owner address (TEXT key hint.namespace), while hint.list, hint.key, hint.value TEXT records and the contract ABI are optional. For bidirectional linkage, the namespace owner should set metadata in their own namespace where the hint list and hint key are 0x0 and the hint value is the keccak256 hash of the ENS subdomain. This makes it easier to find and verify the registry by borrowing the domain's trust.

Standard status: Draft

This ERC was created on August 31, 2023, and its current status is Draft. Since it is at a proposal stage and its content may still change, it is advisable to check the latest original text before implementing it. It requires EIP-712.

Things to watch out for

Original ERC · ← ERCs