[DeFi][FIN-11] Canonical pool identity, permissionless creation and reusable state layout #61

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

What problem does this solve? — In plain English

Different asset pairs should be able to create independently identifiable pools without deploying different compiler-generated logic for each pair. Pool state, asset custody and configuration must be unambiguous.

Visual explanation

flowchart LR
A["Two real asset identities"] --> B["Canonical pool configuration"]
B --> C{"Existing pool identity?"}
C -- Yes --> X["Reject duplicate / resolve existing"]
C -- No --> D["Create authenticated pool state"]
D --> E["Independent pool with shared code"]

Primary implementation layer: On-chain protocol + state architecture.

Dependencies / start conditions: #43 baseline; #52 authentic custody; closed #11 exact code identity.

Detailed design and security review

Developer story and persistent state

An integrator selects two genuinely enforcing token Type Scripts, a fee mode, tick-spacing profile and optional extension policy, and creates a pool without editing compiler code. A second integrator creates an unrelated pool using the same published verifier binaries. Their pool states, reserves and liabilities must remain independently spendable. Discovery is deterministic, but an indexer entry is never itself consensus authority.

The application-owned key must bind ordered complete currency Script identities, immutable fee and tick-spacing configuration, extension code/policy identity, chain domain and configuration version. Specify the unique genesis anchor and whether same-pair pools with different fee profiles are allowed. Pool state must distinguish price, tick, active liquidity, authenticated tick-root, fee liabilities, backed claims and authentic reserve inventory. Reserve custody enforcement must require real matching pool transitions.

Implementation sequence

1. Freeze canonical byte encoding, asset ordering, admitted token modes, duplicate-pair rules and genesis identity; produce byte-identical host/VM/SDK vectors.
2. Define a permissionless creation path for admitted configurations, with any access restrictions scoped explicitly to a token or extension policy.
3. Implement exact-code pool creation with authentic capacity funding and all Lock/Type Script groups. Do not assume a passive resource badge is a validating custody rule.
4. Implement chain-context-aware discovery; test pool A and B independently, then concurrently under competing builders to measure shared-state contention.
5. Freeze asset/share/claim/fee balance-sheet domains and their owning Scripts before implementing dependent tick and position state.

Adversarial review

Design decisions to publish

Choose whether pool identity is anchored by a Type ID or another actual CKB uniqueness mechanism, how policy upgrades are authorised (initially exact/no implicit upgrade), and which state topology avoids one universally spent manager Cell. Publish creation transaction topology, canonical vectors, two-pool costs, group coverage and the independent verification ledger.

Security flow

flowchart TD
    K["Canonical asset/policy key"] --> I["Exact pool identity and genesis"]
    I --> C["Authenticated creation transaction"]
    C --> V{"All required scripts accept?"}
    V -- No --> X["Reject"]
    V -- Yes --> P["Independent pool state and reserves"]

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 canonical PoolKey-like application struct: complete asset Script identities, fee mode, tick spacing, hook identity/permissions, network and deployment context; freeze ordering, uniqueness and asset admission.
• Choose bounded authenticated pool/tick/position/custody layouts and a definite liability model for principal, fees and claims. Compare per-pool versus shared-vault contention without forcing every pool to spend one universal Cell.
• Make admitted-profile creation permissionless, with explicit exceptions for separately permissioned hooks or token profiles; derive discovery identities from committed facts.

Acceptance checklist

• Two independent pools with different admitted assets and parameters share the same deployed protocol implementation and transact without spending a global coordinator.
• Duplicate identities, swapped assets, wrong chain/ELF/CellDep and forged pool genesis are rejected by correct on-chain policy.
• Balance-sheet invariants distinguish reserve principal, position fees, claim backing and other liabilities; show real complete-transaction evidence.
• Canonical pool key, pool creation, lookup and fee/capacity metadata are reproduced by builder and verifier with exact resource budgets.

Explicit boundary: PoolKey is application data; no new pool keyword, compulsory global singleton or automatic permissioned deployment.

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: #52 and closed #11. Downstream: #63 tick state, #66 settlement, #69 hook execution.

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

Verified dependencies and implementation sequencing

Hard prerequisites: #52 authentic pool/LP custody; closed #11 exact handles; umbrella #43.

Unblocks: #63 persistent tick index, #66 ordered accounting, #69 hooks.

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