# coinbase/cb-mpc architecture

> Architecture diagram of the GitHub repository coinbase/cb-mpc, 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/coinbase/cb-mpc
- Repository: https://github.com/coinbase/cb-mpc

## Overview

##### Project Type and Purpose
- This is a cryptographic library designed to support Multi-Party Computation (MPC) protocols and secure threshold signing for managing cryptoasset keys.
- The project provides both a core C++ library (with extensive crypto primitives, protocol implementations, and zero-knowledge proofs) as well as wrappers/demos (including a Go wrapper) for integration.
- Its purpose is general-purpose cryptographic functionality with a high degree of security by default along with detailed specifications, theoretical documentation, and secure usage guidelines.

##### Main Components
a. Core Library (src):
- Submodule “cbmpc” houses the main C++ implementations. Inside, you have logically separated layers:
- Core (e.g., buf, error, logging, utilities)
- Crypto primitives (in src/cbmpc/crypto) with implementations for hashing, RSA, ECC (including secp256k1 adaptations), paillier, and TDH2.
- Protocols (in src/cbmpc/protocol) such as EC-DKG, ECDSA-2PC, ECDSA-MPC, OT, PVE, and the HD-MPC derivation. These are the higher-level protocol applications of the lower-level crypto operations.
- Zero-Knowledge Proofs (in src/cbmpc/zk) to facilitate secure proofs.
b. Go Wrapper (cb-mpc-go):
- Provides Go language bindings for the C++ core library so that prototypical applications (e.g., demos) can leverage the MPC functionality.
- Shows cross-language usage and how the library is exposed to non-C++ projects.
c. Demos:
- Located in demos/demos-cpp and demos/demos-go (also demos/mocknet for networking examples).
- These examples showcase real-world use cases of the cryptographic protocols, such as HD-MPC and threshold signing.
d. Tests and Benchmarks:
- Under tests (unit, integration, and dudect) you have comprehensive testing for constant-time guarantees, correctness, and performance.
- Tools like tools/benchmark provide performance measurements.
e. External Dependencies and Vendors:
- Dependencies on OpenSSL (with custom modifications for RSA OAEP) and a modified version of Bitcoin’s secp256k1.
- Other vendor-level dependencies (like GoogleBenchmark and googletest) are used to support building, testing, and benchmarking.

##### Architectural Relationships and Data Flow
- On the lowest level, the cryptographic primitives (contained in the “crypto” folder) supply core functionalities such as basic math, hash, and modular arithmetic.
- These primitives are invoked by the protocol layer to implement higher-level operations such as ECDSA signing, DKG, and threshold encryption.
- The core library is designed to be modular. For instance, any changes in the crypto primitives flow upward to affect protocol behavior; tests (unit and dudect) verify each layer.
- The Go wrapper (cb-mpc-go) interacts with the C++ core to expose its capabilities to Go applications.
- Demos illustrate how the API components are integrated and interact with networking components and backup/recovery protocols.
- External dependencies (like OpenSSL and secp256k1) form an infrastructure layer, which the core library calls into for low-level cryptographic operations.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Each directory (crypto, protocol, zk, core) represents dedicated modules.
- Secure by Default: Emphasis on constant-time operations, strict build modes (Dev, Test, Release), and clear documentation on secure usage.
- Modularity & Extensibility: Wrappers (Go) and demos are separated from core cryptographic implementations, making extension and integration straightforward.
- Clear dependency management: External components (vendors) are isolated, ensuring the cryptographic library can be built reliably.
- Use of build and testing infrastructure (CMakeLists.txt, Makefiles, Dockerfile, GitHub workflows) indicates an emphasis on CI/CD, code security, and best practices.

##### Elements
- Clear labels for each component/block (e.g., “Crypto Primitives”, “Protocol Layer”, “Go Wrapper”, “Demos”, “Testing & Benchmarking”).
- Annotations to indicate build infrastructure (Makefile, Dockerfile, CI workflows) and external doc dependencies (docs, theories, specifications).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        Secp256k1["secp256k1"]:::external
        GoogleBenchmark["Google Benchmark"]:::external
        Googletest["Google Test"]:::external
    end

    %% Core Library (cbmpc)
    subgraph "Core Library (cbmpc)"
        Core["Core"]:::core
        Crypto["Crypto Primitives"]:::core
        Protocol["Protocol Implementations"]:::core
        ZK["Zero-Knowledge Proofs"]:::core
        Core -->|"supports"| Crypto
        Crypto -->|"enables"| Protocol
        Protocol -->|"extends to"| ZK
    end

    %% Integration Layer
    subgraph "Integration"
        GoWrapper["Go Wrapper"]:::integration
        subgraph "Demos"
            DemosCpp["Demos C++"]:::integration
            DemosGo["Demos Go"]:::integration
            Mocknet["Mocknet"]:::integration
            DemosCpp -->|"flows_to"| DemosGo
            DemosGo -->|"includes"| Mocknet
        end
        subgraph "Tests & Benchmarks"
            Tests["Tests"]:::testing
            Benchmark["Benchmarks"]:::testing
            Tests -->|"coupled_with"| Benchmark
        end
    end

    %% Relationships between Core Library and Integration Components
    Protocol -->|"binding"| GoWrapper
    Protocol -->|"demo"| DemosCpp
    Protocol -->|"tested_by"| Tests

    %% External Dependencies affecting Core Layers
    Secp256k1 -->|"crypto"| Crypto
    Secp256k1 -->|"proto"| Protocol
    GoogleBenchmark -->|"benchmark"| Benchmark
    Googletest -->|"unittest"| Tests

    %% Click Events
    click Core "https://github.com/coinbase/cb-mpc/tree/master/src/cbmpc"
    click GoWrapper "https://github.com/coinbase/cb-mpc/tree/master/cb-mpc-go"
    click DemosCpp "https://github.com/coinbase/cb-mpc/tree/master/demos/demos-cpp"
    click DemosGo "https://github.com/coinbase/cb-mpc/tree/master/demos/demos-go"
    click Mocknet "https://github.com/coinbase/cb-mpc/tree/master/demos/mocknet"
    click Tests "https://github.com/coinbase/cb-mpc/tree/master/tests"
    click Benchmark "https://github.com/coinbase/cb-mpc/tree/master/tools/benchmark"
    click Secp256k1 "https://github.com/coinbase/cb-mpc/tree/master/vendors/secp256k1"
    click GoogleBenchmark "https://github.com/coinbase/cb-mpc/tree/master/vendors/google-benchmark"
    click Googletest "https://github.com/coinbase/cb-mpc/tree/master/vendors/googletest"

    %% Styles
    classDef core fill:#a7e7a7,stroke:#000,stroke-width:2px,color:#000;
    classDef integration fill:#a2d2ff,stroke:#000,stroke-width:2px,color:#000;
    classDef testing fill:#ffb347,stroke:#000,stroke-width:2px,color:#000;
    classDef external fill:#ffcccc,stroke:#000,stroke-width:2px,color:#000;
    
    class Core,Crypto,Protocol,ZK core;
    class GoWrapper,DemosCpp,DemosGo,Mocknet integration;
    class Tests,Benchmark testing;
    class Secp256k1,GoogleBenchmark,Googletest external;
```
