@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha

package/multisig/Signer.compact

@@ -0,0 +1,312 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/Signer.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module Signer<T>
+ * @description Manages signer registry, threshold enforcement, and signer
+ * validation for multisig governance contracts.
+ *
+ * Parameterized over the signer identity type `T`, allowing the consuming
+ * contract to choose the identity mechanism at import time. Common
+ * instantiations include:
+ *
+ * - `Bytes<32>` for commitment-based identity (e.g., hash of ECDSA public key)
+ * - `JubjubPoint` for Schnorr/MuSig aggregated key
+ *
+ * The Signer module does not resolve caller identity. It receives a validated
+ * caller from the contract layer and checks it against the registry.
+ * This separation allows the identity mechanism to change without
+ * modifying the module.
+ *
+ * The signer count and threshold are of type `Uint<8>`, limiting the
+ * maximum number of signers and threshold to 255. This is sufficient
+ * for any practical multisig use case. For large-scale governance
+ * requiring more signers, consider a Merkle tree-based variant.
+ *
+ * Multi-step signer reconfigurations (e.g., removing a signer and
+ * lowering the threshold) may produce intermediate states where the
+ * module's invariants temporarily hold but the contract's intended
+ * configuration is incomplete. This is a contract-layer concern.
+ * Contracts should either perform reconfigurations atomically in a
+ * single circuit or use a configuration nonce to invalidate proposals
+ * created under a stale signer set.
+ *
+ * Underscore-prefixed circuits (_addSigner, _removeSigner,
+ * _changeThreshold) have no access control enforcement. The consuming
+ * contract must gate these behind its own authorization policy.
+ *
+ * Contracts may handle their own initialization and this module
+ * supports custom flows. Thus, contracts may choose to not
+ * call `initialize` in the contract's constructor. Contracts MUST NOT
+ * call `initialize` outside of the constructor context because
+ * this could corrupt the signer set and threshold configuration.
+ */
+module Signer<T> {
+  import CompactStandardLibrary;
+
+  // ─── State ──────────────────────────────────────────────────────────────────
+
+  export ledger _signers: Set<T>;
+  export ledger _signerCount: Uint<8>;
+  export ledger _threshold: Uint<8>;
+
+  /**
+   * @description Initialization flag, tracked per-module to avoid the compiler's
+   * shared transitive-dependency state bug (LFDT-Minokawa/compact#270). See the
+   * Initializable module for rationale.
+   */
+  export ledger _isInitialized: Boolean;
+
+  // ─── Initialization ─────────────────────────────────────────────────────────
+
+  /**
+   * @description Initializes the signer module with the given threshold
+   * and an initial set of signers.
+   * If used, it should only be called in the contract's constructor.
+   *
+   * @circuitInfo k=11, rows=1815
+   *
+   * Requirements:
+   *
+   * - If used, can only be called once (in the constructor).
+   * - `thresh` must not be zero.
+   * - `thresh` must not exceed the number of `signers`.
+   * - `signers` must not contain duplicates.
+   *
+   * @param {Vector<n, T>} signers - The initial signer set.
+   * @param {Uint<8>} thresh - The minimum number of approvals required.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize<#n>(
+    signers: Vector<n, T>,
+    thresh: Uint<8>
+  ): [] {
+    assertNotInitialized();
+    _isInitialized = true;
+
+    for (const signer of signers) {
+      _addSigner(signer);
+    }
+
+    _changeThreshold(thresh);
+  }
+
+  // ─── Guards ─────────────────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that the given caller is an active signer.
+   *
+   * @circuitInfo k=10, rows=585
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   * - `caller` must be a member of the signers registry.
+   *
+   * @param {T} caller - The identity to validate.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertSigner(caller: T): [] {
+    assertInitialized();
+    assert(isSigner(caller), "Signer: not a signer");
+  }
+
+  /**
+   * @description Asserts that the given approval count meets the threshold.
+   *
+   * @circuitInfo k=9, rows=54
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   * - Ledger threshold must be set (not be zero).
+   * - `approvalCount` must be >= threshold.
+   *
+   * @param {Uint<8>} approvalCount - The current number of approvals.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertThresholdMet(approvalCount: Uint<8>): [] {
+    assertInitialized();
+    assert(_threshold != 0, "Signer: threshold not set");
+    assert(approvalCount >= _threshold, "Signer: threshold not met");
+  }
+
+  // ─── View ──────────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the current signer count.
+   *
+   * @circuitInfo k=6, rows=26
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @returns {Uint<8>} The number of active signers.
+   */
+  export circuit getSignerCount(): Uint<8> {
+    assertInitialized();
+    return _signerCount;
+  }
+
+  /**
+   * @description Returns the approval threshold.
+   *
+   * @circuitInfo k=6, rows=26
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @returns {Uint<8>} The threshold.
+   */
+  export circuit getThreshold(): Uint<8> {
+    assertInitialized();
+    return _threshold;
+  }
+
+  /**
+   * @description Returns whether the given account is an active signer.
+   *
+   * @circuitInfo k=10, rows=605
+   *
+   * @param {T} account - The account to check.
+   * @returns {Boolean} True if the account is an active signer.
+   */
+  export circuit isSigner(account: T): Boolean {
+    return _signers.member(disclose(account));
+  }
+
+  // ─── Signer Management ─────────────────────────────────────────────────────
+
+  /**
+   * @description Adds a new signer to the registry.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * @circuitInfo k=10, rows=598
+   *
+   * Requirements:
+   *
+   * - `signer` must not already be an active signer.
+   *
+   * @param {T} signer - The signer to add.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _addSigner(signer: T): [] {
+    assert(
+      !isSigner(signer),
+      "Signer: signer already active"
+    );
+
+    _signers.insert(disclose(signer));
+    _signerCount = _signerCount + 1 as Uint<8>;
+  }
+
+  /**
+   * @description Removes a signer from the registry.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * @circuitInfo k=10, rows=612
+   *
+   * Requirements:
+   *
+   * - `signer` must be an active signer.
+   * - Removal must not drop signer count below threshold.
+   *
+   * @param {T} signer - The signer to remove.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _removeSigner(signer: T): [] {
+    assert(isSigner(signer), "Signer: not a signer");
+
+    const newCount = _signerCount - 1 as Uint<8>;
+    assert(newCount >= _threshold, "Signer: removal would breach threshold");
+
+    _signers.remove(disclose(signer));
+    _signerCount = newCount;
+  }
+
+  /**
+   * @description Updates the approval threshold.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * @circuitInfo k=9, rows=53
+   *
+   * Requirements:
+   *
+   * - `newThreshold` must not be zero.
+   * - `newThreshold` must not exceed the current signer count.
+   *
+   * @param {Uint<8>} newThreshold - The new minimum number of approvals required.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _changeThreshold(newThreshold: Uint<8>): [] {
+    assert(newThreshold <= _signerCount, "Signer: threshold exceeds signer count");
+    _setThreshold(newThreshold);
+  }
+
+  /**
+   * @description Sets the approval threshold without checking
+   * against the current signer count.
+   *
+   * @warning This is intended for use during contract construction
+   * or custom setup flows where signers may not yet be registered.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy. Use `_changeThreshold` for
+   * operational threshold changes with signer count validation.
+   *
+   * @circuitInfo k=6, rows=40
+   *
+   * Requirements:
+   *
+   * - `newThreshold` must not be zero.
+   *
+   * @param {Uint<8>} newThreshold - The minimum number of approvals required.
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _setThreshold(newThreshold: Uint<8>): [] {
+    assert(newThreshold != 0, "Signer: threshold must not be zero");
+    _threshold = disclose(newThreshold);
+  }
+
+  // ─── Init guards ─────────────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that the contract has been initialized, throwing an error if not.
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  circuit assertInitialized(): [] {
+    assert(_isInitialized, "Signer: contract not initialized");
+  }
+
+  /**
+   * @description Asserts that the contract has not been initialized, throwing an error if it has.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   *
+   * @return {[]} - Empty tuple.
+   */
+  circuit assertNotInitialized(): [] {
+    assert(!_isInitialized, "Signer: contract already initialized");
+  }
+}

package/multisig/SignerManager.compact

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/SignerManager.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module SignerManager<T>
+ * @description Manages signer registry, threshold enforcement, and signer
+ * validation for multisig governance contracts.
+ *
+ * Parameterized over the signer identity type `T`, allowing the consuming
+ * contract to choose the identity mechanism at import time. Common
+ * instantiations include:
+ *
+ * - `Either<ZswapCoinPublicKey, ContractAddress>` for ownPublicKey()-based identity
+ * - `Bytes<32>` for commitment-based identity (e.g., hash of ECDSA public key)
+ * - `NativePoint` for Schnorr/MuSig aggregated key
+ *
+ * SignerManager does not resolve caller identity. It receives a validated
+ * caller from the contract layer and checks it against the registry.
+ * This separation allows the identity mechanism to change without
+ * modifying the module.
+ *
+ * Underscore-prefixed circuits (_addSigner, _removeSigner,
+ * _changeThreshold) have no access control enforcement. The consuming
+ * contract must gate these behind its own authorization policy.
+ */
+module SignerManager<T> {
+  import CompactStandardLibrary;
+
+  // ─── State ──────────────────────────────────────────────────────────────────
+
+  export ledger _signers: Set<T>;
+  export ledger _signerCount: Uint<8>;
+  export ledger _threshold: Uint<8>;
+
+  // ─── Initialization ─────────────────────────────────────────────────────────
+
+  /**
+   * @description Initializes the signer manager with the given threshold
+   * and an initial set of signers.
+   * Must be called in the contract's constructor.
+   *
+   * Requirements:
+   *
+   * - `thresh` must be greater than 0.
+   * - `signers` must not contain duplicates.
+   *
+   * @param {Vector<n, T>} signers - The initial signer set.
+   * @param {Uint<8>} thresh - The minimum number of approvals required.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize<#n>(
+    signers: Vector<n, T>,
+    thresh: Uint<8>
+  ): [] {
+    assert(thresh > 0, "SignerManager: threshold must be > 0");
+    _threshold = disclose(thresh);
+
+    for (const signer of signers) {
+      _addSigner(signer);
+    }
+
+    assert(_signerCount >= thresh, "SignerManager: threshold exceeds signer count");
+  }
+
+  // ─── Guards ─────────────────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that the given caller is an active signer.
+   *
+   * Requirements:
+   *
+   * - `caller` must be a member of the signers registry.
+   *
+   * @param {T} caller - The identity to validate.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertSigner(caller: T): [] {
+    assert(isSigner(caller), "SignerManager: not a signer");
+  }
+
+  /**
+   * @description Asserts that the given approval count meets the threshold.
+   *
+   * Requirements:
+   *
+   * - `approvalCount` must be >= threshold.
+   *
+   * @param {Uint<8>} approvalCount - The current number of approvals.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertThresholdMet(approvalCount: Uint<8>): [] {
+    assert(approvalCount >= _threshold, "SignerManager: threshold not met");
+  }
+
+  // ─── View ──────────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the current signer count.
+   *
+   * @returns {Uint<8>} The number of active signers.
+   */
+  export circuit getSignerCount(): Uint<8> {
+    return _signerCount;
+  }
+
+  /**
+   * @description Returns the approval threshold.
+   *
+   * @returns {Uint<8>} The threshold.
+   */
+  export circuit getThreshold(): Uint<8> {
+    return _threshold;
+  }
+
+  /**
+   * @description Returns whether the given account is an active signer.
+   *
+   * @param {T} account - The account to check.
+   *
+   * @returns {Boolean} True if the account is an active signer.
+   */
+  export circuit isSigner(account: T): Boolean {
+    return _signers.member(disclose(account));
+  }
+
+  // ─── Signer Management ─────────────────────────────────────────────────────
+
+  /**
+   * @description Adds a new signer to the registry.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - `signer` must not already be an active signer.
+   *
+   * @param {T} signer - The signer to add.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _addSigner(signer: T): [] {
+    assert(
+      !isSigner(signer),
+      "SignerManager: signer already active"
+    );
+
+    _signers.insert(disclose(signer));
+    _signerCount = _signerCount + 1 as Uint<8>;
+  }
+
+  /**
+   * @description Removes a signer from the registry.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - `signer` must be an active signer.
+   * - Removal must not drop signer count below threshold.
+   *
+   * @param {T} signer - The signer to remove.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _removeSigner(signer: T): [] {
+    assert(isSigner(signer), "SignerManager: not a signer");
+
+    const newCount = _signerCount - 1 as Uint<8>;
+    assert(newCount >= _threshold, "SignerManager: removal would breach threshold");
+
+    _signers.remove(disclose(signer));
+    _signerCount = newCount;
+  }
+
+  /**
+   * @description Updates the approval threshold.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - `newThreshold` must be greater than 0.
+   * - `newThreshold` must not exceed the current signer count.
+   *
+   * @param {Uint<8>} newThreshold - The new minimum number of approvals required.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _changeThreshold(newThreshold: Uint<8>): [] {
+    assert(newThreshold > 0, "SignerManager: threshold must be > 0");
+    assert(newThreshold <= _signerCount, "SignerManager: threshold exceeds signer count");
+    _threshold = disclose(newThreshold);
+  }
+}

package/multisig/UnshieldedTreasury.compact

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/UnshieldedTreasury.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module UnshieldedTreasury
+ * @description Manages unshielded (transparent) token deposits and
+ * transfers for multisig governance contracts.
+ *
+ * Balances are tracked per token color in a single map. Protocol-level
+ * balance comparison circuits (`unshieldedBalanceLte`,
+ * `unshieldedBalanceGte`) are used for overflow and sufficiency checks,
+ * avoiding the exact-match problem of `unshieldedBalance`.
+ *
+ * Underscore-prefixed circuits (_deposit, _send) have no access control
+ * enforcement. The consuming contract must gate these behind its own
+ * authorization policy.
+ */
+module UnshieldedTreasury {
+  import CompactStandardLibrary;
+  import { UINT128_MAX } from "../utils/Utils" prefix Utils_;
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  export ledger _balances: Map<Bytes<32>, Uint<128>>;
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @description Receives unshielded tokens into the treasury.
+   *
+   * The token receive is executed at the protocol level first via
+   * `receiveUnshielded`. The balance map is then updated.
+   *
+   * Zero-value deposits are permitted. While currently a no-op
+   * economically, they may serve as signaling mechanisms when events
+   * are supported.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - Deposit must not cause balance overflow.
+   *
+   * @param {Bytes<32>} color - The token type identifier.
+   * @param {Uint<128>} amount - The amount to deposit.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _deposit(color: Bytes<32>, amount: Uint<128>): [] {
+    assert(
+      unshieldedBalanceLte(disclose(color), Utils_UINT128_MAX() - disclose(amount)),
+      "UnshieldedTreasury: overflow"
+    );
+
+    receiveUnshielded(disclose(color), disclose(amount));
+
+    const bal = getTokenBalance(color);
+    _balances.insert(disclose(color), disclose(bal + amount as Uint<128>));
+  }
+
+  // ─── Send ───────────────────────────────────────────────────────
+
+  /**
+   * @description Sends unshielded tokens from the treasury.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - The treasury must hold sufficient balance for the given token color.
+   *
+   * @param {Either<ContractAddress, UserAddress>} recipient - The recipient address.
+   * @param {Bytes<32>} color - The token type identifier.
+   * @param {Uint<128>} amount - The amount to send.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _send(
+    recipient: Either<ContractAddress, UserAddress>,
+    color: Bytes<32>,
+    amount: Uint<128>
+  ): [] {
+    assert(
+      unshieldedBalanceGte(disclose(color), disclose(amount)),
+      "UnshieldedTreasury: insufficient balance"
+    );
+
+    const bal = getTokenBalance(color);
+    _balances.insert(disclose(color), disclose(bal - amount as Uint<128>));
+    sendUnshielded(disclose(color), disclose(amount), disclose(recipient));
+  }
+
+  // ─── View ───────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the balance for a given token color.
+   *
+   * @param {Bytes<32>} color - The token type identifier.
+   *
+   * @returns {Uint<128>} The current balance.
+   */
+  export circuit getTokenBalance(color: Bytes<32>): Uint<128> {
+    if (!_balances.member(disclose(color))) {
+      return 0;
+    }
+    return _balances.lookup(disclose(color));
+  }
+}