code/cl8y-dex-terraclassic

Fork 0

design: research DEX farming/yields vs volume, fees, and CMM cash flow #1207

New issue

Open

opened 2026-09-05 12:17:44 +00:00 by PlasticDigits · 0 comments

PlasticDigits commented

2026-09-05 12:17:44 +00:00

Owner

Summary

Research / decision only — do not implement a farm, gauge, emissions contract, APR UI, or fee-split migrate in this issue.

Bundle into one investigation (do not split farming vs yields vs case studies vs CMM cash-flow):

What “farming” would mean on this DEX given there is no LP/maker incentive program today (H531-4), pair commission already goes to the CMM treasury (Llama dailySupplySideRevenue = 0), and retail copy forbids APR / points / farm chrome.
Case studies of DEX liquidity mining, real-yield, gauges, protocol-owned liquidity (POL), and maker rebates — successes and failures, with dated sources. Terra Classic / Terraport-class farms are in-scope as the local comparison, not as a product to copy.
Feasibility against live CL8Y DEX volume and fees from public indexer rollups (GET /api/v1/overview, GET /api/v1/protocol/fees, GET /api/v1/defillama/daily). Snapshot numbers in this ticket are illustrative as of 2026-09-05 UTC; the memo must re-pull and date its own tables.
Strategies that can raise net CMM cash flow without hurting the CMM balance sheet / CR — including “do nothing / POL only.” Paying LPs by minting or spending treasury assets that sit in the CR numerator is a fail unless the memo proves a cash-flow and CR-neutral path.

Related, not duplicates:

#531 — retail LP how-to; explicitly no incentive program.
#558 — CMM-custodied POL; farming-and-exit of CMM LP is forbidden.
#546 / #619 — range-ladder / V3 Grid (inventory product, not emissions).
#575 — UST1 collateral yield (Venus vs Noble). Different stack; do not merge.
#586 / #652 / #668 — /protocol fee and volume census (inputs to this memo).
#514 — maker placement discount (existing, not a farm).
#717 — inventory path bot.
ustr-cmm#14 / #16 / #19 — protocol LP in treasury CR, protocol-token haircut, A–E asset-quality credits.

Not in scope: shipping a Generator/gauge, changing FEE_CONFIG to LPs, adding /farm, advertising APR on /pool, staking CMM LP, emitting CL8Y/UST1/vFDUSD from the treasury, or reversing H531-4 in the dApp until an ADR is Accepted and a follow-up implementation issue exists.

Current codebase

CL8Y DEX is a Terra Classic constant-product AMM plus FIFO limit book (hybrid router). Liquidity providers mint LP CW20 shares (18 decimals). They do not receive swap commission. Commission is fee-on-output to each pair’s FEE_CONFIG.treasury (factory snapshot at CreatePair; production sink is the ustr-cmm CMM treasury). Hooks (burn / tax / LP-burn) are optional post-swap; they are not a farm.

Layer	Behavior today
On-chain LP	Pair `provide_liquidity` / CW20 `withdraw_liquidity`. First mint locks `MINIMUM_LIQUIDITY`. Off-ratio provide donates excess. One-sided zap is dApp multi-msg, not a farm.
Fees	Default pair fee is 180 bps (docs / deploy verify). Taker commission → CMM. Maker placement is `floor(effective/2)` with `/tiers` `limit_discount_bps` (I13). Unregistered retail: 90 bps place / 90 bps take at 180 bps pair fee.
Existing “incentive”	Hold CL8Y + Register on `/tiers`. Discount reduces protocol take; it does not pay LPs. No staking of LP tokens.
Retail copy	`/pool#lp-howto` and `docs/user-lunc-liquidity.md`: “There is no LP or maker incentive program currently.” Tests forbid `\bfarm(ing)?\b` in that copy.
POL	CMM already holds factory LP on several pairs. Custody invariant: do not sell, break, or farm-and-exit those shares. ustr-cmm `/treasury` marks LP into CR with protocol-token haircuts.
Census	`/protocol` + indexer `protocol_fee_events` (swap_amm, book_take, limit_place, wrap, unwrap, ust1_mint, ust1_redeem). Llama maps `dailyFees` = `dailyRevenue`; supply-side = 0. Yields/emissions listing is explicitly Do not.
Terraport delta	`docs/terraport.md`: Terraport staking/farming/governance are not in this repo and were called out of core in gap analyses.

Live scale (public indexer, 2026-09-05 UTC — re-pull in the memo)

GET https://indexer.dex.cl8y.com/api/v1/overview (rounded):

Metric	Snapshot
TVL (`total_liquidity_usd`)	~$119k (9 priced / 11 unpriced pairs)
Volume 24h / 7d / 30d USD	~$501 / ~$5.2k / ~$27.1k
Trades 24h / unique traders 24h	31 / 5
Fees 24h / 7d / 30d USD	~$6.3 / ~$69 / ~$281

GET /api/v1/protocol/fees?window=30d mix (USD): swap_amm ~$121 (43%), wrap ~$54 (19%), limit_place ~$52 (18%), ust1_mint ~$22, ust1_redeem ~$16, unwrap ~$13, book_take ~$3. Window + wrap fees are CMM product cash, not AMM LP residual. Any farm budget that spends “all protocol fees” is mixing unrelated sinks.

Annualizing $281 / 30d ≈ **$3.4k/year** gross protocol fee USD at this print. That is the ceiling for fee-funded incentives unless the memo proves a volume multiplier that survives mercenary exit.

Why this work is needed

Operators are asking whether a farm can grow the venue while CMM stays solvent. The product currently collects fees as CMM cash and does not share them with LPs. Flipping that without a model is a balance-sheet event, not a UI tweak.
H531-4 is load-bearing copy. Users already confuse v2 LP, maker limits, wrap, and /ust1. A farm, points program, or fake APR would collide with IL notices, NFA, and phishing (“send LP to this address”).
Volume is thin. Five unique traders in 24h and ~$27k / 30d volume cannot support Uniswap-v2-era emission APRs on ~$119k TVL without paying more than the venue earns. Mercenary LP would inflate TVL, farm, dump the reward token, and leave; CMM would keep the IL and the CR hole.
CMM already has POL and a hold-to-discount flywheel. Those are incentive designs. The memo must compare them to a new farm instead of assuming “no incentive exists.”
Adjacent tickets must not be overloaded. #546/#619 are grid inventory. #575 is collateral yield. This ticket owns DEX liquidity incentives vs CMM cash + CR.

Constraints / guardrails

Docs-only for this issue. No new CosmWasm message, no LP-staking contract, no indexer apr column, no /farm route, no Llama yields adapter, no FEE_CONFIG redirect to an LP vault.
Do not spend the CR numerator to buy TVL. Forbidden unless the ADR proves cash-flow and CR neutrality: selling/breaking CMM LP (#558), emitting UST1 or vFDUSD from treasury, circulating new CL8Y from CMM, staking CMM’s own LP into a farm, counting protocol tokens as un-haircut collateral (ustr-cmm#16).
Net CMM cash flow = DEX pair commission + wrap/window fees + other CMM inflows minus incentive outflows minus IL on POL minus CR-driven forced recap. A strategy that raises DEX volume but cuts fee share more than the volume gain fails the cash-flow test.
Do not mix fee sources. Farm budgets may only treat DEX trading fees (swap_amm + book_take + limit_place) as the DEX pool, unless the memo argues wrap/window spend and CMM product owners accept it. Default: do not fund a DEX farm from ust1-window or wrap-mapper take.
Existing discount stays. /tiers is a CL8Y demand sink that reduces CMM take. The memo must model stacking a farm on top of 180 bps − tier discounts, not assume 180 bps on every dollar.
H531-4 / #489. No APR, points, or farm chrome in production UI until a later implementation issue. Research copy is NFA; no guaranteed yield.
Gems / hostile tokens. Soft-launch gems stay hidden (#562). Do not design a farm that incentivizes unverified CW20s or FoT/rebase (whitelist policy).
No operational leakage. Memo uses public indexer + on-chain queries. Do not publish host, deploy-pipeline, or key material.
Anonymize people. Cite protocols, papers, dashboards — not private chats.

Relevant files

Area	Path
Fee destination	`docs/architecture.md`, `docs/security-model.md`, `docs/runbooks/rotate-fee-treasury.md`, pair `execute_update_treasury` / factory `SetPairTreasury*`
Default fee / tiers	`docs/reference/fee-discount-tiers.md` (I4, I13), `skills/AGENTS_FEE_DISCOUNT_TIERS.md`
Hooks (not farms)	`smartcontracts/contracts/hooks/README.md`
No-farm retail	`frontend-dapp/src/utils/poolLpHowtoCopy.ts`, `docs/user-lunc-liquidity.md`, `skills/AGENTS_FRONTEND_POOL_LP_HOWTO.md` (H531-4)
Terraport farming (out of core)	`docs/terraport.md`
Llama fees vs LP	`docs/DEFILLAMA.md` (Yields/emissions = Do not)
Fee/volume census	`indexer/src/indexer/protocol_fees.rs`, `frontend-dapp/src/components/protocol/ProtocolFeeStats.tsx`, `ProtocolGlobalStats.tsx`
POL	`docs/runbooks/rebalance-mint-ust1-lp.md`, `skills/AGENTS_REBALANCE_MINT_UST1_LP.md`
ADRs	`docs/adr/` (next unused number; do not collide with #575’s proposed 0004)
CMM CR	ustr-cmm treasury LP + haircut issues above (cross-repo; no code change here)

Recommended direction

Write ADR docs/adr/NNNN-dex-farming-yield-cmm-cashflow.md (Status: Proposed) and a one-line pointer from docs/README.md Architecture. Optional skill stub only if Accepted later.
Re-pull live scale (UTC date, endpoint, JSON fields). Split fees by by_source. Compute:
- DEX-trading fee run-rate vs wrap/window.
- Implied fee/TVL and fee/volume.
- Break-even: extra annual volume required for a given LP share or emission APR so net CMM cash ≥ status quo.
- Stress: unique traders stay in the single digits; 50% of 30d volume is wash; mercenary TVL +100% for 30 days then −80%.

Case-study pack (min. each row: mechanism, who paid, sticky TVL after emissions ended, token dump, protocol insolvency Y/N, lesson for a ~$100k-TVL / few-trader venue):

Family	Examples to cover (researchers may add)
No mining	Uniswap v2/v3 organic fees
Vampire / emissions	SushiSwap, many BSC farms, Terra Classic generator clones
Gauges / vote-lock	Curve + Convex bribes
Real yield (fee share)	GMX-class fee-to-stakers; dYdX historical
POL	Olympus-style POL paid with emissions vs CMM POL paid from inventory
Maker programs	CEX maker rebates; this DEX’s existing place/take split
Local	Terraport farming vs this DEX’s “out of core” choice

Strategy scorecard (every option gets cash-flow, CR, mercenary-risk, implementation cost, copy/phishing risk):

ID	Strategy	Default hypothesis (to confirm or kill)
S0	Status quo: POL + `/tiers` + no farm	Likely best CR; cash = 100% of DEX fees
S1	Grow POL only (more CMM LP, no third-party farm)	Uses inventory; IL is the cost; #558 custody stays
S2	Fee-funded maker rebate (cap = trailing DEX fees × k, k≤1)	May deepen book; must not exceed book_take+place surplus
S3	Fee-share to v2 LPs (cut CMM `treasury` bps)	Lowers CMM cash immediately; Llama supply-side becomes non-zero
S4	Third-party emissions (listing team pays their token)	CMM cash untouched; dump risk on their token; still no APR chrome until impl issue
S5	CL8Y or UST1 emissions from CMM	Presumed fail on CR / cash unless proven otherwise
S6	Gauge / vote-escrow	Overweight vs venue size; governance attack surface
S7	Points / retrodrop	Copy and sybil hell; still a payable liability
S8	V3 Grid / ladder (#546/#619) as the “yield” surface	Inventory product; not an emission farm

CMM cash-flow test (required formula in the ADR). For each surviving strategy:

Δcash = Δ(DEX fees kept by CMM) + Δ(wrap/window if argued) − incentive paid − POL IL − recap

Pass only if Δcash ≥ 0 in the base live-volume case and in a mercenary-exit case. CR test: numerator does not drop from spending A-grade assets or un-haircutting protocol tokens.
Decision: Stay (S0/S1) / Fee-capped rebate (S2) / Partner-paid only (S4) / Defer / Reject farm. Spawn follow-up implementation issues only if decision ≠ stay. Do not sneak a Generator into this MR.
Verify script scripts/qa/verify-issue-NNN.sh: required ADR headings present; no farm UI strings; no dailySupplySideRevenue change; poolLpHowtoCopy still has no-incentive + forbidden farm regex.

Acceptance criteria

AC1. One ADR covering farming, yields, case studies, live volume/fees, and CMM cash+CR — not split across issues.
AC2. Live indexer tables dated; sources split; wrap/window not silently used as DEX farm budget.
AC3. Break-even math: emission APR or LP fee-share vs current DEX fee run-rate and TVL.
AC4. Case studies include at least one success, one mercenary failure, one real-yield, one Terra Classic / local, and POL-vs-emissions.
AC5. Scorecard of S0–S8 (or justified merge) with cash-flow and CR columns.
AC6. Explicit mapping onto H531-4, #558 custody, ustr-cmm LP-in-CR + haircut, Llama supply-side = 0, /tiers discount reducing take.
AC7. Single product decision. No “quietly add a farm later.”
AC8. Docs-only MR: no pair/factory/hook/indexer/frontend farm surface.
AC9. NFA language; no guaranteed APR in docs or sample UI.
AC10. Follow-up impl issues listed only if decision ≠ stay; otherwise “no impl spawn.”
AC11. docs/README.md links the ADR.

Test plan (all research paths)

Document and process tests, not chain deploys. Each path must appear in the ADR (or appendix) with pass/fail.

ID	Path	How to test
P1 Status quo	LPs get residual/IL only; CMM gets commission	Trace pair treasury + Llama `dailySupplySideRevenue` = 0; `/pool` no-incentive copy
P2 Live fees	24h / 7d / 30d overview + `protocol/fees`	Re-pull; table by_source; note trader count
P3 Fee mix	DEX vs wrap vs window	Farm budget uses DEX-trading subset unless an explicit CMM-product exception is argued and rejected or accepted
P4 `/tiers` stack	180 bps × (1 − discount)	Model unregistered vs tier 5/9; farm-on-top does not assume 180 bps on all volume
P5 POL	CMM LP in CR	Cite #558 + ustr-cmm#14/#16; staking CMM LP = fail
P6 Break-even	APR × TVL vs fee run-rate	Spreadsheet or `/tmp` sim: 20% / 50% / 100% APR on snapshot TVL vs ~annualized DEX fees
P7 Mercenary	TVL in then out	30d farm then −80% TVL; leftover IL on POL; CMM still paid emissions
P8 Wash volume	Self-trade to farm	Unique-trader=5 world; fee paid to self as “rewards”
P9 S2 rebate	Maker rebate ≤ book surplus	Cap vs 30d `book_take`+`limit_place`; cannot exceed that pool
P10 S3 fee-share	Cut treasury bps	Δcash at unchanged volume (must be negative) vs optimistic volume × remaining share
P11 S4 partner	Listing-team token	CMM cash/CR unchanged; dump is their token; still no dApp APR until impl issue
P12 S5 emissions	CL8Y/UST1 from CMM	Show CR and available-supply impact; presumed fail
P13 S8 grid	#546/#619	Distinct from farm; may be the recommended “yield” UX without emissions
P14 Copy	H531-4 / #489	Research MR does not add farm strings to `poolLpHowtoCopy.ts`
P15 Llama	Yields adapter	ADR does not enable DeFiLlama yields listing
P16 Decision	Stay vs rebate vs partner vs reject	One checked option; residual risks; impl spawn rule

Negative / skip paths

N1. Memo that only says “farms attract TVL” with no fee math → fail.
N2. Ranking solely on headline APR → fail.
N3. Implementation diff (farm contract, APR badge, treasury redirect) in the research MR → fail AC8.
N4. Treating wrap/window 30d fees as LP rewards without an explicit rejected/accepted exception → fail.
N5. Recommending CMM LP be staked → fail #558.
N6. Merging this with #575 collateral yield → fail.

Test plan (attack, hack, and abuse)

Research must evaluate each vector. Do not write exploits, PoCs, or attack procedures.

ID	Vector	What the memo must show	Fail if
A1 Mercenary LP	Deposit, farm, withdraw, dump reward	Sticky-TVL evidence from case studies; CL8Y/UST1 dump hits CR and retail	Treats TVL spike as success
A2 Wash / sybil	Self-swaps or many wallets to farm	Unique-trader and volume/fee ratio; need for sybil-resistant design	Pays on raw volume with no wash discussion
A3 Farm-the-POL	If CMM LP is farmable, outsider cannot steal it but CMM could be socially engineered to stake	Custody: CMM LP never enters a farm	“Just stake treasury LP”
A4 Phishing APR	Fake farm URL / “send LP to earn”	Why H531-4 and no-farm copy exist; any future UI needs domain + token checks	Adds APR chrome in this MR
A5 Reward-token insolvency	Emissions hyperinflate	Who is the residual claimant (CMM vs holders)	Emits UST1 as “yield”
A6 Fee-share grief	Route around taxed/farmed pairs	Hybrid router + pair-direct bypass (#704 class)	Assumes all volume hits the farmed pair
A7 Gauge capture	Vote-lock / bribes	Venue too small; governance 2-of-3 vs public gauges	Recommends ve-token without capture model
A8 Discount + rebate stack	Whale registers tier 9 and also farms	Remaining fee may be ~5% of 180 bps; rebate can exceed take	Ignores `/tiers`
A9 Hostile LP token	FoT / rebase / fake LP	Whitelist + code-id audit; farm would widen blast radius	Farms any factory pair including gems
A10 Oracle/APR lie	Display APY from unsound volume	Indexer USD can be null; gems excluded from Llama	Quotes a live APR from 24h of wash
A11 CR cosmetics	Farm TVL counted as CMM asset	ustr-cmm haircut rules	Counts mercenary LP as treasury
A12 Pause / blacklist	Farm during pause or blacklisted trader	Pause must stop claims; no bypass via hook	Silent on pause

Verification criteria

ADR merged (or posted as the sole deliverable of the MR) with AC1–AC11 checked in the MR description.
scripts/qa/verify-issue-NNN.sh (or documented make verify-issue-NNN) asserts required headings, no farm UI, no-incentive copy still present.
make check-fee-discount-tier-docs still passes if that file is untouched (it should be).
Reviewers can re-run the public curls and get the same field names (values will move).
No follow-up farm implementation is opened unless the ADR decision is not stay.

Out of scope

Implementing Generator, MasterChef, gauges, points, or /farm.
Changing pair fee_bps, CMM treasury pointer, or Llama methodology except as recommendations.
UST1 collateral venue yield (#575).
Shipping V3 Grid (#619) — cite only.
Deploy, migrate, or inventory movement of CMM LP.
Choosing hosts, SKUs, models, or images.

## Summary **Research / decision only — do not implement a farm, gauge, emissions contract, APR UI, or fee-split migrate in this issue.** Bundle into **one** investigation (do not split farming vs yields vs case studies vs CMM cash-flow): 1. **What “farming” would mean on this DEX** given there is **no** LP/maker incentive program today (**H531-4**), pair commission already goes to the CMM treasury (Llama `dailySupplySideRevenue` = **0**), and retail copy forbids APR / points / farm chrome. 2. **Case studies** of DEX liquidity mining, real-yield, gauges, protocol-owned liquidity (POL), and maker rebates — **successes and failures**, with dated sources. Terra Classic / Terraport-class farms are in-scope as the local comparison, not as a product to copy. 3. **Feasibility against live CL8Y DEX volume and fees** from public indexer rollups (`GET /api/v1/overview`, `GET /api/v1/protocol/fees`, `GET /api/v1/defillama/daily`). Snapshot numbers in this ticket are **illustrative as of 2026-09-05 UTC**; the memo must **re-pull** and date its own tables. 4. **Strategies that can raise net CMM cash flow without hurting the CMM balance sheet / CR** — including “do nothing / POL only.” Paying LPs by minting or spending treasury assets that sit in the CR numerator is a **fail** unless the memo proves a cash-flow and CR-neutral path. Related, **not duplicates:** - [#531](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/531) — retail LP how-to; **explicitly no incentive program**. - [#558](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/558) — CMM-custodied POL; **farming-and-exit of CMM LP is forbidden**. - [#546](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/546) / [#619](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/619) — range-ladder / V3 Grid (inventory product, not emissions). - [#575](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/575) — UST1 **collateral** yield (Venus vs Noble). Different stack; do not merge. - [#586](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/586) / [#652](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/652) / [#668](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/668) — `/protocol` fee and volume census (inputs to this memo). - [#514](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/514) — maker **placement discount** (existing, not a farm). - [#717](https://git.cl8y.com/code/cl8y-dex-terraclassic/issues/717) — inventory path bot. - [ustr-cmm#14](https://git.cl8y.com/code/ustr-cmm/issues/14) / [#16](https://git.cl8y.com/code/ustr-cmm/issues/16) / [#19](https://git.cl8y.com/code/ustr-cmm/issues/19) — protocol LP in treasury CR, protocol-token haircut, A–E asset-quality credits. **Not in scope:** shipping a Generator/gauge, changing `FEE_CONFIG` to LPs, adding `/farm`, advertising APR on `/pool`, staking CMM LP, emitting CL8Y/UST1/vFDUSD from the treasury, or reversing **H531-4** in the dApp until an ADR is **Accepted** and a follow-up implementation issue exists. --- ## Current codebase CL8Y DEX is a Terra Classic constant-product AMM plus FIFO limit book (hybrid router). Liquidity providers mint **LP CW20 shares** (18 decimals). They do **not** receive swap commission. Commission is fee-on-output to each pair’s `FEE_CONFIG.treasury` (factory snapshot at `CreatePair`; production sink is the **ustr-cmm CMM treasury**). Hooks (burn / tax / LP-burn) are optional post-swap; they are **not** a farm. | Layer | Behavior today | |-------|----------------| | **On-chain LP** | Pair `provide_liquidity` / CW20 `withdraw_liquidity`. First mint locks `MINIMUM_LIQUIDITY`. Off-ratio provide donates excess. One-sided zap is dApp multi-msg, not a farm. | | **Fees** | Default pair fee is **180 bps** (docs / deploy verify). Taker commission → CMM. Maker placement is `floor(effective/2)` with `/tiers` `limit_discount_bps` (**I13**). Unregistered retail: 90 bps place / 90 bps take at 180 bps pair fee. | | **Existing “incentive”** | **Hold CL8Y + Register on `/tiers`**. Discount reduces **protocol** take; it does not pay LPs. No staking of LP tokens. | | **Retail copy** | `/pool#lp-howto` and `docs/user-lunc-liquidity.md`: *“There is no LP or maker incentive program currently.”* Tests forbid `\bfarm(ing)?\b` in that copy. | | **POL** | CMM already holds factory LP on several pairs. Custody invariant: do not sell, break, or farm-and-exit those shares. ustr-cmm `/treasury` marks LP into CR with protocol-token haircuts. | | **Census** | `/protocol` + indexer `protocol_fee_events` (swap_amm, book_take, limit_place, wrap, unwrap, ust1_mint, ust1_redeem). Llama maps `dailyFees` = `dailyRevenue`; supply-side = 0. Yields/emissions listing is explicitly **Do not**. | | **Terraport delta** | `docs/terraport.md`: Terraport staking/farming/governance are **not** in this repo and were called out of core in gap analyses. | ### Live scale (public indexer, 2026-09-05 UTC — re-pull in the memo) `GET https://indexer.dex.cl8y.com/api/v1/overview` (rounded): | Metric | Snapshot | |--------|----------| | TVL (`total_liquidity_usd`) | ~$119k (9 priced / 11 unpriced pairs) | | Volume 24h / 7d / 30d USD | ~$501 / ~$5.2k / ~$27.1k | | Trades 24h / unique traders 24h | 31 / **5** | | Fees 24h / 7d / 30d USD | ~$6.3 / ~$69 / ~$281 | `GET /api/v1/protocol/fees?window=30d` mix (USD): swap_amm ~$121 (43%), wrap ~$54 (19%), limit_place ~$52 (18%), ust1_mint ~$22, ust1_redeem ~$16, unwrap ~$13, book_take ~$3. **Window + wrap fees are CMM product cash, not AMM LP residual.** Any farm budget that spends “all protocol fees” is mixing unrelated sinks. Annualizing ~$281 / 30d ≈ **~$3.4k/year** gross protocol fee USD at this print. That is the **ceiling** for fee-funded incentives unless the memo proves a volume multiplier that survives mercenary exit. --- ## Why this work is needed 1. **Operators are asking whether a farm can grow the venue** while CMM stays solvent. The product currently **collects** fees as CMM cash and **does not** share them with LPs. Flipping that without a model is a balance-sheet event, not a UI tweak. 2. **H531-4 is load-bearing copy.** Users already confuse v2 LP, maker limits, wrap, and `/ust1`. A farm, points program, or fake APR would collide with IL notices, NFA, and phishing (“send LP to this address”). 3. **Volume is thin.** Five unique traders in 24h and ~$27k / 30d volume cannot support Uniswap-v2-era emission APRs on ~$119k TVL without **paying more than the venue earns**. Mercenary LP would inflate TVL, farm, dump the reward token, and leave; CMM would keep the IL and the CR hole. 4. **CMM already has POL and a hold-to-discount flywheel.** Those are incentive designs. The memo must compare them to a new farm instead of assuming “no incentive exists.” 5. **Adjacent tickets must not be overloaded.** #546/#619 are grid inventory. #575 is collateral yield. This ticket owns **DEX liquidity incentives vs CMM cash + CR**. --- ## Constraints / guardrails - **Docs-only for this issue.** No new CosmWasm message, no LP-staking contract, no indexer `apr` column, no `/farm` route, no Llama yields adapter, no `FEE_CONFIG` redirect to an LP vault. - **Do not spend the CR numerator to buy TVL.** Forbidden unless the ADR proves cash-flow **and** CR neutrality: selling/breaking CMM LP (#558), emitting UST1 or vFDUSD from treasury, circulating new CL8Y from CMM, staking CMM’s own LP into a farm, counting protocol tokens as un-haircut collateral (ustr-cmm#16). - **Net CMM cash flow** = DEX pair commission + wrap/window fees + other CMM inflows **minus** incentive outflows **minus** IL on POL **minus** CR-driven forced recap. A strategy that raises DEX volume but cuts fee share more than the volume gain **fails** the cash-flow test. - **Do not mix fee sources.** Farm budgets may only treat **DEX trading** fees (swap_amm + book_take + limit_place) as the DEX pool, unless the memo argues wrap/window spend and CMM product owners accept it. Default: **do not** fund a DEX farm from ust1-window or wrap-mapper take. - **Existing discount stays.** `/tiers` is a CL8Y **demand sink** that **reduces** CMM take. The memo must model stacking a farm **on top of** 180 bps − tier discounts, not assume 180 bps on every dollar. - **H531-4 / #489.** No APR, points, or farm chrome in production UI until a later implementation issue. Research copy is NFA; no guaranteed yield. - **Gems / hostile tokens.** Soft-launch gems stay hidden (#562). Do not design a farm that incentivizes unverified CW20s or FoT/rebase (whitelist policy). - **No operational leakage.** Memo uses public indexer + on-chain queries. Do not publish host, deploy-pipeline, or key material. - **Anonymize people.** Cite protocols, papers, dashboards — not private chats. --- ## Relevant files | Area | Path | |------|------| | Fee destination | [`docs/architecture.md`](docs/architecture.md), [`docs/security-model.md`](docs/security-model.md), [`docs/runbooks/rotate-fee-treasury.md`](docs/runbooks/rotate-fee-treasury.md), pair `execute_update_treasury` / factory `SetPairTreasury*` | | Default fee / tiers | [`docs/reference/fee-discount-tiers.md`](docs/reference/fee-discount-tiers.md) (**I4**, **I13**), `skills/AGENTS_FEE_DISCOUNT_TIERS.md` | | Hooks (not farms) | [`smartcontracts/contracts/hooks/README.md`](smartcontracts/contracts/hooks/README.md) | | No-farm retail | [`frontend-dapp/src/utils/poolLpHowtoCopy.ts`](frontend-dapp/src/utils/poolLpHowtoCopy.ts), [`docs/user-lunc-liquidity.md`](docs/user-lunc-liquidity.md), `skills/AGENTS_FRONTEND_POOL_LP_HOWTO.md` (**H531-4**) | | Terraport farming (out of core) | [`docs/terraport.md`](docs/terraport.md) | | Llama fees vs LP | [`docs/DEFILLAMA.md`](docs/DEFILLAMA.md) (Yields/emissions = Do not) | | Fee/volume census | `indexer/src/indexer/protocol_fees.rs`, `frontend-dapp/src/components/protocol/ProtocolFeeStats.tsx`, `ProtocolGlobalStats.tsx` | | POL | `docs/runbooks/rebalance-mint-ust1-lp.md`, `skills/AGENTS_REBALANCE_MINT_UST1_LP.md` | | ADRs | [`docs/adr/`](docs/adr/) (next unused number; do not collide with #575’s proposed 0004) | | CMM CR | ustr-cmm treasury LP + haircut issues above (cross-repo; no code change here) | --- ## Recommended direction 1. **Write ADR** `docs/adr/NNNN-dex-farming-yield-cmm-cashflow.md` (Status: **Proposed**) and a one-line pointer from [`docs/README.md`](docs/README.md) Architecture. Optional skill stub **only if** Accepted later. 2. **Re-pull live scale** (UTC date, endpoint, JSON fields). Split fees by `by_source`. Compute: - DEX-trading fee run-rate vs wrap/window. - Implied fee/TVL and fee/volume. - Break-even: extra annual volume required for a given LP share or emission APR so **net CMM cash ≥ status quo**. - Stress: unique traders stay in the single digits; 50% of 30d volume is wash; mercenary TVL +100% for 30 days then −80%. 3. **Case-study pack** (min. each row: mechanism, who paid, sticky TVL after emissions ended, token dump, protocol insolvency Y/N, lesson for a ~$100k-TVL / few-trader venue): | Family | Examples to cover (researchers may add) | |--------|-----------------------------------------| | No mining | Uniswap v2/v3 organic fees | | Vampire / emissions | SushiSwap, many BSC farms, Terra Classic generator clones | | Gauges / vote-lock | Curve + Convex bribes | | Real yield (fee share) | GMX-class fee-to-stakers; dYdX historical | | POL | Olympus-style POL paid with emissions vs CMM POL paid from inventory | | Maker programs | CEX maker rebates; this DEX’s existing place/take split | | Local | Terraport farming vs this DEX’s “out of core” choice | 4. **Strategy scorecard** (every option gets cash-flow, CR, mercenary-risk, implementation cost, copy/phishing risk): | ID | Strategy | Default hypothesis (to **confirm or kill**) | |----|----------|-----------------------------------------------| | **S0** | Status quo: POL + `/tiers` + no farm | Likely **best CR**; cash = 100% of DEX fees | | **S1** | Grow POL only (more CMM LP, no third-party farm) | Uses inventory; IL is the cost; #558 custody stays | | **S2** | Fee-funded maker rebate (cap = trailing DEX fees × k, k≤1) | May deepen book; must not exceed book_take+place surplus | | **S3** | Fee-share to v2 LPs (cut CMM `treasury` bps) | Lowers CMM cash immediately; Llama supply-side becomes non-zero | | **S4** | Third-party emissions (listing team pays their token) | CMM cash untouched; dump risk on **their** token; still no APR chrome until impl issue | | **S5** | CL8Y or UST1 emissions from CMM | **Presumed fail** on CR / cash unless proven otherwise | | **S6** | Gauge / vote-escrow | Overweight vs venue size; governance attack surface | | **S7** | Points / retrodrop | Copy and sybil hell; still a payable liability | | **S8** | V3 Grid / ladder (#546/#619) as the “yield” surface | Inventory product; not an emission farm | 5. **CMM cash-flow test (required formula in the ADR).** For each surviving strategy: `Δcash = Δ(DEX fees kept by CMM) + Δ(wrap/window if argued) − incentive paid − POL IL − recap` Pass only if `Δcash ≥ 0` in the **base** live-volume case **and** in a **mercenary-exit** case. CR test: numerator does not drop from spending A-grade assets or un-haircutting protocol tokens. 6. **Decision:** **Stay (S0/S1)** / **Fee-capped rebate (S2)** / **Partner-paid only (S4)** / **Defer** / **Reject farm**. Spawn **follow-up implementation issues only if** decision ≠ stay. Do not sneak a Generator into this MR. 7. **Verify script** `scripts/qa/verify-issue-NNN.sh`: required ADR headings present; no farm UI strings; no `dailySupplySideRevenue` change; `poolLpHowtoCopy` still has no-incentive + forbidden farm regex. --- ## Acceptance criteria - [ ] **AC1.** One ADR covering farming, yields, case studies, live volume/fees, and CMM cash+CR — **not** split across issues. - [ ] **AC2.** Live indexer tables dated; sources split; wrap/window **not** silently used as DEX farm budget. - [ ] **AC3.** Break-even math: emission APR or LP fee-share vs current DEX fee run-rate and TVL. - [ ] **AC4.** Case studies include at least one **success**, one **mercenary failure**, one **real-yield**, one **Terra Classic / local**, and POL-vs-emissions. - [ ] **AC5.** Scorecard of S0–S8 (or justified merge) with cash-flow **and** CR columns. - [ ] **AC6.** Explicit mapping onto **H531-4**, #558 custody, ustr-cmm LP-in-CR + haircut, Llama supply-side = 0, `/tiers` discount reducing take. - [ ] **AC7.** Single product decision. No “quietly add a farm later.” - [ ] **AC8.** Docs-only MR: no pair/factory/hook/indexer/frontend farm surface. - [ ] **AC9.** NFA language; no guaranteed APR in docs or sample UI. - [ ] **AC10.** Follow-up impl issues listed **only if** decision ≠ stay; otherwise “no impl spawn.” - [ ] **AC11.** `docs/README.md` links the ADR. --- ## Test plan (all research paths) Document and process tests, not chain deploys. Each path must appear in the ADR (or appendix) with pass/fail. | ID | Path | How to test | |----|------|-------------| | **P1 Status quo** | LPs get residual/IL only; CMM gets commission | Trace pair treasury + Llama `dailySupplySideRevenue` = 0; `/pool` no-incentive copy | | **P2 Live fees** | 24h / 7d / 30d overview + `protocol/fees` | Re-pull; table by_source; note trader count | | **P3 Fee mix** | DEX vs wrap vs window | Farm budget uses DEX-trading subset unless an explicit CMM-product exception is argued and rejected or accepted | | **P4 `/tiers` stack** | 180 bps × (1 − discount) | Model unregistered vs tier 5/9; farm-on-top does not assume 180 bps on all volume | | **P5 POL** | CMM LP in CR | Cite #558 + ustr-cmm#14/#16; staking CMM LP = fail | | **P6 Break-even** | APR × TVL vs fee run-rate | Spreadsheet or `/tmp` sim: 20% / 50% / 100% APR on snapshot TVL vs ~annualized DEX fees | | **P7 Mercenary** | TVL in then out | 30d farm then −80% TVL; leftover IL on POL; CMM still paid emissions | | **P8 Wash volume** | Self-trade to farm | Unique-trader=5 world; fee paid to self as “rewards” | | **P9 S2 rebate** | Maker rebate ≤ book surplus | Cap vs 30d `book_take`+`limit_place`; cannot exceed that pool | | **P10 S3 fee-share** | Cut treasury bps | Δcash at **unchanged** volume (must be negative) vs optimistic volume × remaining share | | **P11 S4 partner** | Listing-team token | CMM cash/CR unchanged; dump is their token; still no dApp APR until impl issue | | **P12 S5 emissions** | CL8Y/UST1 from CMM | Show CR and available-supply impact; presumed fail | | **P13 S8 grid** | #546/#619 | Distinct from farm; may be the recommended “yield” UX without emissions | | **P14 Copy** | H531-4 / #489 | Research MR does not add farm strings to `poolLpHowtoCopy.ts` | | **P15 Llama** | Yields adapter | ADR does not enable DeFiLlama yields listing | | **P16 Decision** | Stay vs rebate vs partner vs reject | One checked option; residual risks; impl spawn rule | **Negative / skip paths** - [ ] **N1.** Memo that only says “farms attract TVL” with no fee math → **fail**. - [ ] **N2.** Ranking solely on headline APR → **fail**. - [ ] **N3.** Implementation diff (farm contract, APR badge, treasury redirect) in the research MR → **fail** AC8. - [ ] **N4.** Treating wrap/window 30d fees as LP rewards without an explicit rejected/accepted exception → **fail**. - [ ] **N5.** Recommending CMM LP be staked → **fail** #558. - [ ] **N6.** Merging this with #575 collateral yield → **fail**. --- ## Test plan (attack, hack, and abuse) Research must **evaluate** each vector. **Do not** write exploits, PoCs, or attack procedures. | ID | Vector | What the memo must show | Fail if | |----|--------|-------------------------|---------| | **A1 Mercenary LP** | Deposit, farm, withdraw, dump reward | Sticky-TVL evidence from case studies; CL8Y/UST1 dump hits CR and retail | Treats TVL spike as success | | **A2 Wash / sybil** | Self-swaps or many wallets to farm | Unique-trader and volume/fee ratio; need for sybil-resistant design | Pays on raw volume with no wash discussion | | **A3 Farm-the-POL** | If CMM LP is farmable, outsider cannot steal it but CMM could be socially engineered to stake | Custody: CMM LP never enters a farm | “Just stake treasury LP” | | **A4 Phishing APR** | Fake farm URL / “send LP to earn” | Why H531-4 and no-farm copy exist; any future UI needs domain + token checks | Adds APR chrome in this MR | | **A5 Reward-token insolvency** | Emissions hyperinflate | Who is the residual claimant (CMM vs holders) | Emits UST1 as “yield” | | **A6 Fee-share grief** | Route around taxed/farmed pairs | Hybrid router + pair-direct bypass (#704 class) | Assumes all volume hits the farmed pair | | **A7 Gauge capture** | Vote-lock / bribes | Venue too small; governance 2-of-3 vs public gauges | Recommends ve-token without capture model | | **A8 Discount + rebate stack** | Whale registers tier 9 and also farms | Remaining fee may be ~5% of 180 bps; rebate can exceed take | Ignores `/tiers` | | **A9 Hostile LP token** | FoT / rebase / fake LP | Whitelist + code-id audit; farm would widen blast radius | Farms any factory pair including gems | | **A10 Oracle/APR lie** | Display APY from unsound volume | Indexer USD can be null; gems excluded from Llama | Quotes a live APR from 24h of wash | | **A11 CR cosmetics** | Farm TVL counted as CMM asset | ustr-cmm haircut rules | Counts mercenary LP as treasury | | **A12 Pause / blacklist** | Farm during pause or blacklisted trader | Pause must stop claims; no bypass via hook | Silent on pause | --- ## Verification criteria - ADR merged (or posted as the sole deliverable of the MR) with **AC1–AC11** checked in the MR description. - `scripts/qa/verify-issue-NNN.sh` (or documented `make verify-issue-NNN`) asserts required headings, no farm UI, no-incentive copy still present. - `make check-fee-discount-tier-docs` still passes if that file is untouched (it should be). - Reviewers can re-run the public `curl`s and get **the same field names** (values will move). - No follow-up farm implementation is opened unless the ADR decision is not stay. --- ## Out of scope - Implementing Generator, MasterChef, gauges, points, or `/farm`. - Changing pair `fee_bps`, CMM treasury pointer, or Llama methodology except as **recommendations**. - UST1 collateral venue yield (#575). - Shipping V3 Grid (#619) — cite only. - Deploy, migrate, or inventory movement of CMM LP. - Choosing hosts, SKUs, models, or images.

PlasticDigits referenced this issue

2026-09-11 07:20:22 +00:00

design(dex): research BSC bStocks dividends, rebase risk, and DEX volume if bridged #1223

PlasticDigits referenced this issue

2026-09-21 04:23:33 +00:00

feat(protocol): top-5 30d pair volume, TVL, and vol/LP on /protocol #1263

PlasticDigits referenced this issue

2026-09-22 05:15:07 +00:00

feat(protocol): CMM-held v2 LP columns for 30d fee bps and volume rollover #1317

PlasticDigits referenced this issue

2026-09-24 09:38:34 +00:00

feat(protocol): CMM-held v2 LP columns for 30d fee bps and volume rollover #1317