# signalapp/sparsepostquantumratchet architecture

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

- Interactive diagram: https://gitdiagram.com/signalapp/sparsepostquantumratchet
- Repository: https://github.com/signalapp/sparsepostquantumratchet

## Overview

##### Project Type and Purpose
- Type: A Rust cryptographic library (crate) implementing a post-quantum secure ratchet protocol.
- Purpose: Produce message keys for encryption/decryption to provide Forward Secrecy (FS) and Post-Compromise Security (PCS).
- Not a standalone messaging service—designed for integration into hybrid secure messaging protocols.

##### File Structure
Top-level:
- Cargo.toml / build.rs – Rust build configuration and custom build script.
- hax.py, proofs/ – Tools and artifacts for formal verification (F* extraction, ProVerif models).
- benches/ – Benchmark harnesses for performance testing.
- src/ – Core Rust modules:
– chain.rs: Symmetric ratchet state machine
– v1/: ML-KEM braid public ratchet implementation
– encoding/: Erasure coding (Reed-Solomon), finite-field arithmetic
– authenticator.rs: Message authentication support
– kdf.rs: Key derivation function
– proto.rs / proto/pq_ratchet.proto: Protobuf definitions & codegen for message framing
– serialize.rs: (De)serialization utilities
– test/: Integration and behavior tests
– util.rs: Shared helper routines

##### Extract Architectural Insights from the README
- Core protocol split into:
– Public ratchet (v1/ML-KEM Braid)
– Symmetric ratchet (chain.rs)
– Encoding layer for chunked message resilience
- Formal verification pipeline: hax (F* extraction) + ProVerif models
- CI workflows trigger tests, benchmarks, and proofs

a. Main Components
1. API Layer (public Rust crate interface)
2. Public Ratchet Module (src/v1)
3. Symmetric Ratchet Module (src/chain.rs)
4. Encoding Layer (src/encoding)
5. Serialization & Protobuf (src/proto, serialize.rs)
6. Authenticator & KDF (src/authenticator.rs, src/kdf.rs)
7. Tests & Benchmarks (src/test, benches/)
8. Formal Verification Tools (hax.py, proofs/fstar, proofs/proverif)
9. Build & CI (build.rs, .github/workflows/*.yml)

b. Relationships & Data Flows
- Consumer calls into API → assembles handshake parameters → Public Ratchet
- Public Ratchet produces shared secret → fed into KDF → Symmetric Ratchet
- Symmetric Ratchet state → derives message keys
- Outgoing message keys + plaintext → Encoding layer (chunking + erasure codes)
- Chunks → Serializer / Protobuf → Network transport (external)
- Incoming raw data → Deserializer → Encoding decode → Symmetric ratchet decrypt
- All modules rely on util.rs for shared math and byte-buffer routines

c. Architectural Patterns & Principles
- Layered design: Key agreement → symmetric state machine → encoding → serialization
- Clear separation of public vs. symmetric ratchet concerns
- Formal‐verification pipeline isolated from core library code
- Benchmarks and tests decoupled from production API

d. Key Technologies & Frameworks
- Rust + Cargo for build and dependency management
- Protobuf (via proto/pq_ratchet.proto)
- hax + F* for machine‐checked proofs
- ProVerif for symbolic security proofs
- Reed-Solomon erasure coding (in encoding/polynomial.rs)

##### Diagramming Recommendations
– Handshake → shared secret → KDF → ratchet → keys → encode → serialize
– Blue: Core ratchet logic
– Green: Encoding & serialization
– Orange: Verification & CI

##### Essential Architectural Elements
- Public-ratchet vs. symmetric-ratchet layers
- Encoding resilience (chunking + erasure codes)
- Protobuf framing boundary
- Verification pipeline (hax → F* → ProVerif)
- CI/build orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    API["API Layer"]:::api
    click API "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/lib.rs"

    %% Core Ratchet Logic
    subgraph "Core Ratchet Logic"
        direction TB
        PR["Public Ratchet Module"]:::core
        click PR "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/v1.rs"
        click PR "https://github.com/signalapp/sparsepostquantumratchet/tree/main/src/v1/"
        SR["Symmetric Ratchet Module"]:::core
        click SR "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/chain.rs"
        Util["Shared Utilities"]:::core
        click Util "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/util.rs"
    end

    %% Encoding & Serialization
    subgraph "Encoding & Serialization"
        direction TB
        ENC["Encoding Layer"]:::enc
        click ENC "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/encoding.rs"
        click ENC "https://github.com/signalapp/sparsepostquantumratchet/tree/main/src/encoding/"
        SER["Serialization & Protobuf"]:::enc
        click SER "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/serialize.rs"
        click SER "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/proto.rs"
        click SER "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/proto/pq_ratchet.proto"
        click SER "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/proto/pq_ratchet.rs"
    end

    %% Authenticator & KDF
    subgraph "Authentication & KDF"
        direction TB
        AUTH["Authenticator"]:::security
        click AUTH "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/authenticator.rs"
        click AUTH "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/authenticator/serialize.rs"
        KDF["Key Derivation Function"]:::security
        click KDF "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/kdf.rs"
    end

    %% Tests & Benchmarks
    subgraph "Tests & Benchmarks"
        direction TB
        TBENCH["Benchmarks"]:::test
        click TBENCH "https://github.com/signalapp/sparsepostquantumratchet/tree/main/benches/"
        TTEST["Tests"]:::test
        click TTEST "https://github.com/signalapp/sparsepostquantumratchet/blob/main/src/test.rs"
        click TTEST "https://github.com/signalapp/sparsepostquantumratchet/tree/main/src/test/"
    end

    %% Formal Verification Tools
    subgraph "Formal Verification Tools"
        direction TB
        HAX["hax.py"]:::tools
        click HAX "https://github.com/signalapp/sparsepostquantumratchet/blob/main/hax.py"
        FSTAR["F* Extraction"]:::tools
        click FSTAR "https://github.com/signalapp/sparsepostquantumratchet/tree/main/proofs/fstar/"
        PROVERIF["ProVerif Models"]:::tools
        click PROVERIF "https://github.com/signalapp/sparsepostquantumratchet/tree/main/proofs/proverif/"
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        BUILD["build.rs"]:::infra
        click BUILD "https://github.com/signalapp/sparsepostquantumratchet/blob/main/build.rs"
        CARGO["Cargo.toml"]:::infra
        click CARGO "https://github.com/signalapp/sparsepostquantumratchet/blob/main/Cargo.toml"
        CI1["CI: hax.yml"]:::infra
        click CI1 "https://github.com/signalapp/sparsepostquantumratchet/blob/main/.github/workflows/hax.yml"
        CI2["CI: test.yml"]:::infra
        click CI2 "https://github.com/signalapp/sparsepostquantumratchet/blob/main/.github/workflows/test.yml"
    end

    %% External Integration
    EXT["Host Application / Network"]:::external

    %% Data Flows
    API -->|"Handshake Params"| PR
    PR -->|"SharedSecret"| KDF
    KDF -->|"DerivedKeys"| SR
    SR -->|"MessageKeys"| ENC
    ENC -->|"Chunks"| SER
    SER -->|"Serialized Data"| EXT

    EXT -->|"Raw Data"| SER
    SER -->|"Deserialized Chunks"| ENC
    ENC -->|"Decoded Plaintext"| SR

    PR --> Util
    SR --> Util
    ENC --> Util
    SER --> Util
    AUTH --> SR
    AUTH --> SER

    %% QA Pipelines
    API --> TBENCH
    PR --> TBENCH
    SR --> TBENCH
    ENC --> TBENCH
    SER --> TBENCH

    HAX --> FSTAR
    HAX --> PROVERIF
    HAX --> TBENCH

    BUILD --> CI1
    BUILD --> CI2

    %% Styles
    classDef api fill:#AED6F1,stroke:#21618C,color:#1B4F72;
    classDef core fill:#D6EAF8,stroke:#2874A6,color:#154360;
    classDef enc fill:#D5F5E3,stroke:#28B463,color:#186A3B;
    classDef security fill:#FDEBD0,stroke:#DC7633,color:#935116;
    classDef test fill:#E8DAEF,stroke:#9B59B6,color:#4A235A;
    classDef tools fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef infra fill:#F2F3F4,stroke:#566573,color:#1C2833;
    classDef external fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
```
