[DeFi][FIN-27] Authenticated pool indexing, extension-aware quotes and route discovery #77

Parent umbrella: #43. New FIN work-item: FIN-27. Planning only; no implementation is claimed.

Plain-language explanation

A developer needs to discover live pools and positions, quote a trade using the actual extension logic, and build a transaction that still works if the chain state changes. A stored spot price is not a valid quote.

Mermaid walkthrough

flowchart TD
A["CKB node + committed Cells"] --> B["Reorg-aware indexed state"]
B --> C["Discover authorised pools and positions"]
C --> D["Simulate quote including permitted extensions"]
D --> E["Build and preflight signed transaction"]
E --> F["Verify state freshness on submission"]

Implementation layer: Indexer/query API, quotation SDK and sample client.

Dependencies / staging: #61 pool identity, #63 authenticated tick state, #65 swap execution, #69/#71 hook-aware pricing, #55 DX and #59 operational recovery.

Detailed design and security review

Indexing and execution are separate trust domains

A chain indexer helps discover pool, tick, position, hook, claim and fee state. It does not define what value exists or what a Script is allowed to spend. Every quote must bind actual live predecessor OutPoints, code/Script identities, pool/hook configuration, authentic committed tick state and a selected chain context. A result lacking enough data must report incomplete/unquotable, not invent a price.

Indexed schema and rebuild semantics

Define stable event/Cell reconstruction records for creation, swaps, tick index changes, liquidity positions, donations, fees, claims and hook policy changes. Include genesis/network, source block/hash, cell OutPoints, input/output correspondence, commitment roots and an explicit chain-reorganisation rollback algorithm. Pin a clean-bootstrap path from node data; do not rely on a trusted explorer cache.

Quote and route stages

1. Implement pool/asset exact-identity discovery and stable price/active-liquidity read against actual state.
2. Implement per-pool exact-input and exact-output quotes with [DeFi][FIN-12] Checked tick pricing, fixed-point arithmetic and exact swap-step maths #62/[DeFi][FIN-15] Bounded cross-tick swaps with exact-input and exact-output settlement #65 checked numerical contracts, including path limits and configurable slippage.
3. For nontrivial hooks, either execute/prove the exact permitted result using [DeFi][FIN-19] Authenticated before/after operation hooks and permissions #69/[DeFi][FIN-21] Permissioned extension balance deltas and alternative pricing curves #71 or label the quote unsupported. Static ABI compatibility is not a financial quote.
4. Implement bounded candidate routes and optional split paths, ranking by net user amount including funding/witness/capacity/fee costs under a stated metric.
5. Materialise a transaction with the existing SDK/ProtocolBundle, independently preflight every required Script group, sign the final bytes and classify stale/unknown submission outcomes using [DeFi][FIN-09][M5] Make financial builders recover safely and benchmark contention #59.

Adversarial / UX tests

Deliverables and evidence

Public API must expose confirmed-vs-observed status, quote reference block/OutPoints, underlying script identities, operations, exact/minimum/maximum amounts, fees/capacity and predicted execution bound. Supply an independent clean-room integration and no hidden manual encoding of compiler-owned witnesses. A top-scored route is not evidence of global routing optimality.

End-to-end security flow

flowchart TD
    N["CKB node + actual Cell history"] --> R["Reorg-aware index"]
    R --> D["Discover exact pools, positions and hooks"]
    D --> Q["Model/execute checked quote"]
    Q --> B["Build complete signed candidate"]
    B --> V{"Current state and all groups still valid?"}
    V -- No --> X["Stale or unsupported result"]
    V -- Yes --> S["Submit and observe explicit outcome"]

General audit and release criteria

• This work is confined to ordinary CellScript protocol packages, tested maths, authenticated state and existing off-chain SDK/adapter boundaries. No application action name can authorise a finance-specific grammar, VM or compiler feature.
• Freeze selected schema/domain/operation budget, accountable implementer, independent human review disposition and valid/late-invalid resource ceilings. Any missing generic language primitive must have its own small business-neutral issue and independent-machine verification.
• Execute authentic full CKB transactions with all required Lock and Type groups, preserve original state continuity and distinct off-chain/VM/node/deployment evidence. Retain exact source, compiler/checker, artifact, CellDep, transaction and chain identities. Never claim a deployed or audited result without that evidence.

Design and delivery

• Provide reorg-aware indexing for pool/tick/position/fee/claim and hook identities with exact state OutPoint/chain provenance and safe reconstruction from pinned node data.
• Implement both amount-mode quotes, bounded path and optional split-route selection, user limits and actual hook-adjusted settlement simulations.
• Expose generated SDK APIs for discover→quote→build→validate→sign→submit and a minimal developer-facing trading/liquidity interface.
• Classify supported vs unknown extension behaviour explicitly; an identity receipt alone is not permission to guess a hook's trade outcome.

Acceptance criteria

• Clean index rebuild and node reorg produce consistent authenticated state and explicit stale indicators.
• Quotes match actual CKB-VM execution or fail with concrete unsupported hook/source/state reasons.
• Exact-output and split-route builders respect final amount caps/refunds and every required Script/CellDep identity.
• Off-chain route discovery does not become consensus authority or a promise of globally optimal execution.

Security / scope boundary: No invented EVM storage API, no universal router optimality guarantee and no complete commercial front-end mandate.

General implementation and acceptance rules

• Issue status: proposed. Identify owners, reviewers and any actual review disposition explicitly; no release/deployment permission is implied.
• Deliver these semantics in ordinary CellScript protocol packages, standard library helpers or existing SDK boundaries. New compiler semantics require a separate demonstrably business-neutral failure case and checker/ABI/diagnostics contract.
• Freeze input/step/byte/cycle/capacity budgets, test genuine and hostile final CKB transactions with every required Script group, and archive pinned source/build/dependency/transaction/model identities and applicable gates.

Verified dependencies and implementation sequencing

Entry prerequisites: #61, #63, #65.

Conditional execution capabilities: #69, #71.

Related evidence / integration owners: #55, #59.

Unblocks / consumed by: #78.

Reason for this sequence: The index is an observation service, not consensus authority. Nontrivial hooked quotes must be executed against the admitted extension contract or explicitly classified unquotable.

Dependency links are explanatory; they do not mark code as implemented, grant a reviewer waiver or set native GitHub issue blockers.