feat: retail how-to for providing LUNC liquidity (v2 LP + maker limits)

PlasticDigits commented

2026-08-16 07:14:02 +00:00

(Migrated from gitlab.com)

Summary

Retail users on dex.cl8y.com cannot figure out how to provide LUNC liquidity. Support already answered the product facts; the dApp does not.

“I can provide liquidity of lunc for some period, I want to know how it works?”
“Yes you can provide and withdraw v2 lp, or place limit orders. Theres no incentive program currently”
“Has it been written here before how to do this? Or can you write to me briefly… Thanks. I cant figure out how to do it on dex.cl8y.com”

Bundle one retail how-to surface for both ways people hear “provide LUNC liquidity”:

v2 AMM LP — /pool provide + withdraw (native LUNC auto-wrap or wrap-then-deposit).
Maker limits — /trade or /limits (escrow is not pool LP; no farming UI).

Do not split “write a GitLab doc” vs “add a Pool hint” vs “explain wrap” vs “explain two-sided deposit” vs “distinguish limit maker” into separate issues. Do not add a rewards/farming program.

Related: #147 (CW20 add-LP three fees), #213 (native wrap + provide), #366 (IL notice), #417 (onboarding strip is Swap/Trade/Limits only), #480 (provide auto-fill / withdraw preview), #489 (no always-on essays), #507 (/wrap), #462 (pre-sign summary).

Current codebase

The mechanics work. What is missing is a user-facing path that a LUNC holder can follow without reading GitLab docs/frontend.md.

Layer	Behavior today
On-chain LP	Pair `provide_liquidity { assets }` and CW20 `send` → `withdraw_liquidity`. First deposit locks `MINIMUM_LIQUIDITY` (1000). Later deposits mint `min(amount_a × share / reserve_a, …)`. Off-ratio deposits donate the excess.
Native LUNC	Pools hold CW20 (cLUNC / wrapped). `/pool` checkbox Use native LUNC (auto-wrap) builds a multi-msg wrap+provide (#213). `/wrap` is under More when wrap env is set (#507). Burn tax / unwrap quotes are wrap-page concerns (#512).
Gas	CW20/CW20 provide = three txs (allowance A, allowance B, provide) — bank uluna must cover all three before the first broadcast (#147). Native path = one multi-msg fee. Failed provide rolls back allowances in one `decrease_allowance` multi-tx.
`/pool` UI	Indexer pair list, Provide / Withdraw tabs, IL notice + GitLab “Learn more” (#366), counterpart auto-fill, ratio warning, pre-sign summary, pause/blacklist gates. No first-visit how-to. Docs links point at GitLab `frontend.md` anchors, not a retail guide.
Nav	Pool is a primary item, but tablets fold it into header More (`HEADER_FULL_NAV_MIN_WIDTH_PX` = 1200). Mobile bottom nav includes Pool.
Onboarding (#417)	`TradeOnboardingStrip` on `/`, `/trade`, `/limits` only: “Start with Swap” + Swap · Trade · Limits. Pool and Wrap are absent. Dismiss persists forever.
Portfolio	LP overview + “Manage on Pool”. Open limits + “Manage on Limits or Trade”. No how-to, no provide CTA beyond the link.
Limits as “liquidity”	Resting limits escrow one token at a limit price. That is maker inventory, not v2 LP shares, and there is no incentive program. Support mentioned both in one sentence; the dApp never explains the difference.
User docs	`docs/user-incident-faq.md` covers pause/blacklist, not “how do I add LUNC to a pool?”. Engineering docs are not a retail FAQ.

Why this is needed

Users cannot complete a supported action. Support told them LP and limits exist; they still cannot find the steps on dex.cl8y.com.
“Provide LUNC” is two products. AMM LP needs both sides of a pair (LUNC + the other asset, or wrapped equivalents). A LUNC-only holder who never sees that will bounce. Limits need a pair, side, price, and escrow — also not discoverable from Swap alone after the onboarding strip is dismissed.
Wrap is a hidden prerequisite. Native LUNC is not the pool CW20. The auto-wrap checkbox is easy to miss; /wrap lives under More.
No rewards UI is correct — but silence looks like a missing feature. Users hunt for farms. A short, honest “no incentive program” belongs in the how-to, not as a permanent banner on every page.
GitLab frontend.md is not an answer to “has it been written here?” on the production dApp.

Constraints / guardrails

#489 cognitive load. No always-on architecture essays, cross-nav lectures, or “you pay gas / burn tax” footers on Swap/Pool/Trade. How-to = opt-in (<details>, first-visit dismissible strip, or a short /help / docs page linked once). Labels stay ≤ ~5 words on chrome.
Do not invent incentives. No APR, points, or “earn” chrome. One sentence: there is no LP/maker incentive program currently.
Do not conflate products. v2 LP ≠ limit escrow ≠ /ust1 mint ≠ /wrap as a destination. Wrap is a step for native LUNC, not the liquidity product.
Two-sided AMM is mandatory. Never imply a user can deposit only LUNC into a v2 pool. Show the other asset (or native equivalent) before the provide CTA is enabled — already true in the form; the how-to must say it.
Keep safety gates. IL notice (#366), NFA / risk modal (#138), clickwrap (#517), pause/blacklist, gas gates (#147), ratio warning, pre-sign summary (#462). Docs must not replace blocking errors.
Do not change pool math, fee treasury, or wrap-mapper fees in this issue.
Copy: Buy/Sell + token symbols; no token0/token1. “Pool” / “Provide” / “Withdraw” / “Limit” — not “AMM invariant” / “CW20 Send”.
Tablet/More discoverability. If the how-to says “open Pool”, it must still work when Pool is under More (< 1200px) and on mobile bottom nav.
Themes / a11y. Light + dark; how-to must not cover wallet modal, clickwrap, or money CTAs.
LocalTerra for provide/withdraw/wrap/limit place paths. Do not skip with a false “no LocalTerra”.

Relevant files

File	Role
`frontend-dapp/src/pages/PoolPage.tsx`	Provide / withdraw, native checkbox, IL + GitLab docs links
`frontend-dapp/src/components/common/TradeOnboardingStrip.tsx`	First-visit strip (no Pool today)
`frontend-dapp/src/components/common/navItems.ts`	Pool vs More vs Wrap
`frontend-dapp/src/pages/WrapPage.tsx`	Native ↔ cLUNC (optional pre-step)
`frontend-dapp/src/components/portfolio/PortfolioLpOverviewSection.tsx`	Existing “Manage on Pool”
`frontend-dapp/src/components/legal/legalCopy.ts`	Incident FAQ href pattern
`docs/frontend.md` § Pool provide / wrap	Engineering invariants (keep; not the retail answer)
`docs/user-incident-faq.md`	Existing user-facing FAQ (incident only)
`skills/AGENTS_FRONTEND_COPY_COGNITIVE_LOAD.md`	Copy rules
`skills/AGENTS_FRONTEND_POOL_PROVIDE_WITHDRAW_PREVIEW.md`	Provide/withdraw preview
`skills/AGENTS_MAINNET_WRAP_ENABLEMENT.md`	Wrap env / cLUNC

Recommended direction

Ship a short retail how-to the dApp can open in one tap, plus one discoverability hook.

Canonical user doc (same-origin or GitLab blob that is written for humans, not agents): ~8–15 steps covering
- Connect wallet on dex.cl8y.com; confirm network badge.
- Pool LP: open Pool (header, More, or mobile tab) → pick a LUNC / cLUNC pair → Provide → both amounts (auto-fill) → optional Use native LUNC (auto-wrap) → IL + pre-sign → wallet prompts (1 or 3) → keep LP tokens to withdraw later.
- Withdraw: Pool → Withdraw → LP amount → preview → sign.
- Limits (optional second path): Trade/Limits → Buy/Sell → price → Pay → Place limit. Say clearly this is not pool LP and not a rewards program.
- No incentive program (one line).
In-product entry (pick one primary, others may link):
- Dismissible first-visit line on /pool (“Add both tokens. Native LUNC can auto-wrap. How to”), or
- Extend TradeOnboardingStrip with a Pool link without turning it into a lecture, or
- Footer / Portfolio “How to add liquidity” next to the existing incident FAQ pattern.
Do not replace the IL notice or pre-sign card with the how-to. Link out.
Engineering docs/frontend.md stays the invariant source; add a pointer to the retail doc so agents do not paste protocol essays onto the page.

Acceptance criteria

AC1 — Answer the report. A new user on dex.cl8y.com can reach a how-to that names Pool provide/withdraw and optional limit maker, without opening this GitLab issue or docs/frontend.md as the only guide.
AC2 — LUNC-specific. How-to states: pools use wrapped LUNC; Use native LUNC (auto-wrap) on /pool or /wrap first; bank LUNC is still required for gas.
AC3 — Two-sided. How-to states both assets are required; LUNC-only deposit is not a v2 pool action.
AC4 — No farm. How-to states there is no incentive program currently. No APR/points UI.
AC5 — Withdraw. How-to includes withdraw via /pool and that LP tokens represent the share.
AC6 — Limits disambiguation. If limits are mentioned, they are maker orders, not LP shares; link /trade or /limits.
AC7 — #489. No permanent educational banner on Swap/Trade/Limits. Entry is dismissible or <details> / dedicated help. Chrome labels stay short.
AC8 — Discoverable under More. Phone + tablet (< 1200px): user can still find Pool and the how-to.
AC9 — Gates unchanged. IL, pause, blacklist, gas, ratio warning, clickwrap, NFA still block or warn as today.
AC10 — Tests + verify target. RTL/E2E for the entry + make verify-issue-<iid>.

Test plan (all paths)

Content / IA

#	Path	Assert
C1	First visit `/pool` (or chosen entry)	How-to control visible; does not cover Provide CTA
C2	Dismiss (if dismissible)	Stays dismissed after reload; Provide still works
C3	How-to body	Mentions Pool, both tokens, native auto-wrap or Wrap, withdraw, no incentives
C4	Limits branch	Optional; if present, does not call limits “LP”
C5	Incident FAQ	Still reachable; how-to does not replace it
C6	GitLab `frontend.md` links	May remain as “Learn more” for IL; not the only how-to

Unit / RTL (`make test-frontend`)

Pool page: how-to testid present; Provide/Withdraw tabs and IL notice still render disconnected.
Onboarding strip (if extended): Pool link; dismiss still does not block wallet/submit.
Copy tests: no token0/token1; no APR; “no incentive” string if specified.
Existing PoolPage pause/blacklist/gas tests still pass.

Playwright

#	Path	Assert
P1	`/pool` desktop	Open how-to; click through to Provide form; native LUNC checkbox visible on a wrap-capable pair
P2	Tablet 820×1180	Pool via More; how-to still reachable
P3	Phone 390×844	Bottom-nav Pool; how-to does not cover tab bar or Provide CTA
P4	Provide happy (dev wallet / LocalTerra)	Existing `pool.spec.ts` + tx path still green with how-to mounted
P5	Withdraw	How-to mentions withdraw; withdraw form still opens
P6	`/wrap` then `/pool`	Optional path described; wrap page has no new always-on lecture (#489)
P7	`/limits` or `/trade`	If how-to links here, place form still primary; no new banner over Place limit
P8	Light + dark	How-to readable; no contrast fail

Manual QA (production-shaped)

Fresh browser profile on dex.cl8y.com (or QA). Do not use GitLab. Follow only in-product copy to add LUNC LP (or explain why the other token is required).
Confirm wrap checkbox or Wrap → Pool.
Confirm withdraw steps are findable from Portfolio “Manage on Pool”.
Confirm a user looking for “farm / rewards” sees “no incentive program” once, not a fake APR.

Test plan — attack, hack, and abuse vectors

Vector	What to prove
A1 Phishing / wrong URL	How-to tells users to check the network badge / env strip (existing `ENVIRONMENT_EXPLAINER`). Do not teach signing messages from a different origin.
A2 Fake farm / airdrop copy	No third-party URL, QR, or “send LUNC to this address to LP”. Only in-app Pool/Wrap/Limits.
A3 One-sided donate	How-to + existing ratio warning: off-ratio provide still donates excess. Do not hide that.
A4 Wrap / burn-tax surprise	Native unwrap is not “free LUNC out”. Link wrap docs / `#512` behavior; do not tell users to unwrap to an exchange without the existing warning.
A5 Allowance grief	Three-tx path: do not tell users to skip the gas gate. Rollback still one multi `decrease_allowance` if provide fails.
A6 Clickwrap / NFA bypass	How-to must not skip Legal TermsGate or first-visit risk modal.
A7 XSS	How-to is static React/markdown — no `innerHTML` of indexer or wallet strings.
A8 Overlay / clickjack	How-to dialog/details must sit under wallet modal and clickwrap; must not cover Provide with an invisible hit target.
A9 Social-engineering “support”	Do not add a support chat widget or “paste your mnemonic”. Incident path stays the existing security issue template.
A10 Incentive spoof	Tests fail if APR/points/reward APIs are introduced as part of this how-to.

Verification criteria

Issue is done when all of the following are true:

Cold-user test. Someone who only has the three quoted messages can add (or correctly attempt) LUNC LP from dex.cl8y.com using in-product help alone.
Two products stay distinct. LP vs limits vs wrap vs UST1.
#489 held. No new always-on lecture on Swap/Trade/Limits/Wrap.
Safety gates unchanged (IL, gas, pause, blacklist, clickwrap, NFA, ratio donate warning).
Automated P1–P3 + A2/A7/A10. make verify-issue-<iid> green.
Docs: retail how-to exists; docs/frontend.md / copy playbook point at it. No farm program shipped.

Mode

v2 (pool-only LP)
limit order (disambiguation only — no new place/cancel semantics)

Severity

major UX (supported action is invisible to retail users on production)

## Summary Retail users on **dex.cl8y.com** cannot figure out how to **provide LUNC liquidity**. Support already answered the product facts; the dApp does not. > “I can provide liquidity of lunc for some period, I want to know how it works?” > “Yes you can provide and withdraw v2 lp, or place limit orders. Theres no incentive program currently” > “Has it been written here before how to do this? Or can you write to me briefly… Thanks. I cant figure out how to do it on dex.cl8y.com” Bundle **one** retail how-to surface for both ways people hear “provide LUNC liquidity”: 1. **v2 AMM LP** — `/pool` provide + withdraw (native LUNC auto-wrap or wrap-then-deposit). 2. **Maker limits** — `/trade` or `/limits` (escrow is **not** pool LP; no farming UI). Do **not** split “write a GitLab doc” vs “add a Pool hint” vs “explain wrap” vs “explain two-sided deposit” vs “distinguish limit maker” into separate issues. Do **not** add a rewards/farming program. Related: [#147](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/147) (CW20 add-LP three fees), [#213](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/213) (native wrap + provide), [#366](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/366) (IL notice), [#417](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/417) (onboarding strip is Swap/Trade/Limits only), [#480](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/480) (provide auto-fill / withdraw preview), [#489](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/489) (no always-on essays), [#507](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/507) (`/wrap`), [#462](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/462) (pre-sign summary). ## Current codebase The **mechanics work**. What is missing is a **user-facing path** that a LUNC holder can follow without reading GitLab `docs/frontend.md`. | Layer | Behavior today | |-------|----------------| | **On-chain LP** | Pair `provide_liquidity { assets }` and CW20 `send` → `withdraw_liquidity`. First deposit locks `MINIMUM_LIQUIDITY` (1000). Later deposits mint `min(amount_a × share / reserve_a, …)`. Off-ratio deposits donate the excess. | | **Native LUNC** | Pools hold **CW20** (cLUNC / wrapped). `/pool` checkbox **Use native LUNC (auto-wrap)** builds a multi-msg wrap+provide ([#213](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/213)). `/wrap` is under **More** when wrap env is set ([#507](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/507)). Burn tax / unwrap quotes are wrap-page concerns ([#512](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/512)). | | **Gas** | CW20/CW20 provide = **three** txs (allowance A, allowance B, provide) — bank **uluna** must cover all three before the first broadcast ([#147](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/147)). Native path = one multi-msg fee. Failed provide rolls back allowances in one `decrease_allowance` multi-tx. | | **`/pool` UI** | Indexer pair list, Provide / Withdraw tabs, IL notice + GitLab “Learn more” ([#366](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/366)), counterpart auto-fill, ratio warning, pre-sign summary, pause/blacklist gates. **No first-visit how-to.** Docs links point at **GitLab `frontend.md` anchors**, not a retail guide. | | **Nav** | **Pool** is a primary item, but tablets fold it into header **More** (`HEADER_FULL_NAV_MIN_WIDTH_PX` = 1200). Mobile bottom nav includes Pool. | | **Onboarding (#417)** | `TradeOnboardingStrip` on `/`, `/trade`, `/limits` only: “Start with Swap” + Swap · Trade · Limits. **Pool and Wrap are absent.** Dismiss persists forever. | | **Portfolio** | LP overview + “Manage on Pool”. Open limits + “Manage on Limits or Trade”. No how-to, no provide CTA beyond the link. | | **Limits as “liquidity”** | Resting limits escrow one token at a limit price. That is **maker inventory**, not v2 LP shares, and there is **no incentive program**. Support mentioned both in one sentence; the dApp never explains the difference. | | **User docs** | `docs/user-incident-faq.md` covers pause/blacklist, not “how do I add LUNC to a pool?”. Engineering docs are not a retail FAQ. | ## Why this is needed 1. **Users cannot complete a supported action.** Support told them LP and limits exist; they still cannot find the steps on dex.cl8y.com. 2. **“Provide LUNC” is two products.** AMM LP needs **both sides** of a pair (LUNC + the other asset, or wrapped equivalents). A LUNC-only holder who never sees that will bounce. Limits need a pair, side, price, and escrow — also not discoverable from Swap alone after the onboarding strip is dismissed. 3. **Wrap is a hidden prerequisite.** Native LUNC is not the pool CW20. The auto-wrap checkbox is easy to miss; `/wrap` lives under More. 4. **No rewards UI is correct — but silence looks like a missing feature.** Users hunt for farms. A short, honest “no incentive program” belongs in the how-to, not as a permanent banner on every page. 5. **GitLab `frontend.md` is not an answer** to “has it been written here?” on the production dApp. ## Constraints / guardrails 1. **#489 cognitive load.** No always-on architecture essays, cross-nav lectures, or “you pay gas / burn tax” footers on Swap/Pool/Trade. How-to = **opt-in** (`<details>`, first-visit dismissible strip, or a short `/help` / docs page linked once). Labels stay ≤ ~5 words on chrome. 2. **Do not invent incentives.** No APR, points, or “earn” chrome. One sentence: there is **no** LP/maker incentive program currently. 3. **Do not conflate products.** v2 LP ≠ limit escrow ≠ `/ust1` mint ≠ `/wrap` as a destination. Wrap is a **step** for native LUNC, not the liquidity product. 4. **Two-sided AMM is mandatory.** Never imply a user can deposit **only** LUNC into a v2 pool. Show the other asset (or native equivalent) before the provide CTA is enabled — already true in the form; the how-to must say it. 5. **Keep safety gates.** IL notice (#366), NFA / risk modal (#138), clickwrap (#517), pause/blacklist, gas gates (#147), ratio warning, pre-sign summary (#462). Docs must not replace blocking errors. 6. **Do not change pool math, fee treasury, or wrap-mapper fees** in this issue. 7. **Copy:** Buy/Sell + token symbols; no `token0`/`token1`. “Pool” / “Provide” / “Withdraw” / “Limit” — not “AMM invariant” / “CW20 Send”. 8. **Tablet/More discoverability.** If the how-to says “open Pool”, it must still work when Pool is under **More** (< 1200px) and on mobile bottom nav. 9. **Themes / a11y.** Light + dark; how-to must not cover wallet modal, clickwrap, or money CTAs. 10. **LocalTerra** for provide/withdraw/wrap/limit place paths. Do not skip with a false “no LocalTerra”. ## Relevant files | File | Role | |------|------| | [`frontend-dapp/src/pages/PoolPage.tsx`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/pages/PoolPage.tsx) | Provide / withdraw, native checkbox, IL + GitLab docs links | | [`frontend-dapp/src/components/common/TradeOnboardingStrip.tsx`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/components/common/TradeOnboardingStrip.tsx) | First-visit strip (no Pool today) | | [`frontend-dapp/src/components/common/navItems.ts`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/components/common/navItems.ts) | Pool vs More vs Wrap | | [`frontend-dapp/src/pages/WrapPage.tsx`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/pages/WrapPage.tsx) | Native ↔ cLUNC (optional pre-step) | | [`frontend-dapp/src/components/portfolio/PortfolioLpOverviewSection.tsx`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/components/portfolio/PortfolioLpOverviewSection.tsx) | Existing “Manage on Pool” | | [`frontend-dapp/src/components/legal/legalCopy.ts`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/components/legal/legalCopy.ts) | Incident FAQ href pattern | | [`docs/frontend.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/docs/frontend.md) § Pool provide / wrap | Engineering invariants (keep; not the retail answer) | | [`docs/user-incident-faq.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/docs/user-incident-faq.md) | Existing user-facing FAQ (incident only) | | [`skills/AGENTS_FRONTEND_COPY_COGNITIVE_LOAD.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/skills/AGENTS_FRONTEND_COPY_COGNITIVE_LOAD.md) | Copy rules | | [`skills/AGENTS_FRONTEND_POOL_PROVIDE_WITHDRAW_PREVIEW.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/skills/AGENTS_FRONTEND_POOL_PROVIDE_WITHDRAW_PREVIEW.md) | Provide/withdraw preview | | [`skills/AGENTS_MAINNET_WRAP_ENABLEMENT.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/skills/AGENTS_MAINNET_WRAP_ENABLEMENT.md) | Wrap env / cLUNC | ## Recommended direction Ship a **short retail how-to** the dApp can open in one tap, plus **one** discoverability hook. 1. **Canonical user doc** (same-origin or GitLab blob that is written for humans, not agents): ~8–15 steps covering - Connect wallet on dex.cl8y.com; confirm network badge. - **Pool LP:** open **Pool** (header, More, or mobile tab) → pick a LUNC / cLUNC pair → Provide → both amounts (auto-fill) → optional **Use native LUNC (auto-wrap)** → IL + pre-sign → wallet prompts (1 or 3) → keep LP tokens to withdraw later. - **Withdraw:** Pool → Withdraw → LP amount → preview → sign. - **Limits (optional second path):** Trade/Limits → Buy/Sell → price → Pay → Place limit. Say clearly this is **not** pool LP and **not** a rewards program. - **No incentive program** (one line). 2. **In-product entry (pick one primary, others may link):** - Dismissible first-visit line on `/pool` (“Add both tokens. Native LUNC can auto-wrap. How to”), **or** - Extend `TradeOnboardingStrip` with a **Pool** link without turning it into a lecture, **or** - Footer / Portfolio “How to add liquidity” next to the existing incident FAQ pattern. 3. **Do not** replace the IL notice or pre-sign card with the how-to. Link out. 4. **Engineering `docs/frontend.md`** stays the invariant source; add a pointer to the retail doc so agents do not paste protocol essays onto the page. ## Acceptance criteria - [ ] **AC1 — Answer the report.** A new user on dex.cl8y.com can reach a how-to that names **Pool provide/withdraw** and **optional limit maker**, without opening this GitLab issue or `docs/frontend.md` as the only guide. - [ ] **AC2 — LUNC-specific.** How-to states: pools use wrapped LUNC; **Use native LUNC (auto-wrap)** on `/pool` **or** `/wrap` first; bank LUNC is still required for **gas**. - [ ] **AC3 — Two-sided.** How-to states both assets are required; LUNC-only deposit is not a v2 pool action. - [ ] **AC4 — No farm.** How-to states there is **no** incentive program currently. No APR/points UI. - [ ] **AC5 — Withdraw.** How-to includes withdraw via `/pool` and that LP tokens represent the share. - [ ] **AC6 — Limits disambiguation.** If limits are mentioned, they are **maker orders**, not LP shares; link `/trade` or `/limits`. - [ ] **AC7 — #489.** No permanent educational banner on Swap/Trade/Limits. Entry is dismissible or `<details>` / dedicated help. Chrome labels stay short. - [ ] **AC8 — Discoverable under More.** Phone + tablet (< 1200px): user can still find Pool and the how-to. - [ ] **AC9 — Gates unchanged.** IL, pause, blacklist, gas, ratio warning, clickwrap, NFA still block or warn as today. - [ ] **AC10 — Tests + verify target.** RTL/E2E for the entry + `make verify-issue-<iid>`. ## Test plan (all paths) ### Content / IA | # | Path | Assert | |---|------|--------| | C1 | First visit `/pool` (or chosen entry) | How-to control visible; does not cover Provide CTA | | C2 | Dismiss (if dismissible) | Stays dismissed after reload; Provide still works | | C3 | How-to body | Mentions Pool, both tokens, native auto-wrap **or** Wrap, withdraw, no incentives | | C4 | Limits branch | Optional; if present, does not call limits “LP” | | C5 | Incident FAQ | Still reachable; how-to does not replace it | | C6 | GitLab `frontend.md` links | May remain as “Learn more” for IL; not the only how-to | ### Unit / RTL (`make test-frontend`) 1. Pool page: how-to testid present; Provide/Withdraw tabs and IL notice still render disconnected. 2. Onboarding strip (if extended): Pool link; dismiss still does not block wallet/submit. 3. Copy tests: no `token0`/`token1`; no APR; “no incentive” string if specified. 4. Existing PoolPage pause/blacklist/gas tests still pass. ### Playwright | # | Path | Assert | |---|------|--------| | P1 | `/pool` desktop | Open how-to; click through to Provide form; native LUNC checkbox visible on a wrap-capable pair | | P2 | Tablet 820×1180 | Pool via **More**; how-to still reachable | | P3 | Phone 390×844 | Bottom-nav Pool; how-to does not cover tab bar or Provide CTA | | P4 | Provide happy (dev wallet / LocalTerra) | Existing `pool.spec.ts` + tx path still green with how-to mounted | | P5 | Withdraw | How-to mentions withdraw; withdraw form still opens | | P6 | `/wrap` then `/pool` | Optional path described; wrap page has no new always-on lecture (#489) | | P7 | `/limits` or `/trade` | If how-to links here, place form still primary; no new banner over Place limit | | P8 | Light + dark | How-to readable; no contrast fail | ### Manual QA (production-shaped) 1. Fresh browser profile on dex.cl8y.com (or QA). Do **not** use GitLab. Follow only in-product copy to add LUNC LP (or explain why the other token is required). 2. Confirm wrap checkbox **or** Wrap → Pool. 3. Confirm withdraw steps are findable from Portfolio “Manage on Pool”. 4. Confirm a user looking for “farm / rewards” sees “no incentive program” once, not a fake APR. ## Test plan — attack, hack, and abuse vectors | Vector | What to prove | |--------|----------------| | **A1 Phishing / wrong URL** | How-to tells users to check the **network badge** / env strip (existing `ENVIRONMENT_EXPLAINER`). Do not teach signing messages from a different origin. | | **A2 Fake farm / airdrop copy** | No third-party URL, QR, or “send LUNC to this address to LP”. Only in-app Pool/Wrap/Limits. | | **A3 One-sided donate** | How-to + existing ratio warning: off-ratio provide still **donates** excess. Do not hide that. | | **A4 Wrap / burn-tax surprise** | Native unwrap is not “free LUNC out”. Link wrap docs / `#512` behavior; do not tell users to unwrap to an exchange without the existing warning. | | **A5 Allowance grief** | Three-tx path: do not tell users to skip the gas gate. Rollback still one multi `decrease_allowance` if provide fails. | | **A6 Clickwrap / NFA bypass** | How-to must not skip Legal TermsGate or first-visit risk modal. | | **A7 XSS** | How-to is static React/markdown — no `innerHTML` of indexer or wallet strings. | | **A8 Overlay / clickjack** | How-to dialog/details must sit **under** wallet modal and clickwrap; must not cover Provide with an invisible hit target. | | **A9 Social-engineering “support”** | Do not add a support chat widget or “paste your mnemonic”. Incident path stays the existing security issue template. | | **A10 Incentive spoof** | Tests fail if APR/points/reward APIs are introduced as part of this how-to. | ## Verification criteria Issue is done when **all** of the following are true: 1. **Cold-user test.** Someone who only has the three quoted messages can add (or correctly attempt) LUNC LP from dex.cl8y.com using in-product help alone. 2. **Two products stay distinct.** LP vs limits vs wrap vs UST1. 3. **#489 held.** No new always-on lecture on Swap/Trade/Limits/Wrap. 4. **Safety gates unchanged** (IL, gas, pause, blacklist, clickwrap, NFA, ratio donate warning). 5. **Automated P1–P3 + A2/A7/A10.** `make verify-issue-<iid>` green. 6. **Docs:** retail how-to exists; `docs/frontend.md` / copy playbook point at it. No farm program shipped. ## Mode - [x] v2 (pool-only LP) - [x] limit order (disambiguation only — no new place/cancel semantics) ## Severity - [x] major UX (supported action is invisible to retail users on production)

PlasticDigits commented

2026-08-16 07:17:27 +00:00

(Migrated from gitlab.com)

mentioned in commit b35548b994

mentioned in commit b35548b9944794657728089deaa6895b301a47f8

PlasticDigits commented

2026-08-16 07:19:32 +00:00

(Migrated from gitlab.com)

Also need to mention fees if they exist, for instance on pair creation

PlasticDigits commented

2026-08-16 07:33:41 +00:00

(Migrated from gitlab.com)

mentioned in commit 410f8fd733

mentioned in commit 410f8fd73379ed11a01eeef4f46bdbee6ca65ca0

PlasticDigits commented

2026-08-16 07:33:43 +00:00

(Migrated from gitlab.com)

mentioned in merge request !1061

PlasticDigits commented

2026-08-16 07:33:56 +00:00

(Migrated from gitlab.com)

Implementation is in !1061 (feat/531-retail-lunc-lp-howto).

Shipped: opt-in /pool#lp-howto (dismissible hint + <details>), footer/Portfolio links, pair-creation fee mention, no incentive copy, make verify-issue-531.

Still for humans: cold-user pass on QA/dex.cl8y.com (do not use GitLab as the only guide).

Implementation is in !1061 (`feat/531-retail-lunc-lp-howto`). Shipped: opt-in `/pool#lp-howto` (dismissible hint + `<details>`), footer/Portfolio links, pair-creation fee mention, no incentive copy, `make verify-issue-531`. Still for humans: cold-user pass on QA/dex.cl8y.com (do not use GitLab as the only guide).

PlasticDigits commented

2026-08-16 08:44:20 +00:00

(Migrated from gitlab.com)

Merge sanity check for !1061 (before landing on main):

Implementation matches H531-1–H531-10 (opt-in /pool#lp-howto, two-sided LP, wrap/gas/withdraw, pair-creation fee, no incentive program, footer/Portfolio hooks).
Playwright gap: spec has no P4 (footer/Portfolio deep-link click). verify-issue-531.sh only gates P1–P3 even though P5/P8 exist in the spec.
Footer uses a plain <a href="/pool#lp-howto"> (full reload) rather than a React Router <Link>.
Cold-user pass on QA/dex.cl8y.com is still a human follow-up (do not treat GitLab docs as the only guide).
Not blocking merge. CI pipeline on the MR failed immediately (duration 0) — not treated as a code verdict.

Merge sanity check for !1061 (before landing on main): - Implementation matches H531-1–H531-10 (opt-in `/pool#lp-howto`, two-sided LP, wrap/gas/withdraw, pair-creation fee, no incentive program, footer/Portfolio hooks). - Playwright gap: spec has no P4 (footer/Portfolio deep-link click). `verify-issue-531.sh` only gates P1–P3 even though P5/P8 exist in the spec. - Footer uses a plain `<a href="/pool#lp-howto">` (full reload) rather than a React Router `<Link>`. - Cold-user pass on QA/dex.cl8y.com is still a human follow-up (do not treat GitLab docs as the only guide). - Not blocking merge. CI pipeline on the MR failed immediately (duration 0) — not treated as a code verdict.

PlasticDigits commented

2026-08-16 08:44:30 +00:00

(Migrated from gitlab.com)

mentioned in commit dac47e806e

mentioned in commit dac47e806e59aa6aa4ba629e99fb4164dd1cddf4

PlasticDigits (Migrated from gitlab.com) closed this issue

2026-08-16 08:44:30 +00:00

PlasticDigits commented

2026-08-16 08:45:17 +00:00

(Migrated from gitlab.com)

mentioned in commit c03dbdf199

mentioned in commit c03dbdf199e38a579cc2c1a87fa36b29fa78866e