Update docs and comments

Author: shahthepro

contracts/contracts/strategies/crosschainV3/FLOWS.md

@@ -532,7 +532,7 @@ sequenceDiagram
         Master->>Master: _processWithdrawClaimAck(N+2, claimed, body)
         Note over Master: store nonceProcessed[N+2] = true<br/>store pendingWithdrawalAmount = 0<br/>store remoteStrategyBalance = yieldBaseline
         Note over Master: transfers full WETH balance from Master Strategy to L2 Vault
-    else queue not yet matured (NACK)
+    else NACK (outstandingRequestId != EMPTY / amount == 0 / bridgeAssetHeld < amount / ship out of [min,max])
         Note over Remote: currentBalance = _yieldOnlyBaseline()<br/>body = encode(currentBalance, false, 0)<br/>payload = packPayload(WITHDRAW_CLAIM_ACK, N+2, body)
         Remote->>SuperEth: sendMessage(payload)
         SuperEth->>Bridge: ccipSend{value:fee}(BASE_SELECTOR, ccipMessage)
@@ -563,7 +563,7 @@ message comes from Master's local ETH pool (`_send (userFunded=false)` uses
 leg-2 claim ack lands.
 
 For `withdrawAll` (vault or governor sweep), `_withdrawRequest` is called with
-`min(remoteStrategyBalance, inboundAdapter.maxTransferAmount())` so a sweep
+`min(_drawableRemoteBalance(), inboundAdapter.maxTransferAmount())` so a sweep
 larger than the bridge's per-tx limit lands as a partial withdrawal rather
 than reverting.
 
@@ -727,7 +727,7 @@ sequenceDiagram
         Master->>Master: _processWithdrawClaimAck(N+2, landed, body)
         Note over Master: store nonceProcessed[N+2] = true<br/>store pendingWithdrawalAmount = 0<br/>store remoteStrategyBalance = yieldBaseline
         Note over Master: transfers full USDC balance from Master Strategy to Spoke sub-OUSD Vault
-    else queue not yet matured (NACK)
+    else NACK (outstandingRequestId != EMPTY / amount == 0 / bridgeAssetHeld < amount / ship out of [min,max])
         Note over Remote: currentBalance = _yieldOnlyBaseline()<br/>body = encode(currentBalance, false, 0)<br/>payload = packPayload(WITHDRAW_CLAIM_ACK, N+2, body)
         Remote->>AdapterEth: sendMessage(payload)
         AdapterEth->>CCTP: sendMessage(message)

contracts/contracts/strategies/crosschainV3/MasterWOTokenStrategy.sol

@@ -164,11 +164,14 @@ contract MasterWOTokenStrategy is AbstractWOTokenStrategy {
     ///      must equal the vault (enforced by the require below); Master always forwards the
     ///      received bridgeAsset to `vaultAddress` on the leg-2 ack.
     ///
-    ///      Only the `remoteStrategyBalance` slice is drawable here: `_amount` must be
-    ///      `<= remoteStrategyBalance` even though `checkBalance` can report more (local
-    ///      bridgeAsset + positive bridgeAdjustment). To realise the remainder, the strategist
-    ///      can `requestSettlement()` (folding bridgeAdjustment into remoteStrategyBalance)
-    ///      and/or use the locally-held bridgeAsset, then withdraw.
+    ///      Drawable bound is `_drawableRemoteBalance()` = `remoteStrategyBalance +
+    ///      min(0, bridgeAdjustment)`, NOT `remoteStrategyBalance` alone:
+    ///        - a NEGATIVE `bridgeAdjustment` (net BRIDGE_OUT) is folded in, lowering the cap so we
+    ///          never request more shares than Remote can actually unwrap (else it NACKs on Remote);
+    ///        - a POSITIVE `bridgeAdjustment` is excluded here even though `checkBalance` counts it
+    ///          (that + local bridgeAsset can report more). To realise it, `requestSettlement()`
+    ///          first (folds bridgeAdjustment into remoteStrategyBalance) and/or use the local
+    ///          bridgeAsset, then withdraw.
     function withdraw(
         address _recipient,
         address _asset,
@@ -197,8 +200,8 @@ contract MasterWOTokenStrategy is AbstractWOTokenStrategy {
         ) {
             return;
         }
-        // Best-effort: a mid-migration cleared inbound adapter must no-op the sweep, not
-        // revert it (honors the "best-effort no-op" contract).
+        // Best-effort no-op if the inbound adapter isn't wired yet (pre-configuration only —
+        // setInboundAdapter now rejects zero, so it can't be cleared mid-migration).
         address inbound = inboundAdapter;
         if (inbound == address(0)) return;
         // remoteStrategyBalance is OToken (18dp); withdraw amounts are bridgeAsset units.

contracts/contracts/strategies/crosschainV3/RemoteWOTokenStrategy.sol

@@ -295,6 +295,8 @@ contract RemoteWOTokenStrategy is AbstractWOTokenStrategy {
         internal
     {
         uint256 amount = CrossChainV3Helper.decodeUint256(payload);
+        // Defensive / unreachable in normal flow: Master validates amount > 0 before shipping
+        // WITHDRAW_REQUEST — this only guards a malformed/forged inbound message.
         require(amount > 0, "Remote: zero withdraw");
         require(
             outstandingRequestId == REQUEST_ID_EMPTY,
@@ -635,12 +637,15 @@ contract RemoteWOTokenStrategy is AbstractWOTokenStrategy {
     ///      `oTokenAmount` is in OToken (18dp) units, matching `_viewCheckBalance`;
     ///      `_yieldOnlyBaseline()` is the `oTokenAmount == 0` case.
     /// @dev Clamps to 0 rather than reverting on a negative. `_viewCheckBalance - bridgeAdjustment`
-    ///      is principal + yield + retained fees and is never *economically* negative, but the
-    ///      wOToken ERC-4626 rounds against the strategy by ~1 wei on each BRIDGE_IN (floor) /
-    ///      BRIDGE_OUT (ceil), so once a `withdrawAll` drains this near 0 a later bridge op can push
-    ///      it a few wei negative. Reverting there would freeze the whole serialized yield channel on
-    ///      dust; clamping reports a dust-accurate 0 instead (and matches the project-wide
-    ///      checkBalance-never-reverts convention). The accumulated drift is economically nil.
+    ///      is principal + yield + retained fees and is never *economically* negative **while
+    ///      (w)OTokens are up-only** — the only thing that pushes it a few wei negative is the
+    ///      wOToken 4626 rounding against the strategy (~1 wei per BRIDGE_IN floor / BRIDGE_OUT
+    ///      ceil) once a `withdrawAll` drains it near 0. Reverting on that dust would freeze the
+    ///      serialized yield channel, so we clamp (matches checkBalance-never-reverts).
+    ///      CAVEAT: a real negative rebase (loss/slashing) would make this genuinely negative; the
+    ///      clamp then masks it, and because Master re-adds its OWN `bridgeAdjustment`,
+    ///      `checkBalance` OVER-reports by ~`bridgeAdjustment` (not 0). Out of scope while
+    ///      (w)OTokens never negative-rebase; revisit (signed baseline) if that changes. See DESIGN §3.10.
     function _yieldOnlyBaselineAfter(uint256 oTokenAmount)
         internal
         view