Merge 9e2defa into 068867b

EIPS/eip-7547.md

@@ -0,0 +1,393 @@
+---
+title: Trusted Hint Registry
+description: Registry of trusted hints for decentralized ecosystems.
+author: Philipp Bolte (@strumswell), Dennis von der Bey (@DennisVonDerBey), Lauritz Leifermann (@lleifermann)
+discussions-to: https://ethereum-magicians.org/t/eip-trusted-hint-registry/15615
+status: Draft
+type: Standards Track
+category: ERC
+created: 2023-08-31
+requires: 712
+---
+
+## Abstract
+
+This ERC proposes the "Trusted Hint Registry," a standardized on-chain metadata management interface. It addresses the
+critical need for trust establishment in decentralized ecosystems, enabling entities to efficiently manage hints that
+bolster claim integrity and verifiability. The addition of various management features around delegation, ownership, and
+meta transactions aim to create an adaptable registry for various use cases and requirements within decentralized
+ecosystems.This ERC proposes the "Trusted Hint Registry," a standardized on-chain metadata management interface. It
+addresses the critical need for trust establishment in decentralized ecosystems, enabling entities to efficiently manage
+hints that bolster claim integrity and verifiability. The addition of various management features around delegation,
+ownership, and meta transactions aim to create an adaptable registry for various use cases and requirements within
+decentralized ecosystems.
+
+## 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 these are in need of technologies building trust in their realm. Real world applications
+have show 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 these claim metadata on-chain poses a significant hurdle to the
+formation and sustainment 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", "NOT
+RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
+
+### Definitions
+
+- `claim`: A claim is a statement about an entity made by another entity.
+- `hint`: A hint is a metadata snippet that describes key attributes related to verifiable data or identities. These
+  hints provide insights, aiding in the interpretation, reliability, and 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.
+
+```solidity
+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.
+
+```solidity
+function setHint(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.
+
+```solidity
+function setHintSigned(address namespace, bytes32 _list, bytes32 _key, bytes32 _value, bytes calldata _signature) public;
+```
+
+##### setHints
+
+A method with the following signature **MUST** be implemented that changes multiple hint values in a hint list of a
+namespace.
+
+```solidity
+function setHints(bytes32 _list, bytes32 _key, 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.
+
+```solidity
+function setHintsSigned(address namespace, bytes32 _list, bytes32 _key, bytes32[] calldata _values, bytes calldata _signature) public;
+```
+
+#### 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.
+
+```solidity
+function setHintDelegated(address namespace, bytes32 calldata _entry, bool _isTrusted) 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.
+
+```solidity
+function setHintDelegatedSigned(address namespace, bytes32 calldata _entry, bool _isTrusted, bytes calldata _signature) public;
+```
+
+##### 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.
+
+```solidity
+function setHintsDelegated(address namespace, bytes32 _list, bytes32 _key, 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.
+
+```solidity
+function setHintsDelegatedSigned(address namespace, bytes32 _list, bytes32 _key, bytes32[] calldata _values, bytes calldata _signature) public;
+```
+
+#### Hint List Management
+
+##### setListStatus
+
+A method with the following signature **MAY** be implemented that changes the validity state of a hint list. This
+enables one to (un)-revoke a whole list of hint values.
+
+```solidity
+function setListStatus(bytes32 _list, bytes32 _key, 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. This enables one to (un)-revoke a whole list of hint values.
+
+```solidity
+function setListStatusSigned(bytes32 _list, bytes32 _key, bool _revoked, bytes calldata _signature) public;
+```
+
+##### 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.
+
+```solidity
+function setListOwner(bytes32 _list, bytes32 _key, 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.
+
+```solidity
+function setListOwnerSigned(bytes32 _list, bytes32 _key, address _newOwner, bytes calldata _signature) public;
+```
+
+##### addListDelegate
+
+A method with the following signature **MAY** be implemented to add a delegate to an owner’s hint list in a namespace.
+
+```solidity
+function addListDelegate(address _namespace, bytes32 _list, address _delegate) 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.
+
+```solidity
+function addListDelegateSigned(address _namespace, bytes32 _list, address _delegate, bytes calldata _signature) public;
+```
+
+##### removeListDelegate
+
+A method with the following signature **MAY** be implemented to remove a delegate from an owner’s revocation hint list
+in a namespace.
+
+```solidity
+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 revocation hint list
+in a namespace with a raw signature. The raw signature **MUST** be generated following the Meta Transactions section.
+
+```solidity
+function removeListDelegateSigned(address _namespace, bytes32 _list, address _delegate, bytes calldata _signature) public;
+```
+
+****
+
+#### Events
+
+##### HintValueChanged
+
+**MUST** be emitted when a hint value has changed.
+
+```solidity
+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.
+
+```solidity
+event HintListOwnerChanged(
+address indexed namespace,
+bytes32 indexed list,
+bytes32 indexed newOwner
+);
+```
+
+##### HintListDelegateAdded
+
+**MUST** be emitted when a delegate has been added to a hint list.
+
+```solidity
+event HintListDelegateAdded(
+address indexed namespace,
+bytes32 indexed list,
+bytes32 indexed newDelegate
+);
+```
+
+##### HintListDelegateRemoved
+
+**MUST** be emitted when a delegate has been removed from a hint list.
+
+```solidity
+event HintListDelegateRemoved(
+address indexed namespace,
+bytes32 indexed list,
+bytes32 indexed oldDelegate
+);
+```
+
+##### HintListStatusChanged
+
+**MUST** be emitted when the validity status of the hint list has been changed.
+
+### 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
+  wrapped 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](./eip-712.md). 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 this **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 reliable hint registry contract, 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 ENS subdomain **SHALL** be created only used for a specific hint list, e.g.,
+“trusted-issuers.ens.eth”. The following records **SHALL** be set:
+
+- ADDRESS ETH - address of the trusted hint registry contract
+- TEXT - key: “hint.namespace”; value: owner address of namespace
+- TEXT - key: “hint.list”; value: bytes32 key of hint list
+
+The following records **MAY** be set:
+
+- ABI - ABI of trusted hint registry contract
+
+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.
+
+```solidity
+//     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](./eip-712.md) 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](./eip-712.md)
+
+### 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
+
+Copyright and related rights waived via [CC0](../LICENSE.md).