[DeFi][FIN-19] Authenticated before/after operation hooks and permissions #69

Parent programme: #43. Capability work-item FIN-19 (proposed; no new compiler/release commitment).

In plain English

Pool owners should be able to attach an independently written programme that checks or adjusts an operation at defined points. It must really execute: listing the programme in a manifest is not enough.

Visual explanation

flowchart TD
A["Pool action + committed hook policy"] --> B["Verify exact hook code and permissions"]
B --> C["Before-hook: check actual result"]
C --> D["Apply pool operation"]
D --> E["After-hook: check actual result"]
E --> F["Bind final state and authorisation"]

Primary layer: Extensible on-chain protocol + exact external execution.

Dependencies: #61 FIN-11 pool configuration; closed #11 exact handles and admitted external execution; #28/#29 only if a later compatible-open hook is truly required.

Detailed design and security review

Execution feasibility is part of the specification

CKB Script groups execute independent validation; one Script cannot simply call a second Script as an Ethereum contract callback. Before admitting a general hook API, choose an enforceable representation: for example, an exact hash-bound verifier executed through a bounded supported child-process/IPC boundary for pure computed results, plus separate genuine hook-owned Cell transitions where state is persistent. A trace supplied only by a builder is not proof of execution.

Lifecycle and permission ABI

Use ten distinct lifecycle points: before/after initialisation, liquidity addition, liquidity removal, swaps and donations. Return-delta authorisation is four additional permission classes, not four more lifecycle entry points. Freeze which callbacks can reject only, provide a typed checked output, modify declared fees or affect the final settlement. Every callback must be tied to a concrete pool ID, exact hook implementation, action/domain tag, original inputs and committed result schema. Empty hook and declared missing callback have distinct states.

Protocol phases

1. Formalise hook-pool binding at initialisation, permission validation and policy-update/immutability rules.
2. Implement exactly one pure checked before-hook and after-hook with pinned code bytes, supported CKB external execution or a verified on-chain validity route, and explicit errors on omission or bad return.
3. Implement a stateful hook whose own authentic Type Cell evolves in the same transaction and which cannot be omitted without rejection by the pool authority path.
4. Admit all lifecycle permission combinations, correct logical order through authenticated commitments, one-action result binding and bounds for IPC/proof/witness/VM cycles.
5. Integrate return-delta hooks only under separate [DeFi][FIN-21] Permissioned extension balance deltas and alternative pricing curves #71 semantics, not as a side effect of checking a callback flag.

Attack and rejection matrix

Delivery gate

Publish two reference hook packages built independently from ordinary source and execute complete pool transactions through all actual required Script groups. Document which logical hook semantics are equivalent, adapted or unsupported under CKB; do not imply synchronous shared-memory callbacks.

State and execution flow

flowchart TD
    P["Pool commits exact hook and permissions"] --> V["Verify hook code and action domain"]
    V --> B["Prove or execute before-hook result"]
    B --> O["Verify pool operation"]
    O --> A["Prove or execute after-hook result"]
    A --> S["Bind authorised final output state"]
    S --> C["All required Script groups accept"]

General implementation, evidence and release policy

• Preserve business-neutral CellScript semantics: exact Script handles, typed transaction views, resource ownership, bounded execution and independent machine checking. Missing general primitives require separate, narrowly scoped issues and actual failing use cases.
• Freeze chosen data/ABI/profile, maxima, code deployment and review disposition before implementation admission. Record positive and hostile CKB-VM tests over complete transactions with correct signature setup, exact ELF/CellDep identities, state predecessors/successors and separate costs for VM cycles, witness bytes and occupied capacity.
• Builder checks and ProtocolBundle dry-runs are helpful but do not replace on-chain authority. No automatic public deployment, external audit claim or core compiler release follows from a completed protocol issue.

Implementation plan

• Define a versioned permission set for ten before/after lifecycle callbacks (initialise, add/remove liquidity, swap, donate) plus four separately authorised return-delta capabilities; preserve these as hook ABI permissions, not language keywords.
• Specify logical sequencing and actual bounded hook invocation/receipt verification with exact code, deployment, pool, operation context, return codec and failure handling; Script-group ordering itself does not establish callback order.
• First support exact separately deployed hooks, including no-hook, read-only, stateful and rejecting cases. Keep later compatible-open selection independent.

Executable acceptance

• Valid before/after callbacks at all admitted lifecycle points work and yield authenticated results bound to one operation.
• All fourteen permissions have positive/negative tests; return-delta permission without its callback is rejected.
• Wrong hook code/pool/context, missing hook, ignored return, malformed response, recursive/self-call ambiguity and over-budget execution fail closed.
• A third-party hook written in ordinary CellScript works without a hook-specific compiler patch.

Boundary: Do not copy Ethereum address-bit permission tricks or assume direct inter-Script invocation; demonstrate an enforceable CKB-native execution contract.

Acceptance policy (all FIN work)

• Status: proposed. Implementer/reviewer unassigned; do not represent an unperformed audit as completed. Freeze versioned API, threat and bounded resource contracts first.
• Core compiler remains protocol-neutral: use ordinary CellScript data types, functions, actions, CKB views and existing generated builders. A demonstrated general-language failure requires its own business-neutral issue.
• All accepted proofs require exact source/compiler/checker/CellDep/transaction identities, independent financial models, hostile full-transaction cases and relevant dev/CI/backend gates. Node/public deployment claims remain separate. No release milestone is inferred.

Verified GitHub dependency links

Core: #61 and closed #11. Optional open selection: #28/#29. Downstream: #70, #71, #73, #74, #78.

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

Verified dependencies and implementation sequencing

Hard prerequisites: #61, #11.

Conditional capability only: #28, #29; not required for the exact-deployment initial path.

Unblocks or integrates with: #70, #71, #73, #78.

Technical dependency note: Default to exact code/CellDep selection and authenticated execution. Compatible-open selection is optional and cannot be treated as proof that a hook actually ran.

This is a documented logical dependency, not a native GitHub blocking relationship or implementation acceptance.