@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha

package/multisig/ProposalManager.compact

@@ -0,0 +1,328 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ProposalManager.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ProposalManager
+ * @description Token-agnostic proposal lifecycle management for multisig
+ * governance contracts.
+ *
+ * Supports shielded and unshielded proposals through a unified
+ * Recipient type with a RecipientKind tag. Typed helper circuits
+ * provide safe construction of recipients without exposing the
+ * internal Bytes<32> representation to consumers.
+ */
+module ProposalManager {
+  import CompactStandardLibrary;
+
+  // ─── Types ──────────────────────────────────────────────────────
+
+  export enum ProposalStatus {
+    Inactive,
+    Active,
+    Executed,
+    Cancelled
+  }
+
+  export enum RecipientKind {
+    ShieldedUser,
+    UnshieldedUser,
+    Contract
+  }
+
+  export struct Recipient {
+    kind: RecipientKind,
+    address: Bytes<32>
+  }
+
+  export struct Proposal {
+    to: Recipient,
+    color: Bytes<32>,
+    amount: Uint<128>,
+    status: ProposalStatus
+  }
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  export ledger _nextProposalId: Counter;
+  export ledger _proposals: Map<Uint<64>, Proposal>;
+
+  // ─── Recipient Helpers ──────────────────────────────────────────
+
+  /**
+   * @description Constructs a shielded user recipient.
+   *
+   * @param {ZswapCoinPublicKey} key - The shielded recipient's public key.
+   *
+   * @returns {Recipient} The typed recipient.
+   */
+  export circuit shieldedUserRecipient(key: ZswapCoinPublicKey): Recipient {
+    return Recipient { kind: RecipientKind.ShieldedUser, address: key.bytes };
+  }
+
+  /**
+   * @description Constructs an unshielded user recipient.
+   *
+   * @param {UserAddress} addr - The unshielded recipient's address.
+   *
+   * @returns {Recipient} The typed recipient.
+   */
+  export circuit unshieldedUserRecipient(addr: UserAddress): Recipient {
+    return Recipient { kind: RecipientKind.UnshieldedUser, address: addr.bytes };
+  }
+
+  /**
+   * @description Constructs a contract recipient.
+   *
+   * @param {ContractAddress} addr - The contract address.
+   *
+   * @returns {Recipient} The typed recipient.
+   */
+  export circuit contractRecipient(addr: ContractAddress): Recipient {
+    return Recipient { kind: RecipientKind.Contract, address: addr.bytes };
+  }
+
+  /**
+   * @description Converts a Recipient to a shielded send recipient.
+   * Handles both ShieldedUser and Contract kinds.
+   *
+   * Requirements:
+   *
+   * - Recipient kind must be ShieldedUser or Contract.
+   *
+   * @param {Recipient} r - The recipient.
+   *
+   * @returns {Either<ZswapCoinPublicKey, ContractAddress>} The shielded recipient.
+   */
+  export circuit toShieldedRecipient(r: Recipient): Either<ZswapCoinPublicKey, ContractAddress> {
+    if (r.kind == RecipientKind.ShieldedUser) {
+      return left<ZswapCoinPublicKey, ContractAddress>(
+        ZswapCoinPublicKey { bytes: r.address }
+      );
+    }
+    assert(r.kind == RecipientKind.Contract, "ProposalManager: invalid shielded recipient");
+    return right<ZswapCoinPublicKey, ContractAddress>(
+      ContractAddress { bytes: r.address }
+    );
+  }
+
+  /**
+   * @description Converts a Recipient to an unshielded send recipient.
+   * Handles both UnshieldedUser and Contract kinds.
+   *
+   * Requirements:
+   *
+   * - Recipient kind must be UnshieldedUser or Contract.
+   *
+   * @param {Recipient} r - The recipient.
+   *
+   * @returns {Either<ContractAddress, UserAddress>} The unshielded recipient.
+   */
+  export circuit toUnshieldedRecipient(r: Recipient): Either<ContractAddress, UserAddress> {
+    if (r.kind == RecipientKind.Contract) {
+      return left<ContractAddress, UserAddress>(
+        ContractAddress { bytes: r.address }
+      );
+    }
+    assert(r.kind == RecipientKind.UnshieldedUser, "ProposalManager: invalid unshielded recipient");
+    return right<ContractAddress, UserAddress>(
+      UserAddress { bytes: r.address }
+    );
+  }
+
+  // ─── Guards ─────────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that a proposal exists.
+   *
+   * Requirements:
+   *
+   * - Proposal with `id` must have been created.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertProposalExists(id: Uint<64>): [] {
+    assert(
+      _proposals.member(disclose(id)),
+      "ProposalManager: proposal not found"
+    );
+  }
+
+  /**
+   * @description Asserts that a proposal exists and is active.
+   *
+   * Requirements:
+   *
+   * - Proposal must exist.
+   * - Proposal status must be Active.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit assertProposalActive(id: Uint<64>): [] {
+    assertProposalExists(id);
+    assert(
+      _proposals.lookup(disclose(id)).status == ProposalStatus.Active,
+      "ProposalManager: proposal not active"
+    );
+  }
+
+  // ─── Proposal Lifecycle ─────────────────────────────────────────
+
+  /**
+   * @description Creates a new proposal.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - `amount` must be greater than 0.
+   *
+   * @param {Recipient} to - The recipient (constructed via helper circuits).
+   * @param {Bytes<32>} color - The token color.
+   * @param {Uint<128>} amount - The amount to transfer.
+   *
+   * @returns {Uint<64>} The new proposal ID.
+   */
+  export circuit _createProposal(
+    to: Recipient,
+    color: Bytes<32>,
+    amount: Uint<128>
+  ): Uint<64> {
+    assert(amount > 0, "ProposalManager: zero amount");
+
+    _nextProposalId.increment(1);
+    const id = _nextProposalId;
+
+    _proposals.insert(id, disclose(Proposal {
+      to: to,
+      color: color,
+      amount: amount,
+      status: ProposalStatus.Active
+    }));
+
+    return id;
+  }
+
+  /**
+   * @description Cancels a proposal.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - Proposal must be active.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _cancelProposal(id: Uint<64>): [] {
+    assertProposalActive(id);
+
+    const proposal = _proposals.lookup(disclose(id));
+    _proposals.insert(disclose(id), Proposal {
+      to: proposal.to,
+      color: proposal.color,
+      amount: proposal.amount,
+      status: ProposalStatus.Cancelled
+    });
+  }
+
+  /**
+   * @description Marks a proposal as executed.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - Proposal must be active.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _markExecuted(id: Uint<64>): [] {
+    assertProposalActive(id);
+
+    const proposal = _proposals.lookup(disclose(id));
+    _proposals.insert(disclose(id), Proposal {
+      to: proposal.to,
+      color: proposal.color,
+      amount: proposal.amount,
+      status: ProposalStatus.Executed
+    });
+  }
+
+  // ─── View ───────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the full proposal data.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {Proposal} The proposal.
+   */
+  export circuit getProposal(id: Uint<64>): Proposal {
+    assertProposalExists(id);
+    return _proposals.lookup(disclose(id));
+  }
+
+  /**
+   * @description Returns the recipient of a proposal.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {Recipient} The recipient.
+   */
+  export circuit getProposalRecipient(id: Uint<64>): Recipient {
+    assertProposalExists(id);
+    return _proposals.lookup(disclose(id)).to;
+  }
+
+  /**
+   * @description Returns the amount of a proposal.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {Uint<128>} The amount.
+   */
+  export circuit getProposalAmount(id: Uint<64>): Uint<128> {
+    assertProposalExists(id);
+    return _proposals.lookup(disclose(id)).amount;
+  }
+
+  /**
+   * @description Returns the token color of a proposal.
+   *
+   * @param {Uint<64>} id - The proposal ID.
+   *
+   * @returns {Bytes<32>} The token color.
+   */
+  export circuit getProposalColor(id: Uint<64>): Bytes<32> {
+    assertProposalExists(id);
+    return _proposals.lookup(disclose(id)).color;
+  }
+
+  /**
+   * @description Returns the status of a proposal.
+   *
+   * @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;
+  }
+}

package/multisig/ShieldedTreasury.compact

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ShieldedTreasury.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ShieldedTreasury
+ * @description Manages shielded (private) token deposits, accounting,
+ * and transfers for multisig governance contracts.
+ *
+ * Coins are stored on the contract ledger in a map keyed by token color,
+ * with one UTXO per color. Deposits are merged with existing coins of
+ * the same color via `mergeCoinImmediate`. This simplifies coin selection
+ * at spend time — the executor doesn't need to choose between multiple
+ * UTXOs of the same color.
+ *
+ * Cumulative received and sent totals are tracked per color for audit
+ * purposes. The canonical balance query is `getTokenBalance`, which
+ * reads the actual coin value from the UTXO map.
+ *
+ * Underscore-prefixed circuits (_deposit, _send) have no access control
+ * enforcement. The consuming contract must gate these behind its own
+ * authorization policy.
+ */
+module ShieldedTreasury {
+  import CompactStandardLibrary;
+  import { selfAsRecipient, UINT128_MAX } from "../utils/Utils" prefix Utils_;
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  export ledger _coins: Map<Bytes<32>, QualifiedShieldedCoinInfo>;
+  export ledger _received: Map<Bytes<32>, Uint<128>>;
+  export ledger _sent: Map<Bytes<32>, Uint<128>>;
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @description Receives a shielded coin into the treasury.
+   *
+   * The coin is first claimed at the protocol level via `receiveShielded`,
+   * which allocates the Merkle tree index required by `insertCoin`.
+   * The coin is then merged with any existing coin of the same color,
+   * or inserted as a new entry if no coin of that color exists.
+   *
+   * Zero-value deposits are permitted. While currently a no-op
+   * economically, they may serve as signaling mechanisms when events
+   * are supported, or as decoy transactions for privacy.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - Deposit must not cause received total overflow.
+   *
+   * @param {ShieldedCoinInfo} coin - The incoming shielded coin descriptor.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _deposit(coin: ShieldedCoinInfo): [] {
+    const currentReceived = getReceivedTotal(coin.color);
+    assert(currentReceived <= Utils_UINT128_MAX() - coin.value, "ShieldedTreasury: overflow");
+
+    receiveShielded(disclose(coin));
+
+    const coinColor = disclose(coin.color);
+
+    if (_coins.member(coinColor)) {
+      const merged = mergeCoinImmediate(_coins.lookup(coinColor), disclose(coin));
+      _coins.insertCoin(coinColor, merged, Utils_selfAsRecipient());
+    } else {
+      _coins.insertCoin(coinColor, disclose(coin), Utils_selfAsRecipient());
+    }
+
+    _received.insert(
+      coinColor,
+      disclose(currentReceived + coin.value as Uint<128>)
+    );
+  }
+
+  // ─── Send ───────────────────────────────────────────────────────
+
+  /**
+   * @description Sends shielded tokens from the treasury.
+   *
+   * Looks up the stored coin by color, verifies sufficient value,
+   * and executes the shielded send. If the send produces change,
+   * it is sent back to the contract via `sendImmediateShielded`.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - A coin of the given `color` must exist in the treasury.
+   * - The coin's value must be >= `amount`.
+   * - Send must not cause sent total overflow.
+   *
+   * @param {Either<ZswapCoinPublicKey, ContractAddress>} recipient - The recipient.
+   * @param {Bytes<32>} color - The token color.
+   * @param {Uint<128>} amount - The amount to send.
+   *
+   * @returns {ShieldedSendResult} The result containing sent coin and any change.
+   */
+  export circuit _send(
+    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+    color: Bytes<32>,
+    amount: Uint<128>
+  ): ShieldedSendResult {
+    assert(_coins.member(disclose(color)), "ShieldedTreasury: no balance");
+
+    const coin = _coins.lookup(disclose(color));
+    assert(coin.value >= amount, "ShieldedTreasury: coin value insufficient");
+
+    const currentSent = getSentTotal(color);
+    assert(currentSent <= Utils_UINT128_MAX() - amount, "ShieldedTreasury: overflow");
+
+    const result = sendShielded(coin, disclose(recipient), disclose(amount));
+
+    if (disclose(result.change.is_some)) {
+      const changeCoin = result.change.value;
+      sendImmediateShielded(
+        changeCoin,
+        Utils_selfAsRecipient(),
+        changeCoin.value
+      );
+      _coins.insertCoin(disclose(color), changeCoin, Utils_selfAsRecipient());
+    } else {
+      _coins.remove(disclose(color));
+    }
+
+    _sent.insert(
+      disclose(color),
+      disclose(currentSent + amount as Uint<128>)
+    );
+
+    return result;
+  }
+
+  // ─── View ───────────────────────────────────────────────────────
+
+  /**
+   * @description Returns the current token balance for a color.
+   * Reads the actual coin value from the UTXO map.
+   *
+   * @param {Bytes<32>} color - The token color.
+   *
+   * @returns {Uint<128>} The current balance.
+   */
+  export circuit getTokenBalance(color: Bytes<32>): Uint<128> {
+    if (!_coins.member(disclose(color))) {
+      return 0;
+    }
+    return _coins.lookup(disclose(color)).value;
+  }
+
+  // ─── Accounting ─────────────────────────────────────────────────
+
+  /**
+   * @description Returns the cumulative received total for a color.
+   *
+   * @param {Bytes<32>} color - The token color.
+   *
+   * @returns {Uint<128>} Total received.
+   */
+  export circuit getReceivedTotal(color: Bytes<32>): Uint<128> {
+    if (!_received.member(disclose(color))) {
+      return 0;
+    }
+    return _received.lookup(disclose(color));
+  }
+
+  /**
+   * @description Returns the cumulative sent total for a color.
+   *
+   * @param {Bytes<32>} color - The token color.
+   *
+   * @returns {Uint<128>} Total sent.
+   */
+  export circuit getSentTotal(color: Bytes<32>): Uint<128> {
+    if (!_sent.member(disclose(color))) {
+      return 0;
+    }
+    return _sent.lookup(disclose(color));
+  }
+
+  /**
+   * @description Returns the difference between cumulative received
+   * and cumulative sent totals for a color. Should equal
+   * `getTokenBalance` if accounting is consistent.
+   *
+   * @param {Bytes<32>} color - The token color.
+   *
+   * @returns {Uint<128>} Received minus sent.
+   */
+  export circuit getReceivedMinusSent(color: Bytes<32>): Uint<128> {
+    return getReceivedTotal(color) - getSentTotal(color) as Uint<128>;
+  }
+}

package/multisig/ShieldedTreasuryStateless.compact

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha (multisig/ShieldedTreasuryStateless.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ShieldedTreasury
+ * @description Manages shielded (private) token deposits, accounting,
+ * and transfers for multisig governance contracts.
+ *
+ * Coins are stored on the contract ledger in a map keyed by token color,
+ * with one UTXO per color. Deposits are merged with existing coins of
+ * the same color via `mergeCoinImmediate`. This simplifies coin selection
+ * at spend time — the executor doesn't need to choose between multiple
+ * UTXOs of the same color.
+ *
+ * Cumulative received and sent totals are tracked per color for audit
+ * purposes. The canonical balance query is `getTokenBalance`, which
+ * reads the actual coin value from the UTXO map.
+ */
+module ShieldedTreasuryStateless {
+  import CompactStandardLibrary;
+  import { selfAsRecipient } from "../utils/Utils" prefix Utils_;
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @description Receives a shielded coin into the treasury.
+   */
+  export circuit _deposit(coin: ShieldedCoinInfo): [] {
+    receiveShielded(disclose(coin));
+  }
+
+  // ─── Send ───────────────────────────────────────────────────────
+
+  /**
+   * @description Sends shielded tokens using a caller-provided coin.
+   *
+   * The coin is supplied by the caller rather than looked up from
+   * on-chain state; the token color is derived from `coin.color`.
+   * Executes the shielded send and, if change is produced, returns it
+   * to the contract via `sendImmediateShielded`. No balance or
+   * received/sent accounting is tracked on the ledger.
+   *
+   * @notice Access control is NOT enforced here.
+   * The consuming contract must gate this behind its own
+   * authorization policy.
+   *
+   * Requirements:
+   *
+   * - `coin.value` must be >= `amount`.
+   *
+   * @param {QualifiedShieldedCoinInfo} coin - The coin to spend (provided by the caller).
+   * @param {Either<ZswapCoinPublicKey, ContractAddress>} recipient - The recipient.
+   * @param {Uint<128>} amount - The amount to send.
+   *
+   * @returns {ShieldedSendResult} The result containing sent coin and any change.
+   */
+  export circuit _send(
+    coin: QualifiedShieldedCoinInfo,
+    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+    amount: Uint<128>
+  ): ShieldedSendResult {
+    const result = sendShielded(disclose(coin), disclose(recipient), disclose(amount));
+
+    if (disclose(result.change.is_some)) {
+      sendImmediateShielded(
+        disclose(result.change.value),
+        Utils_selfAsRecipient(),
+        disclose(result.change.value.value)
+      );
+    }
+
+    return result;
+  }
+}