From 624b1299590df5f3cdb1206711f27939efa0da93 Mon Sep 17 00:00:00 2001 From: Simon Meier Date: Thu, 18 Jun 2026 17:11:12 +0200 Subject: [PATCH] review comments for the docs I've read so far --- README.md | 2 ++ docs/architecture.md | 26 ++++++++++++++++++++++++-- docs/workflows.md | 10 ++++++++++ 3 files changed, 36 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0c7020d2..3072221d 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,8 @@ factories instead of a custom off-ledger balance model. | Operator backend | Implemented | HTTP API, JSON Ledger API driver, idempotency, indexing, and recovery | | Stable-pool extension | Example | Separate Daml project consuming the DEX DAR | +REVIEW(SM): check whether DEX .dar defines Daml interfaces that decouple the two apps + ## Who Should Use It? | You are | This helps because | diff --git a/docs/architecture.md b/docs/architecture.md index 050b9da0..112b4f8e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -9,6 +9,7 @@ builders how to build a real exchange directly on top of: - Token Standard V2 allocations and batch settlement - registry-backed `InstrumentConfiguration` + (REVIEW(SM): I'm a bit unsure about this line, as the DA registry is only one option of how to implement a token.) - Canton privacy, routing, and atomic transaction semantics ## Design Inputs @@ -53,7 +54,7 @@ Splice's `token-standard-v2-upcoming` branch: - `FinalizedAllocation.extraTransferLegSides` - settle results that return next-iteration allocation state -Those changes are what make it realistic to use allocations not only for trade +Those changes are what make it possible to use allocations not only for trade reservation but also for long-lived pool inventory. ## Core Decisions @@ -72,11 +73,13 @@ reservation but also for long-lived pool inventory. 4. Arbitrary `InstrumentId` pairs - the DEX should support any pair the registry exposes, not just "cash vs asset" flows + REVIEW(SM): "the registry exposes" --> change to any pair of InstrumentId whose registries implement the V2 holding and allocation APIs 5. Instrument lifecycle stays standard - bonds, options, escrow obligations, margin-like positions, and LP tokens should all remain token-standard holdings whose semantics come from instrument configuration and lifecycle facilities + (REVIEW(SM): note that the token standard does not mandate instrument configurations and lifecycle facilities. There seems to be a bit of a misunderstanding here.) 6. LP token is first-class - pool shares should be their own instrument and be holdable, transferable, @@ -147,7 +150,7 @@ The instrument layer defines what is being traded. Expected concepts: -- `InstrumentConfiguration` +- `InstrumentConfiguration` (REVIEW(SM): not standard. However the `metadata-v1.yaml` does list some properties that you can query about an instrument.) - registry-managed transfer rules and credentials - versioned instrument semantics - optional external identifiers such as ISIN or CUSIP @@ -212,6 +215,20 @@ The intended model is: - the off-chain operator proposes actions, but the ledger-visible contracts validate the quantity, pair, expiry, side, and reserve references being used +REVIEW(SM): good design choices here. Looking forward to reading the Daml code. + Consider also referring to the https://github.com/canton-foundation/canton-dev-fund/blob/main/proposals/2026-05-BitSafe-decentralization-manager.md for decentralizing the execution + of this validation logic. + + Futhermore, if you want to decentralize the off-ledger automation driven by the backend + then consider leveraging the approaches used in Splice for the DSO automation. The gist + is described here: https://docs.canton.network/sdks-tools/api-reference/splice-architecture#decentralized-transaction-validation-and-automation + + Efficiently batching committments to on-ledger actions was recently implemented for traffic based app rewards + in https://github.com/canton-network/splice/blob/main/daml/splice-amulet/daml/Splice/Amulet/RewardAccountingV2.daml. + Happy to give you access to the design doc that has a detailed high-level description: + https://docs.google.com/document/d/1Uff-Id4umJBqBo6GLDupuqFfJnp_iVi4BFRkFdcmo_g/edit?tab=t.0#heading=h.j1o9vy5fqmrz + + This also means we should avoid designs where a routine action touches every pool allocation at once. The implementation now follows this for all hot-path flows: @@ -337,6 +354,10 @@ Lifecycle management then becomes a versioning problem: In other words, the registry side should be able to take one instrument version in and hand back a new version with the lifecycle side effects applied. +REVIEW(SM): not that this functionality has not (yet) been standardized. It might +be worth to call this out here. Until it is standardized DEX operators do have the +option of doing custom integrations with the registries that implement such life-cycling. + The important point is that the traded asset remains a standard holding even when its lifecycle is rich. @@ -362,6 +383,7 @@ The reference architecture has a deliberate split: - OTC and RFQ flows can be implemented against the current `TradingAppV2` surface + REVIEW(SM): this is confusing -- TradingAppV2 can support V1 allocations, but really shines when V2 allocations are involved. What is this trying to say here? - pool-backed liquidity should be implemented only against a branch that includes the V2-style allocation changes diff --git a/docs/workflows.md b/docs/workflows.md index 32e90d89..9e9f0d8c 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -41,6 +41,9 @@ It does not need on day one: Those are worthwhile later features, but they are not required to validate the core Canton-native design. +REVIEW(SM): also consider making an argument that the included use-case cover X% for a large X +of the Uniwswap market volume -- I don't know whether your current pick is the right one, but it surely is if it addresses a large share of the market volume. + ## Workflow Design Principles 1. One workflow, one business object @@ -130,6 +133,7 @@ state and cancellation rules. Purpose: - define that the DEX supports trading a given base and quote `InstrumentId` + Inputs: - base instrument id @@ -143,6 +147,12 @@ Inputs: On-ledger flow: 1. `DexOperator` creates `DexPair` + +REVIEW(SM): to verify later in the review: what contract governs the creation of the DexPair? Is there a DexRules contract +that makes it easy to reason about how the DEX's contract state can evolve? Also consider whether there are two or more +apps in this design that could actually be decoupled with suitable Daml interfaces. That is only worth it if each of them +can be understood and reasoned about in isolation, and the interface is narrow enough to be useful. + 2. `DexPair` records the supported instruments and execution policy 3. off-chain services subscribe to the pair for matching or pool operations