# saudadeeee/zk-snark-x-steganography architecture

> Architecture diagram of the GitHub repository saudadeeee/zk-snark-x-steganography, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saudadeeee/zk-snark-x-steganography
- Repository: https://github.com/saudadeeee/zk-snark-x-steganography

## Overview

##### Project type and purpose
- This is an open-source Python + Circom tool/library for ZK-SNARK–based steganography.
- Purpose: embed messages (or metadata) into images using chaos-based LSB steganography, generate succinct zero-knowledge proofs (Groth16 via Circom/WASM), and pack everything into a PNG container.
- Key use cases: forensic integrity, copyright watermarking, private communication.

##### File structure
- Top-level directories:
- Demo/ (quick-start, step-by-step, benchmarks)
- artifacts/keys/ (Powers of Tau ptau, verification_key.json)
- bin/ (Circom compiler wrapper)
- circuits/ (source `.circom` + compiled R1CS, WASM, ZKey)
- comparative_benchmarks/, scientific_benchmarks/ (analysis scripts & reports)
- examples/testvectors/ (cover images)
- src/zk_stego/ (ChaosEmbedding, ZKProofGenerator, HybridProofArtifact)
- verify_zk_stego.py (CLI verification tool)
- zk-schnorr/ (separate ZK Schnorr stego experiment)

##### README for insights
- Four logical layers are described:
1) ZK Circuit layer (`chaos_zk_stego.circom`) with 32 constraints
2) ZK Proof layer (`zk_proof_generator.py`) automating witness + trusted setup + proof
3) Steganography layer (`chaos_embedding.py`) with Arnold Cat Map & Logistic Map + LSB
4) Integration layer (`hybrid_proof_artifact.py`) combining PNG chunk metadata + proof

- Circuits & Compiler: `circuits/source/chaos_zk_stego.circom` → R1CS, WASM via circom
- Trusted Setup: `pot12_final.ptau` + R1CS → `.zkey` → export `verification_key.json`
- ZK Proof Generator: Python class → generate witness (WASM) → snarkjs prove → proof JSON
- Chaos Embedding: Python class → Arnold Cat Map + Logistic Map → LSB modify image
- Hybrid Integration: Python class → embed proof & public inputs into PNG chunks
- CLI & Demos: `verify_zk_stego.py`, Demo scripts, benchmarks

- Cover image + message → ChaosEmbedding → stego-image raw
- Chaos params + trace → WASM witness generator → witness
- witness + `.zkey` → Groth16 prover → proof JSON + public inputs
- proof + public inputs → HybridProofArtifact → final PNG (custom chunks: stEg, tEXt)
- verify flow: final PNG → CLI tool → extract chunks → call snarkjs verify → PASS/FAIL

c. Architectural patterns & design principles:
- Layered separation of concerns (Circuit vs. Proof vs. Embedding vs. Integration)
- Modular code in `src/zk_stego`
- Reusable Circom circuits independent of Python logic
- Clear artifact management (`artifacts/keys`, `circuits/compiled/build`)

d. Relevant technologies & libraries:
- Circom compiler & snarkjs (Node.js, WASM)
- Python (PIL, numpy, hashlib)
- Groth16 proving system
- Demo & benchmark frameworks (matplotlib, CSV/JSON outputs)

##### Essential details
- Constraint count (32), proof size (739 bytes), performance metrics (embed <0.01s, proof gen ≈2.3s, verify ≈0.5s).
- Trusted setup workflow separately: ptau download → circuit setup → zkey → export verification key.
- PNG chunk structure: standard chunks + custom stEg/tEXt for proof & metadata.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Trusted Setup
    subgraph "Trusted Setup"
        direction TB
        PT["pot12_final.ptau"]:::artifact
        R1CS["R1CS (chaos_zk_stego.r1cs)"]:::artifact
        ZKEY["chaos_zk_stego.zkey"]:::artifact
        VK["verification_key.json"]:::artifact
        PT -->|"setup with R1CS"| ZKEY
        ZKEY -->|"export"| VK
    end

    %% Circuit Compilation
    subgraph "ZK Circuit Layer & Compiler"
        direction TB
        CIRCOM["chaos_zk_stego.circom"]:::circuits
        COMPILER["circom (bin/circom)"]:::external
        BUILD["circuits/compiled/build/"]:::artifact
        CIRCOM -->|"compile"| COMPILER
        COMPILER -->|"outputs"| BUILD
    end

    %% Proof Generation
    subgraph "ZK Proof Generation" 
        direction TB
        WASM["chaos_zk_stego.wasm"]:::circuits
        WITNESS_GEN["generate_witness.js"]:::external
        ZK_PY["zk_proof_generator.py"]:::python
        SNARKJS_PROVE["snarkjs prove"]:::external
        WITNESS["witness.wtns"]:::artifact
        PROOF["proof.json + public_inputs.json"]:::artifact

        BUILD --> WASM
        BUILD --> WITNESS_GEN
        WASM --> WITNESS_GEN
        WITNESS_GEN -->|"generates"| WITNESS
        ZK_PY -->|uses WITNESS| WITNESS
        ZK_PY -->|uses ZKEY| ZKEY
        ZK_PY -->|calls| SNARKJS_PROVE
        SNARKJS_PROVE --> PROOF
    end

    %% Embedding
    subgraph "Steganography Embedding"
        direction TB
        INPUT["Cover image + Message"]:::external
        CHAOS["ChaosEmbedding"]:::python
        STEGO_RAW["Raw stego-image"]:::artifact
        INPUT -->|image & msg| CHAOS
        CHAOS -->|modifies| STEGO_RAW
    end

    %% Integration
    subgraph "Hybrid Proof Artifact Integration"
        direction TB
        HYBRID["HybridProofArtifact"]:::python
        FINAL_PNG["Final PNG w/ stEg & tEXt chunks"]:::artifact
        STEGO_RAW -->|input| HYBRID
        PROOF -->|proof & inputs| HYBRID
        HYBRID --> FINAL_PNG
    end

    %% Verification
    subgraph "Verification Flow"
        direction TB
        CLI["verify_zk_stego.py"]:::python
        SNARKJS_VERIFY["snarkjs verify"]:::external
        RESULT["PASS / FAIL"]:::external
        FINAL_PNG -->|input| CLI
        CLI -->|extract chunks| SNARKJS_VERIFY
        SNARKJS_VERIFY --> RESULT
    end

    %% Demos & Benchmarks
    subgraph "Demo & Benchmark Suites"
        direction TB
        DEMO["Demo/ scripts"]:::python
        COMP_BM["comparative_benchmarks/"]:::python
        SCI_BM["scientific_benchmarks/"]:::python
    end

    %% Styling
    classDef circuits fill:#ADD8E6,stroke:#000;
    classDef python fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef artifact fill:#D3D3D3,stroke:#000;

    %% Click events
    click CIRCOM "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/circuits/source/chaos_zk_stego.circom"
    click BUILD "https://github.com/saudadeeee/zk-snark-x-steganography/tree/main/circuits/compiled/build/"
    click COMPILER "https://github.com/saudadeeee/zk-snark-x-steganography/tree/main/bin/circom"
    click PT "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/artifacts/keys/pot12_final.ptau"
    click ZKEY "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/circuits/compiled/build/chaos_zk_stego.zkey"
    click VK "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/circuits/compiled/build/verification_key.json"
    click ZK_PY "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/src/zk_stego/zk_proof_generator.py"
    click WASM "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/circuits/compiled/build/chaos_zk_stego_js/chaos_zk_stego.wasm"
    click WITNESS_GEN "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/circuits/compiled/build/chaos_zk_stego_js/generate_witness.js"
    click CHAOS "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/src/zk_stego/chaos_embedding.py"
    click HYBRID "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/src/zk_stego/hybrid_proof_artifact.py"
    click CLI "https://github.com/saudadeeee/zk-snark-x-steganography/blob/main/verify_zk_stego.py"
    click DEMO "https://github.com/saudadeeee/zk-snark-x-steganography/tree/main/Demo/"
    click COMP_BM "https://github.com/saudadeeee/zk-snark-x-steganography/tree/main/comparative_benchmarks/"
    click SCI_BM "https://github.com/saudadeeee/zk-snark-x-steganography/tree/main/scientific_benchmarks/"
```
