@coti-io/coti-contracts 1.1.0 → 1.3.0

package/contracts/privacyBridge/PrivacyBridgeCotiNative.sol

@@ -0,0 +1,316 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "./PrivacyBridge.sol";
+import "@openzeppelin/contracts/utils/math/Math.sol";
+import "../token/PrivateERC20/tokens/PrivateCOTI.sol";
+
+/**
+ * @title PrivacyBridgeCotiNative
+ * @notice Bridge contract for converting between native COTI and privacy-preserving COTI.p tokens
+ * @dev Withdraw pulls private balance via `IPrivateERC20(address(privateCoti)).transferFrom` so the call matches
+ *      the canonical {IPrivateERC20} surface (`contracts/token/PrivateERC20/IPrivateERC20.sol`) while `privateCoti`
+ *      remains the concrete {PrivateCOTI} type for mint/burn. Deploy `_privateCoti` as that implementation (or a
+ *      fully ABI-compatible successor); do not point at arbitrary ERC-20s.
+ *
+ *      **Two native deposit paths (document for wallets / indexers):**
+ *      - {deposit(uint256,uint256)}: user passes `cotiOracleTimestamp` and `tokenOracleTimestamp` (same value
+ *        twice for `"COTI"`); {_validateOracleTimestamps} enforces they match the on-chain Band row—same quote row
+ *        as {estimateDepositFee}. Use this when you need binding between off-chain estimate and execution.
+ *      - {receive} / plain ETH send: uses {_directDeposit}; fee still uses {_computeCotiFee} with staleness
+ *        ({_requireOracleFreshness}) but **does not** require equality to estimate timestamps—no prior estimate row
+ *        is pinned. Prefer explicit {deposit} for predictable “what I quoted is what executes.”
+ *
+ *      **Unsolicited native:** balance can increase via `selfdestruct` or other forced transfers without invoking
+ *      {receive}; that ETH does not mint private tokens and does not update {PrivacyBridge.totalUserLiability}.
+ */
+contract PrivacyBridgeCotiNative is PrivacyBridge {
+    PrivateCOTI public privateCoti;
+
+    event NativeRescued(address indexed to, uint256 amount);
+
+    // Scaling factor removed (using native 18 decimals due to uint256 upgrade)
+
+    /**
+     * @notice Initialize the Native Bridge
+     * @param _privateCoti Address of the PrivateCoti token contract
+     * @param _priceOracle Non-zero price oracle (see {PrivacyBridge}'s constructor)
+     */
+    constructor(address _privateCoti, address _feeRecipient, address _rescueRecipient, address _priceOracle) PrivacyBridge(_feeRecipient, _rescueRecipient, _priceOracle) {
+        if (_privateCoti == address(0)) revert InvalidAddress();
+        privateCoti = PrivateCOTI(_privateCoti);
+    }
+
+    /**
+     * @dev Native COTI fee math + one {getPriceWithMeta("COTI")} read. Used by {_computeCotiFee} and
+     *      {estimateDepositFee}/{estimateWithdrawFee}. Each {Math.mulDiv} truncates toward zero (see
+     *      {PrivacyBridge.FEE_DIVISOR} NatSpec). Extreme `cotiAmount`×`cotiUsdRate` values can make {Math.mulDiv}
+     *      revert—keep amounts within configured max deposit/withdraw limits.
+     * @param cotiAmount Amount in COTI wei the fee is computed for
+     * @param fixedFee Minimum fee floor in COTI wei
+     * @param percentageBps Percentage parameter scaled by {PrivacyBridge.FEE_DIVISOR}
+     * @param maxFee Maximum fee cap in COTI wei
+     * @return fee Computed fee in COTI wei
+     * @return cotiLastUpdated COTI oracle row `lastUpdated`
+     * @return blockTimestamp Third field from the COTI oracle row
+     */
+    function _computeCotiFeeAndMeta(
+        uint256 cotiAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee
+    ) internal view returns (uint256 fee, uint256 cotiLastUpdated, uint256 blockTimestamp) {
+        _requirePriceOracle();
+        (uint256 cotiUsdRate, uint256 cotiLU, uint256 cotiBts) = ICotiPriceConsumer(priceOracle).getPriceWithMeta("COTI");
+        _requirePositiveOracleRate(cotiUsdRate);
+        _requireOracleFreshness(cotiLU);
+        uint256 txValueUsd = Math.mulDiv(cotiAmount, cotiUsdRate, 1e18);
+        uint256 percentageFeeUsd = Math.mulDiv(txValueUsd, percentageBps, FEE_DIVISOR);
+        uint256 percentageFeeCoti = Math.mulDiv(percentageFeeUsd, 1e18, cotiUsdRate);
+        fee = _calculateDynamicFee(percentageFeeCoti, fixedFee, maxFee);
+        cotiLastUpdated = cotiLU;
+        blockTimestamp = cotiBts;
+    }
+
+    function _computeCotiFee(
+        uint256 cotiAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee
+    ) internal view returns (uint256) {
+        (uint256 f,,) = _computeCotiFeeAndMeta(cotiAmount, fixedFee, percentageBps, maxFee);
+        return f;
+    }
+
+    /**
+     * @notice Simulate fee calculation for native COTI with arbitrary parameters.
+     * @dev Public view — allows frontends/operators to preview fees with custom fee params.
+     *      Reads live COTI oracle price but accepts custom fee configuration.
+     * @param cotiAmount The COTI amount to compute fee for (wei; very large values can revert in fee math)
+     * @param fixedFee The minimum fee floor in COTI wei
+     * @param percentageBps The percentage in basis points (relative to {FEE_DIVISOR})
+     * @param maxFee The maximum fee cap in COTI wei
+     * @return The computed fee in COTI wei
+     */
+    function computeCotiFee(
+        uint256 cotiAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee
+    ) external view returns (uint256) {
+        return _computeCotiFee(cotiAmount, fixedFee, percentageBps, maxFee);
+    }
+
+    /**
+     * @notice Estimate the deposit fee in COTI for a given COTI amount
+     * @param cotiAmount The amount of native COTI to deposit (wei; very large values can revert in fee math)
+     * @return fee                The estimated fee in COTI wei
+     * @return cotiLastUpdated    COTI oracle data last update timestamp
+     * @return blockTimestamp     Third field from the COTI oracle row (same as pre-refactor behavior)
+     * @dev Use `cotiLastUpdated` for **both** `cotiOracleTimestamp` and `tokenOracleTimestamp` on {deposit}/{withdraw}
+     *      (native bridge validates `"COTI"` twice). See {PrivacyBridge._validateOracleTimestamps}.
+     */
+    function estimateDepositFee(uint256 cotiAmount) external view returns (uint256 fee, uint256 cotiLastUpdated, uint256 blockTimestamp) {
+        (fee, cotiLastUpdated, blockTimestamp) = _computeCotiFeeAndMeta(
+            cotiAmount,
+            depositFixedFee,
+            depositPercentageBps,
+            depositMaxFee
+        );
+    }
+
+    /**
+     * @notice Estimate the withdrawal fee in COTI for a given COTI amount
+     * @param cotiAmount The amount of native COTI to withdraw (wei; very large values can revert in fee math)
+     * @return fee                The estimated fee in COTI wei
+     * @return cotiLastUpdated    COTI oracle data last update timestamp
+     * @return blockTimestamp     Third field from the COTI oracle row (same as pre-refactor behavior)
+     * @dev Same timestamp usage as {estimateDepositFee} for the subsequent {withdraw}.
+     */
+    function estimateWithdrawFee(uint256 cotiAmount) external view returns (uint256 fee, uint256 cotiLastUpdated, uint256 blockTimestamp) {
+        (fee, cotiLastUpdated, blockTimestamp) = _computeCotiFeeAndMeta(
+            cotiAmount,
+            withdrawFixedFee,
+            withdrawPercentageBps,
+            withdrawMaxFee
+        );
+    }
+
+    /**
+     * @notice Internal function to handle deposits
+     * @param sender Address of the depositor
+     */
+    function _deposit(address sender, uint256 cotiOracleTimestamp, uint256 tokenOracleTimestamp) internal {
+        if (!isDepositEnabled) revert DepositDisabled();
+        if (msg.value == 0) revert AmountZero();
+
+        _checkDepositLimits(msg.value);
+        _validateOracleTimestamps(cotiOracleTimestamp, tokenOracleTimestamp, "COTI");
+
+        // Compute dynamic fee in COTI
+        uint256 fee = _computeCotiFee(msg.value, depositFixedFee, depositPercentageBps, depositMaxFee);
+        uint256 netAmount = msg.value - fee;
+        if (netAmount == 0) revert AmountZero();
+
+        accumulatedCotiFees += fee;
+
+        totalUserLiability += netAmount;
+        privateCoti.mint(sender, netAmount);
+
+        // Emit gross deposit amount and net private tokens minted
+        emit Deposit(sender, msg.value, netAmount);
+    }
+
+    /**
+     * @notice Deposit native COTI to receive private COTI (COTI.p)
+     * @param cotiOracleTimestamp COTI `lastUpdated` from the latest `estimateDepositFee` (must still equal on-chain at execution).
+     * @param tokenOracleTimestamp Same value as `cotiOracleTimestamp` for this bridge (both checks use `"COTI"`).
+     * @dev User sends native COTI with the transaction. Oracle races: {OracleTimestampMismatch} — re-estimate; see {_validateOracleTimestamps}.
+     */
+    function deposit(uint256 cotiOracleTimestamp, uint256 tokenOracleTimestamp) external payable nonReentrant whenNotPaused notBlacklisted {
+        _deposit(msg.sender, cotiOracleTimestamp, tokenOracleTimestamp);
+    }
+
+    /**
+     * @notice Withdraw native COTI by burning private COTI
+     * @param amount Amount of private COTI to burn
+     * @param cotiOracleTimestamp COTI `lastUpdated` from the latest `estimateWithdrawFee` (must still equal on-chain at execution).
+     * @param tokenOracleTimestamp Same value as `cotiOracleTimestamp` for this bridge.
+     * @dev User must have approved the bridge to spend their private tokens. Oracle rules: {_validateOracleTimestamps}.
+     */
+    function withdraw(uint256 amount, uint256 cotiOracleTimestamp, uint256 tokenOracleTimestamp) external nonReentrant whenNotPaused notBlacklisted {
+        _withdraw(msg.sender, amount, cotiOracleTimestamp, tokenOracleTimestamp);
+    }
+
+    function _withdraw(
+        address to,
+        uint256 amount,
+        uint256 cotiOracleTimestamp,
+        uint256 tokenOracleTimestamp
+    ) internal {
+        if (amount == 0) revert AmountZero();
+        _checkWithdrawLimits(amount);
+        _validateOracleTimestamps(cotiOracleTimestamp, tokenOracleTimestamp, "COTI");
+
+        // Compute dynamic withdrawal fee in COTI
+        uint256 fee = _computeCotiFee(amount, withdrawFixedFee, withdrawPercentageBps, withdrawMaxFee);
+        uint256 publicAmount = amount - fee;
+        if (publicAmount == 0) revert AmountZero();
+
+        accumulatedCotiFees += fee;
+
+        if (address(this).balance < publicAmount)
+            revert InsufficientEthBalance();
+
+        // Extinguish liability for the full private amount burned (fee stays with bridge as native revenue).
+        totalUserLiability -= amount;
+
+        // Pull and burn private tokens
+        IPrivateERC20(address(privateCoti)).transferFrom(
+            msg.sender,
+            address(this),
+            amount
+        );
+        privateCoti.burn(amount);
+
+        (bool success, ) = to.call{value: publicAmount}("");
+        if (!success) revert EthTransferFailed();
+
+        emit Withdraw(to, amount, publicAmount);
+    }
+
+    /**
+     * @notice Internal deposit without binding to a prior estimate’s oracle `lastUpdated` snapshot.
+     * @dev Used by {receive}. Fee uses {_computeCotiFee}, which still enforces: oracle configured
+     *      ({PriceOracleNotSet}), non-zero COTI/USD rate ({InvalidOraclePrice}), and max age of
+     *      `lastUpdated` when {PrivacyBridge.maxOracleAge} is set ({OraclePriceStale} /
+     *      {OracleLastUpdatedInFuture}). What plain sends do **not** do is equality to timestamps
+     *      passed into {deposit} from an off-chain estimate—users who need that binding should call {deposit}.
+     */
+    function _directDeposit(address sender) internal {
+        if (!isDepositEnabled) revert DepositDisabled();
+        if (msg.value == 0) revert AmountZero();
+
+        _checkDepositLimits(msg.value);
+
+        uint256 fee = _computeCotiFee(msg.value, depositFixedFee, depositPercentageBps, depositMaxFee);
+        uint256 netAmount = msg.value - fee;
+        if (netAmount == 0) revert AmountZero();
+
+        accumulatedCotiFees += fee;
+
+        totalUserLiability += netAmount;
+        privateCoti.mint(sender, netAmount);
+
+        emit Deposit(sender, msg.value, netAmount);
+    }
+
+    /**
+     * @notice Fallback for plain native transfers: same fee path as {_directDeposit}.
+     * @dev See {_directDeposit}: zero/stale oracle rates are rejected via {_computeCotiFee}; use {deposit}
+     *      when you must match `lastUpdated` from {estimateDepositFee} to the on-chain row (see {_validateOracleTimestamps}).
+     */
+    receive() external payable nonReentrant whenNotPaused notBlacklisted {
+        _directDeposit(msg.sender);
+    }
+
+    /**
+     * @notice Get the native COTI balance held by the bridge
+     * @return The contract's balance in native units (wei-equivalent)
+     */
+    function getBridgeBalance() external view returns (uint256) {
+        return address(this).balance;
+    }
+
+    /**
+     * @notice Withdraw accumulated fees to feeRecipient (Native implementation)
+     * @param amount Amount of fees to withdraw
+     * @dev Only the owner can call this function
+     */
+    function withdrawFees(
+        uint256 amount
+    ) external onlyOwner nonReentrant {
+        if (feeRecipient == address(0)) revert FeeRecipientNotSet();
+        if (amount == 0) revert AmountZero();
+        if (amount > accumulatedCotiFees) revert InsufficientAccumulatedFees();
+        if (amount > address(this).balance) revert InsufficientEthBalance();
+
+        accumulatedCotiFees -= amount;
+
+        // Transfer native COTI tokens to feeRecipient
+        (bool success, ) = feeRecipient.call{value: amount}("");
+        if (!success) revert EthTransferFailed();
+
+        emit FeesWithdrawn(feeRecipient, amount);
+    }
+
+    /**
+     * @notice Move native COTI from this bridge to {rescueRecipient} while the bridge is paused.
+     * @dev Emergency / migration path: sends up to `amount` (typically the full {address(this).balance}) to
+     *      {rescueRecipient}. That balance can include all user-deposited native liquidity and unswept fee
+     *      float—there is no on-chain carve-out that keeps “user principal” behind. Intended for bug recovery
+     *      or handover to a new bridge; a malicious or compromised owner who has paused can drain TVL to
+     *      {rescueRecipient} in one or more calls. See {PrivacyBridge} contract-level @dev (3) for governance
+     *      mitigations (multisig, timelock, monitoring). After a partial rescue, {accumulatedCotiFees} is capped
+     *      to the remaining balance so fee accounting cannot exceed what is still on the contract. {totalUserLiability}
+     *      is **not** adjusted: rescue only moves native to {rescueRecipient}; it does not burn private tokens or
+     *      reduce user obligations on this contract, so the counter may exceed {address(this).balance} until a
+     *      separate migration makes users whole.
+     * @param amount Amount of native currency to send (often the full balance for migration).
+     */
+    function rescueNative(uint256 amount) external onlyOwner nonReentrant whenPaused {
+        if (amount == 0) revert AmountZero();
+        if (amount > address(this).balance) revert InsufficientEthBalance();
+
+        (bool success, ) = rescueRecipient.call{value: amount}("");
+        if (!success) revert EthTransferFailed();
+
+        uint256 remaining = address(this).balance;
+        if (accumulatedCotiFees > remaining) {
+            accumulatedCotiFees = remaining;
+        }
+
+        emit NativeRescued(rescueRecipient, amount);
+    }
+
+}

package/contracts/privacyBridge/PrivacyBridgeERC20.sol

@@ -0,0 +1,333 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "./PrivacyBridge.sol";
+import "@openzeppelin/contracts/utils/math/Math.sol";
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import "../token/PrivateERC20/IPrivateERC20.sol";
+
+/// @dev Minimal interface to read decimals from tokens without modifying IPrivateERC20
+interface IHasDecimals {
+    function decimals() external view returns (uint8);
+}
+
+/**
+ * @dev Abstract base contract for ERC20 Token Privacy Bridges
+ * @dev Handles the logic for bridging ERC20 tokens to their private counterparts.
+ * @dev The public ERC20 must match standard transfer semantics: {safeTransferFrom} of `amount` must
+ *      increase the bridge balance by exactly `amount` ({UnexpectedTransferBalance} otherwise). This
+ *      rejects common fee-on-transfer / deflationary patterns. Rebasing, blacklist hooks, and other
+ *      non-standard behavior remain unsupported—deployment must still use a suitable asset.
+ * @dev **Private token:** The constructor stores `_privateToken` as {IPrivateERC20} from
+ *      `contracts/token/PrivateERC20/IPrivateERC20.sol` (same `pragma` family as this contract). Integrators should
+ *      bind ABIs/codegen to that canonical interface in this repo; alternate compiler pipelines (e.g. via-IR-only)
+ *      should still target the same ABI, not ad-hoc casts to incompatible shapes.
+ */
+abstract contract PrivacyBridgeERC20 is PrivacyBridge {
+    using SafeERC20 for IERC20;
+
+    /// @notice The public ERC20 token being bridged (e.g., USDC, WETH)
+    IERC20 public token;
+
+    /// @notice Private token contract being minted/burned
+    IPrivateERC20 public privateToken;
+
+    /// @notice Band oracle symbol for the bridged token (e.g., "ETH", "WBTC", "ADA", "USDC", "USDT")
+    string public tokenSymbol;
+
+    /// @notice Cached ERC20 decimals (matches private token; set in constructor).
+    uint8 internal immutable bridgedTokenDecimals;
+
+    error InvalidTokenAddress();
+    error InvalidPrivateTokenAddress();
+    error CannotRescueBridgeToken();
+    error InvalidScalingFactor();
+    error AmountTooLarge();
+    error AmountTooSmall();
+    error InsufficientBridgeLiquidity();
+    error TokenTransferFailed();
+    error InvalidTokenSender();
+    error NativeFeeRequiredForTransferAndCallWithdraw();
+    error DecimalsMismatch();
+    /// @notice Pulled balance increase did not match `amount` (e.g. fee-on-transfer or deflationary token).
+    error UnexpectedTransferBalance(uint256 expected, uint256 received);
+    event ERC20Rescued(address indexed token, address indexed to, uint256 amount);
+
+    function _computeErc20Fee(
+        uint256 tokenAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee
+    ) internal view returns (uint256) {
+        (uint256 fee,,,) = _computeErc20FeeAndMeta(tokenAmount, fixedFee, percentageBps, maxFee, tokenSymbol, bridgedTokenDecimals);
+        return fee;
+    }
+
+    /**
+     * @notice Simulate fee calculation for any token symbol and decimals.
+     * @dev Public view — allows frontends/operators to preview fees with arbitrary parameters.
+     *      Reads live oracle prices but accepts custom fee params and token config.
+     * @param tokenAmount The token amount to simulate fee for (raw units; very large values can revert in fee math)
+     * @param fixedFee The minimum fee floor in COTI wei
+     * @param percentageBps The percentage in basis points (relative to {FEE_DIVISOR})
+     * @param maxFee The maximum fee cap in COTI wei
+     * @param _tokenSymbol The Band oracle symbol (e.g. "ETH", "WBTC", "ADA")
+     * @param _tokenDecimals The decimal precision of the token (e.g. 18, 8, 6)
+     * @return The computed fee in native COTI (18 decimals)
+     */
+    function computeErc20Fee(
+        uint256 tokenAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee,
+        string calldata _tokenSymbol,
+        uint8 _tokenDecimals
+    ) external view returns (uint256) {
+        (uint256 fee,,,) = _computeErc20FeeAndMeta(tokenAmount, fixedFee, percentageBps, maxFee, _tokenSymbol, _tokenDecimals);
+        return fee;
+    }
+
+    /**
+     * @dev ERC20 fee math + two {getPriceWithMeta} reads (token then COTI). Used by {_computeErc20Fee}
+     *      and {estimateDepositFee}/{estimateWithdrawFee}. Each {Math.mulDiv} step truncates toward zero
+     *      (see {PrivacyBridge.FEE_DIVISOR} NatSpec). Extreme `tokenAmount`×`tokenUsdRate` values can make
+     *      {Math.mulDiv} revert—keep amounts within configured max deposit/withdraw limits.
+     */
+    function _computeErc20FeeAndMeta(
+        uint256 tokenAmount,
+        uint256 fixedFee,
+        uint256 percentageBps,
+        uint256 maxFee,
+        string memory oracleTokenSymbol,
+        uint8 tokenDecimals
+    )
+        internal
+        view
+        returns (uint256 fee, uint256 cotiLastUpdated, uint256 tokenLastUpdated, uint256 blockTimestamp)
+    {
+        _requirePriceOracle();
+        ICotiPriceConsumer oracle = ICotiPriceConsumer(priceOracle);
+        (uint256 tokenUsdRate, uint256 tokenLU,) = oracle.getPriceWithMeta(oracleTokenSymbol);
+        (uint256 cotiUsdRate, uint256 cotiLU, uint256 cotiBts) = oracle.getPriceWithMeta("COTI");
+        _requirePositiveOracleRate(tokenUsdRate);
+        _requirePositiveOracleRate(cotiUsdRate);
+        _requireOracleFreshness(tokenLU);
+        _requireOracleFreshness(cotiLU);
+        uint256 txValueUsd = Math.mulDiv(tokenAmount, tokenUsdRate, 10 ** uint256(tokenDecimals));
+        uint256 percentageFeeUsd = Math.mulDiv(txValueUsd, percentageBps, FEE_DIVISOR);
+        uint256 percentageFeeCoti = Math.mulDiv(percentageFeeUsd, 1e18, cotiUsdRate);
+        fee = _calculateDynamicFee(percentageFeeCoti, fixedFee, maxFee);
+        cotiLastUpdated = cotiLU;
+        tokenLastUpdated = tokenLU;
+        blockTimestamp = cotiBts;
+    }
+
+    /**
+     * @notice Estimate the deposit fee in COTI for a given token amount
+     * @param tokenAmount The amount of ERC20 tokens to deposit (raw token units; very large values can revert in fee math)
+     * @return fee                The estimated fee in native COTI (18 decimals)
+     * @return cotiLastUpdated    COTI oracle data last update timestamp
+     * @return tokenLastUpdated   Token oracle data last update timestamp
+     * @return blockTimestamp     Third field from the COTI oracle row (same as pre-refactor behavior)
+     * @dev Pass the returned `cotiLastUpdated` and `tokenLastUpdated` verbatim into {deposit}/{withdraw} together
+     *      with the same `tokenAmount` path; see {PrivacyBridge._validateOracleTimestamps} for strict equality UX.
+     */
+    function estimateDepositFee(uint256 tokenAmount) external view returns (uint256 fee, uint256 cotiLastUpdated, uint256 tokenLastUpdated, uint256 blockTimestamp) {
+        (fee, cotiLastUpdated, tokenLastUpdated, blockTimestamp) = _computeErc20FeeAndMeta(
+            tokenAmount,
+            depositFixedFee,
+            depositPercentageBps,
+            depositMaxFee,
+            tokenSymbol,
+            bridgedTokenDecimals
+        );
+    }
+
+    /**
+     * @notice Estimate the withdrawal fee in COTI for a given token amount
+     * @param tokenAmount The amount of ERC20 tokens to withdraw (raw units; very large values can revert in fee math)
+     * @return fee                The estimated fee in native COTI (18 decimals)
+     * @return cotiLastUpdated    COTI oracle data last update timestamp
+     * @return tokenLastUpdated   Token oracle data last update timestamp
+     * @return blockTimestamp     Third field from the COTI oracle row (same as pre-refactor behavior)
+     * @dev Same timestamp handoff as {estimateDepositFee}: use return values unchanged on the subsequent {withdraw}.
+     */
+    function estimateWithdrawFee(uint256 tokenAmount) external view returns (uint256 fee, uint256 cotiLastUpdated, uint256 tokenLastUpdated, uint256 blockTimestamp) {
+        (fee, cotiLastUpdated, tokenLastUpdated, blockTimestamp) = _computeErc20FeeAndMeta(
+            tokenAmount,
+            withdrawFixedFee,
+            withdrawPercentageBps,
+            withdrawMaxFee,
+            tokenSymbol,
+            bridgedTokenDecimals
+        );
+    }
+
+    /**
+     * @notice Collect the dynamic native COTI fee from msg.value and refund any excess
+     * @param fee The computed fee in native COTI
+     * @dev Reverts with {InsufficientCotiFee} if msg.value < fee.
+     *      Excess above `fee` is sent back to `msg.sender` with a plain `call` (no receive hook guarantee).
+     *      Smart wallets or contracts that revert or return false on unsolicited ETH will not receive the push;
+     *      the excess is then credited to {refundableNativeExcess}[msg.sender] and emits `NativeRefundExcessPushFailed`
+     *      (see {PrivacyBridge._creditRefundableNativeExcess} and {PrivacyBridge.claimRefundableNativeExcess}). Excess
+     *      is never added to {accumulatedCotiFees}.
+     */
+    function _collectDynamicNativeFee(uint256 fee) internal {
+        if (msg.value < fee) revert InsufficientCotiFee();
+        // Verify contract balance covers the fee before accounting
+        if (address(this).balance < fee) revert InsufficientEthBalance();
+        accumulatedCotiFees += fee;
+        if (msg.value > fee) {
+            uint256 excess = msg.value - fee;
+            (bool ok, ) = msg.sender.call{value: excess}("");
+            if (!ok) {
+                _creditRefundableNativeExcess(msg.sender, excess);
+            }
+        }
+    }
+
+    /**
+     * @notice Initialize the PrivacyBridgeERC20 contract
+     * @param _token Address of the public ERC20 token (must be standard: no fee-on-transfer, no rebasing; same decimals as private token)
+     * @param _privateToken Address of the private token
+     * @param _tokenSymbol Band oracle symbol for the bridged token (e.g., "ETH", "WBTC") — required for Band Protocol compatibility check
+     * @param _priceOracle Non-zero price oracle (same requirement as {PrivacyBridge}'s constructor)
+     * @dev **Decimals:** reads `decimals()` on both tokens at deploy; reverts {DecimalsMismatch} if they differ—so
+     *      mis-paired tokens fail **at construction**, not on first user tx. {bridgedTokenDecimals} is then cached
+     *      immutably for fee math. After deploy, a mismatch cannot appear unless token contracts were misconfigured
+     *      at deploy time or an upgradeable token later changes `decimals()` (exceptional external risk; not re-checked on-chain).
+     */
+    constructor(
+        address _token,
+        address _privateToken,
+        string memory _tokenSymbol,
+        address _feeRecipient,
+        address _rescueRecipient,
+        address _priceOracle
+    ) PrivacyBridge(_feeRecipient, _rescueRecipient, _priceOracle) {
+        if (_token == address(0)) revert InvalidTokenAddress();
+        if (_privateToken == address(0)) revert InvalidPrivateTokenAddress();
+
+        uint8 pubDecimals = IHasDecimals(_token).decimals();
+        if (pubDecimals != IHasDecimals(_privateToken).decimals()) revert DecimalsMismatch();
+        bridgedTokenDecimals = pubDecimals;
+
+        token = IERC20(_token);
+        privateToken = IPrivateERC20(_privateToken);
+        tokenSymbol = _tokenSymbol;
+    }
+
+    /**
+     * @notice Deposit public ERC20 tokens to receive equivalent private tokens
+     * @param amount Amount of public ERC20 tokens to deposit
+     * @param cotiOracleTimestamp COTI `lastUpdated` from the latest `estimateDepositFee` (must still equal on-chain at execution).
+     * @param tokenOracleTimestamp Token `lastUpdated` from the same estimate (must still equal on-chain at execution).
+     * @dev Native COTI fee: send msg.value >= computed fee. Excess native is push-refunded then pull-credited on failure
+     *      ({_collectDynamicNativeFee}). If the Band row advances before inclusion, tx reverts with {OracleTimestampMismatch}—re-estimate and resubmit (see {_validateOracleTimestamps}).
+     */
+    function deposit(
+        uint256 amount,
+        uint256 cotiOracleTimestamp,
+        uint256 tokenOracleTimestamp
+    ) external payable nonReentrant whenNotPaused notBlacklisted {
+        _deposit(amount, cotiOracleTimestamp, tokenOracleTimestamp);
+    }
+
+    /**
+     * @dev Pulls public tokens before collecting the native COTI fee so a non-standard transfer
+     *      (e.g. fee-on-transfer) reverts before debiting `msg.value`, and insufficient `msg.value`
+     *      still reverts the whole tx including the token transfer.
+     */
+    function _deposit(uint256 amount, uint256 cotiOracleTimestamp, uint256 tokenOracleTimestamp) internal {
+        if (!isDepositEnabled) revert DepositDisabled();
+        if (amount == 0) revert AmountZero();
+        _checkDepositLimits(amount);
+        _validateOracleTimestamps(cotiOracleTimestamp, tokenOracleTimestamp, tokenSymbol);
+
+        uint256 fee = _computeErc20Fee(amount, depositFixedFee, depositPercentageBps, depositMaxFee);
+
+        uint256 balBefore = token.balanceOf(address(this));
+        token.safeTransferFrom(msg.sender, address(this), amount);
+        uint256 received = token.balanceOf(address(this)) - balBefore;
+        if (received != amount) revert UnexpectedTransferBalance(amount, received);
+
+        _collectDynamicNativeFee(fee);
+
+        totalUserLiability += received;
+        privateToken.mint(msg.sender, received);
+
+        emit Deposit(msg.sender, amount, received);
+    }
+
+    /**
+     * @notice Withdraw public ERC20 tokens by burning private tokens
+     * @param amount Amount of private tokens to burn
+     * @param cotiOracleTimestamp COTI `lastUpdated` from the latest `estimateWithdrawFee` (must still equal on-chain at execution).
+     * @param tokenOracleTimestamp Token `lastUpdated` from the same estimate (must still equal on-chain at execution).
+     * @dev Requires prior approval on the private token. Send `msg.value >= fee`; native fee is
+     *      collected only after the public token transfer succeeds (mirrors {deposit} ordering). Oracle
+     *      timestamp rules match {deposit} / {_validateOracleTimestamps}. Native excess handling matches {deposit}.
+     */
+    function withdraw(
+        uint256 amount,
+        uint256 cotiOracleTimestamp,
+        uint256 tokenOracleTimestamp
+    ) external payable nonReentrant whenNotPaused notBlacklisted {
+        _withdraw(amount, cotiOracleTimestamp, tokenOracleTimestamp);
+    }
+
+    /**
+     * @dev Mirrors {_deposit}: native fee is collected only after the ERC20 leg succeeds by standard
+     *      semantics (here: burn + public transfer with full `userGain`). Insufficient `msg.value`
+     *      then reverts the entire withdrawal including private burn and public transfer.
+     */
+    function _withdraw(uint256 amount, uint256 cotiOracleTimestamp, uint256 tokenOracleTimestamp) internal {
+        if (amount == 0) revert AmountZero();
+        _checkWithdrawLimits(amount);
+        _validateOracleTimestamps(cotiOracleTimestamp, tokenOracleTimestamp, tokenSymbol);
+
+        uint256 fee = _computeErc20Fee(amount, withdrawFixedFee, withdrawPercentageBps, withdrawMaxFee);
+
+        uint256 bridgeBalance = token.balanceOf(address(this));
+        if (bridgeBalance < amount) revert InsufficientBridgeLiquidity();
+
+        totalUserLiability -= amount;
+        privateToken.transferFrom(msg.sender, address(this), amount);
+        privateToken.burn(amount);
+
+        uint256 userBalBefore = token.balanceOf(msg.sender);
+        token.safeTransfer(msg.sender, amount);
+        uint256 userGain = token.balanceOf(msg.sender) - userBalBefore;
+        if (userGain != amount) revert UnexpectedTransferBalance(amount, userGain);
+
+        _collectDynamicNativeFee(fee);
+
+        emit Withdraw(msg.sender, amount, amount);
+    }
+
+    /**
+     * @notice Move ERC20 from this contract to {rescueRecipient} while the bridge is paused.
+     * @dev Requires {whenPaused} for every `_token` so rescue never runs concurrently with user flows.
+     *      For the live public {token}, `amount` can be the full balance—including all TVL backing withdrawals.
+     *      Same governance risk as {PrivacyBridgeCotiNative.rescueNative}: owner + pause can send user funds
+     *      to {rescueRecipient}; see {PrivacyBridge} contract @dev (3). Private token cannot be rescued here
+     *      ({CannotRescueBridgeToken}). {totalUserLiability} is intentionally **not** updated here: rescue only
+     *      moves collateral to {rescueRecipient}; it does not burn private tokens or unwind user obligations on
+     *      this ledger, so outstanding claims can exceed {token} held by this contract until a separate migration
+     *      path makes users whole.
+     */
+    function rescueERC20(
+        address _token,
+        uint256 amount
+    ) external onlyOwner nonReentrant whenPaused {
+        if (amount == 0) revert AmountZero();
+
+        if (_token == address(privateToken)) revert CannotRescueBridgeToken();
+
+        IERC20(_token).safeTransfer(rescueRecipient, amount);
+
+        emit ERC20Rescued(_token, rescueRecipient, amount);
+    }
+}

package/contracts/privacyBridge/PrivacyBridgeUSDCe.sol

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.19;
+
+import "./PrivacyBridgeERC20.sol";
+import "../token/PrivateERC20/tokens/PrivateBridgedUSDC.sol";
+
+/**
+ * @title PrivacyBridgeUSDCe
+ * @notice Bridge contract for converting between USDC.e and privacy-preserving p.USDC.e tokens
+ */
+contract PrivacyBridgeUSDCe is PrivacyBridgeERC20 {
+
+    constructor(
+        address _usdc,
+        address _privateUsdc,
+        address _feeRecipient,
+        address _rescueRecipient,
+        address _priceOracle
+    ) PrivacyBridgeERC20(_usdc, _privateUsdc, "USDC", _feeRecipient, _rescueRecipient, _priceOracle) {
+        
+    }
+}