saymrwulf/zk-perp
1
0
Fork 0
mirror of https://github.com/saymrwulf/zk-perp.git synced 2026-05-14 20:58:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
zk-perp/ANALYSIS.md
oho 9408d1e9c8 Initial commit: zk-perp - Zero-Knowledge Perpetual DEX 
A fully functional proof-of-concept perpetual futures DEX with ZK proofs.

Features:
- Ed25519 digital signatures for transaction authentication
- SHA-256 Sparse Merkle Trees (6-tree Hypertree architecture)
- Price-time priority order matching engine
- RISC Zero zkVM integration for state transition proofs
- File-based Data Availability layer with state continuity
- Simulated oracle with mean-reverting price movements
- HTTP API (Axum) for sequencer and verifier
- Comprehensive documentation

Components:
- crates/core: Types, crypto, Merkle trees, transactions
- crates/orderbook: Order matching engine
- crates/state: Global state management
- crates/oracle: Price feed implementations
- crates/da: Append-only log DA layer
- methods/guest: RISC Zero ZK verification logic
- host: Proof generation
- sequencer: Transaction processing and batching
- verifier: Independent proof verification

73 tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
2026-01-06 18:04:52 +01:00

4.2 KiB
Raw Permalink Blame History

Local Claude Code installation

  • No ~/.code directory found; Claude Code data appears under ~/.claude/ and ~/.claude.json.
  • ~/.claude.json shows installMethod: "native", autoUpdates: false, theme: "light", and lastReleaseNotesSeen: "2.0.76".
  • Claude Code state directories present: debug/, downloads/, file-history/, history.jsonl, ide/, plans/, plugins/, projects/, session-env/, shell-snapshots/, statsig/, todos/.
  • Project metadata includes /Users/oho/GitClone/ClaudeCodeProjects with trust dialog accepted and empty allowed tools list.

zk-perp project overview (analogy: Lighter, with RISC Zero instead of Plonky2)

/Users/oho/GitClone/ClaudeCodeProjects/zk-perp is a Rust workspace implementing a perp DEX stack with:

  • Core types, Merkle/Hypertree state, and transaction definitions.
  • An orderbook + matching engine.
  • A sequencer with HTTP API, batching, and proof generation.
  • A DA (data availability) append-only log.
  • A RISC Zero zkVM guest program and host prover.
  • A verifier that consumes DA proofs and advances verified state.

Workspace members are declared in Cargo.toml:

  • crates/core, crates/orderbook, crates/state, crates/oracle, crates/da
  • methods (RISC Zero guest build)
  • host (prover)
  • sequencer (API + execution)
  • verifier

ZK proving flow (RISC Zero)

  • methods/ uses risc0-build to embed the guest program (methods/build.rs).
  • methods/src/lib.rs exports ZK_PERP_GUEST_ELF/ZK_PERP_GUEST_ID when built with the risc0 feature, otherwise stub values.
  • methods/guest/src/main.rs reads a BatchInput, verifies transactions when witnesses are present, computes a batch hash, and commits a BatchOutput to the journal.
  • host/src/lib.rs exposes a Prover that can run in mock mode (no proof) or real mode (RISC Zero default_prover).
  • sequencer defaults to use_mock_prover: true in SequencerConfig.

Notable caveats in the current guest logic:

  • Transactions are only deeply verified when witnesses are present; otherwise they are accepted for testing.

Core state model

  • The state commitment uses a 6-tree Hypertree (crates/core/src/merkle/hypertree.rs):
    1. Accounts
    2. Account Orders
    3. Orderbook
    4. Positions
    5. Pools
    6. System (markets/oracles/config)
  • Each tree is a Sparse Merkle Tree; the combined root is a hash of the six roots.
  • There is a TODO in the sparse Merkle proof verification test (crates/core/src/merkle/tree.rs) indicating proof verification logic is not finalized.

Transactions and signatures

  • Transaction types include Deposit, Withdraw, PlaceOrder, CancelOrder, Liquidate, and UpdateOracle (crates/core/src/transactions/mod.rs).
  • Signatures use Ed25519 via ed25519-dalek (crates/core/src/crypto.rs).
  • Transaction hashes are SHA-256 over bincode-serialized payloads.

Sequencer, execution, and API

  • The sequencer validates signatures (optional), executes transactions against GlobalState, batches pending transactions, triggers proving, and writes to the DA log (sequencer/src/lib.rs).
  • GlobalState maintains the hypertree, in-memory caches (accounts/positions), and per-market orderbooks, plus oracle prices (crates/state/src/lib.rs).
  • The HTTP API (Axum) exposes health, status, account registration, balances, orderbook snapshots, positions, tx submission, and batch triggers (sequencer/src/api.rs).

Orderbook and matching

  • Orderbook uses BTreeMap price levels with FIFO at each level, giving price-time priority (crates/orderbook/src/book.rs).
  • Matching engine is used by state transition logic for order execution (crates/state/src/lib.rs).

Oracle

  • Oracle module includes MockOracle, SimulatedOracle, and a PriceSource trait for price feeds (crates/oracle/src/lib.rs).

DA layer (append-only log)

  • DA stores batches and proofs on disk with an index (crates/da/src/lib.rs).
  • The layout is batches/, proofs/, and index.json under the configured data directory.

Verifier

  • The verifier pulls batches from DA, verifies proofs via the host prover, and advances its verified root (verifier/src/lib.rs).

Build artifacts

  • target/ contains compiled artifacts, including a RISC Zero guest build under target/riscv-guest/..., indicating the guest has been built before.