Program Architecture

This page summarizes the on-chain architecture of ZEclipse based on DOCUMENTATION.md, docs/TECHNICAL_DOCUMENTATION.md, and the Rust sources under programs/zeclipse.

High-Level Layout

Repository structure (simplified from the docs):

BlackoutSOL
├── programs
│   ├── zeclipse                # Main program logic
│   │   ├── src
│   │   │   ├── instructions/   # Program instructions
│   │   │   │   ├── initialize.rs
│   │   │   │   ├── execute_hop.rs
│   │   │   │   ├── batch_hop.rs
│   │   │   │   ├── finalize.rs
│   │   │   │   ├── refund.rs
│   │   │   │   ├── reveal_fake.rs
│   │   │   │   └── config_update.rs
│   │   │   ├── state/          # Account structures & state management
│   │   │   ├── verification/   # Formal verification modules
│   │   │   │   ├── formal/
│   │   │   │   │   └── bloom_filter_specification.rs
│   │   │   │   └── mod.rs
│   │   │   ├── utils.rs        # Cryptographic helpers, ZK plumbing
│   │   │   ├── errors.rs       # Error codes (BlackoutError)
│   │   │   ├── entrypoint.rs   # Solana entrypoint
│   │   │   └── lib.rs          # Program module wiring
│   │   └── examples/
│   └── zeclipse-anchor         # Anchor account definitions
│       └── src/anchor_accounts.rs
└── poseidon_* / verification   # Supporting crates & verification helpers

Core Instructions

The main program instructions implement the privacy pipeline:

• initialize – creates the TransferState account, stores encrypted routing information, and verifies initial proofs.
• execute_hop – processes a single hop (validation, proof verification, split logic, state update).
• batch_hop – optimized multi-hop / multi-split processing in batch form.
• finalize – recombines real splits, delivers funds to recipient PDAs, reclaims rent by closing state accounts.
• refund – returns funds if a transfer fails or times out, following strict safety rules.
• reveal_fake – selectively reveals fake splits under controlled conditions (e.g., for diagnostics or proofs-of-safety).
• config_update – updates protocol parameters (e.g., split counts, limits) under governance / admin controls.

Each instruction is implemented as a separate Rust module under instructions/, wired together by the mod.rs and program lib.rs.

State & Accounts

The main on-chain state lives in:

• TransferState (in state/):
  • Tracks hop index and progress.
  • Stores commitments, Bloom filters, and metadata for real/fake splits.
  • Holds up to a fixed number of recipients (e.g., 6) plus recipient_count.
• Configuration accounts:
  • Global parameters (e.g., max hops, split counts, limits).
  • Possibly fee/treasury and admin keys (depending on your version of the code).

Guiding principles from the docs:

• Minimal persistent state – to reduce rent and storage footprint.
• Deterministic PDAs – for predictable addressing and simplified client logic.
• Tight serialization – using Anchor and helper crates to minimize account size.

Verification & Utilities

The verification/ and utils.rs modules provide:

• Glue code between on-chain logic and ZK proofs (HyperPlonk, range proofs, Merkle proofs).
• Poseidon-based hashing and commitment utilities.
• Formal specifications (e.g., Bloom filter behavior) to support reasoning and tooling.

From AGENTS.md and DOCUMENTATION.md:

• ZK components are experimental, with some placeholder or prototype code paths.
• Poseidon and proof verification logic are performance-sensitive and should be treated as critical for audits.

Build & Development Notes

See Getting Started → Build & Run and docs/COMPILE_INSTRUCTIONS.md:

• Use --features no-entrypoint for many development and test flows to work around Anchor macro issues while still compiling ZK and Poseidon code.
• Keep the crate ecosystem (Anchor, solana-program, solana-poseidon) at the documented versions to avoid subtle integration breakage.

For deeper details, read:

• DOCUMENTATION.md – System Architecture, Privacy Mechanism, Zero-Knowledge Proofs, State Management, Instructions.
• The actual Rust files under programs/zeclipse/src.