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

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 {
 
     // ============================================
@@ -573,7 +579,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 {
@@ -620,14 +626,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
             ) {
@@ -651,7 +660,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
@@ -662,12 +673,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,
             )
@@ -1005,14 +1021,15 @@ 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). 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.
+        ///      Successful CREATE/DEPOSIT requests may return a precision residual that could not
+        ///      be represented in Cadence. WITHDRAW/CLOSE requests never send a refund.
         /// @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 refund 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
@@ -1030,13 +1047,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)
 
@@ -1047,10 +1063,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(
@@ -1929,16 +1944,59 @@ access(all) contract FlowYieldVaultsEVM {
     /// @notice Converts a UInt256 amount from EVM to UFix64 for Cadence
     /// @dev For native FLOW: Uses 18 decimals (attoflow to FLOW conversion)
     ///      For ERC20: Uses FlowEVMBridgeUtils to look up token decimals
+    ///      PRECISION WARNING: UFix64 has only 8 decimal places vs uint256's 18.
+    ///      Precision beyond 8 decimals is truncated and 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

cadence/contracts/FlowYieldVaultsEVMWorkerOps.cdc

@@ -146,10 +146,10 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
         nextRunCapacity: UInt8?,
     )
 
-    /// @notice Emitted when a WorkerHandler has panicked and SchedulerHandler has marked the request as FAILED
+    /// @notice Emitted when SchedulerHandler detects a failed WorkerHandler execution
     /// @param status The status of the transaction (Unknown, Scheduled, Executed, Canceled)
-    /// @param markedAsFailed Whether the request was marked as FAILED
-    /// @param request The request that was marked as FAILED
+    /// @param markedAsFailed Whether the request was successfully marked as FAILED on EVM
+    /// @param request The tracked request being recovered
     access(all) event WorkerHandlerPanicDetected(
         status: UInt8?,
         markedAsFailed: Bool,
@@ -171,6 +171,7 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
     )
 
     /// @notice Emitted when stopAll() cannot mark a cancelled request as FAILED
+    /// @dev The request remains tracked in scheduledRequests so a later recovery attempt can retry finalization.
     /// @param requestId EVM request ID that could not be marked as FAILED
     /// @param workerTransactionId Cancelled WorkerHandler transaction ID
     access(all) event StopAllMarkFailedSkipped(
@@ -332,6 +333,7 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
                         requestId: scheduledRequestId,
                         workerTransactionId: request.workerTransactionId,
                     )
+                    continue
                 }
 
                 FlowYieldVaultsEVMWorkerOps.scheduledRequests.remove(key: scheduledRequestId)
@@ -583,7 +585,8 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
         /// @notice Main scheduler logic
         /// @dev Flow:
         ///      1. Check for failed worker requests
-        ///         - If a failure is identified, mark the request as failed and remove it from scheduledRequests
+        ///         - If a failure is identified, attempt to mark the request as FAILED
+        ///         - Remove it from scheduledRequests only after EVM finalization succeeds
         ///      2. If fetchCount > 0, fetch pending requests from EVM
         ///      3. Preprocess requests to drop invalid requests
         ///      4. Start processing requests (PENDING -> PROCESSING)
@@ -631,7 +634,7 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
         ///         - Only acceptable transaction status is Scheduled (pending execution)
         ///         - No status is considered not acceptable because it means the manager cleaned up the request
         ///      4. If the transaction status is invalid, mark the request as FAILED providing the transaction ID
-        ///      5. Remove the request from scheduledRequests
+        ///      5. Remove the request from scheduledRequests only after it has been marked as FAILED on EVM
         /// @param manager The scheduler manager
         /// @param worker The worker capability
         access(self) fun _checkForFailedWorkerRequests(
@@ -669,9 +672,10 @@ access(all) contract FlowYieldVaultsEVMWorkerOps {
                         message: "Worker transaction did not execute successfully. Transaction ID: \(txId.toString())",
                     )
 
-                    // Remove request from scheduledRequests
-                    // Success is not checked because errors are not considered transient
-                    FlowYieldVaultsEVMWorkerOps.scheduledRequests.remove(key: requestId)
+                    // Keep the request tracked if EVM finalization fails so crash recovery can retry later.
+                    if success {
+                        FlowYieldVaultsEVMWorkerOps.scheduledRequests.remove(key: requestId)
+                    }
 
                     emit WorkerHandlerPanicDetected(
                         status: txStatus?.rawValue,

cadence/tests/transactions/scheduler/run_scheduler_with_capacity.cdc

@@ -0,0 +1,24 @@
+import "FlowTransactionScheduler"
+import "FlowYieldVaultsEVMWorkerOps"
+
+/// @title Run Scheduler Manually With Capacity
+/// @notice Runs the scheduler manually with an explicit run capacity
+/// @dev Test-only helper for forcing preprocessing/scheduling without waiting for recurrent runs
+/// @param runCapacity The number of pending requests this manual run is allowed to preprocess
+transaction(runCapacity: UInt8) {
+    let schedulerHandlerCap: Capability<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}>
+
+    prepare(signer: auth(IssueStorageCapabilityController) &Account) {
+        self.schedulerHandlerCap = signer.capabilities.storage
+            .issue<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}>(
+                FlowYieldVaultsEVMWorkerOps.SchedulerHandlerStoragePath
+            )
+    }
+
+    execute {
+        self.schedulerHandlerCap.borrow()!.executeTransaction(
+            id: 42,
+            data: runCapacity
+        )
+    }
+}

deployments/artifacts/FlowYieldVaultsRequests.json

@@ -315,6 +315,11 @@
         "name": "message",
         "type": "string",
         "internalType": "string"
+      },
+      {
+        "name": "refundAmount",
+        "type": "uint256",
+        "internalType": "uint256"
       }
     ],
     "outputs": [],
@@ -1998,6 +2003,22 @@
     "name": "InvalidCOAAddress",
     "inputs": []
   },
+  {
+    "type": "error",
+    "name": "InvalidRefundAmount",
+    "inputs": [
+      {
+        "name": "expectedOrMaximum",
+        "type": "uint256",
+        "internalType": "uint256"
+      },
+      {
+        "name": "actual",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ]
+  },
   {
     "type": "error",
     "name": "InvalidRequestState",