fix(FLOW-16): reconcile cross-VM refund precision and harden worker recovery

CLAUDE.md

@@ -48,7 +48,7 @@ flow deps install --skip-alias --skip-deployments  # Install dependencies
 1. **EVM User** calls `FlowYieldVaultsRequests.sol` (creates request, escrows funds)
 2. **FlowYieldVaultsEVMWorkerOps.cdc** SchedulerHandler schedules WorkerHandlers to process requests
 3. **FlowYieldVaultsEVM.cdc** Worker fetches pending requests via `getPendingRequestsUnpacked()`
-4. **Two-phase commit**: `startProcessingBatch()` marks PROCESSING and deducts balance, `completeProcessing()` marks COMPLETED/FAILED (refunds credited to `claimableRefunds` on failure)
+4. **Two-phase commit**: `startProcessingBatch()` marks PROCESSING and deducts balance, `completeProcessing()` marks COMPLETED/FAILED and credits any EVM-side refund due to `claimableRefunds` (failed CREATE/DEPOSIT or successful CREATE/DEPOSIT precision residuals)
 
 ### Contract Components
 
@@ -117,6 +117,8 @@ flow deps install --skip-alias --skip-deployments  # Install dependencies
 | FlowYieldVaultsEVM (Cadence)      | `df111ffc5064198a`                           |
 | FlowYieldVaultsEVMWorkerOps       | `df111ffc5064198a`                           |
 
+The current worker code expects the 5-argument `completeProcessing(uint256,bool,uint64,string,uint256)` ABI. Keep Cadence and EVM deployments in sync when reviewing or updating testnet addresses.
+
 ## Blockchain Execution Model (Critical for Code Review)
 
 When reviewing this codebase, keep these fundamental blockchain properties in mind:

FLOW_YIELD_VAULTS_EVM_BRIDGE_DESIGN.md

@@ -99,7 +99,7 @@ mapping(address => uint256[]) public pendingRequestIdsByUser;
 
 // Balance tracking
 mapping(address => mapping(address => uint256)) public pendingUserBalances;  // Escrowed for active requests
-mapping(address => mapping(address => uint256)) public claimableRefunds;     // Claimable from cancelled/failed
+mapping(address => mapping(address => uint256)) public claimableRefunds;     // Claimable from cancelled, dropped, failed, or success-path residual refunds
 
 // Token configuration
 mapping(address => TokenConfig) public allowedTokens;
@@ -226,7 +226,7 @@ enum RequestStatus {
     PENDING,     // 0 - Awaiting processing
     PROCESSING,  // 1 - Being processed (balance deducted)
     COMPLETED,   // 2 - Successfully processed
-    FAILED       // 3 - Failed (refund credited; user must claim)
+    FAILED       // 3 - Failed (escrowed CREATE/DEPOSIT may credit a claimable refund)
 }
 
 struct TokenConfig {
@@ -385,6 +385,7 @@ All refund scenarios use a pull pattern - funds are credited to `claimableRefund
 | Scenario | What Happens |
 |----------|--------------|
 | After `startProcessingBatch()` (failed CREATE/DEPOSIT) | Funds credited to `claimableRefunds` |
+| Successful CREATE/DEPOSIT with precision loss | Precision residual credited to `claimableRefunds` |
 | User cancels request | Funds moved from `pendingUserBalances` to `claimableRefunds` |
 | Admin drops request | Funds moved from `pendingUserBalances` to `claimableRefunds` |
 | WITHDRAW/CLOSE | No escrowed funds on EVM side, so refunds are not applicable |
@@ -418,19 +419,21 @@ function completeProcessing(
     uint256 requestId,
     bool success,
     uint64 yieldVaultId,
-    string calldata message
+    string calldata message,
+    uint256 refundAmount
 ) external onlyAuthorizedCOA {
     // 1. Validate request is PROCESSING
-    // 2. Mark as COMPLETED or FAILED
-    // 3. On failure (CREATE/DEPOSIT): Credit claimableRefunds (user must call claimRefund)
-    // 4. On CREATE_YIELDVAULT success: Register YieldVault ownership
-    // 5. On CLOSE_YIELDVAULT success: Unregister YieldVault ownership
-    // 6. Remove from pending queue
-    // 7. Emit RequestProcessed event
+    // 2. Validate refundAmount against the request lifecycle
+    // 3. Mark as COMPLETED or FAILED
+    // 4. Credit claimableRefunds when a failed CREATE/DEPOSIT or success-path precision residual must stay on EVM
+    // 5. On CREATE_YIELDVAULT success: Register YieldVault ownership
+    // 6. On CLOSE_YIELDVAULT success: Unregister YieldVault ownership
+    // 7. Remove from pending queue
+    // 8. Emit RequestProcessed event
 }
 ```
 
-**Purpose:** Finalizes the operation with proper cleanup. On failure, refunds are credited for later claim; cross-VM flow is not atomic.
+**Purpose:** Finalizes the operation with proper cleanup. Refunds are credited for later claim when a failed CREATE/DEPOSIT must be returned on EVM or when a successful CREATE/DEPOSIT leaves a precision residual on EVM; cross-VM flow is not atomic.
 
 ---
 
@@ -620,8 +623,8 @@ Ownership is verified for WITHDRAW/CLOSE on both EVM and Cadence. Deposits are p
 
 ### Fund Safety
 
-1. **Escrow Model:** Funds held in contract until processing begins; refunds are claimable on failure
-2. **Two-Phase Commit:** Balance deducted before operation, credited back on failure
+1. **Escrow Model:** Funds held in contract until processing begins; failed CREATE/DEPOSIT and success-path precision residuals become claimable refunds
+2. **Two-Phase Commit:** Balance deducted before operation, then reconciled on completion via success/failure finalization plus any explicit refund amount
 3. **Cross-VM Non-Atomicity:** Funds can be in transit between EVM and Cadence; stuck PROCESSING is possible without admin recovery
 4. **ReentrancyGuard:** Solidity contract protected against reentrancy
 
@@ -742,7 +745,7 @@ pre {
 
 ### Cadence Error Handling
 
-Failed operations return `ProcessResult` with `success: false` and descriptive message. The Worker emits `RequestFailed` and calls `completeProcessing(success: false)` to credit refunds for later `claimRefund`.
+Failed operations return `ProcessResult` with `success: false` and descriptive message. The Worker emits `RequestFailed` and calls `completeProcessing(..., refundAmount)` to credit any failed escrowed amount for later `claimRefund`. Successful CREATE/DEPOSIT requests may also credit a smaller precision-residual refund during completion.
 
 ---
 

README.md

@@ -64,7 +64,7 @@ This bridge allows EVM users to interact with Flow YieldVaults (yield-generating
 3. **SchedulerHandler** fetches pending requests, calls `preprocessRequests()` to validate and transition (PENDING → PROCESSING), then schedules WorkerHandlers
 4. **WorkerHandler** processes individual requests via `processRequest()`:
    - Execute Cadence operation (create/deposit/withdraw/close YieldVault)
-   - `completeProcessing()`: Marks as COMPLETED or FAILED (on failure, credits `claimableRefunds`; user claims via `claimRefund`)
+   - `completeProcessing()`: Marks as COMPLETED or FAILED and credits any EVM-side refund due to `claimableRefunds` (failed CREATE/DEPOSIT or successful CREATE/DEPOSIT precision residuals; user claims via `claimRefund`)
 5. **Funds bridged** to user on withdrawal/close operations
 
 ## Quick Start
@@ -193,6 +193,8 @@ forge script ./solidity/script/FlowYieldVaultsYieldVaultOperations.s.sol:FlowYie
 
 Source of truth for published addresses: `deployments/contract-addresses.json`.
 
+The current contracts must be deployed in lockstep: the worker now calls the 5-argument `completeProcessing(uint256,bool,uint64,string,uint256)` ABI, so any environment still pointing at an older `FlowYieldVaultsRequests` deployment must be updated before using the current Cadence worker.
+
 ## Versioning and Branching
 
 This repo follows the contract versioning approach discussed in
@@ -281,7 +283,7 @@ Testnet E2E uses `deployments/contract-addresses.json` to auto-load addresses (s
 
 ### Fund Safety
 
-- Funds are escrowed until processing begins; failed CREATE/DEPOSIT credit refunds to `claimableRefunds` (user calls `claimRefund`)
+- Funds are escrowed until processing begins; failed CREATE/DEPOSIT and successful CREATE/DEPOSIT precision residuals credit `claimableRefunds` (user calls `claimRefund`)
 - Two-phase commit keeps EVM-side balance updates consistent; cross-VM flow is not atomic
 - Request cancellation and admin drop move escrowed funds to `claimableRefunds` (pull pattern)
 

cadence/contracts/FlowYieldVaultsEVM.cdc

@@ -24,7 +24,13 @@ import "FlowEVMBridgeConfig"
 ///         batch-update statuses (PENDING -> PROCESSING for valid, PENDING -> FAILED for invalid)
 ///      2. Processing: For each PROCESSING request, executes Cadence-side operation
 ///         (create/deposit/withdraw/close YieldVault), then calls completeProcessing() to mark
-///         as COMPLETED or FAILED (with refund to EVM contract on CREATE/DEPOSIT failure)
+///         as COMPLETED or FAILED while reconciling any refund owed on the EVM side
+///      PRECISION NOTE:
+///      Native FLOW uses 18 decimals and ERC20 tokens use their own token decimals,
+///      while Cadence UFix64 supports 8 decimal places.
+///      CREATE/DEPOSIT requests therefore round the bridged amount down to the nearest
+///      Cadence-representable quantity and refund any remainder back to EVM claimable refunds.
+
 access(all) contract FlowYieldVaultsEVM {
 
     // ============================================
@@ -575,7 +581,7 @@ access(all) contract FlowYieldVaultsEVM {
         /// @dev This is the main dispatcher that:
         ///      1. Validates request status - should be PROCESSING
         ///      2. Dispatches to the appropriate process function based on request type
-        ///      3. Calls completeProcessing to update final status (with refund on failure for CREATE/DEPOSIT)
+        ///      3. Calls completeProcessing to update final status and return any refund due on EVM
         /// @param request The EVM request to process
         /// @return ProcessResult with success status, the yieldVaultId, and status message
         access(all) fun processRequest(_ request: EVMRequest): ProcessResult {
@@ -622,14 +628,17 @@ access(all) contract FlowYieldVaultsEVM {
                 )
             }
 
-            // Pass refund info - completeProcessing will determine if refund is needed
-            // based on success flag and request type
+            let refundAmount = FlowYieldVaultsEVM.refundAmountForCompletion(
+                request: request,
+                success: result!.success
+            )
+
             if !self.completeProcessing(
                 requestId: request.id,
                 success: result!.success,
                 yieldVaultId: result!.yieldVaultId,
                 message: result!.message,
-                refundAmount: request.amount,
+                refundAmount: refundAmount,
                 tokenAddress: request.tokenAddress,
                 requestType: request.requestType
             ) {
@@ -653,7 +662,9 @@ access(all) contract FlowYieldVaultsEVM {
         }
 
         /// @notice Marks a request as FAILED
-        /// @dev Calls completeProcessing to mark the request as failed with the given message
+        /// @dev Calls completeProcessing to mark the request as failed with the given message.
+        ///      Uses the same refund computation as the normal completion path to keep
+        ///      failed CREATE/DEPOSIT and failed WITHDRAW/CLOSE behavior consistent.
         /// @param request The EVM request to mark as failed
         /// @param message The error message to include in the result
         /// @return True if the request was marked as failed on EVM, false otherwise
@@ -664,12 +675,17 @@ access(all) contract FlowYieldVaultsEVM {
 
             FlowYieldVaultsEVM.emitRequestFailed(request, message: message)
 
+            let refundAmount = FlowYieldVaultsEVM.refundAmountForCompletion(
+                request: request,
+                success: false,
+            )
+
             return self.completeProcessing(
                 requestId: request.id,
                 success: false,
                 yieldVaultId: request.yieldVaultId,
                 message: message,
-                refundAmount: request.amount,
+                refundAmount: refundAmount,
                 tokenAddress: request.tokenAddress,
                 requestType: request.requestType,
             )
@@ -1007,15 +1023,17 @@ access(all) contract FlowYieldVaultsEVM {
             return nil // success
         }
 
-        /// @notice Marks a request as COMPLETED or FAILED, returning escrowed funds on failure
-        /// @dev For failed CREATE/DEPOSIT: returns funds from COA to EVM contract via msg.value (native)
-        ///      or approve+transferFrom (ERC20). ERC20 approve return data is validated when present.
-        ///      For WITHDRAW/CLOSE or success: no refund sent.
+        /// @notice Marks a request as COMPLETED or FAILED, returning any refund owed on EVM
+        /// @dev Failed CREATE/DEPOSIT requests return the full escrowed amount to the EVM requests
+        ///      contract, where it is credited to claimable refunds. Successful CREATE/DEPOSIT
+        ///      requests may return only a precision residual that Cadence could not represent
+        ///      exactly. WITHDRAW/CLOSE requests never send a refund. ERC20 approve return data
+        ///      is validated when present.
         /// @param requestId The request ID to complete
         /// @param success Whether the operation succeeded
         /// @param yieldVaultId The associated YieldVault Id
         /// @param message Status message or error reason
-        /// @param refundAmount Amount to refund (0 if no refund needed)
+        /// @param refundAmount Amount to credit to claimable refunds (0 if no refund needed)
         /// @param tokenAddress Token address for refund (used to determine native vs ERC20)
         /// @param requestType The type of request (needed to determine if refund applies)
         /// @return True if the EVM call succeeded, false otherwise
@@ -1033,13 +1051,12 @@ access(all) contract FlowYieldVaultsEVM {
             let evmYieldVaultId = yieldVaultId ?? UInt64.max
 
             let calldata = EVM.encodeABIWithSignature(
-                "completeProcessing(uint256,bool,uint64,string)",
-                [requestId, success, evmYieldVaultId, message]
+                "completeProcessing(uint256,bool,uint64,string,uint256)",
+                [requestId, success, evmYieldVaultId, message, refundAmount]
             )
 
-            // Determine if refund is needed (failed CREATE or DEPOSIT)
-            let needsRefund = !success
-                && refundAmount > 0
+            // Determine if refund is needed for CREATE/DEPOSIT lifecycle accounting
+            let needsRefund = refundAmount > 0
                 && (requestType == FlowYieldVaultsEVM.RequestType.CREATE_YIELDVAULT.rawValue
                     || requestType == FlowYieldVaultsEVM.RequestType.DEPOSIT_TO_YIELDVAULT.rawValue)
 
@@ -1050,10 +1067,9 @@ access(all) contract FlowYieldVaultsEVM {
                 let isNativeFlow = tokenAddress.toString() == FlowYieldVaultsEVM.nativeFlowEVMAddress.toString()
 
                 if isNativeFlow {
-                    // Native FLOW: send with the call
-                    // Convert UInt256 to UFix64 then to EVM.Balance
-                    let refundUFix64 = FlowYieldVaultsEVM.ufix64FromUInt256(refundAmount, tokenAddress: tokenAddress)
-                    refundValue = FlowYieldVaultsEVM.balanceFromUFix64(refundUFix64, tokenAddress: tokenAddress)
+                    // Native FLOW: send the original attoflow amount back to EVM without
+                    // round-tripping through UFix64, which would truncate sub-8-decimal precision.
+                    refundValue = EVM.Balance(attoflow: UInt(refundAmount))
                 } else {
                     // ERC20: approve contract to pull funds
                     let approveCalldata = EVM.encodeABIWithSignature(
@@ -1978,18 +1994,59 @@ access(all) contract FlowYieldVaultsEVM {
     /// @dev For native FLOW: Uses 18 decimals (attoflow to FLOW conversion)
     ///      For ERC20: Uses FlowEVMBridgeUtils to look up token decimals.
     ///      Cadence UFix64 preserves 8 decimal places, so tokens with more than 8
-    ///      decimals are truncated toward zero when entering Cadence. Any remainder
-    ///      smaller than 0.00000001 token is lost and cannot be recovered later.
+    ///      decimals are truncated toward zero when entering Cadence. For CREATE and
+    ///      DEPOSIT flows, any discarded remainder must be reconciled on the EVM side.
     /// @param value The amount in wei/smallest unit (UInt256)
     /// @param tokenAddress The token address to determine decimal conversion
-    /// @return The converted amount in UFix64 format
+    /// @return The converted amount in UFix64 format (truncated to 8 decimals)
     access(self) fun ufix64FromUInt256(_ value: UInt256, tokenAddress: EVM.EVMAddress): UFix64 {
         if tokenAddress.toString() == FlowYieldVaultsEVM.nativeFlowEVMAddress.toString() {
             return FlowEVMBridgeUtils.uint256ToUFix64(value: value, decimals: 18)
         }
         return FlowEVMBridgeUtils.convertERC20AmountToCadenceAmount(value, erc20Address: tokenAddress)
     }
 
+    /// @notice Computes the exact EVM-side amount that survives a round trip through Cadence precision
+    /// @dev This floors the amount to the nearest quantity representable by Cadence UFix64.
+    /// @param value The requested amount in wei/smallest unit
+    /// @param tokenAddress The token address to determine decimal conversion
+    /// @return The EVM-side amount that can be processed in Cadence without losing precision
+    access(self) fun exactCadenceRepresentableAmount(_ value: UInt256, tokenAddress: EVM.EVMAddress): UInt256 {
+        let cadenceAmount = FlowYieldVaultsEVM.ufix64FromUInt256(value, tokenAddress: tokenAddress)
+        return FlowYieldVaultsEVM.uint256FromUFix64(cadenceAmount, tokenAddress: tokenAddress)
+    }
+
+    /// @notice Computes the refund amount that must be returned on EVM completion
+    /// @dev Failed CREATE/DEPOSIT requests refund the full amount. Successful CREATE/DEPOSIT
+    ///      requests refund only the precision residual that could not be represented in Cadence.
+    /// @param request The request being completed
+    /// @param success Whether the Cadence operation succeeded
+    /// @return Amount to credit to claimable refunds on the Solidity side
+    access(self) fun refundAmountForCompletion(request: EVMRequest, success: Bool): UInt256 {
+        let isEscrowedRequest =
+            request.requestType == FlowYieldVaultsEVM.RequestType.CREATE_YIELDVAULT.rawValue
+            || request.requestType == FlowYieldVaultsEVM.RequestType.DEPOSIT_TO_YIELDVAULT.rawValue
+
+        if !isEscrowedRequest {
+            return 0
+        }
+
+        if !success {
+            return request.amount
+        }
+
+        let exactProcessableAmount = FlowYieldVaultsEVM.exactCadenceRepresentableAmount(
+            request.amount,
+            tokenAddress: request.tokenAddress
+        )
+
+        if request.amount > exactProcessableAmount {
+            return request.amount - exactProcessableAmount
+        }
+
+        return 0
+    }
+
     /// @notice Converts a UFix64 amount from Cadence to UInt256 for EVM
     /// @dev For native FLOW: Uses 18 decimals (FLOW to attoflow conversion)
     ///      For ERC20: Uses FlowEVMBridgeUtils to look up token decimals.