Pool: auto-fill provide counterpart amounts + withdraw receive preview #480

New issue

Closed

opened 2026-07-12 08:24:53 +00:00 by PlasticDigits · 9 comments

PlasticDigits commented

2026-07-12 08:24:53 +00:00

(Migrated from gitlab.com)

Summary

User feedback from mainnet Pool UX (dex.cl8y.co):

Provide liquidity — automatically fill the second token amount from the current pool price ratio when the user edits one side.
Withdraw liquidity — show an estimate of how many underlying tokens will be received for the LP amount being burned.

These are related Pool form improvements that share the same reserve math already used for Estimated LP / min_assets. Bundle them in one issue.

Related closed work: #109 added balances, Max/50%, Estimated LP, and the unbalanced-ratio warning, but did not implement counterpart auto-fill (it was listed as an optional direction). #462 added the pre-sign summary; withdraw still shows LP amount only.

Current codebase

Provide (`expanded === 'add'` in `PoolCard`)

frontend-dapp/src/pages/PoolPage.tsx — two independent inputs (amountA / amountB); Max/50% sets one side only; no lastEditedSide / linked editing.
frontend-dapp/src/utils/provideLiquidityEstimate.ts:
- estimateProvideLiquidityUserLp — mirrors on-chain LP mint.
- isProportionalAddAmounts — detects off-ratio deposits; UI shows donation warning when false.
Unbalanced deposits are still allowed: contract mints LP from min(lpA, lpB) and credits full declared amounts to reserves (excess is effectively donated to existing LPs). Warning is informational only.
Pre-submit summary (PoolPreSubmitSummary) shows typed A/B amounts.

Withdraw (`expanded === 'remove'`)

User enters LP amount + slippage presets (0.5 / 1.0 / 2.0).
withdrawMinAssetAmounts in frontend-dapp/src/utils/rawAmountMath.ts computes slippage-adjusted min_assets for the tx — not shown as a human “you receive ~X / ~Y” preview.
Pre-submit summary shows "X LP" only — no underlying token breakdown.
Optional “Receive as wrapped tokens” / auto-unwrap after tx; preview should reflect that wording.

Shared data already available

getPool / poolQuery → reserves + total_share (no new contract or indexer API required).
Pair contract has no simulate_provide / simulate_withdraw query; client-side BigInt floor math is the established pattern (same as Estimated LP).

Relevant files

Path	Role
`frontend-dapp/src/pages/PoolPage.tsx`	Provide/withdraw UI, estimates, summary wiring
`frontend-dapp/src/utils/provideLiquidityEstimate.ts`	LP mint estimate + ratio check
`frontend-dapp/src/utils/rawAmountMath.ts`	`withdrawMinAssetAmounts` (slippage mins)
`frontend-dapp/src/components/pool/PoolPreSubmitSummary.tsx`	Pre-sign amount lines (#462)
`frontend-dapp/src/components/common/AmountBalanceActions.tsx`	Max / 50% row
`frontend-dapp/src/services/terraclassic/pair.ts`	`getPool`, `provideLiquidity`, `withdrawLiquidity`
`frontend-dapp/src/utils/maxSpendableAmount.ts`	Gas-aware max on native wrap path
`packages/localnet-trading-swarm/src/liquidityGuards.ts`	Bot helper `pickScaledProvideAmounts` (reference only; not used by dApp)
`smartcontracts/contracts/pair/src/contract.rs`	On-chain provide/withdraw math to mirror
`frontend-dapp/src/pages/PoolPage.test.tsx`	Existing Pool UI tests
`frontend-dapp/src/utils/__tests__/provideLiquidityEstimate.test.ts`	LP / ratio unit tests
`frontend-dapp/src/utils/__tests__/rawAmountMath.test.ts`	Withdraw min-assets unit tests
`frontend-dapp/e2e/pool.spec.ts` / `e2e/helpers/pool-ui.ts`	Pool E2E locators

Why this is needed

Off-ratio provide is easy to miss despite the warning; users can donate excess tokens without intending to (see mainnet EMBER/CORAL screenshot: both sides filled near wallet max, not pool ratio).
Withdraw shows only LP burned; users cannot verify expected EMBER/CORAL (or other pair assets) before signing — weakens the #462 pre-sign transparency goal.
Counterpart auto-fill is standard AMM UX and was already foreshadowed in #109 but never shipped.

Constraints / guardrails

Client-side mirror only — do not add contract queries or indexer preview endpoints for this UX. Use BigInt floor division matching the pair contract.
Empty / first deposit — when both reserves are 0, there is no pool price; do not auto-fill. User sets both amounts (initial price). Keep Estimated LP / MINIMUM_LIQUIDITY behavior (#124).
Manual override — auto-fill must not trap the user; editing the counterpart after sync is allowed; show the existing donation warning when isProportionalAddAmounts === false.
Native wrap + Terra Classic tax — when “Use native (auto-wrap)” is on, derive the counterpart from net deposit amounts already used for estimates (provideRawAddA / provideRawAddB), not gross UI strings alone.
Max / 50% — after setting one side via Max/Half, auto-fill the other from pool ratio (may then exceed the other asset’s balance → keep existing insufficient-balance gates).
Withdraw preview ≠ guaranteed receive — show pro-rata expected amounts at current reserves; separately (or as secondary text) show minimum after slippage from withdrawMinAssetAmounts. Actual execution uses on-chain state at inclusion time.
Wrapped vs native receive — label preview clearly when auto-unwrap is enabled vs “Receive as wrapped tokens”.
Paused / blacklist — previews may still render; submit remains gated as today.
Do not change on-chain provide/withdraw semantics — this is UI + pure helpers only. Unbalanced provide remains possible (with warning).
LP decimals caveat — PoolPage currently hardcodes LP_DECIMALS = 6 while on-chain LP CW20 is 18 decimals (#124). Do not silently “fix” decimals as part of this issue unless required for correct preview; if touched, call it out in the MR and keep scope minimal.
No provide slippage UI in this issue (contract supports slippage_tolerance but UI passes null) — optional follow-up only.

Recommended direction

A. Provide auto-fill

Add a pure helper (prefer provideLiquidityEstimate.ts), e.g. computeProportionalCounterpartRaw(editedSide, editedRaw, pool.assets) → counterpart raw or null (empty/one-sided reserves).
In PoolCard, track last-edited side (state or ref) to avoid feedback loops.
On A change → set B from helper (when pool has both reserves); symmetric for B → A.
Wire Max/Half handlers to trigger the same sync.
Keep ratioBalanced warning for deliberate off-ratio edits.

Reference math for non-empty pool: counterpart_B = floor(amount_A × reserve_B / reserve_A) (and symmetric).

B. Withdraw estimation preview

Extract / add estimateWithdrawAssetAmounts(lp, total_share, reserveA, reserveB) = pro-rata at 0% slippage (shared core with withdrawMinAssetAmounts).
In withdraw panel, when lpAmount + poolQuery.data are present, show e.g. Estimated receive: ~X TOKEN_A + ~Y TOKEN_B (aria-live like Estimated LP).
Optionally show Minimum receive (N% slippage): … from existing helper.
Extend PoolPreSubmitSummary amountLines for withdraw to include underlying token amounts (not LP-only).

Acceptance criteria

Editing Asset A on a non-empty pool auto-fills Asset B to the current pool ratio (and vice versa).
Max / 50% on either side also updates the counterpart.
Empty pool (first deposit): no auto-fill; both fields remain independently editable.
Off-ratio after manual override still shows the existing donation warning; submit still allowed.
Native wrap path: auto-fill uses net/tax-aware amounts consistent with Estimated LP.
Withdraw panel shows estimated underlying token amounts for the entered LP burn.
Withdraw preview updates when LP amount, pool reserves, or (if shown) slippage selection changes for minimums.
Pre-submit withdraw summary includes underlying token amounts (not only LP).
Preview copy distinguishes expected vs minimum-after-slippage and wrapped vs native receive where applicable.
No contract/indexer API changes required for merge.

Test plan (all paths)

Unit

computeProportionalCounterpartRaw (or equivalent): balanced round-trip floor cases; empty pool → null; zero/invalid input → null; asymmetric reserves.
estimateWithdrawAssetAmounts: matches pro-rata floor; agrees with withdrawMinAssetAmounts(..., 0) (or shared core); tiny LP → possible zero on one side.
Existing isProportionalAddAmounts / LP estimate tests still pass with auto-filled amounts.

Component (`PoolPage.test.tsx`)

Type A → B auto-filled when pool mocked with reserves.
Type B → A auto-filled.
Empty pool: typing A does not set B.
Manual edit off-ratio → donation warning visible.
Max on A fills B (and insufficient-B messaging when applicable).
Withdraw: LP input shows estimated A/B labels with data-testids.
Withdraw pre-submit summary includes token lines.
Paused / blacklist: preview still visible; submit disabled as today.

E2E (optional smoke)

e2e/pool.spec.ts: provide panel shows synced counterpart after typing one side (LocalTerra pair with reserves).
Withdraw panel shows estimated receive line before submit (no need to broadcast for preview-only assert).

Native wrap / CW20 paths

Provide with “Use native” on one side: auto-fill still coherent with tax-adjusted estimate.
Withdraw with receive-wrapped checked vs unchecked: label/copy correct (amounts are still CW20 pro-rata before unwrap).

Test plan — attack / hack / abuse vectors

Dust / precision abuse: extremely small edited amounts → counterpart floors to 0; UI must not submit misleading “balanced” state; Estimated LP / gates handle zero.
Stale pool race: reserves change between preview and inclusion — preview is approximate; withdraw mins still protect via min_assets; document that expected ≠ guaranteed.
Max-side grief / donation: user Maxes both sides independently after disabling sync, or overrides counterpart upward — warning must remain; never silently strip excess without disclosure.
Input injection: only decimal amount regex as today; no script/HTML in preview strings (token labels from trusted registry/pair metadata).
Integer overflow / huge strings: BigInt path rejects or no-ops invalid amounts; no Number precision loss for raw math.
LP amount > balance: insufficient LP gate still blocks; preview may show theoretical receive but submit disabled.
Slippage under-estimate social engineering: ensure UI does not present slippage minimum as “you will receive exactly”; keep expected vs min wording distinct.
First-depositor price setting: no auto-fill on empty pool so an attacker cannot trick UI into implying a “correct” ratio that does not exist yet.
Paused pair / trading blacklist: cannot bypass submit gates via auto-fill or preview UI.

Verification criteria

On LocalTerra (or mainnet read-only QA): open /pool → Provide on a pair with reserves → enter one amount → counterpart matches floor(amount × reserve_other / reserve_self) within display formatting.
Estimated LP after auto-fill shows no donation warning (ratioBalanced !== false).
Deliberately break ratio → warning reappears; LP estimate still uses min side.
Withdraw: enter LP → estimated token amounts match independent calculation from pool LCD query; changing slippage updates minimum line if shown; broadcast still uses existing withdrawMinAssetAmounts.
Pre-submit summaries for both modes list the economically meaningful amounts (tokens in + tokens out).
make test-frontend (or targeted vitest files above) green; optional Playwright smoke if added.

Out of scope

Changing pair contract provide/withdraw math or adding simulation queries.
Provide-side slippage_tolerance UI.
Full LP decimals migration (6 → 18) unless required for correctness of this preview (track separately if needed).
Indexer historical liquidity-event APIs.

## Summary User feedback from mainnet Pool UX (`dex.cl8y.co`): 1. **Provide liquidity** — automatically fill the second token amount from the current pool price ratio when the user edits one side. 2. **Withdraw liquidity** — show an estimate of how many underlying tokens will be received for the LP amount being burned. These are related Pool form improvements that share the same reserve math already used for Estimated LP / `min_assets`. Bundle them in one issue. Related closed work: [#109](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/109) added balances, Max/50%, Estimated LP, and the unbalanced-ratio **warning**, but did **not** implement counterpart auto-fill (it was listed as an optional direction). [#462](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/462) added the pre-sign summary; withdraw still shows LP amount only. --- ## Current codebase ### Provide (`expanded === 'add'` in `PoolCard`) - `frontend-dapp/src/pages/PoolPage.tsx` — two **independent** inputs (`amountA` / `amountB`); Max/50% sets one side only; no `lastEditedSide` / linked editing. - `frontend-dapp/src/utils/provideLiquidityEstimate.ts`: - `estimateProvideLiquidityUserLp` — mirrors on-chain LP mint. - `isProportionalAddAmounts` — detects off-ratio deposits; UI shows donation warning when `false`. - Unbalanced deposits are still **allowed**: contract mints LP from `min(lpA, lpB)` and credits full declared amounts to reserves (excess is effectively donated to existing LPs). Warning is informational only. - Pre-submit summary (`PoolPreSubmitSummary`) shows typed A/B amounts. ### Withdraw (`expanded === 'remove'`) - User enters LP amount + slippage presets (`0.5` / `1.0` / `2.0`). - `withdrawMinAssetAmounts` in `frontend-dapp/src/utils/rawAmountMath.ts` computes slippage-adjusted `min_assets` for the tx — **not shown** as a human “you receive ~X / ~Y” preview. - Pre-submit summary shows `"X LP"` only — no underlying token breakdown. - Optional “Receive as wrapped tokens” / auto-unwrap after tx; preview should reflect that wording. ### Shared data already available - `getPool` / `poolQuery` → reserves + `total_share` (no new contract or indexer API required). - Pair contract has **no** `simulate_provide` / `simulate_withdraw` query; client-side BigInt floor math is the established pattern (same as Estimated LP). ### Relevant files | Path | Role | |------|------| | `frontend-dapp/src/pages/PoolPage.tsx` | Provide/withdraw UI, estimates, summary wiring | | `frontend-dapp/src/utils/provideLiquidityEstimate.ts` | LP mint estimate + ratio check | | `frontend-dapp/src/utils/rawAmountMath.ts` | `withdrawMinAssetAmounts` (slippage mins) | | `frontend-dapp/src/components/pool/PoolPreSubmitSummary.tsx` | Pre-sign amount lines ([#462](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/462)) | | `frontend-dapp/src/components/common/AmountBalanceActions.tsx` | Max / 50% row | | `frontend-dapp/src/services/terraclassic/pair.ts` | `getPool`, `provideLiquidity`, `withdrawLiquidity` | | `frontend-dapp/src/utils/maxSpendableAmount.ts` | Gas-aware max on native wrap path | | `packages/localnet-trading-swarm/src/liquidityGuards.ts` | Bot helper `pickScaledProvideAmounts` (reference only; not used by dApp) | | `smartcontracts/contracts/pair/src/contract.rs` | On-chain provide/withdraw math to mirror | | `frontend-dapp/src/pages/PoolPage.test.tsx` | Existing Pool UI tests | | `frontend-dapp/src/utils/__tests__/provideLiquidityEstimate.test.ts` | LP / ratio unit tests | | `frontend-dapp/src/utils/__tests__/rawAmountMath.test.ts` | Withdraw min-assets unit tests | | `frontend-dapp/e2e/pool.spec.ts` / `e2e/helpers/pool-ui.ts` | Pool E2E locators | --- ## Why this is needed - Off-ratio provide is easy to miss despite the warning; users can **donate** excess tokens without intending to (see mainnet EMBER/CORAL screenshot: both sides filled near wallet max, not pool ratio). - Withdraw shows only LP burned; users cannot verify expected EMBER/CORAL (or other pair assets) before signing — weakens the [#462](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/462) pre-sign transparency goal. - Counterpart auto-fill is standard AMM UX and was already foreshadowed in [#109](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/109) but never shipped. --- ## Constraints / guardrails 1. **Client-side mirror only** — do not add contract queries or indexer preview endpoints for this UX. Use BigInt floor division matching the pair contract. 2. **Empty / first deposit** — when both reserves are `0`, there is no pool price; **do not** auto-fill. User sets both amounts (initial price). Keep Estimated LP / `MINIMUM_LIQUIDITY` behavior ([#124](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/124)). 3. **Manual override** — auto-fill must not trap the user; editing the counterpart after sync is allowed; show the existing donation warning when `isProportionalAddAmounts === false`. 4. **Native wrap + Terra Classic tax** — when “Use native (auto-wrap)” is on, derive the counterpart from **net** deposit amounts already used for estimates (`provideRawAddA` / `provideRawAddB`), not gross UI strings alone. 5. **Max / 50%** — after setting one side via Max/Half, auto-fill the other from pool ratio (may then exceed the other asset’s balance → keep existing insufficient-balance gates). 6. **Withdraw preview ≠ guaranteed receive** — show pro-rata expected amounts at current reserves; separately (or as secondary text) show **minimum after slippage** from `withdrawMinAssetAmounts`. Actual execution uses on-chain state at inclusion time. 7. **Wrapped vs native receive** — label preview clearly when auto-unwrap is enabled vs “Receive as wrapped tokens”. 8. **Paused / blacklist** — previews may still render; submit remains gated as today. 9. **Do not change on-chain provide/withdraw semantics** — this is UI + pure helpers only. Unbalanced provide remains possible (with warning). 10. **LP decimals caveat** — `PoolPage` currently hardcodes `LP_DECIMALS = 6` while on-chain LP CW20 is **18** decimals ([#124](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/124)). Do not silently “fix” decimals as part of this issue unless required for correct preview; if touched, call it out in the MR and keep scope minimal. 11. **No provide slippage UI** in this issue (contract supports `slippage_tolerance` but UI passes `null`) — optional follow-up only. --- ## Recommended direction ### A. Provide auto-fill 1. Add a pure helper (prefer `provideLiquidityEstimate.ts`), e.g. `computeProportionalCounterpartRaw(editedSide, editedRaw, pool.assets)` → counterpart raw or `null` (empty/one-sided reserves). 2. In `PoolCard`, track last-edited side (state or ref) to avoid feedback loops. 3. On A change → set B from helper (when pool has both reserves); symmetric for B → A. 4. Wire Max/Half handlers to trigger the same sync. 5. Keep `ratioBalanced` warning for deliberate off-ratio edits. Reference math for non-empty pool: `counterpart_B = floor(amount_A × reserve_B / reserve_A)` (and symmetric). ### B. Withdraw estimation preview 1. Extract / add `estimateWithdrawAssetAmounts(lp, total_share, reserveA, reserveB)` = pro-rata at **0% slippage** (shared core with `withdrawMinAssetAmounts`). 2. In withdraw panel, when `lpAmount` + `poolQuery.data` are present, show e.g. `Estimated receive: ~X TOKEN_A + ~Y TOKEN_B` (`aria-live` like Estimated LP). 3. Optionally show `Minimum receive (N% slippage): …` from existing helper. 4. Extend `PoolPreSubmitSummary` `amountLines` for withdraw to include underlying token amounts (not LP-only). --- ## Acceptance criteria - [ ] Editing Asset A on a non-empty pool auto-fills Asset B to the current pool ratio (and vice versa). - [ ] Max / 50% on either side also updates the counterpart. - [ ] Empty pool (first deposit): no auto-fill; both fields remain independently editable. - [ ] Off-ratio after manual override still shows the existing donation warning; submit still allowed. - [ ] Native wrap path: auto-fill uses net/tax-aware amounts consistent with Estimated LP. - [ ] Withdraw panel shows estimated underlying token amounts for the entered LP burn. - [ ] Withdraw preview updates when LP amount, pool reserves, or (if shown) slippage selection changes for minimums. - [ ] Pre-submit withdraw summary includes underlying token amounts (not only LP). - [ ] Preview copy distinguishes expected vs minimum-after-slippage and wrapped vs native receive where applicable. - [ ] No contract/indexer API changes required for merge. --- ## Test plan (all paths) ### Unit - [ ] `computeProportionalCounterpartRaw` (or equivalent): balanced round-trip floor cases; empty pool → `null`; zero/invalid input → `null`; asymmetric reserves. - [ ] `estimateWithdrawAssetAmounts`: matches pro-rata floor; agrees with `withdrawMinAssetAmounts(..., 0)` (or shared core); tiny LP → possible zero on one side. - [ ] Existing `isProportionalAddAmounts` / LP estimate tests still pass with auto-filled amounts. ### Component (`PoolPage.test.tsx`) - [ ] Type A → B auto-filled when pool mocked with reserves. - [ ] Type B → A auto-filled. - [ ] Empty pool: typing A does not set B. - [ ] Manual edit off-ratio → donation warning visible. - [ ] Max on A fills B (and insufficient-B messaging when applicable). - [ ] Withdraw: LP input shows estimated A/B labels with `data-testid`s. - [ ] Withdraw pre-submit summary includes token lines. - [ ] Paused / blacklist: preview still visible; submit disabled as today. ### E2E (optional smoke) - [ ] `e2e/pool.spec.ts`: provide panel shows synced counterpart after typing one side (LocalTerra pair with reserves). - [ ] Withdraw panel shows estimated receive line before submit (no need to broadcast for preview-only assert). ### Native wrap / CW20 paths - [ ] Provide with “Use native” on one side: auto-fill still coherent with tax-adjusted estimate. - [ ] Withdraw with receive-wrapped checked vs unchecked: label/copy correct (amounts are still CW20 pro-rata before unwrap). --- ## Test plan — attack / hack / abuse vectors - [ ] **Dust / precision abuse**: extremely small edited amounts → counterpart floors to `0`; UI must not submit misleading “balanced” state; Estimated LP / gates handle zero. - [ ] **Stale pool race**: reserves change between preview and inclusion — preview is approximate; withdraw mins still protect via `min_assets`; document that expected ≠ guaranteed. - [ ] **Max-side grief / donation**: user Maxes both sides independently after disabling sync, or overrides counterpart upward — warning must remain; never silently strip excess without disclosure. - [ ] **Input injection**: only decimal amount regex as today; no script/HTML in preview strings (token labels from trusted registry/pair metadata). - [ ] **Integer overflow / huge strings**: BigInt path rejects or no-ops invalid amounts; no `Number` precision loss for raw math. - [ ] **LP amount > balance**: insufficient LP gate still blocks; preview may show theoretical receive but submit disabled. - [ ] **Slippage under-estimate social engineering**: ensure UI does not present slippage minimum as “you will receive exactly”; keep expected vs min wording distinct. - [ ] **First-depositor price setting**: no auto-fill on empty pool so an attacker cannot trick UI into implying a “correct” ratio that does not exist yet. - [ ] **Paused pair / trading blacklist**: cannot bypass submit gates via auto-fill or preview UI. --- ## Verification criteria 1. On LocalTerra (or mainnet read-only QA): open `/pool` → Provide on a pair with reserves → enter one amount → counterpart matches `floor(amount × reserve_other / reserve_self)` within display formatting. 2. Estimated LP after auto-fill shows no donation warning (`ratioBalanced !== false`). 3. Deliberately break ratio → warning reappears; LP estimate still uses `min` side. 4. Withdraw: enter LP → estimated token amounts match independent calculation from `pool` LCD query; changing slippage updates minimum line if shown; broadcast still uses existing `withdrawMinAssetAmounts`. 5. Pre-submit summaries for both modes list the economically meaningful amounts (tokens in + tokens out). 6. `make test-frontend` (or targeted vitest files above) green; optional Playwright smoke if added. --- ## Out of scope - Changing pair contract provide/withdraw math or adding simulation queries. - Provide-side `slippage_tolerance` UI. - Full LP decimals migration (`6` → `18`) unless required for correctness of this preview (track separately if needed). - Indexer historical liquidity-event APIs.

PlasticDigits commented

2026-07-12 08:24:54 +00:00

(Migrated from gitlab.com)

marked as related to #109