feat: add identity registry for agent promotion to be discoverable (#4496)

### Description

Added an Identity Registry facet to the AppRegistry diamond,
implementing ERC-8004 compliant agent identity management. This allows
apps to register as agents with metadata and URIs, creating a
decentralized identity system for apps in the Towns ecosystem.

### Changes

- Added `IdentityRegistryFacet` with registration, metadata management,
and URI functionality
- Created interfaces and storage contracts for the identity registry
system
- Integrated the identity registry with the AppRegistry diamond
deployment
- Added a `publish` method to SimpleApp to register as an agent
- Added tests for agent publishing functionality

### Checklist

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

Author: giuseppecrj

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

@@ -3,7 +3,7 @@ pragma solidity ^0.8.23;
 
 // interfaces
 import {IDiamondInitHelper} from "./IDiamondInitHelper.sol";
-import {IAppFactory, IAppFactoryBase} from "src/apps/facets/factory/IAppFactory.sol";
+import {IAppFactoryBase} from "src/apps/facets/factory/IAppFactory.sol";
 
 // libraries
 import {DeployDiamondCut} from "@towns-protocol/diamond/scripts/deployments/facets/DeployDiamondCut.sol";
@@ -17,6 +17,7 @@ import {DeployAppInstallerFacet} from "../facets/DeployAppInstallerFacet.s.sol";
 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";
 
 // contracts
 import {Diamond} from "@towns-protocol/diamond/src/Diamond.sol";
@@ -101,6 +102,7 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("AppRegistryFacet");
         facetHelper.add("AppInstallerFacet");
         facetHelper.add("AppFactoryFacet");
+        facetHelper.add("IdentityRegistryFacet");
 
         facetHelper.deployBatch(deployer);
 
@@ -131,6 +133,13 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
             DeployAppFactoryFacet.makeInitData(beacons, _getEntryPoint())
         );
 
+        facet = facetHelper.getDeployedAddress("IdentityRegistryFacet");
+        addFacet(
+            makeCut(facet, FacetCutAction.Add, DeployIdentityRegistry.selectors()),
+            facet,
+            DeployIdentityRegistry.makeInitData()
+        );
+
         address multiInit = facetHelper.getDeployedAddress("MultiInit");
 
         return
@@ -166,6 +175,9 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
             if (facetName.eq("AppFactoryFacet")) {
                 addCut(makeCut(facet, FacetCutAction.Add, DeployAppFactoryFacet.selectors()));
             }
+            if (facetName.eq("IdentityRegistryFacet")) {
+                addCut(makeCut(facet, FacetCutAction.Add, DeployIdentityRegistry.selectors()));
+            }
         }
 
         return baseFacets();

packages/contracts/scripts/deployments/facets/DeployIdentityRegistry.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 {DeployERC721A} from "../facets/DeployERC721A.s.sol";
+
+// contracts
+import {IdentityRegistryFacet} from "src/apps/facets/identity/IdentityRegistryFacet.sol";
+import {DynamicArrayLib} from "solady/utils/DynamicArrayLib.sol";
+
+library DeployIdentityRegistry {
+    using DynamicArrayLib for DynamicArrayLib.DynamicArray;
+
+    function selectors() internal pure returns (bytes4[] memory res) {
+        uint256 selectorsCount = 20;
+        DynamicArrayLib.DynamicArray memory arr = DynamicArrayLib.p().reserve(selectorsCount);
+        arr.p(bytes4(keccak256("register()")));
+        arr.p(bytes4(keccak256("register(string)")));
+        arr.p(bytes4(keccak256("register(string,(string,bytes)[])")));
+        arr.p(IdentityRegistryFacet.getMetadata.selector);
+        arr.p(IdentityRegistryFacet.setMetadata.selector);
+        arr.p(IdentityRegistryFacet.setAgentUri.selector);
+
+        {
+            bytes4[] memory selectors_2 = DeployERC721A.selectors();
+            if (selectors_2.length > selectorsCount) {
+                revert("Selectors count is greater than the reserved space");
+            }
+            for (uint256 i; i < selectors_2.length; ++i) {
+                arr.p(selectors_2[i]);
+            }
+        }
+
+        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() internal pure returns (bytes memory) {
+        return abi.encodeCall(IdentityRegistryFacet.__IdentityRegistryFacet_init, ());
+    }
+
+    function deploy() internal returns (address) {
+        return LibDeploy.deployCode("IdentityRegistryFacet.sol", "");
+    }
+}

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

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+
+// libraries
+
+// contracts
+
+/// @title IIdentityRegistryBase
+/// @notice Base interface for ERC-8004 compliant agent identity registry
+/// @dev Defines core data structures, events, and errors for agent registration and metadata management
+interface IIdentityRegistryBase {
+    /// @notice Metadata entry for storing additional on-chain agent information
+    /// @dev Used in batch metadata operations during agent registration
+    struct MetadataEntry {
+        /// @notice The metadata key identifier
+        string metadataKey;
+        /// @notice The metadata value stored as bytes
+        bytes metadataValue;
+    }
+
+    /// @notice Emitted when a new agent is registered in the identity registry
+    /// @param agentId The unique identifier (agentId) assigned to the agent
+    /// @param agentUri The URI pointing to the agent's registration file
+    /// @param owner The address that owns the agent identity
+    event Registered(uint256 indexed agentId, string agentUri, address indexed owner);
+
+    /// @notice Emitted when metadata is set or updated for an agent
+    /// @param agentId The unique identifier of the agent
+    /// @param indexedKey The metadata key as indexed parameter for efficient filtering
+    /// @param metadataKey The metadata key as non-indexed parameter for reading
+    /// @param metadataValue The metadata value stored as bytes
+    event MetadataSet(
+        uint256 indexed agentId,
+        string indexed indexedKey,
+        string metadataKey,
+        bytes metadataValue
+    );
+
+    /// @notice Emitted when an agent's URI is updated
+    /// @param agentId The unique identifier of the agent
+    /// @param agentUri The new URI pointing to the agent's registration file
+    /// @param updatedBy The address that performed the update
+    event UriUpdated(uint256 indexed agentId, string agentUri, address indexed updatedBy);
+
+    /// @notice Thrown when caller is not authorized to perform the operation
+    /// @dev Authorization requires being the owner, an approved operator, or approved for the specific token
+    error IdentityRegistry__NotAuthorized();
+
+    /// @notice Thrown when attempting to access an agent that does not exist
+    error IdentityRegistry__AgentDoesNotExist();
+
+    /// @notice Thrown when attempting an operation on an agent that is not registered
+    error IdentityRegistry__AgentNotRegistered();
+
+    /// @notice Thrown when attempting to register an agent that is banned
+    error IdentityRegistry__AgentBanned();
+
+    /// @notice Thrown when attempting to promote or register an agent that already has a promoted identity
+    error IdentityRegistry__AgentAlreadyPromoted();
+}
+
+/// @title IIdentityRegistry
+/// @notice ERC-8004 compliant agent identity registry interface
+/// @dev Extends ERC-721 with agent registration, metadata management, and URI storage capabilities.
+///      Each agent is uniquely identified globally by: namespace (eip155), chainId, identityRegistry address, and agentId.
+///      The tokenURI resolves to an agent registration file containing endpoints, capabilities, and trust model information.
+interface IIdentityRegistry is IIdentityRegistryBase {
+    /// @notice Register a new agent identity without initial URI or metadata
+    /// @dev Mints a new ERC-721 token to msg.sender. URI can be set later via setAgentUri.
+    /// @return agentId The unique identifier assigned to the newly registered agent
+    function register() external returns (uint256 agentId);
+
+    /// @notice Register a new agent identity with a tokenURI
+    /// @dev Mints a new ERC-721 token to msg.sender and sets the tokenURI
+    /// @param agentUri The URI pointing to the agent's registration file (e.g., ipfs://cid or https://domain.com/agent.json)
+    /// @return agentId The unique identifier assigned to the newly registered agent
+    function register(string calldata agentUri) external returns (uint256 agentId);
+
+    /// @notice Register a new agent identity with tokenURI and metadata
+    /// @dev Mints a new ERC-721 token to msg.sender, sets the tokenURI, and stores metadata entries.
+    ///      This is the most complete registration method for agents with immediate metadata.
+    /// @param agentUri The URI pointing to the agent's registration file
+    /// @param metadata Array of metadata entries to store as on-chain metadata
+    /// @return agentId The unique identifier assigned to the newly registered agent
+    function register(
+        string calldata agentUri,
+        MetadataEntry[] calldata metadata
+    ) external returns (uint256 agentId);
+
+    /// @notice Retrieve metadata value for a specific agent and metadataKey
+    /// @dev Returns empty bytes if the metadataKey does not exist
+    /// @param agentId The unique identifier of the agent
+    /// @param metadataKey The metadata key to retrieve
+    /// @return The metadata value stored as bytes
+    function getMetadata(
+        uint256 agentId,
+        string memory metadataKey
+    ) external view returns (bytes memory);
+
+    /// @notice Set or update metadata for a specific agent
+    /// @dev Only callable by the agent owner, approved operator, or token-specific approved address.
+    ///      Emits MetadataSet event.
+    /// @param agentId The unique identifier of the agent
+    /// @param metadataKey The metadata key to set
+    /// @param metadataValue The metadata value to store as bytes
+    function setMetadata(
+        uint256 agentId,
+        string memory metadataKey,
+        bytes memory metadataValue
+    ) external;
+
+    /// @notice Update the tokenURI for an agent
+    /// @dev Only callable by the agent owner, approved operator, or token-specific approved address.
+    ///      Emits UriUpdated event. Useful when agent registration data changes.
+    /// @param agentId The unique identifier of the agent
+    /// @param agentUri The new URI pointing to the agent's updated registration file
+    function setAgentUri(uint256 agentId, string calldata agentUri) external;
+
+    /// @notice Get the tokenURI for an agent
+    /// @dev Returns the URI pointing to the agent's registration file.
+    ///      Reverts if the token does not exist.
+    /// @param agentId The unique identifier of the agent (ERC-721 tokenId)
+    /// @return The URI string pointing to the agent's registration file
+    function tokenURI(uint256 agentId) external view returns (string memory);
+}

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

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.23;
+
+// interfaces
+import {IIdentityRegistryBase} from "./IIdentityRegistry.sol";
+
+// libraries
+import {IdentityRegistryStorage} from "./IdentityRegistryStorage.sol";
+
+// contracts
+
+abstract contract IdentityRegistryBase is IIdentityRegistryBase {
+    function _setAgentUri(uint256 agentId, string memory agentUri) internal {
+        IdentityRegistryStorage.getLayout().agentUri[agentId] = agentUri;
+    }
+
+    function _getAgentUri(uint256 agentId) internal view returns (string memory) {
+        return IdentityRegistryStorage.getLayout().agentUri[agentId];
+    }
+
+    function _setMetadata(uint256 agentId, string memory metadataKey, bytes memory value) internal {
+        IdentityRegistryStorage.getLayout().metadata[agentId][metadataKey] = value;
+        emit MetadataSet(agentId, metadataKey, metadataKey, value);
+    }
+
+    function _getMetadata(
+        uint256 agentId,
+        string memory metadataKey
+    ) internal view returns (bytes memory) {
+        return IdentityRegistryStorage.getLayout().metadata[agentId][metadataKey];
+    }
+}