@coti-io/coti-contracts 1.1.0 → 1.3.0

package/contracts/token/PrivateERC20/PrivateERC20.sol

@@ -4,18 +4,96 @@ pragma solidity ^0.8.19;
 
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IPrivateERC20} from "./IPrivateERC20.sol";
+import {ITokenReceiver} from "./ITokenReceiver.sol";
+import {ITokenReceiverEncrypted} from "./ITokenReceiverEncrypted.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+import {ERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 import "../../utils/mpc/MpcCore.sol";
 
-abstract contract PrivateERC20 is Context, IPrivateERC20 {
-    uint64 private constant MAX_UINT_64 = type(uint64).max;
+/*
+THIS IS THE 256 BIT VERSION OF PRIVATE ERC20.
+
+Key Features:
+- Full uint256 support (no scaling factors)
+- AccessControl (for Bridge Integrations)
+- ERC165 Support - Tokens Discoverability
+- Payable Tokens with TransferAndCall (ERC677-like callback pattern)
+- Encrypted Operations (Mint, Burn, Transfer, Approve)
+
+Failure semantics (integrators and contract callers):
+- State-changing operations that move value or change supply/allowances are designed to follow a
+  revert-on-failure model: if the MPC layer reports that the core update did not succeed, the
+  transaction reverts (enforced in {_update} for mint/transfer/burn, and via explicit requires
+  where an operation composes multiple steps). Success is therefore implied by a completed call
+  that did not revert. Pure/view helpers and read paths that only return ciphertext or onboarded
+  values are not “success/failure” token operations in that sense.
+
+Storage encoding ({_safeOnboard} — see implementation NatSpec):
+- Uninitialized or zeroed `ctUint256` slots read as both 128-bit limbs zero. The implementation
+  treats that as **canonical empty** and maps it to `MpcCore.setPublic256(0)` without calling
+  `MpcCore.onBoard` (gas). Any other pattern is onboarded with `MpcCore.onBoard`.
+- Successful updates in this contract only write ciphertext via `MpcCore.offBoard` after MPC
+  success, so balances, allowances, and aggregate supply stay consistent with the precompile.
+
+Trust assumptions (deploy only when these hold):
+- Deploy only on chains where the MPC precompile at address(0x64) is part of the trusted base.
+  You explicitly trust that network: its consensus, node/precompile implementation, and upgrade
+  policy. All balances and transfers are ultimately defined by MPC results this contract cannot
+  independently verify. If the precompile were malicious or buggy, accounting integrity could fail
+  in ways Solidity cannot fix on-chain. Optional mitigations (e.g. admin pause, monitoring) only
+  limit further damage after suspicion; they do not prove past MPC correctness or roll back state.
+  If the chain allows precompile upgrades, consider monitoring and circuit-breakers.
+- There is **no** trust-minimized substitute on-chain: auditors and integrators should record which
+  chain ID, precompile address, and build/version they rely on, and treat MPC upgrades as **trusted**
+  migrations unless your organization runs independent off-chain verification against published specs.
+- MINTER_ROLE must only pass valid amounts to mint/mintGt/mint(itUint256). If the MPC layer
+  enforces bounds or validity, that dependency applies.
+- Minting is bounded by {supplyCap} (override in concrete tokens like {decimals}); enforced in {_update}.
+- Integrators — {totalSupply} vs supply: the default {totalSupply} returns 0 and does **not** reflect
+  circulating aggregate supply (see {totalSupply} NatSpec). Do not plug this token into protocols that
+  assume ERC-20 `totalSupply` semantics. Use {supplyCap} only as the **mint ceiling** parameter; for
+  actual supply, use off-chain indexing or a dedicated extension (e.g. auditor reencryption mocks).
+- Gas: multiple precompile calls per transfer/approve; no unbounded loops. Document expected
+  gas ranges for common operations if needed for integrators.
+- Reentrancy: balance/allowance-changing entry points use nonReentrant so a transferAndCall
+  receiver cannot nest transferFrom/transfer/approve/increaseAllowance/decreaseAllowance/mint/burn in the same transaction.
+- transferAndCall: public-amount overload uses {ITokenReceiver}; encrypted-amount overload uses
+  {ITokenReceiverEncrypted} (no plaintext amount in callback). Receivers are still fully trusted
+  for callback behavior.
+*/
+
+/**
+ * @title PrivateERC20
+ * @notice Privacy-oriented ERC-20 base whose balances and transfer rules are enforced through MPC (`MpcCore`), not plain EVM arithmetic on cleartext balances.
+ * @dev **MPC trust model:** This contract treats the MPC precompile as the source of truth for
+ *      garbled/encrypted `uint256` operations. There is no on-chain fallback that validates MPC
+ *      soundness. See {IPrivateERC20} trust assumptions and the file-level comment block above for
+ *      deployment and integration requirements. Pausing and `AccessControl` mitigate operational
+ *      risk; they do not prove MPC correctness retroactively.
+ */
+abstract contract PrivateERC20 is
+    Context,
+    ERC165,
+    IPrivateERC20,
+    AccessControl,
+    ReentrancyGuard
+{
+    uint256 private constant MAX_UINT_256 = type(uint256).max;
+
+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+
+    /// @dev Controls whether public uint256 operations are allowed (mint/burn/transfer/transferFrom/approve/transferAndCall with clear values).
+    bool public publicAmountsEnabled;
 
     mapping(address account => address) private _accountEncryptionAddress;
 
-    mapping(address account => utUint64) private _balances;
+    mapping(address account => utUint256) private _balances;
 
-    mapping(address account => mapping(address spender => Allowance)) private _allowances;
+    mapping(address account => mapping(address spender => Allowance))
+        private _allowances;
 
-    ctUint64 private _totalSupply;
+    ctUint256 private _totalSupply;
 
     string private _name;
 
@@ -45,15 +123,54 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      */
     error ERC20InvalidSpender(address spender);
 
+    /**
+     * @dev Indicates that clear (public) uint256 operations are disabled for this token.
+     */
+    error PublicAmountsDisabled();
+
+    /**
+     * @dev Indicates that transferAndCall was used with a non-contract recipient.
+     *      transferAndCall is for contract-to-contract flows; the recipient must have code.
+     */
+    error TransferAndCallRequiresContract(address to);
+
+    /**
+     * @dev Indicates that a transfer to self (from == to) was attempted.
+     *      CRITICAL: Self-transfer is explicitly disallowed. The MPC precompile behavior when
+     *      from == to is undefined; allowing it could lead to incorrect balance updates or
+     *      inconsistent state. All transfer/transferFrom paths go through _transfer and are
+     *      therefore protected.
+     */
+    error ERC20SelfTransferNotAllowed(address account);
+
+    /**
+     * @dev Indicates that name or symbol was empty in the constructor.
+     */
+    error ERC20InvalidMetadata();
+
+    /**
+     * @dev Emitted when the admin enables or disables public uint256 operations.
+     */
+    event PublicAmountsEnabledSet(bool enabled);
+
+    /**
+     * @dev Emitted when an account sets or changes its encryption address for balance reencryption.
+     */
+    event AccountEncryptionAddressSet(address indexed account, address indexed newAddress);
+
     /**
      * @dev Sets the values for {name} and {symbol}.
      *
-     * All two of these values are immutable: they can only be set once during
+     * Both of these values are immutable: they can only be set once during
      * construction.
      */
     constructor(string memory name_, string memory symbol_) {
+        if (bytes(name_).length == 0) revert ERC20InvalidMetadata();
+        if (bytes(symbol_).length == 0) revert ERC20InvalidMetadata();
         _name = name_;
         _symbol = symbol_;
+        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
+        publicAmountsEnabled = true;
     }
 
     /**
@@ -85,49 +202,219 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      * {IPrivateERC20-balanceOf} and {IPrivateERC20-transfer}.
      */
     function decimals() public view virtual returns (uint8) {
-        return 6;
+        return 18;
     }
 
     /**
-     * @dev See {IPrivateERC20-totalSupply}.
+     * @dev Configurable **upper bound** on how much can be minted in aggregate (checked in {_update} against
+     *      the encrypted total in storage). This is **not** “current circulating supply” and **not** a live
+     *      substitute for {totalSupply} on a normal ERC-20. Default: `type(uint256).max`.
+     *
+     *      Override in concrete tokens when a fixed cap is required (e.g. with {decimals} or tokenomics).
      */
-    function totalSupply() public view virtual returns (uint256) {
+    function supplyCap() public view virtual returns (uint256) {
+        return type(uint256).max;
+    }
+
+    /**
+     * @inheritdoc IPrivateERC20
+     * @notice Deliberately **not** standard ERC-20 circulating supply: returns `0` in this implementation.
+     *
+     * Do **not** use for vault share math, pro-rata rewards, or oracles that expect `totalSupply` to reflect
+     * aggregate issuance. For the mint **ceiling**, use {supplyCap}. For optional encrypted aggregate supply
+     * to a designated party, see examples under `contracts/mocks/token/PrivateERC20/`.
+     */
+    function totalSupply() public view virtual override returns (uint256) {
         return 0;
     }
 
-    function accountEncryptionAddress(address account) public view returns (address) {
+    function mint(
+        address to,
+        uint256 amount
+    ) public virtual override onlyRole(MINTER_ROLE) nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        gtUint256 gtAmount = MpcCore.setPublic256(amount);
+        _mint(to, gtAmount);
+    }
+
+    /**
+     * @dev Mint an already-garbled amount without re-wrapping.
+     * Intended for contract-to-contract flows that already hold a gtUint256.
+     * Trust: MINTER_ROLE must only pass valid amounts. Reverts if {_update} reports MPC failure.
+     */
+    function mintGt(
+        address to,
+        gtUint256 gtAmount
+    ) public virtual override onlyRole(MINTER_ROLE) nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        _mint(to, gtAmount);
+    }
+
+    /**
+     * @dev Mint with encrypted (itUint256) amount.
+     * Trust: MINTER_ROLE must only pass valid amounts. Reverts if {_update} reports MPC failure.
+     */
+    function mint(
+        address to,
+        itUint256 calldata amount
+    ) public virtual override onlyRole(MINTER_ROLE) nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        gtUint256 gtAmount = MpcCore.validateCiphertext(amount);
+        _mint(to, gtAmount);
+    }
+
+    function burn(uint256 amount) public virtual override nonReentrant {
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        gtUint256 gtAmount = MpcCore.setPublic256(amount);
+        _burn(_msgSender(), gtAmount);
+    }
+
+    /**
+     * @dev Burn an already-garbled amount without re-wrapping.
+     * Intended for contract-to-contract flows that already hold a gtUint256.
+     * Reverts if {_update} reports MPC failure.
+     */
+    function burnGt(gtUint256 gtAmount) public virtual override nonReentrant {
+        _burn(_msgSender(), gtAmount);
+    }
+
+    /// @dev Reverts if {_update} reports MPC failure.
+    function burn(itUint256 calldata amount) public virtual override nonReentrant {
+        gtUint256 gtAmount = MpcCore.validateCiphertext(amount);
+        _burn(_msgSender(), gtAmount);
+    }
+
+    /**
+     * @dev Transfers tokens to `to` then calls onTokenReceived(to, amount, data).
+     *      Only use with trusted receivers. `nonReentrant` blocks re-entry into this function and
+     *      into other guarded entry points (transfer, transferFrom, approve, burn, mint, etc.);
+     *      the receiver must still be trusted for protocol correctness.
+     */
+    function transferAndCall(
+        address to,
+        uint256 amount,
+        bytes calldata data
+    ) public virtual override nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        if (to.code.length == 0) revert TransferAndCallRequiresContract(to);
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+
+        gtUint256 gtAmount = MpcCore.setPublic256(amount);
+        address sender = _msgSender();
+        _transfer(sender, to, gtAmount);
+
+        require(
+            ITokenReceiver(to).onTokenReceived(sender, amount, data),
+            "Callback failed"
+        );
+    }
+
+    /**
+     * @dev Transfers an encrypted amount to `to`, then calls {ITokenReceiverEncrypted-onPrivateTransferReceived}.
+     *      The callback does **not** receive a plaintext amount (privacy). Receivers must implement
+     *      {ITokenReceiverEncrypted}; do not use {ITokenReceiver} for this overload.
+     *      Only use with **trusted** receivers; see {transferAndCall(address,uint256,bytes)} for reentrancy scope.
+     */
+    function transferAndCall(
+        address to,
+        itUint256 calldata amount,
+        bytes calldata data
+    ) public virtual override nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        if (to.code.length == 0) revert TransferAndCallRequiresContract(to);
+
+        gtUint256 gtAmount = MpcCore.validateCiphertext(amount);
+        address sender = _msgSender();
+        _transfer(sender, to, gtAmount);
+
+        require(
+            ITokenReceiverEncrypted(to).onPrivateTransferReceived(sender, data),
+            "Callback failed"
+        );
+    }
+
+    function supportsInterface(
+        bytes4 interfaceId
+    ) public view virtual override(AccessControl, ERC165) returns (bool) {
+        return
+            interfaceId == type(IPrivateERC20).interfaceId ||
+            super.supportsInterface(interfaceId);
+    }
+
+    /**
+     * @dev Returns the encryption address set for `account` for balance reencryption.
+     *
+     * Requirements:
+     * - `account` must not be the zero address.
+     */
+    function accountEncryptionAddress(
+        address account
+    ) public view returns (address) {
+        if (account == address(0)) revert ERC20InvalidReceiver(address(0));
         return _accountEncryptionAddress[account];
-    } 
+    }
 
     /**
      * @dev See {IPrivateERC20-balanceOf}.
+     *
+     * Requirements:
+     * - `account` must not be the zero address.
      */
-    function balanceOf(address account) public view virtual returns (ctUint64) {
+    function balanceOf(
+        address account
+    ) public view virtual override returns (ctUint256 memory) {
+        if (account == address(0)) revert ERC20InvalidReceiver(address(0));
         return _balances[account].userCiphertext;
     }
 
     /**
      * @dev See {IPrivateERC20-balanceOf}.
+     *      May perform external calls to the MPC precompile via _getBalance.
+     *      Do not use in staticcall or view contexts; off-chain code must not assume this is view-safe.
      */
-    function balanceOf() public virtual returns (gtUint64) {
+    function balanceOf() public virtual override returns (gtUint256) {
         return _getBalance(_msgSender());
     }
 
     /**
      * @dev See {IPrivateERC20-setAccountEncryptionAddress}.
-     * 
+     *
      * NOTE: This will not reencrypt your allowances until they are changed
      */
-    function setAccountEncryptionAddress(address offBoardAddress) public virtual returns (bool) {
-        gtUint64 gtBalance = _getBalance(_msgSender());
+    function setAccountEncryptionAddress(
+        address offBoardAddress
+    ) public virtual override nonReentrant returns (bool) {
+        if (offBoardAddress == address(0)) revert ERC20InvalidReceiver(address(0));
+
+        gtUint256 gtBalance = _getBalance(_msgSender());
+
+        // Compute new user ciphertext first; reverts if precompile fails. Only then update storage
+        // so that we never leave _accountEncryptionAddress and userCiphertext out of sync.
+        ctUint256 memory newUserCiphertext = MpcCore.offBoardToUser(
+            gtBalance,
+            offBoardAddress
+        );
 
-        _accountEncryptionAddress[_msgSender()] = offBoardAddress;
+        address account = _msgSender();
+        _accountEncryptionAddress[account] = offBoardAddress;
+        _balances[account].userCiphertext = newUserCiphertext;
 
-        _balances[_msgSender()].userCiphertext = MpcCore.offBoardToUser(gtBalance, offBoardAddress);
+        emit AccountEncryptionAddressSet(account, offBoardAddress);
 
         return true;
     }
-    
+
+    /**
+     * @dev Enables or disables operations that use clear public uint256 amounts
+     *      (mint, burn, transfer, transferFrom, approve, transferAndCall with uint256).
+     *      Intended to be called by the token admin to disallow public value usage if desired.
+     */
+    function setPublicAmountsEnabled(bool enabled) external onlyRole(DEFAULT_ADMIN_ROLE) {
+        publicAmountsEnabled = enabled;
+        emit PublicAmountsEnabledSet(enabled);
+    }
+
     /**
      * @dev See {IPrivateERC20-transfer}.
      *
@@ -135,105 +422,252 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      *
      * - `to` cannot be the zero address.
      * - the caller must have a balance of at least `value`.
+     *
+     * Reverts if {_update} reports MPC failure. Success is implied by absence of revert.
      */
-    function transfer(address to, itUint64 calldata value) public virtual returns (gtBool) {
+    /// @notice Transfer with encrypted (itUint256) amount
+    function transfer(
+        address to,
+        itUint256 calldata value
+    ) public virtual override nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
         address owner = _msgSender();
 
-        gtUint64 gtValue = MpcCore.validateCiphertext(value);
+        gtUint256 gtValue = MpcCore.validateCiphertext(value);
 
-        return _transfer(owner, to, gtValue);
+        _transfer(owner, to, gtValue);
     }
 
-    /**
-     * @dev See {IPrivateERC20-transfer}.
-     *
-     * Requirements:
-     *
-     * - `to` cannot be the zero address.
-     * - the caller must have a balance of at least `value`.
-     */
-    function transfer(address to, gtUint64 value) public virtual returns (gtBool) {
+    /// @notice Transfer with garbled-text (gtUint256) amount. Reverts if {_update} reports MPC failure.
+    function transferGT(
+        address to,
+        gtUint256 value
+    ) public virtual override nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        address owner = _msgSender();
+
+        _transfer(owner, to, value);
+    }
+
+    /// @notice Transfer with plain public uint256 amount
+    function transfer(
+        address to,
+        uint256 value
+    ) public virtual override nonReentrant {
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
         address owner = _msgSender();
 
-        return _transfer(owner, to, value);
+        gtUint256 gtValue = MpcCore.setPublic256(value);
+
+        _transfer(owner, to, gtValue);
     }
 
     /**
      * @dev See {IPrivateERC20-allowance}.
+     *
+     * Requirements:
+     * - `owner` and `spender` must not be the zero address.
      */
-    function allowance(address owner, address spender) public view virtual returns (Allowance memory) {
+    function allowance(
+        address owner,
+        address spender
+    ) public view virtual override returns (Allowance memory) {
+        if (owner == address(0)) revert ERC20InvalidApprover(address(0));
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
         return _allowances[owner][spender];
     }
 
     /**
      * @dev See {IPrivateERC20-allowance}.
+     *      May perform external calls to the MPC precompile via _safeOnboard.
+     *      Do not use in staticcall or view contexts; off-chain code must not assume this is view-safe.
+     *
+     * Requirements:
+     * - `account` must not be the zero address.
      */
-    function allowance(address account, bool isSpender) public virtual returns (gtUint64) {
+    function allowance(
+        address account,
+        bool isSpender
+    ) public virtual override returns (gtUint256) {
+        if (account == address(0)) revert ERC20InvalidReceiver(address(0));
         if (isSpender) {
-            return _safeOnboard(_allowances[_msgSender()][account].ciphertext);
-        } else {
+            // Caller is spender; `account` is owner — read _allowances[owner][spender]
             return _safeOnboard(_allowances[account][_msgSender()].ciphertext);
+        } else {
+            // Caller is owner; `account` is spender — read _allowances[owner][spender]
+            return _safeOnboard(_allowances[_msgSender()][account].ciphertext);
         }
     }
 
-    function reencryptAllowance(address account, bool isSpender) public virtual returns (bool) {
+    /**
+     * @dev Reencrypts the caller's view of an allowance (as owner or spender) using the caller's encryption address.
+     *
+     * Requirements:
+     * - `account` must not be the zero address.
+     * - Caller must have an encryption address set (EOA or contract with setAccountEncryptionAddress).
+     *
+     * Emits an {AllowanceReencrypted} event.
+     */
+    function reencryptAllowance(
+        address account,
+        bool isSpender
+    ) public virtual nonReentrant {
+        if (account == address(0)) revert ERC20InvalidReceiver(address(0));
         address encryptionAddress = _getAccountEncryptionAddress(_msgSender());
+        if (encryptionAddress == address(0)) revert ERC20InvalidReceiver(address(0));
+
+        address owner_;
+        address spender_;
 
         if (isSpender) {
-            Allowance storage allowance_ = _allowances[_msgSender()][account];
+            // Caller is spender; `account` is owner — _allowances[owner][spender]
+            owner_ = account;
+            spender_ = _msgSender();
+            Allowance storage allowance_ = _allowances[owner_][spender_];
 
-            allowance_.ownerCiphertext = MpcCore.offBoardToUser(
+            allowance_.spenderCiphertext = MpcCore.offBoardToUser(
                 _safeOnboard(allowance_.ciphertext),
                 encryptionAddress
             );
         } else {
-            Allowance storage allowance_ = _allowances[account][_msgSender()];
+            // Caller is owner; `account` is spender — _allowances[owner][spender]
+            owner_ = _msgSender();
+            spender_ = account;
+            Allowance storage allowance_ = _allowances[owner_][spender_];
 
-            allowance_.spenderCiphertext = MpcCore.offBoardToUser(
+            allowance_.ownerCiphertext = MpcCore.offBoardToUser(
                 _safeOnboard(allowance_.ciphertext),
                 encryptionAddress
             );
         }
 
-        return true;
+        emit AllowanceReencrypted(owner_, spender_, isSpender);
     }
 
     /**
      * @dev See {IPrivateERC20-approve}.
      *
-     * NOTE: If `value` is the maximum `itUint64`, the allowance is not updated on
+     * NOTE: If `value` is the maximum `itUint256`, the allowance is not updated on
      * `transferFrom`. This is semantically equivalent to an infinite approval.
      *
+     * Reverts with {ERC20UnsafeApprove} if both the current allowance and the new value are
+     * non-zero (same mitigation as {approve(address,uint256)}). Prefer {increaseAllowance} or
+     * {decreaseAllowance} to change a non-zero allowance without a two-step reset.
+     *
      * Requirements:
      *
      * - `spender` cannot be the zero address.
      */
-    function approve(address spender, itUint64 calldata value) public virtual returns (bool) {
+    /// @notice Approve with encrypted (itUint256) amount
+    function approve(
+        address spender,
+        itUint256 calldata value
+    ) public virtual override nonReentrant  {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
         address owner = _msgSender();
 
-        gtUint64 gtValue = MpcCore.validateCiphertext(value);
+        gtUint256 gtValue = MpcCore.validateCiphertext(value);
+
+        _requireSafeEncryptedApprove(owner, spender, gtValue);
 
         _approve(owner, spender, gtValue);
 
-        return true;
     }
 
-    /**
-     * @dev See {IPrivateERC20-approve}.
-     *
-     * NOTE: If `value` is the maximum `gtUint64`, the allowance is not updated on
-     * `transferFrom`. This is semantically equivalent to an infinite approval.
-     *
-     * Requirements:
-     *
-     * - `spender` cannot be the zero address.
-     */
-    function approve(address spender, gtUint64 value) public virtual returns (bool) {
+    /// @notice Approve with garbled-text (gtUint256) amount
+    function approveGT(
+        address spender,
+        gtUint256 value
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
         address owner = _msgSender();
 
+        _requireSafeEncryptedApprove(owner, spender, value);
+
         _approve(owner, spender, value);
 
-        return true;
+    }
+
+    /// @notice Approve with plain public uint256 amount
+    function approve(
+        address spender,
+        uint256 value
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        address owner = _msgSender();
+
+        if (value != 0) {
+            gtUint256 currentAllowance = _safeOnboard(
+                _allowances[owner][spender].ciphertext
+            );
+            if (!MpcCore.decrypt(MpcCore.eq(currentAllowance, uint256(0)))) {
+                revert ERC20UnsafeApprove();
+            }
+        }
+
+        gtUint256 gtValue = MpcCore.setPublic256(value);
+
+        _approve(owner, spender, gtValue);
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function increaseAllowance(
+        address spender,
+        itUint256 calldata addedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        gtUint256 gtAdded = MpcCore.validateCiphertext(addedValue);
+        _increaseAllowance(_msgSender(), spender, gtAdded);
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function increaseAllowance(
+        address spender,
+        uint256 addedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        _increaseAllowance(_msgSender(), spender, MpcCore.setPublic256(addedValue));
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function increaseAllowanceGT(
+        address spender,
+        gtUint256 addedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        _increaseAllowance(_msgSender(), spender, addedValue);
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function decreaseAllowance(
+        address spender,
+        itUint256 calldata subtractedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        gtUint256 gtSub = MpcCore.validateCiphertext(subtractedValue);
+        _decreaseAllowance(_msgSender(), spender, gtSub);
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function decreaseAllowance(
+        address spender,
+        uint256 subtractedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        _decreaseAllowance(_msgSender(), spender, MpcCore.setPublic256(subtractedValue));
+    }
+
+    /// @inheritdoc IPrivateERC20
+    function decreaseAllowanceGT(
+        address spender,
+        gtUint256 subtractedValue
+    ) public virtual override nonReentrant {
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+        _decreaseAllowance(_msgSender(), spender, subtractedValue);
     }
 
     /**
@@ -245,46 +679,106 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      * - `from` must have a balance of at least `value`.
      * - the caller must have allowance for ``from``'s tokens of at least
      * `value`.
+     *
+     * Order: (1) check allowance and revert if insufficient, (2) deduct via {_spendAllowance}
+     * (reusing the onboarded allowance from step 1), (3) _transfer.
      */
-    function transferFrom(address from, address to, itUint64 calldata value) public virtual returns (gtBool) {
+    /// @notice transferFrom with encrypted (itUint256) amount
+    function transferFrom(
+        address from,
+        address to,
+        itUint256 calldata value
+    ) public virtual override nonReentrant {
+        if (from == address(0)) revert ERC20InvalidSender(address(0));
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
         address spender = _msgSender();
 
-        gtUint64 gtValue = MpcCore.validateCiphertext(value);
+        gtUint256 gtValue = MpcCore.validateCiphertext(value);
+
+        gtUint256 currentAllowance = _safeOnboard(_allowances[from][spender].ciphertext);
+        gtBool maxAllowance = _isMaxAllowance(currentAllowance);
+        gtBool inSufficientAllowance = MpcCore.lt(currentAllowance, gtValue);
+        require(
+            MpcCore.decrypt(MpcCore.or(maxAllowance, MpcCore.not(inSufficientAllowance))),
+            "ERC20: insufficient allowance"
+        );
+        bool unlimitedAllowance = MpcCore.decrypt(maxAllowance);
 
-        _spendAllowance(from, spender, gtValue);
+        _spendAllowance(from, spender, gtValue, currentAllowance, unlimitedAllowance);
 
-        return _transfer(from, to, gtValue);
+        _transfer(from, to, gtValue);
     }
-    
-    /**
-     * @dev See {IPrivateERC20-transferFrom}.
-     *
-     * Requirements:
-     *
-     * - `from` and `to` cannot be the zero address.
-     * - `from` must have a balance of at least `value`.
-     * - the caller must have allowance for ``from``'s tokens of at least
-     * `value`.
-     */
-    function transferFrom(address from, address to, gtUint64 value) public virtual returns (gtBool) {
+
+    /// @notice transferFrom with garbled-text (gtUint256) amount
+    function transferFromGT(
+        address from,
+        address to,
+        gtUint256 value
+    ) public virtual override nonReentrant {
+        if (from == address(0)) revert ERC20InvalidSender(address(0));
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
         address spender = _msgSender();
 
-        _spendAllowance(from, spender, value);
+        gtUint256 currentAllowance = _safeOnboard(_allowances[from][spender].ciphertext);
+        gtBool maxAllowance = _isMaxAllowance(currentAllowance);
+        gtBool inSufficientAllowance = MpcCore.lt(currentAllowance, value);
+        require(
+            MpcCore.decrypt(MpcCore.or(maxAllowance, MpcCore.not(inSufficientAllowance))),
+            "ERC20: insufficient allowance"
+        );
+        bool unlimitedAllowance = MpcCore.decrypt(maxAllowance);
+
+        _spendAllowance(from, spender, value, currentAllowance, unlimitedAllowance);
 
-        return _transfer(from, to, value);
+        _transfer(from, to, value);
     }
-    
+
+
+    /// @notice transferFrom with plain public uint256 amount
+    function transferFrom(
+        address from,
+        address to,
+        uint256 value
+    ) public virtual override nonReentrant {
+        if (!publicAmountsEnabled) revert PublicAmountsDisabled();
+        if (from == address(0)) revert ERC20InvalidSender(address(0));
+        if (to == address(0)) revert ERC20InvalidReceiver(address(0));
+        address spender = _msgSender();
+
+        gtUint256 gtValue = MpcCore.setPublic256(value);
+
+        gtUint256 currentAllowance = _safeOnboard(_allowances[from][spender].ciphertext);
+        gtBool maxAllowance = _isMaxAllowance(currentAllowance);
+        gtBool inSufficientAllowance = MpcCore.lt(currentAllowance, gtValue);
+        require(
+            MpcCore.decrypt(MpcCore.or(maxAllowance, MpcCore.not(inSufficientAllowance))),
+            "ERC20: insufficient allowance"
+        );
+        bool unlimitedAllowance = MpcCore.decrypt(maxAllowance);
+
+        _spendAllowance(from, spender, gtValue, currentAllowance, unlimitedAllowance);
+
+        _transfer(from, to, gtValue);
+    }
+
     /**
      * @dev Moves a `value` amount of tokens from `from` to `to`.
      *
      * This internal function is equivalent to {transfer}, and can be used to
      * e.g. implement automatic token fees, slashing mechanisms, etc.
      *
-     * Emits a {Transfer} event.
+     * Self-transfer (from == to) is not allowed and reverts.
+     *
+     * On success, emits a {Transfer} event via {_update}; on MPC transfer failure, {_update} reverts
+     * and no event is emitted.
      *
      * NOTE: This function is not virtual, {_update} should be overridden instead.
      */
-    function _transfer(address from, address to, gtUint64 value) internal returns (gtBool) {
+    function _transfer(
+        address from,
+        address to,
+        gtUint256 value
+    ) internal {
         if (from == address(0)) {
             revert ERC20InvalidSender(address(0));
         }
@@ -293,86 +787,172 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
             revert ERC20InvalidReceiver(address(0));
         }
 
-        return _update(from, to, value);
+        if (from == to) {
+            revert ERC20SelfTransferNotAllowed(from);
+        }
+
+        _update(from, to, value);
     }
-    
+
     /**
      * @dev Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
      * (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
      * this function.
      *
-     * Emits a {Transfer} event.
+     * Storage and {Transfer} are updated only when the MPC operation succeeds (transfer success bit, or mint
+     * add without overflow and within {supplyCap}). On failure, balances and aggregate supply are unchanged,
+     * no event is emitted, and this function reverts so the failed operation does not succeed silently.
      */
-    function _update(address from, address to, gtUint64 value) internal virtual returns (gtBool) {
-        gtUint64 newToBalance;
-        gtUint64 valueTransferred = value;
-        gtBool result = MpcCore.setPublic(true);
+    function _update(
+        address from,
+        address to,
+        gtUint256 value
+    ) internal virtual {
+        gtUint256 newToBalance;
+        gtUint256 valueTransferred = value;
+        gtBool result;
+        bool ok;
 
         if (from == address(0)) {
-            gtUint64 totalSupply_ = _safeOnboard(_totalSupply);
-
-            totalSupply_ = MpcCore.add(totalSupply_, value);
+            gtUint256 currentBalance = _getBalance(to);
+            gtBool balanceOverflow;
+            (balanceOverflow, newToBalance) = MpcCore.checkedAddWithOverflowBit(
+                currentBalance,
+                value
+            );
+            gtBool balanceOk = MpcCore.not(balanceOverflow);
 
-            _totalSupply = MpcCore.offBoard(totalSupply_);
+            gtUint256 totalSupply_ = _safeOnboard(_totalSupply);
+            (gtBool supplyOverflow, gtUint256 newTotalSupply) = MpcCore.checkedAddWithOverflowBit(
+                totalSupply_,
+                value
+            );
+            gtBool supplyOk = MpcCore.not(supplyOverflow);
+            gtBool withinCap = MpcCore.le(newTotalSupply, supplyCap());
 
-            gtUint64 currentBalance = _getBalance(to);
+            result = MpcCore.and(balanceOk, MpcCore.and(supplyOk, withinCap));
+            ok = MpcCore.decrypt(result);
+            if (ok) {
+                _totalSupply = MpcCore.offBoard(newTotalSupply);
 
-            newToBalance = MpcCore.add(currentBalance, value);
+                _updateBalance(to, newToBalance);
+            }
         } else {
-            gtUint64 fromBalance = _getBalance(from);
-            gtUint64 toBalance = _getBalance(to);
-
-            gtUint64 newFromBalance;
+            gtUint256 fromBalance = _getBalance(from);
+            // Burn (`to == address(0)`): use canonical public zero as the sink balance. Do not read
+            // `_balances[address(0)]` — that slot must never affect burn accounting if it were ever corrupted.
+            gtUint256 toBalance = to == address(0)
+                ? MpcCore.setPublic256(0)
+                : _getBalance(to);
+
+            gtUint256 newFromBalance;
+
+            (newFromBalance, newToBalance, result) = MpcCore.transfer(
+                fromBalance,
+                toBalance,
+                value
+            );
 
-            (newFromBalance, newToBalance, result) = MpcCore.transfer(fromBalance, toBalance, value);
+            ok = MpcCore.decrypt(result);
+            if (ok) {
+                _updateBalance(from, newFromBalance);
 
-            _updateBalance(from, newFromBalance);
+                valueTransferred = MpcCore.sub(newToBalance, toBalance);
 
-            valueTransferred = MpcCore.sub(newToBalance, toBalance);
-        }
+                if (to == address(0)) {
+                    gtUint256 totalSupply_ = _safeOnboard(_totalSupply);
 
-        if (to == address(0)) {
-            gtUint64 totalSupply_ = _safeOnboard(_totalSupply);
+                    totalSupply_ = MpcCore.sub(totalSupply_, valueTransferred);
 
-            totalSupply_ = MpcCore.sub(totalSupply_, valueTransferred);
+                    _totalSupply = MpcCore.offBoard(totalSupply_);
+                } else {
+                    _updateBalance(to, newToBalance);
+                }
+            }
+        }
 
-            _totalSupply = MpcCore.offBoard(totalSupply_);
-        } else {
-            _updateBalance(to, newToBalance);
+        if (ok) {
+            // When minting or transferring to/from a smart contract (which has no AES key),
+            // we must bypass offBoardToUser to prevent on-chain reverts.
+            ctUint256 memory senderCt;
+            address fromEnc = _getAccountEncryptionAddress(from);
+            if (fromEnc != address(0)) {
+                senderCt = MpcCore.offBoardToUser(valueTransferred, fromEnc);
+            } else {
+                senderCt = ctUint256({
+                    ciphertextHigh: ctUint128.wrap(0),
+                    ciphertextLow: ctUint128.wrap(0)
+                });
+            }
+
+            ctUint256 memory receiverCt;
+            address toEnc = _getAccountEncryptionAddress(to);
+            if (toEnc != address(0)) {
+                receiverCt = MpcCore.offBoardToUser(valueTransferred, toEnc);
+            } else {
+                receiverCt = ctUint256({
+                    ciphertextHigh: ctUint128.wrap(0),
+                    ciphertextLow: ctUint128.wrap(0)
+                });
+            }
+
+            emit Transfer(from, to, senderCt, receiverCt);
         }
-        
-        emit Transfer(
-            from,
-            to,
-            MpcCore.offBoardToUser(valueTransferred, from),
-            MpcCore.offBoardToUser(valueTransferred, to)
-        );
+        require(MpcCore.decrypt(result), "ERC20: update failed");
+    }
 
-        return result;
+    /**
+     * @dev Aggregate supply as a garbled value (on-boarded from storage ciphertext).
+     *      Intended for subclasses that expose encrypted total supply to a designated party
+     *      (e.g. via `MpcCore.offBoardToUser`) without putting plaintext aggregate supply in {totalSupply}.
+     */
+    function _getTotalSupplyGarbled() internal returns (gtUint256) {
+        return _safeOnboard(_totalSupply);
     }
 
-    function _getBalance(address account) internal returns (gtUint64) {
-        ctUint64 ctBalance = _balances[account].ciphertext;
+    function _getBalance(address account) internal returns (gtUint256) {
+        ctUint256 memory ctBalance = _balances[account].ciphertext;
 
         return _safeOnboard(ctBalance);
     }
 
-    function _getAccountEncryptionAddress(address account) internal view returns (address) {
+    function _getAccountEncryptionAddress(
+        address account
+    ) internal view returns (address) {
+        if (account == address(0)) return address(0);
+
         address encryptionAddress = _accountEncryptionAddress[account];
 
         if (encryptionAddress == address(0)) {
+            if (account.code.length > 0) {
+                // Smart contracts don't have AES keys, so we return address(0)
+                // as a signal to bypass encryption in offBoardToUser.
+                return address(0);
+            }
             encryptionAddress = account;
         }
 
         return encryptionAddress;
     }
 
-    function _updateBalance(address account, gtUint64 balance) internal {
+    function _updateBalance(address account, gtUint256 balance) internal {
         address encryptionAddress = _getAccountEncryptionAddress(account);
 
-        _balances[account] = MpcCore.offBoardCombined(balance, encryptionAddress);
+        if (encryptionAddress == address(0)) {
+            // Contract accounts have no AES key; store ciphertext only, no user reencryption.
+            _balances[account].ciphertext = MpcCore.offBoard(balance);
+            _balances[account].userCiphertext = ctUint256({
+                ciphertextHigh: ctUint128.wrap(0),
+                ciphertextLow: ctUint128.wrap(0)
+            });
+        } else {
+            _balances[account] = MpcCore.offBoardCombined(
+                balance,
+                encryptionAddress
+            );
+        }
     }
-    
+
     /**
      * @dev Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0).
      * Relies on the `_update` mechanism
@@ -381,12 +961,12 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      *
      * NOTE: This function is not virtual, {_update} should be overridden instead.
      */
-    function _mint(address account, gtUint64 value) internal returns (gtBool) {
+    function _mint(address account, gtUint256 value) internal {
         if (account == address(0)) {
             revert ERC20InvalidReceiver(address(0));
         }
 
-        return _update(address(0), account, value);
+        _update(address(0), account, value);
     }
 
     /**
@@ -397,12 +977,12 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      *
      * NOTE: This function is not virtual, {_update} should be overridden instead
      */
-    function _burn(address account, gtUint64 value) internal returns (gtBool) {
+    function _burn(address account, gtUint256 value) internal {
         if (account == address(0)) {
             revert ERC20InvalidSender(address(0));
         }
 
-        return _update(account, address(0), value);
+        _update(account, address(0), value);
     }
 
     /**
@@ -420,7 +1000,86 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
      *
      * Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument.
      */
-    function _approve(address owner, address spender, gtUint64 value) internal {
+
+    /**
+     * @dev If the new allowance is non-zero, requires the current allowance to be zero.
+     *      Same mitigation as {approve(address,uint256)} / {ERC20UnsafeApprove} for the encrypted and GT approve paths.
+     */
+    function _requireSafeEncryptedApprove(
+        address owner,
+        address spender,
+        gtUint256 gtNewValue
+    ) internal {
+        gtBool newIsZero = MpcCore.eq(gtNewValue, MpcCore.setPublic256(0));
+        if (MpcCore.decrypt(newIsZero)) {
+            return;
+        }
+
+        gtUint256 currentAllowance = _safeOnboard(
+            _allowances[owner][spender].ciphertext
+        );
+        if (!MpcCore.decrypt(MpcCore.eq(currentAllowance, uint256(0)))) {
+            revert ERC20UnsafeApprove();
+        }
+    }
+
+    /**
+     * @dev Atomically adds `added` to the current allowance. Reverts on overflow (mirrors
+     *      ERC-20 reference behavior for `type(uint256).max + x`). Does not use
+     *      {_requireSafeEncryptedApprove} — intended as the safe alternative to resetting via {approve}.
+     */
+    function _increaseAllowance(
+        address owner,
+        address spender,
+        gtUint256 added
+    ) internal {
+        if (owner == address(0)) revert ERC20InvalidApprover(address(0));
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+
+        gtUint256 currentAllowance = _safeOnboard(
+            _allowances[owner][spender].ciphertext
+        );
+        (gtBool overflow, gtUint256 newAllowance) = MpcCore.checkedAddWithOverflowBit(
+            currentAllowance,
+            added
+        );
+        require(
+            MpcCore.decrypt(MpcCore.not(overflow)),
+            "ERC20: allowance overflow"
+        );
+        _approve(owner, spender, newAllowance);
+    }
+
+    /**
+     * @dev Atomically subtracts `subtracted` from the current allowance. Reverts on underflow.
+     */
+    function _decreaseAllowance(
+        address owner,
+        address spender,
+        gtUint256 subtracted
+    ) internal {
+        if (owner == address(0)) revert ERC20InvalidApprover(address(0));
+        if (spender == address(0)) revert ERC20InvalidSpender(address(0));
+
+        gtUint256 currentAllowance = _safeOnboard(
+            _allowances[owner][spender].ciphertext
+        );
+        (gtBool underflow, gtUint256 newAllowance) = MpcCore.checkedSubWithOverflowBit(
+            currentAllowance,
+            subtracted
+        );
+        require(
+            MpcCore.decrypt(MpcCore.not(underflow)),
+            "ERC20: insufficient allowance"
+        );
+        _approve(owner, spender, newAllowance);
+    }
+
+    function _approve(
+        address owner,
+        address spender,
+        gtUint256 value
+    ) internal {
         if (owner == address(0)) {
             revert ERC20InvalidApprover(address(0));
         }
@@ -429,50 +1088,100 @@ abstract contract PrivateERC20 is Context, IPrivateERC20 {
             revert ERC20InvalidSpender(address(0));
         }
 
-        ctUint64 ciphertext = MpcCore.offBoard(value);
+        ctUint256 memory ciphertext = MpcCore.offBoard(value);
 
         address encryptionAddress = _getAccountEncryptionAddress(owner);
 
-        ctUint64 ownerCiphertext = MpcCore.offBoardToUser(value, encryptionAddress);
+        ctUint256 memory ownerCiphertext;
+        if (encryptionAddress != address(0)) {
+            ownerCiphertext = MpcCore.offBoardToUser(value, encryptionAddress);
+        } else {
+            ownerCiphertext = ctUint256({
+                ciphertextHigh: ctUint128.wrap(0),
+                ciphertextLow: ctUint128.wrap(0)
+            });
+        }
 
         encryptionAddress = _getAccountEncryptionAddress(spender);
 
-        ctUint64 spenderCiphertext = MpcCore.offBoardToUser(value, encryptionAddress);
+        ctUint256 memory spenderCiphertext;
+        if (encryptionAddress != address(0)) {
+            spenderCiphertext = MpcCore.offBoardToUser(
+                value,
+                encryptionAddress
+            );
+        } else {
+            spenderCiphertext = ctUint256({
+                ciphertextHigh: ctUint128.wrap(0),
+                ciphertextLow: ctUint128.wrap(0)
+            });
+        }
 
-        _allowances[owner][spender] = Allowance(ciphertext, ownerCiphertext, spenderCiphertext);
+        _allowances[owner][spender] = Allowance(
+            ciphertext,
+            ownerCiphertext,
+            spenderCiphertext
+        );
 
         emit Approval(owner, spender, ownerCiphertext, spenderCiphertext);
     }
 
     /**
-     * @dev Updates `owner` s allowance for `spender` based on spent `value`.
-     *
-     * Does not decrease the allowance value in case of infinite allowance.
-     * Does not decrease the allowance if not enough allowance is available.
-     *
+     * @dev Unlimited allowance: semantic equality to `type(uint256).max` via secret-vs-public
+     *      `eq` (MPC RHS_PUBLIC). Using this instead of `eq(allowance, setPublic256(max))` ensures
+     *      any valid garbled encoding of max is recognized, not only one canonical pair.
      */
-    function _spendAllowance(address owner, address spender, gtUint64 value) internal virtual {
-        gtUint64 currentBalance = _safeOnboard(_balances[owner].ciphertext);
-        gtUint64 currentAllowance = _safeOnboard(_allowances[owner][spender].ciphertext);
-
-        gtBool maxAllowance = MpcCore.eq(currentAllowance, MpcCore.setPublic64(MAX_UINT_64));
-        gtBool insufficientBalance = MpcCore.lt(currentBalance, value);
-        gtBool inSufficientAllowance = MpcCore.lt(currentAllowance, value);
-
-        gtUint64 newAllowance = MpcCore.mux(
-            MpcCore.or(maxAllowance, MpcCore.or(insufficientBalance, inSufficientAllowance)),
-            MpcCore.sub(currentAllowance, value),
-            currentAllowance
-        );
+    function _isMaxAllowance(gtUint256 gtAllowance) internal returns (gtBool) {
+        return MpcCore.eq(gtAllowance, MAX_UINT_256);
+    }
 
+    /**
+     * @dev Deducts `value` from `owner`/`spender` allowance after {transferFrom} prechecks.
+     * @param currentAllowance Garbled allowance from the same `_safeOnboard` pass as the insufficient-allowance check (avoids a second onboard + duplicate `eq`/`lt`).
+     * @param unlimitedAllowance Result of `MpcCore.decrypt(_isMaxAllowance(currentAllowance))` for the same slot.
+     *
+     * If unlimited, returns without writing storage or emitting {Approval} (OZ-style). Otherwise
+     * subtracts `value`, which is safe because {transferFrom} already enforced sufficiency when not unlimited.
+     */
+    function _spendAllowance(
+        address owner,
+        address spender,
+        gtUint256 value,
+        gtUint256 currentAllowance,
+        bool unlimitedAllowance
+    ) internal virtual {
+        if (unlimitedAllowance) {
+            return;
+        }
+        gtUint256 newAllowance = MpcCore.sub(currentAllowance, value);
         _approve(owner, spender, newAllowance);
     }
 
-    function _safeOnboard(ctUint64 value) internal returns (gtUint64) {
-        if (ctUint64.unwrap(value) == 0) {
-            return MpcCore.setPublic64(0);
-        }
+    /// @dev EVM-uninitialized or fully cleared `ctUint256` storage reads as both limbs zero.
+    function _isCanonicalEmptyCtUint256(
+        ctUint256 memory ct
+    ) private pure returns (bool) {
+        return
+            ctUint128.unwrap(ct.ciphertextHigh) == 0 &&
+            ctUint128.unwrap(ct.ciphertextLow) == 0;
+    }
 
+    /**
+     * @dev Converts persisted `ctUint256` into garbled `gtUint256` for MPC operations.
+     *
+     * **Canonical zero:** Storage that has never been written, or reads as all-zero limbs, is
+     * treated as semantic zero via `MpcCore.setPublic256(0)` without `MpcCore.onBoard`, to avoid a
+     * precompile round-trip on empty balances/allowances/supply. Any non–all-zero encoding is
+     * onboarded with `MpcCore.onBoard`.
+     *
+     * Invariant: values persisted by this contract come from `MpcCore.offBoard` after successful MPC
+     * updates, so normal state is consistent with the precompile. Subclasses or integrations must not
+     * inject arbitrary ciphertext into these slots unless it matches MPC encoding expectations.
+     */
+    function _safeOnboard(ctUint256 memory value) internal returns (gtUint256) {
+        if (_isCanonicalEmptyCtUint256(value)) {
+            return MpcCore.setPublic256(0);
+        }
         return MpcCore.onBoard(value);
     }
-}
+}