@coordination-network/contracts 0.0.1

package/revocation/base/RevocationRegistries.sol

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { InternalLeanIMTPlus, LeanIMTPlusData } from "@zk-kit/lean-imt-plus.sol/InternalLeanIMTPlus.sol";
+import { IRevocationRegistries } from "../interfaces/IRevocationRegistries.sol";
+
+/// @title RevocationRegistries
+/// @notice Base contract that owns the revocation trees. Inherit it to build a revocation service.
+/// @dev This is the reusable half of the package: it holds one LeanIMT+ per registry, gates every
+/// write behind a per-registry admin, and exposes the read surface a holder needs to rebuild a tree
+/// off chain. It deliberately knows nothing about root histories, expiry or proof systems, so a
+/// consumer can layer its own policy on top. {Revocation} is the reference layer.
+///
+/// Every mutation takes the physical index of the affected leaf's predecessor as an argument. The
+/// LeanIMT+ library validates that index in O(1) but does not search for it, which is what keeps a
+/// write at O(depth) storage writes. Compute it off chain with the revocation-registry package:
+/// `RevocationRegistry.lowLeafIndexOf` for a revocation, `RevocationRegistry.predecessorIndexOf` for an
+/// un-revocation or an update. It must be computed against the same tree state the transaction will
+/// execute in; if another write lands first the transaction reverts and the index must be
+/// recomputed.
+abstract contract RevocationRegistries is IRevocationRegistries {
+    using InternalLeanIMTPlus for LeanIMTPlusData;
+
+    /// @dev The LeanIMT+ backing each registry. Its leaves are the revoked commitments.
+    mapping(uint256 registryId => LeanIMTPlusData tree) internal revocationTrees;
+
+    /// @dev The admin of each registry. It can be an account or a contract, and is the only address
+    /// allowed to revoke in that registry. The zero address means the registry does not exist.
+    mapping(uint256 registryId => address admin) internal registryAdmins;
+
+    /// @dev An admin that has been proposed for a registry and has not accepted yet.
+    mapping(uint256 registryId => address pendingAdmin) internal pendingRegistryAdmins;
+
+    /// @dev Restricts a call to the registry admin.
+    /// @param registryId The id of the registry.
+    modifier onlyRegistryAdmin(uint256 registryId) {
+        _onlyRegistryAdmin(registryId);
+        _;
+    }
+
+    /// @dev Requires the registry to exist.
+    /// @param registryId The id of the registry.
+    modifier onlyExistingRegistry(uint256 registryId) {
+        _onlyExistingRegistry(registryId);
+        _;
+    }
+
+    /// @dev The body of {onlyRegistryAdmin}, kept out of the modifier so the check is compiled
+    /// once and jumped to rather than inlined at every guarded function.
+    /// @param registryId The id of the registry.
+    function _onlyRegistryAdmin(uint256 registryId) internal view {
+        if (registryAdmins[registryId] != msg.sender) revert CallerIsNotTheRegistryAdmin();
+    }
+
+    /// @dev The body of {onlyExistingRegistry}, kept out of the modifier for the same reason.
+    /// @param registryId The id of the registry.
+    function _onlyExistingRegistry(uint256 registryId) internal view {
+        if (registryAdmins[registryId] == address(0)) revert RegistryDoesNotExist();
+    }
+
+    /// @dev Creates a registry. The caller is responsible for allocating an unused `registryId`.
+    /// @param registryId The id of the new registry.
+    /// @param admin The address allowed to revoke in it.
+    function _createRegistry(uint256 registryId, address admin) internal virtual {
+        if (admin == address(0)) revert ZeroAdmin();
+
+        registryAdmins[registryId] = admin;
+
+        emit RegistryCreated(registryId);
+        emit RegistryAdminUpdated(registryId, address(0), admin);
+    }
+
+    /// @dev Proposes a new registry admin. The transfer is two-step: it only takes effect once the
+    /// proposed admin calls {_acceptRegistryAdmin}, so a typo cannot strand a registry.
+    /// @param registryId The id of the registry.
+    /// @param newAdmin The proposed admin.
+    function _updateRegistryAdmin(uint256 registryId, address newAdmin) internal virtual onlyRegistryAdmin(registryId) {
+        pendingRegistryAdmins[registryId] = newAdmin;
+
+        emit RegistryAdminPending(registryId, msg.sender, newAdmin);
+    }
+
+    /// @dev Accepts a pending admin transfer. Callable only by the proposed admin.
+    /// @param registryId The id of the registry.
+    function _acceptRegistryAdmin(uint256 registryId) internal virtual {
+        if (pendingRegistryAdmins[registryId] != msg.sender) revert CallerIsNotThePendingRegistryAdmin();
+
+        address oldAdmin = registryAdmins[registryId];
+
+        registryAdmins[registryId] = msg.sender;
+
+        delete pendingRegistryAdmins[registryId];
+
+        emit RegistryAdminUpdated(registryId, oldAdmin, msg.sender);
+    }
+
+    /// @dev Revokes a credential by inserting its commitment.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revocation commitment of the credential.
+    /// @param lowLeafIndex The physical index of the commitment's predecessor, found off chain and
+    /// validated here. Ignored for the first revocation in a registry, which creates the sentinel.
+    /// @return revocationRoot The new root of the registry.
+    function _revoke(uint256 registryId, uint256 revocationCommitment, uint256 lowLeafIndex)
+        internal
+        virtual
+        onlyRegistryAdmin(registryId)
+        returns (uint256 revocationRoot)
+    {
+        uint256 index = revocationTrees[registryId]._insert(revocationCommitment, lowLeafIndex);
+        revocationRoot = revocationTrees[registryId]._root();
+
+        emit CredentialRevoked(registryId, index, revocationCommitment, revocationRoot);
+    }
+
+    /// @dev Revokes several credentials in one call. Cheaper than one {_revoke} per commitment,
+    /// because every affected internal node is rehashed at most once.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitments The commitments to revoke, in insertion order.
+    /// @param lowLeafIndices For each commitment, the physical index of its predecessor in the tree
+    /// state after the earlier commitments in this batch have been inserted.
+    /// @return revocationRoot The new root of the registry.
+    function _revokeMany(
+        uint256 registryId,
+        uint256[] calldata revocationCommitments,
+        uint256[] calldata lowLeafIndices
+    ) internal virtual onlyRegistryAdmin(registryId) returns (uint256 revocationRoot) {
+        revocationTrees[registryId]._insertMany(revocationCommitments, lowLeafIndices);
+        revocationRoot = revocationTrees[registryId]._root();
+
+        emit CredentialsRevoked(registryId, revocationCommitments, revocationRoot);
+    }
+
+    /// @dev Undoes a revocation, tombstoning the commitment's slot.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revoked commitment.
+    /// @param predecessorIndex The physical index of the leaf whose `nextValue` is the commitment.
+    /// @return revocationRoot The new root of the registry.
+    function _unrevoke(uint256 registryId, uint256 revocationCommitment, uint256 predecessorIndex)
+        internal
+        virtual
+        onlyRegistryAdmin(registryId)
+        returns (uint256 revocationRoot)
+    {
+        uint256 index = revocationTrees[registryId]._indexOf(revocationCommitment);
+
+        revocationTrees[registryId]._remove(revocationCommitment, predecessorIndex);
+        revocationRoot = revocationTrees[registryId]._root();
+
+        emit CredentialUnrevoked(registryId, index, revocationCommitment, revocationRoot);
+    }
+
+    /// @dev Replaces a revoked commitment with another one, reusing its physical slot. Cheaper than
+    /// an un-revocation followed by a revocation, which would tombstone a slot and append a new one.
+    /// @param registryId The id of the registry.
+    /// @param oldRevocationCommitment The revoked commitment to replace.
+    /// @param newRevocationCommitment The commitment to put in its place.
+    /// @param oldPredecessorIndex The physical index of the old commitment's predecessor.
+    /// @param newPredecessorIndex The physical index of the new commitment's predecessor in the
+    /// tree state after the old commitment has been unlinked.
+    /// @return revocationRoot The new root of the registry.
+    function _updateRevocationCommitment(
+        uint256 registryId,
+        uint256 oldRevocationCommitment,
+        uint256 newRevocationCommitment,
+        uint256 oldPredecessorIndex,
+        uint256 newPredecessorIndex
+    ) internal virtual onlyRegistryAdmin(registryId) returns (uint256 revocationRoot) {
+        uint256 index = revocationTrees[registryId]._indexOf(oldRevocationCommitment);
+
+        revocationTrees[registryId]._update(
+            oldRevocationCommitment, newRevocationCommitment, oldPredecessorIndex, newPredecessorIndex
+        );
+        revocationRoot = revocationTrees[registryId]._root();
+
+        emit RevocationCommitmentUpdated(
+            registryId, index, oldRevocationCommitment, newRevocationCommitment, revocationRoot
+        );
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getRegistryAdmin(uint256 registryId) public view virtual override returns (address) {
+        return registryAdmins[registryId];
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getPendingRegistryAdmin(uint256 registryId) public view virtual override returns (address) {
+        return pendingRegistryAdmins[registryId];
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function isRevoked(uint256 registryId, uint256 revocationCommitment) public view virtual override returns (bool) {
+        return revocationTrees[registryId]._has(revocationCommitment);
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function indexOf(uint256 registryId, uint256 revocationCommitment) public view virtual override returns (uint256) {
+        return revocationTrees[registryId]._indexOf(revocationCommitment);
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getLeaf(uint256 registryId, uint256 index)
+        public
+        view
+        virtual
+        override
+        returns (uint256 value, uint256 nextValue)
+    {
+        return (revocationTrees[registryId].leaves[index].value, revocationTrees[registryId].leaves[index].nextValue);
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getRevocationRoot(uint256 registryId) public view virtual override returns (uint256) {
+        return revocationTrees[registryId]._root();
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getRevocationTreeDepth(uint256 registryId) public view virtual override returns (uint256) {
+        return revocationTrees[registryId].depth;
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getRevocationTreeSize(uint256 registryId) public view virtual override returns (uint256) {
+        return revocationTrees[registryId].size;
+    }
+
+    /// @inheritdoc IRevocationRegistries
+    function getRevocationTreeLeafCount(uint256 registryId) public view virtual override returns (uint256) {
+        return revocationTrees[registryId].leaves.length;
+    }
+}

package/revocation/interfaces/IRevocation.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+/// @title IRevocation
+/// @notice Interface of the deployable revocation service.
+/// @dev {Revocation} adds two things to {RevocationRegistries}: anyone can create a registry and
+/// become its admin, and every root a registry has ever published stays acceptable for a bounded
+/// window. The window exists because a holder builds a proof against the root they last saw. A
+/// revocation landing between proof generation and verification would otherwise invalidate an
+/// honest proof.
+interface IRevocation {
+    /// @notice Per-registry policy.
+    /// @dev `rootSupersededAt` is the root history: it maps every root the registry has published
+    /// to the block timestamp at which it was superseded, which is when its expiry clock starts.
+    struct Registry {
+        uint256 rootDuration;
+        mapping(uint256 revocationRoot => uint256 supersededAt) rootSupersededAt;
+    }
+
+    /// @notice Emitted when a registry's accepted-root window changes.
+    /// @param registryId The id of the registry.
+    /// @param oldRootDuration The previous window, in seconds.
+    /// @param newRootDuration The new window, in seconds.
+    event RegistryRootDurationUpdated(uint256 indexed registryId, uint256 oldRootDuration, uint256 newRootDuration);
+
+    /// @notice The number of registries created so far, and the id the next one will get.
+    /// @return The registry counter.
+    function registryCounter() external view returns (uint256);
+
+    /// @notice Creates a registry administered by the caller, with the default root window.
+    /// @return registryId The id of the new registry.
+    function createRegistry() external returns (uint256 registryId);
+
+    /// @notice Creates a registry with the default root window.
+    /// @param admin The address allowed to revoke in it.
+    /// @return registryId The id of the new registry.
+    function createRegistry(address admin) external returns (uint256 registryId);
+
+    /// @notice Creates a registry with a custom root window.
+    /// @param admin The address allowed to revoke in it.
+    /// @param rootDuration How long a superseded root stays acceptable, in seconds. Zero is allowed
+    /// and means only the current root is ever accepted.
+    /// @return registryId The id of the new registry.
+    function createRegistry(address admin, uint256 rootDuration) external returns (uint256 registryId);
+
+    /// @notice Proposes a new admin for a registry. It takes effect on {acceptRegistryAdmin}.
+    /// @param registryId The id of the registry.
+    /// @param newAdmin The proposed admin.
+    function updateRegistryAdmin(uint256 registryId, address newAdmin) external;
+
+    /// @notice Accepts a pending admin transfer.
+    /// @param registryId The id of the registry.
+    function acceptRegistryAdmin(uint256 registryId) external;
+
+    /// @notice Changes how long a superseded root of a registry stays acceptable.
+    /// @dev Shortening the window makes proofs against already superseded roots expire sooner, so
+    /// pick a window that comfortably covers how long a holder takes to sync and present. Setting it
+    /// to zero turns the grace period off entirely: only the current root is accepted, and every
+    /// proof in flight when a revocation lands is invalidated. That is the strictest setting and the
+    /// one a registry with adversarial timing concerns wants, at the cost of failed presentations
+    /// that an honest holder cannot avoid.
+    /// @param registryId The id of the registry.
+    /// @param newRootDuration The new window, in seconds. Zero is allowed.
+    function updateRegistryRootDuration(uint256 registryId, uint256 newRootDuration) external;
+
+    /// @notice Revokes a credential.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revocation commitment of the credential.
+    /// @param lowLeafIndex The physical index of the commitment's predecessor, found off chain.
+    function revoke(uint256 registryId, uint256 revocationCommitment, uint256 lowLeafIndex) external;
+
+    /// @notice Revokes several credentials in one call.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitments The commitments to revoke, in insertion order.
+    /// @param lowLeafIndices Each commitment's predecessor index, in the tree state after the
+    /// earlier commitments in the batch have been inserted.
+    function revokeMany(uint256 registryId, uint256[] calldata revocationCommitments, uint256[] calldata lowLeafIndices)
+        external;
+
+    /// @notice Undoes a revocation.
+    /// @dev A credential becomes valid again for every verifier, including those still accepting an
+    /// older root. Revocation is normally permanent; reach for this deliberately.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revoked commitment.
+    /// @param predecessorIndex The physical index of the leaf whose `nextValue` is the commitment.
+    function unrevoke(uint256 registryId, uint256 revocationCommitment, uint256 predecessorIndex) external;
+
+    /// @notice Replaces a revoked commitment with another one, reusing its slot.
+    /// @param registryId The id of the registry.
+    /// @param oldRevocationCommitment The revoked commitment to replace.
+    /// @param newRevocationCommitment The commitment to put in its place.
+    /// @param oldPredecessorIndex The physical index of the old commitment's predecessor.
+    /// @param newPredecessorIndex The physical index of the new commitment's predecessor, in the
+    /// tree state after the old commitment has been unlinked.
+    function updateRevocationCommitment(
+        uint256 registryId,
+        uint256 oldRevocationCommitment,
+        uint256 newRevocationCommitment,
+        uint256 oldPredecessorIndex,
+        uint256 newPredecessorIndex
+    ) external;
+
+    /// @notice Whether a root may back a revocation proof right now.
+    /// @dev This is the call a verifier makes. It accepts the registry's current root, and any root
+    /// superseded strictly less than `rootDuration` seconds ago, so a `rootDuration` of zero accepts
+    /// the current root only. It is the only on-chain read a privacy-preserving
+    /// verification needs: the zero-knowledge proof itself is verified elsewhere, and it outputs the
+    /// root that is checked here.
+    /// @param registryId The id of the registry.
+    /// @param revocationRoot The root the proof was built against.
+    /// @return True if the root is currently accepted.
+    function isValidRoot(uint256 registryId, uint256 revocationRoot) external view returns (bool);
+
+    /// @notice The timestamp at which a root was superseded, or zero if it is not a past root.
+    /// @dev Zero is also returned for the current root, which never expires while it is current.
+    /// @param registryId The id of the registry.
+    /// @param revocationRoot The root to look up.
+    /// @return The timestamp at which the root stopped being current.
+    function getRootSupersededAt(uint256 registryId, uint256 revocationRoot) external view returns (uint256);
+
+    /// @notice The accepted-root window of a registry, in seconds.
+    /// @param registryId The id of the registry.
+    /// @return The window.
+    function getRegistryRootDuration(uint256 registryId) external view returns (uint256);
+}

package/revocation/interfaces/IRevocationRegistries.sol

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+/// @title IRevocationRegistries
+/// @notice Interface of the base contract that owns the revocation trees.
+/// @dev Every revocation registry is one LeanIMT+ whose leaves are the revocation commitments of
+/// revoked credentials, plus an admin allowed to write to it. A credential is proven unrevoked with
+/// a non-membership proof against the registry's root.
+interface IRevocationRegistries {
+    error RegistryDoesNotExist();
+    error CallerIsNotTheRegistryAdmin();
+    error CallerIsNotThePendingRegistryAdmin();
+    error ZeroAdmin();
+
+    /// @notice Emitted when a registry is created.
+    /// @param registryId The id of the new registry.
+    event RegistryCreated(uint256 indexed registryId);
+
+    /// @notice Emitted when a registry admin change takes effect.
+    /// @param registryId The id of the registry.
+    /// @param oldAdmin The previous admin.
+    /// @param newAdmin The new admin.
+    event RegistryAdminUpdated(uint256 indexed registryId, address indexed oldAdmin, address indexed newAdmin);
+
+    /// @notice Emitted when a registry admin change is proposed and awaits acceptance.
+    /// @param registryId The id of the registry.
+    /// @param oldAdmin The current admin.
+    /// @param newAdmin The proposed admin.
+    event RegistryAdminPending(uint256 indexed registryId, address indexed oldAdmin, address indexed newAdmin);
+
+    /// @notice Emitted when a credential is revoked.
+    /// @param registryId The id of the registry.
+    /// @param index The physical leaf index the commitment was written to.
+    /// @param revocationCommitment The revoked commitment.
+    /// @param revocationRoot The new root of the registry.
+    event CredentialRevoked(
+        uint256 indexed registryId, uint256 index, uint256 revocationCommitment, uint256 revocationRoot
+    );
+
+    /// @notice Emitted when several credentials are revoked in one call.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitments The revoked commitments, in insertion order.
+    /// @param revocationRoot The new root of the registry.
+    event CredentialsRevoked(uint256 indexed registryId, uint256[] revocationCommitments, uint256 revocationRoot);
+
+    /// @notice Emitted when a revocation is undone.
+    /// @param registryId The id of the registry.
+    /// @param index The physical leaf index that was tombstoned.
+    /// @param revocationCommitment The commitment that is no longer revoked.
+    /// @param revocationRoot The new root of the registry.
+    event CredentialUnrevoked(
+        uint256 indexed registryId, uint256 index, uint256 revocationCommitment, uint256 revocationRoot
+    );
+
+    /// @notice Emitted when a revoked commitment is replaced in place.
+    /// @param registryId The id of the registry.
+    /// @param index The physical leaf index that was rewritten.
+    /// @param oldRevocationCommitment The commitment that was replaced.
+    /// @param newRevocationCommitment The commitment that took its place.
+    /// @param revocationRoot The new root of the registry.
+    event RevocationCommitmentUpdated(
+        uint256 indexed registryId,
+        uint256 index,
+        uint256 oldRevocationCommitment,
+        uint256 newRevocationCommitment,
+        uint256 revocationRoot
+    );
+
+    /// @notice Returns the admin of a registry, or the zero address if the registry does not exist.
+    /// @param registryId The id of the registry.
+    /// @return The registry admin.
+    function getRegistryAdmin(uint256 registryId) external view returns (address);
+
+    /// @notice Returns the admin that has been proposed for a registry but has not accepted yet.
+    /// @param registryId The id of the registry.
+    /// @return The pending registry admin, or the zero address if there is none.
+    function getPendingRegistryAdmin(uint256 registryId) external view returns (address);
+
+    /// @notice Whether a credential has been revoked.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revocation commitment of the credential.
+    /// @return True if the commitment is in the registry.
+    function isRevoked(uint256 registryId, uint256 revocationCommitment) external view returns (bool);
+
+    /// @notice Returns the physical leaf index of a revoked commitment. Reverts if it is not revoked.
+    /// @param registryId The id of the registry.
+    /// @param revocationCommitment The revocation commitment of the credential.
+    /// @return The physical leaf index.
+    function indexOf(uint256 registryId, uint256 revocationCommitment) external view returns (uint256);
+
+    /// @notice Returns the indexed leaf stored at a physical index, as `(value, nextValue)`.
+    /// @dev Reading every slot from `0` to {getRevocationTreeLeafCount} minus one yields the whole
+    /// registry, which is what a holder rebuilds the tree from, so the registry stays usable even if
+    /// no indexer or snapshot service is available. Reverts if `index` is out of range.
+    /// @param registryId The id of the registry.
+    /// @param index The physical leaf index.
+    /// @return value The commitment stored at the index, or zero for the sentinel and tombstones.
+    /// @return nextValue The next commitment in sorted order, or zero at the tail.
+    function getLeaf(uint256 registryId, uint256 index) external view returns (uint256 value, uint256 nextValue);
+
+    /// @notice Returns the current revocation root of a registry. Zero while the registry is empty.
+    /// @param registryId The id of the registry.
+    /// @return The current root.
+    function getRevocationRoot(uint256 registryId) external view returns (uint256);
+
+    /// @notice Returns the depth of a registry's tree.
+    /// @param registryId The id of the registry.
+    /// @return The tree depth.
+    function getRevocationTreeDepth(uint256 registryId) external view returns (uint256);
+
+    /// @notice Returns the number of revoked commitments in a registry, excluding the sentinel and
+    /// any tombstones.
+    /// @param registryId The id of the registry.
+    /// @return The number of revoked commitments.
+    function getRevocationTreeSize(uint256 registryId) external view returns (uint256);
+
+    /// @notice Returns the number of physical leaf slots, including the sentinel and tombstones.
+    /// @dev This is the upper bound for {getLeaf}, not the number of revocations.
+    /// @param registryId The id of the registry.
+    /// @return The number of leaf slots.
+    function getRevocationTreeLeafCount(uint256 registryId) external view returns (uint256);
+}