Abstract

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.

Motivation

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.

Specification

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.

Definitions

  • 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.

Interface

Hint Management

getHint

A method with the following signature MUST be implemented that returns the hint value in a hint list of a namespace.

function getHint(address _namespace, bytes32 _list, bytes32 _key) external view returns (bytes32);
setHint

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.

function setHint(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) public;
setHintSigned

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.

function setHintSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, address _signer, bytes calldata _signature) public;

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.

setHints

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.

function setHints(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values) public;
setHintsSigned

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.

function setHintsSigned(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values, address _signer, bytes calldata _signature) public;

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.

Delegated Hint Management

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.

setHintDelegated

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.

function setHintDelegated(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) public;
setHintDelegatedSigned

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.

function setHintDelegatedSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, address _signer, bytes calldata _signature) public;

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.

setHintsDelegated

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.

function setHintsDelegated(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values) public;
setHintsDelegatedSigned

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.

function setHintsDelegatedSigned(address _namespace, bytes32 _list, bytes32[] calldata _keys, bytes32[] calldata _values, address _signer, bytes calldata _signature) public;

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.

Hint List Management

setListStatus

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.

function setListStatus(address _namespace, bytes32 _list, bool _revoked) public;
setListStatusSigned

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.

function setListStatusSigned(address _namespace, bytes32 _list, bool _revoked, address _signer, bytes calldata _signature) public;

The type hash MUST be the keccak256 hash of SetListStatusSigned(address namespace,bytes32 list,bool revoked,address signer,uint256 nonce) when generating the signature.

setListOwner

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.

function setListOwner(address _namespace, bytes32 _list, address _newOwner) public;
setListOwnerSigned

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.

function setListOwnerSigned(address _namespace, bytes32 _list, address _newOwner, address _signer, bytes calldata _signature) public;

The type hash MUST be the keccak256 hash of SetListOwnerSigned(address namespace,bytes32 list,address newOwner,address signer,uint256 nonce) when generating the signature.

addListDelegate

A method with the following signature MAY be implemented to add a delegate to an owner’s hint list in a namespace.

function addListDelegate(address _namespace, bytes32 _list, address _delegate, uint256 _untilTimestamp) public;
addListDelegateSigned

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.

function addListDelegateSigned(address _namespace, bytes32 _list, address _delegate, uint256 _untilTimestamp, address _signer, bytes calldata _signature) public;

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.

removeListDelegate

A method with the following signature MAY be implemented to remove a delegate from an owner’s hint list in a namespace.

function removeListDelegate(address _namespace, bytes32 _list, address _delegate) public;
removeListDelegateSigned

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.

function removeListDelegateSigned(address _namespace, bytes32 _list, address _delegate, address _signer, bytes calldata _signature) public;

The type hash MUST be the keccak256 hash of RemoveListDelegateSigned(address namespace,bytes32 list,address delegate,address signer,uint256 nonce) when generating the signature.

Metadata Management

getMetadata

A method with the following signature MAY be implemented to retrieve metadata for a hint.

function getMetadata(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value) external view returns (bytes memory);
setMetadata

A method with the following signature MAY be implemented to set metadata for a hint.

function setMetadata(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata) public;
setMetadataSigned

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.

function setMetadataSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata, address _signer, bytes calldata _signature) public;

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.

setMetadataDelegated

A method with the following signature MAY be implemented to set metadata for a hint as a pre-approved delegate of the hint list.

function setMetadataDelegated(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata) public;
setMetadataDelegatedSigned

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.

function setMetadataDelegatedSigned(address _namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _metadata, address _signer, bytes calldata _signature) public;

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.

Events

HintValueChanged

MUST be emitted when a hint value has changed.

event HintValueChanged(
  address indexed namespace,
  bytes32 indexed list,
  bytes32 indexed key,
  bytes32 value
);
HintListOwnerChanged

MUST be emitted when the owner of a list has changed.

event HintListOwnerChanged(
  address indexed namespace,
  bytes32 indexed list,
  address indexed newOwner
);
HintListDelegateAdded

MUST be emitted when a delegate has been added to a hint list.

event HintListDelegateAdded(
  address indexed namespace,
  bytes32 indexed list,
  address indexed newDelegate
);
HintListDelegateRemoved

MUST be emitted when a delegate has been removed from a hint list.

event HintListDelegateRemoved(
  address indexed namespace,
  bytes32 indexed list,
  address indexed oldDelegate
);
HintListStatusChanged

MUST be emitted when the validity status of the hint list has been changed.

event HintListStatusChanged(
  address indexed namespace,
  bytes32 indexed list,
  bool indexed revoked
);

Meta Transactions

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).

Signed Hash

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.

Nonce

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.

Trust Anchor via ENS

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:

  • ADDRESS ETH - address of the trusted hint registry contract
  • TEXT - key: “hint.namespace”; value: owner address of namespace

The following records MAY be set:

  • TEXT - key: “hint.list”; value: bytes32 key of hint list
  • TEXT - key: “hint.key”; value: bytes32 key of hint key
  • TEXT - key: “hint.value”; value: bytes32 key of hint value
  • ABI - ABI of trusted hint registry contract

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.

Rationale

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.

//     namespace          hint list          hint key    hint value
mapping(address => mapping(bytes32 => mapping(bytes32 => bytes32))) hints;

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.

Backwards Compatibility

No backward compatibility issues found.

Security Considerations

Meta Transactions

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.

Rights Management

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.

Governance

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.