@openzeppelin/compact-contracts 0.4.0-alpha.1 → 0.4.0-alpha.2

package/multisig/Signer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/Signer.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/Signer.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -37,78 +37,41 @@ pragma language_version >= 0.26.0;
  * _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.
+ * The module has no `initialize`. The consuming contract, or a manager module
+ * wrapping this one, registers signers with `_addSigner` and sets the
+ * threshold with `_changeThreshold` / `_setThreshold`, either from the
+ * constructor or behind its own authorization policy. Leaving them ungated
+ * lets the first caller register their own signer set and take control of
+ * the contract.
  *
- * `_isInitialized` records only whether `initialize` has run; it gates
- * re-entry into `initialize` and nothing else. No other circuit consults it,
- * so a contract that configures signers through its own flow
- * (`_addSigner` / `_setThreshold`) is fully functional without ever calling
- * `initialize`. Provided it gates those circuits behind its own
- * authorization policy. Leaving them ungated lets the first caller register
- * their own signer set and take control of the contract.
- *
- * @notice Not asserting initialization on the guard and view circuits is a
- * deliberate divergence from the other modules in this library, which do.
- * Those modules gate a zero-valued identity (an owner, a role holder); this
- * one gates an empty collection, which rejects by absence. Safety here comes
- * from the state rather than from a flag: an empty registry makes `isSigner`
+ * @notice The guard and view circuits carry no "configured" flag, a
+ * deliberate divergence from the other modules in this library. Those gate a
+ * zero-valued identity (an owner, a role holder); this one gates an empty
+ * collection, which rejects by absence. An empty registry makes `isSigner`
  * false for every input, so `assertSigner` rejects every caller, and a zero
  * `_threshold` makes `assertThresholdMet` reject before it compares any
- * approval count regardless of how the threshold came to be zero. Contracts
- * needing a "configured" signal beyond that should track one at the contract
- * layer.
+ * approval count. Contracts needing a "configured" signal beyond that should
+ * track one at the contract layer.
  */
 module Signer<T> {
   import CompactStandardLibrary;
 
   // ─── State ──────────────────────────────────────────────────────────────────
 
+  /**
+   * @description The registered signer set. `T` is chosen by the consuming
+   * contract, so a signer is whatever identity that contract authenticates.
+   */
   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.
+   * @description The number of registered signers.
    */
-  export ledger _isInitialized: Boolean;
-
-  // ─── Initialization ─────────────────────────────────────────────────────────
-
+  export ledger _signerCount: Uint<8>;
   /**
-   * @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.
-   *
-   * 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.
+   * @description How many approvals an action requires. Never zero once set,
+   * and removals that would drop `_signerCount` below it are rejected.
    */
-  export circuit initialize<#n>(
-    signers: Vector<n, T>,
-    thresh: Uint<8>
-  ): [] {
-    assertNotInitialized();
-    _isInitialized = true;
-
-    for (const signer of signers) {
-      _addSigner(signer);
-    }
-
-    _changeThreshold(thresh);
-  }
+  export ledger _threshold: Uint<8>;
 
   // ─── Guards ─────────────────────────────────────────────────────────────
 
@@ -140,7 +103,7 @@ module Signer<T> {
    * the remaining signers satisfy, and bounding the count would reject those.
    * See the stale-signer-set guidance in the module header.
    *
-   * @circuitInfo k=9, rows=54
+   * @constraints k=9, rows=52
    *
    * Requirements:
    *
@@ -162,7 +125,7 @@ module Signer<T> {
    * @description Returns the current signer count. Returns zero when no
    * signers have been registered.
    *
-   * @circuitInfo k=6, rows=26
+   * @constraints k=6, rows=24
    *
    * @returns {Uint<8>} The number of active signers.
    */
@@ -174,7 +137,7 @@ module Signer<T> {
    * @description Returns the approval threshold. Returns zero when the
    * threshold has not been set.
    *
-   * @circuitInfo k=6, rows=26
+   * @constraints k=6, rows=24
    *
    * @returns {Uint<8>} The threshold.
    */
@@ -250,7 +213,7 @@ module Signer<T> {
    * The consuming contract must gate this behind its own
    * authorization policy.
    *
-   * @circuitInfo k=9, rows=53
+   * @constraints k=9, rows=51
    *
    * Requirements:
    *
@@ -285,7 +248,7 @@ module Signer<T> {
    * authorization policy. Use `_changeThreshold` for
    * operational threshold changes with signer count validation.
    *
-   * @circuitInfo k=6, rows=40
+   * @constraints k=6, rows=38
    *
    * Requirements:
    *
@@ -298,19 +261,4 @@ module Signer<T> {
     assert(newThreshold != 0, "Signer: threshold must not be zero");
     _threshold = disclose(newThreshold);
   }
-
-  // ─── Init guards ─────────────────────────────────────────────────────────
-
-  /**
-   * @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/UnshieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/UnshieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/UnshieldedTreasury.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -37,6 +37,14 @@ module UnshieldedTreasury {
 
   // ─── State ──────────────────────────────────────────────────────
 
+  /**
+   * @description The treasury's tracked balance per token color. Deposits add
+   * to it and sends subtract.
+   * @type {Bytes<32>} color - The token color.
+   * @type {Uint<128>} balance - The amount currently held of it.
+   * @type {Map<color, balance>}
+   * @type {Map<Bytes<32>, Uint<128>>} _balances
+   */
   export ledger _balances: Map<Bytes<32>, Uint<128>>;
 
   // ─── Deposit ────────────────────────────────────────────────────

package/multisig/{presets/forwarder/ForwarderPrivate.compact → examples/ForwarderPrivateExample.compact}

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/presets/forwarder/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/examples/ForwarderPrivateExample.compact)
 
 pragma language_version >= 0.26.0;
 
 /**
- * @title ForwarderPrivate
+ * @title ForwarderPrivateExample
  * @description Private-parent forwarder. The parent address is hidden
  * behind a `persistentHash` commitment on the ledger. Coins dwell at
  * the contract address after deposit; the operator drains them later
@@ -22,7 +22,7 @@ pragma language_version >= 0.26.0;
  */
 
 import CompactStandardLibrary;
-import "../../ForwarderPrivate" prefix ForwarderPrivate_;
+import "../ForwarderPrivate" prefix ForwarderPrivate_;
 
 export { ShieldedCoinInfo, QualifiedShieldedCoinInfo, ShieldedSendResult, ZswapCoinPublicKey };
 

package/multisig/{presets/forwarder/ForwarderShielded.compact → examples/ForwarderShieldedExample.compact}

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/presets/forwarder/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/examples/ForwarderShieldedExample.compact)
 
 pragma language_version >= 0.26.0;
 
 /**
- * @title ForwarderShielded
+ * @title ForwarderShieldedExample
  * @description Public-parent forwarder for shielded coins. Receives a
  * shielded coin and atomically forwards it to the configured parent
  * recipient, a coin public key.
@@ -22,7 +22,7 @@ pragma language_version >= 0.26.0;
  */
 
 import CompactStandardLibrary;
-import "../../ForwarderShielded" prefix Forwarder_;
+import "../ForwarderShielded" prefix Forwarder_;
 
 export { ZswapCoinPublicKey, ContractAddress, ShieldedCoinInfo, Either };
 

package/multisig/{presets/forwarder/ForwarderUnshielded.compact → examples/ForwarderUnshieldedExample.compact}

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/presets/forwarder/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/examples/ForwarderUnshieldedExample.compact)
 
 pragma language_version >= 0.26.0;
 
 /**
- * @title ForwarderUnshielded
+ * @title ForwarderUnshieldedExample
  * @description Public-parent forwarder for unshielded coins. Receives
  * an unshielded amount of a given color and atomically forwards it to
  * the configured parent recipient, a user address.
@@ -24,7 +24,7 @@ pragma language_version >= 0.26.0;
  */
 
 import CompactStandardLibrary;
-import "../../ForwarderUnshielded" prefix Forwarder_;
+import "../ForwarderUnshielded" prefix Forwarder_;
 
 export { ContractAddress, UserAddress, Either };
 

package/multisig/examples/NativeShieldedTokenIssuerExample.compact

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/examples/NativeShieldedTokenIssuerExample.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @title NativeShieldedTokenIssuerExample
+ * @description Deployable reference contract for the `NativeShieldedTokenIssuer`
+ * preset: a native shielded token whose supply enters only through an
+ * ECDSA-authorized mint and leaves only through an ECDSA-authorized burn.
+ *
+ * The token is non-transferable by construction. There is no transfer circuit,
+ * so a holder's only exit is to present the coin back for burn.
+ */
+
+import CompactStandardLibrary;
+
+import "../presets/NativeShieldedTokenIssuer" prefix NativeShieldedTokenIssuer_;
+
+export { ZswapCoinPublicKey, ContractAddress, Either, Maybe };
+export { ShieldedCoinInfo, QualifiedShieldedCoinInfo };
+
+// Surface the preset's state unprefixed so `ledger()` readers use the keys the
+// modules declare.
+import {
+  _counter,
+  _domainSeparator,
+  _derivedNonceCounter,
+  _instanceSalt,
+  _signers,
+  _signerCount,
+  _threshold,
+  _domain,
+  _name,
+  _symbol,
+  _decimals,
+  _isInitialized,
+} from "../presets/NativeShieldedTokenIssuer";
+export {
+  _counter,
+  _domainSeparator,
+  _derivedNonceCounter,
+  _instanceSalt,
+  _signers,
+  _signerCount,
+  _threshold,
+  _domain,
+  _name,
+  _symbol,
+  _decimals,
+  _isInitialized,
+};
+
+/**
+ * @description Deploys the issuer with 3 signer commitments, a threshold
+ * of 2, and the token's domain and metadata.
+ *
+ * Requirements:
+ *
+ * - `signerCommitments` must not contain duplicates.
+ * - `instanceSalt` should be cryptographically random.
+ *
+ * @param {Bytes<32>} instanceSalt - Random salt for signer commitment derivation.
+ * @param {Bytes<32>} tokenDomain - Domain separator for this contract's token color.
+ * @param {Opaque<"string">} name_ - The token name.
+ * @param {Opaque<"string">} symbol_ - The token symbol.
+ * @param {Uint<8>} decimals_ - The token decimals.
+ * @param {Vector<3, Bytes<32>>} signerCommitments - Hashed signer identities.
+ */
+constructor(
+  instanceSalt: Bytes<32>,
+  tokenDomain: Bytes<32>,
+  name_: Opaque<"string">,
+  symbol_: Opaque<"string">,
+  decimals_: Uint<8>,
+  signerCommitments: Vector<3, Bytes<32>>,
+) {
+  NativeShieldedTokenIssuer_initialize(
+    instanceSalt,
+    tokenDomain,
+    name_,
+    symbol_,
+    decimals_,
+    signerCommitments,
+  );
+}
+
+export pure circuit _calculateSignerId(
+  pk: Secp256k1Point,
+  salt: Bytes<32>
+): Bytes<32> {
+  return NativeShieldedTokenIssuer__calculateSignerId(pk, salt);
+}
+
+export circuit mint(
+  amount: Uint<64>,
+  recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+  pubkeys: Vector<2, Secp256k1Point>,
+  signatures: Vector<2, Secp256k1EcdsaSignature>
+): ShieldedCoinInfo {
+  return NativeShieldedTokenIssuer_mint(amount, recipient, pubkeys, signatures);
+}
+
+export circuit burn(
+  coin: QualifiedShieldedCoinInfo,
+  amount: Uint<64>,
+  pubkeys: Vector<2, Secp256k1Point>,
+  signatures: Vector<2, Secp256k1EcdsaSignature>
+): Maybe<ShieldedCoinInfo> {
+  return NativeShieldedTokenIssuer_burn(coin, amount, pubkeys, signatures);
+}
+
+export circuit getNonce(): Uint<64> {
+  return NativeShieldedTokenIssuer_getNonce();
+}
+
+export circuit name(): Opaque<"string"> {
+  return NativeShieldedTokenIssuer_name();
+}
+
+export circuit symbol(): Opaque<"string"> {
+  return NativeShieldedTokenIssuer_symbol();
+}
+
+export circuit decimals(): Uint<8> {
+  return NativeShieldedTokenIssuer_decimals();
+}
+
+export circuit tokenColor(): Bytes<32> {
+  return NativeShieldedTokenIssuer_tokenColor();
+}
+
+export circuit getSignerCount(): Uint<8> {
+  return NativeShieldedTokenIssuer_getSignerCount();
+}
+
+export circuit getThreshold(): Uint<8> {
+  return NativeShieldedTokenIssuer_getThreshold();
+}
+
+export circuit isSigner(commitment: Bytes<32>): Boolean {
+  return NativeShieldedTokenIssuer_isSigner(commitment);
+}

package/multisig/examples/ShieldedMultiSigV2Example.compact

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.4.0-alpha.2 (multisig/examples/ShieldedMultiSigV2Example.compact)
+
+pragma language_version >= 0.26.0;
+
+/**
+ * @title ShieldedMultiSigV2Example
+ * @description Deployable reference contract for the `ShieldedMultiSigV2`
+ * preset: a 2-of-3 wallet whose spends are authorized by ECDSA signatures
+ * collected off-chain and verified in a single transaction.
+ *
+ * Coin data never reaches the public ledger. The operator tracks the wallet's
+ * UTXOs off-chain and passes the coin to spend as a circuit argument.
+ */
+
+import CompactStandardLibrary;
+
+import "../presets/ShieldedMultiSigV2" prefix ShieldedMultiSigV2_;
+
+export { ShieldedCoinInfo, QualifiedShieldedCoinInfo, ShieldedSendResult };
+
+// Surface the preset's domain separator unprefixed so `ledger()` readers see
+// the key name the preset published.
+import { _domainSeparator } from "../presets/ShieldedMultiSigV2";
+export { _domainSeparator };
+
+/**
+ * @description Deploys the wallet with 3 signer commitments and a threshold.
+ *
+ * @param {Bytes<32>} instanceSalt - Random salt for commitment derivation.
+ * @param {Vector<3, Bytes<32>>} signerCommitments - Hashed signer identities.
+ * @param {Uint<8>} thresh - Minimum approvals required.
+ */
+constructor(
+  instanceSalt: Bytes<32>,
+  signerCommitments: Vector<3, Bytes<32>>,
+  thresh: Uint<8>,
+) {
+  ShieldedMultiSigV2_initialize(instanceSalt, signerCommitments, thresh);
+}
+
+export circuit deposit(coin: ShieldedCoinInfo): [] {
+  return ShieldedMultiSigV2_deposit(coin);
+}
+
+export circuit execute(
+  to: ShieldedMultiSigV2_Proposal_Recipient,
+  amount: Uint<128>,
+  coin: QualifiedShieldedCoinInfo,
+  pubkeys: Vector<2, Secp256k1Point>,
+  signatures: Vector<2, Secp256k1EcdsaSignature>
+): ShieldedSendResult {
+  return ShieldedMultiSigV2_execute(to, amount, coin, pubkeys, signatures);
+}
+
+export pure circuit _calculateSignerId(
+  pk: Secp256k1Point,
+  salt: Bytes<32>
+): Bytes<32> {
+  return ShieldedMultiSigV2__calculateSignerId(pk, salt);
+}
+
+export circuit getNonce(): Uint<64> {
+  return ShieldedMultiSigV2_getNonce();
+}
+
+export circuit getSignerCount(): Uint<8> {
+  return ShieldedMultiSigV2_getSignerCount();
+}
+
+export circuit getThreshold(): Uint<8> {
+  return ShieldedMultiSigV2_getThreshold();
+}
+
+export circuit isSigner(commitment: Bytes<32>): Boolean {
+  return ShieldedMultiSigV2_isSigner(commitment);
+}