feat: implement reputation registry system with feedback functionality (#4507)

### Description

This PR introduces a new Reputation Registry system for agent feedback management. The system allows clients to provide ratings and feedback for agents, with support for tagging, revocation, and responses to feedback.

### Changes

- Removed unused `_verifyStake()` function from `IdentityRegistryFacet.sol`
- Added new `IReputationRegistry.sol` interface defining the reputation system contract methods
- Implemented `ReputationRegistryBase.sol` with core reputation functionality:
  - Feedback submission with ratings and tags
  - Feedback revocation
  - Response management for feedback
  - Comprehensive query methods for feedback data
- Created `ReputationRegistryFacet.sol` that implements the interface and extends the base functionality
- Added `ReputationRegistryStorage.sol` for managing the reputation system's persistent state

### Checklist

- [ ] Tests added where required
- [ ] Documentation updated where applicable
- [ ] Changes adhere to the repository's contribution guidelines

Author: giuseppecrj

packages/contracts/scripts/deployments/diamonds/DeployAppRegistry.s.sol

@@ -18,6 +18,7 @@ import {DeployAppFactoryFacet} from "../facets/DeployAppFactoryFacet.s.sol";
 import {DeploySpaceFactory} from "../diamonds/DeploySpaceFactory.s.sol";
 import {DeploySimpleAppBeacon} from "../diamonds/DeploySimpleAppBeacon.s.sol";
 import {DeployIdentityRegistry} from "../facets/DeployIdentityRegistry.s.sol";
+import {DeployReputationRegistry} from "../facets/DeployReputationRegistry.s.sol";
 
 // contracts
 import {Diamond} from "@towns-protocol/diamond/src/Diamond.sol";
@@ -37,6 +38,11 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
     DeploySimpleAppBeacon private deploySimpleAppBeacon = new DeploySimpleAppBeacon();
 
     string internal constant APP_REGISTRY_SCHEMA = "address app, address client";
+    string internal constant FEEDBACK_SCHEMA =
+        "uint256 agentId, uint8 score, bytes32 tag1, bytes32 tag2, string feedbackUri, bytes32 feedbackHash";
+    string internal constant RESPONSE_SCHEMA =
+        "uint256 agentId, address reviewerAddress, uint64 feedbackIndex, string responseUri, bytes32 responseHash";
+
     address internal spaceFactory;
     address internal simpleAppBeacon;
 
@@ -103,6 +109,7 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("AppInstallerFacet");
         facetHelper.add("AppFactoryFacet");
         facetHelper.add("IdentityRegistryFacet");
+        facetHelper.add("ReputationRegistryFacet");
 
         facetHelper.deployBatch(deployer);
 
@@ -140,6 +147,13 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
             DeployIdentityRegistry.makeInitData()
         );
 
+        facet = facetHelper.getDeployedAddress("ReputationRegistryFacet");
+        addFacet(
+            makeCut(facet, FacetCutAction.Add, DeployReputationRegistry.selectors()),
+            facet,
+            DeployReputationRegistry.makeInitData(FEEDBACK_SCHEMA, RESPONSE_SCHEMA)
+        );
+
         address multiInit = facetHelper.getDeployedAddress("MultiInit");
 
         return

packages/contracts/scripts/deployments/facets/DeployReputationRegistry.s.sol

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IDiamond} from "@towns-protocol/diamond/src/IDiamond.sol";
+
+// libraries
+import {LibDeploy} from "@towns-protocol/diamond/src/utils/LibDeploy.sol";
+import {DynamicArrayLib} from "solady/utils/DynamicArrayLib.sol";
+
+// contracts
+import {ReputationRegistryFacet} from "src/apps/facets/reputation/ReputationRegistryFacet.sol";
+
+library DeployReputationRegistry {
+    using DynamicArrayLib for DynamicArrayLib.DynamicArray;
+
+    function selectors() internal pure returns (bytes4[] memory res) {
+        uint256 selectorsCount = 10;
+        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(selectorsCount);
+        arr.p(ReputationRegistryFacet.giveFeedback.selector);
+        arr.p(ReputationRegistryFacet.revokeFeedback.selector);
+        arr.p(ReputationRegistryFacet.appendResponse.selector);
+        arr.p(ReputationRegistryFacet.getIdentityRegistry.selector);
+        arr.p(ReputationRegistryFacet.getSummary.selector);
+        arr.p(ReputationRegistryFacet.readFeedback.selector);
+        arr.p(ReputationRegistryFacet.readAllFeedback.selector);
+        arr.p(ReputationRegistryFacet.getResponseCount.selector);
+        arr.p(ReputationRegistryFacet.getClients.selector);
+        arr.p(ReputationRegistryFacet.getLastIndex.selector);
+
+        bytes32[] memory selectors_ = arr.asBytes32Array();
+
+        assembly ("memory-safe") {
+            res := selectors_
+        }
+    }
+
+    function makeCut(
+        address facetAddress,
+        IDiamond.FacetCutAction action
+    ) internal pure returns (IDiamond.FacetCut memory) {
+        return
+            IDiamond.FacetCut({
+                action: action,
+                facetAddress: facetAddress,
+                functionSelectors: selectors()
+            });
+    }
+
+    function makeInitData(
+        string memory feedbackSchema,
+        string memory responseSchema
+    ) internal pure returns (bytes memory) {
+        return
+            abi.encodeCall(
+                ReputationRegistryFacet.__ReputationRegistry_init,
+                (feedbackSchema, responseSchema)
+            );
+    }
+
+    function deploy() internal returns (address) {
+        return LibDeploy.deployCode("ReputationRegistryFacet.sol", "");
+    }
+}

packages/contracts/src/apps/facets/identity/IIdentityRegistry.sol

@@ -59,6 +59,9 @@ interface IIdentityRegistryBase {
 
     /// @notice Thrown when attempting to promote or register an agent that already has a promoted identity
     error IdentityRegistry__AgentAlreadyPromoted();
+
+    /// @notice Thrown when attempting to register an agent with too many metadata entries
+    error IdentityRegistry__TooManyMetadataEntries();
 }
 
 /// @title IIdentityRegistry

packages/contracts/src/apps/facets/identity/IdentityRegistryFacet.sol

@@ -21,6 +21,8 @@ contract IdentityRegistryFacet is
 {
     using CustomRevert for bytes4;
 
+    uint256 internal constant MAX_METADATA_ENTRIES = 10;
+
     function __IdentityRegistryFacet_init() external onlyInitializing {
         __IdentityRegistryFacet_init_unchained();
         __ERC721A_init_unchained("Towns Bot Agent", "TBA");
@@ -52,15 +54,17 @@ contract IdentityRegistryFacet is
         string calldata agentUri,
         MetadataEntry[] calldata metadata
     ) external returns (uint256 agentId) {
+        _verifyMetadataLength(metadata);
         _verifyAgent();
         agentId = _nextTokenId();
         _mint(msg.sender, 1);
         _setAgentUri(agentId, agentUri);
-        emit Registered(agentId, agentUri, msg.sender);
 
         for (uint256 i; i < metadata.length; ++i) {
             _setMetadata(agentId, metadata[i].metadataKey, metadata[i].metadataValue);
         }
+
+        emit Registered(agentId, agentUri, msg.sender);
     }
 
     /// @inheritdoc IIdentityRegistry
@@ -100,6 +104,12 @@ contract IdentityRegistryFacet is
     /*                      INTERNAL FUNCTIONS                    */
     /*.•°:°.´+˚.*°.˚:*.´•*.+°.•°:´*.´•*.•°.•°:°.´:•˚°.*°.˚:*.´+°.•*/
 
+    function _verifyMetadataLength(MetadataEntry[] calldata metadata) internal pure {
+        uint256 metadataLength = metadata.length;
+        if (metadataLength > MAX_METADATA_ENTRIES)
+            IdentityRegistry__TooManyMetadataEntries.selector.revertWith();
+    }
+
     function _verifyAgent() internal view {
         if (_balanceOf(msg.sender) > 0)
             IdentityRegistry__AgentAlreadyPromoted.selector.revertWith();

packages/contracts/src/apps/facets/reputation/IReputationRegistry.sol

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+
+/// @title Reputation Registry Base - ERC-8004 Data Structures
+/// @notice Core data structures and events for the ERC-8004 reputation system
+interface IReputationRegistryBase {
+    struct Feedback {
+        uint8 rating;
+        bytes32 tag1;
+        bytes32 tag2;
+    }
+
+    struct FeedbackAuth {
+        uint256 agentId;
+        address reviewerAddress;
+        uint64 indexLimit;
+        uint256 expiry;
+        uint256 chainId;
+        address identityRegistry;
+        address signerAddress;
+    }
+
+    event NewFeedback(
+        uint256 indexed agentId,
+        address indexed reviewerAddress,
+        uint8 score,
+        bytes32 indexed tag1,
+        bytes32 tag2,
+        string feedbackUri,
+        bytes32 feedbackHash
+    );
+
+    event FeedbackRevoked(
+        uint256 indexed agentId,
+        address indexed reviewerAddress,
+        uint64 indexed feedbackIndex
+    );
+
+    event ResponseAppended(
+        uint256 indexed agentId,
+        address indexed reviewerAddress,
+        uint64 feedbackIndex,
+        address indexed responder,
+        string responseUri,
+        bytes32 responseHash
+    );
+}
+
+/// @title Reputation Registry - ERC-8004 Implementation
+/// @notice A reputation system for AI agents enabling feedback collection, scoring, and trust establishment
+/// @dev This contract implements the ERC-8004 Reputation Registry specification, which enables
+///      discovering and trusting agents across organizational boundaries through reputation signals.
+interface IReputationRegistry is IReputationRegistryBase {
+    /// @notice Returns the address of the identity registry where agents are registered as NFTs
+    /// @dev The identity registry is an ERC-721 contract where each agent has a unique token ID.
+    ///      This registry links reputation data to agent identities defined in the ERC-8004 Identity Registry.
+    /// @return The address of the identity registry contract
+    function getIdentityRegistry() external view returns (address);
+
+    /// @notice Posts feedback for an agent after completing a task or interaction
+    /// @param agentId The NFT token ID of the agent being reviewed
+    /// @param score The rating from 0 (worst) to 100 (best)
+    /// @param tag1 First tag for categorization and filtering (use bytes32(0) for none)
+    /// @param tag2 Second tag for categorization and filtering (use bytes32(0) for none)
+    /// @param feedbackUri URI pointing to detailed off-chain feedback data (IPFS recommended)
+    /// @param feedbackHash KECCAK-256 hash of off-chain data for integrity verification
+    function giveFeedback(
+        uint256 agentId,
+        uint8 score,
+        bytes32 tag1,
+        bytes32 tag2,
+        string calldata feedbackUri,
+        bytes32 feedbackHash
+    ) external;
+
+    /// @notice Revokes previously submitted feedback
+    /// @dev Only the original reviewer can revoke their feedback. Revoked feedback is excluded
+    ///      from getSummary() calculations but remains visible in readAllFeedback() with the
+    ///      revoked status flag. This maintains audit trail integrity per ERC-8004 principles.
+    /// @param agentId The NFT token ID of the agent
+    /// @param feedbackIndex The 1-based index of the feedback to revoke (must be > 0)
+    function revokeFeedback(uint256 agentId, uint64 feedbackIndex) external;
+
+    /// @notice Appends a response to existing feedback
+    /// @param agentId The NFT token ID of the agent
+    /// @param reviewerAddress The address that gave the original feedback
+    /// @param feedbackIndex The 1-based index of the feedback being responded to
+    /// @param responseUri URI pointing to the response content (IPFS recommended)
+    /// @param responseHash KECCAK-256 hash of response data for integrity verification
+    function appendResponse(
+        uint256 agentId,
+        address reviewerAddress,
+        uint64 feedbackIndex,
+        string calldata responseUri,
+        bytes32 responseHash
+    ) external;
+
+    /// @notice Retrieves aggregated reputation statistics for an agent with optional filtering
+    /// @param agentId The NFT token ID of the agent
+    /// @param clientAddresses Optional filter for specific reviewers (empty = all reviewers)
+    /// @param tag1 Optional filter for first tag (bytes32(0) = no filter)
+    /// @param tag2 Optional filter for second tag (bytes32(0) = no filter)
+    /// @return count Number of matching feedback entries (excludes revoked)
+    /// @return averageScore Mean score 0-100 (returns 0 if no feedback matches)
+    function getSummary(
+        uint256 agentId,
+        address[] calldata clientAddresses,
+        bytes32 tag1,
+        bytes32 tag2
+    ) external view returns (uint64 count, uint8 averageScore);
+
+    /// @notice Reads a specific feedback entry by agent, reviewer, and index
+    /// @param agentId The NFT token ID of the agent
+    /// @param reviewerAddress The address that gave the feedback
+    /// @param index The 1-based feedback index (must be > 0 and <= lastIndex)
+    /// @return score The rating from 0 to 100
+    /// @return tag1 The first categorization tag
+    /// @return tag2 The second categorization tag
+    /// @return isRevoked True if feedback has been revoked, false otherwise
+    function readFeedback(
+        uint256 agentId,
+        address reviewerAddress,
+        uint64 index
+    ) external view returns (uint8 score, bytes32 tag1, bytes32 tag2, bool isRevoked);
+
+    /// @notice Reads all feedback for an agent with flexible filtering options
+    /// @param agentId The NFT token ID of the agent
+    /// @param clientAddresses Optional filter for specific reviewers (empty = all reviewers)
+    /// @param tag1 Optional filter for first tag (bytes32(0) = no filter)
+    /// @param tag2 Optional filter for second tag (bytes32(0) = no filter)
+    /// @param includeRevoked Whether to include revoked feedback in results
+    /// @return clients Array of reviewer addresses (one per feedback entry)
+    /// @return scores Array of ratings 0-100 (parallel to clients array)
+    /// @return tag1s Array of first tags (parallel to clients array)
+    /// @return tag2s Array of second tags (parallel to clients array)
+    /// @return revokedStatuses Array of revocation flags (parallel to clients array)
+    function readAllFeedback(
+        uint256 agentId,
+        address[] calldata clientAddresses,
+        bytes32 tag1,
+        bytes32 tag2,
+        bool includeRevoked
+    )
+        external
+        view
+        returns (
+            address[] memory clients,
+            uint8[] memory scores,
+            bytes32[] memory tag1s,
+            bytes32[] memory tag2s,
+            bool[] memory revokedStatuses
+        );
+
+    /// @notice Gets the total count of responses with flexible filtering
+    /// @param agentId The NFT token ID of the agent
+    /// @param reviewerAddress Filter by reviewer (address(0) = all reviewers)
+    /// @param feedbackIndex Filter by specific feedback index (0 = all feedback)
+    /// @param responders Filter by specific responders (empty = all responders)
+    /// @return Total count of responses matching the filter criteria
+    function getResponseCount(
+        uint256 agentId,
+        address reviewerAddress,
+        uint64 feedbackIndex,
+        address[] calldata responders
+    ) external view returns (uint256);
+
+    /// @notice Returns all addresses that have given feedback to this agent
+    /// @param agentId The NFT token ID of the agent
+    /// @return clients Array of all reviewer addresses (in order of first feedback)
+    function getClients(uint256 agentId) external view returns (address[] memory clients);
+
+    /// @notice Gets the highest feedback index for a specific reviewer-agent pair
+    /// @param agentId The NFT token ID of the agent
+    /// @param reviewerAddress The address of the reviewer
+    /// @return lastIndex The highest assigned index (0 if no feedback exists)
+    function getLastIndex(
+        uint256 agentId,
+        address reviewerAddress
+    ) external view returns (uint64 lastIndex);
+}