# o1-labs/o1js architecture

> Architecture diagram of the GitHub repository o1-labs/o1js, 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/o1-labs/o1js
- Repository: https://github.com/o1-labs/o1js

## Overview

Based on our analysis of the complete file tree and README, this project (o1js) is a TypeScript library designed to empower developers when building zero knowledge-enabled applications (zkApps) on the Mina Protocol. It evolved from the earlier SnarkyJS and now offers a modular and layered implementation for everything from cryptographic primitives to zkApp-specific functionality, with additional ancillary modules such as a dedicated mina-signer.

##### Main Components
- Core Library Modules: These lie primarily in the src/lib folder. They are organized into several logical areas:
- Mina-specific components (“src/lib/mina”) with versions v1 and v2 that encapsulate account updates, transactions, smart contracts, and blockchain interactions.
- The Proof System (“src/lib/proof-system”) which implements zero-knowledge proof creation and verification, including caching, workers, and recursive proof handling.
- Provable Components (“src/lib/provable”) that provide a layer for declaring and managing provable types, cryptographic primitives, and gadgets.
- Additional utility and testing support in directories like “src/lib/util” and “src/lib/testing”.
- Bindings and Build Infrastructure: Look inside “src/bindings” and “src/build” – these modules handle artifact generation (e.g., JavaScript/Node and web bindings), copying artifacts, and build pipelines.
- Examples & Demos: The “src/examples” directory contains a broad set of examples (from basic API exploration to full zkApp examples, circuit samples, and even several “zkapps” subdirectories) that illustrate various application scenarios.
- Additional Tools: The “src/mina-signer” subproject is a separate module focused on signing functionality and transaction handling. It uses its own scripts, tests, and configuration.
- CI/CD & DevOps: There is significant configuration in the .github directory (workflows, actions) and additional scripts (e.g., run-all-local-tests.sh, update-changelog.sh) to automate testing, build, and release duties.

##### Relationships and Interactions
- Core library modules interact in a layered manner: lower-level cryptographic primitives and provable types support the proof system modules, which in turn power the Mina-specific functionalities.
- The Mina layers (v1 and v2) are built atop these core concepts and share testing and utility modules.
- The build and binding systems, while not directly contributing to runtime functionality, interlink with the core modules, ensuring that both Node and browser environments get proper bindings.
- The mina-signer acts as a complementary tool that interfaces with the core cryptographic and transaction modules from the main o1js codebase.
- Multiple examples and test suites show how clients can interact with these libraries, so represent the data flow from API usage (via examples) into the core modules and then into signing/proof systems.

##### Architectural Patterns & Design Principles
- Modularization: The project is divided into functional libraries (mina, proof-system, provable) so that each component has a single, clear responsibility.
- Layered Architecture: The system builds from low-level cryptographic primitives up through abstraction layers to domain-specific functionality (e.g., zkApp app development) and accompanying client libraries.
- Test-Driven Development & CI Integration: A strong emphasis on testing (unit tests, integration tests, benchmarks, and CI pipelines in GitHub Actions) ensures robust system behavior.
- Extensibility: The design supports adding higher-level functionality (new zkApp examples, additional signing methods) with a cohesive modular approach.
- Continuous Integration/Delivery: The extensive presence of GitHub workflows and build scripts emphasizes automated testing and release management.

## Diagram (Mermaid)

```mermaid
graph TD
    Core["o1js Core"]:::core

    subgraph "Foundation Layer"
        Provable["Provable Components"]:::found
        Utility["Utility & Testing Support"]:::found
    end

    subgraph "Intermediate Layer"
        Proof["Proof System Module"]:::intermediate
        Mina_v1["Mina v1"]:::intermediate
        Mina_v2["Mina v2"]:::intermediate
    end

    subgraph "Application & Auxiliary Tools"
        Bindings["Bindings & Build Infrastructure"]:::aux
        Examples["Examples & Demos"]:::aux
        Signer["mina-signer"]:::aux
    end

    subgraph "Development/Operational Layer"
        CI["CI/CD & DevOps"]:::dev
    end

    Core --> Provable
    Core --> Utility

    Provable -->|"supports"| Proof
    Proof -->|"supports"| Mina_v1
    Proof -->|"supports"| Mina_v2
    Provable -->|"supports"| Mina_v1
    Provable -->|"supports"| Mina_v2
    Utility -->|"supports"| Mina_v1
    Utility -->|"supports"| Mina_v2

    Core --> Bindings
    Core --> Examples
    Core --> Signer

    Bindings -->|"triggers"| CI
    Examples -->|"triggers"| CI
    Signer -->|"triggers"| CI

    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px,color:black;
    classDef found fill:#90ee90,stroke:#333,stroke-width:2px,color:black;
    classDef intermediate fill:#add8e6,stroke:#333,stroke-width:2px,color:black;
    classDef aux fill:#ffb6c1,stroke:#333,stroke-width:2px,color:black;
    classDef dev fill:#D3D3D3,stroke:#333,stroke-width:2px,color:black;

    click Provable "https://github.com/o1-labs/o1js/tree/main/src/lib/provable"
    click Proof "https://github.com/o1-labs/o1js/tree/main/src/lib/proof-system"
    click Mina_v1 "https://github.com/o1-labs/o1js/tree/main/src/lib/mina/v1"
    click Mina_v2 "https://github.com/o1-labs/o1js/tree/main/src/lib/mina/v2"
    click Utility "https://github.com/o1-labs/o1js/tree/main/src/lib/util"
    click Utility "https://github.com/o1-labs/o1js/tree/main/src/lib/testing"
    click Bindings "https://github.com/o1-labs/o1js/tree/main/src/bindings"
    click Bindings "https://github.com/o1-labs/o1js/tree/main/src/build"
    click Examples "https://github.com/o1-labs/o1js/tree/main/src/examples"
    click Signer "https://github.com/o1-labs/o1js/tree/main/src/mina-signer"
    click CI "https://github.com/o1-labs/o1js/blob/main/.github"
    click CI "https://github.com/o1-labs/o1js/blob/main/run-all-local-tests.sh"
    click CI "https://github.com/o1-labs/o1js/blob/main/update-changelog.sh"
```
