How tlsnotary/tlsn works
Project Type and Purpose
• This is a Rust-based monorepo implementing the TLSNotary protocol—a secure multi‑party computation system for data provenance and privacy.
• It hosts multiple libraries (“prover”, “verifier”, “tls core”, “components” for cryptographic circuits, etc.), services (the “notary” server and client), tooling (WASM build, benchmarks, test fixtures), and example applications.
File Structure Analysis
• Top‑level Cargo workspace with dozens of crates under crates/.
– crates/components/: low‑level ZK‑circuit libraries (AES, HMAC, key‑exchange).
– crates/common/, crates/core/, crates/formats/, crates/mpc-tls/: shared utilities, TLS logic, multi‑party handshake.
– crates/prover/ & crates/verifier/: core protocol roles, each depending on common, core, components, and mpc-tls.
– crates/notary/: Axum‑based notary server + CLI client; relies on prover/verifier libraries and TLS stacks.
– crates/tls/: standalone Rust TLS client and server‑fixture crates.
– crates/wasm/: Rust→WASM bindings exposing prover/verifier to JS, plus a crates/wasm-test-runner.
– crates/examples/, crates/benches/, crates/tests-integration/, crates/data-fixtures/: samples, benchmarks, end‑to‑end tests, and HTTP/TLS fixtures.
Key README Insights
• The repo’s goal is to provide a Rust implementation of TLSNotary with libraries for prover/verifier and a standalone notary service.
• Highlights support for both native and WASM targets, external dependency on OpenSSL and clang for WASM builds.
Components to Highlight
a. Library Layer (shared code):
– Cryptographic Circuits (components)
– TLS Core (tls/core)
– Common Utilities (common, formats, data-fixtures)
– Multiparty TLS Logic (mpc-tls)
b. Protocol Roles:
– Prover (prover crate)
– Verifier (verifier crate)
c. Notary Service:
– Notary Server (REST & WebSocket via Axum)
– Notary Client CLI
d. TLS Clients/Servers:
– Native TLS Client (tls/client-async, tls/client)
– Server Fixture for testing (server-fixture, tls/server-fixture)
e. WebAssembly Front‑End:
– WASM bindings (wasm crate)
– Test Runner & Browser UI (wasm-test-runner)
f. External Dependencies:
– OpenSSL (via openssl-sys)
– clang/LLVM (for WASM target)
Interactions and Data Flows
• Prover and Verifier use the TLS Core + Crypto Components to produce and consume ZK proofs.
• The Notary Client interacts with the Notary Server over HTTP/WebSocket; server delegates proof generation/verification to respective libraries.
• Native and WASM clients both call into the same prover/verifier logic via either direct crate linkage or wasm-bindgen interfaces.
• TLS handshake messages flow through mpc-tls into circuits in components, then into core for transcript management.
Architectural Patterns and Principles
• Multi‑crate Cargo workspace enforcing clear module boundaries.
• Layered design: low‑level crypto → TLS primitives → protocol roles → services/UI.
• Polyglot targets: native (x86_64) and WASM (wasm32-unknown-unknown).
• Service‑oriented approach for the notary server (Axum + Tokio).
Technologies and Frameworks
• Rust + Cargo workspaces
• Axum (HTTP/WebSocket server)
• Tokio (async runtime)
• wasm-bindgen & web-sys for WASM
• OpenSSL-sys, clang/LLVM for native crypto
• Docker (benchmarks), GitHub Actions CI