Skip to content

CLAUDE.md

Latest commit

 

History

History
94 lines (61 loc) · 3.33 KB

CLAUDE.md

File metadata and controls

94 lines (61 loc) · 3.33 KB
Raw

CLAUDE.md

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

Build & Test Commands

# Regenerate all code from templates (required after editing .tmpl files)
go generate ./...

# Run tests (use -short to skip slow tests - recommended during development)
go test -short ./...

# Test specific curve
go test -short ./ecc/bn254/...

# Benchmarks
go test -short -benchmem -count=4 -bench=<BenchmarkName> ./ecc/bn254/...

Architecture Overview

This is a heavily code-generated cryptography library. ~90% of code under ecc/ and field/ is generated from Go templates in internal/generator/.

Key Directories

  • internal/generator/ - Template engine and all .tmpl templates (entry: main.go)
  • ecc/<curve>/ - Generated curve implementations (bn254, bls12-381, bls12-377, bls24-315, bls24-317, bw6-761, bw6-633, grumpkin, secp256k1, secp256r1, stark-curve)
  • field/ - Standalone field implementations (babybear, goldilocks, koalabear)
  • field/asm/ - Shared assembly code for field arithmetic (amd64/arm64)

Generated vs Non-Generated Files

Before editing any file, check if it starts with // Code generated by consensys/gnark-crypto DO NOT EDIT.

  • Generated files → Edit the .tmpl template in internal/generator/ instead
  • Non-generated files → Edit directly

Template location pattern: ecc/bn254/g1.go → internal/generator/ecc/template/point.go.tmpl

Workflow for Changes

  1. Check file header for "DO NOT EDIT"
  2. If generated, modify .tmpl file in internal/generator/<component>/template/
  3. Regenerate: go generate ./...
  4. Test: go test -short ./...

Code Patterns

// Field elements are fixed-size arrays (Montgomery representation)
type Element [4]uint64  // bn254/fr - 4 limbs for 254-bit field

// Jacobian coordinates for efficient EC operations
type G1Jac struct { X, Y, Z fp.Element }

// Affine for storage/serialization
type G1Affine struct { X, Y fp.Element }

Performance Guidelines

  • Performance is critical: Avoid allocations in hot paths, use pointer receivers
  • Assembly is used for critical field operations - check element_amd64.go / element_arm64.go for Go declarations
  • Tests use gopter for property-based testing

Assembly Generation

Two Types of Generated Assembly

  1. Template-based assembly (.tmpl files): Generated via bavard templates will contain the code generation to define the function in a .go file that pairs with the .s file and other useful constants
  2. Programmatic assembly (Go code that emits .s files): Located in internal/generator/field/asm/

F31 Fields (koalabear, babybear)

These 31-bit prime fields have specialized SIMD implementations:

  • internal/generator/field/asm/amd64/ - AVX512 assembly generators
  • internal/generator/field/asm/arm64/ - NEON assembly generators

Key files for Poseidon2 ARM64:

  • Generator: internal/generator/field/asm/arm64/element_vec_F31_poseidon2.go
  • Output: field/koalabear/poseidon2/poseidon2_arm64.s

Regenerating Assembly

# Regenerate everything (required for assembly changes)
go generate ./internal/generator/...

# This is different from `go generate ./field/...` which only runs bavard templates
# Assembly generators in internal/generator/field/asm/ require the former