# bitcoin-core/secp256k1 architecture

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

- Interactive diagram: https://gitdiagram.com/bitcoin-core/secp256k1
- Repository: https://github.com/bitcoin-core/secp256k1

## Overview

##### Project type and purpose
- This is a high-performance C library (libsecp256k1) providing elliptic-curve cryptography on secp256k1.
- It is not a client/server or full-stack app but an embeddable crypto primitive library, with optional modules (ECDH, Schnorr, MuSig, ElligatorSwift, key recovery).

##### File structure
- Top-level:
- configure/autotools files (`configure.ac`, `Makefile.am`, `autogen.sh`, `build-aux/…`)
- CMake support (`CMakeLists.txt`, `cmake/…`, `CMakePresets.json`)
- `src/`: core implementation, subdirs: `asm`, `modules`, high-assurance C code, self-tests
- `include/`: public headers (.h) exporting the API
- `examples/`: usage examples (ECDSA, Schnorr, ECDH, ElligatorSwift)
- `tools/`: helper scripts (ABI checks, vector generation, WycheProof utilities)
- `sage/`: scripts for parameter generation and proofs
- `doc/`: design notes, release process, module docs
- `tests` split between `src/tests.c`, exhaustive tests in `src/modules/*/tests_impl.h`, and `tools/wycheproof` integration
- CI and GitHub Actions for automated builds and sanitizers

##### README for additional insights
- The README highlights:
- Core features (ECDSA signing/verification, keygen, tweaks, serialization)
- No runtime dependencies, no heap, no data-dependent branches
- Optional modules toggled at configure/CMake time
- Build workflows (Autotools, CMake, cross-compile toolchains)
- Examples and benchmarks

##### Main components and their interactions
a. Build and Configuration Layer
- Autotools/CMake → generate Makefiles/VS projects
- Feature flags enable/disable modules
- Cross-compile toolchain files in `cmake/`
b. Core Crypto Engine (`src/`)
- Field arithmetic (5×52, 10×26 limbs, assembly)
- Scalar arithmetic (4×64, 8×32 limbs)
- Modular inverse (safegcd)
- Ops (point add/double, Jacobian/affine)
- ECDSA and precompute tables
- Public API stubs in `secp256k1.c`
c. Optional Modules (`src/modules/*`)
- ECDH, Schnorrsig, ElligatorSwift, MuSig, Extrakeys, Recovery
- Each module has hooks: bench_impl, main_impl, tests_impl
- Config flags into core build
d. Public API Headers (`include/`)
- Expose only high-level functions
- Minimize API surface
e. Examples & Benchmarks (`examples/`, bench code in `src/bench*`)
- Depend on built library + enabled modules
f. Tests & Verification
- Self-tests in core (`src/tests.c`, `src/tests_exhaustive.c`)
- Module tests (`tests_impl.h`)
- Wycheproof integration under `src/wycheproof` & tools
- CI pipelines orchestrate builds, sanitizers, log printing
g. Tools & Scripts (`tools/`, `sage/`)
- Generate test vectors or parameters
- Check ABI, symbol definitions
- Sage proofs for parameters

##### Architectural patterns and design principles
- Modular plugin architecture: optional modules register hooks into core
- Layered design: build/config → core engine → modules → API → applications/tests
- Emphasis on constant-time, no-branch operations, portability (C89 + uint64_t)
- Separation of public API (include/) and implementation (src/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Configuration Layer
    subgraph "Build & Configuration" 
        direction TB
        Autotools["Autotools"]:::build
        CMake["CMake (CMakeLists.txt)"]:::build
    end

    %% Core Crypto Engine
    subgraph "Core Crypto Engine" 
        direction TB
        SECAPI["secp256k1.c"]:::core
        FieldOps["Field Ops (field.h)"]:::core
        ScalarOps["Scalar Ops (scalar.h)"]:::core
        GroupOps["Group Ops (group.h)"]:::core
        ECDSACore["ECDSA Core (ecdsa.h)"]:::core
    end

    %% Optional Modules
    subgraph "Optional Modules" 
        direction TB
        ECDH["ECDH"]:::module
        Schnorr["Schnorrsig"]:::module
        MuSig["MuSig"]:::module
        Elligator["ElligatorSwift"]:::module
        Extrakeys["Extrakeys"]:::module
        Recovery["Recovery"]:::module
    end

    %% Public API Headers
    subgraph "Public API Headers" 
        direction TB
        APIcore["secp256k1.h"]:::api
        APIecdh["secp256k1_ecdh.h"]:::api
        APIschnorr["secp256k1_schnorrsig.h"]:::api
        APImusig["secp256k1_musig.h"]:::api
        APIellswift["secp256k1_ellswift.h"]:::api
        APIextrakey["secp256k1_extrakeys.h"]:::api
        APIrecovery["secp256k1_recovery.h"]:::api
        APIprealloc["secp256k1_preallocated.h"]:::api
    end

    %% Examples & Benchmarks & Tests
    subgraph "Examples / Benchmarks / Tests" 
        direction TB
        Examples["Examples"]:::examples
        Benchmarks["Benchmarks"]:::examples
        Tests["Core & Module Tests"]:::examples
        Wycheproof["Wycheproof Integration"]:::examples
    end

    %% Tools & Scripts
    subgraph "Tools & Scripts" 
        direction TB
        Tools["Helper Scripts"]:::tools
    end

    %% Sage Proofs
    subgraph "Sage Proofs" 
        direction TB
        Sage["Parameter Generation & Proofs"]:::tools
    end

    %% Relationships
    Autotools -->|"generate build files"| SECAPI
    CMake -->|"generate build files"| SECAPI

    SECAPI --> FieldOps
    SECAPI --> ScalarOps
    SECAPI --> GroupOps
    SECAPI --> ECDSACore

    FieldOps --> ECDH
    ScalarOps --> Schnorr
    GroupOps --> MuSig
    ECDSACore --> Schnorr

    APIcore --> SECAPI
    APIecdh --> ECDH
    APIschnorr --> Schnorr
    APImusig --> MuSig
    APIellswift --> Elligator
    APIextrakey --> Extrakeys
    APIrecovery --> Recovery

    Examples --> APIcore
    Benchmarks --> APIcore
    Tests --> APIcore
    Tests --> ECDH
    Wycheproof --> Tests

    Tools --> Tests
    Tools --> Wycheproof
    Sage --> Tests

    %% Click Events
    click Autotools "https://github.com/bitcoin-core/secp256k1/blob/master/configure.ac"
    click CMake "https://github.com/bitcoin-core/secp256k1/blob/master/CMakeLists.txt"
    click SECAPI "https://github.com/bitcoin-core/secp256k1/blob/master/src/secp256k1.c"
    click FieldOps "https://github.com/bitcoin-core/secp256k1/blob/master/src/field.h"
    click ScalarOps "https://github.com/bitcoin-core/secp256k1/blob/master/src/scalar.h"
    click GroupOps "https://github.com/bitcoin-core/secp256k1/blob/master/src/group.h"
    click ECDSACore "https://github.com/bitcoin-core/secp256k1/blob/master/src/ecdsa.h"
    click ECDH "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/ecdh/main_impl.h"
    click Schnorr "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/schnorrsig/main_impl.h"
    click MuSig "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/musig/main_impl.h"
    click Elligator "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/ellswift/main_impl.h"
    click Extrakeys "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/extrakeys/main_impl.h"
    click Recovery "https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/recovery/main_impl.h"
    click APIcore "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1.h"
    click APIecdh "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_ecdh.h"
    click APIschnorr "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_schnorrsig.h"
    click APImusig "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_musig.h"
    click APIellswift "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_ellswift.h"
    click APIextrakey "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_extrakeys.h"
    click APIrecovery "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_recovery.h"
    click APIprealloc "https://github.com/bitcoin-core/secp256k1/blob/master/include/secp256k1_preallocated.h"

    %% Styles
    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#a8e6cf,stroke:#333,stroke-width:1px
    classDef module fill:#d0e1f9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef api fill:#ffd3b6,stroke:#333,stroke-width:1px
    classDef examples fill:#e2b1f9,stroke:#333,stroke-width:1px
    classDef tools fill:#f9f1a5,stroke:#333,stroke-width:1px
```
