libsecp256k1/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

libsecp256k1 is a high-performance C library for cryptographic operations on the secp256k1 elliptic curve, primarily developed for Bitcoin. It provides ECDSA signing/verification, Schnorr signatures (BIP-340), ECDH, ElligatorSwift (BIP-324), and MuSig2 (BIP-327).

Build Commands

Autotools (primary)

./autogen.sh           # Generate configure script
./configure            # Configure build (add --enable-module-* flags for optional modules)
make                   # Build
make check             # Run tests

CMake

cmake -B build                # Configure
cmake --build build           # Build
ctest --test-dir build        # Run tests

Common configure flags

• --enable-module-recovery - ECDSA pubkey recovery (off by default)
• --enable-module-schnorrsig - Schnorr signatures
• --enable-module-musig - MuSig2 multi-signatures
• --enable-module-ellswift - ElligatorSwift
• --enable-module-ecdh - ECDH key exchange
• --enable-examples - Build example programs
• --enable-coverage - Enable coverage analysis (requires GCC)

Test coverage

./configure --enable-coverage
make check
gcovr --exclude 'src/bench*' --exclude 'src/modules/.*/bench_impl.h' --print-summary

Architecture

Core structure

• src/secp256k1.c - Main library implementation, includes all other source files
• include/secp256k1.h - Primary public API header with argument ordering rules
• include/secp256k1_*.h - Module-specific public headers

Implementation pattern

The library uses a header-only internal architecture:

• src/*.h - Internal declarations
• src/*_impl.h - Corresponding implementations (included by secp256k1.c)

Key components

• Field operations: field_5x52*.h (64-bit) or field_10x26*.h (32-bit) - arithmetic mod p
• Scalar operations: scalar_4x64*.h (64-bit) or scalar_8x32*.h (32-bit) - arithmetic mod n
• Group operations: group*.h - elliptic curve point operations
• Modular inverse: modinv64*.h / modinv32*.h - safegcd-based inversion
• ecmult: ecmult*.h - point multiplication (signing and verification)

Optional modules (src/modules/)

• ecdh/ - Elliptic curve Diffie-Hellman
• recovery/ - ECDSA public key recovery
• extrakeys/ - x-only pubkeys (required by schnorrsig)
• schnorrsig/ - BIP-340 Schnorr signatures (requires extrakeys)
• musig/ - BIP-327 MuSig2 (requires schnorrsig)
• ellswift/ - BIP-324 ElligatorSwift encoding

Code Conventions

• Language: C89 with /* */ comments only (no //)
• Declarations: Must appear at beginning of blocks before statements
• Memory: No runtime heap allocation unless explicitly requested by caller
• Identifiers: File-scope identifiers must start with secp256k1_
• Pointers: Use void *ptr not void* ptr; use unsigned int not unsigned
• Comparison: Use secp256k1_memcmp_var instead of memcmp
• Secret data: Must be constant-time, cleared after use, tested with ctime_tests

Testing

• src/tests.c - Main test suite
• src/tests_exhaustive.c - Exhaustive tests on small groups
• src/ctime_tests.c - Constant-time verification (requires valgrind)
• src/unit_test.c - Unit tests

API Design

Arguments follow a specific order (from include/secp256k1.h):

1. Context pointers first
2. Output arguments
3. Combined output/input arguments
4. Input-only arguments
5. Array lengths immediately follow their arrays