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

package/multisig/EcdsaSignerManager.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/EcdsaSignerManager.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/EcdsaSignerManager.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -13,23 +13,34 @@ pragma language_version >= 0.26.0;
  * The salt is per-deployment, so the same public key yields a different
  * commitment in every instance and cannot be correlated across contracts.
  *
- * Wraps `Signer<Bytes<32>>` for the registry and threshold. Consuming
- * contracts own the digest: they compute the message hash their signers
- * signed, then hand it to `assertApprovals` with the parallel public-key and
- * signature vectors.
+ * Wraps `Signer<Bytes<32>>` for the registry and threshold and configures it
+ * from `initialize`. Consuming contracts own the digest: they compute the
+ * message hash their signers signed, then hand it to `assertApprovals` with
+ * the parallel public-key and signature vectors.
  *
- * The module's ledger is not exported, so a contract importing it under a
- * prefix keeps the salt and the signer registry out of its generated
- * `ledger()` reader.
+ * @notice Consuming contracts must not import `Signer` alongside this module.
+ * A second import instantiates a separate registry that `assertApprovals`
+ * never reads.
  */
 module EcdsaSignerManager {
   import CompactStandardLibrary;
   import "../crypto/Ecdsa" prefix Ecdsa_;
   import "./Signer"<Bytes<32>> prefix Signer_;
 
+  // Named import/re-export of the registry state only, so a consuming
+  // contract's ledger keys read as `_signers` rather than `Signer__signers`.
+  // The circuits stay behind the `Signer_` prefix.
+  import { _signers, _signerCount, _threshold } from "./Signer"<Bytes<32>>;
+  export { _signers, _signerCount, _threshold };
+
   // ─── State ──────────────────────────────────────────────────────────────────
 
-  ledger _instanceSalt: Bytes<32>;
+  /**
+   * @description Deployment-supplied salt for signer commitments. Set at
+   * initialization and never changed. The registered commitments must have been
+   * derived under this same salt.
+   */
+  export sealed ledger _instanceSalt: Bytes<32>;
 
   // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -58,7 +69,8 @@ module EcdsaSignerManager {
 
   /**
    * @description Stores the instance salt and registers the initial signer set.
-   * Call from the consuming contract's constructor only.
+   * Call from the consuming contract's constructor only. Writes the `sealed`
+   * salt, so it cannot be reached from an exported circuit.
    *
    * Requirements:
    *
@@ -79,9 +91,14 @@ module EcdsaSignerManager {
     signerCommitments: Vector<n, Bytes<32>>,
     threshold: Uint<8>
   ): [] {
+    assert(Signer_getSignerCount() == 0, "EcdsaSignerManager: signers already registered");
     _instanceSalt = disclose(instanceSalt);
     assert(threshold <= 2, "EcdsaSignerManager: threshold cannot exceed 2 (assertApprovals verifies 2 signatures)");
-    Signer_initialize<n>(signerCommitments, threshold);
+
+    for (const commitment of signerCommitments) {
+      Signer__addSigner(commitment);
+    }
+    Signer__changeThreshold(threshold);
   }
 
   // ─── Commitments ────────────────────────────────────────────────────────────
@@ -125,7 +142,7 @@ module EcdsaSignerManager {
    * @dev Both entries are asserted, so the count handed to the threshold check
    * is always 2 and a threshold below 2 admits nothing extra.
    *
-   * @circuitInfo k=17, rows=64916
+   * @constraints k=17, rows=64916 (zkir-v3)
    *
    * Requirements:
    *
@@ -196,7 +213,7 @@ module EcdsaSignerManager {
   /**
    * @description Returns the number of registered signers.
    *
-   * @circuitInfo k=6, rows=34
+   * @constraints k=6, rows=34 (zkir-v3)
    *
    * @returns {Uint<8>} The signer count.
    */
@@ -207,7 +224,7 @@ module EcdsaSignerManager {
   /**
    * @description Returns the approval threshold.
    *
-   * @circuitInfo k=6, rows=34
+   * @constraints k=6, rows=34 (zkir-v3)
    *
    * @returns {Uint<8>} The threshold.
    */
@@ -218,7 +235,7 @@ module EcdsaSignerManager {
   /**
    * @description Returns whether the given commitment is a registered signer.
    *
-   * @circuitInfo k=8, rows=129
+   * @constraints k=8, rows=129 (zkir-v3)
    *
    * @param {Bytes<32>} commitment - The signer commitment to check.
    * @returns {Boolean} True if registered.

package/multisig/ForwarderPrivate.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ForwarderPrivate.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ForwarderPrivate.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -33,6 +33,12 @@ module ForwarderPrivate {
 
   // ─── State ──────────────────────────────────────────────────────
 
+  /**
+   * @description Commitment to `(parentAddr, opSecret)`, published in place of
+   * the parent itself. A caller proves knowledge of both. The parent key alone
+   * is not secret, so `opSecret` supplies the hiding: without it a candidate
+   * parent could be hashed and matched against this value.
+   */
   export ledger _parentCommitment: Bytes<32>;
 
   /**
@@ -76,7 +82,7 @@ module ForwarderPrivate {
    * @description Receives a shielded coin into the forwarder's custody.
    * No ledger write — coins dwell at the contract address until drained.
    *
-   * @circuitInfo k=13, rows=6538
+   * @constraints k=13, rows=6522
    *
    * Requirements:
    *
@@ -110,7 +116,7 @@ module ForwarderPrivate {
    * would defeat the private-parent guarantee. A coin public key is encrypted
    * inside the Zswap output and never appears on the public transcript.
    *
-   * @circuitInfo k=15, rows=23937
+   * @constraints k=15, rows=23837
    *
    * Requirements:
    *
@@ -121,7 +127,7 @@ module ForwarderPrivate {
    *
    * @param {QualifiedShieldedCoinInfo} coin - The coin to spend.
    * @param {ZswapCoinPublicKey} parent - The parent coin public key. Its 32
-   * bytes are the preimage to the stored commitment.
+   * bytes are one half of the commitment preimage, alongside `opSecret`.
    * @param {Bytes<32>} opSecret - The operational secret. Never appears
    * on the public transcript.
    *
@@ -148,7 +154,7 @@ module ForwarderPrivate {
     // Reject a zero parent before the commitment gate.
     assert(!Utils_isKeyZero(parent), "ForwarderPrivate: zero parent");
 
-    // Commitment gate — the preimage is the parent key's 32 bytes.
+    // Commitment gate. The preimage is the parent key's 32 bytes and `opSecret`.
     assert(
       _calculateParentCommitment(parent.bytes, opSecret) == _parentCommitment,
       "ForwarderPrivate: invalid parent"

package/multisig/ForwarderShielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ForwarderShielded.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ForwarderShielded.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -103,7 +103,7 @@ module ForwarderShielded {
    * `sendImmediateShielded` to the stored parent recipient (always the
    * `left` / coin-public-key arm today).
    *
-   * @circuitInfo k=15, rows=24446
+   * @constraints k=15, rows=24373
    *
    * Requirements:
    *

package/multisig/ForwarderUnshielded.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ForwarderUnshielded.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ForwarderUnshielded.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -105,7 +105,7 @@ module ForwarderUnshielded {
    * forwards it to `_parent` via `sendUnshielded` (always the `right` /
    * user-address arm today).
    *
-   * @circuitInfo k=10, rows=565
+   * @constraints k=10, rows=563
    *
    * Requirements:
    *

package/multisig/ProposalManager.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ProposalManager.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ProposalManager.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -14,7 +14,7 @@ pragma language_version >= 0.26.0;
  * internal Bytes<32> representation to consumers.
  *
  * @warning PROPOSALS ARE PUBLIC. `_proposals` is exported ledger state, so
- * every proposal's recipient address, token color, amount, and status is
+ * every proposal's recipient address, token color, amount, and state is
  * readable off-chain, and `_nextProposalId` reveals how many have been created.
  * This holds regardless of which treasury a consumer composes: pairing this
  * module with `ShieldedTreasuryStateless` still publishes the full intent of
@@ -34,41 +34,145 @@ module ProposalManager {
   // ─── Types ──────────────────────────────────────────────────────
 
   /**
-   * @description Proposal lifecycle states. `Inactive` is the zero value and is
-   * never stored: `_createProposal` writes `Active`, and every view asserts the
-   * proposal exists before reading, so a stored proposal can never read
-   * `Inactive`.
+   * @description Proposal lifecycle states, derived from `Proposal.state` by
+   * `getProposalStatus`. Not stored on the ledger.
+   *
+   * - `Inactive`: no proposal with that id exists.
+   * - `Active`: `state` is an expiry in the future.
+   * - `Executed`: `state` is `executedState()`.
+   * - `Cancelled`: `state` is `cancelledState()`.
+   * - `Expired`: `state` is an expiry at or before the current block time.
    */
   export enum ProposalStatus {
     Inactive,
     Active,
     Executed,
-    Cancelled
+    Cancelled,
+    Expired
   }
 
+  /**
+   * @description What a `Recipient`'s bytes are and which rail accepts them.
+   *
+   * - `ShieldedUser`: a Zswap coin public key. `toShieldedRecipient` only.
+   * - `UnshieldedUser`: a user address. `toUnshieldedRecipient` only.
+   * - `Contract`: a contract address. Accepted by both.
+   *
+   * @warning `toShieldedRecipient` rejects `UnshieldedUser` and
+   * `toUnshieldedRecipient` rejects `ShieldedUser`, both at execution rather
+   * than at creation. That mismatch is the hazard noted in `_createProposal`.
+   */
   export enum RecipientKind {
     ShieldedUser,
     UnshieldedUser,
     Contract
   }
 
+  /**
+   * @description A transfer target.
+   *
+   * @warning `address` is raw 32 bytes. `kind` alone decides whether they are
+   * read as a Zswap coin public key, a user address, or a contract address.
+   */
   export struct Recipient {
     kind: RecipientKind,
     address: Bytes<32>
   }
 
+  /**
+   * @description A proposal. `state` holds both the lifecycle stage and the
+   * expiry in a single field:
+   *
+   * - `executedState()` (1): executed.
+   * - `cancelledState()` (2): cancelled.
+   * - any greater value: the expiry, as seconds since the Unix epoch. The
+   *   proposal is active while the block time is below it and expired
+   *   afterwards.
+   *
+   * `_createProposal` rejects an `expiry` in the reserved range, so a proposal
+   * that has not reached a terminal state always has `state` greater than
+   * `cancelledState()`. Note that `Expired` is NOT terminal: a lapsed proposal
+   * still carries its original deadline, which is what tells a reader when it
+   * lapsed.
+   *
+   * @warning In the deadline range, `state` marks when a proposal STOPS being
+   * executable, not when it starts: it is executable while `blockTime < state`
+   * and inert once `blockTime >= state`.
+   *
+   * @notice This module implements no execution delay. `expiry` bounds how long
+   * a proposal stays valid; it does not impose a minimum wait before it may be
+   * executed. A consumer that needs a delay must compose one.
+   *
+   * @notice Off-chain readers decode `state` themselves, applying the sentinel
+   * checks and the deadline comparison above. `_proposals` is exported ledger
+   * state and readable without a proof. `executedState` and
+   * `cancelledState` are pure, so a reader can obtain the sentinel values without
+   * hardcoding them. A state-reading accessor will be revisited once contract-to-contract
+   * interactions are available.
+   */
   export struct Proposal {
     to: Recipient,
     color: Bytes<32>,
     amount: Uint<128>,
-    status: ProposalStatus
+    state: Uint<64>
   }
 
   // ─── State ──────────────────────────────────────────────────────
 
+  /**
+   * @description Monotonic source of proposal ids. `_createProposal` increments
+   * it and reads the new value back to key `_proposals` so an id is never
+   * reused.
+   *
+   * @notice Reading the counter back is what serializes concurrent creates. The
+   * increment on its own would commute, but using the result as a map key turns
+   * creation into a pinned read-modify-write. Thus two creates landing in the same
+   * block cannot both succeed and the loser is rejected.
+   *
+   * @notice Readable off-chain without a proof and it discloses how many
+   * proposals the contract has ever created.
+   */
   export ledger _nextProposalId: Counter;
+
+  /**
+   * @description Proposals by id, keyed by the value `_nextProposalId` produced
+   * at creation. Each entry carries the recipient, token color, amount, and the
+   * overlaid lifecycle/expiry encoding documented on `Proposal`.
+   * @type {Uint<64>} id - The proposal identifier, issued by `_nextProposalId`.
+   * @type {Proposal} proposal - The proposal record.
+   * @type {Map<id, proposal>}
+   * @type {Map<Uint<64>, Proposal>} _proposals
+   *
+   * @notice Entries are never deleted. Reaching a terminal state overwrites
+   * `state` in place so the map only grows, and no circuit here prunes it.
+   * A consumer that needs cleanup must compose its own.
+   *
+   * @notice Readable off-chain without a proof so integrators read this map
+   * directly rather than calling a circuit. Decoding `state` is the reader's
+   * job. See `Proposal`
+   */
   export ledger _proposals: Map<Uint<64>, Proposal>;
 
+  // ─── State Sentinels ────────────────────────────────────────────
+
+  /**
+   * @description The `Proposal.state` value marking a proposal as executed.
+   *
+   * @returns {Uint<64>} 1.
+   */
+  export pure circuit executedState(): Uint<64> {
+    return 1;
+  }
+
+  /**
+   * @description The `Proposal.state` value marking a proposal as cancelled.
+   *
+   * @returns {Uint<64>} 2.
+   */
+  export pure circuit cancelledState(): Uint<64> {
+    return 2;
+  }
+
   // ─── Recipient Helpers ──────────────────────────────────────────
 
   /**
@@ -173,12 +277,23 @@ module ProposalManager {
   }
 
   /**
-   * @description Asserts that a proposal exists and is active.
+   * @description Asserts that a proposal exists and is still executable. The two
+   * checks are separate: a terminal `state` (executed or cancelled) fails the
+   * first, and a deadline that has passed fails the second, so the error message
+   * distinguishes the two.
+   *
+   * @notice Expiry is terminal, unlike a conflicting read. A tx rejected
+   * for a stale read succeeds once rebuilt against fresh state. Rebuilding
+   * cannot help here: block time only moves forward, so an expired proposal
+   * stays expired. Check the proposal's status before re-proving.
    *
    * Requirements:
    *
    * - Proposal must exist.
-   * - Proposal status must be Active.
+   * - Proposal must not be executed or cancelled.
+   * - Proposal must not have expired.
+   *
+   * @constraints k=9, rows=129
    *
    * @param {Uint<64>} id - The proposal ID.
    *
@@ -186,10 +301,16 @@ module ProposalManager {
    */
   export circuit assertProposalActive(id: Uint<64>): [] {
     assertProposalExists(id);
+
+    const state = _proposals.lookup(disclose(id)).state;
     assert(
-      _proposals.lookup(disclose(id)).status == ProposalStatus.Active,
+      state > cancelledState(),
       "ProposalManager: proposal not active"
     );
+    assert(
+      blockTimeLt(state),
+      "ProposalManager: proposal expired"
+    );
   }
 
   // ─── Proposal Lifecycle ─────────────────────────────────────────
@@ -203,12 +324,27 @@ module ProposalManager {
    * - A `kind` the execution rail cannot accept (an `UnshieldedUser` recipient
    *   on a shielded treasury, say) creates a proposal that passes here and then
    *   reverts in `toShieldedRecipient` at execution. It stays `Active` and
-   *   unexecutable on that rail until `_cancelProposal` retires it.
+   *   unexecutable on that rail until `_cancelProposal` retires it or its
+   *   `expiry` lapses.
    * - A zero or otherwise unspendable `address` is accepted, and funds sent to
    *   it on execution are unrecoverable.
    *
    * @notice `_nextProposalId` is incremented and then read back for the map key,
-   * making this a pinned read-modify-write.
+   * making this a pinned read-modify-write. The `increment` alone would commute,
+   * but reading it back to key the map reintroduces the conflict, so two
+   * proposals created in the same block serialize and the loser is rejected.
+   *
+   * @notice `expiry` is mandatory and is only checked against the present: a
+   * proposal cannot be born expired. There is deliberately NO maximum horizon
+   * here, because the module cannot know what a sensible one is for a given
+   * deployment. A caller may therefore pass an effectively unreachable expiry,
+   * reintroducing the immortal proposal this field exists to prevent. Consuming
+   * contracts that need a bounded lifetime must impose their own cap.
+   *
+   * @notice `expiry` is also rejected if it falls in the sentinel range, keeping
+   * the two domains `state` overlays disjoint. That check is enforced here rather
+   * than left to the future check, so disjointness holds for whatever block time
+   * the executing environment reports.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -217,35 +353,52 @@ module ProposalManager {
    * Requirements:
    *
    * - `amount` must be greater than 0.
+   * - `expiry` must be greater than `cancelledState()`.
+   * - `expiry` must be in the future.
+   *
+   * @constraints k=10, rows=913
    *
    * @param {Recipient} to - The recipient (constructed via helper circuits).
    * @param {Bytes<32>} color - The token color.
    * @param {Uint<128>} amount - The amount to transfer.
+   * @param {Uint<64>} expiry - Seconds since the Unix epoch, at and after which
+   * the proposal is inert.
    *
    * @returns {Uint<64>} The new proposal ID.
    */
   export circuit _createProposal(
     to: Recipient,
     color: Bytes<32>,
-    amount: Uint<128>
+    amount: Uint<128>,
+    expiry: Uint<64>
   ): Uint<64> {
     assert(amount > 0, "ProposalManager: zero amount");
+    assert(
+      expiry > cancelledState(),
+      "ProposalManager: expiry in reserved range"
+    );
+    assert(
+      blockTimeLt(disclose(expiry)),
+      "ProposalManager: expiry not in the future"
+    );
 
     _nextProposalId.increment(1);
     const id = _nextProposalId;
+    // Defense in depth
+    assert(!_proposals.member(id), "ProposalManager: id already used");
 
     _proposals.insert(id, disclose(Proposal {
       to: to,
       color: color,
       amount: amount,
-      status: ProposalStatus.Active
+      state: expiry
     }));
 
     return id;
   }
 
   /**
-   * @description Cancels a proposal.
+   * @description Cancels a proposal, retiring it before its expiry.
    *
    * @notice Access control is NOT enforced here.
    * The consuming contract must gate this behind its own
@@ -267,7 +420,7 @@ module ProposalManager {
       to: proposal.to,
       color: proposal.color,
       amount: proposal.amount,
-      status: ProposalStatus.Cancelled
+      state: cancelledState()
     });
   }
 
@@ -294,14 +447,16 @@ module ProposalManager {
       to: proposal.to,
       color: proposal.color,
       amount: proposal.amount,
-      status: ProposalStatus.Executed
+      state: executedState()
     });
   }
 
   // ─── View ───────────────────────────────────────────────────────
 
   /**
-   * @description Returns the full proposal data.
+   * @description Returns the full proposal data. The returned `state` is the
+   * raw encoded field. See `Proposal` for how to read it, and prefer
+   * `getProposalStatus` when the lifecycle stage is what is wanted.
    *
    * @param {Uint<64>} id - The proposal ID.
    *
@@ -349,14 +504,31 @@ module ProposalManager {
   }
 
   /**
-   * @description Returns the status of a proposal.
+   * @description Derives the lifecycle status of a proposal from its `state`
+   * field and the current block time. Returns `Inactive` for an id that was
+   * never created rather than failing.
+   *
+   * @constraints k=9, rows=252
    *
    * @param {Uint<64>} id - The proposal ID.
    *
    * @returns {ProposalStatus} The proposal status.
    */
   export circuit getProposalStatus(id: Uint<64>): ProposalStatus {
-    assertProposalExists(id);
-    return _proposals.lookup(disclose(id)).status;
+    if (!_proposals.member(disclose(id))) {
+      return ProposalStatus.Inactive;
+    }
+
+    const state = _proposals.lookup(disclose(id)).state;
+    if (state == executedState()) {
+      return ProposalStatus.Executed;
+    }
+    if (state == cancelledState()) {
+      return ProposalStatus.Cancelled;
+    }
+    if (blockTimeLt(state)) {
+      return ProposalStatus.Active;
+    }
+    return ProposalStatus.Expired;
   }
 }

package/multisig/ShieldedTreasury.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ShieldedTreasury.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ShieldedTreasury.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -41,8 +41,35 @@ module ShieldedTreasury {
 
   // ─── State ──────────────────────────────────────────────────────
 
+  /**
+   * @description The treasury's shielded holdings, one coin per token color.
+   * A deposit of an existing color merges into the stored coin rather than
+   * adding a second entry.
+   * @type {Bytes<32>} color - The token color.
+   * @type {QualifiedShieldedCoinInfo} coin - The coin the treasury holds of it.
+   * @type {Map<color, coin>}
+   * @type {Map<Bytes<32>, QualifiedShieldedCoinInfo>} _coins
+   */
   export ledger _coins: Map<Bytes<32>, QualifiedShieldedCoinInfo>;
+  /**
+   * @description Lifetime deposits per token color. Only ever increases, so it
+   * is a running total rather than a balance. `getTokenBalance` reads `_coins`
+   * and is the canonical balance; `getReceivedMinusSent` derives it from the
+   * totals and documents when that derivation holds.
+   * @type {Bytes<32>} color - The token color.
+   * @type {Uint<128>} total - The amount deposited over the contract's life.
+   * @type {Map<color, total>}
+   * @type {Map<Bytes<32>, Uint<128>>} _received
+   */
   export ledger _received: Map<Bytes<32>, Uint<128>>;
+  /**
+   * @description Lifetime payouts per token color. The counterpart to
+   * `_received`; also only ever increases.
+   * @type {Bytes<32>} color - The token color.
+   * @type {Uint<128>} total - The amount sent over the contract's life.
+   * @type {Map<color, total>}
+   * @type {Map<Bytes<32>, Uint<128>>} _sent
+   */
   export ledger _sent: Map<Bytes<32>, Uint<128>>;
 
   // ─── Deposit ────────────────────────────────────────────────────

package/multisig/ShieldedTreasuryStateless.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.1 (multisig/ShieldedTreasuryStateless.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/ShieldedTreasuryStateless.compact)
 
 pragma language_version >= 0.26.0;