# arkworks-rs/algebra architecture

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

- Interactive diagram: https://gitdiagram.com/arkworks-rs/algebra
- Repository: https://github.com/arkworks-rs/algebra

## Overview

##### Project type and purpose
- This is an open-source Rust “monorepo” containing multiple interrelated crates for algebraic primitives underlying zkSNARKs.
- Core functionality:
- ark-ff – finite‐field abstractions & implementations
- ark-ec – elliptic‐curve abstractions & implementations (pairing‐friendly + standard curves)
- ark-poly – univariate/multivariate polynomials & FFTs
- ark-serialize – serialization/compression for fields & curves
- Extension repository “curves”: dozens of per‐curve crates that implement concrete curves by plugging into ark-ff & ark-ec.
- Supporting crates: bench-templates, test-curves, scripts, macros, assembly backend (ff-asm), derive macros (ff-macros, serialize-derive), poly/serialize test templates.

##### Key directories and architectural patterns
- Top-level workspace with multiple crates. Cargo.toml defines the workspace and inter‐crate dependencies.
- Crates folder structure shows clear module boundaries (src/lib.rs, src/*).
- “curves” is its own directory, containing sub-crates for each elliptic curve (e.g., bls12_381, bn254, secp256k1).
- Build scripts (makefile, .github/workflows) orchestrate CI, benchmarks, tests, and assembly feature flags.
- Scripts directory holds Python/Sage scripts for test‐vector generation and Git hooks.

1. Core crates: ark-ff, ark-ec, ark-poly, ark-serialize
2. Assembly backend: ff-asm (feature of ark-ff)
3. Macros crates: ff-macros, serialize-derive
4. Curves: each sub-crate under /curves (group these as “Curves Marketplace” with sample curves)
5. Bench-templates & test-curves (benchmarking & integration tests)
6. Scripts & CI (pre-commit hooks, changelog linkifier, workflows)
7. External tool: Sage (for curve parameters scripts)
- ark-ec → ark-ff
- ark-poly → ark-ff
- ark-serialize → ark-ff, ark-ec
- ff-asm → ark-ff (opt‐in feature)
- ff-macros → ark-ff (codegen)
- serialize-derive → ark-serialize
- Curves (each) → ark-ff, ark-ec
- bench-templates, test-curves → all core crates + curves
- Scripts → CI workflows, Cargo builds, Sage
c. Architectural patterns & principles
- Modular workspace pattern: each crate is a reusable library with clear API surface.
- Plugin/extensibility: curves repository shows how new curves plug into generic traits from ark-ff & ark-ec.
- Feature flags for optional assembly backend.
- Separation of concerns: arithmetic, serialization, polynomial operations, curve implementations.
d. Technologies & frameworks
- Rust + Cargo workspace
- Inline assembly via Rust nightly (+bmi2,+adx)
- Sage scripts for generating field/curve parameters
- Python scripts for test‐vector/changelog tooling
- GitHub Actions for CI & linting

##### Essential details to capture
- Component’s role (e.g., “ark-ff: field arithmetic & big-integer”).
- How generic traits flow from core crates to concrete implementations in curves.
- Test & benchmark pipelines and how scripts integrate with CI.
- External dependencies (Sage, Python, Rust nightly).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Crates
    subgraph "Core Crates"
        FF["ark-ff: field arithmetic & big-integer"]:::core
        EC["ark-ec: elliptic-curve abstractions & implementations"]:::core
        POLY["ark-poly: univariate/multivariate polynomials & FFTs"]:::core
        SER["ark-serialize: serialization & compression"]:::core
    end

    %% Optional Features & Macros
    subgraph "Optional Features & Macros"
        ASM["ff-asm: assembly backend"]:::optional
        MACRO["ff-macros: field codegen macros"]:::optional
        SDER["serialize-derive: serialization derive macros"]:::optional
    end

    %% Curves Marketplace
    subgraph "Curves Marketplace"
        BLS["bls12_381"]:::curve
        BN["bn254"]:::curve
        SECP["secp256k1"]:::curve
    end

    %% Tooling & Scripts
    subgraph "Tooling & Scripts"
        BENCH["bench-templates"]:::tool
        TEST["test-curves"]:::tool
        SCRIPTS["scripts"]:::tool
        CI["CI Workflows & Hooks"]:::tool
    end

    %% External Dependencies
    subgraph "External Dependencies"
        SAGE["Sage"]:::external
        PY["Python"]:::external
        RUSTN["Rust Nightly"]:::external
    end

    %% Dependencies
    EC -->|"depends on"| FF
    POLY -->|"depends on"| FF
    SER -->|"depends on"| FF
    SER -->|"depends on"| EC
    ASM -->|"opt-in feature of"| FF
    MACRO -->|"codegen for"| FF
    SDER -->|"derive for"| SER

    BLS -->|"implements via"| FF
    BLS -->|"implements via"| EC
    BN -->|"implements via"| FF
    BN -->|"implements via"| EC
    SECP -->|"implements via"| FF
    SECP -->|"implements via"| EC

    BENCH -->|"benchmarks"| FF
    BENCH -->|"benchmarks"| EC
    BENCH -->|"benchmarks"| POLY
    BENCH -->|"benchmarks"| SER
    BENCH -->|"benchmarks"| BLS
    BENCH -->|"benchmarks"| BN
    BENCH -->|"benchmarks"| SECP

    TEST -->|"tests"| FF
    TEST -->|"tests"| EC
    TEST -->|"tests"| POLY
    TEST -->|"tests"| SER
    TEST -->|"tests"| BLS
    TEST -->|"tests"| BN
    TEST -->|"tests"| SECP

    SCRIPTS -->|"triggers"| CI
    SCRIPTS -->|"generates vectors with"| SAGE
    SCRIPTS -->|"uses"| PY

    RUSTN -->|"required for inline assembly"| ASM

    %% Click Events
    click FF "https://github.com/arkworks-rs/algebra/tree/master/ff/"
    click EC "https://github.com/arkworks-rs/algebra/tree/master/ec/"
    click POLY "https://github.com/arkworks-rs/algebra/tree/master/poly/"
    click SER "https://github.com/arkworks-rs/algebra/tree/master/serialize/"
    click ASM "https://github.com/arkworks-rs/algebra/tree/master/ff-asm/"
    click MACRO "https://github.com/arkworks-rs/algebra/tree/master/ff-macros/"
    click SDER "https://github.com/arkworks-rs/algebra/tree/master/serialize-derive/"
    click BLS "https://github.com/arkworks-rs/algebra/tree/master/curves/bls12_381/"
    click BN "https://github.com/arkworks-rs/algebra/tree/master/curves/bn254/"
    click SECP "https://github.com/arkworks-rs/algebra/tree/master/curves/secp256k1/"
    click BENCH "https://github.com/arkworks-rs/algebra/tree/master/bench-templates/"
    click TEST "https://github.com/arkworks-rs/algebra/tree/master/test-curves/"
    click CI "https://github.com/arkworks-rs/algebra/tree/master/.github/workflows/"
    click SCRIPTS "https://github.com/arkworks-rs/algebra/tree/master/scripts/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#2B6CB0,color:#2B6CB0
    classDef optional fill:#E9D8FD,stroke:#6B46C1,color:#6B46C1,stroke-dasharray: 5 5
    classDef curve fill:#E6FFFA,stroke:#2F855A,color:#2F855A
    classDef tool fill:#FFF5E6,stroke:#DD6B20,color:#DD6B20
    classDef external fill:#F7FAFC,stroke:#718096,color:#2D3748,stroke-dasharray: 2 2
```
