This EIP standardizes a system for managing on-chain metadata (hints), enabling claim interpretation, reliability, and verification. It structures these hints within defined namespaces and lists, enabling structured organization and retrieval, as well as permissioned write access. The system permits namespace owners to delegate hint management tasks, enhancing operational flexibility. It incorporates secure meta transactions via EIP-712-enabled signatures and offers optional ENS integration for trust verification and discoverability. The interface is equipped to emit specific events for activities like hint modifications, facilitating easy traceability of changes to hints. This setup aims to provide a robust, standardized framework for managing claim- and ecosystem-related metadata, essential for maintaining integrity and trustworthiness in decentralized environments.
In an increasingly interconnected and decentralized landscape, the formation of trust among entities remains a critical concern. Ecosystems, both on-chain and off-chain—spanning across businesses, social initiatives, and other organized frameworks—frequently issue claims for or about entities within their networks. These claims serve as the foundational elements of trust, facilitating interactions and transactions in environments that are essentially untrustworthy by nature. While the decentralization movement has brought about significant improvements around trustless technologies, many ecosystems building on top of these are in need of technologies that build trust in their realm. Real-world applications have shown that verifiable claims alone are not enough for this purpose. Moreover, a supporting layer of on-chain metadata is needed to support a reliable exchange and verification of those claims.
The absence of a structured mechanism to manage claim metadata on-chain poses a significant hurdle to the formation and maintenance of trust among participating entities in an ecosystem. This necessitates the introduction of a layer of on-chain metadata, which can assist in the reliable verification and interpretation of these claims. Termed "hints" in this specification, this metadata can be used in numerous ways, each serving to bolster the integrity and reliability of the ecosystem's claims. Hints can perform various tasks, such as providing revocation details, identifying trusted issuers, or offering timestamping hashes. These are just a few examples that enable ecosystems to validate and authenticate claims, as well as verify data integrity over time.
The proposed "Trusted Hint Registry" aims to provide a robust, flexible, and standardized interface for managing such hints. The registry allows any address to manage multiple lists of hints, with a set of features that not only make it easier to create and manage these hints but also offer the flexibility of delegating these capabilities to trusted entities. In practice, this turns the hint lists into dynamic tools adaptable to varying requirements and use cases. Moreover, an interface has been designed with a keen focus on interoperability, taking into consideration existing W3C specifications around Decentralized Identifiers and Verifiable Credentials, as well as aligning with on-chain projects like the Ethereum Attestation Service.
By providing a standardized smart contract interface for hint management, this specification plays an integral role in enabling and scaling trust in decentralized ecosystems. It offers a foundational layer upon which claims — both on-chain and off-chain — can be reliably issued, verified, and interpreted, thus serving as an essential building block for the credible operation of any decentralized ecosystem. Therefore, the Trusted Hint Registry is not just an addition to the ecosystem but a necessary evolution in the complex topology of decentralized trust.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
This EIP specifies a contract called TrustedHintRegistry and standardizes a set of REQUIRED core hint functions,
while also providing a common set of OPTIONAL management functions, enabling various ways for collaborative hint
management. Ecosystems MAY use this specification to build their own hint registry contracts with ecosystem-specific,
non-standardized features. Governance is deliberately excluded from this ERC and MAY be implemented according to an
ecosystem's need.
claim: A claim is a statement about an entity made by another entity.hint: A "hint" refers to a small piece of information that provides insights, aiding in the interpretation,
reliability, or verifiability of decentralized ecosystem data.namespace: A namespace is a representation of an Ethereum address inside the registry that corresponds to its
owner’s address. A namespace contains hint lists for different use cases.hint list: A hint list is identified by a unique value that contains a number of hint keys that resolve to hint
values. An example of this is a revocation key that resolves to a revocation state.hint key: A hint key is a unique value that resolves to a hint value. An example of this is a trusted issuer
identifier, which resolves to the trust status of that identifier.hint value: A hint value expresses data about an entity in an ecosystem.delegate: An Ethereum address that has been granted writing permissions to a hint list by its owner.A method with the following signature MUST be implemented that returns the hint value in a hint list of a namespace.
A method with the following signature MUST be implemented that changes the hint value in a hint list of a namespace.
An overloaded method with an additional bytes calldata _metadata parameter MAY be implemented to set metadata
together with the hint value.
A method with the following signature MAY be implemented that changes the hint value in a hint list of a namespace
with a raw signature. The raw signature MUST be generated following the Meta Transactions section. An overloaded
method with an additional bytes calldata _metadata parameter MAY be implemented to set metadata together with the
hint value.
The type hash MUST be the keccak256 hash of SetHintSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,address signer,uint256 nonce)
or SetHintSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)
when calling the metadata variant.
A method with the following signature MUST be implemented that changes multiple hint values in a hint list of a
namespace. An overloaded method with an additional bytes[] calldata _metadata parameter MAY be implemented to set
metadata together with the hint value.
A method with the following signature MUST be implemented that multiple hint values in a hint list of a namespace
with a raw signature. The raw signature MUST be generated following the Meta Transactions section. An overloaded
method with an additional bytes[] calldata _metadata parameter MAY be implemented to set metadata together with the
hint value.
The type hash MUST be the keccak256 hash of SetHintsSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,address signer,uint256 nonce)
or SetHintsSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,bytes[] metadata,address signer,uint256 nonce)
when calling the metadata variant.
A namespace owner can add delegate addresses to specific hint lists in their namespace. These delegates SHALL have write access to the specific lists via a specific set of methods.
A method with the following signature MAY be implemented that changes the hint value in a hint list of a namespace
for pre-approved delegates. An overloaded method with an additional bytes calldata _metadata parameter MAY be
implemented to set metadata together with the hint value.
A method with the following signature MAY be implemented that changes the hint value in a hint list of a namespace
for pre-approved delegates with a raw signature. The raw signature MUST be generated following the Meta Transactions
section. An overloaded method with an additional bytes calldata _metadata parameter MAY be implemented to set
metadata together with the hint value.
The type hash MUST be the keccak256 hash of SetHintDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,address signer,uint256 nonce)
or SetHintDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)
when calling the metadata variant.
A method with the following signature MAY be implemented that changes multiple hint values in a hint list of a
namespace for pre-approved delegates. An overloaded method with an additional bytes[] calldata _metadata parameter
MAY be implemented to set metadata together with the hint value.
A method with the following signature MAY be implemented that has multiple hint values in a hint list of a namespace
for pre-approved delegates with a raw signature. The raw signature MUST be generated following the Meta Transactions
section. An overloaded method with an additional bytes[] calldata _metadata parameter MAY be implemented to set
metadata together with the hint value.
The type hash MUST be the keccak256 hash of SetHintsDelegatedSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,address signer,uint256 nonce)
or SetHintsDelegatedSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,bytes[] metadata,address signer,uint256 nonce)
when calling the metadata variant.
A method with the following signature MAY be implemented that changes the validity state of a hint list. Revoking a list CAN be used to invalidate all hint values in a list.
A method with the following signature MAY be implemented that changes the validity state of a hint list with a raw signature. Revoking a list CAN be used to invalidate all hint values in a list.
The type hash MUST be the keccak256 hash of SetListStatusSigned(address namespace,bytes32 list,bool revoked,address signer,uint256 nonce)
when generating the signature.
A method with the following signature MAY be implemented that transfers the ownership of a trust list to another address. Changing the owner of a list SHALL NOT change the namespace the hint list resides in, to retain references of paths to a hint value.
A method with the following signature MAY be implemented that transfers the ownership of a trust list to another address with a raw signature. The raw signature MUST be generated following the Meta Transactions section. Changing the owner of a list SHALL NOT change the namespace the hint list resides in, to retain references to paths to a hint value.
The type hash MUST be the keccak256 hash of SetListOwnerSigned(address namespace,bytes32 list,address newOwner,address signer,uint256 nonce)
when generating the signature.
A method with the following signature MAY be implemented to add a delegate to an owner’s hint list in a namespace.
A method with the following signature MAY be implemented to add a delegate to an owner’s hint list in a namespace with a raw signature. The raw signature MUST be generated following the Meta Transactions section.
The type hash MUST be the keccak256 hash of AddListDelegateSigned(address namespace,bytes32 list,address delegate,uint256 untilTimestamp,address signer,uint256 nonce)
when generating the signature.
A method with the following signature MAY be implemented to remove a delegate from an owner’s hint list in a namespace.
A method with the following signature MAY be implemented to remove a delegate from an owner’s hint list in a namespace with a raw signature. The raw signature MUST be generated following the Meta Transactions section.
The type hash MUST be the keccak256 hash of RemoveListDelegateSigned(address namespace,bytes32 list,address delegate,address signer,uint256 nonce)
when generating the signature.
A method with the following signature MAY be implemented to retrieve metadata for a hint.
A method with the following signature MAY be implemented to set metadata for a hint.
A method with the following signature MAY be implemented to set metadata for a hint with a raw signature. The raw signature MUST be generated following the Meta Transactions section.
The type hash MUST be the keccak256 hash of SetMetadataSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)
when generating the signature.
A method with the following signature MAY be implemented to set metadata for a hint as a pre-approved delegate of the hint list.
A method with the following signature MAY be implemented to set metadata for a hint as a pre-approved delegate of the hint list with a raw signature. The raw signature MUST be generated following the Meta Transactions section.
The type hash MUST be the keccak256 hash of SetMetadataDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)
when generating the signature.
MUST be emitted when a hint value has changed.
MUST be emitted when the owner of a list has changed.
MUST be emitted when a delegate has been added to a hint list.
MUST be emitted when a delegate has been removed from a hint list.
MUST be emitted when the validity status of the hint list has been changed.
This section uses the following terms:
transaction signer: An Ethereum address that signs arbitrary data for the contract to execute BUT does not
commit the transaction.transaction sender: An Ethereum address that takes signed data from a transaction signer and commits it
as part of the method call in a transaction to the smart contract.A transaction signer MAY be able to deliver a signed payload off-band to a transaction sender that initiates the Ethereum interaction with the smart contract. The signed payload MUST be limited to being used only once (see Signed Hash and Nonce).
The signature of the transaction signer MUST conform to EIP-712. This helps users understand what the payload they are signing consists of, and it provides protection against replay attacks.
This EIP RECOMMENDS the use of a dedicated nonce mapping for meta transactions. If the signature of the transaction sender and its meta-contents are verified, the contract increases a nonce for the transaction signer. This effectively removes the possibility for any other sender to execute the same transaction again with another wallet.
Ecosystems that use an Ethereum Name Service (ENS) domain can increase trust by using ENS entries to share information about a hint list registry. This method takes advantage of the ENS domain's established credibility to make it easier to find a hint registry contract of the domain's entity, as well as the appropriate namespace and hint list customized for particular ecosystem needs. Implementing a trust anchor through ENS is OPTIONAL.
For each use case, a specific or set of ENS subdomain SHALL be created. Each subdomain should be treated as an atomic entity for a singular set of namespace-list-key-value TEXT records. The following records SHALL be set:
The following records MAY be set:
To create a two-way connection, a namespace owner SHALL set metadata referencing the complete ENS subdomain hash.
Metadata SHALL be set in the owners namespace with a hint list and hint key value of 0x0 where the hint value is
the ENS subdomain keccak256 hash.
By establishing this connection, a robust foundation for trust and discovery within an ecosystem is created.
Examining the method signatures reveals a deliberate architecture and data hierarchy within this ERC: A namespace address maps to a hint list, which in turn maps to a hint key, which then reveals the hint value.
This structure is designed to implicitly establish the initial ownership of all lists under a given namespace, eliminating the need for subsequent claiming actions. As a result, it simplifies the process of verifying and enforcing write permissions, thereby reducing potential attack surfaces. Additional data structures must be established and validated for features like delegate management and ownership transfer of hint lists. These structures won't affect the main namespace layout; rather, they serve as a secondary mechanism for permission checks.
One of the primary objectives of this ERC is to include management features, as these significantly influence the ease of collaboration and maintainability of hint lists. These features also enable platforms to hide complexities while offering user-friendly interfaces. Specifically, the use of meta-transactions allows users to maintain control over their private keys while outsourcing the technical heavy lifting to platforms, which is achieved simply by signing an EIP-712 payload.
No backward compatibility issues found.
The signature of signed transactions could potentially be replayed on different chains or deployed versions of the registry implementing this ERC. This security consideration is addressed by the usage of EIP-712.
The different roles and their inherent permissions are meant to prevent changes from unauthorized entities. The hint list owner should always be in complete control over its hint list and who has writing access to it.
It is recognized that ecosystems might have processes in place that might also apply to changes in hint lists. This ERC explicitly leaves room for implementers or users of the registry to apply a process that fits the requirements of their ecosystem. Possible solutions can be an extension of the contract with governance features around specific methods, the usage of multi-sig wallets, or off-chain processes enforced by an entity.
Copyright and related rights waived via CC0.