mirror of
https://github.com/saymrwulf/zk-perp.git
synced 2026-05-14 20:58:10 +00:00
9408d1e9c8
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)
3 KiB
3 KiB
Quick Start Guide
Get zk-perp running in under 5 minutes.
Prerequisites
- Rust 1.75+ (
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh) - Git
Build & Run
# Clone and build
git clone https://github.com/your-repo/zk-perp.git
cd zk-perp
cargo build --release
# Start sequencer (mock proving, instant)
cargo run --bin sequencer -- --port 8080
# In another terminal, start verifier
cargo run --bin verifier -- --port 8081
Test the API
1. Check Health
curl http://localhost:8080/health | jq
Response:
{
"success": true,
"data": {
"status": "healthy",
"version": "0.1.0",
"block_number": 0,
"pending_transactions": 0
}
}
2. Register an Account
# Generate a keypair (in a real app)
# For testing, use a dummy public key:
curl -X POST http://localhost:8080/accounts \
-H "Content-Type: application/json" \
-d '{
"public_key": "0000000000000000000000000000000000000000000000000000000000000001"
}' | jq
Response:
{
"success": true,
"data": {
"account_id": 0,
"public_key": "0000000000000000000000000000000000000000000000000000000000000001"
}
}
3. Check Account
curl http://localhost:8080/accounts/0 | jq
4. Get Order Book
# BTC-USDC market (market_id = 0)
curl "http://localhost:8080/markets/0/orderbook?depth=10" | jq
5. Get Market Price
curl http://localhost:8080/markets/0/price | jq
Response:
{
"success": true,
"data": {
"id": 0,
"name": "BTC-USDC",
"base_asset": "BTC",
"quote_asset": "USDC",
"price": 5000000000000
}
}
6. Check Verifier Status
curl http://localhost:8081/stats | jq
Using Real ZK Proofs
For real zero-knowledge proofs (slower, ~16 seconds per batch):
# Install RISC Zero toolchain
curl -L https://risczero.com/install | bash
rzup install
# Run with real proving
cargo run --bin sequencer --features risc0 -- --real-proving
Run Tests
# Run all tests
cargo test
# Run specific crate tests
cargo test -p zk-perp-core
cargo test -p zk-perp-orderbook
cargo test -p zk-perp-verifier
# Run with real RISC Zero proving (slow)
cargo test -p zk-perp-host --test integration -- --ignored
Project Structure Overview
zk-perp/
├── crates/
│ ├── core/ # Types, crypto, Merkle trees
│ ├── orderbook/ # Order matching engine
│ ├── state/ # Global state management
│ ├── oracle/ # Price feeds
│ └── da/ # Data availability layer
├── methods/ # RISC Zero guest (ZK circuit)
├── host/ # Proof generation
├── sequencer/ # Main server
└── verifier/ # Verification node
Next Steps
- Read the README for a complete overview
- Explore the Architecture for technical details
- Check the API reference in the README
- Try writing a client that submits transactions