Dark pools — design outline + resolved decisions
Status: Design walkthrough complete (2026-06-02). Decisions baked into Technical spec §11.1; new open questions captured in §11.2. Runs in parallel to existing Stage 1 / 2 implementation flow. Pre-PoC.
Audience: engineers + architects. Captures the decision walkthrough that gated implementation planning.
1. Purpose
This document captures:
- A one-page architecture summary so a reader can place implementation slices without re-reading the full spec.
- The resolved design decisions from the 2026-06-02 walkthrough — v1 defaults + forward intent for each of the 13 original open questions plus appendix opens.
- The new open questions surfaced during the walkthrough that carry forward.
- The slice-zero PoC proposal, now refined with the resolved decisions baked in.
Working assumption about flow: the existing Stage 1 / 2 implementation queue continues in parallel. After the upcoming planning session, priorities may shift toward the slice-zero PoC.
2. Architecture summary
2.1 State machine + primitives
- Order state machine extends settlement-flow.md with two new pre-Invoice states:
Committed(Pedersen commitment on chain) andMatched(UCAN attestation accepted by on-chain matcher). - Confidentiality primitives reuse the DBC stack: Pedersen commitments for price/size/side hiding; stealth addresses for recipient hiding; RingCT for cash-leg unlinkability.
- DBC fungibility across pools via a global
PoolRegistry.soldirectory mapping(chainId, poolId, dbc_id) → homeSpentBookAddr(multi-tenant-aware).
2.2 Four bridging layers
| Layer | What | When |
|---|---|---|
| 5.1 L1 ↔ pool | Per-pool Railgun-aware bridge contract on mainnet | Stage 3+; stubs in v1 |
| 5.2 Pool ↔ pool | Three routing mechanisms over a shared PoolRegistry: direct sync lookup, lease + commit, burn-mint | v1 core (lease + commit is default) |
| 5.3 Match → settlement DVP | DarkPoolSettlement.sol atomically settles both legs | v1 core |
| 5.4 EIL external interop | Ethereum Interoperability Layer integration | Stage 3+ (separable layer) |
2.3 Matcher as registered code + operator-Party trust
Matcher is registered code, off-chain execution by a trusted operator-Party. Three verification tiers — T1 signed (v1), T2 optimistic (forward), T3 ZK/TEE (Stage 4+). Operator is a Party in the conceptual model. v1 disputes are post-hoc Relationship-level reputation events; bond sizing + dispute mechanics deferred.
2.4 SpentBook lease primitive — three use cases
- A Cross-pool spend atomicity (default 10s window)
- B Wallet → pool liquidity provision (default 30min)
- C Crossing-time lease for over-committed interest (default 3s; v2 advanced model)
Event-driven lifecycle — LeaseAcquired / Finalized / Released / Expired events; no polling.
2.5 Composite wallet across pools
Single wallet, N pool memberships. New darkpool/ stream (6th data-type family per the stream-per-data-type-family principle). Composite UI aggregates DBC holdings, open commitments, active leases, fills across all pools. Eventually consistent — flat v1 SLAs (60s stale-indicator, 5min refuse-action, sync re-verify on active actions).
2.6 Search and discovery
- Intra-pool: traders submit search hints (ECDH-encrypted side / price-band / size-bucket / instrument) alongside Pedersen commitments. Operator-Party triages, requests reveals for promising pairs.
- Cross-pool: digest publication every 10 blocks to
DiscoveryRegistry.sol+ neutral discovery agent + bilateral handshake via cross-persona-messaging. - Pool-as-searcher (Appendix B) is v2+, not v1.
2.7 Pricing modes
| Mode | Mechanism | v1 reach |
|---|---|---|
| P1 Reference-price cross | Match at oracle ± band | Slice-zero scope (NAVOracle backed) |
| P2 Periodic auction | Uniform-clearing-price auction | v1 mode-aware, not slice-zero |
| P3 Negotiated cross | Off-chain neg + matcher verify | v1 mode-aware, not slice-zero |
3. Resolved design decisions (2026-06-02 walkthrough)
The original 13 open questions walked in clustered order, with v1 defaults + forward intent. Full detail in Technical spec §11.1.
Cluster A — Topology
- Q1 Pool deployment: Multi-tenant by design, deployment flexible. Asset-to-pool granularity deliberately undecided.
- Q2 PoolRegistry placement: Hub cocoon-L2 instance for v1. Forward direction = L1 (advertising + trust roots) + L2 hub federation (flow coordination).
Cluster B — Routing
- Q3 Lease duration defaults: A=10s / B=30min / C=3s; SpentBook hard maxes 60s / 24h / 30s. Per-venue configurable.
- Q4 Routing mechanism selection: 5.2.b lease+commit as default for cross-pool fills. 5.2.a as operator-config override; 5.2.c only for explicit migration.
Cluster C — Wallet
- Q5 Stream allocation: New
darkpool/stream. Confirmed stream-per-data-type-family principle for the wallet. - Q8 Composite-view freshness: Flat v1 defaults (60s stale-indicator / 5min refuse-action / synchronous re-verify on active actions). Tiered per-pool SLA contracts are forward intent.
Cluster D — Operator trust
- Q10: v1 T1 (signed) only. T2 (optimistic) and T3 (ZK/TEE) mechanics — bond sizing, dispute window, matcher-replay gas budget — deferred to dedicated follow-on sessions.
Cluster E — Oracle
- Q11: O1 (push), tier-graded by instrument class. Slice-zero scope = NAV-priced regulated instruments only (existing NAVOracle.sol). Crypto-asset + OTC wait until test-feed infrastructure is built.
Cluster F — Aggregator + interop
- Q12 Aggregator failure: Refund + 1 internal retry as v1 default; per-pool configurable.
- Q13 EIL timing: design assumes EIL mainnet first; EIL stays a separable retrofittable layer.
Cluster G — Withdrawal / freshness
- Q6 Match-attestation freshness: 5 min default, per-venue configurable.
- Q7 Withdrawal reveal scope: operator-only cleartext as v1 pragmatic; ZK-attested withdrawal proof preferred long-term.
Cluster H — Advanced model
- Q9 Over-commitment: Not in v1. SpentBook lease primitive is forward-compatible substrate; wallet-side policy + UX is v2 work.
Cluster I — Search opens (Appendix A)
- Hint encryption (v1): ECDH (trader-Persona × operator-Party) + AES-GCM. ZK-attested proofs preferred long-term.
- Information scope: side + bucketed price-band + size-bucket + instrument. Per-pool bucket granularity.
- Digest publication cadence: every 10 blocks default. Adaptive cadence deferred.
Cluster J — Pool-as-searcher opens (Appendix B)
- Not in v1. §6.5 passive auto-aggregator covers v1 needs. Reputation primitive + policy versioning + reciprocal policies + conflict resolution all v2.
Design principles confirmed
- ZK-first, cleartext fallback only where ZK isn't viable for v1. Applies across the design — every cleartext reveal in v1 is a pragmatic starting point with ZK as the preferred evolution.
- Wallet stream per data type family. Stream management feels natural to providers + users; new data type family → new stream.
4. New open questions surfaced during the walkthrough
Three carry forward and should be resolved alongside slice-zero scoping:
- Asset-to-pool granularity — whether one pool contract serves one asset, one asset class, or multiple assets. Decide alongside slice-zero implementation plan.
- L1 advertising/trust-root ↔ L2 hub-coordination interface — forward architecture has pool advertising on L1 and flow coordination on L2 hubs. How the two layers interface (registry sync, trust-root propagation, audit anchors) needs design. Probably extends §5.4 EIL territory.
- Test-feed infrastructure for non-NAV instrument classes — cocoon-side oracle mirror for external feeds (Chainlink Data Standard etc.) and its test harness do not yet exist. Building this is a v2 prerequisite for crypto-asset and OTC modes.
5. Decision dependencies — which questions block which slices
(Now mostly resolved; preserved for traceability.)
| Slice | Was blocked by | Status |
|---|---|---|
| DP-1 OrderRegistry extension + Pedersen | Q1; Cluster I | ✓ Unblocked |
| DP-2 Matcher + UCAN | Q10, Q11 | ✓ Unblocked (T1 + O1) |
| DP-3 DarkPoolSettlement DVP | Q1, Q2 | ✓ Unblocked |
| DP-4 L1 Railgun on-ramp | Q13 + Railgun Workstream 1 | Stage 3+ |
| DP-5a Direct cross-chain lookup | Q1, Q2 | ✓ Unblocked |
| DP-5b Lease primitive | Q3, Q5 | ✓ Unblocked |
| DP-5c Burn-mint | Q1, Q2 | ✓ Unblocked |
| DP-6 Multi-pool wire-up | Q1, Q2, Q4 | ✓ Unblocked |
| DP-7 Oracle integration | Q11 | ✓ Unblocked for NAV; crypto-asset/OTC blocked on new Q3 (test feeds) |
| DP-8 Auto-aggregator | Q12, Q4 | ✓ Unblocked |
| DP-9 EIL bridge | Q13 | Stage 3+ |
| DP-10/11 T2/T3 verification tiers | Q10 | Deferred (own sessions) |
| DP-12 Search hints | Cluster I | ✓ Unblocked |
| DP-13 DiscoveryRegistry | Cluster I | ✓ Unblocked |
| DP-14/15 Liquidity policy + pool-as-searcher | Cluster J | v2+ |
6. Slice-zero PoC — refined
A minimum-viable single-pool PoC to validate the architecture end-to-end before scoping the full slice plan. The user has indicated priorities may shift toward this PoC after the upcoming planning session.
| Aspect | Scope |
|---|---|
| Slices | DP-1 (OrderRegistry extension + Pedersen) + DP-2 (matcher + UCAN, T1 signed) + DP-3 (DarkPoolSettlement DVP) |
| Topology | Single-pool; PoolRegistry stubbed |
| Mode | P1 reference-price cross backed by existing NAVOracle.sol |
| Instrument class | NAV-priced regulated only (slice-zero scope per Q11 resolution) |
| Wallet | Minimum-viable darkpool/ stream — submit commitment, store salt, sign reveal. No composite UI, no leases, no overcommit |
| Search | Intra-pool only; ECDH-encrypted hints (no DiscoveryRegistry) |
| Test feeds | Existing NAVOracle + new pocs/services/internal/oracle/testfeed/ fixture with deterministic scenarios |
| Out of PoC | All cross-pool routing (DP-5a/b/c); Railgun on-ramp; EIL; auto-aggregator; pool-as-searcher; T2/T3 tiers; advanced overcommit |
| Goal | Validate matcher-as-registered-code + operator-Party trust + DVP atomicity end-to-end |
| Sizing | 4–6 weeks for a small team, with resolved decisions in hand |
Decision points for slice-zero kick-off:
- Resolve new Q1 (asset-to-pool granularity) — pick a single asset for the PoC.
- Confirm operator-Party identity / mandate format for the PoC venue.
- Pick the PoC instrument (most likely a tokenized RWA, since NAVOracle is already wired for it).
7. How this work coordinates with existing flow
- Existing Stage 1 / 2 implementation queue continues in parallel during PoC planning.
- After the planning session, priorities may shift toward the slice-zero PoC.
- Three docs sit alongside REQUIREMENTS.md as project-internal forward design.
8. Next steps
- Planning session — align dark-pool PoC work with the existing Stage 1 / 2 flow. Decide whether and when priorities shift.
- Resolve new Q1 (asset-to-pool granularity) for slice-zero — pick a single asset; pin in the slice-zero plan.
- Slice-zero kick-off — DP-1 + DP-2 + DP-3 with the resolved decisions in hand.
- Forward sessions owed before broader implementation:
- T2/T3 dispute mechanics design (Q10 follow-on)
- L1 advertising/trust-root ↔ L2 hub interface (new Q2)
- Test-feed infrastructure for non-NAV instrument classes (new Q3)