Skip to main content

Getting Started with ZEclipse

ZEclipse is a Solana privacy protocol that routes transfers through 4 hops with 48 paths per hop (4 real + 44 fake), yielding an anonymity set of roughly 5.3 million possible paths.

This page summarizes how the pieces fit together and how to orient yourself in the codebase.

Repository Layout​

The core components live in the BlackoutSOL project:

  • programs/zeclipse: Main Anchor-based Solana program (instructions, state, verification, utilities).
  • programs/zeclipse-anchor: Anchor account definitions and client types.
  • app/: TypeScript SDK, CLI, temporal obfuscation logic, and DApp connector.
  • poseidon/: Poseidon hash implementation, validators, and standalone helpers.
  • verification/: Formal verification modules (e.g. Bloom filter specification).
  • docs/ and DOCUMENTATION.md: In-depth technical and architectural documentation.

See AGENTS.md in the root of the repo for a concise development guide.

Core Workflow​

At a high level, a private transfer goes through three stages:

  1. Initialization & Split Planning
    • Client constructs a transfer request and generates ZK proofs off-chain.
    • On-chain program creates a TransferState account with encrypted routing information.
  2. Multi-hop Execution
    • The program executes hop instructions (execute_hop, batch_hop) for each level.
    • Real and fake splits are advanced through multiple PDAs; proofs are verified on-chain.
    • Temporal obfuscation (if enabled) randomizes execution timing on the client side.
  3. Finalization
    • Final hop recombines real splits and delivers funds to privacy-preserving recipient PDAs.
    • Transfer state accounts are closed to reclaim rent.

For a more detailed walkthrough, see Core Concepts → Privacy Model.

  1. README.md in BlackoutSOL/ (high-level overview and motivation).
  2. DOCUMENTATION.md (deep technical documentation).
  3. docs/TECHNICAL_DOCUMENTATION.md (cost/efficiency and DApp integration examples).
  4. The Rust program in programs/zeclipse/src and the TypeScript SDK in app/src.

Then continue with:

  • Getting Started → Build & Run
  • Getting Started → SDK Quickstart