Skip to content

review comments for the docs I've read so far #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
meiersi-da wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

review comments for the docs I've read so far #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
26 changes: 24 additions & 2 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.

Expand All @@ -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

Expand Down
10 changes: 10 additions & 0 deletions docs/workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
Loading