feat(indexer): tax-aware route/solve ranking for community tax CW20 #615
Labels
No labels
agent:fix_bugfix
agent:fix_conflicts
agent:fix_security
agent:gap_analysis
agent:implement
agent:implement
agent:implement
agent:open_issues
agent:ready
agent:research
agent:security_audit
agent:verify
architecture
backend
blocker:hybrid
blocker:launch
blocker:limit-orders
blocker:v2
block:log_only
block:security
bug
ci
contracts
correctness
deploy
dev
devops
docs
documentation
duplicate
e2e
enhancement
epic
feature
frontend
functional-completion
gas
good first issue
governance
help wanted
high-risk
hooks
hybrid
indexer
infra
infrastructure
integrators
invalid
launch-blocker
limit-orders
localnet
localterra
low priority
missing-implementation
needs-design
ops
performance
priority
high
priority
medium
product
qa
QA
question
ready
ready
research
scripts
security
security-hardening
smartcontracts
tech-debt
testing
ux
UX
v2
verification
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
code/cl8y-dex-terraclassic#615
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?
Parent / related
Community tax classify T592-13 / #607 improved option 2 (official-router hops tax the original trader). Retail always-on hybrid #596. Swap + Trade market share
GET /route/solve#501. Catalogbuy_bps/sell_bps#594. Solver contract: ADR 0002,docs/route-solver.md.Playbooks:
skills/AGENTS_COMMUNITY_TAX_ROUTER.md,skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md,skills/AGENTS_HYBRID_QUOTING.md.Current codebase
GET /api/v1/route/solveranks candidate paths by routersimulate_swap_operations/ pairhybrid_simulationestimated_amount_out. Optionaltraderis CL8Y fee-discount only (#238 / #245 / #283).It does not read the #594 catalog or
TaxPreview. Community buy/sell never enter the score.That is still quote=execute for pair/router hop amounts (inbound stays 1:1, T592-1 / H-01). It is not best net for the trader after #607.
Frontend Max shrinks
amount_infor sell extra-debit (extraDebitSellBpsForExecute). Wallet sim / You Receive is still pre-buy-tax pair out.Why this is needed
After #607 option 2, advertised bps apply on pair-direct and official-router hops. The solver can still pick a route that is worse net, or that fails at execute:
amount_outis pre-buy-split. You Receive overstates. Ranking among those paths is monotone (samebuy_bps), but display ≠ execute net.Send+Swapextra-debits the trader in TAX leftover. The user never received that leftover (tokens sat on the router). Execute hitsInsufficientForSellTaxunless they already hold TAX. Solver can still pick this path if pool+book out is highest.code_id.Do not “fix” this by adding pair/router FoT math (H-01). Do not turn hybrid off (#596).
Constraints / guardrails
min_return/max_spreadstay on pair/router amounts (H-01). UI receive for a tax-token output is post-buy-split.traderis catalog-exempt, apply 0 bps. Unknown exempt → fail closed (keep bps).buy_bpsquery param as the only source — prefer indexer catalog snapshot + optional LCDTaxPreviewcheck.pool_onlyto dodge tax (#596).Ranking contract (implement this)
Let
raw_out= today’s hop/router sim output (unchanged).Eligibility (fail closed):
Send+Swapof that token) and that token is nottoken_in.token_inis that tax token (first hop sell). Max already reserved leftover. All remaining paths pay the same sell extra-debit intoken_in— do not re-rank on that leftover.Score:
token_outis a catalogued tax token andbuy_bps > 0and trader is not directory-exempt:net_out = raw_out - floor(raw_out * buy_bps / 10000).net_out = raw_out.net_out(same tie-break as today: first path with that out).Response (additive, do not break integrators):
estimated_amount_out=raw_out(execute /min_return/ wallet sim still use this).estimated_amount_out_net(and optionallytax_kind/buy_tax/sell_tax/tax_notes) so Swap/Trade You Receive can show post-buy-split whentoken_outis the tax token.optimality_scope/hybrid_notesmust say ranking is net of catalog buy/sell policy for this snapshot, inside the existing top-5 / grid bounds.11611 pin:
code_id+ known option-2data_hashor an explicit indexer flag after migrate. Document the switch in the #607 playbook. Do not silently mark unmigrated 11611 as option 2.Relevant files
indexer/src/api/route_solver.rs/best_execution.rs(winner compare)indexer/src/api/community_tokens.rs+db/queries/community_tokens.rs(bps snapshot)discount_tierpattern — add tax identity)frontend-dapp/src/utils/cw20RouteSolveQuote.ts(You Receive = net when output is tax token)frontend-dapp/src/utils/taxPreviewMaxSpend.ts(Max already extra-debits; do not double-count)docs/route-solver.md, ADR 0002 amendment,skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md,skills/AGENTS_HYBRID_QUOTING.md,skills/AGENTS_COMMUNITY_TAX_ROUTER.mdAcceptance criteria
net_outas specified; hop LCD/DB sims unchanged.token_in(option-2 wasm only).token_intax token: same extra-debit on every remaining path; winner still maxraw_out/net_outof the ask.token_outtax token:estimated_amount_out_netmatchesTaxPreviewbuy split; Swap/Trade You Receive uses net; submit still Sends declared and uses pre-taxmin_return.trader→ 0 bps (catalog or LCD). Unknown exempt fail-closed.make verify-issue-607still green (do not regress classify). Newmake verify-issue-<this>for solver + frontend helpers.docs/route-solver.md+ ADR 0002 amendment + cross-links.Test plan
raw_out.net_out<raw_outby buy bps; You Receive shows net; execute still works.net_out == raw_out.Verification
marked as related to #607
marked as related to #596
marked as related to #501
marked as related to #594
mentioned in commit
17ee753b69mentioned in merge request !1131
Implemented on
issue/615-tax-aware-route-ranking— MR !1131.make verify-issue-615passed (includesverify-issue-607+ retest).Done vs issue acceptance
net_out; hop LCD/DB sims unchanged (R615-1).token_in— option-2 only (COMMUNITY_TAX_OPTION2_*).token_intax: leftover not re-ranked; winner max ask raw/net.token_outtax:estimated_amount_out_net+ You Receive net;min_returnpre-tax.verify-issue-607+verify-issue-615; skills / route-solver / ADR 0002 / invariants.Not in this change: option-2 wasm/classify (keep on
feat/607-router-tax-option-2); live columbus-5 execute of the skip; catalogdata_hashstorage; pair/router FoT math; LCD TaxPreview on every hop.Playbook:
skills/AGENTS_INDEXER_TAX_AWARE_ROUTING.md(R615-1–R615-8).mentioned in commit
2d9b573b6fmentioned in issue #616
marked as related to #616
Merge sanity (!1131 landed on
main; CI not waited).Conflicts with !1127 were docs/Makefile/skills: kept option-2 implement close (not disclose-only Honest hops) plus R615 ranking + 11611 pin.
Automated:
make verify-issue-6157/7 (R615 docs/ADR, indexer net rank + cache identity, You Receive net helpers, nestedverify-issue-607).Acceptance leftover
COMMUNITY_TAX_OPTION2_CODE_IDS/COMMUNITY_TAX_OPTION2_DATA_HASHESafter CMM migrate. Ranking will still allow a middle TAX hop until that flip.data_hash(env pin only).Post-merge env flip + live ranking QA: #616.
mentioned in issue #620
marked as related to #620
mentioned in issue #622
marked as related to #622
mentioned in issue #690