Skip to content

Docs cleanup and align with latest changes #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
satran004 merged 2 commits into from
May 17, 2026
Merged

Docs cleanup and align with latest changes #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1dbf206
Align docs with latest code change
satran004 May 17, 2026
e053655
Snapshot version
satran004 May 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 32 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,36 @@
# ZeroJ

> [!WARNING]
> **Status: Experimental — Research & Learning Project**
>
> This project is generated using AI, with human-assisted design, testing, and verification.
> It is an experimental project created mainly for research and exploration purposes.
>
> **Please do not use this in production.** Expect rough edges, incomplete features, and potential bugs.

Java-first zero-knowledge proof toolkit for Cardano.

ZeroJ lets Java developers **define ZK circuits**, **generate proofs**, **verify** them off-chain, and **execute on-chain verification** on Cardano — all without leaving the Java ecosystem. **Zero external tools required.**
ZeroJ lets Java developers **define ZK circuits**, **generate proofs**, **verify** them off-chain, and **execute on-chain verification** on Cardano. The Java DSL and pure-Java proving path require no native libraries or external CLIs.

## What You Can Do Today

### Define ZK Circuits
- **CircuitSpec Java DSL** (recommended) — define circuits as reusable Java classes with `CircuitSpec`
- **Inline lambda DSL** — quick prototyping with `CircuitBuilder.define(api -> ...)`
- **circom support** — use existing circom circuits (`.circom` → `.r1cs` + `.wasm`)
- **Standard library** — Poseidon, PoseidonN (variable arity), MiMC, MiMCSponge, Merkle proofs, comparators, binary ops, AliasCheck
- **Multi-backend** — single Java circuit compiles to Groth16 (R1CS), PlonK, or Halo2
- **circom interop** — use externally compiled circom/snarkjs artifacts (`.r1cs`, `.zkey`, `.wtns`; `.wasm` witness calculation in incubator)
- **Standard library** — Poseidon, PoseidonN, MiMC, MiMCSponge, Merkle, Comparators, Binary, Mux, AliasCheck
- **Multi-backend compilation** — one Java circuit can compile to R1CS for Groth16 or to PlonK

### Generate Proofs
- **Pure Java prover** (recommended) — Groth16 + PlonK for BLS12-381 and BN254. Zero native dependencies. GraalVM compatible.
- **gnark FFM** — in-process Groth16/PlonK proving via Go native library (10-50x faster for large circuits)
- **gnark FFM** — optional in-process Groth16/PlonK proving via Go native library
- **snarkjs CLI** — external CLI for circom-based circuits
- **circom interop** — import snarkjs `.zkey` files, prove with the pure Java prover
- **snarkjs key import** — import `.zkey` files, prove with the pure Java prover

### Verify ZK Proofs (Pure Java, Zero Native Deps)
- **Groth16 BN254** — pure Java verification
- **Groth16 BLS12-381** — pure Java verification (also available via blst for ~1ms perf)
- **Groth16 BLS12-381** — pure Java verification; optional blst-backed native verifier is also available
- **PlonK BN254/BLS12-381** — pure Java verification
- **Halo2 IPA** — via Rust FFM bindings (incubator)
- Parse snarkjs proof artifacts (`proof.json`, `verification_key.json`, `public.json`)
- Pluggable backend SPI — add new proof systems without changing application code

Expand Down Expand Up @@ -70,8 +77,11 @@ var witness = circuit.calculateWitness(Map.of(

// 3. Setup + Prove (pure Java — zero native dependencies)
var srs = PowersOfTauBLS381.generate(4); // dev/test only
var setup = Groth16SetupBLS381.setup(constraints, numWires, numPublic, srs.tauScalar());
var proof = Groth16ProverBLS381.prove(setup.provingKey(), witness, constraints, numWires);
var constraints = r1cs.constraints();
var setup = Groth16SetupBLS381.setup(
constraints, r1cs.numWires(), r1cs.numPublicInputs(), srs.tauScalar());
var proof = Groth16ProverBLS381.prove(
setup.provingKey(), witness, constraints, r1cs.numWires());

// 4. Verify off-chain (pure Java)
boolean valid = BLS12381Pairing.pairingCheck(...); // Groth16 pairing equation
Expand All @@ -81,12 +91,12 @@ var script = JulcScriptLoader.load(Groth16BLS12381Verifier.class, vkParams...);
// Lock ADA → unlock with ZK proof → Cardano verifies BLS12-381 pairing
```

For production setup, use an MPC ceremony `.zkey` instead of `PowersOfTauBLS381.generate()`. See the [Pure Java Prover Guide](docs/pure-java-prover-guide.md).
For setup beyond local tests, use an MPC ceremony `.zkey` instead of `PowersOfTauBLS381.generate()`. See the [Pure Java Prover Guide](docs/pure-java-prover-guide.md).

### Alternative: gnark FFM (for maximum speed)
### Alternative: gnark FFM

```java
// Same circuit, but prove via gnark (10-50x faster, requires Go native lib)
// Same circuit, but prove via gnark (requires Go native lib)
try (var prover = new GnarkProver()) {
var result = prover.groth16FullProve(r1cs, witness, CurveId.BLS12_381);
String proofJson = result.proveResponse().proofJson();
Expand Down Expand Up @@ -117,8 +127,7 @@ sdk use java 25.0.2-graal

| Dependency | Version | Required By | Notes |
|------------|---------|-------------|-------|
| **Go** | 1.21+ | `zeroj-prover-gnark` | For gnark native prover (faster) |
| **Rust** | stable | `zeroj-verifier-halo2` (incubator) | For Halo2 verification |
| **Go** | 1.21+ | `zeroj-prover-gnark` | For the optional gnark native prover |
| **circom** | 2.x | Circuit compilation (if using circom) | `cargo install circom` |
| **snarkjs** | 0.7+ | Proof generation (if using snarkjs) | `npm install -g snarkjs` |

Expand All @@ -133,7 +142,7 @@ The **pure Java prover and verifier require no optional dependencies**.
# Build the core privacy path only
./gradlew :zeroj-bom-core:build :zeroj-verifier-core:build :zeroj-verifier-groth16:build :zeroj-verifier-plonk:build :zeroj-crypto:build :zeroj-onchain-julc:build

# Run all tests (2680+ tests)
# Run all tests
./gradlew test

# Run end-to-end on-chain tests (requires Yaci DevKit)
Expand All @@ -155,7 +164,7 @@ The **pure Java prover and verifier require no optional dependencies**.
│ │
Pure Java Prover gnark FFM Prover
(Groth16ProverBLS381) (GnarkProver)
Zero native deps 10-50x faster
Zero native deps Optional native backend
│ │
└──────────┬──────────────────┘
│
Expand All @@ -178,19 +187,19 @@ The **pure Java prover and verifier require no optional dependencies**.
| [`zeroj-codec`](zeroj-codec/) | Proof serialization — snarkjs JSON, CBOR, canonical hashing |
| [`zeroj-backend-spi`](zeroj-backend-spi/) | Service Provider Interface for verification backends |
| [`zeroj-verifier-core`](zeroj-verifier-core/) | Verifier orchestration and backend routing |
| [`zeroj-verifier-groth16`](zeroj-verifier-groth16/) | Groth16 verification — BN254 (pure Java) + BLS12-381 (pure Java / blst) |
| [`zeroj-verifier-groth16`](zeroj-verifier-groth16/) | Groth16 verification — BN254 pure Java + BLS12-381 pure Java/native blst |
| [`zeroj-verifier-plonk`](zeroj-verifier-plonk/) | PlonK verification — BN254 + BLS12-381 (pure Java) |
| [`zeroj-bls12381`](zeroj-bls12381/) | Pure Java BLS12-381 field, curve, and pairing primitives |
| [`zeroj-blst`](zeroj-blst/) | BLS12-381 pairing operations via blst native library |
| [`zeroj-crypto`](zeroj-crypto/) | **Pure Java prover** — Montgomery field arithmetic, EC operations, Groth16 + PlonK for BN254 and BLS12-381 |
| [`zeroj-circuit-dsl`](zeroj-circuit-dsl/) | Java Circuit DSL — define circuits with CircuitSpec, compile to R1CS/PlonK/Halo2 |
| [`zeroj-circuit-lib`](zeroj-circuit-lib/) | Circuit standard library — Poseidon, PoseidonN, MiMC, MiMCSponge, Merkle, comparators, AliasCheck |
| [`zeroj-circuit-dsl`](zeroj-circuit-dsl/) | Java Circuit DSL — define circuits with CircuitSpec, compile to R1CS/PlonK |
| [`zeroj-circuit-lib`](zeroj-circuit-lib/) | Circuit standard library — Poseidon, PoseidonN, MiMC, MiMCSponge, Merkle, Comparators, Binary, Mux, AliasCheck |
| [`zeroj-prover-spi`](zeroj-prover-spi/) | Minimal prover request/response SPI shared by prover implementations |
| [`zeroj-prover-gnark`](zeroj-prover-gnark/) | gnark native prover (Groth16 + PlonK) via FFM |
| [`zeroj-patterns`](zeroj-patterns/) | High-level ZK patterns — state transitions, nullifier claims, membership proofs |
| [`zeroj-cardano`](zeroj-cardano/) | Cardano anchoring — proof anchor model, metadata encoding |
| [`zeroj-ccl`](zeroj-ccl/) | Cardano Client Lib integration — fluent transaction helpers |
| [`zeroj-onchain-julc`](zeroj-onchain-julc/) | Reusable Plutus V3 on-chain verifiers via Julc; Groth16 is production, PlonK is an experimental prototype |
| [`zeroj-onchain-julc`](zeroj-onchain-julc/) | Reusable Plutus V3 on-chain verifiers via Julc; Groth16 is the primary supported path, PlonK is an experimental prototype |

#### Mainline Opt-In Modules (`zeroj-bom-all` only)

Expand All @@ -206,15 +215,14 @@ The **pure Java prover and verifier require no optional dependencies**.
|--------|-------------|
| [`zeroj-test-vectors`](zeroj-test-vectors/) | Shared test fixtures — pre-generated proofs and VKs |
| [`zeroj-examples`](zeroj-examples/) | End-to-end demos: circuit definition to on-chain verification |
| [`zeroj-bom-core`](zeroj-bom-core/) | BOM for the stable v3 core path |
| [`zeroj-bom-core`](zeroj-bom-core/) | BOM for the v3 core path |
| [`zeroj-bom-all`](zeroj-bom-all/) | BOM for core plus opt-in and incubator modules |

#### Incubator Modules (`incubator/`)

| Module | Description |
|--------|-------------|
| [`zeroj-prover-wasm`](incubator/zeroj-prover-wasm/) | Circom witness calculation via GraalVM WebAssembly |
| [`zeroj-verifier-halo2`](incubator/zeroj-verifier-halo2/) | Halo2 IPA verification via Rust FFM (no trusted setup) |

## Dependency (Gradle)

Expand All @@ -237,7 +245,7 @@ dependencies {
// On-chain verification (Cardano Plutus V3)
implementation 'com.bloxbean.cardano:zeroj-onchain-julc'

// Optional: gnark FFM prover (faster, requires Go native lib)
// Optional: gnark FFM prover (requires Go native lib)
// implementation 'com.bloxbean.cardano:zeroj-prover-gnark'
}
```
Expand Down
30 changes: 15 additions & 15 deletions docs/alternate-prover-backends.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,17 @@

ZeroJ's **recommended** prover is the [pure Java prover](pure-java-prover-guide.md) (`zeroj-crypto`), which requires zero native dependencies. This document covers the **alternate native backends** for cases where you need:

- Maximum proving speed (~10-100x faster for large circuits)
- Integration with a native proving library
- Compatibility with existing gnark/snarkjs workflows
- BN254 curve support (pure Java prover focuses on BLS12-381 for Cardano)
- External ceremony or proof-generation tooling

## Backend Comparison

| Backend | Proof Systems | Curves | Speed | Dependencies | Module |
|---------|-------------|--------|-------|-------------|--------|
| **Pure Java** | Groth16, PlonK | BN254, BLS12-381 | Baseline | None | `zeroj-crypto` |
| **gnark FFM** | Groth16, PlonK | BN254, BLS12-381 | ~10-50x faster | Go native lib | `zeroj-prover-gnark` |
| **snarkjs CLI** | Groth16, PlonK | BN254, BLS12-381 | Slowest | Node.js + snarkjs | (external process) |
| Backend | Proof Systems | Curves | Dependencies | Module |
|---------|-------------|--------|--------------|--------|
| **Pure Java** | Groth16, PlonK | BN254, BLS12-381 | None | `zeroj-crypto` |
| **gnark FFM** | Groth16, PlonK | BN254, BLS12-381 | Go native lib | `zeroj-prover-gnark` |
| **snarkjs CLI** | Groth16, PlonK | BN254, BLS12-381 | Node.js + snarkjs | external process |

## gnark FFM (Foreign Function & Memory)

Expand Down Expand Up @@ -85,6 +85,7 @@ implemented.
### Gradle

```gradle
implementation platform('com.bloxbean.cardano:zeroj-bom-all:0.1.0')
implementation 'com.bloxbean.cardano:zeroj-prover-gnark'
```

Expand Down Expand Up @@ -131,7 +132,7 @@ var proof = Groth16ProverBLS381.prove(zkeyData.provingKey(), witness,
zkeyData.constraints(), zkeyData.numWires());
```

This is the **recommended production pattern**: ceremony via snarkjs, proving via pure Java.
This is the recommended ceremony/import pattern when evaluating a setup beyond local single-party test keys.

## circom Integration

Expand Down Expand Up @@ -166,10 +167,9 @@ var proof = snarkjs.groth16Prove(zkeyPath, wtnsPath, workDir);

| Scenario | Recommended Backend |
|----------|-------------------|
| **Cardano on-chain verification** | Pure Java (BLS12-381) |
| **Development / testing** | Pure Java (zero setup, instant) |
| **Large circuits (>10K constraints)** | gnark FFM (10-50x faster) |
| **BN254 proofs (Ethereum)** | gnark FFM |
| **Existing snarkjs workflow** | snarkjs CLI → import .zkey → pure Java prove |
| **Mobile / serverless** | Pure Java (no native deps, GraalVM compatible) |
| **CI/CD pipelines** | Pure Java (no build toolchain needed) |
| **Cardano on-chain verification** | Pure Java BLS12-381 path |
| **Development / testing** | Pure Java local setup |
| **Native proving acceptable** | gnark FFM |
| **Existing snarkjs workflow** | snarkjs CLI for setup/artifacts, then import `.zkey` |
| **Mobile / serverless** | Pure Java path |
| **CI/CD pipelines** | Pure Java path when native build toolchains are undesirable |
25 changes: 8 additions & 17 deletions docs/architecture-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ structured proof adapter is added.
## Module Organization

Modules are organized into core modules, mainline opt-in modules, and incubator
modules. `zeroj-bom-core` covers the stable v3 privacy path. `zeroj-bom-all`
modules. `zeroj-bom-core` covers the v3 core privacy path. `zeroj-bom-all`
covers core plus opt-in BBS/WASM and incubator modules.

## Module Dependency Graph
Expand All @@ -42,9 +42,6 @@ zeroj-api (foundation types)
| +-- zeroj-verifier-groth16 (→ zeroj-backend-spi, zeroj-codec, zeroj-bls12381, zeroj-blst)
| |
| +-- zeroj-verifier-plonk (→ zeroj-backend-spi, zeroj-codec, zeroj-crypto, zeroj-verifier-groth16 for BN254 arithmetic)
| |
| +-- zeroj-verifier-halo2 (→ zeroj-backend-spi, zeroj-codec, Rust FFM) [incubator]
|
+-- zeroj-bls12381 (pure Java BLS12-381 field/curve/pairing)
| |
| +-- zeroj-crypto (→ zeroj-api, zeroj-bls12381)
Expand Down Expand Up @@ -81,16 +78,15 @@ zeroj-bom-core / zeroj-bom-all (platform modules, no code)
### Layer 1: Core Model (`zeroj-api`)
Immutable data types shared across all modules:
- `ZkProofEnvelope` -- the proof container
- `ProofSystemId` -- GROTH16, PLONK, FFLONK, HALO2
- `CurveId` -- BN254, BLS12_381, PALLAS
- `ProofSystemId` -- public docs focus on GROTH16, PLONK, and BBS
- `CurveId` -- public docs focus on BN254 and BLS12_381
- `VerificationResult` -- crypto validity + policy validity
- `VerificationMaterial` -- verification key + metadata

### Layer 2: Serialization (`zeroj-codec`)
Proof format parsers and serializers:
- snarkjs JSON format (proof.json, verification_key.json, public.json)
- gnark PlonK/Groth16 format
- Halo2 proof format
- CBOR binary format for network transmission
- Canonical hashing for deterministic proof identification

Expand All @@ -105,14 +101,13 @@ Backend abstraction:
Concrete implementations:
- `zeroj-verifier-groth16` -- Groth16 for BN254 (pure Java) + BLS12-381 (pure Java / blst)
- `zeroj-verifier-plonk` -- structured PlonK proof verification for BN254 + BLS12-381 (pure Java)
- `zeroj-verifier-halo2` -- Halo2 IPA via Rust FFM (incubator)
- `zeroj-blst` -- Low-level BLS12-381 curve operations

### Layer 5: Circuit Definition (`zeroj-circuit-dsl`, `zeroj-circuit-lib`)
Java circuit definition and compilation:
- `CircuitBuilder` / `CircuitAPI` -- define circuits in Java
- `SignalBuilder` -- OO Signal-style API
- Compiles to R1CS (Groth16), PlonK gates, or Halo2 PLONKish
- Compiles to R1CS (Groth16) or PlonK gates
- `zeroj-circuit-lib` -- Poseidon, MiMC, Merkle, comparators, binary ops

### Layer 6: Orchestration (`zeroj-verifier-core`)
Expand All @@ -122,7 +117,7 @@ Routes verification requests to the correct backend based on proof system and cu
Proof generation backends:
- `zeroj-crypto` -- pure Java Groth16 and PlonK proving where supported
- `zeroj-prover-spi` -- minimal prover-side request/response contract
- `zeroj-prover-gnark` -- production native Groth16/PlonK proving via Go FFM
- `zeroj-prover-gnark` -- optional native Groth16/PlonK proving via Go FFM
- `zeroj-prover-wasm` -- Circom witness calculation via GraalVM WASM (incubator)

### Layer 8: High-Level Patterns (`zeroj-patterns`)
Expand All @@ -147,15 +142,14 @@ Reusable Plutus V3 spending validators compiled via Julc:
| Proof System | Curve | Backend | Implementation | Native Deps |
|-------------|-------|---------|----------------|-------------|
| Groth16 | BLS12-381 | Pure Java | `zeroj-verifier-groth16` | None |
| Groth16 | BLS12-381 | blst native (FFM) | `zeroj-verifier-groth16` | blst (~1ms) |
| Groth16 | BLS12-381 | blst native (FFM) | `zeroj-verifier-groth16` | blst |
| Groth16 | BN254 | Pure Java | `zeroj-verifier-groth16` | None |
| PlonK | BLS12-381 | Pure Java | `zeroj-verifier-plonk` | None |
| PlonK | BN254 | Pure Java | `zeroj-verifier-plonk` | None |
| Halo2 IPA | Pallas | Rust FFM | `zeroj-verifier-halo2` (incubator) | Rust binary |

- BLS12-381 pure Java verifier uses field arithmetic validated against gnark
- BN254 uses pure Java field arithmetic, validated against Ethereum EIP-196/197 test vectors
- blst option available for BLS12-381 when maximum performance is needed (~1ms vs ~100ms)
- blst option available for BLS12-381 when a native verifier backend is acceptable

## On-Chain Verification

Expand Down Expand Up @@ -183,13 +177,10 @@ Best-effort compatibility from the start; hardened in later milestones.
| ADR | Decision |
|-----|----------|
| [0001](adr/0001-verifier-first-architecture.md) | Verifier-first, no prover in core |
| [0002](adr/0002-external-proof-submission-first-class.md) | External proof submission as primary flow |
| [0003](adr/0003-pure-java-mvp.md) | Hybrid: blst for BLS12-381, pure Java for BN254 |
| [0004](adr/0004-off-chain-cardano-anchoring-first.md) | Off-chain Cardano anchoring first |
| [0005](adr/0005-plugin-provability-contract.md) | Explicit plugin provability contract |
| [0006](adr/0006-separation-of-crypto-and-policy-verification.md) | Separate crypto and policy verification |
| [0007](adr/0007-module-structure-and-boundaries.md) | Multi-module structure |
| [0008](adr/0008-plonk-support-via-gnark.md) | PlonK support via gnark |
| [0009](adr/0009-halo2-support-strategy.md) | Halo2 support strategy |
| [0010](adr/0010-java-circuit-dsl.md) | Java Circuit DSL |
| [0012](adr/0012-pure-java-provers-groth16-plonk.md) | Pure Java Groth16 and PlonK provers |
| [0020](adr/0020-module-cleanup-and-core-restructure.md) | Module cleanup and core restructure |
Loading
Loading