Repository navigation
[DeFi][FIN-18] Native CKB pool trading with explicit storage-capacity ownership #68
Description
Parent programme: #43. Capability work-item FIN-18 (proposed; no new compiler/release commitment).
In plain English
CKB used as a tradable asset is also needed to occupy Cells and pay transaction fees. The pool must not accidentally sell the storage deposit as though it were liquid trading capital.
Visual explanation
flowchart LR
A["Native CKB input"] --> B["Split trade principal / occupied capacity / fees"]
B --> C["Pool trade or LP operation"]
C --> D["Reserve and claim accounting"]
D --> E["Capacity-safe outputs and refund"]
Primary layer: Currency/custody protocol and SDK.
Dependencies: #61 FIN-11 pool identity; #66 FIN-16 settlement; #52 capacity/custody constraints.
Detailed design and security review
Why native CKB requires a dedicated contract
CKB capacity is simultaneously a potential traded asset, the storage budget of Cells and the source of transaction fees. A token-style reserve amount field does not capture those roles. If a pool holds 1,000 units of capacity but 200 are required to keep its outputs alive, 1,000 cannot automatically be represented as freely withdrawable trading principal.
Explicit monetary/capacity model
Define real occupied capacity from the final output Script/data shape (not a guessed constant), refundable capacity entitlement, tradable reserve amount, fee funding, change and any deposits sponsoring other participants. A policy must bind which participant funds/recovers each unit. Prove output capacities cover their occupied minima after an operation and that claimed CKB liquidity cannot be used simultaneously to pay a network fee or subsidise another user's position.
Implementation phases
- Freeze native currency identity, representation in pool accounting and pairing with approved Type Script-backed fungible assets.
- Implement pool seed/deposit/withdrawal with principal versus occupied-capacity separation, authorised capacity top-ups and refunds.
- Implement swaps in both modes, including exact-output reserve availability, maximum CKB spend and fee attribution.
- Integrate [DeFi][FIN-16] Ordered multi-operation settlement with per-user asset deltas #66 ordered settlement and optional backed claims ([DeFi][FIN-17] Fully backed transferable multi-asset custody claims #67) without mixing tradable reserve, claim collateral and occupied capacity.
- Exercise state growth and closure, reorganisation, negative fee funding and fragmented cell topology.
Adversarial validation
| Malicious or boundary transaction | Expected |
|---|---|
| Consume occupied-capacity floor as trade output | Reject as output under-capacity or invalid reserve |
| Refund storage deposit to attacker | Reject capacity-owner mismatch |
| Claim a CKB payment both as swap principal and network fee | Reject accounting insufficiency |
| Change output data/Lock to alter occupied capacity | Recompute exact occupancy and authorisation |
| Supply an unrelated change Cell as reserve | Reject source and custody identity |
| Attempt a final withdrawal that strands state Cells | Reject unless explicitly authorised closure |
Disclosure and evidence
Publish the amount of actual tradable CKB versus capacity used to store the protocol on every test trajectory. Keep shannons/CKB units, asset amounts and fee units distinct; expose exact occupied/available/refundable accounting through builder metadata. Benchmark occupied capacity growth separately from swap fees and CKB-VM cycles.
State and execution flow
flowchart TD
I["Native CKB and pool state"] --> O["Compute output occupied minima"]
O --> L["Separate tradeable reserve and liabilities"]
L --> S["Settle trade / fee / refund"]
S --> C{"All final Cells funded and owned?"}
C -- No --> X["Reject"]
C -- Yes --> F["Authorised pool successors"]
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 native currency profile without assuming a wrapped token, distinguishing tradable principal from occupied/refundable capacity and transaction fees.
- Integrate native CKB exact-input/output swaps, liquidity, claim redemption, fee/change and storage expansion/closure; specify who funds and recovers capacity.
- Set safe balance equations with mixed fungible tokens and native CKB, using actual CKB capacity checks and group identities.
Executable acceptance
- Native CKB/token swap in both modes, LP deposit/withdrawal and eligible claim redemption complete with explicit fees and refunds.
- Over-withdrawal of occupied capacity, dust outputs, reserve/capacity mix-up, wrong refund owner and fee subsidy by an unrelated party reject.
- Storage expansion/closure and fragmented Cells preserve tradable balances and the authorised capacity owner.
- All-group transaction verification and independent accounts agree at minimum and maximum occupied-capacity bounds.
Boundary: Correct fee estimation alone does not establish native-asset pool support.
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, #66 and #52. Downstream: #75 routing and #77 quotations.
These are planning links, not executed acceptance or formal GitHub blocking relationships. Parent: #43.
Verified dependencies and implementation sequencing
Hard prerequisites: #61, #66, #52.
Unblocks or integrates with: #75, #77.
Technical dependency note: Native CKB has both tradable principal and occupied transaction capacity. Claim interactions additionally use #67 when admitted.
This is a documented logical dependency, not a native GitHub blocking relationship or implementation acceptance.
Activity