How google/longfellow-zk works
Step 1: Identify Project Type and Purpose
• This is a C++ “monorepo” library (Longfellow ZK) for building zero-knowledge proofs over legacy identity formats (MDOC, JWT, W3 VC).
• It exposes core building blocks (finite fields, FFTs, merkle trees, sumcheck, circuits, provers, verifiers) and is consumed by CMake clients.
• It includes unit tests and benchmarks (googletest, googlebenchmark).
Step 2: Analyze File Structure
• Top-level:
• .devcontainer, .github/workflows: CI and dev container config
• lib/: all C++ submodules with CMake build files
• docs/: Doxygen API reference
• README.md, LICENSE, Doxyfile
• Under lib/, key subdirectories (each with its own CMakeLists.txt):
• util: basic utilities (logging, serialization, crypto wrappers)
• algebra: finite‐field, FFT, convolution, Reed-Solomon, etc.
• arrays, cbor: data structures and parsers
• circuits: Zero-knowledge circuit definitions (anoncred, base64, cbor_parser, compiler, ecdsa, jwt, logic, mac, mdoc, sha, sha3)
• ec, gf2k: elliptic-curve and GF(2^k) support
• merkle: merkle tree commitments
• proto: circuit protobuf messages
• random: randomness engines/transcripts
• sumcheck: sumcheck protocol layers
• zk: top-level zk_prover, zk_verifier, zk_common
• testing: test runner and harness
Step 3: README Insights
• Describes overall goal: zero-knowledge over legacy credentials
• Points out external dependencies: openssl, zstd, clang, googletest, googlebenchmark
• No external network or runtime services—pure C++ library
a. Build & Dev Environment
• CMake (lib/CMake, scripts)
• Devcontainer / Docker
• CI pipelines (.github/workflows)
• External deps: OpenSSL, Zstd, googletest, googlebenchmark
1. util
2. algebra, arrays, cbor, ec, gf2k, merkle, random
3. circuits (sub‐packages)
4. sumcheck
5. zk (zk_common, zk_prover, zk_verifier)
c. Tests & Benchmarks
• Unit tests (googletest)
• Benchmarks (googlebenchmark)
d. Docs
• Doxygen output under docs/html
• util → algebra, arrays, cbor, random
• algebra → circuits & sumcheck
• cbor, ec, gf2k, merkle → circuits
• circuits (compiler backend) → sumcheck & zk layers
• sumcheck → zk_prover & zk_verifier
• zk_prover/zk_verifier → external APIs (application code)
Architectural Patterns & Principles
• Modular layering: each lib/* folder is a logical module
• Clear separation: low-level math (util, algebra) → circuit definitions → proof protocols
• Extensible circuit framework: new circuits can plug into compiler and zk layers
• Build isolation via CMake subprojects
Key Technologies/Frameworks
• C++17
• CMake for build orchestration
• Docker (devcontainer)
• Doxygen for API docs
• OpenSSL, Zstd (compression)
• googletest, googlebenchmark
• Core functionality: the five pillars (util, algebra, circuits, sumcheck, zk).
• Extension points: circuits/* folders (anoncred, jwt, mdoc, etc.) and compiler backends.
• How applications link against libzk (expose Public API).
• Blue: Core Math (util, algebra, ec, gf2k)
• Green: Data Structures/Parsing (arrays, cbor, merkle, random)
• Orange: Circuit Definitions (circuits/*)
• Purple: Protocols (sumcheck, zk)
• Gray: Build, CI, Docs, Tests
Step 7: Essential Elements to Include
• Arrowheads indicating dependency direction or data flow.
• Title specifying “Longfellow ZK Architecture.”
• Footnote listing external dependencies and build tools.