[DeFi][FIN-14] Range positions, liquidity updates, fee-growth accounting and donations #64

Umbrella: #43 · Proposed application capability · FIN work-item FIN-14. No milestone, implementer, reviewer or release approval is implied.

What problem does this solve? — In plain English

Two liquidity providers may fund different price ranges. The protocol must update active liquidity and pay each provider only the fees earned in their range.

Visual explanation

flowchart TD
A["Authenticated position + range"] --> B["Add / remove liquidity"]
B --> C["Update tick gross/net + active liquidity"]
C --> D["Accrue fees / donations by range"]
D --> E["Claim earned fees or close position"]

Primary implementation layer: Liquidity position protocol.

Dependencies / start conditions: FIN-11 pool identity; FIN-12 price maths; FIN-13 tick state; #52 authentic custody.

Detailed design and security review

Financial model and distinct ownership

An application position identifies its owner, pool, lower/upper tick, independent salt/nonce and current liquidity. It is not fungible with the constant-product LP shares in #52/#54. A position is entitled to its own principal and accumulated fees: the global fee growth and tick-outside values determine what was earned inside the selected interval.

Freeze the tick gross/net liquidity equations, active-liquidity effects upon crossing, inside/outside fee-growth update rules, fee rollover representation, donation policy and the obligation to preserve other positions' entitlements. A donation must not convert itself into a free LP position or pay out to positions not active under the selected rule.

Implementation sequence

1. Create and validate range position identity, owner consent, unique positions with identical ranges but different salts, and exact allowed ranges/tick spacing.
2. Add/increase/decrease/zero-delta position operations. Authenticate every touched tick and pool successor; exercise current-state continuous transaction lineage.
3. Implement global and tick-outside/inside fee growth and collect/realise operations. Separate principal, earned fees, protocol/hook charges and CKB capacity refunds.
4. Compose with cross-tick state updates ([DeFi][FIN-13] Authenticated sparse tick index with complete next-boundary proofs #63/[DeFi][FIN-15] Bounded cross-tick swaps with exact-input and exact-output settlement #65); verify active liquidity whenever price crosses a position boundary.
5. Support explicit authorised ownership transfer/close. Rich manager UX belongs to [DeFi][FIN-24] Position management, ownership transfers and non-custodial subscriptions #74.

Executable test inventory

Review outputs

Publish an explicit state-transition table and independent accounting oracle. Record reserve principal, share/position liabilities, fees outside/inside, native capacity, rounding losses, transaction bytes and all relevant Script groups. No claim that an NFT label alone enforces positions.

Security flow

flowchart TD
    I["Owner + range + salt"] --> L["Authorised liquidity delta"]
    L --> T["Update authenticated tick gross/net"]
    T --> F["Track global/outside/inside fee growth"]
    F --> C["Claim fee or remove principal"]
    C --> V["Verify all successor liabilities"]

Source-contract and release discipline

• Reuse the existing CellScript transaction-view, resource-lifecycle, exact Script-handle, ProtocolBundle and generated-builder contracts. Do not invent a finance-specific parser/IR/codegen branch, implicit cross-Script call or a second transaction serializer.
• Freeze the semantic support matrix, named implementation owner, explicit reviewer/waiver disposition, transaction and byte budgets before acceptance. An arbitrary unchecked witness is not execution evidence.
• Full-transaction CKB-VM adversarial negatives must fail at the intended enforcing Script with otherwise-valid signatures and correctly constructed participating groups. Maintain source/ELF/CellDep/transaction/node identities, independent reference vectors, full gates and disclosed unknown outcomes.
• These issues do not assert public deployment or a new compiler release.

Implementation scope

• Define author-owned position identity (owner, range, salt), position lifecycle, add/remove/zero-liquidity modification and authorised transfer/closure.
• Maintain global and tick-outside/inside fee-growth records, active liquidity and donation attribution with checked rounding and no principal-fee conflation.
• Preserve existing fungible LP-share contracts under [DeFi][FIN-02][M1] Enforce authentic pool custody, asset identity and LP supply #52/[DeFi][FIN-04][M2] Complete constant-product AMM/LP lifecycle with generated builders #54; range positions use a separate application schema and economic rules.

Acceptance checklist

• Two owners with overlapping, disjoint and identical-but-distinct positions accrue exactly their independent fee entitlements.
• Correct tick changes, fee collection, zero-liquidity fee-realisation, donations and position closure execute in linked complete transactions.
• Repeated collection, ownership substitution, crossing-boundary rounding, counterfeit positions and attempts to take principal as fees reject.
• Independent accounting model agrees on positions, global fees, per-range accrued fees and authentic reserves under frozen budgets.

Explicit boundary: A position identifier or NFT wrapper is insufficient without the executed liquidity and fee accounting.

General scope and evidence gate

• This is application/protocol/SDK work, not a new CellScript grammar feature, VM opcode or finance-name-specific code generation.
• Before acceptance: freeze semantic contract, threat model, limits, role/authority boundary and accountable implementer/review disposition (unassigned initially).
• Run independently modelled positives and targeted adversarial cases in actual CKB-VM with all required Script groups, pinned sources/artifact/CellDep/transaction identities and the applicable dev/CI/backend gates. Distinguish node and public deployment evidence.
• A demonstrably missing business-neutral language capability needs a separate general-purpose issue and independent-checker/ABI/diagnostic acceptance. Opening this issue is not release authorisation.

Verified GitHub dependency links

Core: #61, #62, #63, #52. Downstream: #65, #70, #74.

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

Verified dependencies and implementation sequencing

Hard prerequisites: #61, #62, #63 and authentic custody from #52.

Unblocks: #65, #70, #74.

Status: These are explanatory GitHub cross-links and do not set native GitHub blocking relationships, authorise a compiler change, or certify dependent implementation.