[DeFi][FIN-25] Bounded command-plan routing and authenticated liquidity migration #75

Umbrella #43 · work-item FIN-25 · proposal / no release milestone.

What does it do? Plain English

A user may want to withdraw liquidity, swap assets and re-deposit in one transaction. The plan must preserve every step's authorization, balances and final limits, including when a permitted optional branch fails.

Visual walkthrough

flowchart TD
A["Signed bounded command list"] --> B["Authenticate order and permissions"]
B --> C["Execute each logical step"]
C --> D{"Required step valid?"}
D -- No --> X["Reject"]
D -- Yes --> E["Final settle / sweep / refund"]
E --> F["One authorised complete CKB transaction"]

Implementation layer: Off-chain router and on-chain authorised operation-plan protocol.

Prerequisites: #65 FIN-15 swaps, #66 FIN-16 ordered deltas, FIN-24 positions, FIN-26 signed intent, #58 pure-pool routing; optional claim/native/custom curve modules only when corresponding commands enabled.

Detailed design and security review

Transaction plans are not executable instruction streams

A router can accept an ordered list of user-authorised operations: a swap, liquidity removal, another swap, liquidity provision, fee collection, claim settlement or refund. On CKB this cannot be implemented by pretending an output Cell is spent in the same transaction. The on-chain Scripts must verify actual predecessor Cells, a bounded logical operation transcript and the final successors; any intermediate value is an accounted temporary state, not an independently spendable UTXO.

Command schema and authority

Define a versioned finite command vocabulary, exact operand types, pool/asset/position identities, dependency graph, maximum operation count, expected return/result envelopes, signed user limits and CKB capacity owners. Every command needs a required/optional label with an explicit state-effect policy. An optional branch may be skipped only when the entire alternative transaction shape is authenticated and does not require a failing Script group to succeed. Signed permissions constrain branches: a wallet approval for one route cannot authorise a different recipient or extra fee.

Implementation stages

1. Start with pure two-pool swaps and exact-output reverse quotations, using the pure AMM route portion of [DeFi][FIN-08][M4] Enforce shared-payment allocation and bounded multihop routes #58 without requiring [DeFi][FIN-06][M3] Implement escrowed partial-fill orders and cumulative rounding #56/[DeFi][FIN-07][M3] Settle an order against an AMM with enforced asset flows #57 order settlement.
2. Add remove-liquidity→swap→re-add as one logical sequence; authenticate intermediate pool/position/tick and fee changes and one final real successor per consumed persistent state.
3. Add settlement commands for genuine backed claims ([DeFi][FIN-17] Fully backed transferable multi-asset custody claims #67), native CKB ([DeFi][FIN-18] Native CKB pool trading with explicit storage-capacity ownership #68), limited delegation ([DeFi][FIN-26] Scoped signed intents, delegation, nonces and replay protection #76) and optional hook deltas ([DeFi][FIN-21] Permissioned extension balance deltas and alternative pricing curves #71), with per-command capability requirements.
4. Define stateful migration across distinct deployed pool/position policies. An immutable old policy without a spend/migrate authority must remain unsupported; creating a new unrelated position is not migration.
5. Build canonical SDK command encoding and all-group preflight; record stale-state rebuild and original-user-intent preservation.

Negative test matrix

Acceptance

Test plan lengths 1, 2 and maximum with multiple owners, distinct/repeated pool operations, empty/failed optional branches, and exact signing/CKB-VM parity. Distinguish a builder's planned path from an authenticated final on-chain transition. Preserve full operation budgets and zero outstanding liabilities.

End-to-end security flow

flowchart TD
    I["Signed bounded command plan"] --> D["Resolve real input Cells and exact scripts"]
    D --> O["Verify logical operations in order"]
    O --> B["Accumulate per-asset / per-owner deltas"]
    B --> C{"Every selected branch authorised?"}
    C -- No --> X["Reject whole transaction"]
    C -- Yes --> F["Validate final outputs, limits and refunds"]

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.

Implementation contract

• Define bounded versioned action plan for exact-input/output swaps, split routes, position operations, claim/native settlement, sweeps and controlled migration.
• Support repeated-pool sequences via independently verified intermediate logical states; do not pretend one transaction output is a consumable input.
• Specify optional branches as authenticated alternative protocol paths with complete state/obligation semantics; an unexecuted failing Script group cannot simply be ignored.
• Real migrations must actually consume an authorised predecessor; immutable old deployments that cannot migrate remain explicitly unsupported.

Acceptance

• Initialise+provide, remove→swap→readd, claim-funded and exact-output/refund multi-operation scenarios execute under user limits.
• Repeated-pool and optional branch scenarios reproduce state, amounts and permitted errors; no stranded debt or unauthorised partial application.
• Unknown command, stale state, forged signer, changed recipient/fees, missing prerequisite and failed required Script group reject.
• SDK, mathematical model and all-group CKB-VM match final bytes, complete asset movements and cost ceilings.

Explicit exclusions: Commands are ordinary application data. No generic cross-contract call, hidden parser syntax or unbounded script executor.

Programme-wide acceptance discipline

• Proposed only; assign accountable implementer/review disposition, versioned threat/ABI/numeric limits and exact evidence before claiming implementation.
• Financial semantics live in ordinary CellScript protocol packages and generated builders, not hard-coded finance language constructs. A genuine general core gap must become a separate business-neutral issue.
• Preserve exact compiler/checker/source/ELF/CellDep/transaction/model identities, full-transaction positive/hostile cases, frozen resource ceilings and applicable gates. No node deployment or human audit is inferred.

Verified dependencies and implementation sequencing

Hard prerequisites: #65, #66, #74, #76, #58.

Conditional optional integrations: #67, #68, #71.

Unblocks / integrated by: #78.

Security and scheduling rationale: #58's pure pool route slice is independent of #56/#57 order settlement. Optional claims, native capacity and custom deltas are required only for commands that expressly use them.

These are referenced planning contracts; no automatically enforced GitHub blocking relationship or accepted implementation is claimed.