How simoneroznowicz/master-thesis works
Project type and purpose (what you’re diagramming)
This is a single-machine, end-to-end Rust implementation of the PoEUS (Proof of Efficiently Usable Space) protocol. Even though everything runs as one process (cargo run --release -- <loglevel>), the codebase clearly models distinct protocol roles and phases (e.g., prover/verifier/client-like communication) and a data pipeline (input file → block generation/encoding → commitments/Merkle structures → proof generation → verification).
File structure analysis (what the architecture wants to be)
Top-level:
• PoEUS/CPoS/Cargo.toml → one Rust crate (likely one binary)
• PoEUS/CPoS/src/main.rs → entrypoint / orchestrator
• PoEUS/CPoS/src/block_generation/* → encoding/decoding pipeline, block creation, utilities
• PoEUS/CPoS/src/Merkle_Tree/* → Merkle tree structures and verification
• PoEUS/CPoS/src/PoS/* → proof generation and verification logic (prover/verifier roles)
• PoEUS/CPoS/src/communication/* → message/path generation, client abstraction, protocol structs
• input.mp4, output.bin → sample workload artifacts (filesystem IO is part of the real system)
This strongly suggests an internal architecture of:
Orchestrator → Block Generation → Commitment (Merkle) → Challenge/Path selection → Prover → Verifier
with “communication” acting as the glue for “who sends what to whom”, even if it’s in-memory.
README insights (what to emphasize)
• It is a complete end-to-end protocol implementation, not just a library.
• It’s sensitive to performance/parallelization in *block generation* (important to annotate concurrency/CPU-heavy stage).
• Operates on large input files (GB-scale), so the data plane (file → blocks → encoded artifacts) matters.
CLI / Entrypoint
• src/main.rs
• Responsibility: parse log level, run protocol end-to-end, coordinate phases.
Block Generation Subsystem
• src/block_generation/main.rs, blockgen.rs, encoder.rs, decoder.rs, utils.rs
• Responsibility: read input.mp4, split into blocks, encode blocks, possibly decode for checks, produce on-disk/in-memory representations (e.g., output.bin).
Merkle Tree / Commitment Subsystem
• src/Merkle_Tree/mod.rs, structs.rs, client_verify.rs
• Responsibility: build Merkle tree over block commitments (or encoded blocks), provide root commitment, provide/verify Merkle proofs (paths).
Proof-of-Space / Protocol Logic
• src/PoS/prover.rs, verifier.rs, utils.rs, mod.rs
• Responsibility: implement PoEUS proving and verification steps; “Prover” generates responses; “Verifier” checks them.
Communication / Message & Path Orchestration
• src/communication/client.rs, path_generator.rs, structs.rs, mod.rs
• Responsibility: define protocol messages/structs, generate challenge paths / queries, emulate client/verifier interactions.
External Dependencies (explicitly show them even if not in tree)
• Filesystem (reads input.mp4, writes output.bin)
• CPU / Parallel execution (block generation parallelization)
Architectural patterns / principles
• Pipeline architecture: block generation → commitment → challenge/prove → verify
• Role separation (even in-process): Prover vs Verifier vs Client/Coordinator
• Deterministic data structure verification: Merkle proofs enable verification without full data
• Performance hotspot: block generation is parallelizable; annotate it with “parallel / CPU-bound”
Relevant technologies
• Rust binary crate (single executable)
• Merkle Tree (commitment + membership proofs)
• Proof protocol modules: prover.rs / verifier.rs
C4 Level 1 (Context)
• Actor: “User (runs cargo)”
• System: “PoEUS Protocol Runner (CPoS)”
• External: Filesystem (input/output)
C4 Level 2 (Container) (even if everything is one binary, treat modules as containers)
• CLI/Orchestrator
• Block Generation
• Commitment (Merkle)
• PoS Prover
• PoS Verifier
• Communication/Path Generator
• Filesystem
C4 Level 3 (Component) (map directly to directories/files)
• Block Generation: encoder/decoder/blockgen
• PoS: prover/verifier/utils
• Merkle: structs/client_verify
• Communication: client/path_generator/structs
Runtime ordering:
• main → block_generation(main/blockgen/encoder)
• build Merkle root
• path_generator produces challenges
• prover constructs proof (+ Merkle paths)
• verifier validates (possibly via client_verify)
• return result
This combo removes confusion about “is it distributed?” while still accurately representing the protocol roles.
Diagramming rules to follow (make it unambiguous)
Elements explicitly:
• Clear labels
• bulk data (thick line) vs proof/messages (thin line)
• Example scheme:
• Blue rectangles: internal Rust modules
• Orange hexagon: cryptographic primitive (hash)
• Green rounded rectangles: protocol roles (Prover/Verifier)
• Annotate trust boundaries
• Even on one machine, mark conceptual boundaries:
• “Prover side” vs “Verifier side”
• This is crucial for protocol comprehension.
Concrete “best” component breakdown for *this repo* (don’t overthink—split aggressively)
• main.rs (Orchestrator)
• block_generation::main
• block_generation::blockgen
• block_generation::encoder
• block_generation::decoder
• block_generation::utils
• Merkle_Tree::structs
• Merkle_Tree::client_verify
• PoS::prover
• PoS::verifier
• PoS::utils
• communication::client
• communication::path_generator
• communication::structs
• External: Filesystem input/output