Refactor signer implementation to use p8k package
- 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.
This commit is contained in:
290
pkg/crypto/p8k/SUMMARY.md
Normal file
290
pkg/crypto/p8k/SUMMARY.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user