How bitcoin-core/secp256k1 works
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/)