crypto/MIGRATION.md

Sonr Cryptography Library Migration Context

Repository Migration: sonr-io/sonr/crypto/ → sonr-io/crypto Package Name: github.com/sonr-io/crypto Current Version: v1.0.1

Overview

The Sonr Cryptography Library is a comprehensive collection of cryptographic primitives designed for secure decentralized applications. It provides enterprise-grade implementations of elliptic curve cryptography, multi-party computation, threshold cryptography, zero-knowledge proofs, and advanced signature schemes.

Key Features:

• Multi-Party Computation (MPC): Secure distributed key generation and signing
• Threshold Cryptography: TECDSA and TED25519 with FROST protocol
• Advanced Signatures: BLS aggregation, BBS+ selective disclosure, Schnorr variants
• Secret Sharing: Shamir, Feldman VSS, Pedersen VSS implementations
• Zero-Knowledge Proofs: Bulletproofs for range proofs
• Multiple Elliptic Curves: Ed25519, Secp256k1, P-256, BLS12-381, Pallas/Vesta
• UCAN Integration: Capability-based authorization tokens
• DID Key Management: Multi-chain wallet address derivation

Repository Structure

sonr-io/crypto/
├── core/                    # Core cryptographic primitives
│   ├── curves/             # Elliptic curve implementations
│   │   ├── native/         # Native curve arithmetic
│   │   │   ├── bls12381/   # BLS12-381 pairing-friendly curve
│   │   │   ├── k256/       # Secp256k1 (Bitcoin/Ethereum)
│   │   │   ├── p256/       # NIST P-256
│   │   │   └── pasta/      # Pallas/Vesta for ZK proofs
│   │   ├── bls12377_curve.go
│   │   ├── bls12381_curve.go
│   │   ├── ed25519_curve.go
│   │   ├── k256_curve.go
│   │   ├── p256_curve.go
│   │   └── pallas_curve.go
│   ├── protocol/           # MPC protocol framework
│   ├── commit.go           # Pedersen commitments
│   ├── hash.go             # Cryptographic hash utilities
│   └── mod.go              # Modular arithmetic
│
├── mpc/                     # Multi-Party Computation
│   ├── enclave.go          # MPC enclave management
│   ├── protocol.go         # DKG and signing protocols
│   ├── codec.go            # Serialization/deserialization
│   ├── import.go           # Enclave import/export
│   ├── verify.go           # Signature verification
│   └── spec/               # UCAN/JWT specifications
│
├── tecdsa/                  # Threshold ECDSA
│   └── dklsv1/             # 2-party ECDSA (DKLS v1)
│       ├── dkg/            # Distributed key generation
│       ├── sign/           # Threshold signing
│       ├── refresh/        # Key refresh protocol
│       └── dealer/         # Trusted dealer mode
│
├── ted25519/                # Threshold Ed25519
│   ├── frost/              # FROST protocol (DKG + signing)
│   └── ted25519/           # Core threshold Ed25519
│
├── signatures/              # Digital signature schemes
│   ├── bls/                # BLS signatures
│   │   └── bls_sig/        # Aggregatable BLS
│   ├── bbs/                # BBS+ selective disclosure
│   ├── schnorr/            # Schnorr variants
│   │   ├── mina/           # Mina protocol integration
│   │   └── nem/            # NEM blockchain support
│   └── common/             # Shared signature utilities
│
├── sharing/                 # Secret sharing schemes
│   ├── shamir.go           # Shamir's Secret Sharing
│   ├── feldman.go          # Feldman VSS
│   ├── pedersen.go         # Pedersen VSS
│   └── v1/                 # Version 1 implementations
│
├── dkg/                     # Distributed Key Generation
│   ├── frost/              # FROST DKG for Ed25519
│   ├── gennaro/            # Gennaro DKG protocol
│   └── gennaro2p/          # 2-party simplified DKG
│
├── bulletproof/             # Bulletproofs (range proofs)
│   ├── range_prover.go     # Range proof generation
│   ├── range_verifier.go   # Range proof verification
│   ├── ipp_prover.go       # Inner product argument
│   └── generators.go       # Generator points
│
├── accumulator/             # Cryptographic accumulators
│   ├── accumulator.go      # RSA accumulator
│   ├── witness.go          # Membership witnesses
│   └── proof.go            # Inclusion/exclusion proofs
│
├── paillier/                # Paillier homomorphic encryption
│   ├── paillier.go         # Public/private key operations
│   └── psf.go              # Proof of safe factorization
│
├── ot/                      # Oblivious Transfer
│   ├── base/simplest/      # Simplest OT protocol
│   └── extension/kos/      # KOS OT extension
│
├── zkp/                     # Zero-Knowledge Proofs
│   └── schnorr/            # Schnorr proofs of knowledge
│
├── ucan/                    # User-Controlled Authorization Networks
│   ├── capability.go       # Capability management
│   ├── crypto.go           # UCAN cryptographic operations
│   ├── jwt.go              # JWT-based UCAN tokens
│   ├── verifier.go         # Delegation chain verification
│   └── vault.go            # Vault-specific capabilities
│
├── keys/                    # Key management utilities
│   ├── didkey.go           # DID key format support
│   ├── pubkey.go           # Public key operations
│   └── parsers/            # Multi-chain key parsers
│       ├── btc_parser.go   # Bitcoin key parsing
│       ├── eth_parser.go   # Ethereum key parsing
│       ├── cosmos_parser.go # Cosmos SDK parsing
│       ├── sol_parser.go   # Solana key parsing
│       └── ...             # Other blockchain parsers
│
├── aead/                    # Authenticated encryption
│   └── aes_gcm.go          # AES-GCM AEAD
│
├── daed/                    # Deterministic AEAD
│   └── aes_siv.go          # AES-SIV encryption
│
├── ecies/                   # Elliptic Curve IES
│   ├── encrypt.go          # ECIES encryption
│   └── keys.go             # Key generation
│
├── argon2/                  # Password hashing
│   └── kdf.go              # Argon2 key derivation
│
├── vrf/                     # Verifiable Random Functions
│   └── vrf.go              # Curve25519 VRF
│
├── ecdsa/                   # ECDSA utilities
│   ├── canonical.go        # Canonical signature encoding
│   └── deterministic.go    # RFC 6979 deterministic signing
│
├── subtle/                  # Low-level crypto utilities
│   ├── hkdf.go             # HKDF key derivation
│   ├── random/             # Secure randomness
│   └── x25519.go           # X25519 key exchange
│
└── internal/                # Internal utilities
    ├── ed25519/            # Extended Ed25519 operations
    ├── hash.go             # Hash utilities
    └── point.go            # Point operations

Core Modules

1. Multi-Party Computation (mpc/)

Purpose: Secure distributed key generation and threshold signing without trusted dealers.

MPC Enclave Structure

type EnclaveData struct {
    PubHex    string    `json:"pub_hex"`   // Compressed public key (hex)
    PubBytes  []byte    `json:"pub_bytes"` // Uncompressed public key
    ValShare  Message   `json:"val_share"` // Alice (validator) keyshare
    UserShare Message   `json:"user_share"`// Bob (user) keyshare
    Nonce     []byte    `json:"nonce"`     // Encryption nonce
    Curve     CurveName `json:"curve"`     // Elliptic curve name
}

Key Functions

// Generate new MPC enclave (2-of-2 threshold)
func NewEnclave() (Enclave, error)

// Import enclave from various sources
func ImportEnclave(options ...ImportOption) (Enclave, error)

// Execute distributed signing protocol
func ExecuteSigning(signFuncVal SignFunc, signFuncUser SignFunc) ([]byte, error)

// Execute keyshare refresh protocol
func ExecuteRefresh(refreshFuncVal RefreshFunc, refreshFuncUser RefreshFunc,
                   curve CurveName) (Enclave, error)

// Verify signature with public key
func VerifyWithPubKey(pubKeyCompressed []byte, data []byte, sig []byte) (bool, error)

Security Features

• 2-of-2 Threshold: Both parties required for signing
• No Single Point of Failure: Neither party can sign alone
• Proactive Refresh: Key rotation without changing public key
• AES-GCM Encryption: Secure enclave data encryption
• SHA3-256 Hashing: Cryptographic hash operations

Supported Curves

• K256 - Secp256k1 (Bitcoin, Ethereum)
• P256 - NIST P-256
• ED25519 - Twisted Edwards curve
• BLS12381 - Pairing-friendly curve

2. Elliptic Curves (core/curves/)

Purpose: Comprehensive elliptic curve implementations with unified interfaces.

Supported Curves

Ed25519

• Twisted Edwards curve for EdDSA signatures
• High-performance, constant-time operations
• Used in: Cosmos SDK, Solana, many modern systems

Secp256k1 (K256)

• Bitcoin and Ethereum standard curve
• ECDSA signature support
• Native field arithmetic implementations

P-256 (Secp256r1)

• NIST standard curve
• FIPS 186-4 compliant
• Wide hardware acceleration support

BLS12-381

• Pairing-friendly curve for BLS signatures
• Optimal ate pairing support
• Signature aggregation capabilities
• G1, G2, and GT group operations

BLS12-377

• Alternative pairing curve
• Used in certain ZK-SNARK constructions

Pallas/Vesta

• Pasta curves for recursive ZK proofs
• Cycle of curves for composition

Curve Interface

type Curve interface {
    Scalar
    Point
    Name() string
    NewIdentityPoint() Point
    NewGeneratorPoint() Point
    Hash(input []byte) Point
    // ... additional methods
}

3. Signature Schemes (signatures/)

BLS Signatures (signatures/bls/)

Features:

• Signature aggregation (combine multiple signatures)
• Threshold signatures (t-of-n)
• Multi-signatures with proof of possession
• Both G1 and G2 variants (tiny_bls and usual_bls)

Key Operations:

// Sign message
func (sk *SecretKey) Sign(msg []byte) *Signature

// Aggregate multiple signatures
func AggregateSignatures(sigs ...*Signature) (*MultiSignature, error)

// Verify aggregated signature
func (sig *Signature) AggregateVerify(pks []*PublicKey, msgs [][]byte) (bool, error)

// Threshold key generation
func ThresholdGenerateKeys(threshold, total int) (*PublicKey, []*SecretKeyShare, error)

BBS+ Signatures (signatures/bbs/)

Purpose: Privacy-preserving signatures with selective disclosure

Features:

• Blind signatures for credential issuance
• Selective disclosure of attributes
• Zero-knowledge proofs of possession
• Unlinkable presentations

Use Cases:

• Verifiable credentials
• Anonymous authentication
• Privacy-preserving identity systems

Schnorr Signatures (signatures/schnorr/)

Mina Protocol (mina/):

• Poseidon hash function
• Schnorr signatures for Mina blockchain
• Challenge derivation

NEM/Symbol (nem/):

• Ed25519-Keccak variant
• NEM blockchain compatibility

4. Secret Sharing (sharing/)

Shamir's Secret Sharing

type Shamir struct {
    Threshold int
    Limit     int
    Curve     Curve
}

// Split secret into shares
func (s *Shamir) Split(secret []byte) ([]*ShamirShare, error)

// Reconstruct secret from shares
func (s *Shamir) Combine(shares []*ShamirShare) ([]byte, error)

Feldman Verifiable Secret Sharing

Added Security: Public commitments for share verification

type FeldmanVerifier struct {
    Commitments []curves.Point
}

// Verify share validity
func (v *FeldmanVerifier) Verify(share *ShamirShare) error

Pedersen Verifiable Secret Sharing

Enhanced Privacy: Computationally binding commitments

// Split with verifiable commitments
func (p *Pedersen) Split(secret []byte) (*PedersenResult, error)

5. Threshold Cryptography

TECDSA (tecdsa/dklsv1/)

Protocol: Two-party threshold ECDSA (DKLS v1)

Components:

• DKG: Distributed key generation without trusted dealer
• Signing: Threshold signature generation
• Refresh: Proactive keyshare rotation
• Dealer: Optional trusted dealer mode

Key Features:

• No trusted third party required
• Active security against malicious adversaries
• Compatible with standard ECDSA verification

TED25519 (ted25519/)

FROST Protocol (frost/):

• Flexible Round-Optimized Schnorr Threshold signatures
• Efficient threshold Ed25519 signatures
• Three-round signing protocol

Core Operations (ted25519/):

// Threshold key generation
func KeyGen(threshold, total int) ([]*SecretKeyShare, *PublicKey, error)

// Partial signature generation
func ThresholdSign(expandedSecretKeyShare []byte, publicKey []byte,
                   rShare []byte, R []byte, message []byte) []byte

// Signature aggregation
func AggregateSignatures(partialSigs [][]byte, R []byte) ([]byte, error)

6. Distributed Key Generation (dkg/)

Gennaro DKG (dkg/gennaro/)

Standard DKG protocol with:

• Four-round protocol
• Pedersen commitments
• Complaint handling
• Byzantine fault tolerance

FROST DKG (dkg/frost/)

Optimized for Ed25519:

• Two-round DKG
• Simplified complaint phase
• Integration with FROST signing

2-Party DKG (dkg/gennaro2p/)

Simplified protocol for two parties:

• Reduced communication overhead
• Faster execution
• Suitable for client-server architectures

7. Zero-Knowledge Proofs

Bulletproofs (bulletproof/)

Range Proofs without Trusted Setup:

// Prove value in range [0, 2^n]
func (p *RangeProver) Prove(v *big.Int, n int) (*RangeProof, error)

// Verify range proof
func (v *RangeVerifier) Verify(proof *RangeProof, commitment Point, n int) (bool, error)

// Batched range proofs (aggregate multiple proofs)
func BatchProve(values []*big.Int, n int) (*RangeProof, error)

Features:

• Logarithmic proof size: O(log n)
• Inner product arguments
• Batch verification support
• No trusted setup required

Applications:

• Confidential transactions
• Private smart contracts
• Privacy-preserving audits

Schnorr Proofs (zkp/schnorr/)

Proof of Knowledge:

• Discrete logarithm proofs
• Commitment proofs
• Non-interactive via Fiat-Shamir

8. Advanced Cryptography

Cryptographic Accumulators (accumulator/)

RSA Accumulator for set membership:

// Add element to accumulator
func (acc *Accumulator) Add(element []byte) (*Witness, error)

// Generate membership proof
func (w *Witness) GenerateProof() (*Proof, error)

// Verify membership
func (acc *Accumulator) Verify(element []byte, proof *Proof) bool

Use Cases:

• Revocation lists
• Anonymous credentials
• Blockchain state commitments

Paillier Encryption (paillier/)

Homomorphic Properties:

• Additive homomorphism: E(m1) * E(m2) = E(m1 + m2)
• Scalar multiplication: E(m)^k = E(k * m)
• Threshold decryption support

Applications:

• Private computation
• Secure multi-party computation
• E-voting systems

Oblivious Transfer (ot/)

Simplest OT (base/simplest/):

• 1-out-of-2 OT protocol
• Based on Curve25519

KOS Extension (extension/kos/):

• Extend base OT to many OTs
• Efficient batch operations
• Correlated randomness generation

Applications:

• Private set intersection
• Secure two-party computation
• Password-authenticated key exchange

9. UCAN (User-Controlled Authorization Networks) (ucan/)

Capability-Based Authorization:

// Create UCAN token
func CreateUCAN(issuer DID, audience DID, capabilities []Capability) (string, error)

// Attenuate capabilities (reduce permissions)
func AttenuateUCAN(parentToken string, newCapabilities []Capability) (string, error)

// Verify delegation chain
func VerifyDelegationChain(tokenString string, rootDID string) error

Capability Types:

• DID capabilities (read, write, update)
• DWN capabilities (records, protocols)
• Vault capabilities (sign, decrypt)
• DEX capabilities (swap, provide liquidity)

Features:

• JWT-based tokens
• Delegation chains
• Capability attenuation
• Proof-of-possession
• Expiration and not-before timestamps

10. Key Management (keys/)

DID Key Support (didkey.go)

// Create DID from public key
func NewDID(publicKey []byte, keyType crypto.KeyType) (*DID, error)

// Derive blockchain address from DID
func (did *DID) Address() (string, error)

// Get raw public key bytes
func (did *DID) Raw() ([]byte, error)

Multi-Chain Parsers (parsers/)

Supported Blockchains:

• Bitcoin (BTC) - BIP32/BIP44 derivation
• Ethereum (ETH) - Keccak addresses
• Cosmos SDK - Bech32 encoding
• Solana (SOL) - Ed25519 keys
• Filecoin (FIL) - Secp256k1 keys
• TON - Ed25519 keys

11. Encryption Utilities

AEAD (aead/)

AES-GCM Authenticated Encryption:

const (
    KeySize   = 32  // 256-bit key
    NonceSize = 12  // 96-bit nonce
    TagSize   = 16  // 128-bit auth tag
)

// Encrypt with automatic nonce generation
func (c *AESGCMCipher) Encrypt(plaintext, aad []byte) ([]byte, error)

// Decrypt and verify
func (c *AESGCMCipher) Decrypt(ciphertext, aad []byte) ([]byte, error)

DAED (daed/)

Deterministic AES-SIV:

• Same plaintext → same ciphertext
• Useful for encrypted indices
• Misuse-resistant

ECIES (ecies/)

Elliptic Curve Integrated Encryption Scheme:

// Generate ECIES keypair
func GenerateKey(curve Curve) (*PrivateKey, error)

// Encrypt message to public key
func Encrypt(recipientPubKey *PublicKey, message []byte) ([]byte, error)

// Decrypt with private key
func (sk *PrivateKey) Decrypt(ciphertext []byte) ([]byte, error)

12. Utility Modules

VRF (vrf/)

Verifiable Random Function (Curve25519):

// Generate VRF output and proof
func (sk *PrivateKey) Prove(message []byte) (vrf []byte, proof []byte)

// Verify VRF proof
func (pk *PublicKey) Verify(message, vrf, proof []byte) bool

Applications:

• Leader election
• Lottery systems
• Randomness beacons
• Sortition algorithms

Argon2 (argon2/)

Password-Based Key Derivation:

// Derive key from password
func DeriveKey(password, salt []byte, keyLen uint32) []byte

Parameters:

• Time cost: 1 iteration (configurable)
• Memory cost: 64 MB (configurable)
• Parallelism: 4 threads (configurable)

ECDSA Utilities (ecdsa/)

Canonical Encoding:

• BIP 66 / RFC 6979 compliance
• Deterministic signature generation
• Low-S normalization

Integration Patterns

Usage in Sonr Blockchain

The crypto library is heavily integrated throughout the Sonr ecosystem:

DID Module

import "github.com/sonr-io/crypto/keys"
import "github.com/sonr-io/crypto/mpc"

// DID creation from MPC enclave
enclave, _ := mpc.NewEnclave()
pubKey := enclave.GetPubPoint()
did := keys.NewDID(pubKey.Bytes(), crypto.Secp256k1)

DWN Module

import "github.com/sonr-io/crypto/mpc"
import "github.com/sonr-io/crypto/aead"

// Vault operations
enclave := keeper.LoadEnclave(ctx, vaultID)
signature, _ := enclave.Sign(message)

// Encrypted data storage
cipher := aead.NewAESGCMCipher(key)
encrypted, _ := cipher.Encrypt(data, nil)

Service Module

import "github.com/sonr-io/crypto/ucan"

// UCAN capability verification
verifier := ucan.NewVerifier(didResolver)
err := verifier.VerifyDelegationChain(ctx, tokenString)

Motor Worker Integration

The WASM worker uses the crypto library extensively:

import (
    "github.com/sonr-io/crypto/mpc"
    "github.com/sonr-io/crypto/core/curves"
)

//go:wasmexport sign
func sign() int32 {
    // Load enclave from WASM memory
    enclave := loadEnclave()

    // Sign message
    signature, _ := enclave.Sign(message)

    return writeOutput(signature)
}

Security Considerations

Threat Model

The library is designed to protect against:

Key Compromise:

• MPC threshold schemes prevent single points of failure
• Proactive refresh rotates keyshares

Insider Threats:

• Multi-party protocols require cooperation
• No single party can perform operations alone

Network Attacks:

• Protocol messages are cryptographically protected
• Authentication prevents man-in-the-middle attacks

Side-Channel Attacks:

• Constant-time implementations where critical
• Secure memory handling
• Zeroization of sensitive data

Best Practices

1. Key Management:

   • Use hardware security modules when available
   • Implement secure key backup and recovery
   • Regular keyshare rotation via refresh protocols

2. MPC Operations:

   • Secure communication channels (TLS)
   • Proper authentication of parties
   • Audit logging of all operations

3. Random Number Generation:

   • Use crypto/rand for all random values
   • Never reuse nonces in AEAD
   • Verify randomness quality in production

4. Error Handling:

   • Don't leak sensitive information in errors
   • Validate all inputs
   • Use constant-time comparisons for secrets

Testing

The library includes comprehensive tests:

# Run all tests
go test ./...

# Run with race detection
go test -race ./...

# Generate coverage report
go test -cover ./...

# Run specific module tests
go test ./mpc/...
go test ./signatures/bls/...
go test ./bulletproof/...

# Benchmark performance
go test -bench=. ./core/curves/...

Test Coverage

• MPC: Enclave operations, protocol execution, refresh
• Signatures: BLS aggregation, BBS+ proofs, Schnorr
• Secret Sharing: Shamir, Feldman, Pedersen
• Threshold Crypto: TECDSA, TED25519, DKG protocols
• ZK Proofs: Bulletproofs range proofs, Schnorr proofs
• Encryption: AEAD, ECIES, Paillier
• Curves: All curve operations, point arithmetic

Dependencies

External Libraries

require (
    github.com/btcsuite/btcd/btcec/v2 v2.3.2      // Bitcoin crypto
    github.com/consensys/gnark-crypto v0.19.0     // BLS12-377/381
    golang.org/x/crypto v0.42.0                   // Standard crypto
    github.com/golang-jwt/jwt/v5 v5.3.0           // JWT tokens
)

Internal Dependencies

The crypto library is self-contained and has no dependencies on other Sonr modules, making it suitable for independent use.

Performance Characteristics

Benchmarks (on AMD64, 2.5 GHz)

Elliptic Curve Operations:

• K256 scalar multiplication: ~50 µs
• Ed25519 signing: ~25 µs
• BLS12-381 pairing: ~1.2 ms

MPC Operations:

• DKG (2-party): ~15 ms
• Threshold signing: ~10 ms
• Key refresh: ~12 ms

Signature Schemes:

• BLS aggregation (100 sigs): ~150 ms
• BBS+ proof generation: ~80 ms
• Schnorr signing: ~30 µs

Zero-Knowledge Proofs:

• Bulletproof (64-bit range): ~40 ms
• Verification: ~25 ms

Migration Checklist

When using the crypto library in a new project:

• Add dependency: go get github.com/sonr-io/crypto@v1.0.1
• Import required modules
• Initialize curve instances as needed
• Set up secure random number generation
• Implement proper error handling
• Add comprehensive tests
• Review security best practices
• Benchmark critical operations
• Set up monitoring/logging
• Document cryptographic assumptions

Version Compatibility

Go Version: 1.24.4+

Cosmos SDK: Compatible with v0.50.x (if using Cosmos integration)

Semantic Versioning: The library follows semver

• Major: Breaking API changes
• Minor: New features, backwards compatible
• Patch: Bug fixes

Related Documentation

• Cosmos SDK Cryptography
• BLS Signatures Spec
• FROST Paper
• Bulletproofs Paper
• UCAN Spec
• W3C DID Core

Support

Repository: https://github.com/sonr-io/crypto Issues: https://github.com/sonr-io/crypto/issues License: Apache 2.0