Claude Code Instructions for p256k1

Project Overview

Pure Go implementation of secp256k1 elliptic curve cryptography. No cgo, no external dependencies.

Project Structure

p256k1/
├── *.go              # Core implementation (field, scalar, group, signatures)
├── *_amd64.go        # AMD64-specific optimizations
├── *_amd64.s         # AMD64 assembly
├── *_32bit.go        # 32-bit fallbacks
├── *_wasm.go         # WebAssembly support
├── *_generic.go      # Generic fallbacks
│
├── ecdsa/            # ECDSA domain package
├── schnorr/          # Schnorr/BIP-340 domain package
├── keys/             # Key management domain package
├── exchange/         # ECDH domain package
├── signer/           # High-level signer abstraction
│
├── avx/              # Experimental AVX2 optimizations
├── wnaf/             # wNAF encoding utilities
├── bench/            # Benchmarking tools
├── testdata/         # Test vectors
└── docs/             # Technical documentation

Key Files

• field.go, field_mul.go, field_4x64.go - Field arithmetic (F_p)
• scalar.go - Scalar arithmetic (mod group order)
• group.go, group_4x64.go - Point operations
• ecdsa.go - ECDSA implementation
• schnorr.go, schnorr_batch.go - Schnorr signatures
• ecdh.go - ECDH key exchange
• hash.go - SHA-256, HMAC, RFC6979
• verify.go - Combined verification with Strauss algorithm
• ecmult_gen.go - Generator multiplication with precomputed tables

Build Tags

• Default: Uses optimized AMD64 code when available
• //go:build !amd64 - 32-bit/generic fallback
• //go:build wasm - WebAssembly build

Testing

go test ./...                    # Run all tests
go test -bench=. .               # Run benchmarks
go test -run TestSchnorr .       # Run specific tests

Performance Considerations

• Hot paths avoid heap allocations
• Field elements use 5x52-bit limbs for efficient multiplication
• Scalars use 4x64-bit limbs
• GLV endomorphism splits 256-bit multiplications into 2x128-bit
• Strauss algorithm shares doublings across multiple multiplications
• Precomputed tables for generator point

Domain Packages

The domain packages (ecdsa/, schnorr/, keys/, exchange/) are thin wrappers around the core p256k1 package. They:

• Re-export core types via type aliases
• Provide cleaner, more focused APIs
• Add domain-specific documentation
• Don't contain implementation logic (just delegation)

Conventions

• Use existing patterns when adding new functionality
• Keep hot paths allocation-free
• Add *Raw variants for functions that can write to caller-provided buffers
• Assembly files use Go's plan9 assembly syntax
• Test files follow *_test.go naming