# cypherock/cychain-poc architecture

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

- Interactive diagram: https://gitdiagram.com/cypherock/cychain-poc
- Repository: https://github.com/cypherock/cychain-poc

## Overview

##### Project Type and Purpose
- This project is a cryptographic proof-of-concept focused on decentralized access control using a threshold signature scheme built atop homomorphic encryption over class groups. It leverages components from the BICYCL library (located in include/bicycl) and uses C++ with CMake for building.

##### Analyzing the File Structure
- At the top level there are build system files (CMakeLists.txt), source directories (src) with core application logic like CryptoUtils, PolicyContract, ThreadPool, and a dedicated section for signature generation (cychain_sig_gen).
- The include directory is extensive. It houses the BICYCL library source code and tests, examples, documentation and benchmarks. This suggests a modular separation where the low-level cryptographic operations (like encryption, decryption, key share operations) reside in BICYCL, while the higher-level protocol coordination is managed in the src/ (and possibly through examples in include/bicycl/examples).
- Tests and benchmarks further indicate the emphasis on verifying cryptographic primitives and the distributed protocol steps.

a. Main Components:
- Cryptographic Engine:
· BICYCL library which implements various schemes such as CL-HSMqk, CL-HSM2k, and supports operations for key generation, encryption, homomorphic addition, scalar multiplication, partial decryption, and aggregation.
· Helper modules for handling GMP and OpenSSL integrations.
- Distributed Key Generation (DKG) Module:
· This component includes the two rounds described in the README for distributing key shares among participants. Its sub-components should capture:
- Round 1: Generation and sharing of random secrets, Pederson commitments, encryption of shares (including chunking operations).
- Round 2: Decryption of encrypted shares, combination of shares into one overall public encryption key.
- Signature Generation Module:
· Three rounds (as detailed in the README) represented sequentially:
◦ Round 1: Generation of ephemeral keys (K_i), computation of ECC point multiplication.
◦ Round 2: Homomorphic computations where members provide their random scalars (p_i), combine encrypted values, and perform homomorphic scalar multiplications.
◦ Round 3: Partial decryption by both user group members and validators and final aggregation to derive the ECDSA signature components (r and s).
- User Group and Validator Network:
· User Group Setup: The component where a policy is defined, users combine their individual ECDSA signing key shares through encryption and homomorphic addition.
· Validator Network: A set of distributed nodes that also participate in both the DKG and signature generation process by providing partial decryptions and verifications.
- Policy Contract:
· A (potentially smart contract–based) component enforcing access control where the policy is checked before proceeding with signature generation.
- Application / Orchestration Layer:
· Represented by components in the src/ directory that initiate and coordinate cryptographic operations (e.g., CryptoUtils, PolicyContract, ThreadPool for parallel verification, and the main executable “cychain_sig_gen”).

b. Relationships and Interactions:
· Users send their individual contributions (e.g., a_i.G, encrypted a_i, proofs) into the key aggregation process.
· For signature generation, illustrate the multi-round interaction:
- In Round 1, show how each node computes and broadcasts its ephemeral key and encrypted nonce.
- In Round 2, show the inputs (enc(p_i), enc(p_i*k), enc(p_i*X)) being homomorphically added and combined.
- In Round 3, highlight the partial decryption process and the aggregation step resulting in signature s.

c. Architectural Patterns and Technologies:
- Use of modular and layered architecture:
· Lower Layer: Cryptographic primitives and library (BICYCL, GMP, OpenSSL).
· Middle Layer: Protocol rounds encapsulating DKG and signature generation (with zero-knowledge proofs verification, secret sharing, and chunking code).
· Top Layer: Application orchestration (PolicyContract validations, thread pooling, user input/output).

- That you include detailed labels such as “KeyGen”, “Encrypt”, “Homomorphic Addition”, “Scalar Multiplication”, “Partial Decryption”, and aggregation steps where appropriate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Lower Layer - Cryptographic Primitives
    subgraph "Lower Layer - Cryptographic Primitives"
        CE["Cryptographic Engine (BICYCL)"]:::blue
    end

    %% Middle Layer - Protocol Modules
    subgraph "Middle Layer - Protocol Modules"
        subgraph "Distributed Key Generation (DKG) Module"
            DKG1["Round 1: Share Generation, Pedersen Commitments, Encryption/Chunking"]:::green
            DKG2["Round 2: Decryption of Shares & Public Key Aggregation"]:::green
            DKG1 -->|"proceeds_to"| DKG2
        end

        subgraph "Signature Generation Module"
            SG1["Round 1: Ephemeral Key Generation & ECC Computation"]:::green
            SG2["Round 2: Homomorphic Operations & Encrypted Aggregation"]:::green
            SG3["Round 3: Partial Decryption & Signature Finalization (r,s)"]:::green
            SG1 -->|"proceeds_to"| SG2
            SG2 -->|"proceeds_to"| SG3
        end
    end

    %% Top Layer - Application and Network
    subgraph "Top Layer - Application & Network"
        AO["Application / Orchestration Layer"]:::orange
        PC["Policy Contract"]:::orange
        UG["User Group"]:::orange
        VN["Validator Network"]:::orange
    end

    %% Data and Control Flow
    AO -->|"initiates"| DKG1
    AO -->|"initiates"| SG1
    UG -->|"input_to"| DKG1
    UG -->|"participates_in"| SG1
    VN -->|"contributes_to"| DKG1
    VN -->|"contributes_to"| SG1
    PC -->|"validates"| AO

    %% Connection to Cryptographic Engine
    DKG1 -->|"encrypt/share_ops"| CE
    DKG2 -->|"utilizes"| CE
    SG2 -->|"homomorphic_ops"| CE
    SG3 -->|"utilizes"| CE

    %% Final signature output delivered back to Application Layer
    SG3 -->|"delivers_signature"| AO

    %% Legend Note
    note1["Blue: Cryptographic Functions | Green: Distributed Protocols | Orange: Application/Network"]:::noteStyle
    AO --- note1

    %% Click Events
    click CE "https://github.com/cypherock/cychain-poc/tree/master/include/bicycl"
    click CE "https://github.com/cypherock/cychain-poc/tree/master/include/bicycl/src/bicycl/"
    click DKG1 "https://github.com/cypherock/cychain-poc/blob/master/include/bicycl/src/bicycl/threshold_ECDSA.hpp"
    click DKG1 "https://github.com/cypherock/cychain-poc/blob/master/include/bicycl/src/bicycl/threshold_ECDSA.inl"
    click SG1 "https://github.com/cypherock/cychain-poc/blob/master/src/cychain_sig_gen.cpp"
    click PC "https://github.com/cypherock/cychain-poc/blob/master/src/PolicyContract.cpp"
    click PC "https://github.com/cypherock/cychain-poc/blob/master/src/PolicyContract.h"
    click AO "https://github.com/cypherock/cychain-poc/blob/master/src/CryptoUtils.cpp"
    click AO "https://github.com/cypherock/cychain-poc/blob/master/src/ThreadPool.cpp"

    %% Styles
    classDef blue fill:#aee,stroke:#333,stroke-width:2px;
    classDef green fill:#afa,stroke:#333,stroke-width:2px;
    classDef orange fill:#fda,stroke:#333,stroke-width:2px;
    classDef noteStyle fill:#eee,stroke:#333,stroke-width:1px,font-style:italic;
```
