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

package/multisig/presets/NativeShieldedTokenIssuer.compact

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Compact Contracts v0.4.0-alpha.3 (multisig/presets/NativeShieldedTokenIssuer.compact)
+// OpenZeppelin Compact Contracts v0.4.0-alpha.5 (multisig/presets/NativeShieldedTokenIssuer.compact)
 
 pragma language_version >= 0.26.0;
 
@@ -7,8 +7,10 @@ pragma language_version >= 0.26.0;
  * @module NativeShieldedTokenIssuer
  * @description
  * A 2-of-3 ECDSA multisig that mints and burns one native shielded token,
- * for tokenized deposits. Value enters only through `mint` and leaves the
- * contract only through `burn`; each is a single tx carrying two registered
+ * for tokenized deposits. Value enters only through `mint` (to a holder's
+ * coin public key) or `mintToSelf` (a coin this contract holds) and leaves
+ * only through `burn` (a holder's coin, paid into the tx) or `burnFromSelf`
+ * (a coin this contract holds); each is a single tx carrying two registered
  * signers' approvals, so no single party creates or destroys tokens.
  *
  * Composes `EcdsaSignerManager` (signer commitments, approval checks),
@@ -23,8 +25,9 @@ pragma language_version >= 0.26.0;
  * - `DS`: `_domainSeparator`, the EIP-712 domain separator fixed at
  *   construction.
  * - `self`: `kernel.self().bytes`, this contract's address.
- * - `opNonce`: the `_counter` value read at the start of `mint` / `burn`. It
- *   is the signature replay counter and is separate from the
+ * - `opNonce`: the `_counter` value read at the start of every operation
+ *   (`mint`, `mintToSelf`, `burn`, `burnFromSelf`). It is the signature
+ *   replay counter and is separate from the
  *   `NativeShieldedTokenDerivedNonce` counter that feeds coin nonces.
  * - `cm`: a signer commitment, the registry key.
  * - `color`: `tokenType(_domain, self)`, this token's coin color.
@@ -37,16 +40,23 @@ pragma language_version >= 0.26.0;
  *   and a 32-byte address does not fit `address`. `self` inside each struct
  *   separates deployments instead.
  * - Mint digest: `keccak(0x1901 ‖ DS ‖ keccak([MINT_TYPEHASH, self,
- *   recipientWord, boolWord(isContract), uint64Word(opNonce),
- *   uint64Word(amount)]))`, with `canonRecipient =
- *   Utils_canonicalize(recipient)` (unused `Either` arm zeroed),
- *   `recipientWord` its active arm and `isContract = !canonRecipient.is_left`.
+ *   recipient.bytes, uint64Word(opNonce), uint64Word(amount)]))`.
+ * - MintToSelf digest: `keccak(0x1901 ‖ DS ‖ keccak([MINT_TO_SELF_TYPEHASH,
+ *   self, uint64Word(opNonce), uint64Word(amount)]))`.
  * - Burn digest: `keccak(0x1901 ‖ DS ‖ keccak([BURN_TYPEHASH, self,
- *   uint64Word(opNonce), uint64Word(amount)]))`.
+ *   refundTo.bytes, uint64Word(opNonce), uint128Word(amount)]))`.
+ * - BurnFromSelf digest: `keccak(0x1901 ‖ DS ‖ keccak([
+ *   BURN_FROM_SELF_TYPEHASH, self, uint64Word(opNonce), uint128Word(amount),
+ *   coin.nonce, uint128Word(coin.value)]))`. The last two words name the
+ *   holding, so approvals authorize one coin rather than an amount.
  * - Type hashes: `MINT_TYPEHASH = keccak("Mint(bytes32 contractAddress,
- *   bytes32 recipient,bool isContract,uint256 nonce,uint256 amount)")` and
- *   `BURN_TYPEHASH = keccak("Burn(bytes32 contractAddress,uint256 nonce,
- *   uint256 amount)")`, written as literal words.
+ *   bytes32 recipient,uint256 nonce,uint256 amount)")`,
+ *   `MINT_TO_SELF_TYPEHASH = keccak("MintToSelf(bytes32 contractAddress,
+ *   uint256 nonce,uint256 amount)")`, `BURN_TYPEHASH = keccak("Burn(bytes32 contractAddress,bytes32 refundTo,
+ *   uint256 nonce,uint256 amount)")` and `BURN_FROM_SELF_TYPEHASH =
+ *   keccak("BurnFromSelf(bytes32 contractAddress,uint256 nonce,
+ *   uint256 amount,bytes32 coinNonce,uint256 coinValue)")`, written as
+ *   literal words.
  * - Signer commitment: `cm = H<SignerCommitmentInput>({ pkX, pkY, salt,
  *   domain: pad(32, "multisig:signer:") })`, `pkX` / `pkY` the affine
  *   coordinates as `Bytes<32>`. `_calculateSignerId` is the exported pure
@@ -57,7 +67,8 @@ pragma language_version >= 0.26.0;
  *   Digest integers are big-endian ABI words (`utils/EvmAbi`), so an EVM
  *   signer's typed-data encoder reproduces them.
  *   `contracts/src/multisig/test/EcdsaTestUtils.ts` pins the digests
- *   through ethers (`mintMsgHash`, `burnMsgHash`).
+ *   through ethers (`mintMsgHash`, `mintToSelfMsgHash`, `burnMsgHash`,
+ *   `burnFromSelfMsgHash`).
  *
  * @notice Implementing contracts register the signer set from their
  * constructor by calling this module's `initialize`, and MUST NOT import
@@ -68,8 +79,8 @@ pragma language_version >= 0.26.0;
  *
  * @dev Compatibility:
  * The wire format the custodian's signer implements is the EIP-712 domain
- * (`NativeShieldedTokenIssuer`, version `1`, salt), the `Mint` / `Burn`
- * type strings, the `multisig:signer:` commitment domain (generic prefix,
+ * (`NativeShieldedTokenIssuer`, version `1`, salt), the `Mint` /
+ * `MintToSelf` / `Burn` / `BurnFromSelf` type strings, the `multisig:signer:` commitment domain (generic prefix,
  * owned by `EcdsaSignerManager`), the `cm` preimage struct, and the
  * `Vector<2>` / `Vector<3>` shapes. Changing any of them breaks every
  * existing signer setup. The test suite pins them through
@@ -77,22 +88,30 @@ pragma language_version >= 0.26.0;
  *
  * @notice Privacy:
  * - Public, per tx:
- *   - Entry point: mint vs burn.
+ *   - Entry point: which of the four operations ran.
  *   - Approvers: the two signer commitments (`disclose(commitment)` in
  *     `Signer_assertSigner`), so WHICH two of the three signers approved.
  *   - Mint: `amount`, as the `shieldedMints` effect under the token domain,
  *     and the coin commitment as a spend claim. Recipient and nonce are not
  *     published. The nonce is `evolveNonce` of the public
  *     `_derivedNonceCounter`, so a candidate recipient can be tested
- *     against the commitment. A mint to this contract adds the same
- *     commitment as a receive claim and names the contract in the Zswap
- *     output.
- *   - Burn: the spent coin's nullifier, the burn-output commitment and, on a
- *     partial burn, the change commitment as both spend and receive claim.
- *     `amount`, the coin's value and `mt_index` are not published. Every
- *     coin this contract holds was minted to it, so its nullifier is
- *     computable and a burn links to its mint; the amount is protected by
- *     the commitment hash alone.
+ *     against the commitment.
+ *   - MintToSelf: as `mint`, plus the same commitment as a receive claim and
+ *     the contract named in the Zswap output.
+ *   - Burn: the holder's coin commitment as a receive claim, the burn-output
+ *     commitment and, on a partial burn, the refund commitment. `amount`,
+ *     `coin.value` and `refundTo` stay hidden only while `coin` carries a
+ *     nonce the observer does not know. A coin passed straight from `mint`
+ *     has a derived nonce, so the receive claim links the burn to its mint
+ *     and exposes all three by trial: `coin.value` from the mint, `amount`
+ *     over `[0, value]` against the burn output, `refundTo` against the
+ *     refund commitment.
+ *   - BurnFromSelf: the spent coin's nullifier, the burn-output commitment
+ *     and, on a partial burn, the change commitment as both spend and
+ *     receive claim. `amount`, the coin's value and `mt_index` are not
+ *     published, but every held coin has a derived nonce, so its nullifier
+ *     links the burn to its mint and `amount` is recoverable by trial over
+ *     `[0, value]`.
  * - Public, as state:
  *   - Cells: `_counter`, `_domainSeparator`, `_derivedNonceCounter`,
  *     `_signers`, `_signerCount`, `_threshold`, `_instanceSalt`, `_domain`,
@@ -102,37 +121,41 @@ pragma language_version >= 0.26.0;
  * - Private:
  *   - Signer material: public keys and signatures are verified in-circuit,
  *     never disclosed.
- *   - Operation data: burn amounts. Mint recipients, up to the commitment
- *     test above.
+ *   - Operation data: `burn` amounts and `refundTo`, for a coin whose nonce
+ *     is secret. Mint recipients, up to the commitment test above.
  * - Signer identity: keys sit behind `cm` with a public salt, so an observer
  *   holding a candidate key can test membership; one without cannot
  *   correlate a signer across deployments.
  * - Counterparty: a mint recipient learns nothing beyond the coin handed over
  *   out of band; every observer learns the amount of every mint and can
  *   test a candidate recipient against the commitment.
- * - Auditability: mint amounts are public, burn amounts are not. No
+ * - Auditability: mint amounts are public; `burnFromSelf` amounts are
+ *   recoverable by trial, `burn` amounts only for a linkable coin. No
  *   on-chain total is kept. `NativeShieldedTokenPublicSupply` adds one and
  *   makes burn amounts public.
  *
  * @notice Security:
  * - Digest binding: each struct binds its type hash, `self`, `opNonce` and
- *   `amount` (`mint` also the recipient word and its kind) under `DS`, so a
+ *   `amount` (`mint` also `recipient`, `burn` also `refundTo`,
+ *   `burnFromSelf` also `coin.nonce` and `coin.value`) under `DS`, so a
  *   signature authorizes one operation on one instance at one nonce, and is
- *   neither replayable as the other operation, nor under another domain,
+ *   neither replayable as another operation, nor under another domain,
  *   nor redirectable. Removing the `self` word removes cross-instance
- *   replay protection, since `DS` cannot carry the address.
+ *   replay protection, since `DS` cannot carry the address. Only
+ *   `burnFromSelf` binds its coin, because only there does the submitter
+ *   pick it from the contract's own holdings. `Burn` needs no such word. Its
+ *   coin is paid into the tx by whoever submits it so replaying a
+ *   signature against a different coin destroys the submitter's own funds and
+ *   still refunds the bound `refundTo`.
  * - Low-s: verification goes through `Ecdsa_secp256k1EcdsaVerifyLowS`, so a
  *   high-s encoding is an invalid signature.
  * - Distinct signers: `assertApprovals` asserts both entries and rejects a
  *   repeated commitment, so two distinct registered signers are always
- *   required. The threshold `2` is the ceiling `EcdsaSignerManager` accepts.
- * - Canonical recipient: `Utils_canonicalize` zeroes the unused `Either` arm
- *   before hashing and minting, so a recipient with both arms populated
- *   cannot yield two digests for one destination.
+ *   required. The threshold `2` is the only value `EcdsaSignerManager` accepts.
  * - Immutable signer set: no signer reconfiguration circuit is exported, so
  *   the three commitments and the threshold are fixed. Losing two of the
  *   three keys freezes the contract.
- * - Griefing: the derived-nonce mint is the only mint path and it is
+ * - Griefing: the derived-nonce mints are the only mint paths and both are
  *   threshold-gated, so `NativeShieldedTokenDerivedNonce`'s
  *   collision-griefing precondition (a caller-nonce mint at another trust
  *   level) is absent.
@@ -140,24 +163,24 @@ pragma language_version >= 0.26.0;
  *   neither counter advances and the sender pays no fee.
  *
  * @notice Concurrency:
- * - Replay counter: `mint` and `burn` both read `_counter` into the digest.
- *   The read is pinned, so any two of them in one block conflict: at most one
- *   mint-or-burn lands per block, and the losing signer pair re-signs at the
- *   next nonce.
- * - Derived-nonce counter: `mint` also pins it (`evolveNonce` consumes it);
- *   the `_counter` conflict already covers that pair.
- * - `getNonce`: submitted as a tx it pins `_counter` and conflicts with a
- *   same-block mint or burn.
+ * - Replay counter: `mint`, `mintToSelf`, `burn` and `burnFromSelf` read
+ *   `_counter` into the digest. The read is pinned, so any two of them in one block
+ *   conflict: at most one operation lands per block, and the losing signer
+ *   pair re-signs at the next nonce.
+ * - Derived-nonce counter: both mints also pin it (`evolveNonce` consumes
+ *   it); the `_counter` conflict already covers those pairs.
+ * - `getNonce`: submitted as a tx it pins `_counter` and conflicts with any
+ *   same-block operation.
  * - Views: metadata, `tokenColor` and the signer views read only state
  *   written by `initialize`, so they commute with everything.
  *
  * @notice Scope:
  * Mint and burn only. No send, transfer or execute circuit exists, so
- * contract-held coins leave only through `burn`. No deposit or receive
- * circuit exists either: `burn` spends a coin the contract already holds,
- * supplied by the operator as `QualifiedShieldedCoinInfo`. Coins minted to
- * users are ordinary Zswap coins the contract neither tracks nor restricts.
- * No supply accounting.
+ * contract-held coins (from `mintToSelf` or `burnFromSelf` change) leave only
+ * through `burnFromSelf`, supplied by the operator as
+ * `QualifiedShieldedCoinInfo`. Coins minted to users are ordinary
+ * Zswap coins the contract neither tracks nor restricts; a holder redeems by
+ * paying the coin into a `burn` tx. No supply accounting.
  *
  * @notice Client-side duties:
  * - Before deploy: pick a random `instanceSalt`, derive each `cm` with
@@ -165,28 +188,40 @@ pragma language_version >= 0.26.0;
  * - Per operation: read `getNonce()`, rebuild the digest as
  *   `EcdsaTestUtils.ts` does, collect two low-s signatures off-chain, submit
  *   keys and signatures in matching `Vector<2>` positions.
- * - Coin delivery: hand the `ShieldedCoinInfo` returned by `mint` to the
- *   recipient out of band; contract-initiated mints create no ciphertext, so
- *   a wallet cannot find the coin by scanning.
- * - Coin tracking: keep contract-held coins off-chain, recovering each
- *   coin's `mt_index` from the indexer's `ZswapOutput` / ledger events to
- *   build the `QualifiedShieldedCoinInfo` that `burn` takes.
- * - Change coin: persist the one `burn` returns. It replaces the spent coin
- *   as the contract's holding and is not otherwise recoverable.
+ * - `mint`: hand the returned `ShieldedCoinInfo` to the recipient out of
+ *   band; contract-initiated mints create no ciphertext, so a wallet cannot
+ *   find the coin by scanning.
+ * - `mintToSelf`: persist the returned coin as a contract holding, as for
+ *   `burnFromSelf` change.
+ * - `burn`: the holder's wallet funds `coin` into the tx; hand the returned
+ *   refund coin to `refundTo` out of band. For an unlinkable burn the holder
+ *   re-nonces the coin first (a wallet self-transfer yields a fresh secret
+ *   nonce); the minted coin as-is is valid but linkable. The contract cannot
+ *   enforce this.
+ * - `burnFromSelf` coin selection: pick the coin before collecting
+ *   signatures, not after. Its `nonce` and `value` are in the digest, so
+ *   signers approve one holding and the submitted coin must be that one.
+ * - `burnFromSelf` coin tracking: keep contract-held coins off-chain,
+ *   recovering each coin's `mt_index` from the indexer's `ZswapOutput` /
+ *   ledger events to build the `QualifiedShieldedCoinInfo` it takes.
+ * - `burnFromSelf` change coin: it replaces the spent coin as the contract's
+ *   holding. Either persist the coin the circuit returns, or rebuild it from
+ *   the signed `coinNonce` and `coinValue`, which determine it, so recovery
+ *   doesn't need to rest on the submitter alone. Rebuilding leans on the protocol's
+ *   nonce derivation which this module neither defines nor pins.
  *
  * @notice Scalability:
- * - Throughput: one mint-or-burn per block (see Concurrency).
+ * - Throughput: one operation per block (see Concurrency).
  * - State: constant-size, two counters and a three-entry signer set. Nothing
  *   grows per operation.
- * - Amounts: `mint` caps at `Uint<64>` by `mintShieldedToken`; `burn` takes
- *   `Uint<64>` by its signature although `NST__burnFromSelf` accepts
- *   `Uint<128>`.
+ * - Amounts: mints cap at `Uint<64>` by `mintShieldedToken`. Burns take
+ *   `Uint<128>`, the coin value range.
  *
  * @dev Composition:
  * - Recipient privacy: pass a caller-supplied secret random nonce to
- *   `NST__mint` instead of `NSTDerivedNonce__deriveNonce()`.
- * - Deposits: a deposit path needs a `receiveShielded` circuit; none is
- *   included.
+ *   `NST__mint` / `NST__mintToSelf` instead of `NSTDerivedNonce__deriveNonce()`.
+ * - Deposits: no deposit-and-hold path; `burn` receives and spends the
+ *   holder's coin in one call.
  *
  * @notice Requires ZKIR v3: `keccak256` is unavailable on the v2 backend.
  */
@@ -195,7 +230,6 @@ module NativeShieldedTokenIssuer {
 
   import "../EcdsaSignerManager" prefix EcdsaSignerManager_;
   import "../../crypto/Eip712" prefix Eip712_;
-  import "../../utils/Utils" prefix Utils_;
   import "../../utils/EvmAbi" prefix EvmAbi_;
   import "../../token/NativeShieldedToken" prefix NST_;
   import "../../token/extensions/NativeShieldedTokenDerivedNonce" prefix NSTDerivedNonce_;
@@ -212,10 +246,11 @@ module NativeShieldedTokenIssuer {
   export { _derivedNonceCounter };
 
   /**
-   * @description Signature replay counter. `mint` and `burn` read it into
-   * their digest and increment it; `getNonce` returns the value the next
-   * digest binds to. The read is pinned, so at most one mint-or-burn lands
-   * per block.
+   * @description Signature replay counter. Every operation (`mint`,
+   * `mintToSelf`, `burn`, `burnFromSelf`) reads it into its digest and
+   * increments it; `getNonce` returns the value
+   * the next digest binds to. The read is pinned, so at most one operation
+   * lands per block.
    */
   export ledger _counter: Counter;
 
@@ -277,19 +312,39 @@ module NativeShieldedTokenIssuer {
 
   /**
    * @description `keccak256` of the `Mint` type string:
-   * `Mint(bytes32 contractAddress,bytes32 recipient,bool isContract,uint256 nonce,uint256 amount)`
+   * `Mint(bytes32 contractAddress,bytes32 recipient,uint256 nonce,uint256 amount)`
    *
-   * @dev Written as a literal word; see `BURN_TYPEHASH`. The spec checks this
+   * @dev Written as a literal word; see `BURN_FROM_SELF_TYPEHASH`. The spec checks this
    * word against the type string above.
    *
    * @returns {Bytes<32>} The `Mint` type hash.
    */
   pure circuit MINT_TYPEHASH(): Bytes<32> {
     const typeHash: Vector<32, Uint<8>> = [
-      0x28, 0xd4, 0xc8, 0x40, 0xbc, 0x95, 0xfe, 0x08,
-      0x4e, 0xa5, 0xe3, 0x20, 0x94, 0x43, 0xba, 0x67,
-      0x21, 0xb7, 0x17, 0x09, 0x71, 0xee, 0x05, 0xef,
-      0xaf, 0x0a, 0x98, 0x51, 0xee, 0x5f, 0xd1, 0xf5
+      0x65, 0x2d, 0x4d, 0xad, 0x8f, 0xb2, 0x6c, 0x5c,
+      0x50, 0xc9, 0x87, 0xd4, 0x19, 0xdc, 0x93, 0x53,
+      0x14, 0xa0, 0x1e, 0xd4, 0x5d, 0xb1, 0x59, 0xf2,
+      0x30, 0xad, 0xc1, 0xa7, 0xe9, 0x02, 0x91, 0x1c
+    ];
+
+    return typeHash as Bytes<32>;
+  }
+
+  /**
+   * @description `keccak256` of the `MintToSelf` type string:
+   * `MintToSelf(bytes32 contractAddress,uint256 nonce,uint256 amount)`
+   *
+   * @dev Written as a literal word; see `BURN_FROM_SELF_TYPEHASH`. The spec
+   * checks this word against the type string above.
+   *
+   * @returns {Bytes<32>} The `MintToSelf` type hash.
+   */
+  pure circuit MINT_TO_SELF_TYPEHASH(): Bytes<32> {
+    const typeHash: Vector<32, Uint<8>> = [
+      0xf8, 0xb3, 0x1e, 0x4e, 0x0f, 0x2d, 0x10, 0x33,
+      0x82, 0xb4, 0xb3, 0x72, 0xac, 0x65, 0xa7, 0xad,
+      0xcd, 0x03, 0x89, 0x39, 0x8d, 0x24, 0x6c, 0x5e,
+      0xc2, 0xc9, 0x09, 0x38, 0x53, 0xdb, 0x49, 0x91
     ];
 
     return typeHash as Bytes<32>;
@@ -297,21 +352,41 @@ module NativeShieldedTokenIssuer {
 
   /**
    * @description `keccak256` of the `Burn` type string:
-   * `Burn(bytes32 contractAddress,uint256 nonce,uint256 amount)`
+   * `Burn(bytes32 contractAddress,bytes32 refundTo,uint256 nonce,uint256 amount)`
+   *
+   * @dev Written as a literal word; see `BURN_FROM_SELF_TYPEHASH`. The spec
+   * checks this word against the type string above.
+   *
+   * @returns {Bytes<32>} The `Burn` type hash.
+   */
+  pure circuit BURN_TYPEHASH(): Bytes<32> {
+    const typeHash: Vector<32, Uint<8>> = [
+      0x96, 0x8e, 0x03, 0xa5, 0xba, 0x91, 0xc8, 0xdd,
+      0x27, 0x56, 0x79, 0x5a, 0xc6, 0x57, 0x52, 0x13,
+      0x06, 0xe0, 0xd9, 0x7c, 0xe8, 0x1e, 0xbf, 0x9b,
+      0x68, 0x24, 0x45, 0xa2, 0x86, 0xfc, 0xeb, 0xef
+    ];
+
+    return typeHash as Bytes<32>;
+  }
+
+  /**
+   * @description `keccak256` of the `BurnFromSelf` type string:
+   * `BurnFromSelf(bytes32 contractAddress,uint256 nonce,uint256 amount,bytes32 coinNonce,uint256 coinValue)`
    *
    * @dev Written as a literal word. `compactc` emits a full keccak
    * permutation even for a constant argument, so hashing the type string
    * in-circuit would add ~4.2k rows to every operation. The spec checks this
    * word against the type string above.
    *
-   * @returns {Bytes<32>} The `Burn` type hash.
+   * @returns {Bytes<32>} The `BurnFromSelf` type hash.
    */
-  pure circuit BURN_TYPEHASH(): Bytes<32> {
+  pure circuit BURN_FROM_SELF_TYPEHASH(): Bytes<32> {
     const typeHash: Vector<32, Uint<8>> = [
-      0xdf, 0x62, 0xd6, 0x7d, 0x39, 0x08, 0x06, 0xa6,
-      0xb6, 0x3f, 0xbd, 0x9f, 0xb5, 0xb8, 0x90, 0x4e,
-      0xf8, 0x6a, 0x4d, 0x67, 0xf3, 0x82, 0x4a, 0x3d,
-      0x85, 0x5f, 0x6e, 0xef, 0xb8, 0xe7, 0x98, 0x09
+      0x50, 0xa1, 0xf2, 0x88, 0xba, 0xb8, 0x77, 0x4b,
+      0x1f, 0x55, 0x86, 0x31, 0xc7, 0x75, 0xda, 0x49,
+      0xec, 0x20, 0x4e, 0x07, 0xcf, 0x88, 0x53, 0x9b,
+      0xca, 0x8e, 0xb9, 0x8c, 0xac, 0xf4, 0x5b, 0xe9
     ];
 
     return typeHash as Bytes<32>;
@@ -348,7 +423,7 @@ module NativeShieldedTokenIssuer {
    * @notice The returned coin info is the only copy available to the
    * recipient; deliver it out of band.
    *
-   * @constraints k=17, rows=105173 (zkir-v3)
+   * @constraints k=17, rows=89815 (zkir-v3)
    *
    * Requirements:
    *
@@ -357,61 +432,135 @@ module NativeShieldedTokenIssuer {
    * - Signers must not be duplicates.
    * - Threshold must be met.
    * - `recipient` is not zero.
-   * - A contract `recipient` is this contract's own address.
    *
    * @param {Uint<64>} amount - The token amount to mint.
-   * @param {Either<ZswapCoinPublicKey, ContractAddress>} recipient - The address to receive the minted tokens.
+   * @param {ZswapCoinPublicKey} recipient - The coin public key to receive the minted tokens.
    * @param {Vector<2, Secp256k1Point>} pubkeys - Public keys of approving signers.
    * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - ECDSA signatures over the mint hash.
    * @returns {ShieldedCoinInfo} The minted coin (nonce, color, value).
    */
   export circuit mint(
     amount: Uint<64>,
-    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
+    recipient: ZswapCoinPublicKey,
     pubkeys: Vector<2, Secp256k1Point>,
     signatures: Vector<2, Secp256k1EcdsaSignature>
   ): ShieldedCoinInfo {
     const opNonce = _counter;
     _counter.increment(1);
 
-    // Canonicalize recipient to ensure garbage values don't sully the hash
-    const canonRecipient = Utils_canonicalize<ZswapCoinPublicKey, ContractAddress>(recipient);
+    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<5, Bytes<32>>>([
+      MINT_TYPEHASH(),
+      // Binds the digest to this deployment. The domain cannot carry the
+      // address, so removing this word removes cross-instance replay
+      // protection.
+      kernel.self().bytes,
+      recipient.bytes,
+      EvmAbi_uint64Word(opNonce),
+      EvmAbi_uint64Word(amount)
+    ]));
+
+    EcdsaSignerManager_assertApprovals(msgHash, pubkeys, signatures);
 
-    // Only the active arm reaches the digest, so a crafted value carrying data
-    // in its unused arm cannot alter what was signed.
-    const recipientWord = canonRecipient.is_left
-      ? canonRecipient.left.bytes
-      : canonRecipient.right.bytes;
+    return NST__mint(recipient, amount, NSTDerivedNonce__deriveNonce());
+  }
 
-    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<6, Bytes<32>>>([
-      MINT_TYPEHASH(),
+  /**
+   * @description Mints a new shielded coin of this contract's token to the
+   * contract itself, claimed in the same call, authorized by threshold
+   * signatures.
+   *
+   * @notice The returned coin info is the contract's only record of the
+   * holding; persist it for `burnFromSelf`.
+   *
+   * @constraints k=17, rows=85594 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - Both public keys must hash to registered signer commitments.
+   * - Both signatures must be valid over the mint-to-self message hash.
+   * - Signers must not be duplicates.
+   * - Threshold must be met.
+   *
+   * @param {Uint<64>} amount - The token amount to mint.
+   * @param {Vector<2, Secp256k1Point>} pubkeys - Public keys of approving signers.
+   * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - ECDSA signatures over the mint-to-self hash.
+   * @returns {ShieldedCoinInfo} The minted coin (nonce, color, value).
+   */
+  export circuit mintToSelf(
+    amount: Uint<64>,
+    pubkeys: Vector<2, Secp256k1Point>,
+    signatures: Vector<2, Secp256k1EcdsaSignature>
+  ): ShieldedCoinInfo {
+    const opNonce = _counter;
+    _counter.increment(1);
+
+    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<4, Bytes<32>>>([
+      MINT_TO_SELF_TYPEHASH(),
       // Binds the digest to this deployment. The domain cannot carry the
       // address, so removing this word removes cross-instance replay
       // protection.
       kernel.self().bytes,
-      recipientWord,
-      EvmAbi_boolWord(!canonRecipient.is_left),
       EvmAbi_uint64Word(opNonce),
       EvmAbi_uint64Word(amount)
     ]));
 
     EcdsaSignerManager_assertApprovals(msgHash, pubkeys, signatures);
 
-    // `NST__mint` takes a coin public key only; the contract arm is limited to
-    // this contract, since a mint to any other contract leaves an unclaimed
-    // output.
-    // The recipient is public (it is already in the signed digest), so the
-    // arm may gate which mint runs.
-    const target = disclose(canonRecipient);
-    const self = kernel.self();
-    assert(target.is_left || target.right == self,
-           "NativeShieldedToken: recipient contract must be self");
-    const nonce = NSTDerivedNonce__deriveNonce();
-    if (target.is_left) {
-      return NST__mint(target.left, amount, nonce);
-    } else {
-      return NST__mintToSelf(amount, nonce);
-    }
+    return NST__mintToSelf(amount, NSTDerivedNonce__deriveNonce());
+  }
+
+  /**
+   * @description Burns `amount` from a holder's coin, authorized by threshold
+   * signatures. The holder's transaction pays `coin` in; the contract
+   * receives it and burns it in the same call. Any change goes to `refundTo`.
+   *
+   * @notice The returned refund coin info is the only copy available to
+   * `refundTo`; deliver it out of band.
+   *
+   * @constraints k=17, rows=119826 (zkir-v3)
+   *
+   * Requirements:
+   *
+   * - Both public keys must hash to registered signer commitments.
+   * - Both signatures must be valid over the burn message hash.
+   * - Signers must not be duplicates.
+   * - Threshold must be met.
+   * - `coin.color` is this contract's token color.
+   * - `amount` is less than or equal to `coin.value`.
+   * - `refundTo` is not zero.
+   *
+   * @param {ShieldedCoinInfo} coin - The holder's coin to burn from.
+   * @param {Uint<128>} amount - The token amount to burn.
+   * @param {ZswapCoinPublicKey} refundTo - Receives `coin.value - amount`.
+   * @param {Vector<2, Secp256k1Point>} pubkeys - Public keys of approving signers.
+   * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - ECDSA signatures over the burn hash.
+   * @returns {Maybe<ShieldedCoinInfo>} The refund coin created for `refundTo`,
+   * or `none` if the coin was burned in full.
+   */
+  export circuit burn(
+    coin: ShieldedCoinInfo,
+    amount: Uint<128>,
+    refundTo: ZswapCoinPublicKey,
+    pubkeys: Vector<2, Secp256k1Point>,
+    signatures: Vector<2, Secp256k1EcdsaSignature>
+  ): Maybe<ShieldedCoinInfo> {
+    const opNonce = _counter;
+    _counter.increment(1);
+
+    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<5, Bytes<32>>>([
+      BURN_TYPEHASH(),
+      // Binds the digest to this deployment. The domain cannot carry the
+      // address, so removing this word removes cross-instance replay
+      // protection.
+      kernel.self().bytes,
+      refundTo.bytes,
+      EvmAbi_uint64Word(opNonce),
+      EvmAbi_uint128Word(amount)
+    ]));
+
+    EcdsaSignerManager_assertApprovals(msgHash, pubkeys, signatures);
+
+    return NST__burn(coin, amount, refundTo);
   }
 
   /**
@@ -423,41 +572,47 @@ module NativeShieldedTokenIssuer {
    * and returned; it replaces `coin` as the contract's holding, so the
    * operator must persist it.
    *
-   * @constraints k=17, rows=97232 (zkir-v3)
+   * The digest binds `coin.nonce` and `coin.value`, so approvals authorize one
+   * specific holding rather than an amount.
+   *
+   * @constraints k=17, rows=104981 (zkir-v3)
    *
    * Requirements:
    *
    * - Both public keys must hash to registered signer commitments.
-   * - Both signatures must be valid over the burn message hash.
+   * - Both signatures must be valid over the burn-from-self message hash.
    * - Signers must not be duplicates.
    * - Threshold must be met.
    * - `coin.color` is this contract's token color.
    * - `amount` is less than or equal to `coin.value`.
+   * - `coin.nonce` and `coin.value` match the approved coin.
    *
    * @param {QualifiedShieldedCoinInfo} coin - The contract-held coin to burn from.
-   * @param {Uint<64>} amount - The token amount to burn.
+   * @param {Uint<128>} amount - The token amount to burn.
    * @param {Vector<2, Secp256k1Point>} pubkeys - Public keys of approving signers.
-   * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - ECDSA signatures over the burn hash.
+   * @param {Vector<2, Secp256k1EcdsaSignature>} signatures - ECDSA signatures over the burn-from-self hash.
    * @returns {Maybe<ShieldedCoinInfo>} The change coin retained by the
    * contract, or `none` if the coin was burned in full.
    */
-  export circuit burn(
+  export circuit burnFromSelf(
     coin: QualifiedShieldedCoinInfo,
-    amount: Uint<64>,
+    amount: Uint<128>,
     pubkeys: Vector<2, Secp256k1Point>,
     signatures: Vector<2, Secp256k1EcdsaSignature>
   ): Maybe<ShieldedCoinInfo> {
     const opNonce = _counter;
     _counter.increment(1);
 
-    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<4, Bytes<32>>>([
-      BURN_TYPEHASH(),
+    const msgHash = Eip712_hashTypedData(_domainSeparator, keccak256<Vector<6, Bytes<32>>>([
+      BURN_FROM_SELF_TYPEHASH(),
       // Binds the digest to this deployment. The domain cannot carry the
       // address, so removing this word removes cross-instance replay
       // protection.
       kernel.self().bytes,
       EvmAbi_uint64Word(opNonce),
-      EvmAbi_uint64Word(amount)
+      EvmAbi_uint128Word(amount),
+      coin.nonce,
+      EvmAbi_uint128Word(coin.value)
     ]));
 
     EcdsaSignerManager_assertApprovals(msgHash, pubkeys, signatures);
@@ -466,7 +621,7 @@ module NativeShieldedTokenIssuer {
   }
 
   /**
-   * @description Returns the counter the next mint or burn digest will bind to.
+   * @description Returns the counter the next operation's digest will bind to.
    *
    * @constraints k=6, rows=34 (zkir-v3)
    *