Add script for monitoring pools

[AndriiDiachuk]

Summary

Adds get_pool_execution_health.cdc a Cadence script used by fcm-observer to periodically monitor execution health of FlowSwap V3 pools used by ALP and FYV.

The script simulates swap execution via the QuoterV2 contract and measures price impact in both directions at a configurable canonical trade size. This is more reliable than raw token balances for V3 concentrated-liquidity pools.

For each pool the script:

1. Resolves the pool address from the factory
2. Checks pool.liquidity() for in-range liquidity
3. Quotes a small probe trade (~$10) and a canonical trade ($1000 by default) in both directions (tokenA -> tokenB and tokenB -> tokenA)
4. Computes price impact between probe and canonical quote
5. Marks the pool healthyForExecution when both directions quote successfully and both impacts are within maxImpactBps

The existing get_pool_liquidity.cdc is kept — it remains valid for V2 reserve-style pools where raw balances are a reliable liquidity signal.

Sample input

factoryHex:        "0xca6d7Bb03334bBf135902e1d919a5feccb461632"
quoterHex:         "0x370A8DF17742867a44e56223EC20D82092242C85"
poolNames:         ["moet_pyusd0"]
tokenAAddrs:       ["0x213979bb8a9a86966999b3aa797c1fcf3b967ae2"]
tokenANames:       ["MOET"]
tokenBAddrs:       ["0x99aF3EeA856556646C98c8B9b2548Fe815240750"]
tokenBNames:       ["PYUSD0"]
fees:              [100]
tokenAUsdPrices:   [1.0]
tokenBUsdPrices:   [1.0]
canonicalTradeUsd: 1000.0
maxImpactBps:      100.0

[vishalchangrani]

@AndriiDiachuk can you please post sample input and output of the script?

[AndriiDiachuk]

@AndriiDiachuk can you please post sample input and output of the script?
@vishalchangrani

Input:

factoryHex:  "0xcB3da766122DD0F25C1c7Fe9B0Ad59Ce1cfE462B"

poolNames:   ["moet_pyusd0",                               "weth_wbtc"]
tokenAAddrs: ["0xB3F6C6C7b1b4F53E1c5B7F4d9F8A2e1C6D3b9A2e", "0xA1b2C3d4E5f6A7b8C9d0E1f2A3b4C5d6E7f8A9b0"]
tokenANames: ["MOET",                                      "WETH"]
tokenBAddrs: ["0xD4e5F6a7B8c9D0e1F2a3B4c5D6e7F8a9B0c1D2e3", "0xC2d3E4f5A6b7C8d9E0f1A2b3C4d5E6f7A8b9C0d1"]
tokenBNames: ["PYUSD0",                                    "WBTC"]
fees:        [100,                                         3000]

Output:

[
  PoolStatus(
    pool:         "moet_pyusd0",
    tokenA:       "MOET",
    balanceA:     19.89200582,    // MOET held by pool contract
    tokenB:       "PYUSD0",
    balanceB:     30022.35759300, // PYUSD0 held by pool contract
    hasLiquidity: true
  ),
  PoolStatus(
    pool:         "weth_wbtc",
    tokenA:       "WETH",
    balanceA:     0.0,            // pool exists but no in-range liquidity
    tokenB:       "WBTC",
    balanceB:     0.0,
    hasLiquidity: false
  )
]

The second entry covers both the "pool has no in-range liquidity" and "factory call failed" cases. both return the same shape with zero balances and hasLiquidity: false, so the metric is always present in Prometheus regardless of pool state.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AndriiDiachuk]

@liobrasil can you please review it once more and approve if everything is fine now?