Repository navigation
[DeFi][FIN-24] Position management, ownership transfers and non-custodial subscriptions #74
Description
Umbrella #43 · work-item FIN-24 · proposal / no release milestone.
What does it do? Plain English
Liquidity providers need one consistent way to open, increase, decrease, transfer, collect and close range positions. Subscribers may observe changes but must not gain control of the underlying assets.
Visual walkthrough
flowchart TD
A["Owner opens range position"] --> B["Increase / decrease liquidity"]
B --> C["Collect fees or transfer owner"]
C --> D["Close position and refund"]
B -. "Optional notification" .-> E["Registered subscriber"]
E -. "No custody capability" .-> D
Implementation layer: Position-management protocol and generated SDK.
Prerequisites: #64 FIN-14 range positions; #66 FIN-16 settlement; #69 FIN-19 for callbacks; FIN-26 delegated authority where applicable.
Detailed design and security review
Manageable positions without transferring custody
The position-manager package is an application-facing wrapper around the authentic range-position protocol. A position owner must retain the right to withdraw principal and collect accrued fees, subject only to explicit authorised delegation. A subscription is permission to receive state notifications or enforce a narrowly agreed auxiliary condition, not a signature granting custody.
Lifecycle and state
Define PositionId, owner/approved delegate, current lower/upper ticks, liquidity, accrued fees, current state version and optional subscriber references. Distinguish position transfer from transferring underlying fungible pool reserves. For add/remove operations, reuse the actual #64 fee-growth and tick-update predicates; a wrapper-created record must not bypass them. Handle zero-delta liquidity updates as fee-realisation steps where admitted, with correct settlement and capacity refunds.
Implementation phases
- Build ordinary generated-SDK position mint, increase, decrease, collect, transfer and close actions using exact pool and owner identities.
- Integrate signed intent/limited delegation ([DeFi][FIN-26] Scoped signed intents, delegation, nonces and replay protection #76) without granting permanent unrestricted approval.
- Define a versioned bounded subscription ABI: who may subscribe, what events are visible, authentication, notification order, state mutations (if any) and unsubscribing/revocation.
- Select and document which notification cases are mandatory on chain through enforced state/receipt bindings versus best-effort off-chain watchers; independent Script-group execution does not imply synchronous notification.
- Exercise multiple simultaneous owners and subscribers, stale position state, partial fee collection and independent third-party integration.
Threat cases
| Attempt | Expected |
|---|---|
| Manager substitutes another owner's position | Exact owner/Lock identity reject |
| Collect position fees twice | Accrued-liability balance reject |
| Subscription impersonates position owner | No custody or modification authority |
| Revoked subscriber tries to remain mandatory | Revocation/state-version rules reject |
| Transfer position but retain old approval | Explicit delegate expiry/revocation policy |
| Subscriber omits required notification policy | Mandatory check fails or explicitly best-effort |
Developer acceptance
A new integrator must manage two distinct positions from clean package/toolchain inputs without hand-crafting compiler-owned witnesses, changing the pool verifier or creating unauthorised fee/capacity subsidies. Report which operations can compose within one transaction and which need successive stateful transactions.
Security flow
flowchart TD
P["Owner controls position"] --> M["Manager builds authorised operation"]
M --> V["Real position/tick/fee Scripts verify"]
V --> N["Optional subscribed notification"]
V --> S["Authored final state and capacity"]
N -. "Never grants custody" .-> S
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 position-manager action flow and canonical position owner/range/salt mapping, including authorised transfer, fee-realisation and closing.
- Integrate generated builders, fees vs principal distinctions, capacity refunds and optional delegated operations with exact owner authority.
- Specify opt-in lifecycle subscriptions, notification receipts, subscriber permissions, bounded side effects, failure treatment and clean unsubscribe/revocation.
- If CKB cannot guarantee execution of some notification path, classify it as best-effort off-chain rather than silently treating it as on-chain.
Acceptance
- Independent holders complete create→increase→decrease→fees→transfer→close with authentic state/owner successors.
- Invalid owner, double-collection, duplicate position ID, stale transfer, subscriber impersonation and revoked listener effects reject.
- Subscribers cannot spend underlying position assets and unsubscribe does not leave active enforcement authority.
- Exact SDK/transaction/VM behaviour, CKB capacity, cost and notification/receipt evidence is reproducible.
Explicit exclusions: NFT-like position representation need not share external ERC binary interfaces; notification is not necessarily a synchronous callback.
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
Conditional optional integrations: #69, #76.
Unblocks / integrated by: #75, #78.
Security and scheduling rationale: Use #69 only for admitted on-chain lifecycle subscriptions and #76 for scoped delegated actions; subscriber observation never grants principal custody.
These are referenced planning contracts; no automatically enforced GitHub blocking relationship or accepted implementation is claimed.
Activity