@openzeppelin/compact-contracts 0.2.0 → 0.3.0-alpha.1

package/multisig/ForwarderPrivate.compact

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderPrivate.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ForwarderPrivate
+ * @description Private-parent forwarder primitives. The parent is a coin
+ * public key, hidden behind a `persistentHash` commitment on the ledger.
+ * Deposits accumulate at the contract (no atomic forward); the operator
+ * drains coins by presenting the `(parent, opSecret)` preimage at drain
+ * time. The drained coin is sent as a shielded note to the parent key, so
+ * the parent stays hidden on-chain. The parent is deliberately a coin public
+ * key and not a contract address: a shielded send to a contract publishes
+ * that contract's address in cleartext, which would defeat the guarantee.
+ *
+ * Knowledge of the preimage is the sole authorization gate — there is
+ * no signer set and no nullifier scheme. The operational secret is
+ * held off-chain; the contract never sees it except during a drain.
+ * Two forwarders bound to the same parent with different operational
+ * secrets produce different commitments and are unlinkable on-chain.
+ *
+ * Underscore-prefixed circuits have no access control beyond the
+ * preimage check inside `_drain`. State access is gated by the
+ * initialization pattern: every state-touching circuit asserts the
+ * module has been initialized via `initialize`. The pure
+ * `_calculateParentCommitment` helper does not access state and is
+ * intentionally callable without initialization.
+ */
+module ForwarderPrivate {
+  import CompactStandardLibrary;
+  import "../utils/Utils" prefix Utils_;
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  export ledger _parentCommitment: Bytes<32>;
+
+  /**
+   * @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;
+
+  // ─── Init ───────────────────────────────────────────────────────
+
+  /**
+   * @description Initializes the forwarder with a parent commitment.
+   * Called once from the preset constructor. The commitment is
+   * immutable after init.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   * - `parentCommitment` must not be the zero bytes. A zero commitment
+   *   is the sole drain gate and would leave every deposited coin
+   *   permanently unrecoverable (no preimage exists for `default<Bytes<32>>`
+   *   under the domain-tagged hash).
+   *
+   * @param {Bytes<32>} parentCommitment - Domain-tagged
+   * `persistentHash([pad(32, "ForwarderPrivate:commitment"), parentAddr, opSecret])`
+   * computed off-chain by the deployer (see `_calculateParentCommitment`).
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize(parentCommitment: Bytes<32>): [] {
+    assert(parentCommitment != default<Bytes<32>>, "ForwarderPrivate: zero commitment");
+    assertNotInitialized();
+    _isInitialized = true;
+    _parentCommitment = disclose(parentCommitment);
+  }
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @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
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @param {ShieldedCoinInfo} coin - The incoming shielded coin.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _deposit(coin: ShieldedCoinInfo): [] {
+    assertInitialized();
+    receiveShielded(disclose(coin));
+  }
+
+  // ─── Drain ──────────────────────────────────────────────────────
+
+  /**
+   * @description Spends a previously-deposited shielded coin to the parent,
+   * a coin public key. The caller proves knowledge of `(parent, opSecret)`
+   * matching the stored commitment; the coin is sent as a plain shielded note,
+   * so the parent stays hidden on-chain. If `coin.value` exceeds `value`,
+   * `sendShielded` routes the change back to this contract as a self-owned
+   * output; `_drain` returns it untouched via `result.change`. The
+   * implementing contract chooses what to do with it: leave it dwelling at
+   * the contract for a future drain, or spend it onward to a different
+   * recipient in the same transaction via `sendImmediateShielded`.
+   *
+   * The parent is a `ZswapCoinPublicKey`, never a `ContractAddress`: a shielded
+   * send to a contract publishes that contract's address in cleartext on the
+   * transaction (the protocol must route the coin to a named contract), which
+   * 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=16, rows=41961
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   * - `parent` must not be the zero key.
+   * - `_calculateParentCommitment(parent.bytes, opSecret) == _parentCommitment`.
+   * - `coin.value` must be >= `value` (enforced by `sendShielded`).
+   *
+   * @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.
+   * @param {Bytes<32>} opSecret - The operational secret. Never appears
+   * on the public transcript.
+   *
+   * @warning **Losing the operational secret is permanent fund loss.** It
+   * is the sole drain authorization, with no rotation, revocation, or
+   * recovery path. If the operator misplaces it, every shielded coin
+   * accumulated at this contract is forever inaccessible, equivalent to
+   * losing a hot-wallet private key. Back it up offline before the first
+   * deposit and treat it with the same hygiene as a signing key.
+   *
+   * @param {Uint<128>} value - The amount to send.
+   *
+   * @returns {ShieldedSendResult} The result containing the sent coin
+   * and any change.
+   */
+  export circuit _drain(
+    coin: QualifiedShieldedCoinInfo,
+    parent: ZswapCoinPublicKey,
+    opSecret: Bytes<32>,
+    value: Uint<128>
+  ): ShieldedSendResult {
+    assertInitialized();
+
+    // 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.
+    assert(
+      _calculateParentCommitment(parent.bytes, opSecret) == _parentCommitment,
+      "ForwarderPrivate: invalid parent"
+    );
+
+    // Send to the parent coin public key (the `left` arm). `disclose` reveals
+    // nothing: a coin-public-key recipient is encrypted in the Zswap output, so
+    // the parent never appears on the public transcript. A contract recipient
+    // is intentionally unsupported — it would publish the address in cleartext.
+    const result = sendShielded(
+      disclose(coin),
+      left<ZswapCoinPublicKey, ContractAddress>(disclose(parent)),
+      disclose(value)
+    );
+
+    // `sendShielded` already emits any change as a fresh output owned by this
+    // contract (dwelling at the contract address for future drains). `_drain`
+    // returns it untouched: it must not re-spend the change here and then hand
+    // that same (now-nullified) coin back via `result.change` — that is the
+    // double spend a node rejects on the next drain. A caller is free to spend
+    // the returned change onward itself (e.g. route it to another recipient);
+    // the rule is only that the change must never be re-spent AND still treated
+    // as held.
+    return result;
+  }
+
+  // ─── Pure helpers ───────────────────────────────────────────────
+
+  /**
+   * @description Computes the parent commitment from `(parentAddr, opSecret)`.
+   * Pure circuit — used off-chain by the deployer to compute the
+   * constructor argument, and inside `_drain` for the preimage check.
+   * Callable without initialization.
+   *
+   * The first hash input is a fixed domain tag
+   * (`pad(32, "ForwarderPrivate:commitment")`). The tag prevents
+   * preimage collisions with other `persistentHash` users in the
+   * system that hash two `Bytes<32>` values — a colliding preimage
+   * crafted under a different domain cannot satisfy this commitment.
+   *
+   * @param {Bytes<32>} parentAddr - The parent address.
+   * @param {Bytes<32>} opSecret - The operational secret.
+   *
+   * @returns {Bytes<32>} `persistentHash([pad(32, "ForwarderPrivate:commitment"), parentAddr, opSecret])`.
+   */
+  export pure circuit _calculateParentCommitment(
+    parentAddr: Bytes<32>,
+    opSecret: Bytes<32>
+  ): Bytes<32> {
+    return persistentHash<Vector<3, Bytes<32>>>(
+      [pad(32, "ForwarderPrivate:commitment"), parentAddr, opSecret]
+    );
+  }
+
+  // ─── 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, "ForwarderPrivate: 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, "ForwarderPrivate: contract already initialized");
+  }
+}

package/multisig/ForwarderShielded.compact

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderShielded.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ForwarderShielded
+ * @description Public-parent forwarder for shielded coins. Provides an
+ * atomic forward pattern: receive a shielded coin and immediately send
+ * it to the configured parent recipient.
+ *
+ * The parent is stored generically as
+ * `Either<ZswapCoinPublicKey, ContractAddress>` so the ledger layout is
+ * forward-compatible, but `initialize` accepts only a `ZswapCoinPublicKey`
+ * today and stores it in the `left` arm. A contract address is the
+ * unsupported arm: an atomic forward delivers the coin in the same
+ * transaction as the deposit, and a shielded send to a contract is only
+ * valid if that contract claims the output in the same transaction. The
+ * only contract executing in `_deposit` is this forwarder, so a
+ * third-party contract parent would never claim the output and the
+ * deposit would be rejected by the node. A coin public key needs no
+ * in-tx claim, so it is the only recipient an atomic forward can reach.
+ *
+ * Contract-address support is reserved for a future circuit upgrade (via
+ * the Contract Maintenance Authority) once cross-contract UTXO delivery
+ * exists. Because the ledger already stores the generic `Either`, that
+ * upgrade changes only the circuits (verifier keys), not the state
+ * layout — no state migration is required.
+ *
+ * Underscore-prefixed circuits have no access control. The forwarder is
+ * intentionally permissionless — the recipient is fixed at init, so any
+ * caller may deposit without compromising the parent. State access is
+ * gated by a per-module `_isInitialized` flag: every circuit asserts the
+ * contract has been initialized via `initialize`.
+ *
+ * The parent is set once at init and the module exposes no setter, so a
+ * preset that omits one keeps the parent fixed. A consuming contract
+ * that needs to change the parent may add its own setter circuit.
+ *
+ * @notice The deployer must set a parent that can spend the forwarded
+ * coins. Forwarding to a key no one controls strands every deposit
+ * permanently. The zero-key guard rejects only the all-zero key, not an
+ * otherwise-unspendable one.
+ */
+module ForwarderShielded {
+  import CompactStandardLibrary;
+  import "../utils/Utils" prefix Utils_;
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  /**
+   * @description The parent recipient, stored generically as
+   * `Either<ZswapCoinPublicKey, ContractAddress>` for forward compatibility.
+   * `initialize` only ever writes the `left` (coin public key) arm today. See
+   * the module header.
+   */
+  export ledger _parent: Either<ZswapCoinPublicKey, ContractAddress>;
+
+  /**
+   * @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;
+
+  // ─── Init ───────────────────────────────────────────────────────
+
+  /**
+   * @description Initializes the forwarder with a parent recipient.
+   * Called once from the preset constructor. The coin public key is
+   * stored in the `left` arm of the generic `_parent` ledger field.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   * - `parent` must not be the zero key. A zero parent would forward
+   *   every deposit to an unspendable key with no recovery path.
+   *
+   * @param {ZswapCoinPublicKey} parent - The coin public key that
+   * receives every forwarded coin. The parameter is deliberately narrower
+   * than the `_parent` ledger type: only a coin public key can be
+   * delivered to by an atomic forward today (see the module header).
+   *
+   * @notice Beyond the zero-key check, the caller must ensure `parent` can
+   * spend forwarded coins. An unspendable parent strands every deposit with
+   * no recovery path.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize(parent: ZswapCoinPublicKey): [] {
+    assert(!Utils_isKeyZero(parent), "ForwarderShielded: zero parent");
+    assertNotInitialized();
+    _isInitialized = true;
+    _parent = left<ZswapCoinPublicKey, ContractAddress>(disclose(parent));
+  }
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @description Receives a shielded coin and atomically forwards it to
+   * `_parent`. The coin is claimed at the protocol level via
+   * `receiveShielded`, then immediately re-sent via
+   * `sendImmediateShielded` to the stored parent recipient (always the
+   * `left` / coin-public-key arm today).
+   *
+   * @circuitInfo k=15, rows=18573
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @param {ShieldedCoinInfo} coin - The incoming shielded coin.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _deposit(coin: ShieldedCoinInfo): [] {
+    assertInitialized();
+    receiveShielded(disclose(coin));
+    sendImmediateShielded(disclose(coin), _parent, disclose(coin.value));
+  }
+
+  // ─── Init guards ────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that the contract has been initialized, throwing an error if not.
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  circuit assertInitialized(): [] {
+    assert(_isInitialized, "ForwarderShielded: contract not initialized");
+  }
+
+  /**
+   * @description Asserts that the contract has not been initialized, throwing an error if it has.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  circuit assertNotInitialized(): [] {
+    assert(!_isInitialized, "ForwarderShielded: contract already initialized");
+  }
+}

package/multisig/ForwarderUnshielded.compact

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Compact Contracts v0.3.0-alpha.1 (multisig/ForwarderUnshielded.compact)
+
+pragma language_version >= 0.23.0;
+
+/**
+ * @module ForwarderUnshielded
+ * @description Public-parent forwarder for unshielded coins. Provides an
+ * atomic forward pattern: receive an unshielded amount of a given color
+ * and immediately send it to the configured parent recipient.
+ *
+ * The parent is stored generically as
+ * `Either<ContractAddress, UserAddress>` so the ledger layout is
+ * forward-compatible, but `initialize` accepts only a `UserAddress`
+ * today and stores it in the `right` arm. A contract address is the
+ * unsupported arm: an atomic forward delivers the amount in the same
+ * transaction as the deposit, and an unshielded send to a contract is
+ * only valid if that contract claims the amount in the same transaction
+ * (the same `receiveUnshielded` step this forwarder runs to accept the
+ * deposit). The only contract executing in `_deposit` is this forwarder,
+ * so a third-party contract parent would never claim the output and the
+ * deposit would be rejected by the node. A user address needs no in-tx
+ * claim, so it is the only recipient an atomic forward can reach.
+ *
+ * Contract-address support is reserved for a future circuit upgrade (via
+ * the Contract Maintenance Authority) once cross-contract UTXO delivery
+ * exists. Because the ledger already stores the generic `Either`, that
+ * upgrade changes only the circuits (verifier keys), not the state
+ * layout — no state migration is required.
+ *
+ * Unshielded transfers are publicly visible on the chain: depositor,
+ * recipient, color, and amount all appear on the public transcript.
+ *
+ * Underscore-prefixed circuits have no access control. The forwarder is
+ * intentionally permissionless — the recipient is fixed at init, so any
+ * caller may deposit without compromising the parent. State access is
+ * gated by a per-module `_isInitialized` flag: every circuit asserts the
+ * contract has been initialized via `initialize`.
+ *
+ * The parent is set once at init and the module exposes no setter, so a
+ * preset that omits one keeps the parent fixed. A consuming contract
+ * that needs to change the parent may add its own setter circuit.
+ *
+ * @notice The deployer must set a parent that can spend the forwarded
+ * amounts. Forwarding to an address no one controls strands every deposit
+ * permanently. The zero-address guard rejects only the all-zero address,
+ * not an otherwise-unspendable one.
+ */
+module ForwarderUnshielded {
+  import CompactStandardLibrary;
+
+  // ─── State ──────────────────────────────────────────────────────
+
+  /**
+   * @description The parent recipient, stored generically as
+   * `Either<ContractAddress, UserAddress>` for forward compatibility.
+   * `initialize` only ever writes the `right` (user address) arm today. See
+   * the module header.
+   */
+  export ledger _parent: Either<ContractAddress, UserAddress>;
+
+  /**
+   * @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;
+
+  // ─── Init ───────────────────────────────────────────────────────
+
+  /**
+   * @description Initializes the forwarder with a parent recipient.
+   * Called once from the preset constructor. The user address is stored
+   * in the `right` arm of the generic `_parent` ledger field.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   * - `parent` must not be the zero address. A zero parent would forward
+   *   every deposit to an unspendable address with no recovery path.
+   *
+   * @param {UserAddress} parent - The user address that receives every
+   * forwarded amount. The parameter is deliberately narrower than the
+   * `_parent` ledger type: only a user address can be delivered to by an
+   * atomic forward today (see the module header).
+   *
+   * @notice Beyond the zero-address check, the caller must ensure `parent`
+   * can spend forwarded amounts. An unspendable parent strands every
+   * deposit with no recovery path.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit initialize(parent: UserAddress): [] {
+    const isZero = default<UserAddress> == parent;
+    assert(!isZero, "ForwarderUnshielded: zero parent");
+    assertNotInitialized();
+    _isInitialized = true;
+    _parent = right<ContractAddress, UserAddress>(disclose(parent));
+  }
+
+  // ─── Deposit ────────────────────────────────────────────────────
+
+  /**
+   * @description Receives an unshielded amount of `color` and atomically
+   * forwards it to `_parent` via `sendUnshielded` (always the `right` /
+   * user-address arm today).
+   *
+   * @circuitInfo k=9, rows=436
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @param {Bytes<32>} color - The token color.
+   * @param {Uint<128>} amount - The amount to deposit.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  export circuit _deposit(color: Bytes<32>, amount: Uint<128>): [] {
+    assertInitialized();
+    receiveUnshielded(disclose(color), disclose(amount));
+    sendUnshielded(disclose(color), disclose(amount), _parent);
+  }
+
+  // ─── Init guards ────────────────────────────────────────────────
+
+  /**
+   * @description Asserts that the contract has been initialized, throwing an error if not.
+   *
+   * Requirements:
+   *
+   * - Contract must be initialized.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  circuit assertInitialized(): [] {
+    assert(_isInitialized, "ForwarderUnshielded: contract not initialized");
+  }
+
+  /**
+   * @description Asserts that the contract has not been initialized, throwing an error if it has.
+   *
+   * Requirements:
+   *
+   * - Contract must not be initialized.
+   *
+   * @returns {[]} Empty tuple.
+   */
+  circuit assertNotInitialized(): [] {
+    assert(!_isInitialized, "ForwarderUnshielded: contract already initialized");
+  }
+}