@coordination-network/contracts 0.0.1

package/interfaces/IApprovedIssuerSet.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+/// @title IApprovedIssuerSet
+/// @notice The one call the NetworkMemberRegistry makes into the approved-issuer set.
+/// @dev Exists only to break the import cycle: the set reads the registry for authorization, and the
+/// registry calls the set when it removes a member. Deliberately not the full ABI.
+interface IApprovedIssuerSet {
+    /// @notice Retires every signing key a member has published.
+    /// @param memberNetworkId The member whose keys are being retired.
+    function retireAllIssuerKeys(bytes32 memberNetworkId) external;
+
+    /// @notice The registry this set answers, so the registry can refuse to wire a set built for
+    /// another one.
+    function memberRegistry() external view returns (address);
+}

package/interfaces/IERC5564Announcer.sol

@@ -0,0 +1,38 @@
+// https://github.com/ScopeLift/stealth-address-erc-contracts/blob/main/src/interfaces/IERC5564Announcer.sol
+// SPDX-License-Identifier: CC0-1.0
+pragma solidity ^0.8.34;
+
+/// @notice Interface for calling the `ERC5564Announcer` contract, which emits an `Announcement`
+/// event to broadcast information about a transaction involving a stealth address. See
+/// [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) to learn more.
+interface IERC5564Announcer {
+    /// @notice Emitted when something is sent to a stealth address.
+    /// @param schemeId Identifier corresponding to the applied stealth address scheme, e.g. 1 for
+    /// secp256k1, as specified in ERC-5564.
+    /// @param stealthAddress The computed stealth address for the recipient.
+    /// @param caller The caller of the `announce` function that emitted this event.
+    /// @param ephemeralPubKey Ephemeral public key used by the sender to derive the `stealthAddress`.
+    /// @param metadata Arbitrary data to emit with the event. The first byte MUST be the view tag.
+    /// @dev The remaining metadata can be used by the senders however they like. See
+    /// [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) for recommendations on how to structure
+    /// this metadata.
+    event Announcement(
+        uint256 indexed schemeId,
+        address indexed stealthAddress,
+        address indexed caller,
+        bytes ephemeralPubKey,
+        bytes metadata
+    );
+
+    /// @notice Called by integrators to emit an `Announcement` event.
+    /// @param schemeId Identifier corresponding to the applied stealth address scheme, e.g. 1 for
+    /// secp256k1, as specified in ERC-5564.
+    /// @param stealthAddress The computed stealth address for the recipient.
+    /// @param ephemeralPubKey Ephemeral public key used by the sender.
+    /// @param metadata Arbitrary data to emit with the event. The first byte MUST be the view tag.
+    /// @dev The remaining metadata can be used by the senders however they like. See
+    /// [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) for recommendations on how to structure
+    /// this metadata.
+    function announce(uint256 schemeId, address stealthAddress, bytes memory ephemeralPubKey, bytes memory metadata)
+        external;
+}

package/interfaces/ISafeGovernance.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+/// @notice The Safe surface a governance module needs: reading the owner set, and making the Safe act
+/// on the module's behalf.
+/// @dev Declared here rather than imported so the production sources state exactly which Safe
+/// functions they depend on. `operation` is Safe's `Enum.Operation`, which encodes as a uint8.
+interface ISafeGovernance {
+    /// @notice The Safe's current owners.
+    function getOwners() external view returns (address[] memory);
+
+    /// @notice Whether `owner` is one of the Safe's owners.
+    function isOwner(address owner) external view returns (bool);
+
+    /// @notice The number of signatures the Safe currently requires.
+    function getThreshold() external view returns (uint256);
+
+    /// @notice Executes a transaction as the Safe, callable only by an enabled module.
+    /// @dev Returns `false` on an inner revert rather than bubbling it, so a caller must check.
+    function execTransactionFromModuleReturnData(address to, uint256 value, bytes memory data, uint8 operation)
+        external
+        returns (bool success, bytes memory returnData);
+}
+
+/// @notice The Safe's owner-set functions. Only the Safe itself may call them, so a module reaches
+/// them by having the Safe call itself.
+interface ISafeOwnerManager {
+    /// @notice Adds an owner and sets the threshold in one call.
+    function addOwnerWithThreshold(address owner, uint256 threshold) external;
+
+    /// @notice Removes an owner and sets the threshold in one call.
+    /// @param prevOwner The owner preceding `owner` in the Safe's owner linked list.
+    function removeOwner(address prevOwner, address owner, uint256 threshold) external;
+}

package/libraries/IssuerSetHashes.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { PoseidonT3 } from "poseidon-solidity/PoseidonT3.sol";
+import { PoseidonT4 } from "poseidon-solidity/PoseidonT4.sol";
+
+/// @title IssuerSetHashes
+/// @notice The approved-issuer-set leaf and internal-node formulas.
+/// @dev The single Solidity home of these formulas, so a change to the Poseidon instantiation is
+/// one edit here plus regenerated vectors. Their counterparts are the `hash_3` leaf and `hash_2`
+/// internal node in `packages/circuits/src/issuer.nr`, and `issuerLeaf` in
+/// `packages/issuer-set/src/hashes.ts`; all three must agree or every honest proof stops
+/// verifying.
+library IssuerSetHashes {
+    /// @notice Domain separator for a leaf commitment, matching `packages/credential`'s
+    /// `ISSUER_LEAF_DOMAIN` and the circuit's `LEAF_DOMAIN`.
+    uint256 internal constant ISSUER_LEAF_DOMAIN =
+        185404551131306766954100762329350135288498146007932686448214248919067924295;
+
+    /// @notice Commits a Baby Jubjub public key to the field element the tree stores as a leaf.
+    /// @param publicKeyX The public key's x coordinate.
+    /// @param publicKeyY The public key's y coordinate.
+    /// @return The leaf value.
+    function issuerKeyLeaf(uint256 publicKeyX, uint256 publicKeyY) internal pure returns (uint256) {
+        return PoseidonT4.hash([ISSUER_LEAF_DOMAIN, publicKeyX, publicKeyY]);
+    }
+
+    /// @notice Combines two child nodes into their parent.
+    /// @param left The left child.
+    /// @param right The right child.
+    /// @return The parent value.
+    function internalNode(uint256 left, uint256 right) internal pure returns (uint256) {
+        return PoseidonT3.hash([left, right]);
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@coordination-network/contracts",
+  "version": "0.0.1",
+  "description": "The coordination network's Solidity contracts: the network member registry and its governance, the identity registry, the approved-issuer set, the revocation registries and the Semaphore paymaster.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/contracts/src"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/contracts",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "files": [
+    "*.sol",
+    "revocation",
+    "base",
+    "interfaces",
+    "libraries"
+  ],
+  "keywords": [
+    "solidity",
+    "smart-contracts",
+    "account-abstraction",
+    "paymaster",
+    "verifiable-credentials",
+    "semaphore",
+    "zero-knowledge",
+    "revocation",
+    "merkle-tree",
+    "non-membership-proof"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@account-abstraction/contracts": "^0.8.0",
+    "@openzeppelin/contracts": "^5.6.1",
+    "@semaphore-protocol/contracts": "^4.14.3",
+    "@zk-kit/lean-imt-plus.sol": "0.1.1",
+    "@zk-kit/lean-imt.sol": "^2.0.1",
+    "poseidon-solidity": "^0.0.5"
+  }
+}

package/revocation/README.md

@@ -0,0 +1,86 @@
+# Revocation contracts
+
+On-chain revocation registries built on [LeanIMT+](https://pse.dev/blog/lean-imt-plus-efficient-merkle-tree-for-membership-and-non-membership-proofs).
+
+An issuer revokes a credential by publishing its revocation commitment. A holder proves their credential is still valid by proving, in zero knowledge, that their commitment is _absent_ from the registry. The verifier never learns which credential was presented, and never contacts the issuer.
+
+## Contracts
+
+| Contract                               | Role                                                                                                                                                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `RevocationRegistries`                 | Abstract base. Owns one LeanIMT+ per registry, gates writes behind a per-registry admin, and exposes the reads a holder rebuilds the tree from. Inherit it to put revocation inside your own protocol. |
+| `Revocation`                           | Deployable service on top of the base. Anyone can create a registry and become its admin, and each registry keeps a bounded history of accepted roots.                                                 |
+| `IRevocationRegistries`, `IRevocation` | Interfaces. Integrate against these.                                                                                                                                                                   |
+
+The split exists so the primitive and the policy can vary independently. `RevocationRegistries` owns the data structure and the access control that every revocation service needs. `Revocation` adds one particular policy on top: open registry creation and a bounded root history. A protocol that wants different policy, such as registries created only by governance or roots accepted on a different rule, inherits the base and writes its own.
+
+## Usage
+
+```shell
+yarn add @coordination-network/contracts
+```
+
+### Integrating
+
+```solidity
+import { IRevocation } from "@coordination-network/contracts/revocation/interfaces/IRevocation.sol";
+
+contract MyVerifier {
+    IRevocation public immutable revocation;
+
+    function verify(uint256 registryId, uint256 revocationRoot, bytes calldata zkProof) external view {
+        // 1. verify the zero-knowledge proof; it outputs the revocation root it was built against
+        // 2. check that root is one this registry currently accepts
+        require(revocation.isValidRoot(registryId, revocationRoot), "stale or unknown revocation root");
+    }
+}
+```
+
+`isValidRoot` is the only on-chain read a privacy-preserving verification needs. The commitment never appears, which is what keeps presentations unlinkable.
+
+### Revoking
+
+Every mutation takes the physical index of the affected leaf's predecessor. The 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 [`@coordination-network/revocation-registry`](https://github.com/zk-kit/coordination-network/tree/main/packages/revocation-registry):
+
+```ts
+const lowLeafIndex = tree.lowLeafIndexOf(revocationCommitment)
+```
+
+then
+
+```solidity
+revocation.revoke(registryId, revocationCommitment, lowLeafIndex);
+```
+
+The index is only valid against the tree state the transaction executes in. If another revocation lands first the transaction reverts and the index must be recomputed.
+
+`revokeMany` rehashes each affected internal node once for the whole batch instead of once per commitment, so a batch costs less than the same revocations sent one at a time, and the saving grows with batch size.
+
+### The root history
+
+A holder builds their proof against the root they last saw. A revocation landing between proof generation and verification would otherwise invalidate an honest proof, so each registry keeps accepting a superseded root for `rootDuration` seconds (one hour by default, configurable per registry).
+
+The current root never expires; it is accepted for as long as it stays current, however long that is. When a revocation replaces it, the registry stamps that moment and the old root remains acceptable for `rootDuration` seconds from then. Every root therefore gets the same window, starting when it stops being current, which is exactly the interval in which a proof built against it can still be in flight.
+
+This also bounds the risk the window creates. A credential revoked at some moment is absent from every earlier root and present in every later one, so the newest root that still lets it verify is the one its own revocation replaced. That root expires `rootDuration` seconds later, and older roots were superseded earlier and expire sooner. A revoked credential can therefore keep verifying for at most `rootDuration` after its revocation, whatever the registry's history.
+
+`rootDuration` may be zero, which turns the grace period off: only the current root is accepted, and every proof in flight when a revocation lands is invalidated. That is the strictest setting, for a registry where a credential revoked seconds ago must not be presentable at all, and it costs failed presentations an honest holder cannot avoid. The comparison is strict on both ends, so a zero window rejects a root superseded in the same block rather than leaving a one-timestamp gap.
+
+## Build
+
+The contracts are deployed and tested inside the
+[coordination-network](https://github.com/zk-kit/coordination-network) monorepo, in the
+`coordination-network-contracts` Foundry project:
+
+```bash
+yarn build:contracts
+yarn test:contracts
+```
+
+## Notes
+
+- Commitments must be non-zero and below the BN254 scalar field order. Zero is reserved for the sentinel leaf and for tombstones.
+- There is deliberately no on-chain Merkle proof verifier. Verifying a plaintext proof would reveal the commitment, and a caller willing to do that can just call `isRevoked`, which is cheaper and answers the same question. The private path is a zero-knowledge proof verified elsewhere, whose root is checked with `isValidRoot`.
+- Registries are isolated. One deployment serves many issuers, and an admin can only write to its own registry.
+- Admin transfers are two-step, so a typo cannot strand a registry.
+- `test/integration/CrossLanguageRoot.t.sol` pins the contract's roots against the TypeScript package. Any drift in the hashing or the insertion rules fails a test on both sides.

package/revocation/Revocation.sol

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.34;
+
+import { RevocationRegistries } from "./base/RevocationRegistries.sol";
+import { IRevocation } from "./interfaces/IRevocation.sol";
+
+/// @title Revocation
+/// @notice Deployable revocation service. Anyone can create a registry and revoke credentials in it.
+/// @dev One deployment serves many issuers: each gets its own registry, its own LeanIMT+ and its own
+/// root history, and can only write to its own. Contracts that want revocation as part of a larger
+/// protocol can inherit {RevocationRegistries} directly instead of using this one.
+///
+/// The flow this contract is one third of:
+///
+///  1. an issuer revokes a credential here, publishing its revocation commitment;
+///  2. a holder rebuilds the registry's tree off chain and proves, in zero knowledge, that their
+///     commitment is *not* in it, which outputs the root they proved against;
+///  3. a verifier checks that zero-knowledge proof and calls {isValidRoot} with the root it output.
+///
+/// Only step 1 and the {isValidRoot} half of step 3 happen on chain. The commitment never appears in
+/// a verification, which is what keeps a presentation unlinkable.
+contract Revocation is IRevocation, RevocationRegistries {
+    /// @notice The accepted-root window a registry gets unless it asks for another one.
+    /// @dev One hour comfortably covers a holder syncing the tree and presenting a credential, while
+    /// bounding how long a credential revoked a moment ago can still be presented as valid.
+    uint256 public constant DEFAULT_ROOT_DURATION = 1 hours;
+
+    /// @dev The policy and root history of each registry.
+    mapping(uint256 registryId => Registry registry) internal registries;
+
+    /// @inheritdoc IRevocation
+    uint256 public override registryCounter;
+
+    /// @inheritdoc IRevocation
+    function createRegistry() external override returns (uint256 registryId) {
+        return _createRegistryWithDuration(msg.sender, DEFAULT_ROOT_DURATION);
+    }
+
+    /// @inheritdoc IRevocation
+    function createRegistry(address admin) external override returns (uint256 registryId) {
+        return _createRegistryWithDuration(admin, DEFAULT_ROOT_DURATION);
+    }
+
+    /// @inheritdoc IRevocation
+    function createRegistry(address admin, uint256 rootDuration) external override returns (uint256 registryId) {
+        return _createRegistryWithDuration(admin, rootDuration);
+    }
+
+    /// @inheritdoc IRevocation
+    function updateRegistryAdmin(uint256 registryId, address newAdmin) external override {
+        _updateRegistryAdmin(registryId, newAdmin);
+    }
+
+    /// @inheritdoc IRevocation
+    function acceptRegistryAdmin(uint256 registryId) external override {
+        _acceptRegistryAdmin(registryId);
+    }
+
+    /// @inheritdoc IRevocation
+    function updateRegistryRootDuration(uint256 registryId, uint256 newRootDuration)
+        external
+        override
+        onlyRegistryAdmin(registryId)
+    {
+        uint256 oldRootDuration = registries[registryId].rootDuration;
+
+        registries[registryId].rootDuration = newRootDuration;
+
+        emit RegistryRootDurationUpdated(registryId, oldRootDuration, newRootDuration);
+    }
+
+    /// @inheritdoc IRevocation
+    function revoke(uint256 registryId, uint256 revocationCommitment, uint256 lowLeafIndex) external override {
+        uint256 oldRoot = getRevocationRoot(registryId);
+
+        _revoke(registryId, revocationCommitment, lowLeafIndex);
+
+        _supersedeRoot(registryId, oldRoot);
+    }
+
+    /// @inheritdoc IRevocation
+    function revokeMany(uint256 registryId, uint256[] calldata revocationCommitments, uint256[] calldata lowLeafIndices)
+        external
+        override
+    {
+        uint256 oldRoot = getRevocationRoot(registryId);
+
+        _revokeMany(registryId, revocationCommitments, lowLeafIndices);
+
+        _supersedeRoot(registryId, oldRoot);
+    }
+
+    /// @inheritdoc IRevocation
+    function unrevoke(uint256 registryId, uint256 revocationCommitment, uint256 predecessorIndex) external override {
+        uint256 oldRoot = getRevocationRoot(registryId);
+
+        _unrevoke(registryId, revocationCommitment, predecessorIndex);
+
+        _supersedeRoot(registryId, oldRoot);
+    }
+
+    /// @inheritdoc IRevocation
+    function updateRevocationCommitment(
+        uint256 registryId,
+        uint256 oldRevocationCommitment,
+        uint256 newRevocationCommitment,
+        uint256 oldPredecessorIndex,
+        uint256 newPredecessorIndex
+    ) external override {
+        uint256 oldRoot = getRevocationRoot(registryId);
+
+        _updateRevocationCommitment(
+            registryId, oldRevocationCommitment, newRevocationCommitment, oldPredecessorIndex, newPredecessorIndex
+        );
+
+        _supersedeRoot(registryId, oldRoot);
+    }
+
+    /// @inheritdoc IRevocation
+    function isValidRoot(uint256 registryId, uint256 revocationRoot)
+        external
+        view
+        override
+        onlyExistingRegistry(registryId)
+        returns (bool)
+    {
+        if (revocationRoot == getRevocationRoot(registryId)) return true;
+
+        uint256 supersededAt = registries[registryId].rootSupersededAt[revocationRoot];
+
+        if (supersededAt == 0) return false;
+
+        // Strict, so that a `rootDuration` of zero means exactly no grace at all rather than a
+        // one-timestamp window. A superseded root is accepted for `rootDuration` seconds, counted
+        // from the moment it stopped being current.
+        //
+        // Both sides come from the same clock, and the window is a policy measured in minutes or
+        // hours, so the seconds of drift a validator can introduce cannot meaningfully lengthen or
+        // shorten it. The worst case is a proof accepted or rejected a few seconds either side of
+        // its deadline, which is what the window exists to tolerate in the first place.
+        // forge-lint: disable-next-line(block-timestamp)
+        return block.timestamp < supersededAt + registries[registryId].rootDuration;
+    }
+
+    /// @inheritdoc IRevocation
+    function getRootSupersededAt(uint256 registryId, uint256 revocationRoot) external view override returns (uint256) {
+        return registries[registryId].rootSupersededAt[revocationRoot];
+    }
+
+    /// @inheritdoc IRevocation
+    function getRegistryRootDuration(uint256 registryId) external view override returns (uint256) {
+        return registries[registryId].rootDuration;
+    }
+
+    /// @dev Allocates the next registry id and records its root window.
+    /// @param admin The address allowed to revoke in the registry.
+    /// @param rootDuration How long a superseded root stays acceptable, in seconds.
+    /// @return registryId The id of the new registry.
+    function _createRegistryWithDuration(address admin, uint256 rootDuration) private returns (uint256 registryId) {
+        registryId = registryCounter++;
+
+        _createRegistry(registryId, admin);
+
+        registries[registryId].rootDuration = rootDuration;
+    }
+
+    /// @dev Starts the expiry clock of the root a mutation just replaced.
+    ///
+    /// A root's window runs from the moment it stops being current, which is the moment recorded
+    /// here. Until then it is the current root and never expires, however long it stays current.
+    /// Every root therefore gets the same full window, covering exactly the interval in which a
+    /// proof built against it can still be in flight.
+    ///
+    /// This is also what bounds the exposure: the newest root that still verifies an already
+    /// revoked credential is the one that credential's own revocation replaced, so it stops being
+    /// accepted `rootDuration` seconds after that revocation.
+    ///
+    /// The empty-tree root is skipped: it is not a root anybody can build a proof against.
+    ///
+    /// @param registryId The id of the registry.
+    /// @param oldRoot The root the mutation replaced.
+    function _supersedeRoot(uint256 registryId, uint256 oldRoot) private {
+        if (oldRoot == 0) return;
+
+        registries[registryId].rootSupersededAt[oldRoot] = block.timestamp;
+    }
+}