How coinbase/cb-mpc works
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).