Wayfinder: New Position pool status and preview model

[3esmit]

Question

What state model should represent pool status, reserves, existing-position balances, deposit inputs, and LP preview for Issue 30?

Answer should cover:

• active pool vs missing pool vs invalid/inactive/unreadable pool
• current-main active definition (PoolDefinition.liquidity_pool_supply, reserves, account existence)
• AddLiquidity ratio-lock math and min LP from slippage
• NewDefinition independent amount entry, initial LP calculation, MINIMUM_LIQUIDITY, and invalid low-liquidity cases
• fee-tier selection and unsupported fee rejection
• account preview rows for created/updated accounts

[3esmit]

Resolved grilling input: pool status is Missing Pool, Active Pool, or Unavailable Pool. Active Pool uses ratio-locked deposits and previews actual token amounts plus LP minted. Missing Pool uses initial price first, computes minimum initial deposit that satisfies the AMM minimum-liquidity lock, then lets both deposits scale together. Preview must show LP minted, token amounts spent, fee tier, account changes, and include config/current tick/clock where relevant.

[3esmit]

Research conclusion for pool status + preview model:

• Use statuses: Missing Pool, Active Pool, Unavailable Pool.
• Missing Pool = derived pool PDA account is Account::default().
• Active Pool = existing AMM-owned account decodes as the selected pair's PoolDefinition, has supported fee, LP supply >= MINIMUM_LIQUIDITY, nonzero reserves, matching vault/LP/current-tick ids, and vault balances at least reserves.
• Unavailable Pool = any existing malformed/wrong-owner/wrong-pair/wrong-vault/unsupported-fee/zero-reserve/below-minimum/underfunded-vault state.

Current-main detail: PoolDefinition has no active flag. Although comments say zero supply means uninitialized, new_definition currently requires the pool account to be exactly default. So a decoded zero-supply pool account should be treated as Unavailable unless program behavior changes.

Active Pool quote must mirror AddLiquidity integer math:

ideal_a = floor(reserve_a * max_b / reserve_b)
ideal_b = floor(reserve_b * max_a / reserve_a)
actual_a = min(ideal_a, max_a)
actual_b = min(ideal_b, max_b)
expected_lp = min(
  floor(supply * actual_a / reserve_a),
  floor(supply * actual_b / reserve_b)
)
min_lp = floor(expected_lp * (10_000 - slippage_bps) / 10_000)

Reject quote if actual amounts or LP are zero. min_lp must be nonzero because the guest converts it to NonZeroU128.

Missing Pool quote must mirror NewDefinition:

initial_lp = floor(sqrt(amount_a * amount_b))
require initial_lp > MINIMUM_LIQUIDITY (1_000)
user_lp = initial_lp - 1_000
locked_lp = 1_000

Use price-first flow: backend computes minimum raw pair at selected initial price satisfying initial_lp > 1_000, then lets user scale both amounts together.

Account preview must use current account order, not old 7-account issue text:

• NewDefinition: config, pool, vault A, vault B, LP definition, LP-lock holding, user holding A, user holding B, user LP holding, current tick, clock.
• AddLiquidity: config, pool, vault A, vault B, LP definition, user holding A, user holding B, user LP holding, current tick, clock.

Existing QML dummy math uses floating point/Number and should not be reused for production raw u128 quotes.

[3esmit]

Resolved in PR #210 by commit 7f88fd0. The production model classifies missing, active, inactive, and unavailable pools from fresh account reads; performs exact raw u128 opening and ratio-constrained liquidity math; validates fee tiers and minimum liquidity; reports funding errors without blocking simulation; and returns deterministic LP and account previews.