Create IHookMetadata #382

RostyslavBortman · 2024-10-22T13:46:01Z

This Pull Request proposes adding a new interface, IHookMetadata, to the Uniswap V4 Periphery repository. The IHookMetadata interface is designed to provide standardized metadata for hooks, which include information about the audit details and additional metadata. By integrating IHookMetadata, we can create a consistent and transparent way to describe hooks, enhancing both the security and the user experience for developers interacting with Uniswap hooks.

The IHookMetadata interface introduces the following key features:

Audit Metadata: Provides comprehensive information regarding audits conducted on the smart contract.
AuditSummary struct: Contains details such as the auditor's name, the issued timestamp, hashes of the code and audit document, and an audit URI.
Auditor struct: Specifies the audit firm's name, additional URI information, and a list of authors involved in the audit.

EIP-712 Domain Information

The EIP712Domain struct is included to describe the domain for which signatures are generated. This is critical for verifying off-chain signed messages, ensuring consistency and integrity across the Uniswap ecosystem.

Signature Standards:

The SignatureType enum defines multiple signature standards supported, including SECP256K1, BLS, ERC1271, and SECP256R1, which allows the flexibility to adopt different signature approaches as needed by various protocols.

Functions for Metadata Retrieval:

The interface provides several functions for easy retrieval of metadata, such as: name, repository, logoURI, and description: Functions that provide basic descriptive information about the hook.

auditSummary, eip712Domain, and signedAuditSummary: Functions that provide crucial audit and signing information.

By adding IHookMetadata, this interface aims to improve trust in the Uniswap ecosystem through more accessible audit data and standardized metadata for hooks. It would ensure a consistent method of obtaining and verifying metadata and signature information for any hooks that integrate with Uniswap V4.

Motivation

Transparency and Trust: Increasing transparency about hook audits and other metadata contributes to improved trust in the Uniswap ecosystem.

Standardization: A standardized interface for audit information reduces friction for developers seeking to integrate their hooks.

Implementation Notes

This interface is defined to be implemented by any hook used within Uniswap, providing a framework for uniform metadata collection.

Adopting IHookMetadata across hooks will help developers better understand, verify, and use hooks while ensuring they meet established standards.

Conclusion

This PR aims to improve the metadata handling, transparency, and security of hooks in Uniswap V4 by integrating IHookMetadata. We believe this will benefit developers, users, and auditors by providing a clear, accessible, and standardized set of metadata for hooks.

Please let me know if there are any questions or further improvements needed for this interface.

This Pull Request proposes adding a new interface, IHookMetadata, to the Uniswap V4 Periphery repository. The IHookMetadata interface is designed to provide standardized metadata for hooks, which include information about the audit details and additional metadata. By integrating IHookMetadata, we can create a consistent and transparent way to describe hooks, enhancing both the security and the user experience for developers interacting with Uniswap hooks. Details The IHookMetadata interface introduces the following key features: Audit Metadata: Provides comprehensive information regarding audits conducted on the smart contract. AuditSummary struct: Contains details such as the auditor's name, the issued timestamp, hashes of the code and audit document, and an audit URI. Auditor struct: Specifies the audit firm's name, additional URI information, and a list of authors involved in the audit. EIP-712 Domain Information: The EIP712Domain struct is included to describe the domain for which signatures are generated. This is critical for verifying off-chain signed messages, ensuring consistency and integrity across the Uniswap ecosystem. Signature Standards: The SignatureType enum defines multiple signature standards supported, including SECP256K1, BLS, ERC1271, and SECP256R1, which allows the flexibility to adopt different signature approaches as needed by various protocols. Functions for Metadata Retrieval: The interface provides several functions for easy retrieval of metadata, such as: name(), repository(), logoURI(), and description(): Functions that provide basic descriptive information about the hook. auditSummary(), eip712Domain(), and signedAuditSummary(): Functions that provide crucial audit and signing information. By adding IHookMetadata, this interface aims to improve trust in the Uniswap ecosystem through more accessible audit data and standardized metadata for hooks. It would ensure a consistent method of obtaining and verifying metadata and signature information for any hooks that integrate with Uniswap V4. Motivation Transparency and Trust: Increasing transparency about hook audits and other metadata contributes to improved trust in the Uniswap ecosystem. Standardization: A standardized interface for audit information reduces friction for developers seeking to integrate their hooks. Security: Leveraging the EIP-712 domain and supporting multiple signature types strengthens the ability to verify transactions and audit reports effectively. Implementation Notes This interface is defined to be implemented by any hook used within Uniswap, providing a framework for uniform metadata collection. Adopting IHookMetadata across hooks will help developers better understand, verify, and use hooks while ensuring they meet established standards. Conclusion This PR aims to improve the metadata handling, transparency, and security of hooks in Uniswap V4 by integrating IHookMetadata. We believe this will benefit developers, users, and auditors by providing a clear, accessible, and standardized set of metadata for hooks. Please let me know if there are any questions or further improvements needed for this interface.

saucepoint · 2024-10-23T00:33:08Z

@RostyslavBortman can you give it a filename hah

hensha256 · 2025-02-05T10:41:50Z

src/interfaces/IHookMetadata.sol

+        Auditor auditor;         // The auditor who performed the audit
+        uint256 issuedAt;        // The timestamp at which the audit was issued
+        uint256[] ercs;          // List of ERC standards that were covered in the audit
+        bytes32 codeHash;        // Hash of the audited smart contract code


i think this should be more specific in the comment - is this the github commit? the bytecode hash? the initcode hash?

hensha256 · 2025-02-05T11:28:45Z

src/interfaces/IHookMetadata.sol

+    }
+
+    // Struct representing the EIP712 domain, which is used for signatures
+    struct EIP712Domain {


is there a reason not to pre-define the eip712 typehash of what the signature should be of?

hensha256 · 2025-02-05T16:52:55Z

src/interfaces/IHookMetadata.sol

+
+    function name() external view returns (string memory); // Returns the name of the hook
+    function repository() external view returns (string memory); // Returns the repository URI for the smart contract code
+    function logoURI() external view returns (string memory); // Returns the URI for the hook's logo


thoughts on adding a field for the hook dev to provide a URL to a website/docs or something about their hook?

src/interfaces/IHookMetadata.sol

hensha256 · 2025-02-11T10:54:19Z

src/interfaces/IHookMetadata.sol

+        Auditor auditor;
+        uint256 issuedAt;
+        uint256[] ercs;
+        bytes32 bytecodeHash;


i do wonder how practical a bytecodeHash is in practice? It changes even you change the optimiser runs, sometimes if you the deploy parameters, and other very small tweaks - and because its not reversible it might become impossible to see what someone actually audited?
If you have a bytecodeHash from an auditor... how are you meant to find the version of the code that they audited?

Just thinking out loud here, it still might be the best option. But just wondering if youve thought this through

So I think we are talking about the next options here:

commit hash - I don't this reasonable because someone can actually change the code during the deployment and you have to read an actual contract code anyway. But would love to hear your opinion;

bytecodeHash - I think we can also ask devs to deploy with some specific params for optimiser, etc, to be able to allow onchain audit verification. As for deploy parameters - I think we can focus only on the code itself without constructor params;

how are you meant to find the version of the code that they audited?

So, I think the regular flow - they have to have a link to the repo on their website, commit hash, etc. But as for the onchain verification I see bytecodeHash as only one possible option

hensha256 · 2025-02-11T10:54:59Z

src/interfaces/IHookMetadata.sol

+    /// @param signatureType The type of the signature (e.g., SECP256K1, BLS, etc.).
+    /// @param data The actual signature data.
+    struct Signature {
+        SignatureType signatureType;


What was the motivation for removing the EIP712 stuff? Happy either way just interested :)

So I think we want to provide more flexibility in terms of what should be inside of hash for the signature since we can't define function eip712Domain specifically in the interface

One of the main benefits of EIP712 domain signatures would be for DeFi protocols to prevent replay attacks on their signed limit orders using the chain id, contract address, etc... as parameters. In this case there is nothing anyone can do with a signed audit payload so it doesn't need that extra security. I do think a domain separator could add some specification around what is being signed here but it's not necessary

Yes, I agree. + we removed it to provide more flexibility actually

fix: IHookMetadata auditSummaries + eip domen

natspec

HookMetadata

HookMetadata moved to utils

calldata changed to memory

Fixed method signature to match others

saucepoint · 2025-03-05T18:31:49Z

src/utils/HookMetadata.sol

+    /// @notice An internal method that registers a new signed audit summury and emits an event that may be useful for
+    ///         external indexing services to discover and display essential information about a Uniswap V4 hook.
+    /// @dev This internal method should be called in the child hook contract whenever new audit summary is registered
+    ///      (for example, in the constructor or in the custom owner/admin/DAO controlled method).
+    /// @param signedAuditSummary A new signed audit summury to register.
+    /// @return A new signed audit summary ID.
+    function _registerAuditSummary(SignedAuditSummary memory signedAuditSummary) internal returns (uint256) {


not sure if I'm in love with the idea of adding an audit after audits, is there a reason why audit information cannot be provided at the time of deployment (via constructor)?

@saucepoint There are a few reasons why we came out with this solution:

a contract may be audited a few times and have a few audit results from different auditors.

we need a bytecodeHash to store it in the contract with the audit results. To obtain a bytecode we need to deploy a contract.

snreynolds · 2025-03-27T02:48:57Z

src/interfaces/IHookMetadata.sol

+ * 1. Required Metadata
+ *    - Every hook must implement: name(), repository(), logoURI(), websiteURI(),
+ *      description(), version().
+ *    - These fields are effectively immutable and indexed at deployment time.


what does "effectively" immutable mean? When can they be changed?

We assume that after deploy they will not be changed

They are not actually changeable in the contracts though no? So I think you can just declare them to be immutable

@snreynolds Unfortunately, it is impossible to declare string variables as immutable in Solidity at this moment.

From the documentation:
Not all types for constants and immutables are implemented at this time. The only supported types are strings (only for constants) and value types.

However, there is one workaround we can implement instead: put all 6 variables in the HookMetadata storage, mark them as private (not immutable, as this is impossible) and allow them to be set up through the constructor only. No setters will be provided, only getters that will allow reading these state variables from outside or child contracts.

What do you think about this approach?

snreynolds · 2025-03-27T02:53:14Z

src/interfaces/IHookMetadata.sol

+ *      emit the AuditSummaryRegistered event for indexers.
+ *
+ * 3. EIP-712 Domain Information
+ *    - The contract must provide an EIP-712 DOMAIN_SEPARATOR to allow auditors


Is there a standard format you'd want to enforce in the DOMAIN_SEPARATOR? Could give a recommendation for which fields should/must be specified. ie Im guessing the verifyingContract is the hook but maybe worth specifying?

We created a template for IHookMetadata usage - uniswapfoundation/v4-template#58, used https://github.com/uniswap/v4-periphery/blob/ea2bf2e1ba6863bb809fc2ff791744f308c4a26d/src/base/EIP712_v4.sol there

snreynolds · 2025-03-27T02:59:32Z

src/utils/HookMetadata.sol

+ *         summaries and their retrivals using internal counting mechanism.
+ */
+abstract contract HookMetadata is IHookMetadata {
+    mapping(uint256 auditId => SignedAuditSummary signedAuditSummary) private signedAuditsSummaries;


Is there a reason to store on chain? If offchain indexing services are already indexing against the registration, whats the reason to also store on chain?

Good question. The primary reason for storing the audit summary on-chain is to ensure immutability and verifiable proof that an audit actually occurred. By storing the audit data, including the auditor’s signature, directly on-chain, we guarantee that nobody can modify the audit content after submission.

While off-chain indexing services can indeed store a copy of the audit, they can't provide the same cryptographic guarantees of immutability. Additionally, by having an on-chain registry of trusted auditor addresses, anyone can verify directly on-chain whether a hook was audited by a trusted auditor or not.

It's important to note that builders aren't forced to submit audits on-chain—it's an optional but recommended approach if verifiable audit proof is desired directly within the onchain environment.

RostyslavBortman added 2 commits October 23, 2024 10:05

Rename IHookMetadata to IHookMetadata.sol

ac79dcf

Update IHookMetadata.sol

c93d4b8

snreynolds requested review from hensha256 and snreynolds December 4, 2024 19:09

saucepoint previously approved these changes Jan 29, 2025

View reviewed changes

hensha256 reviewed Feb 5, 2025

View reviewed changes

metadata: refactor audit summary

ecedc53

AntonGulak dismissed saucepoint’s stale review via ecedc53 February 7, 2025 19:23

hensha256 reviewed Feb 11, 2025

View reviewed changes

AntonGulak and others added 17 commits February 11, 2025 17:06

refactor: IHookMetadata fmt

f8cd75c

fix: IHookMetadata auditSummaries + eip domen

2115888

Merge pull request #1 from RostyslavBortman/patch-2

c57b25b

fix: IHookMetadata auditSummaries + eip domen

natspec

7e78c5c

Merge pull request #2 from RostyslavBortman/natspec

2c91c7b

natspec

Abstract HookMetadata implementation. IEIP7512 moved to a separate file

2a0c75a

Fixed natspecs

53d62fa

Merge pull request #3 from smak0v/patch-1

9b080fb

HookMetadata

Merge branch 'Uniswap:main' into patch-1

da33a30

HookMetadata moved to utils

a27cb9c

Merge pull request #4 from smak0v/patch-1

a5f5003

HookMetadata moved to utils

calldata changed to memory

b371d61

Merge pull request #5 from smak0v/patch-1

3df37ea

calldata changed to memory

Updated repository() method name

0fbc8b4

Merge branch 'RostyslavBortman:patch-1' into patch-1

f941f1e

Fixed fmt issue

67f11d7

Merge pull request #6 from smak0v/patch-1

735033e

Fixed method signature to match others

smak0v mentioned this pull request Mar 5, 2025

Metadata Hook Template uniswapfoundation/v4-template#58

Closed

saucepoint reviewed Mar 5, 2025

View reviewed changes

snreynolds reviewed Mar 27, 2025

View reviewed changes

Create IHookMetadata #382

Are you sure you want to change the base?

Create IHookMetadata #382

Uh oh!

Conversation

RostyslavBortman commented Oct 22, 2024

The IHookMetadata interface introduces the following key features:

EIP-712 Domain Information

Signature Standards:

Functions for Metadata Retrieval:

Motivation

Implementation Notes

Conclusion

Uh oh!

saucepoint commented Oct 23, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smak0v Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smak0v Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

smak0v Mar 5, 2025 •

edited

Loading

smak0v Apr 2, 2025 •

edited

Loading