Output validator [OutputValidator v1.0.0]

conventions.md

@@ -524,18 +524,48 @@ Bash scripts provide the robust deployment framework with automated retry mechan
   - **Deployment Scripts:**
 
     - Inherit `DeployScriptBase`
-    - Use JSON config with `stdJson`
-    - Define `getConstructorArgs()` if needed
-    - Encode constructor arguments
     - Call `deploy()` with `type({ContractName}).creationCode`
-    - Example JSON handling:
+
+    - **For contracts WITHOUT constructor arguments:**
       ```solidity
-      string memory path = string.concat(root, "/config/{facetName}.json");
-      address configValue = _getConfigContractAddress(
-        path,
-        string.concat(".{key}.", network, ".{subkey}")
-      );
+      contract DeployScript is DeployScriptBase {
+          constructor() DeployScriptBase("ContractName") {}
+
+          function run() public returns (ContractName deployed) {
+              deployed = ContractName(deploy(type(ContractName).creationCode));
+          }
+      }
+      ```
+      - DO NOT implement `getConstructorArgs()` function
+      - DO NOT import `stdJson`
+      - Return only the deployed contract
+
+    - **For contracts WITH constructor arguments:**
+      ```solidity
+      contract DeployScript is DeployScriptBase {
+          using stdJson for string;
+
+          constructor() DeployScriptBase("ContractName") {}
+
+          function run() public returns (ContractName deployed, bytes memory constructorArgs) {
+              constructorArgs = getConstructorArgs();
+              deployed = ContractName(deploy(type(ContractName).creationCode));
+          }
+
+          function getConstructorArgs() internal override returns (bytes memory) {
+              // JSON config handling
+              string memory path = string.concat(root, "/config/{facetName}.json");
+              address configValue = _getConfigContractAddress(
+                path,
+                string.concat(".{key}.", network, ".{subkey}")
+              );
+              return abi.encode(configValue);
+          }
+      }
       ```
+      - Import `stdJson` for configuration
+      - Implement `getConstructorArgs()` function
+      - Return both deployed contract AND constructor args
 
   - **Update Scripts:**
     - Inherit `UpdateScriptBase`

deployments/_deployments_log_file.json

@@ -39125,5 +39125,37 @@
         ]
       }
     }
+  },
+  "OutputValidator": {
+    "arbitrum": {
+      "staging": {
+        "1.0.0": [
+          {
+            "ADDRESS": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A",
+            "OPTIMIZER_RUNS": "1000000",
+            "TIMESTAMP": "2025-08-20 15:59:24",
+            "CONSTRUCTOR_ARGS": "0x000000000000000000000000156cebba59deb2cb23742f70dcb0a11cc775591f",
+            "SALT": "",
+            "VERIFIED": "true",
+            "ZK_SOLC_VERSION": ""
+          }
+        ]
+      }
+    },
+    "optimism": {
+      "staging": {
+        "1.0.0": [
+          {
+            "ADDRESS": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A",
+            "OPTIMIZER_RUNS": "1000000",
+            "TIMESTAMP": "2025-08-20 16:25:58",
+            "CONSTRUCTOR_ARGS": "0x000000000000000000000000156cebba59deb2cb23742f70dcb0a11cc775591f",
+            "SALT": "",
+            "VERIFIED": "true",
+            "ZK_SOLC_VERSION": ""
+          }
+        ]
+      }
+    }
   }
 }

deployments/arbitrum.diamond.staging.json

@@ -191,7 +191,8 @@
       "ReceiverStargateV2": "",
       "RelayerCelerIM": "0xa1Ed8783AC96385482092b82eb952153998e9b70",
       "Patcher": "0x3971A968c03cd9640239C937F8d30D024840E691",
-      "TokenWrapper": "0xF63b27AE2Dc887b88f82E2Cc597d07fBB2E78E70"
+      "TokenWrapper": "0xF63b27AE2Dc887b88f82E2Cc597d07fBB2E78E70",
+      "OutputValidator": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A"
     }
   }
-}
+}

deployments/arbitrum.staging.json

@@ -57,5 +57,6 @@
   "ChainflipFacet": "0xa884c21873A671bD010567cf97c937b153F842Cc",
   "LiFiDEXAggregator": "0x14aB08312a1EA45F76fd83AaE89A3118537FC06D",
   "Patcher": "0x18069208cA7c2D55aa0073E047dD45587B26F6D4",
-  "WhitelistManagerFacet": "0x603f0c31B37E5ca3eA75D5730CCfaBCFF6D17aa3"
-}
+  "WhitelistManagerFacet": "0x603f0c31B37E5ca3eA75D5730CCfaBCFF6D17aa3",
+  "OutputValidator": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A"
+}

deployments/optimism.diamond.staging.json

@@ -165,7 +165,10 @@
       "ReceiverAcrossV3": "0x3877f47B560819E96BBD7e7700a02dfACe36D696",
       "ReceiverChainflip": "",
       "ReceiverStargateV2": "",
-      "TokenWrapper": "0xF63b27AE2Dc887b88f82E2Cc597d07fBB2E78E70"
+      "RelayerCelerIM": "0xa1Ed8783AC96385482092b82eb952153998e9b70",
+      "TokenWrapper": "0xF63b27AE2Dc887b88f82E2Cc597d07fBB2E78E70",
+      "OutputValidator": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A",
+      "Patcher": ""
     }
   }
-}
+}

deployments/optimism.staging.json

@@ -45,5 +45,6 @@
   "LidoWrapper": "0x462A9B6879770050021823D63aE62470E65Af8D4",
   "Permit2Proxy": "0x808eb38763f3F51F9C47bc93Ef8d5aB7E6241F46",
   "GasZipFacet": "0xfEeCe7B3e68B9cBeADB60598973704a776ac3ca1",
+  "OutputValidator": "0xd54C00CA32eC8Db51B7dBbC73124De83096C850A",
   "GlacisFacet": "0x36e1375B0755162d720276dFF6893DF02bd49225"
-}
+}

docs/OutputValidator.md

@@ -0,0 +1,156 @@
+# OutputValidator
+
+## Overview
+
+The `OutputValidator` contract is a periphery contract that validates swap output amounts and transfers excess tokens to a designated validation wallet. It is designed to be called by the Diamond contract after a swap operation to ensure that any excess output tokens are properly distributed.
+
+## Key Features
+
+- **Excess Distribution Management**: Intelligently distributes excess tokens to validation wallet
+- **Dual Token Support**: Handles both native (ETH) and ERC20 tokens with separate functions
+- **No Ownership**: Stateless design without ownership requirements
+- **Gas Optimized**: Minimal validation for maximum efficiency
+
+## Contract Logic
+
+### Native Token Flow
+
+1. The calling contract (Diamond) sends a portion of native tokens as `msg.value` for excess handling
+2. **Calculates excess**: `excessAmount = (contract_balance + msg.value) - expectedAmount`
+3. **Smart distribution**:
+   - If `excessAmount >= msg.value`: All `msg.value` goes to validation wallet (contract balance covers expected amount)
+   - If `excessAmount < msg.value`: Sends `excessAmount` to validation wallet, returns `msg.value - excessAmount` to sender
+4. **User receives expected amount** through the normal swap flow, not from this contract
+
+### ERC20 Token Flow
+
+1. The calling contract (Diamond) must have sufficient ERC20 token balance and approve this contract
+2. **Calculates excess**: `excessAmount = ERC20(tokenAddress).balanceOf(msg.sender) - expectedAmount`
+3. **Transfer excess**: If `excessAmount > 0`, transfers excess tokens to validation wallet via `transferFrom`
+4. **Safety checks**: Validates wallet address and handles zero excess gracefully
+
+> **Design Philosophy**: The contract handles excess distribution only. Users receive their `expectedAmount` through the primary swap mechanism, while this contract ensures proper excess management without holding funds permanently.
+
+**Note**: The contract reverts on arithmetic underflow if actual amounts are less than expected, providing fail-safe behavior.
+
+## Functions
+
+### `validateNativeOutput`
+
+```solidity
+function validateNativeOutput(
+    uint256 expectedAmount,
+    address validationWalletAddress
+) external payable
+```
+
+**Parameters:**
+
+- `expectedAmount`: The expected amount of native tokens (minAmountOut)
+- `validationWalletAddress`: The address to send excess tokens to
+
+**Behavior:**
+
+- Calculates total output as `contract_balance + msg.value`
+- Intelligently distributes excess between validation wallet and sender
+- Designed for scenarios where `msg.value` represents a portion sent for excess handling
+
+### `validateERC20Output`
+
+```solidity
+function validateERC20Output(
+    address tokenAddress,
+    uint256 expectedAmount,
+    address validationWalletAddress
+) external
+```
+
+**Parameters:**
+
+- `tokenAddress`: The address of the ERC20 token to validate
+- `expectedAmount`: The expected amount of tokens (minAmountOut)
+- `validationWalletAddress`: The address to send excess tokens to
+
+**Behavior:**
+
+- Checks caller's token balance and calculates excess
+- Transfers excess to validation wallet if `excessAmount > 0`
+- Validates wallet address and requires sufficient allowance
+
+## Errors
+
+The contract does not define custom errors. Error handling is delegated to the underlying libraries:
+
+- **Native token errors**: Handled by `LibAsset.transferAsset()`
+- **ERC20 token errors**: Handled by `SafeTransferLib.safeTransferFrom()`
+- **Input validation**: Handled by `LibAsset` library for null address checks
+
+## Integration
+
+### Example Usage
+
+```solidity
+// For native tokens - send portion of output for excess handling
+outputValidator.validateNativeOutput{value: portionForExcess}(
+    expectedAmount,
+    validationWallet
+);
+
+// For ERC20 tokens
+// First approve the OutputValidator to spend excess tokens
+token.approve(address(outputValidator), excessAmount);
+outputValidator.validateERC20Output(
+    address(token),
+    expectedAmount,
+    validationWallet
+);
+```
+
+## Security Considerations
+
+- **Stateless Design**: No ownership or state storage reduces attack surface
+- **Safe Transfers**: Uses `SafeTransferLib` for safe ERC20 operations and `LibAsset` for native transfers
+- **Input Validation**: ERC20 function validates wallet addresses; native transfers rely on `LibAsset` validation
+- **Fail-Safe Behavior**: Reverts on arithmetic underflow when actual < expected amounts
+- **No Fund Retention**: Contract never retains funds permanently, minimizing risk
+
+## Test Coverage
+
+The contract includes comprehensive test coverage including:
+
+### **Core Functionality Tests**
+
+- Native token validation with excess (positive slippage scenarios)
+- ERC20 token validation with excess (positive slippage scenarios)
+- Edge cases (zero expected amount, insufficient allowance)
+
+### **Integration Tests**
+
+- Complete DEX swap + OutputValidator + Bridge flows
+- ERC20 → ERC20 swap with positive slippage
+- ERC20 → Native swap with positive slippage
+- Native → ERC20 swap with positive slippage
+
+### **Negative Test Cases**
+
+- Insufficient allowance scenarios
+- Native transfer failures to invalid addresses
+- Zero value with non-zero expected amount
+- **No excess scenarios** (contract handles gracefully by transferring 0 tokens)
+
+### **Test Statistics**
+
+- **19 test cases** covering all code paths
+- **All branches covered** including edge cases
+- **Realistic scenarios** using MockDEX and Diamond integration
+
+## Deployment
+
+The contract is deployed using the standard deployment script pattern with no constructor parameters. The contract is automatically included in periphery contract deployments and is configured in `script/deploy/resources/deployRequirements.json`.
+
+### **Deployment Scripts**
+
+- **Standard**: `script/deploy/facets/DeployOutputValidator.s.sol`
+- **zkSync**: `script/deploy/zksync/DeployOutputValidator.zksync.s.sol`
+
+Both scripts follow the established deployment patterns and integrate with the CREATE3Factory for predictable contract addresses. No configuration parameters are required due to the stateless design.

script/deploy/deploySingleContract.sh

@@ -135,7 +135,7 @@ deploySingleContract() {
   if ! isZkEvmNetwork "$NETWORK"; then
     # prepare bytecode
     BYTECODE=$(getBytecodeFromArtifact "$CONTRACT")
-
+    
     # get CREATE3_FACTORY_ADDRESS
     CREATE3_FACTORY_ADDRESS=$(getCreate3FactoryAddress "$NETWORK")
     checkFailure $? "retrieve create3Factory address from networks.json"
@@ -163,7 +163,7 @@ deploySingleContract() {
     if [[ $CONTRACT == "LiFiDiamond" && $DEPLOY_TO_DEFAULT_DIAMOND_ADDRESS == "true" ]]; then
       CONTRACT_ADDRESS="0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE"
     else
-      CONTRACT_ADDRESS=$(getContractAddressFromSalt "$DEPLOYSALT" "$NETWORK" "$CONTRACT" "$ENVIRONMENT")
+      CONTRACT_ADDRESS=$(getContractAddressFromSalt "$DEPLOYSALT" "$NETWORK" "$CONTRACT" "$ENVIRONMENT" "$CREATE3_FACTORY_ADDRESS")
     fi
 
     # check if address already contains code (=> are we deploying or re-running the script again?)
@@ -229,10 +229,11 @@ deploySingleContract() {
       fi
 
     # check the return code the last call
-    elif [ $RETURN_CODE -eq 0 ]; then
+    else
       # extract deployed-to address from return data
         ADDRESS=$(extractDeployedAddressFromRawReturnData "$RAW_RETURN_DATA" "$NETWORK")
-        if [[ $? -ne 0 ]]; then
+
+        if [[ $? -ne 0 || -z $ADDRESS ]]; then
           error "❌ Could not extract deployed address from raw return data"
           return 1
         elif [[ -n "$ADDRESS" ]]; then

script/deploy/facets/DeployOutputValidator.s.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+pragma solidity ^0.8.17;
+
+import { DeployScriptBase } from "./utils/DeployScriptBase.sol";
+import { OutputValidator } from "lifi/Periphery/OutputValidator.sol";
+
+contract DeployScript is DeployScriptBase {
+    constructor() DeployScriptBase("OutputValidator") {}
+
+    function run() public returns (OutputValidator deployed) {
+        deployed = OutputValidator(deploy(type(OutputValidator).creationCode));
+    }
+}

script/deploy/zksync/DeployOutputValidator.zksync.s.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+pragma solidity ^0.8.17;
+
+import { DeployScriptBase } from "./utils/DeployScriptBase.sol";
+import { OutputValidator } from "lifi/Periphery/OutputValidator.sol";
+
+contract DeployScript is DeployScriptBase {
+    constructor() DeployScriptBase("OutputValidator") {}
+
+    function run() public returns (OutputValidator deployed) {
+        deployed = OutputValidator(deploy(type(OutputValidator).creationCode));
+    }
+}