@openzeppelin/compact-contracts 0.1.0

package/access/AccessControl.compact

@@ -0,0 +1,479 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.1.0 (access/AccessControl.compact)
+
+pragma language_version >= 0.21.0;
+
+/**
+ * @module AccessControl
+ * @description An unshielded AccessControl library.
+ * This module provides a role-based access control mechanism, where roles can be used to
+ * represent a set of permissions.
+ *
+ * Authorization is based on a witness-derived identity scheme. Each caller proves knowledge
+ * of a secret key by injecting it via the `wit_AccessControlSK` witness. The module computes
+ * an account identifier as `persistentHash(secretKey)` which is a commitment that hides the key
+ * while providing a stable, pseudonymous on-chain identity.
+ *
+ * Because the account identifier is `H(secretKey)` with no per-deployment salt or domain
+ * separator, the same secret key produces the same identity across all contracts. This is
+ * intentional. It provides a linkable pseudonymous identity analogous to Solidity's
+ * `msg.sender`. Users who desire cross-contract unlinkability can use different secret keys
+ * per contract at the wallet layer.
+ *
+ * Roles are referred to by their `Bytes<32>` identifier. These should be exposed
+ * in the top-level contract and be unique. One way to achieve this is by
+ * using `export sealed ledger` hash digests that are initialized in the top-level contract:
+ *
+ * ```compact
+ * import CompactStandardLibrary;
+ * import "./node_modules/@openzeppelin-compact/accessControl/src/AccessControl" prefix AccessControl_;
+ *
+ * export sealed ledger MY_ROLE: Bytes<32>;
+ *
+ * constructor() {
+ *  MY_ROLE = persistentHash<Bytes<32>>(pad(32, "MY_ROLE"));
+ * }
+ * ```
+ *
+ * To restrict access to a circuit, use {assertOnlyRole}:
+ *
+ * ```compact
+ * circuit foo(): [] {
+ *  AccessControl_assertOnlyRole(MY_ROLE);
+ *  // ... rest of circuit logic
+ * }
+ * ```
+ *
+ * Roles can be granted and revoked dynamically via the {grantRole} and
+ * {revokeRole} circuits. Each role has an associated admin role, and only
+ * accounts that have a role's admin role can call {grantRole} and {revokeRole}.
+ *
+ * By default, the admin role for all roles is `DEFAULT_ADMIN_ROLE` (zero bytes), which means
+ * that only accounts with this role will be able to grant or revoke other
+ * roles. More complex role relationships can be created by using
+ * {_setRoleAdmin}.
+ *
+ * WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to
+ * grant and revoke this role. Extra precautions should be taken to secure
+ * accounts that have been granted it.
+ *
+ * @notice Roles can only be granted to Bytes<32> identifiers
+ * through the main role approval circuits (`grantRole` and `_grantRole`).
+ * In other words, role approvals to contract addresses are disallowed through these
+ * circuits.
+ * This is because Compact currently does not support contract-to-contract calls which means
+ * if a contract is granted a role, the contract cannot directly call the protected
+ * circuit.
+ *
+ * @notice This module does offer an experimental circuit that allows roles to be granted
+ * to contract addresses (`_unsafeGrantRole`).
+ * Note that the circuit name is very explicit ("unsafe") with this experimental circuit.
+ * Until contract-to-contract calls are supported,
+ * there is no direct way for a contract to call protected circuits.
+ *
+ * @notice The unsafe circuits are planned to become deprecated once contract-to-contract calls
+ * are supported.
+ *
+ * @dev Migration plan (safe -> C2C-capable role grants)
+ *
+ * The account type is the final `Either<Bytes<32>, ContractAddress>` from day one, in both circuit
+ * signatures and the roles ledger map. This is deliberate. Midnight's upgrade mechanism, the
+ * Contract Maintenance Authority (CMA), can rotate a circuit's verifier key but cannot migrate
+ * ledger state (there is no state-rewrite primitive; see the `updatability` tutorial). Fixing the
+ * type now makes the future migration a pure verifier-key rotation with zero ledger-state change,
+ * which is the only kind of upgrade the CMA supports. Widening the type later would instead force
+ * a ledger-layout rewrite, which the CMA cannot perform.
+ *
+ * When C2C lands, an already-deployed contract migrates without changing its address or ledger
+ * state:
+ *
+ * - Minor release: mark `_unsafeGrantRole` deprecated (and emit a warning if possible); keep its
+ *   implementation intact so existing callers continue to work.
+ * - Major release: ship `grantRole` / `_grantRole` with the `isContract` guard removed and drop
+ *   `_unsafeGrantRole`. Operators adopt the new logic by signing a CMA `MaintenanceUpdate` that
+ *   rotates the affected verifier keys (`VerifierKeyRemove` + `VerifierKeyInsert` for each guarded
+ *   circuit, and a `VerifierKeyRemove` for `_unsafeGrantRole`). The contract address and all ledger
+ *   state are preserved. Because the CMA allows multiple active VK versions per operation, old and
+ *   new keys can coexist during a transition window so in-flight proofs still verify. By this
+ *   point, anyone using `_unsafeGrantRole` should have migrated to the now C2C-capable circuits.
+ *
+ * @dev Security Considerations:
+ * - The `secretKey` must be kept private. Loss of the key prevents role holders
+ *   from proving access. Key exposure allows impersonation.
+ * - It is strongly recommended to use cryptographically secure random values for the secret key
+ *   (e.g., `crypto.getRandomValues()`). Weak or predictable keys can be brute-forced.
+ * - The `secretKey` is provided via the `wit_AccessControlSK` witness. As with all witnesses,
+ *   the contract must not assume that the witness implementation matches the developer's code.
+ *   Any DApp may provide any implementation. The ZK proof system constrains what values
+ *   can produce valid proofs.
+ *
+ * @dev Canonicalization
+ * All `Either<Bytes<32>, ContractAddress>` values used as map keys in `_operatorRoles`
+ * are canonicalized before reads and writes. Canonicalization zeroes out the inactive
+ * branch of the Either, ensuring that two values with the same active branch always
+ * resolve to the same map key regardless of what data the inactive branch carries.
+ * `hasRole` canonicalizes on read. `_unsafeGrantRole` and `_revokeRole` canonicalize
+ * on write. Internal circuits use `_hasRole` which assumes pre-canonicalized inputs.
+ *
+ * @notice Missing Features and Improvements:
+ *
+ * - Role events
+ * - An ERC165-like interface
+ */
+module AccessControl {
+  import CompactStandardLibrary;
+  import "../utils/Utils" prefix Utils_;
+
+  /**
+   * @description Mapping from a role identifier -> account -> its permissions.
+   * @type {Bytes<32>} roleId - A hash representing a role identifier.
+   * @type {Map<Either<Bytes<32>, ContractAddress>, Boolean>} hasRole - A mapping from an account to a
+   * Boolean determining if the account is approved for a role.
+   * @type {Map<roleId, hasRole>}
+   * @type {Map<Bytes<32>, Map<Either<Bytes<32>, ContractAddress>, Boolean>>} _operatorRoles
+   */
+  export ledger _operatorRoles: Map<Bytes<32>,
+                                    Map<Either<Bytes<32>, ContractAddress>, Boolean>>;
+
+  /**
+   * @description Mapping from a role identifier to an admin role identifier.
+   * @type {Bytes<32>} roleId - A hash representing a role identifier.
+   * @type {Bytes<32>} adminId - A hash representing an admin identifier.
+   * @type {Map<roleId, adminId>}
+   * @type {Map<Bytes<32>, Bytes<32>>} _adminRoles
+   */
+  export ledger _adminRoles: Map<Bytes<32>, Bytes<32>>;
+
+  /**
+   * @description The default admin role for all roles. Only accounts with this role will be able
+   * to grant or revoke other roles unless custom admin roles are created via {_setRoleAdmin}.
+   *
+   * @return {Bytes<32>} - The default admin role identifier (zero bytes).
+   */
+  export pure circuit DEFAULT_ADMIN_ROLE(): Bytes<32> {
+    return default<Bytes<32>>;
+  }
+
+  /**
+   * @witness wit_AccessControlSK
+   * @description Returns the caller's secret key used in deriving the account identifier.
+   *
+   * The same key produces the same account identifier across all contracts. Users who
+   * desire cross-contract unlinkability should use different keys per contract.
+   *
+   * @returns {Bytes<32>} secretKey - A 32-byte cryptographically secure random value.
+   */
+  witness wit_AccessControlSK(): Bytes<32>;
+
+  /**
+   * @description Returns `true` if `account` has been granted `roleId`.
+   *
+   * @circuitInfo k=10, rows=1019
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - The account to query.
+   * @return {Boolean} - Whether the account has the specified role.
+    */
+  export circuit hasRole(roleId: Bytes<32>,
+                         account: Either<Bytes<32>, ContractAddress>
+                         ): Boolean {
+    const canonAcct = Utils_canonicalize<Bytes<32>, ContractAddress>(account);
+    return _hasRole(roleId, canonAcct);
+  }
+
+  /**
+   * @description Returns `true` if `account` has been granted `roleId`. Internal variant
+   * that assumes `account` has already been canonicalized by the caller. External consumers
+   * should use {hasRole} which canonicalizes the input automatically.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - The canonicalized account to query.
+   * @return {Boolean} - Whether the account has the specified role.
+   */
+  circuit _hasRole(roleId: Bytes<32>,
+                         account: Either<Bytes<32>, ContractAddress>
+                         ): Boolean {
+    if (_operatorRoles.member(disclose(roleId)) &&
+        _operatorRoles.lookup(roleId).member(disclose(account))) {
+      return _operatorRoles.lookup(roleId).lookup(disclose(account));
+    } else {
+      return false;
+    }
+  }
+
+  /**
+   * @description Reverts if the caller cannot prove ownership of `roleId`.
+   * In the case of an external (non-contract) caller, the caller’s identity is
+   * derived from the `wit_AccessControlSK` witness as `persistentHash(secretKey)`.
+   *
+   * @circuitInfo k=13, rows=2669
+   *
+   * Requirements:
+   *
+   * - The caller must have `roleId`.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit assertOnlyRole(roleId: Bytes<32>): [] {
+    // The account constructed via left<...>() is already canonical,
+    // but we route through _checkRole -> hasRole for consistency.
+    // The redundant canonicalization is negligible.
+    _checkRole(roleId, left<Bytes<32>, ContractAddress>(_computeAccountId()));
+  }
+
+  /**
+   * @description Reverts if `account` is missing `roleId`.
+   *
+   * @circuitInfo k=10, rows=987
+   *
+   * Requirements:
+   *
+   * - `account` must have `roleId`.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - The account to query.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _checkRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): [] {
+    assert(hasRole(roleId, account), "AccessControl: unauthorized account");
+  }
+
+  /**
+   * @description Returns the admin role that controls `roleId` or
+   * a byte array with all zero bytes if `roleId` doesn't exist. See {grantRole} and {revokeRole}.
+   *
+   * To change a role's admin use {_setRoleAdmin}.
+   *
+   * @circuitInfo k=9, rows=373
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @return {Bytes<32>} roleAdmin - The admin role that controls `roleId`.
+   */
+  export circuit getRoleAdmin(roleId: Bytes<32>): Bytes<32> {
+    if (_adminRoles.member(disclose(roleId))) {
+      return _adminRoles.lookup(disclose(roleId));
+    }
+    return DEFAULT_ADMIN_ROLE();
+  }
+
+  /**
+   * @description Grants `roleId` to `account`.
+   *
+   * @circuitInfo k=13, rows=3536
+   *
+   * Requirements:
+   *
+   * - `account` must not be a ContractAddress.
+   * - The caller must have `roleId`'s admin role.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit grantRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): [] {
+    assertOnlyRole(getRoleAdmin(roleId));
+    _grantRole(roleId, account);
+  }
+
+  /**
+   * @description Revokes `roleId` from `account`.
+   *
+   * @circuitInfo k=13, rows=3466
+   *
+   * Requirements:
+   *
+   * - The caller must have `roleId`'s admin role.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit revokeRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): [] {
+    assertOnlyRole(getRoleAdmin(roleId));
+    _revokeRole(roleId, account);
+  }
+
+  /**
+   * @description Revokes `roleId` from the calling account.
+   *
+   * @notice Roles are often managed via {grantRole} and {revokeRole}: this circuit's
+   * purpose is to provide a mechanism for accounts to lose their privileges
+   * if they are compromised (such as when a trusted device is misplaced).
+   *
+   * The caller's identity is derived from the `wit_AccessControlSK` witness as
+   * `persistentHash(secretKey)`. The `callerConfirmation` parameter must match
+   * the caller's computed account identifier to prevent accidental renunciation.
+   *
+   * @circuitInfo k=13, rows=3322
+   *
+   * Requirements:
+   *
+   * - The caller's computed account identifier must match `callerConfirmation`.
+   * - The caller must not be a `ContractAddress`.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} callerConfirmation - The caller's account identifier, must match the internally computed value.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit renounceRole(
+                   roleId: Bytes<32>,
+                   callerConfirmation: Either<Bytes<32>, ContractAddress>
+                   ): [] {
+    assert(callerConfirmation == left<Bytes<32>, ContractAddress>(_computeAccountId()),
+           "AccessControl: bad confirmation"
+           );
+
+    _revokeRole(roleId, callerConfirmation);
+  }
+
+  /**
+   * @description Sets `adminRole` as `roleId`'s admin role.
+   *
+   * @circuitInfo k=10, rows=581
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Bytes<32>} adminRole - The admin role identifier.
+   * @return {[]} - Empty tuple.
+   */
+  export circuit _setRoleAdmin(roleId: Bytes<32>, adminRole: Bytes<32>): [] {
+    _adminRoles.insert(disclose(roleId), disclose(adminRole));
+  }
+
+  /**
+   * @description Attempts to grant `roleId` to `account` and returns a boolean indicating if `roleId` was granted.
+   * Internal circuit without access restriction.
+   *
+   * @circuitInfo k=11, rows=1143
+   *
+   * Requirements:
+   *
+   * - `account` must not be a ContractAddress.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
+   * @return {Boolean} roleGranted - A boolean indicating if `roleId` was granted.
+   */
+  export circuit _grantRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): Boolean {
+    const isCommitment = account.is_left;
+    assert(isCommitment, "AccessControl: unsafe role approval");
+    return _unsafeGrantRole(roleId, account);
+  }
+
+  /**
+   * @description Attempts to grant `roleId` to `account` and returns a boolean indicating if `roleId` was granted.
+   * Internal circuit without access restriction. It does NOT check if the role is granted to a ContractAddress.
+   *
+   * @circuitInfo k=11, rows=1142
+   *
+   * @notice External smart contracts cannot call the access control contract at this time, so granting a role to a ContractAddress may
+   * render a circuit permanently inaccessible.
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
+   * @return {Boolean} roleGranted - A boolean indicating if `role` was granted.
+   */
+  export circuit _unsafeGrantRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): Boolean {
+    const canonAcct = Utils_canonicalize<Bytes<32>, ContractAddress>(account);
+    if (_hasRole(roleId, canonAcct)) {
+      return false;
+    }
+
+    if (!_operatorRoles.member(disclose(roleId))) {
+      _operatorRoles.insert(
+        disclose(roleId),
+        default<Map<Either<Bytes<32>, ContractAddress>, Boolean>>
+        );
+    }
+
+    _operatorRoles.lookup(roleId).insert(disclose(canonAcct), true);
+    return true;
+  }
+
+  /**
+   * @description Attempts to revoke `roleId` from `account` and returns a boolean indicating if `roleId` was revoked.
+   * Internal circuit without access restriction.
+   *
+   * @circuitInfo k=11, rows=1073
+   *
+   * @param {Bytes<32>} roleId - The role identifier.
+   * @param {Either<Bytes<32>, ContractAddress>} account - A Bytes<32> or ContractAddress.
+   * @return {Boolean} roleRevoked - A boolean indicating if `roleId` was revoked.
+   */
+  export circuit _revokeRole(
+                   roleId: Bytes<32>,
+                   account: Either<Bytes<32>, ContractAddress>
+                   ): Boolean {
+    const canonAcct = Utils_canonicalize<Bytes<32>, ContractAddress>(account);
+
+    if (!_hasRole(roleId, canonAcct)) {
+      return false;
+    }
+
+    _operatorRoles.lookup(roleId).insert(disclose(canonAcct), false);
+    return true;
+  }
+
+  /**
+   * @description Computes the caller's account identifier from the `wit_AccessControlSK` witness.
+   *
+   * ## ID Derivation
+   * `accountId = persistentHash(secretKey)`
+   *
+   * The result is a 32-byte commitment that uniquely identifies the caller.
+   *
+   * @circuitInfo k=13, rows=2294
+   *
+   * @returns {Bytes<32>} accountId - The computed account identifier.
+   */
+  circuit _computeAccountId(): Bytes<32> {
+    return computeAccountId(wit_AccessControlSK());
+  }
+
+  /**
+   * @description Computes an account identifier without on-chain state, allowing a user to derive
+   * their identity commitment before submitting it in a grant or revoke operation.
+   * This is the off-chain counterpart to {_computeAccountId} and produces an identical result
+   * given the same inputs.
+   *
+   * @warning OpSec: The `secretKey` parameter is a sensitive secret. Mishandling it can
+   * permanently compromise the privacy guarantees of this system:
+   *
+   * - **Never log or persist** the `secretKey` in plaintext — avoid browser devtools,
+   *   application logs, analytics pipelines, or any observable side-channel.
+   * - **Store offline or in secure enclaves** — hardware security modules (HSMs),
+   *   air-gapped devices, or encrypted vaults are strongly preferred over hot storage.
+   * - **Use cryptographically secure randomness** — generate keys with `crypto.getRandomValues()`
+   *   or equivalent; weak or predictable keys can be brute-forced to reveal your identity.
+   * - **Treat key loss as identity loss** — a lost key cannot be recovered. Back up
+   *   keys securely before using them in role commitments.
+   * - **Avoid calling this circuit in untrusted environments** — executing this in an
+   *   unverified browser extension, compromised runtime, or shared machine may expose
+   *   the key to a malicious observer.
+   *
+   * ## ID Derivation
+   * `accountId = persistentHash(secretKey)`
+   *
+   * @param {Bytes<32>} secretKey - A 32-byte cryptographically secure random value.
+   *
+   * @returns {Bytes<32>} accountId - The computed account identifier.
+   */
+  export pure circuit computeAccountId(secretKey: Bytes<32>): Bytes<32> {
+    return persistentHash<Vector<1, Bytes<32>>>([secretKey]);
+  }
+}