mleku
e0a95ca1cd
- Replaced all instances of p256k1signer with the new p8k.Signer across various modules, including event creation, policy handling, and database interactions. - Updated related test cases and benchmarks to ensure compatibility with the new signer interface. - Bumped version to v0.25.0 to reflect these significant changes and improvements in cryptographic operations.
291 lines
8.0 KiB
Markdown
291 lines
8.0 KiB
Markdown
# p8k.mleku.dev - Project Summary
|
|
|
|
## Overview
|
|
|
|
A complete Go package providing bindings to libsecp256k1 **without CGO**. Uses dynamic library loading via [purego](https://github.com/ebitengine/purego) to call C functions directly.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
p8k.mleku.dev/
|
|
├── libsecp256k1.so # Bundled library for Linux AMD64 (1.8 MB)
|
|
├── secp.go # Core library with context management and ECDSA
|
|
├── schnorr.go # Schnorr signature (BIP-340) module
|
|
├── ecdh.go # ECDH key exchange module
|
|
├── recovery.go # Public key recovery module
|
|
├── utils.go # High-level convenience functions
|
|
├── secp_test.go # Comprehensive test suite
|
|
├── examples/
|
|
│ ├── ecdsa/ # ECDSA example
|
|
│ ├── schnorr/ # Schnorr signature example
|
|
│ ├── ecdh/ # ECDH key exchange example
|
|
│ └── recovery/ # Public key recovery example
|
|
├── bench/ # Comparative benchmark suite
|
|
│ ├── bench_test.go # Benchmarks vs BTCEC and P256K1
|
|
│ ├── Makefile # Convenient benchmark targets
|
|
│ ├── README.md # Benchmark documentation
|
|
│ └── run_benchmarks.sh # Automated benchmark runner
|
|
├── go.mod # Module definition
|
|
├── go.sum # Dependency checksums
|
|
├── Makefile # Build automation
|
|
├── README.md # Main documentation
|
|
├── QUICKSTART.md # Quick reference guide
|
|
├── API.md # Complete API documentation
|
|
├── LIBRARY.md # Bundled library documentation
|
|
└── LICENSE # MIT License
|
|
```
|
|
|
|
## Features Implemented
|
|
|
|
### Core Functionality (secp.go)
|
|
✓ Dynamic library loading for Linux, macOS, Windows
|
|
✓ Context creation and management with automatic cleanup
|
|
✓ Context randomization
|
|
✓ Public key generation from private keys
|
|
✓ Public key serialization (compressed/uncompressed)
|
|
✓ Public key parsing
|
|
✓ ECDSA signature creation
|
|
✓ ECDSA signature verification
|
|
✓ DER signature encoding/decoding
|
|
✓ Compact signature encoding/decoding
|
|
✓ Signature normalization
|
|
|
|
### Schnorr Module (schnorr.go)
|
|
✓ Keypair creation for Schnorr
|
|
✓ X-only public key extraction
|
|
✓ Schnorr signature creation (BIP-340)
|
|
✓ Schnorr signature verification (BIP-340)
|
|
✓ X-only public key parsing/serialization
|
|
✓ Conversion from regular to x-only public keys
|
|
|
|
### ECDH Module (ecdh.go)
|
|
✓ EC Diffie-Hellman shared secret computation
|
|
|
|
### Recovery Module (recovery.go)
|
|
✓ Recoverable signature creation
|
|
✓ Recoverable signature serialization
|
|
✓ Recoverable signature parsing
|
|
✓ Public key recovery from signatures
|
|
|
|
### Utility Functions (utils.go)
|
|
✓ Private key generation
|
|
✓ One-line key generation helpers
|
|
✓ One-line signing helpers
|
|
✓ One-line verification helpers
|
|
✓ Key validation functions
|
|
✓ All operations with automatic context management
|
|
|
|
### Testing (secp_test.go)
|
|
✓ Context creation tests
|
|
✓ Public key generation tests
|
|
✓ Serialization tests
|
|
✓ ECDSA signing and verification tests
|
|
✓ DER encoding tests
|
|
✓ Compact encoding tests
|
|
✓ Signature normalization tests
|
|
✓ Schnorr signature tests
|
|
✓ ECDH tests
|
|
✓ Recovery tests
|
|
✓ Performance benchmarks
|
|
|
|
### Examples
|
|
✓ Complete ECDSA example
|
|
✓ Complete Schnorr signature example
|
|
✓ Complete ECDH example
|
|
✓ Complete recovery example
|
|
|
|
### Documentation
|
|
✓ Comprehensive README with installation and usage
|
|
✓ Quick reference guide (QUICKSTART.md)
|
|
✓ Complete API documentation (API.md)
|
|
✓ Inline code documentation
|
|
✓ Example programs
|
|
|
|
### Build System
|
|
✓ Makefile with targets for test, build, examples, etc.
|
|
✓ Automated library installation helper
|
|
✓ Example building and running
|
|
|
|
## Technical Details
|
|
|
|
### No CGO Required
|
|
- Uses `purego` library for dynamic loading
|
|
- Opens libsecp256k1.so/.dylib/.dll at runtime
|
|
- Registers C function symbols dynamically
|
|
- Zero C compiler dependency
|
|
|
|
### Library Loading
|
|
- Automatic platform detection (Linux/macOS/Windows)
|
|
- Tries multiple common library paths
|
|
- Clear error messages on failure
|
|
- Optional module detection (graceful degradation)
|
|
|
|
### Memory Management
|
|
- Automatic context cleanup via finalizers
|
|
- Safe byte slice handling
|
|
- No memory leaks
|
|
- Proper resource cleanup
|
|
|
|
### API Design
|
|
- Two-tier API: Low-level (context-based) and high-level (utility functions)
|
|
- Named return values throughout
|
|
- Comprehensive error handling
|
|
- Clear error messages
|
|
- Type safety
|
|
|
|
### Performance
|
|
- Direct C function calls via purego
|
|
- Minimal overhead compared to CGO
|
|
- Benchmarks included
|
|
- Context reuse for batch operations
|
|
|
|
## Constants Defined
|
|
|
|
```go
|
|
// Context flags
|
|
ContextNone, ContextVerify, ContextSign, ContextDeclassify
|
|
|
|
// EC flags
|
|
ECCompressed, ECUncompressed
|
|
|
|
// Sizes
|
|
PublicKeySize = 64
|
|
CompressedPublicKeySize = 33
|
|
UncompressedPublicKeySize = 65
|
|
SignatureSize = 64
|
|
CompactSignatureSize = 64
|
|
PrivateKeySize = 32
|
|
SharedSecretSize = 32
|
|
SchnorrSignatureSize = 64
|
|
RecoverableSignatureSize = 65
|
|
```
|
|
|
|
## All C Functions Bound
|
|
|
|
### Core Functions
|
|
- secp256k1_context_create
|
|
- secp256k1_context_destroy
|
|
- secp256k1_context_randomize
|
|
- secp256k1_ec_pubkey_create
|
|
- secp256k1_ec_pubkey_serialize
|
|
- secp256k1_ec_pubkey_parse
|
|
- secp256k1_ecdsa_sign
|
|
- secp256k1_ecdsa_verify
|
|
- secp256k1_ecdsa_signature_serialize_der
|
|
- secp256k1_ecdsa_signature_parse_der
|
|
- secp256k1_ecdsa_signature_serialize_compact
|
|
- secp256k1_ecdsa_signature_parse_compact
|
|
- secp256k1_ecdsa_signature_normalize
|
|
|
|
### Schnorr Module
|
|
- secp256k1_schnorrsig_sign32
|
|
- secp256k1_schnorrsig_verify
|
|
- secp256k1_keypair_create
|
|
- secp256k1_xonly_pubkey_parse
|
|
- secp256k1_xonly_pubkey_serialize
|
|
- secp256k1_keypair_xonly_pub
|
|
- secp256k1_xonly_pubkey_from_pubkey
|
|
|
|
### ECDH Module
|
|
- secp256k1_ecdh
|
|
|
|
### Recovery Module
|
|
- secp256k1_ecdsa_recoverable_signature_serialize_compact
|
|
- secp256k1_ecdsa_recoverable_signature_parse_compact
|
|
- secp256k1_ecdsa_sign_recoverable
|
|
- secp256k1_ecdsa_recover
|
|
|
|
## Usage
|
|
|
|
### Basic Example
|
|
|
|
```go
|
|
import "next.orly.dev/pkg/crypto/p8k"
|
|
|
|
// Generate keys
|
|
privKey, _ := secp.GeneratePrivateKey()
|
|
pubKey, _ := secp.PublicKeyFromPrivate(privKey, true)
|
|
|
|
// Sign message
|
|
msgHash := sha256.Sum256([]byte("Hello"))
|
|
sig, _ := secp.SignMessage(msgHash[:], privKey)
|
|
|
|
// Verify signature
|
|
valid, _ := secp.VerifyMessage(msgHash[:], sig, pubKey)
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Run benchmarks
|
|
make bench
|
|
|
|
# Build and run examples
|
|
make run-examples
|
|
|
|
# Build everything
|
|
make build
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Go 1.25.3 or later
|
|
- libsecp256k1 installed on system
|
|
- Linux, macOS, or Windows
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Install the package
|
|
go get p8k.mleku.dev
|
|
|
|
# Install libsecp256k1
|
|
make install-secp256k1 # Or use your package manager
|
|
```
|
|
|
|
## Benefits Over CGO
|
|
|
|
1. **No C Compiler**: No need for GCC/Clang during builds
|
|
2. **Faster Builds**: No C compilation step
|
|
3. **Cross-Compilation**: Easier to cross-compile
|
|
4. **Pure Go**: Better integration with Go tooling
|
|
5. **Runtime Linking**: Can use system-installed libraries
|
|
6. **Bundled Library**: Linux AMD64 includes pre-built library (zero installation!)
|
|
|
|
## System Requirements
|
|
|
|
**Linux AMD64**: ✅ Bundled library included (libsecp256k1.so v5.0.0, 1.8 MB) - works out of the box!
|
|
|
|
**Other Platforms**:
|
|
- Go 1.25.3 or later
|
|
- libsecp256k1 installed on system
|
|
- macOS, Windows, or other Linux architectures
|
|
|
|
## Thread Safety
|
|
|
|
Context objects are NOT thread-safe. Each goroutine should have its own context. Utility functions are safe to use concurrently.
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Credits
|
|
|
|
Bindings to [libsecp256k1](https://github.com/bitcoin-core/secp256k1) by Bitcoin Core developers.
|
|
|
|
## Status
|
|
|
|
✅ All core functionality implemented
|
|
✅ All modules implemented (Schnorr, ECDH, Recovery)
|
|
✅ Comprehensive tests written
|
|
✅ Examples provided
|
|
✅ Comprehensive benchmark suite (vs BTCEC & P256K1)
|
|
✅ Documentation complete
|
|
✅ Bundled library for Linux AMD64 (zero installation!)
|
|
✅ Compiles without errors
|
|
✅ Ready for production use
|
|
|