# 21-dot-dev/swift-secp256k1 architecture

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

- Interactive diagram: https://gitdiagram.com/21-dot-dev/swift-secp256k1
- Repository: https://github.com/21-dot-dev/swift-secp256k1

## Overview

##### Project Type and Purpose
- This is a Swift package intended for cryptographic operations using secp256k1.
- Its purpose is to provide both lightweight (common use) and advanced (e.g., MuSig, BIP‑340) key cryptography operations for Bitcoin and related applications.
- It is implemented as a full Swift package that brings together high‑level Swift API components and corresponding low‑level C bindings, making it available for both Apple and Linux.

##### Analyzing the File Structure
- Top‑level files such as Package.swift, README.md, and Dockerfile indicate that this is a package meant to be integrated via Swift Package Manager (SPM) as well as run in containerized environments.
- The “Sources” directory is split into at least two key modules:
- Sources/secp256k1: Contains Swift implementations and wrappers for cryptographic operations.
- Sources/zkp: Mirrors many of the components in secp256k1 but seems focused on zero‑knowledge proof (ZKP) extensions, likely establishing a parallel API for more advanced functionalities.
- The “Sources/secp256k1_bindings” and “Sources/zkp_bindings” directories house the C binding layer. They include headers and source files that wrap the underlying C library routines.
- The “Submodules” directory brings in external repositories like the original libsecp256k1 and swift‑crypto, hinting at external dependencies that interact with the internal code.
- The “Tests” directory contains unit tests for both zkp and secp256k1 functionality, ensuring that API calls and cryptographic operations are verified.
- Additional developer tools and configuration (e.g., .github/workflows, Dockerfile, swiftlint, swiftformat) indicate CI/CD integration and code style enforcement.

a. Main Components
- API Layer:
- The Swift API defines operations for ECDSA, Schnorr, ECDH, key tweaking, PEM import/export, etc.
- Located in “Sources/secp256k1” and “Sources/zkp”.
- C Bindings Layer:
- Wraps the underlying libsecp256k1 and ZKP C libraries.
- Found in “Sources/secp256k1_bindings” and “Sources/zkp_bindings”.
- External Dependencies:
- External C libraries (from submodules like secp256k1 and secp256k1‑zkp) and Swift‑crypto.
- Test Framework/CI:
- The “Tests” directory and CI configurations (e.g., Bitrise workflows, GitHub Actions).
- Build & Deployment:
- The Package.swift manifests and Dockerfiles indicate integration and containerization paths.

b. Relationships and Interactions
- The high‑level API (Swift layer) makes calls to the lower‑level C bindings, which in turn wrap calls to the native C implementations provided by external submodules.
- Unit tests exercise the API and verify that the C binding interaction yields correct cryptographic results.
- CI/CD services (through GitHub workflows and Bitrise) automatically build, test, and potentially deploy the package.
- There is a clear data flow: client code → Swift API calls → C binding layer → underlying cryptographic C libraries → results returned upward.

c. Important Architectural Patterns and Design Principles
- Layered Architecture:
- Separation between the Swift API layer and the C bindings keeps high‑level logic distinct from lower‑level implementation details.
- Modularity and Encapsulation:
- Different cryptographic operations and functionalities (signatures, key transformation, MuSig2 operations, etc.) are isolated into distinct source files and directories.
- Reuse and Integration:
- The use of external submodules shows a strategy to leverage battle‑tested cryptographic code while still providing a flexible Swift interface.

d. Relevant Technologies/Frameworks
- Swift Package Manager (primary build and dependency tool)
- Docker (containerization)
- CI/CD tools (GitHub Workflows, Bitrise)
- Testing framework (XCTest)
- Coding style/linting tools (swiftformat, swiftlint)

##### Elements
- Components: Each main part (Swift API, C Bindings, External Libraries, CI/CD, Testing) should be represented as a clearly labeled block or node.
- Annotations: Include notes for specific interactions, such as “calls libsecp256k1 for low-level ECDSA operations” or “wraps advanced MuSig signature generation.”

##### Additional Advice
- Be very detailed: Even though a high‑level view is useful, include as many essential components and interactions as possible.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client/Consumer Layer
    A["Client/Consumer"]:::client

    %% Swift API Layer
    subgraph "Swift API Layer"
        B1["secp256k1 (Swift API)"]:::swiftapi
        B2["zkp (Swift API)"]:::swiftapi
    end

    %% C Bindings Layer
    subgraph "C Bindings Layer"
        C1["secp256k1_bindings (C Bindings)"]:::bindings
        C2["zkp_bindings (C Bindings)"]:::bindings
    end

    %% External C Libraries Layer
    subgraph "External C Libraries"
        D1["secp256k1 (External)"]:::externallib
        D2["secp256k1-zkp (External)"]:::externallib
        D3["swift-crypto (External)"]:::externallib
    end

    %% Supporting Infrastructure Layer
    subgraph "Supporting Infrastructure"
        subgraph "Testing Framework"
            E1["Tests"]:::testing
        end
        subgraph "CI/CD & Build Tools"
            F1["Package.swift"]:::cicd
            F2["Dockerfile"]:::cicd
            F3[".github/workflows"]:::cicd
        end
    end

    %% Connections between layers
    A -->|"calls"| B1
    A -->|"calls"| B2

    B1 -->|"invokes"| C1
    B2 -->|"invokes"| C2

    C1 -->|"wraps"| D1
    C1 -->|"uses"| D3
    C2 -->|"wraps"| D2
    C2 -->|"uses"| D3

    %% Testing interacts with API and C Bindings for verification
    E1 -->|"tests"| B1
    E1 -->|"tests"| B2
    E1 -->|"tests"| C1
    E1 -->|"tests"| C2

    %% CI/CD triggers tests and builds
    F1 -->|"triggers"| E1
    F2 -->|"triggers"| E1
    F3 -->|"triggers"| E1

    %% Styling classes
    classDef client fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef swiftapi fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef bindings fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef externallib fill:#ffd700,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ffdead,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click B1 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Sources/secp256k1"
    click B2 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Sources/zkp"
    click C1 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Sources/secp256k1_bindings"
    click C2 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Sources/zkp_bindings"
    click D1 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Submodules/secp256k1"
    click D2 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Submodules/secp256k1-zkp"
    click D3 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Submodules/swift-crypto"
    click E1 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Tests"
    click F1 "https://github.com/21-dot-dev/swift-secp256k1/blob/main/Package.swift"
    click F2 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/Dockerfile"
    click F3 "https://github.com/21-dot-dev/swift-secp256k1/tree/main/.github/workflows"
```
