# ingonyama-zk/icicle architecture

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

- Interactive diagram: https://gitdiagram.com/ingonyama-zk/icicle
- Repository: https://github.com/ingonyama-zk/icicle

## Overview

##### Main Components and Architecture

**┌─────────────────────────────────────────────────────────────┐**
- Language Bindings                        │
- ┬───────────────────────────┬─────────────────┤
- Rust      │           Go              │       C++       │
- ┬───────┴──────────────┬────────────┴────────┬────────┘

**┌───────▼──────────────────────▼──────────────────────▼───────┐**
- ICICLE Core                            │
- ┤
- Primitives  │  Fields  │  Curves │ Hash │ Runtime │ Device  │
- ┬─────────────────────────────────────────────────────┘

**┌───────▼─────────────────────────────────────────────────────┐**
- Hardware Backends                         │
- ┬─────────────────────────┬─────────────────┤
- CPU        │         CUDA            │      Metal      │
- ┴─────────────────────────┴─────────────────┘

##### Component Details

a) Core Components (Rectangles):
- Cryptographic Primitives (NTT, MSM, etc.)
- Field Operations
- Curve Operations
- Hash Functions
- Runtime Management
- Device Management

b) Hardware Backends (Hexagons):
- CPU Backend
- CUDA Backend
- Metal Backend

c) Language Bindings (Rounded Rectangles):
- Rust Wrappers
- Go Wrappers
- C++ Interface

##### Data Flow and Interactions

**Application → Language Binding → Core → Backend → Hardware**

##### Key Features to Highlight

Create subsections showing:
- Multi-device support
- Field/Curve implementations
- Cryptographic primitives
- Memory management
- Backend selection/configuration

##### Implementation Details

Technical details in notes:
- Supported curves (BLS12-381, BN254, etc.)
- Supported fields (babybear, stark252, etc.)
- Hardware requirements
- Performance characteristics

- Clear separation between frontend (bindings) and backend (hardware)
- Extensibility points for new backends
- Performance-critical paths
- Memory management and resource allocation flows
- Where configuration and runtime selection occurs

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef hardware fill:#2ecc71,stroke:#27ae60,color:white
    classDef binding fill:#e67e22,stroke:#d35400,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
    
    %% Language Bindings Layer
    subgraph Bindings
        RustBindings["Rust Bindings"]:::binding
        GoBindings["Go Bindings"]:::binding
        CppBindings["C++ Interface"]:::binding
    end

    %% Core Layer
    subgraph Core
        Primitives["Cryptographic Primitives"]:::core
        Fields["Field Operations"]:::core
        Curves["Curve Operations"]:::core
        Hash["Hash Functions"]:::core
        Runtime["Runtime Management"]:::core
        Device["Device Management"]:::core
    end

    %% Infrastructure Layer
    subgraph Infrastructure
        MemoryMgmt["Memory Management"]:::infra
        ErrorHandling["Error Handling"]:::infra
        DeviceAPI["Device API"]:::infra
        PolyOps["Polynomial Operations"]:::infra
        VecOps["Vector Operations"]:::infra
    end

    %% Hardware Backend Layer
    subgraph Backends
        CPU["CPU Backend"]:::hardware
        CUDA["CUDA Backend"]:::hardware
        Metal["Metal Backend"]:::hardware
    end

    %% Relationships
    RustBindings & GoBindings & CppBindings --> Primitives & Fields & Curves & Hash
    Primitives & Fields & Curves & Hash --> Runtime
    Runtime --> Device
    Device --> DeviceAPI
    DeviceAPI --> CPU & CUDA & Metal
    Device --> MemoryMgmt
    Runtime --> ErrorHandling
    Fields --> PolyOps
    Fields --> VecOps

    %% Click Events
    click RustBindings "https://github.com/ingonyama-zk/icicle/tree/main/wrappers/rust"
    click GoBindings "https://github.com/ingonyama-zk/icicle/tree/main/wrappers/golang"
    click CppBindings "https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle"
    click Primitives "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/ntt.h"
    click Fields "https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/fields"
    click Curves "https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/curves"
    click Hash "https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/hash"
    click Runtime "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/runtime.h"
    click Device "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/device.h"
    click CPU "https://github.com/ingonyama-zk/icicle/tree/main/icicle/backend/cpu"
    click MemoryMgmt "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/memory_tracker.h"
    click ErrorHandling "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/errors.h"
    click DeviceAPI "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/device_api.h"
    click PolyOps "https://github.com/ingonyama-zk/icicle/tree/main/icicle/include/icicle/polynomials"
    click VecOps "https://github.com/ingonyama-zk/icicle/blob/main/icicle/include/icicle/vec_ops.h"
```
