s4 improve uniswapv3 swap precision

[mts1715]

Closes #114

Summary

• Add swapExactOut interface method to DeFiActions.Swapper — introduces exact output swap functionality where users specify the desired output amount and receive any unconsumed input tokens back. Returns a fixed-length array [outVault, leftoverInVault] for predictable handling.
• Implement swapExactOut in UniswapV3SwapConnectors.Swapper — adds _swapExactOut which calls the Uniswap V3 exactOutput router function, returning both the output vault and unused input tokens. Handles reversed path encoding, 3x bridge fees (deposit input + withdraw output + withdraw leftover), and floors leftover amounts to token quantum to avoid bridge rounding errors.
• Update all Swapper implementations for interface conformance:
• • Full support: MultiSwapper (routes to optimal inner swapper), MockSwapper (test implementation)
• • Graceful panic with clear messages: SequentialSwapper, ERC4626SwapConnectors, UniswapV2SwapConnectors, IncrementFiSwapConnectors, IncrementFiPoolLiquidityConnectors.Zapper (not feasible for these swap types)
• Add exactIn and exactOut swap transactions — both transactions set up the output token vault on the signer's account (via FTVaultData) if it doesn't already exist, and deposit swapped tokens instead of destroying them.
• Add fork tests with balance verification — tests run against real FlowSwap V3 on forked mainnet and assert that FLOW is spent and USDC is received after each swap. Includes getFlowBalance and getTokenBalance helpers, plus a new get_balance_by_type.cdc script that resolves vault paths from type identifiers.
• Register EVMAbiHelpers and UniswapV3SwapConnectors mainnet aliases in flow.json

Tests

• testSwapExactInputAgainstFlowSwapV3 — swaps 0.1 FLOW for USDC, verifies FLOW spent >= 0.1 and USDC received > 0
• testSwapExactOutputAgainstFlowSwapV3 — requests 0.001 USDC with max 10 FLOW, verifies FLOW spent <= 10 and USDC received >= 0.001

[jribbink]

It's best that we pin to block heights for determinism in the fork tests (and CI speed/caching advantages that will come a future release)

[jribbink]

Should this be moved to the section with the "helpers" below?
https://github.com/onflow/FlowActions/pull/127/changes#diff-d2b4391d7a409bed31ef788dc70777ad1419c96cee49add229a971a5bd0cc51eR711

[mts1715]

_swapExactOut, _swapExactIn are core swap implementation functions, not a utility helpers.

The helpers section below contains smaller utility functions (like _dryCall, _toCadenceOut, borrowCOA) that support these core implementations and work with members of struct Swapper

[jribbink]

Is it necessary to add a new public function to only the UniswapV3SwapConnectors, outside of the generic Swapper interface conformance?

My understanding was that this could be implemented as part of the {Quote} returned by quoteOut (and/or quoteIn). If we’re able to make a breaking change, the cleanest option would probably be to add a mode (in/out) field to SwapConnectors.BasicQuote

If we can’t, we could keep BasicQuote as-is and introduce another struct, like ModeQuote, which carries this modality, then have swappers interpret it via casting.

e.g. Within the SwapConnectors contract, something like:

access(all) enum SwapMode {
    access(all) case IN
    access(all) case OUT
}

access(all) struct ModeQuote: Quote {
    access(all) let mode: SwapMode
    // ... rest
}

And then within the UniswapV3SwapConnectors contract, something like:

access(all) fun normalizeQuote(quote: {DeFiActions.Quote}): SwapConnectors.ModeQuote {
    if let mq = quote as? SwapConnectors.ModeQuote {
        return mq
    }
    return SwapConnectors.ModeQuote(
        mode: SwapMode.IN,
        // ... rest of quote
    )
}

@nialexsan, maybe you have some more context on the original design philosophy here?

[mts1715]

To simplify and reduce possible errors in using these methods, I proposed two separate interfaces: swap and swapExactOut, because it's better to have two separate methods with different functionality than one method with functionality that depends on some input flags.
Also, UniswapV3 has two separate methods: swapExactInputSingle and swapExactOutputSingle;
and even FungibleToken has: withdraw(amount: UFix64) and withdrawAvailable(maxAmount: UFix64).

[jribbink]

My primary concern is that by deviating from the {Swapper} interface, systems interacting with the swapper will still experience the exact same precision loss that this PR intends to solve, unless they explicitly couple their code to the UniswapV3Connectors conrete implementation (undesirable), as swapExactOutput is not a part of the {Swapper} interface.

i.e. generally speaking a dev trying to swap for an exact output tokens would do the following

let swapper: {Swapper} = ...
swapper.swap(swapper.quoteOut(...), <-tokens)

And this PR would not solve this issue. By conforming to a generic interface & respecting the existing code path, we allow all future {Swapper} implementations to provide this same functionality without changes to the downstream call sites.

[mts1715]

The fundamental issue is that the current Swapper interface:

access(all) fun swap(quote: {Quote}?, inVault: @{FungibleToken.Vault}): @{FungibleToken.Vault}

...cannot support swapExactOut because it needs to return BOTH the output vault AND the remaining/unused input tokens.

To properly solve this at the interface level (so all swappers benefit, not just UniswapV3), we need to change the signature to:

access(all) fun swap(quote: {Quote}?, inVault: @{FungibleToken.Vault}): @[{FungibleToken.Vault}]

Where [0] is the output vault and [1] is leftover input (empty vault for exactInput swaps).

@jribbink @nialexsan

[nialexsan]

I think it makes sense to add swapExactOutput to the interface and treat swap as swapExactIn, since it wouldn't require to return residual in token from the swap

[mts1715]

done