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)
```bash
./autogen.sh           # Generate configure script
./configure            # Configure build (add --enable-module-* flags for optional modules)
make                   # Build
make check             # Run tests
```

### CMake
```bash
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
```bash
./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