pushchain · zaryab2000 · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026 · Mar 30, 2026
diff --git a/...sh Chain_[SCA] Push Chain _ Core Contracts _ Mar2026_P-2025-1876_4_20260625 11_10 (1).pdf b/...sh Chain_[SCA] Push Chain _ Core Contracts _ Mar2026_P-2025-1876_4_20260625 11_10 (1).pdf
diff --git a/docs/3_CEA.md b/docs/3_CEA.md
@@ -106,7 +106,7 @@ Each user has exactly one CEA per external chain (v1). A CEA is deployed via `CE
 **Deployment flow:**
 1. `CEAFactory` clones `CEAProxy` template using `cloneDeterministic(salt)` where `salt = keccak256(abi.encode(pushAccount))`.
 2. `CEAFactory` calls `CEAProxy.initializeCEAProxy(CEA_IMPLEMENTATION)` to set the implementation.
-3. `CEAFactory` calls `CEA.initializeCEA(pushAccount, VAULT, UNIVERSAL_GATEWAY)` through the proxy.
+3. `CEAFactory` calls `CEA.initializeCEA(pushAccount, VAULT, UNIVERSAL_GATEWAY, factory)` through the proxy.
 
 In practice:
 ```

diff --git a/docs/CEA_migration_flow.md b/docs/CEA_migration_flow.md
diff --git a/docs/THREAT_MODELLING_DOC.md b/docs/THREAT_MODELLING_DOC.md
diff --git a/docs/UniversalCore.md b/docs/UniversalCore.md
@@ -3,7 +3,7 @@
 ## Contract Locations
 
 - **UniversalCore**: [`src/UniversalCore.sol`](../src/UniversalCore.sol)
-- **IUniversalCore Interface**: [`src/interfaces/IUniversalCore.sol`](../src/interfaces/IUniversalCore.sol)
+- **IUniversalCore Interface**: [`src/Interfaces/IUniversalCore.sol`](../src/Interfaces/IUniversalCore.sol)
 - **PRC20**: [`src/PRC20.sol`](../src/PRC20.sol)
 - **WPC (Wrapped PC)**: [`src/WPC.sol`](../src/WPC.sol)
 
@@ -28,7 +28,7 @@ UniversalCore maintains an on-chain oracle of external chain state. For each sup
 | `timestampObservedAtByChainNamespace` | Timestamp when the observation was recorded |
 | `gasTokenPRC20ByChainNamespace` | PRC-20 address of the chain's native gas token (e.g. pETH for Ethereum) |
 
-The Universal Executor Module periodically calls `setChainMeta(chainNamespace, price, chainHeight, observedAt)` to push fresh external chain data on-chain, updating both `gasPriceByChainNamespace` and `chainHeightByChainNamespace` in a single call. This makes UniversalCore the single source of truth for external chain gas pricing and block height within Push Chain's contract layer.
+The Universal Executor Module periodically calls `setChainMeta(chainNamespace, price, chainHeight)` to push fresh external chain data on-chain, updating `gasPriceByChainNamespace` and `chainHeightByChainNamespace` in a single call. The observation timestamp is derived internally from `block.timestamp` and stored in `timestampObservedAtByChainNamespace`. This makes UniversalCore the single source of truth for external chain gas pricing and block height within Push Chain's contract layer.
 
 This oracle data drives fee computation: when a user initiates an outbound transaction, the gateway queries `getOutboundTxGasAndFees(prc20, gasLimit)` which reads the stored gas price and multiplies it by the gas limit to produce the fee denominated in the destination chain's gas token.
 
@@ -60,8 +60,8 @@ The UE Module is a protocol-level system address that executes on behalf of the
 |---|---|
 | `depositPRC20Token(prc20, amount, recipient)` | Mint PRC-20 tokens to a recipient address on inbound |
 | `depositPRC20WithAutoSwap(prc20, amount, recipient, fee, minPCOut, deadline)` | Mint PRC-20 and swap to native PC in one step |
-| `setChainMeta(chainNamespace, price, chainHeight, observedAt)` | Update gas price and block height oracle data for an external chain |
-| `refundUnusedGas(recipient, amount)` | Refund unused gas to a recipient after execution |
+| `setChainMeta(chainNamespace, price, chainHeight)` | Update gas price and block height oracle data for an external chain (observation timestamp is set to `block.timestamp` internally) |
+| `refundUnusedGas(gasToken, amount, recipient, withSwap, fee, minPCOut)` | Refund unused gas: either mint `gasToken` PRC-20 directly to `recipient`, or swap back to native PC via Uniswap V3 when `withSwap = true` |
 
 ### Manager Role (`MANAGER_ROLE`)
 
@@ -71,34 +71,35 @@ Managers handle operational configuration that changes with external chain condi
 
 | Function | Purpose |
 |---|---|
-| `setGasTokenPRC20(chainNamespace, prc20)` | Map a chain namespace to its gas token PRC-20 |
+| `setGasTokenPRC20(chainNamespace, prc20)` | Map a chain namespace to its gas token PRC-20 (resets `gasPriceByChainNamespace` to `0` to force explicit reconfiguration) |
 | `setGasPCPool(chainNamespace, gasToken, fee)` | Register a Uniswap V3 pool for PC/gas-token swaps |
-| `setSupportedToken(prc20, supported)` | Mark a PRC-20 token as officially supported |
 | `setBaseGasLimitByChain(chainNamespace, gasLimit)` | Set the minimum base gas limit for TSS execution on a chain |
 | `setRescueFundsGasLimitByChain(chainNamespace, gasLimit)` | Set the fixed gas limit for rescue operations on a chain |
+| `setMaxStalenessByChain(chainNamespace, maxStaleness)` | Set the maximum acceptable age (seconds) of stored gas data before fee quotes revert as stale (`0` disables the check, opt-in) |
 | `setProtocolFeeByToken(prc20, fee)` | Set the protocol fee (in native PC) for a PRC-20 token |
 
 ### Admin Role (`DEFAULT_ADMIN_ROLE`)
 
-Granted to the deployer at initialization. Controls contract-level configuration and emergency operations.
+Granted to the deployer at initialization. Controls contract-level configuration (Uniswap addresses, fee tier, WPC, gateway address) and role administration. Note: pause/unpause authority is **not** held by the admin — it is restricted to `PAUSER_ROLE`.
 
 | Function | Purpose |
 |---|---|
 | `setAutoSwapSupported(token, supported)` | Enable/disable auto-swap for a PRC-20 token |
-| `setWPCContractAddress(addr)` | Update the Wrapped PC token address |
-| `setUniswapV3Addresses(factory, swapRouter, quoter)` | Update Uniswap V3 infrastructure addresses |
-| `setDefaultFeeTier(token, feeTier)` | Set default Uniswap V3 fee tier for a token |
-| `setSlippageTolerance(token, tolerance)` | Set slippage tolerance in basis points |
+| `setWPC(addr)` | Update the Wrapped PC token address |
+| `setUniswapV3Addresses(factory, swapRouter)` | Update Uniswap V3 infrastructure addresses |
+| `setDefaultFeeTier(token, feeTier)` | Set default Uniswap V3 fee tier for a token (allowed tiers: 100, 500, 3000, 10000) |
 | `setDefaultDeadlineMins(minutesValue)` | Set default swap deadline |
-| `pause()` / `unpause()` | Emergency pause/unpause all deposit operations |
+| `setUniversalGatewayPC(addr)` | Update the address authorized to call `swapAndBurnGas` |
+| `grantRole(PAUSER_ROLE, addr)` | Grant `PAUSER_ROLE` to an address (guardian) — inherited from OZ AccessControl |
+| `revokeRole(PAUSER_ROLE, addr)` | Revoke `PAUSER_ROLE` from an address — inherited from OZ AccessControl |
 
 ### Gateway (`universalGatewayPC`)
 
 Not an OZ `AccessControl` role. `universalGatewayPC` is a mutable address stored in UniversalCore, checked via the `onlyGatewayPC` modifier. It is updated by the admin and gates the fee settlement function:
 
 | Function | Purpose |
 |---|---|
-| `swapAndBurnGas(gasToken, vault, fee, gasFee, protocolFee, deadline, caller)` | Swap PC for gas token, burn gas fee, send protocol fee to vault |
+| `swapAndBurnGas(gasToken, fee, gasFee, deadline, caller)` | Swap PC for `gasToken`, burn the `gasFee` amount, refund unused PC to `caller` |
 
 ### Pauser Role (`PAUSER_ROLE`)
 
@@ -130,6 +131,8 @@ getOutboundTxGasAndFees(prc20, gasLimitWithBaseLimit)
     |--> look up chainNamespace from prc20.SOURCE_CHAIN_NAMESPACE()
     |--> look up gasToken from gasTokenPRC20ByChainNamespace[chainNamespace]
     |--> look up gasPrice from gasPriceByChainNamespace[chainNamespace]
+    |--> if maxStalenessByChainNamespace[chainNamespace] > 0, enforce freshness of gas data
+    |       (reverts with StaleGasData if block.timestamp > observedAt + maxStaleness)
     |
     |--> gasFee = gasPrice * gasLimitWithBaseLimit   (denominated in gas token units)
     |--> protocolFee = protocolFeeByToken[prc20]     (flat fee in native PC)
@@ -148,7 +151,10 @@ getRescueFundsGasLimit(prc20)
     |
     |--> look up chainNamespace from prc20.SOURCE_CHAIN_NAMESPACE()
     |--> look up rescueGasLimit from rescueFundsGasLimitByChainNamespace[chainNamespace]
-    |--> look up gasToken, gasPrice, protocolFee (same as outbound)
+    |--> look up gasToken and gasPrice (protocol fee is NOT applied on the rescue path)
+    |--> if maxStalenessByChainNamespace[chainNamespace] > 0, enforce freshness of gas data
+    |
+    |--> gasFee = gasPrice * rescueGasLimit
     |
     '--> returns (gasToken, gasFee, rescueGasLimit, gasPrice, chainNamespace)
 ```
@@ -157,7 +163,7 @@ getRescueFundsGasLimit(prc20)
 
 ## Swap-and-Burn: Gas Fee vs Protocol Fee
 
-Outbound transactions require fee settlement. The user pays in native PC, which gets swapped to the destination chain's gas token PRC-20 via Uniswap V3. The resulting gas tokens are then split into two portions with different destinations:
+Outbound transactions require fee settlement. The user pays in native PC. `UniversalGatewayPC` sends the `protocolFee` portion directly to `VaultPC` in native PC, and forwards the remaining PC (intended to cover the gas fee) to `UniversalCore.swapAndBurnGas`, which swaps it into the destination chain's gas token PRC-20 via Uniswap V3 and burns it. The two fee components therefore settle through different paths:
 
 ### Gas Fee (burned)
 
@@ -178,25 +184,29 @@ User pays native PC
         |
         v
 UniversalGatewayPC
-        |
-        | calls swapAndBurnGas{value: pcAmount}(gasToken, vault, fee, gasFee, protocolFee, deadline, caller)
+        | (pays protocolFee to VaultPC directly in native PC, then:)
+        | calls swapAndBurnGas{value: pcAmount}(gasToken, fee, gasFee, deadline, caller)
         v
 UniversalCore
         |
         |--> 1. Wrap PC into WPC (deposit to IWPC)
         |--> 2. Approve Uniswap V3 router to spend WPC
         |--> 3. Swap WPC -> gasToken via exactOutputSingle
         |       (swap exactly gasFee worth of gas token)
+        |--> 4. Clear router allowance (forceApprove 0)
         |
-        |--> 4. BURN gasFee portion:    IPRC20(gasToken).burn(gasFee)
+        |--> 5. BURN gasFee portion:    IPRC20(gasToken).burn(gasFee)
         |
-        |--> 5. REFUND unused PC:       unwrap leftover WPC, send native PC back to caller
+        |--> 6. REFUND unused PC:       unwrap leftover WPC, send native PC back to caller
         |
-        '--> emit SwapAndBurnGas(gasToken, vault, pcUsed, gasFee, protocolFee, fee, caller)
+        '--> emit SwapAndBurnGas(gasToken, pcIn, gasFee, fee, caller)
+             returns (gasTokenOut, refund)
 ```
 
 The swap uses `exactOutputSingle` — the caller specifies exactly how much gas token output is needed (`gasFee`), and any unused PC input is refunded directly to the caller address. This ensures users never overpay.
 
+Note: `swapAndBurnGas` does not receive or route the protocol fee. `UniversalGatewayPC` pays the `protocolFee` (in native PC) directly to `VaultPC` before invoking `swapAndBurnGas`; only the `gasFee` burn and PC refund happen inside this function. The event therefore emits `(gasToken, pcIn, gasFee, fee, caller)` and does not include vault or protocol-fee fields.
+
 ### Why burn vs transfer?
 
 - **Burn (gas fee)**: The gas fee represents real execution cost on the destination chain. Burning the equivalent PRC-20 on Push Chain keeps the wrapped token supply in sync with actual external-chain liabilities. The protocol (via validators/TSS) covers the real gas on the destination side.

diff --git a/docs/addresses/arbitrum_sepolia.md b/docs/addresses/arbitrum_sepolia.md
@@ -0,0 +1,12 @@
+# Arbitrum Sepolia (Chain ID: 421614)
+
+| Contract                    | Address                                      |
+| --------------------------- | -------------------------------------------- |
+| CEA (logic)                 | `0x2c933Ff6FBcD479055F344691bc628F51DcE871A` |
+| CEAProxy (clone template)   | `0x512d1B8C185a0Fd533a69f8973A3DD6513233009` |
+| CEAFactory (implementation) | `0xd8335e762E42b7f9610293707d6d8A6b97578bFb` |
+| ProxyAdmin                  | `0x6349546d872d483A35bdD165c9ef85757e064D4E` |
+| CEAFactory (proxy)          | `0x88DC189275078Cf509E4Cc773F089c8ad07b7EA2` |
+| CEA_V2 (logic)              | `0xe23741BffF1dAac6f98cEC84ce3EBAfeF1Cd5965` |
+| CEAMigration                | `0x81f33160020AaDF47000E85915d332943b69F9f9` |
+| CEA (post-audit)            | `0x0D74144cED066a1f3BA94887ED9a6443F7bD26c5` |
diff --git a/docs/addresses/base_sepolia.md b/docs/addresses/base_sepolia.md
@@ -0,0 +1,12 @@
+# Base Sepolia (Chain ID: 84532)
+
+| Contract                    | Address                                      |
+| --------------------------- | -------------------------------------------- |
+| CEA (logic)                 | `0x733078bA1dFDDDB68A9E082696A256AEcBFb26b8` |
+| CEAProxy (clone template)   | `0x6c9Cfef12155bEE91ecD6d0C8f516cABA2890656` |
+| CEAFactory (implementation) | `0xd26E793Ef931EB62AeBc6e87DE1FEEF4fDbA01F5` |
+| ProxyAdmin                  | `0x413A39fFA85657A25768799f7fd64A917eceDe48` |
+| CEAFactory (proxy)          | `0x0A75ca7736b488Eb41675ADc3b3156BACF659F55` |
+| CEA_V2 (logic)              | `0x6085C657A6d12F789a388D96730D248b74437730` |
+| CEAMigration                | `0x95c453fDFf55Afc5754c1fA95Ad6607273D71B20` |
+| CEA (post-audit)            | `0xF9EAf33bAB2f7f21bEe1712Ce9688Cf29053BfFb` |
diff --git a/docs/addresses/bsc_testnet.md b/docs/addresses/bsc_testnet.md
@@ -1,19 +1,12 @@
-  # BSC Testnet (Chain ID: 97)
+# BSC Testnet (Chain ID: 97)
 
-  | Contract | Address |
-  |---|---|
-  | CEA (logic) | `0x60A4140429446E515aB15A02f8FB46F7c81fE3b2` |
-  | CEAProxy (clone template) | `0xcF66462F97daea2c0Ef549c542D54C6F4dc3e8B1` |
-  | CEAFactory (implementation) | `0x95E6c8aACe87e8401cd4bDFF1B9DaC53059C8808` |
-  | ProxyAdmin | `0xBD083Bf209D8c791aF71E96ace5aF67D15d83Cef` |
-  | CEAFactory (proxy) | `0xac52b7be327C1e6A617937CFfE90269aDccD211d` |
-
-## New Latest CEA Contracts for BSC
-
-  | Contract | Address |
-  |---|---|
-  | CEA (logic) | `0xa66C8832bB97203E07B65d876d2ceAe3801709B6` |
-  | CEAProxy (clone template) | `0xBDF06996BA23AE797a4aA9C8C5994D313D763a7c` |
-  | CEAFactory (implementation) | `0xC0D35725Dd054B09931740DC231cDea89B0FEd3b` |
-  | ProxyAdmin | `0xf33CBb6a1c1D511dF40764063a11978D640C41A7` |
-  | CEAFactory (proxy) | `0xe2182dae2dc11cBF6AA6c8B1a7f9c8315A6B0719` |
+| Contract                    | Address                                      |
+| --------------------------- | -------------------------------------------- |
+| CEA (logic)                 | `0xdC3A3a18a17EB4FDa9cF34a8CEee8540e6F2b5Fd` |
+| CEAProxy (clone template)   | `0xBDF06996BA23AE797a4aA9C8C5994D313D763a7c` |
+| CEAFactory (implementation) | `0xC0D35725Dd054B09931740DC231cDea89B0FEd3b` |
+| ProxyAdmin                  | `0xf33CBb6a1c1D511dF40764063a11978D640C41A7` |
+| CEAFactory (proxy)          | `0xe2182dae2dc11cBF6AA6c8B1a7f9c8315A6B0719` |
+| CEA_V2 (logic)              | `0x102B1652ABEDC1c1761355F1Fc71c8487c3a9168` |
+| CEAMigration                | `0x2a06BF2A9C19dacbb38852f846B42e278e82e855` |
+| CEA (post-audit)            | `0x8FAB1Da91Bd45F4DaF3D50C47A38b49bE9afEff7` |
diff --git a/docs/addresses/eth_sepolia.md b/docs/addresses/eth_sepolia.md
@@ -0,0 +1,12 @@
+# Ethereum Sepolia (Chain ID: 11155111)
+
+| Contract                    | Address                                      |
+| --------------------------- | -------------------------------------------- |
+| CEA (logic)                 | `0x1939376ce03998F638b8760c7a13C9A379A053C0` |
+| CEAProxy (clone template)   | `0x0a4F7be62B56830070266be81114edB93e68DA09` |
+| CEAFactory (implementation) | `0xe5B51807f2252A5Ea9B591fE02285954446c8cAD` |
+| ProxyAdmin                  | `0xF920e3D1420885A117Cb59830d0474aD5690dd82` |
+| CEAFactory (proxy)          | `0x8ED594A83301FEc545fC6c19fc12cF7111777029` |
+| CEA_V2 (logic)              | `0x2235df0189F720E9dbF1E31685eb7b6221E0fdD7` |
+| CEAMigration                | `0x97BCEba9c6f13B0E12Fde0E4D2697F74A79899de` |
+| CEA (post-audit)            | `0x2d10cdB85989a199a0255E5dc55491B1bdd95A45` |
diff --git a/docs/addresses/sepolia.md b/docs/addresses/sepolia.md
diff --git a/foundry.toml b/foundry.toml
@@ -16,10 +16,13 @@ auto_detect_solc = false
 evm_version = "shanghai"
 via_ir = true
 
-no_match_coverage = "(PRC20V0\\.sol|UniversalCoreV0\\.sol|ReceiverExample\\.sol|src/(libraries|[Ii]nterfaces|mocks)/|test/)"
+no_match_coverage = "(PRC20V0\\.sol|testnetV0/UniversalCore\\.sol|ReceiverExample\\.sol|src/(libraries|[Ii]nterfaces|mocks)/|test/)"
 
 fs_permissions = [{ access = "read-write", path = "deployments/" }]
 
+[fmt]
+ignore = ["src/**"]
+
 [fuzz]
 runs = 1024
 max_test_rejects = 65536

diff --git a/scripts/cea/deployCEA.s.sol b/scripts/cea/deployCEA.s.sol
@@ -11,7 +11,7 @@ import {CEA} from "../../src/cea/CEA.sol";
  * @dev Deploys only the CEA logic contract (no factory, proxy, or admin).
  *      Useful when upgrading the CEA implementation on an existing CEAFactory.
  *
- *      After deployment, call `CEAFactory.updateCEAImplementation(newCEAImpl)`
+ *      After deployment, call `CEAFactory.setCEAImplementation(newCEAImpl)`
  *      on the factory to point clones at the new implementation.
  *
  * CONFIGURATION:
@@ -62,19 +62,13 @@ contract DeployCEAScript is Script {
         console.log(json);
 
         // Write to file
-        string memory filename = string(
-            abi.encodePacked(
-                "deployments/cea-impl-",
-                vm.toString(chainId),
-                ".json"
-            )
-        );
+        string memory filename = string(abi.encodePacked("deployments/cea-impl-", vm.toString(chainId), ".json"));
         vm.writeFile(filename, json);
         console.log("\nDeployment saved to:", filename);
 
         console.log("\n=== Deployment Complete ===");
         console.log(
-            "NEXT STEP: Call CEAFactory.updateCEAImplementation(",
+            "NEXT STEP: Call CEAFactory.setCEAImplementation(",
             address(ceaImplementation),
             ") on the factory proxy to activate this implementation."
         );
@@ -111,7 +105,7 @@ contract DeployCEAScript is Script {
  * Update the factory to use the new implementation:
  *
  * cast send <CEA_FACTORY_PROXY_ADDRESS> \
- *   "updateCEAImplementation(address)" <CEA_IMPLEMENTATION_ADDRESS> \
+ *   "setCEAImplementation(address)" <CEA_IMPLEMENTATION_ADDRESS> \
  *   --rpc-url $RPC_URL \
  *   --private-key $KEY
  */