docs(guides): practical DEX how-to #12
Labels
No labels
agent:implement
agent:research
docs
feature
ready
research
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
code/cl8y-docs#12
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
https://docs.cl8y.com/guidescurrently lists only the Open the DEX CTA stub. There is no crawlable first-party page that teaches how to use the CL8Y DEX: swaps, limit orders, fee tiers, wrapping/unwrapping, adding and removing liquidity, slippage settings, and common transaction errors — with trading fees, network fees, and any applicable taxes named as distinct kinds.Ship one prerendered practical DEX guide on a new allowlisted path so a reader who already knows they want to trade or provide liquidity can complete those jobs on the live first-party DEX, and so support can paste a stable section URL instead of rewriting the same answers in chat.
Bundle (do not split into swap / limit / wrap / LP / fee / slippage / error tickets):
/(AMM / hybrid route the live Swap card already runs)./trade(Limit tab) and/limits(resting book / lifecycle) as the live dApp already presents them./tiers(CL8Y holder discount schedule — pointer only; do not freeze a table)./wrap(native LUNC / USTC vs CW20 wrap legs; unwrap is not free)./pool(existing factory pools; creating a pair is not required to LP one that already exists).Keep
/guides/open-the-dexas the CTA-only child. Do not put this manuscript on/(Start Here,code/cl8y-docs#9),/guides/first-use(code/cl8y-docs#10), or/guides/bridge(code/cl8y-docs#11).v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full DEX manuscripts were out of scope there.
#10owns a newcomer’s first swap as one phase of wallet → gas → inbound → trade → outbound; it must not grow this dedicated DEX how-to.Parent / siblings (do not re-implement):
code/cl8y-docs#3 — v0 host + stubs;/guides/open-the-dexpurpose remains “follow the first-party CTA. Not a trading tutorial.”code/cl8y-docs#9 — Start Here on/(product map). DEX is one or two sentences there, not a how-to. Cite and link; do not expand that ticket.code/cl8y-docs#10 — first-use walkthrough. That ticket must not add/guides/dex. This issue owns the dedicated DEX operations how-to. Do not merge manuscripts; do not rewrite #10’s first-swap path here.code/cl8y-docs#11 — Bridge how-to. Different product origin (https://bridge.cl8y.com). Cite; do not merge inbound/outbound transfer steps into this page.docs/ARCHITECTURE.md§4 / §10 / §12 — closed route allowlist;dexHrefexecute ids; no unverified stats; no unpublished marketingcontent/guides/.code/cl8y-dex-terraclassic— source of currently published Swap / Trade / Limits / Pool / Wrap / Tiers chrome, fee-kind presentation, slippage Settings, and retail error copy (docs/frontend.md,skills/AGENTS_FRONTEND_USER_ERRORS.md). Read, do not vendor unpublished operator internals or copy the SPA into this host.code/CL8Y-web#1 — CL8Y utility-token wording (fee-tier pointer, not a fabricated schedule). Different deployable.Current codebase
Guides index has no DEX operations child:
src/pages/GuidesPage.tsx— lists only/guides/open-the-dex. Copy forbids dumping unpublished marketing manuscripts.src/pages/OpenDexPage.tsx— DEX CTA stub; explicitly not a trading tutorial.src/seo.ts— closedDocsPathunion of seven v0 paths. No/guides/dex.src/lib/dexHref.ts—CAMPAIGNSclosed vocabulary; noguides-dex. Helper always builds Swap/withfrom/to. No path helper for/trade,/pool,/wrap,/limits,/tiers.src/App.tsx— sevenRouteentries; unknown paths 404 via nginxtry_files … =404.src/content/invariants.ts—BANNED_CURRENT_COPY/FORBIDDEN_CLAIM_PATTERNS(no TVL / “best DEX” / CoinGecko / CMC / DeFiLlama; no “Buy CL8Y” CTA).e2e/crawl.spec.ts— currently hardcodes the seven v0 paths (must followROUTESafter this path is added; do not assume loc count 7/8/9 if #10 or #11 land first).src/verify-dist.test.ts— followsROUTES; sitemap loc count follows that module.A complete DEX manuscript therefore must add one allowlisted path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4). Do not overload
/guides/open-the-dex. Do not overload/guides/first-use(#10). Do not add/guides/swap,/guides/liquidity,/guides/wrap, or/guides/feesas extra routes in this issue — support deep-links are in-page fragment ids on the one manuscript.Duplicates / already implemented
//guides/dex.content/guides/https://dex.cl8y.comdocs/frontend.md/ skillsIf
/guides/dexalready exists as a complete prerendered how-to (swaps, limits, tiers, wrap, add/remove LP, slippage, cost kinds, common errors, stable fragment ids) and AC1–AC13 pass, close as implemented — do not duplicate.Why the new implementation is needed
The public docs origin is the URL operators hand people who ask how to swap, place a limit, wrap, or LP. Today:
/guidesnever names DEX operations as a how-to (only a CTA stub).This is documentation copy + one new prerendered route + stable heading
ids + optional same-origin screenshots. No wallet SDK, no swap/LP execution on this host, no Coolify SKU pick.Constraints / guardrails
Route. Add exactly one path:
/guides/dex. Title seedDEX · Guides · CL8Y docs(wordsmith OK; must stay unique vs existing routes and vs #10/#11 titles if those pages exist). Canonicalhttps://docs.cl8y.com/guides/dex(no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add/guides/swap,/guides/liquidity,/guides/wrap,/guides/fees,/guides/wallet, or/guides/withdraw.Support deep-links. Every required section is an
h2with a stableidthat appears in prerendered HTML (no JS). Required ids (exact):idswapslimit-ordersfee-tierswrapadd-liquidityremove-liquidityslippagecostserrorsSupport URLs are
https://docs.cl8y.com/guides/dex#swaps(and the other ids). Do not mint extra sitemap locs for fragments. Fragment ids must be in the static HTMLidattribute (not only client-side).Reader. Someone who already knows they want to use the first-party DEX (not a zero-wallet newcomer — that is #10). Numbered steps. Short sentences. One scrollable manuscript. Not a whitepaper. Not Start Here (#9). Not a Bridge transfer (#11).
This host stays static. INVARIANTS 19: no wagmi, WalletConnect, three.js, LCD keys, or DEX screens running here. Describe using whatever wallets the live DEX already documents. Do not mint a wallet directory. Do not ask the reader to connect a wallet on
docs.cl8y.com. Confirmations happen onhttps://dex.cl8y.com.Surfaces to teach (required; names must match the live dApp). Source:
code/cl8y-dex-terraclassicdocs/frontend.mdroute table and the production chrome — if a surface is unpublished or gated off in production, omit it (“see DEX”) rather than inventing UI./(Swap). Pick pay/receive, review quote, confirm in the wallet on the DEX origin. This host does not broadcast. Point atdexHrefwith execute ids (uluna+ checksummed Terra Classic CL8Y CW20 already insrc/data/contracts.ts) and campaignguides-dex./tradeLimit tab (place against the book) and/limits(wallet’s resting orders / lifecycle). State that/tradeMarket is a different ticket (solver quote + slippage), not a resting limit. Do not document maker-bot insert hints, FIFO reprice internals, or unpublished book APIs./tiers. CL8Y is the utility token for reduced DEX trading fees (code/CL8Y-web#1). Point at the live Tiers UI for the current schedule. Do not invent tier names, CL8Y thresholds, or discount percentages./wrap. Native LUNC (uluna) / native USTC vs CW20 wrap legs (cLUNC/cUSTC). Copy must say wrap and unwrap are not the same as a Swap, and unwrap is not free. Do not treat AMM Swap as mint/redeem. Do not add a/ust1mint/redeem tutorial (out of scope)./poolprovide on an existing factory pair. Creating a pair is not required to LP an existing pool. Do not teach Create Pair / Create Token admin flows./poolwithdraw / Manage. Mention LP-token burn/return in user language; do not paste contract message schemas.slippage,expertMode,recipient,pool_only,hybrid_optimize,showGems.DEX hrefs.
dexHref({ from, to, campaign: "guides-dex" }). Execute ids only. Never tickers asfrom/to.dexPathHref) usingnew URL(path, getDexOrigin())with a closed path vocabulary:/trade,/pool,/wrap,/limits,/tiersonly. Optionalutm_*viaURLSearchParams(campaignguides-dex). No string concat, nowindow.location, no visitor query.rel="noopener noreferrer"iftarget="_blank".utm_*after Swap canonicalize (ARCHITECTURE §10).Costs: trading vs network vs tax. Required distinction on
#costs:/tiers). Point at that chrome. Do not freeze a percentage, bps, or USD.uluna) to the chain, not “the DEX fee.” Distinct from CW20 wrap legs.Production discovery. Do not instruct readers to enable gems / test pairs /
?showGems=1. Production browse omits gems (code/cl8y-dex-terraclassic#562). Do not share or document gem pair addresses.Errors and recovery (user-facing only). Cover at least, using the live DEX labels (source
AGENTS_FRONTEND_USER_ERRORS.md/ pause / blacklist / wrap-pause banners — do not invent friendlier names):uluna) so the wallet cannot broadcast./tradeand/limits) — change price; do not “take” through a Limit ticket unless the live UI says to use Market.cLUNC(or USTC vscUSTC) so wrap/swap/LP uses the wrong leg.Do not publish operator recovery, RPC lists, Coolify, queue ids, pair-admin pause playbooks, or contract migrate steps.
Screenshots (optional but in-scope). Same-origin files only (
public/guides/dex/or equivalent). First-party DEX chrome, cropped, no seed phrases, no live balances presented as current, no third-party CEX UI. Alt text that remains true if images fail. No remote image CDN, no mermaid runtime. If screenshots would go stale faster than copy, ship the prose first.Claims / copy bans. Keep
BANNED_CURRENT_COPYandFORBIDDEN_CLAIM_PATTERNS. No GameFi lore. “Buy CL8Y” is not a CTA. Do not dump unpublished marketing manuscripts. USTR/UST1: not required on this page (that exception is #9’s CMM section on/only). Do not add/ust1or/minttutorials.Guides index.
/guideslists DEX beside Open the DEX (and First use / Bridge if #10/#11 have shipped). One-line each; do not duplicate the manuscript on the index. Suggested stub: “DEX — swaps, limits, fee tiers, wrap, add/remove liquidity, slippage, fees vs gas vs tax, common errors.”Home. Optional one-line link from
/once #9’s Start Here exists; not required to block this PR. Do not redefine/in this issue.Sitemap / nginx. Loc count follows
ROUTES(seven v0 + this path, plus/guides/first-useand/guides/bridgeonly if those issues already merged). nginxtry_filesunchanged. Unknown paths still 404. Do not change Dockerfile, Woodpecker shape, or DEXSitemap:pointer.Do not publish ops internals, queue ids, host/SKU, extra contract strings beyond
src/data/contracts.ts, or gas-limit tables fromdocs/frontend.md.Relevant files
src/pages/DexGuidePage.tsx(new)h2idssrc/content/dexGuide.ts(new, preferred)src/pages/GuidesPage.tsx/guides/dexsrc/App.tsxsrc/seo.tsDocsPath, title, description, campaignsrc/lib/dexHref.ts+dexHref.test.tsguides-dextoCAMPAIGNSsrc/lib/dexPathHref.ts(new)/trade,/pool,/wrap,/limits,/tiers) + unit testssrc/data/contracts.tssrc/content/invariants.tse2e/crawl.spec.tsids. Prefer deriving the path table fromROUTESso #10/#11 cannot desync loc count.src/verify-dist.test.tsROUTES; sitemap loc includes the new path only on this origindocs/ARCHITECTURE.md§4 / §10 / §12docs/INVARIANTS.mdskills/docs-static-host/SKILL.md/docs-dex-ctapublic/guides/dex/code/cl8y-dex-terraclassiccode/cl8y-docs#9, #10, #11Recommended direction
src/content/dexGuide.ts(section titles +ids + body strings + cost-kind sentences with no numeric literals unless sourced). Unit-test: banned hype, nojavascript:, no ticker execute ids, no unverified%/ TVL / invented tax rates / invented tier thresholds.DexGuidePage: H1 DEX; ordered sections with the requiredids; Swap CTA throughdexHref; other CTAs throughdexPathHref.DocsPath/CAMPAIGNS/App/ prerender. Sitemap is generated fromseo.ts— do not hand-edit a second allowlist that can drift. Updatee2e/crawl.spec.tsfromROUTESrather than a hardcoded seven-row table if that is still duplicated.GuidesPage: stub line as in constraint 12.idattributes; crawl MIME tests unchanged; 404 still 404.Acceptance criteria
GET /guides/dexprerendered HTML (no JS) contains a DEX heading and the nine required sections with exactids:swaps,limit-orders,fee-tiers,wrap,add-liquidity,remove-liquidity,slippage,costs,errors.#fee-tierspoints at/tierson the DEX origin and does not print a schedule.#wrapdistinguishes native vs CW20 wrap legs and states unwrap is not free.#limit-ordersdistinguishes Trade Limit vs Market vs/limits.dexHrefwithfrom=uluna,to=the Terra Classic CL8Y CW20 incontracts.ts,utm_campaign=guides-dex. Path hrefs for/trade,/pool,/wrap,/limits,/tiersuse the closed helper.relsafe if new tab. No visitor-query concat. Noslippage/expertMode/ gem query keys.DEX · Guides · CL8Y docsor equivalent); canonicalhttps://docs.cl8y.com/guides/dex. Other v0 routes keep their titles (home may change only via #9; first-use only via #10; Bridge only via #11)./guideslinks to/guides/dex./guides/open-the-dexstill exists and still is not rewritten into this manuscript./guides/first-useand/guides/bridgeare neither created nor rewritten by this PR.https://docs.cl8y.comonly. Unknown paths 404. robots/sitemap MIME unchanged.npm test,npm run typecheck, productionnpm run buildwith requiredVITE_*,npm run test:dist, Playwright 5 workers stay green./guides/dex.CAMPAIGNSincludesguides-dex.Given a reader opens the prerendered
/guides/dexpage When they read the how-to without executing JavaScript Then they can follow swaps, limit orders, fee-tier lookup, wrap/unwrap, add and remove liquidity, and slippage settings on the first-party DEX, distinguish DEX trading fees from network gas and taxes imposed elsewhere, jump to a named section via fragment id, and apply user-facing recovery for common errors — without invented statistics or a wallet UI on this hostTest plan (functional paths)
dist/guides/dex/index.htmlh2ids present%fee/tax/tier table unless sourced constantdexHrefdefault pair +utm_campaign=guides-dex/trade,/pool,/wrap,/limits,/tierson DEX origin;relsafe if new tab/guidesHTML/guides/dex/guides/open-the-dexGET /guides/swap(unlisted)dexGuide.ts%/ invented tax rate / tier thresholddexPathHrefjavascript:/ tickersTest plan (copy safety)
Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. Do not add abuse/hack tests.
javascript:/data:/ protocol-relative DEX hrefslippage/expertMode/showGemscontracts.ts/, #10’s first-use, or #11’s Bridge into this how-toVerification criteria
npm test&&npm run typecheck&& productionnpm run buildwith requiredVITE_*.npm run test:dist(unique titles/canonicals including the new path).ids; crawl MIME tests unchanged./guides/dexand confirm a reader can answer “how do I swap / place a limit / wrap / LP / set slippage / what is a trading fee vs gas vs tax / what if it fails?” from the page alone, and that#slippage(etc.) jumps to the matchingh2, without connecting a wallet on this host.scripts/check-origins.mjsstill fail-closed without HTTPS origins.Out of scope
/(that is #9), implementing/guides/first-use(that is #10), or implementing/guides/bridge(that is #11)./guides/open-the-dexor adding more than one new path./mint, Charts, Portfolio, Protocol stats.code/CL8Y-web,code/cl8y-dex-terraclassic, orcode/cl8y-bridge-monorepoexcept as read-only sources.Sitemap:pointer.First-pass model recommendation
Recommendation: grok-high
Rationale: This is a retail DEX how-to that must source published Swap / Trade / Limits / Pool / Wrap / Tiers chrome, distinguish protocol fees from network gas and any chain tax, and describe slippage plus user-visible errors without freezing rates or tier thresholds. Composer’s docs/test-only path does not apply: product claims have to be read from
code/cl8y-dex-terraclassic/ the live DEX UI, wallet confirmation stays a founder-required topic (even though this host only describes it), the change expands the closed allowlist (DocsPath,CAMPAIGNS, prerender, sitemap, ARCHITECTURE §4) plus a new path-href helper, and the expected files exceed a single-subsystem three-file edit (DexGuidePage,dexGuidecopy module,dexPathHref, seo/campaigns, App, guides index, architecture/invariants, crawl tests). Uncertain published fee/tax/tier/error presentation fails the “known local edit” bar. Comparable control-plane calibration: a single RCA Markdown would be Composer; this is closer to a cross-module content-policy change than a test-helper tweak.