# tlsnotary/tlsn architecture

> Architecture diagram of the GitHub repository tlsnotary/tlsn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tlsnotary/tlsn
- Repository: https://github.com/tlsnotary/tlsn

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Shared Libraries Layer (Blue)
    subgraph "Shared Libraries"
        CC["Cryptographic Circuits\n(crates/components)"]:::blue
        TC["TLS Core Library\n(crates/tls/core)"]:::blue
        CU["Common Utilities\n(crates/common)"]:::blue
        DF["Data Formats Utilities\n(crates/formats)"]:::blue
        DFX["HTTP/TLS Test Fixtures\n(crates/data-fixtures)"]:::blue
        MPC["Multiparty TLS Logic\n(crates/mpc-tls)"]:::blue
    end

    %% Protocol Roles Layer (Green)
    subgraph "Protocol Roles"
        PR["Prover Library\n(crates/prover)"]:::green
        VR["Verifier Library\n(crates/verifier)"]:::green
    end

    %% Notary Service & CLI Layer (Orange)
    subgraph "Notary Service & CLI"
        NS["Notary Server\n(crates/notary/server)"]:::orange
        NC["Notary Client CLI\n(crates/notary/client)"]:::orange
    end

    %% Native TLS Clients & Fixtures (Orange)
    subgraph "Native TLS Clients & Fixtures"
        NTC["Native TLS Client\n(crates/tls/client &\ncrates/tls/client-async)"]:::orange
        TSF["TLS Server Fixture\n(crates/tls/server-fixture)"]:::orange
        GSFX["Generic Server Fixture\n(crates/server-fixture)"]:::orange
    end

    %% WASM & Browser UI Layer (Purple)
    subgraph "WASM & Browser UI"
        WASM["WASM Bindings\n(crates/wasm)"]:::purple
        WTR["WASM Test Runner & Browser UI\n(crates/wasm-test-runner)"]:::purple
    end

    %% Data Flows and Interactions
    CC -->|provides circuits| MPC
    MPC -->|TLS primitives| TC
    CC -->|crypto functions| PR
    MPC -->|multi-party handshake| PR
    TC -->|transcript mgmt| PR
    CC -->|crypto functions| VR
    MPC -->|multi-party handshake| VR
    TC -->|transcript mgmt| VR

    NTC -->|native calls| PR
    NTC -->|native calls| VR
    TSF -->|test fixture| PR
    TSF -->|test fixture| VR
    GSFX -->|demo server| PR
    GSFX -->|demo server| VR

    NC -->|HTTP/WebSocket| NS
    NS -->|delegates proof| PR
    NS -->|delegates verify| VR

    WTR -->|UI tests| WASM
    WASM -->|wasm-bindgen| PR
    WASM -->|wasm-bindgen| VR

    %% Click Events
    click CC "https://github.com/tlsnotary/tlsn/tree/main/crates/components"
    click TC "https://github.com/tlsnotary/tlsn/tree/main/crates/tls/core"
    click CU "https://github.com/tlsnotary/tlsn/tree/main/crates/common"
    click DF "https://github.com/tlsnotary/tlsn/tree/main/crates/formats"
    click DFX "https://github.com/tlsnotary/tlsn/tree/main/crates/data-fixtures"
    click MPC "https://github.com/tlsnotary/tlsn/tree/main/crates/mpc-tls"
    click PR "https://github.com/tlsnotary/tlsn/tree/main/crates/prover"
    click VR "https://github.com/tlsnotary/tlsn/tree/main/crates/verifier"
    click NS "https://github.com/tlsnotary/tlsn/tree/main/crates/notary/server"
    click NC "https://github.com/tlsnotary/tlsn/tree/main/crates/notary/client"
    click NTC "https://github.com/tlsnotary/tlsn/tree/main/crates/tls/client"
    click TSF "https://github.com/tlsnotary/tlsn/tree/main/crates/tls/server-fixture"
    click GSFX "https://github.com/tlsnotary/tlsn/tree/main/crates/server-fixture"
    click WASM "https://github.com/tlsnotary/tlsn/tree/main/crates/wasm"
    click WTR "https://github.com/tlsnotary/tlsn/tree/main/crates/wasm-test-runner"

    %% Styles
    classDef blue fill:#cfe2f3,stroke:#0366d6,color:#0366d6;
    classDef green fill:#d5f5e3,stroke:#28a745,color:#155724;
    classDef orange fill:#ffe5b4,stroke:#fd7e14,color:#6a1b0c;
    classDef purple fill:#e2d5f5,stroke:#6f42c1,color:#4a235a;
```
