Dobby

Problem solved: Traditional on-chain CLOB attempts fail to scale because every order mutates shared best bid/ask and large monolithic queues, forcing strict sequential execution and raising latency. Dobby decomposes the hot path so most orders interact only with narrowly scoped state, enabling true horizontal throughput while staying L1-native (no off-chain sequencing trust).

Dobby is a fully on-chain central limit order book purpose-built for Arcology’s parallel-execution network. Instead of serializing every order placement and match like conventional on-chain DEX designs, Dobby restructures state (price level partitions, per-user balance shards, delta aggregation buffers) so Arcology’s speculative scheduler can safely execute multiple independent order flows concurrently while guaranteeing deterministic final state. This eliminates the need for off-chain match engines, sequencers, or batch auction intermediaries, preserving trust minimization and composability.

Core architecture:

• Storage partitioning: mapping(price => LevelBook) isolates queues; user collateral and reserved balances are striped to shrink transactional write sets.
• Two-phase matching: inner loop accumulates BalanceDelta structs (no immediate balance writes), followed by a compressed commit phase touching only affected accounts and levels.
• Deterministic identifiers: order IDs derived from user, side, price, and a local nonce avoid extra lookups, aiding conflict prediction.
• Event-centric state reconstruction: granular events (OrderPlaced, Match, Cancel, Settlement) let external indexers rebuild the book without privileged access.

Arcology integration:

• Leverages parallel execution by minimizing key collisions; independent price levels and unrelated user fills can finalize in the same block.
• Custom devnet (chain 118) exposes a trimmed JSON-RPC surface at http://65.109.227.117:8545 for deterministic benchmarking.
• concurrentlib primitives conceptually map conflict domains (price buckets, user partitions) to maximize scheduler concurrency without unsafe optimistic merges.

Oracle layer (Pyth):

• Pyth ETH/USDC (and other pairs) feeds supply mark pricing for margin-style risk checks, order reasonableness bands, and settlement PnL.
• Staleness + confidence interval gating prevents toxic order flow against stale marks.
• Decoupled update path: oracle updates can be pushed independently; orders revert cleanly if data is outdated.

Benchmarking: A Hardhat-driven script (benchmark-clob.ts) stress tests contention profiles (narrow vs dispersed price ladders), collects match throughput, fill latency, and reverted ratio (e.g. stale oracle, margin failure). Deterministic seeds provide reproducible performance baselines for iterative optimization.

Differentiators:

• Pure Solidity logic; no hidden off-chain path.
• Parallelism is a first-order design constraint, not an afterthought.
• Oracle-integrated risk gating without central operators.
• Deterministic matching semantics preserving price-time priority inside each level.

Execution Substrate: Arcology Parallel VM

Dobby targets Arcology’s speculative + deterministic parallel EVM implementation. Arcology analyzes per-transaction read/write sets then schedules non-conflicting segments concurrently. We deliberately shaped storage to yield high disjointness:

• Price Level Partitioning: mapping(uint256 => LevelBook) where each LevelBook is a tightly packed struct containing head/tail indices plus an order ring. Independent price levels rarely collide.
• User Balance Stripes: User collateral and reserved amounts are split into shards (e.g. balances[user][asset] plus a segregated delta accumulator). Matching only touches the subset of users actually filled in that batch.
• Delta Accumulation Layer: Instead of directly mutating balances inside the inner matching loop, we build BalanceDelta[] scoped per user, then commit in a second phase, shrinking the write set and enabling Arcology’s conflict detector to keep other orders at unrelated prices flowing.

Arcology’s concurrency benefits arrive “for free” once storage conflicts are minimized; we did not embed explicit threading logic—just structured memory for independence. The net effect: multiple order placement + partial match transactions at disjoint price levels can finalize in parallel without global sequencing bottlenecks typical of monolithic CLOB state.

Devnet Infrastructure (VPS Hosted)

We run a dedicated Arcology devnet (exposed at http://65.109.227.117:8545) on a VPS:

• Single execution cluster exposing a trimmed JSON-RPC surface (only canonical eth_* + web3_*) to reduce noise and remove txpool fingerprinting.
• Automated redeploy pipeline: Hardhat Ignition module pushes Token pairs + CLOB; a post-deploy script writes addresses into contracts/ignition/deployments/chain-118/.
• Benchmark loop runner (Node script) executes from a CI or local terminal, parameterized via environment variables to stress different contention shapes (narrow vs wide price bands).

Contract Architecture

Layered segmentation:

1. Core CLOB (CLOB.sol): Maintains price → order queue (price-time priority) plus indices for head/tail. Orders kept in contiguous arrays or ring buffers allowing O(1) append and amortized O(1) cancellation via tombstoning + lazy compaction.
2. Types / Struct Domain: Canonical Order, Level, MatchResult, BalanceDelta definitions to keep ABI stable and simplify off-chain decoding.
3. Oracle Integration Module (thin adapter) reading Pyth price feeds.
4. Risk & Validation: Ensures notional + available free collateral meet margin-style constraints before allowing placement.
5. Event Surface: Emits granular events (OrderPlaced, Match, OrderCanceled, BalanceSettled) rather than large aggregated blobs to let indexers reconstruct book state incrementally.

Storage Layout Optimizations:

• Sequential slot packing for hot fields (level pointers, best bid/ask).
• Split rarely touched governance / config (fee rates, oracle ids) into a separate struct stored behind a single mapping key to avoid pulling them into hot cache lines.
• Order ID = keccak(user, localIncrement, price, side) enabling deterministic recomputation without extra mapping lookups.

Matching Engine Flow

1. Ingress Validation: Signature + margin + price band sanity.
2. Insert: Append order into its LevelBook queue; update best bid/ask if needed.
3. Crossing Check: If buy ≥ best ask (or sell ≤ best bid) start iterative match loop.
4. Loop:
   • Pull head of opposing level.
   • Compute fill size (min of remaining sizes).
   • Append two BalanceDelta entries (taker vs maker, each asset leg).
   • Decrement / advance head; if level empty, drop level metadata.
   • Short-circuit if taker fully filled.
5. Commit Phase:
   • Aggregate per-user net base/quote deltas to minimize duplicate writes.
   • Apply unified settlement.
   • Emit events; remove fully filled or canceled orders.

Parallelization Assist: Because commit touches only the small set of actually matched users + a bounded number of price levels, unrelated transactions (different levels, different users) proceed without write contention.

Oracle Integration (Pyth)

We integrate Pyth to anchor synthetic pair valuation (e.g. ETH/USDC) for:

• Mark Price: Guardrails on extreme off-market orders (anti-manipulative band).
• Collateral Valuation: Convert reserves into a unified settlement currency for margin / risk. Operational Steps:

1. Off-chain fetch / push: Client or keeper submits the latest Pyth price update blob via a standard update function (payload contains signed price attestations).
2. Validation: Contract verifies freshness (publish time vs block timestamp), confidence interval width, and staleness threshold.
3. Mark Selection: Uses either median of last N updates or immediate latest (configurable) to smooth sudden spikes.
4. Risk Check: Before placement, compute notional = size * limitPrice (or mark) and verify user free collateral ≥ required initial requirement. On match, variation adjustments are booked through BalanceDelta and realized PnL updates.

We intentionally decouple price feed writes from order placement so order flow doesn’t stall if a keeper lags; stale feed triggers reversion with a distinct error signature enabling external monitors to refresh.

Solving the Core Problem

Problem: On-chain CLOBs collapse under sequential contention: each order touches global best bid/ask plus large shared queues, serializing flows and pushing systems off-chain (introducing trust and latency). Dobby Approach:

• Aggressively partition state so most orders don’t collide.
• Use a two-phase (accumulate then commit) pattern to shrink simultaneous writes.
• Leverage Arcology’s deterministic parallel scheduler rather than inventing L2 sequencing or batch auctions.
• Integrate robust oracle-derived pricing to maintain risk integrity without centralized operators. Result: Higher throughput (parallel fills), deterministic outcomes (no off-chain race), composable semantics (pure Solidity).

Benchmark Harness

Script: contracts/scripts/benchmark-clob.ts:

• Deterministic PRNG for price ladder dispersion (seedable for reproducibility).
• Generates mixed order sides with configurable skew and spread.
• Measures end-to-end confirmation latency, effective matches per second, collision rate (count of reverted due to stale price or margin).
• Optionally writes detailed JSON metrics artifact for CI trend analysis.

Hot Path Micro-Optimizations:

• Branch flattening inside match loop.
• Unchecked arithmetic in safe contexts (price ladder increments, internal indices).
• Memory caching of storage pointers for repeated access (price level struct).
• Event indexing tuned for downstream subgraph or log-based indexers (topics include user, price, side).

Hacky / Noteworthy Workarounds

• Tombstone + deferred compaction: Avoids O(n) middle-array deletions during cancellations; periodic sweeps prune holes when fragmentation threshold crossed.
• Oracle Freshness Guard: Inline assembly timestamp comparison to minimize extra stack ops; returns custom selector for gas-cheap revert reason decoding off-chain.
• Minimal RPC Fingerprint: Running devnet with filtered namespaces ensured stable deterministic behavior while benchmarking, at the cost of standard txpool introspection.

Security / Integrity Considerations

• Reentrancy guards around match+commit boundary.
• Oracle staleness + confidence interval gating prevents toxic flow exploitation.
• Overflow / underflow surfaces constrained to internal accounting with explicit invariant checks in debug mode (removable in production build).
• Future: Add circuit breaker if mark deviates from VWAP of recent executed trades beyond threshold.

Limitations & Future Extensions

• Lack of native advanced order types (stop, IOC) — planned via conditional pre-check hook.
• No cross-asset margin netting yet; per-pair isolation simplifies current accounting.
• Off-chain order intent compression (batch submission) could further amortize gas.
• Integrate on-chain liquidation for undercollateralized accounts using oracle mark + buffer.

Technology Stack Summary

• Solidity (core logic)
• Hardhat + Ignition (build/deploy tooling)
• Arcology parallel EVM (execution substrate)
• Pyth Oracle (price + risk backbone)
• Node.js Benchmark + Ops scripts
• Structured Events for external indexers / analytics

This composition yields a trust-minimized, high-throughput, oracle-aware on-chain CLOB exploiting true parallel execution rather than simulating it via off-chain batching.