Skip to content

[DeFi][FIN-06][M3] Implement escrowed partial-fill orders and cumulative rounding #56

Open

Description

@a19q3

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

Scope and invariants

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions