# mratsim/constantine architecture

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

- Interactive diagram: https://gitdiagram.com/mratsim/constantine
- Repository: https://github.com/mratsim/constantine

## Overview

##### Main Components and Their Roles
- Core Library (Constantine Core):
– Written in Nim, this is the heart of the system.
– Contains low‑level modules such as field arithmetic, elliptic curve operations (affine, Jacobian, projective coordinates), finite field arithmetic, and assembly/hardware acceleration.
– Hosts constant‑time implementations and uses inline assembly on x86/x86‑64 (with the potential for ARM/GPU support in the future).
- Cryptographic Primitives & Modules:
– “Elliptic Curves” module for supported curves (BN254, BLS12‑381, Pallas & Vesta).
– “General Cryptography” module with hash routines (SHA256) and csprngs.
– “Protocols” layer that implements blockchain‑related protocols such as Ethereum BLS signatures, KZG commitments (EIP‑4844), IPA commitments, and EVM precompiles.
- Threadpool and Parallelism:
– A dedicated module (with its own subdirectory “constantine/threadpool” and docs) responsible for high‑performance parallel execution.
– Exposes APIs like spawn, parallelFor and nested reductions to support multi‑threaded cryptographic computations.
- Language Bindings & Wrappers:
– C bindings: Includes header directories (./include/constantine) and examples in “examples-c”.
– Rust wrappers and the lower‑level “constantine-sys” are organized under constantine‑rust.
– Go integration through the separate “constantine-go” directory.
– Additionally, Nim remains the primary language so there is a nimble package file and a nimble project file.
- Testing, Benchmarks & Research:
– Large “tests” and “benchmarks” directories ensure correctness and performance validation.
– “research” and “docs” directories cover performance details, threadpool design, hardware acceleration, and even formal verification aspects.

##### Relationships and Interactions
- The Core Library exposes a well‑defined API (via public modules for curves, hashes, etc.) that the Protocol implementations build upon.
- The Protocol layer “sits” on top of the core arithmetic – for example, Ethereum BLS signatures use the underlying BLS12‑381 and BN254 arithmetic.
- The high‑performance Threadpool interacts with both the core arithmetic and protocol implementations to enable efficient parallel and nested computations.
- The language bindings (Rust, C, Go) wrap the functionality from the core library, exposing the high‑level APIs for integration in software written in those languages.
- Testing and benchmarking components validate each layer and serve as a quality “guard” throughout the library.
- The build system (Nimble scripts, Cargo.toml, Go modules) around the different language directories coordinate compilation, linking (including LTO if enabled) and integration testing.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separate low‑level arithmetic primitives, mid‑level protocol implementations, and high‑level language bindings.
- Modularity: Each cryptographic primitive (elliptic curves, hash functions, RNG, threadpool) is in its own module to facilitate testing, re‑use, and future extensions.
- Performance and Security Specialization: The use of constant‑time implementations, assembly optimizations, and a CPU topology‑aware threadpool are central design choices.
- Cross‑language FFI: The design anticipates consumers from multiple language environments through clearly defined headers (C) and wrapper modules (Rust and Go).

##### Relevant Technologies, Frameworks, and Libraries
- Nim is used as the primary implementation language.
- The build system is primarily Nimble with integrations into Cargo (Rust) and Go modules.
- Assembly files (and inline assembly) are utilized on supported architectures.
- External compilers (primarily Clang) are recommended to optimize both performance and constant‑time guarantees.
- The system relies on standard libraries only (keeping external dependencies minimal for security reasons) and includes benchmarks and tests that reference GMP and LLVM (only as tools, not as linked libraries).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Layer
    subgraph "Core Library Layer"
        coreLib["Core Library (Constantine Core)"]:::core
        lowEll["Low-Level Elliptic Curves"]:::core
        mathMod["Math Modules"]:::core
        hashDir["Hashes"]:::core
        csprng["CSPRNGs"]:::core
    end

    %% Cryptographic Primitives
    subgraph "Cryptographic Primitives"
        ecModule["Elliptic Curves Module"]:::crypto
        genCrypto["General Cryptography"]:::crypto
    end

    %% Protocol Implementations
    subgraph "Protocol Implementations"
        ethBLS["Ethereum BLS Signatures"]:::protocol
        kzg["KZG Commitments/EIP4844"]:::protocol
        ipaEVM["IPA & EVM Precompiles"]:::protocol
        ethECDSA["Ethereum ECDSA Signatures"]:::protocol
        ethVerkle["Ethereum Verkle IPA"]:::protocol
    end

    %% Parallel Execution (Threadpool)
    subgraph "Parallel Execution Layer"
        threadpool["Threadpool Parallel Engine"]:::thread
    end

    %% Language Bindings & Wrappers
    subgraph "Language Bindings"
        cBinding["C Bindings"]:::binding
        rustBinding["Rust Wrappers"]:::binding
        goBinding["Go Integration"]:::binding
        nimBinding["Nim (Primary)"]:::binding
    end

    %% Testing, Benchmarks & Research
    subgraph "Validation & Research"
        testsNode["Tests"]:::validation
        benchmarksNode["Benchmarks"]:::validation
        benchThreadpool["Threadpool Benchmarks"]:::validation
        researchDocs["Research & Documentation"]:::validation
    end

    %% Arrows: Core Library exposes primitives
    coreLib -->|"exposes"| ecModule
    coreLib -->|"exposes"| genCrypto
    mathMod -->|"supports"| ecModule
    hashDir -->|"supports"| genCrypto
    csprng -->|"supports"| genCrypto

    %% Arrows: Primitives used by protocols
    ecModule -->|"usedBy"| ethBLS
    ecModule -->|"usedBy"| ethECDSA
    genCrypto -->|"usedBy"| kzg
    genCrypto -->|"usedBy"| ipaEVM

    %% Arrows: Protocols invoking threadpool features
    ethBLS -->|"calls"| threadpool
    kzg -->|"calls"| threadpool
    ipaEVM -->|"calls"| threadpool

    %% Arrow: Threadpool optimizes core computations
    threadpool -->|"optimizes"| coreLib

    %% Arrows: Language Bindings wrap lower layers
    coreLib -->|"wrappedBy"| cBinding
    ecModule -->|"wrappedBy"| rustBinding
    ethBLS -->|"wrappedBy"| goBinding
    genCrypto -->|"wrappedBy"| nimBinding
    kzg -->|"wrappedBy"| rustBinding
    ipaEVM -->|"wrappedBy"| goBinding

    %% Arrows: Validation & Research connected to components
    coreLib --- testsNode
    ecModule --- testsNode
    ethBLS --- testsNode
    threadpool --- testsNode
    cBinding --- testsNode
    rustBinding --- testsNode
    goBinding --- testsNode

    ecModule --- benchmarksNode
    threadpool --- benchThreadpool
    researchDocs --- benchmarksNode

    %% Click Events for Core Library Layer
    click coreLib "https://github.com/mratsim/constantine/tree/master/constantine/"
    click lowEll "https://github.com/mratsim/constantine/blob/master/constantine/lowlevel_elliptic_curves.nim"
    click mathMod "https://github.com/mratsim/constantine/tree/master/constantine/math/"
    click hashDir "https://github.com/mratsim/constantine/tree/master/constantine/hashes/"
    click csprng "https://github.com/mratsim/constantine/blob/master/constantine/csprngs.nim"

    %% Click Events for Cryptographic Primitives
    click ecModule "https://github.com/mratsim/constantine/blob/master/constantine/lowlevel_elliptic_curves.nim"
    click genCrypto "https://github.com/mratsim/constantine/tree/master/constantine/kdf/"

    %% Click Events for Protocol Implementations
    click ethBLS "https://github.com/mratsim/constantine/blob/master/constantine/ethereum_bls_signatures.nim"
    click kzg "https://github.com/mratsim/constantine/blob/master/constantine/ethereum_eip4844_kzg.nim"
    click ipaEVM "https://github.com/mratsim/constantine/blob/master/constantine/ethereum_evm_precompiles.nim"
    click ethECDSA "https://github.com/mratsim/constantine/blob/master/constantine/ethereum_ecdsa_signatures.nim"
    click ethVerkle "https://github.com/mratsim/constantine/blob/master/constantine/ethereum_verkle_ipa.nim"

    %% Click Events for Threadpool
    click threadpool "https://github.com/mratsim/constantine/blob/master/constantine/threadpool.nim"
    click threadpool "https://github.com/mratsim/constantine/tree/master/constantine/threadpool/"

    %% Click Events for Language Bindings
    click cBinding "https://github.com/mratsim/constantine/tree/master/include/constantine/"
    click cBinding "https://github.com/mratsim/constantine/tree/master/examples-c/"
    click rustBinding "https://github.com/mratsim/constantine/tree/master/constantine-rust/constantine-core"
    click rustBinding "https://github.com/mratsim/constantine/tree/master/constantine-rust/constantine-sys"
    click goBinding "https://github.com/mratsim/constantine/tree/master/constantine-go/"
    click nimBinding "https://github.com/mratsim/constantine/blob/master/constantine.nimble"

    %% Click Events for Testing, Benchmarks & Research
    click testsNode "https://github.com/mratsim/constantine/tree/master/tests/"
    click benchmarksNode "https://github.com/mratsim/constantine/tree/master/benchmarks/"
    click benchThreadpool "https://github.com/mratsim/constantine/tree/master/benchmarks-threadpool/"
    click researchDocs "https://github.com/mratsim/constantine/tree/master/research/"
    click researchDocs "https://github.com/mratsim/constantine/tree/master/docs/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef crypto fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef protocol fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef thread fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef binding fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef validation fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
