fix: any token a swap leaves in the router keeps it from reading as received (closes #606)

The decoder checked only the swap's output for being left in the router.
It now records every token a step pays the router, the WETH of a
WRAP_ETH and the rest of a V4 SETTLE taken to the router among them, and
any token still there after the last step gets a Paid to line naming it,
so the minimum reads Min. paid out. Steps that spend all the router holds
of a token count as spending it, and so do swap steps from the router
that together spend what a WRAP_ETH stated, when the router held no WETH
before it. A SETTLE of OPEN_DELTA from the router counts only in the
plain shape of Uniswap's own routes.

Model: opus-5-5

README.md

@@ -2361,7 +2361,7 @@ view would leave a wallet one click from deletion.
       transaction"
     - Decoded action (if calldata is recognized): action name, token details,
       amounts, steps, deadline, and unless a swap pays only the From address, a
-      `Paid to` line for each other address it pays, or saying that its output
+      `Paid to` line for each other address it pays, or saying that a token
       stays in the router or who it pays is unknown (see Transaction Decoding)
     - From: color dot + full address + etherscan link
     - Contract: color dot + full address + etherscan link, token symbol label if
@@ -3054,49 +3054,72 @@ Currently supported:
   such as one whose owner word has a nonzero top byte (the router reads the
   owner from the word's last 20 bytes), likewise sets neither, and it is listed
   as `Balance Check (could not be decoded)`. When a swap step, `TAKE` or
-  `TAKE_PORTION` pays the router the swap's output token, the output stays in
-  the router unless a later step pays all the router holds of it to anyone but
-  the router: a `SWEEP` of that token, an `UNWRAP_WETH` when it is WETH, a
-  `TRANSFER` of `CONTRACT_BALANCE`, a `PAY_PORTION` of 10,000 bips or a
-  `PAY_PORTION_FULL_PRECISION` of 1e18 of that token, or an
-  `ACROSS_V4_DEPOSIT_V3` of `CONTRACT_BALANCE` of that token, or of ETH when it
-  sets `useNative`. The router sends ETH as written, so a `TRANSFER` of
-  `CONTRACT_BALANCE` of ETH always reverts and pays out nothing. A step paying a
-  token to the V2 pair that the very next step spends, as a V2 exact-in of that
-  token whose `amountIn` is `ALREADY_PAID` (zero) or `CONTRACT_BALANCE`, is a
-  hop, not a payout: Uniswap's mixed routes pay the next V2 pair directly, and
-  the router enforces that swap's own minimum. The decoder checks that the
-  address paid is that pair, deriving it from the V2 factory and pair init code
-  hash the network's routers were deployed with and the first two tokens of that
-  step's path; a payment to any other address is named. (Sepolia's
-  `UniversalRouterV1_2_V2Support` was deployed with placeholders for both
-  values, so no V2 swap step can succeed on that router.) Every other payment
-  counts, in whichever step and of whatever token, a share of the output
-  included: an interface fee paid to another address by `PAY_PORTION`,
-  `TRANSFER` or `TAKE_PORTION` is named, and the minimum reads `Min. paid out`,
-  because the swap's minimum includes the fee. The minimum reads `Min. received`
-  only when some step pays the transaction's sender (the From address on
-  TxApproval, the sender the explorer reports on TransactionDetail) and no
-  `Paid to` line is shown. `Paid to` lines after `Token Out` name each other
-  address paid; one reads
+  `TAKE_PORTION` pays the router any token, the swap's output or another, a
+  `WRAP_ETH` pays it WETH, or an `UNWRAP_WETH` into the router turns WETH a step
+  paid it into ETH, that token stays in the router unless a later step pays out
+  or spends all the router holds of it: a `SWEEP` of that token to anyone but
+  the router, an `UNWRAP_WETH` when it is WETH, a `WRAP_ETH` of
+  `CONTRACT_BALANCE` when it is ETH, a `TRANSFER` of `CONTRACT_BALANCE`, a
+  `PAY_PORTION` of 10,000 bips or a `PAY_PORTION_FULL_PRECISION` of 1e18 of that
+  token to anyone but the router, an `ACROSS_V4_DEPOSIT_V3` of
+  `CONTRACT_BALANCE` of that token, or of ETH when it sets `useNative`, or a V2
+  or V3 exact-in swap step or V4 `SETTLE` that pays `CONTRACT_BALANCE` of that
+  token from the router (`payerIsUser` false). V2 and V3 exact-in swap steps and
+  V4 `SETTLE`s that pay WETH from the router also spend all the WETH a
+  `WRAP_ETH` paid it once together they spend the amount the `WRAP_ETH` states,
+  as a swap paid in ETH does, but only when that amount is not
+  `CONTRACT_BALANCE` and the router held no WETH from an earlier step when the
+  `WRAP_ETH` ran: after two `WRAP_ETH`s of 0.5 ETH into the router, a swap of 1
+  WETH from it reads as leaving the WETH there. The router pays a `SETTLE` of
+  `OPEN_DELTA` (zero) only what its step still owes of that token when the
+  `SETTLE` runs, so one from the router counts as spending the amounts the
+  step's swap actions state they spend of that token only when every action in
+  the step could be read, every swap action names the token it spends and the
+  token it buys (a swap action with an empty path swaps nothing), the `SETTLE`
+  is the step's only `SETTLE` or `SETTLE_ALL` of that token and comes after
+  every swap action, no swap action buys that token, and the swap actions that
+  spend it state a quantity together; otherwise it counts as spending nothing.
+  So the rest of a V4 `SETTLE` of more than its swap spends, taken to the
+  router, the WETH of a `WRAP_ETH`, and a token a swap pays the router on the
+  way to the output, each stays in the router when later steps do not spend all
+  of it, where anyone can take it in a later transaction. The router sends ETH
+  as written, so a `TRANSFER` of `CONTRACT_BALANCE` of ETH always reverts and
+  pays out nothing. A step paying a token to the V2 pair that the very next step
+  spends, as a V2 exact-in of that token whose `amountIn` is `ALREADY_PAID`
+  (zero) or `CONTRACT_BALANCE`, is a hop, not a payout: Uniswap's mixed routes
+  pay the next V2 pair directly, and the router enforces that swap's own
+  minimum. The decoder checks that the address paid is that pair, deriving it
+  from the V2 factory and pair init code hash the network's routers were
+  deployed with and the first two tokens of that step's path; a payment to any
+  other address is named. (Sepolia's `UniversalRouterV1_2_V2Support` was
+  deployed with placeholders for both values, so no V2 swap step can succeed on
+  that router.) Every other payment counts, in whichever step and of whatever
+  token, a share of the output included: an interface fee paid to another
+  address by `PAY_PORTION`, `TRANSFER` or `TAKE_PORTION` is named, and the
+  minimum reads `Min. paid out`, because the swap's minimum includes the fee.
+  The minimum reads `Min. received` only when some step pays the transaction's
+  sender (the From address on TxApproval, the sender the explorer reports on
+  TransactionDetail) and no `Paid to` line is shown. `Paid to` lines after
+  `Token Out` name each other address paid; one reads
   `The bridge, which pays the deposit's recipient on another network` for a
   bridge deposit; one reads, for example,
   `The router, 2000.0000 USDT from the sender (later steps may not spend all of it)`
   for each move into the router, followed by a `Token moved into the router`
   line that gives the moved token's address as the `Token In` line does; one
-  reads `The router, where it stays (no later step pays it out)` when the output
-  stays in the router; and one more reads `Unknown (could not be decoded)` when
-  a step that may pay an address went unread. When no step pays anyone, a single
-  line reads `Unknown (not named in the calldata)`. Wherever there is a
-  `Paid to` line, the minimum reads `Min. paid out`. A step goes unread when its
-  recipient does not decode as an address, or when it is a command the decoder
-  does not read: every command other than `PERMIT2_PERMIT`,
-  `PERMIT2_TRANSFER_FROM`, `V2_SWAP_EXACT_IN`, `V2_SWAP_EXACT_OUT`,
-  `V3_SWAP_EXACT_IN`, `V4_SWAP`, `SWEEP`, `TRANSFER`, `PAY_PORTION`,
-  `PAY_PORTION_FULL_PRECISION`, `ACROSS_V4_DEPOSIT_V3`, `WRAP_ETH`,
-  `UNWRAP_WETH` and `BALANCE_CHECK_ERC20` (`V3_SWAP_EXACT_OUT`,
-  `PERMIT2_TRANSFER_FROM_BATCH`, `EXECUTE_SUB_PLAN` and the NFT commands among
-  them), or a type its release names no command for.
+  reads `The router, where it stays (no later step pays it out)` for each token
+  that stays in the router, followed, for any token but the output, by a
+  `Token moved into the router` line giving that token in the same way (ETH by
+  name); and one more reads `Unknown (could not be decoded)` when a step that
+  may pay an address went unread. When no step pays anyone, a single line reads
+  `Unknown (not named in the calldata)`. Wherever there is a `Paid to` line, the
+  minimum reads `Min. paid out`. A step goes unread when its recipient does not
+  decode as an address, or when it is a command the decoder does not read: every
+  command other than `PERMIT2_PERMIT`, `PERMIT2_TRANSFER_FROM`,
+  `V2_SWAP_EXACT_IN`, `V2_SWAP_EXACT_OUT`, `V3_SWAP_EXACT_IN`, `V4_SWAP`,
+  `SWEEP`, `TRANSFER`, `PAY_PORTION`, `PAY_PORTION_FULL_PRECISION`,
+  `ACROSS_V4_DEPOSIT_V3`, `WRAP_ETH`, `UNWRAP_WETH` and `BALANCE_CHECK_ERC20`
+  (`V3_SWAP_EXACT_OUT`, `PERMIT2_TRANSFER_FROM_BATCH`, `EXECUTE_SUB_PLAN` and
+  the NFT commands among them), or a type its release names no command for.
 
 ### Non-Goals Forever