Repository navigation
[DeFi][FIN-06][M3] Implement escrowed partial-fill orders and cumulative rounding #56
Description
Implementation ownership — protocol-first, no finance-specific compiler feature
Primary implementation layers: DeFi order/escrow protocol package + generated transaction builder. Order, fill_order, cancel_order, maker/taker, cumulative pricing and dust are application-defined vocabulary. They do not belong in CellScript's grammar, IR, runtime opcode set or compiler-recognised dispatch.
Implementation shape: define an ordinary persisted Order Cell with immutable economic terms and authenticated escrow assets; its permitted actions spend the old state and validate exactly one correctly priced remainder/successor or authorised closure. Use #52's genuine asset/custody model, #53's safe arithmetic and existing typed transaction views. The financial checks (price, cumulative entitlement, payment recipient, replay/cancel policy) run in actual on-chain Scripts, not solely in quote-building code. Generated SDKs construct fills/cancels and encode normal witnesses.
Acceptance interpretation: demonstrate real, continuously linked partial fills and malicious underpayment/cancellation tests using existing CellScript semantics. This work does not introduce a compiler keyword order, an in-language order-book engine, or an EVM-like cross-contract call.
Compiler-change gate (all FIN work): This issue does not authorise finance-specific grammar, IR, opcodes, codegen branches or hidden protocol semantics. First try existing general CellScript constructs. Any genuinely missing general capability needs a minimal failing application, a non-financial use case, its own narrow issue and independent checker/ABI/resource/gate acceptance as required by #43 §2.2. Application correctness and builder convenience are distinct from language support.
Umbrella: #43 FIN-06/M3. Proposed implementation, not an accepted financial product.
Owner roles: order protocol + generated-builder engineers; reviewer unassigned.
Dependencies and parallelism
- Hard contracts: [DeFi][FIN-02][M1] Enforce authentic pool custody, asset identity and LP supply #52 FIN-02 (asset identity, escrow/custody and authority) and [DeFi][FIN-03][M1] Freeze checked financial arithmetic, rounding and reference model #53 FIN-03 (numeric bounds and reference model).
- Pre-implementation decision gate: freeze [DeFi][Application/Protocol] EVM-class finance on CKB with CellScript #43 D09a–D09d (zero incremental payment, minimum sold amount/payment per fill, final dust/exception, surplus donation versus future credit) plus order-specific D10 expiry/clock policy.
- May develop in parallel with [DeFi][FIN-04][M2] Complete constant-product AMM/LP lifecycle with generated builders #54 FIN-04 pool lifecycle; pool integration is intentionally owned by FIN-07, not required for standalone orders.
- Downstream: FIN-07 ([DeFi][Application/Protocol] EVM-class finance on CKB with CellScript #43 order/pool settlement), FIN-09 recovery/unknown outcomes.
Scope and invariants
- Create an order with actual escrow of the sold asset, exact sold/requested Type Scripts, committed immutable rational price N/D, proceeds recipient, remainder recipient, fill limit, authoriser, cancellation authority and optional explicitly enforceable expiry.
- Repeated partial fills must consume the previous authentic order state and produce exactly one permitted remainder; support final fill and authorised cancellation. Maker need not come online for each permitted fill.
- Specify cumulative maker entitlement across fills: use a formal cumulative pricing/rounding rule and independent integer reference model, preventing a taker from exploiting per-fill rounding over many small fills. Maker aggregate outcome and individual taker fairness must be tested separately.
- Implement D09a–D09d consequences explicitly: zero-payment fills, minimum increments/floors, terminal dust, excess payment/donation versus credit. Do not let a builder decide these semantics by convention.
- Build and validate with existing exact-handle, ProtocolBundle and generated SDK facilities. Define fees, change/capacity owners, signed intent and safe stale-order handling, without replacing on-chain validation with builder trust.
Acceptance
- Versioned full order/escrow/receipt topology, D09a–D09d, D10, widths, bounds and all authorisation and settlement semantics recorded before accepted protocol implementation.
- Continuous full-transaction executions: create → multiple partial fills by distinct takers → final fill; and separate create → fill → cancel; real predecessor lineage and enforcing asset Scripts retained.
- Independent exact-integer model and generated builders agree with all executed amounts, maker entitlement, per-taker economics, reserve and capacity changes at zero/minimum/maximum/dust/rounding boundaries.
- Hostile maker-payment underfill, zero-payment forbidden path, excessive fill, wrong recipient/asset, replayed old state, forged successor, changed price, unescrowed input, unauthorised cancel and stale rebuild reject at the intended boundary.
- Clear failure stages, exact artifact/input/output/witness/dependency hashes, full transaction costs, worst-case rejection outcomes, checker mutations, applicable dev/CI/backend gates and review disposition recorded.
Non-goals: a CLOB engine, market-order matcher, unrestricted multi-order routing, Oracle or lending. FIN-07 later combines orders with AMM. Source: #43 §§4 (D09), 5–6, 8, 10–12.
Dependency cross-links (confirmed GitHub issues)
Hard dependencies: #52 FIN-02 custody and #53 FIN-03 numeric semantics, plus approved #43 D09a–D09d/order D10 decisions. Parallel with: #54 FIN-04, which is not necessary for standalone order acceptance. Required by: #57 FIN-07.
Umbrella dependency graph and authoritative financial acceptance: #43.
Activity