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
function getHint(address _namespace, bytes32 _list, bytes32 _key) external view returns (bytes32);: Looks up the hint value for a key in a namespace's hint list. Required implementation.function setHint(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) public;: Changes a hint value in a namespace's hint list. Required implementation.function setHintSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature created by the signer and lets another address change the hint value on their behalf.function setHints(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values) public;: Changes multiple hint values in a list at once. Required implementation.function setHintsSigned(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and changes multiple hint values on the signer's behalf at once. Required implementation.function setHintDelegated(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) public;: A pre-approved delegate changes a hint value.function setHintDelegatedSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, address _signer, bytes calldata _signature) public;: Takes the delegate's EIP-712 signature and lets another address change the hint value on their behalf.function setHintsDelegated(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values) public;: A delegate changes multiple hint values at once.function setHintsDelegatedSigned(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values, address _signer, bytes calldata _signature) public;: Takes the delegate's EIP-712 signature and changes multiple hint values on their behalf at once.function setListStatus(address _namespace, bytes32 _list, bool _revoked) public;: Changes the validity status of a hint list. Revoking a list can be used to invalidate every hint value within it.function setListStatusSigned(address _namespace, bytes32 _list, bool _revoked, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and changes the list's validity status on the signer's behalf.function setListOwner(address _namespace, bytes32 _list, address _newOwner) public;: Transfers ownership of a hint list to another address. The namespace the list belongs to does not change.function setListOwnerSigned(address _namespace, bytes32 _list, address _newOwner, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and transfers list ownership on the signer's behalf.function addListDelegate(address _namespace, bytes32 _list, address _delegate, uint256 _untilTimestamp) public;: Adds a delegate to a hint list, valid until a specified time.function addListDelegateSigned(address _namespace, bytes32 _list, address _delegate, uint256 _untilTimestamp, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and adds a delegate on the signer's behalf.function removeListDelegate(address _namespace, bytes32 _list, address _delegate) public;: Removes a delegate from a hint list.function removeListDelegateSigned(address _namespace, bytes32 _list, address _delegate, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and removes a delegate on the signer's behalf.function getMetadata(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) external view returns (bytes memory);: Looks up metadata attached to a specific hint.function setMetadata(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata) public;: Records metadata on a specific hint.function setMetadataSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata, address _signer, bytes calldata _signature) public;: Takes an EIP-712 signature and records metadata on the signer's behalf.function setMetadataDelegated(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata) public;: A pre-approved delegate records metadata for a hint.function setMetadataDelegatedSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata, address _signer, bytes calldata _signature) public;: Takes the delegate's EIP-712 signature and records metadata on their behalf.
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
- Signature replay risk: A signed meta transaction could potentially be reused on a different chain or in a different deployment implementing this ERC. The original text states that the use of EIP-712 addresses this issue.
- Permission management: Role-based permissions exist to prevent unauthorized parties from making changes. A hint list owner should always have full control over their own list and its write permissions.
- Governance is each ecosystem's responsibility: Some ecosystems may need separate procedures for changing hint lists. This ERC does not define governance and can be adapted to each ecosystem's requirements through extensions that add governance functionality to specific functions, multisig wallets, off-chain procedures, and the like.