[DeFi][FIN-21] Permissioned extension balance deltas and alternative pricing curves #71

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

What does it do? Plain English

An authorised extension may change a trade's final asset amounts or use its own pricing formula. It must never be allowed to create unbacked payouts or silently change the user's trade terms.

Visual walkthrough

flowchart TD
A["Authenticated pool + user intent"] --> B["Authorised extension computes deltas"]
B --> C{"Permission / signed amount / solvency check"}
C -- Bad --> X["Reject"]
C -- Valid --> D["Apply declared curve or fee policy"]
D --> E["Settle all user and extension balances"]

Implementation layer: Hook settlement protocol with independent custom-curve contracts.

Prerequisites: #65 FIN-15 price execution; #66 FIN-16 settlement; #69 FIN-19 hook receipts.

Detailed design and security review

Result permissions are not economic guarantees

A return-delta hook may change what a swapper owes or receives, but successful execution of a hook does not prove that its alternative pricing curve is economically correct. Freeze the return schema, sign conventions, exact-input/exact-output interpretation and the identity of every party whose balance changes. A check-only hook cannot gain debit authority by returning a value in the right byte format.

Contract of an extension result

Bind every delta to the exact hook implementation and permission, pool, current action, specified amount mode, original currency identities and authenticated operation transcript. Require typed signed ranges and safe narrowing, including positive and negative zero-like boundary cases. Define whether the extension adds a fee, rebates an amount, or substitutes pricing entirely; never apply two incompatible price calculations without an explicit combination rule. Any value owed to the extension or from it must appear in the full participant/asset ledger under #66.

Implementation stages

1. Accept a no-delta validation-only hook; ensure the result is checked, not merely present in a witness.
2. Admit a single before-swap signed delta and afterwards a separately authorised after-swap delta. Define application ordering and conflicts.
3. Implement a fully independent custom pricing package using ordinary author-defined functions; compare it against its own reference model rather than the concentrated-liquidity invariant.
4. Implement extended liquidity changes and fees, including owner consent and donation/rebate paths.
5. For intentionally asynchronous designs, issue persistent enforceable orders/claims with a future settlement/cancel path; a returned receipt is not immediately redeemed output.

Hostile test inventory

Scope and evidence

Publish a line-item signed delta ledger and independent curve-model tests for successful, partial and rejected operations. Include a no-hook baseline to detect unintended economic changes. Code pinning, spawned verifier results, actual state transitions and final CKB-VM group acceptance must remain separate evidence categories.

Security flow

flowchart LR
    A["Signed user intent and pool action"] --> B["Exact extension permission + result"]
    B --> C["Apply checked signed delta"]
    C --> D["Independently calculate custom curve"]
    D --> E["Final per-party / per-asset settlement"]
    E --> F{"No unpaid or unauthorised balance?"}

Shared assurance rules

• The protocol owns its economic policy; these issues do not add finance-specific syntax or special compiler behaviour. Any missing business-neutral general primitive needs a separate minimal failing case, versioned contract and evidence.
• Freeze concrete source/chain/ABI/asset roles, numerical bounds, revocation semantics and a named reviewer/waiver disposition before claiming acceptance. No original issue or human review is silently inherited.
• Execute complete actual CKB transactions with all required script groups. Preserve independent model, generated builder, checker mutation, exact source/ELF/CellDep/tx/node evidence and worst success/late-rejection budgets. A valid simulator trace, RPC response or indexer record alone is not authority.

Implementation contract

• Define versioned before/after swap and post-liquidity returned-delta semantics, sign conventions, specified/unspecified amounts, hook compensation and exact-input/output limits.
• Permit one independently authored alternative curve or full/partial pool-pricing replacement, without falsely claiming the original concentrated-price invariant applies.
• Bind return values to precise hook permissions and a final authorised asset/delta settlement; ensure user-declared spend/output limits remain authoritative.
• For deferred/asynchronous cases, return an enforceable persistent order/claim and test later settlement separately; do not report immediate successful swap.

Acceptance

• Independently authored custom-curve and fee/withdrawal hooks execute with matched independently calculated signed deltas.
• Unauthorized or malformed delta, omitted hook debit, double-credit, overdrawn claim and sign/amount-mode conversion reject.
• Exact-input/output user limits and final credited amounts remain valid after applying all hook effects.
• Missing permission, incomplete hook execution, failed settlement and over-budget cases reject at their actual enforcing boundaries.

Explicit exclusions: A trusted interface identity does not certify arbitrary custom-curve economics; the selected package must declare and validate its own financial rules.

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 GitHub dependency links

Core: #65, #66, #69. Downstream: #75 router, #77 quotes, #78 extensions.

These are planning links, not executed acceptance or formal GitHub blocking relationships. Parent: #43.

Verified dependencies and implementation sequencing

Hard prerequisites: #65, #66, #69.

Conditional optional integrations: #70.

Unblocks / integrated by: #75, #77, #78.

Security and scheduling rationale: A verified hook identity/ABI does not guarantee custom-curve correctness. The full signed-delta solvency and user-limit constraints remain mandatory.

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