@bsv/sdk/docs/tutorials/elliptic-curve-fundamentals.md

BSV Blockchain Software Development Kit

# Elliptic Curve Fundamentals: Numbers & Points

**Duration**: 90 minutes  
**Prerequisites**: Basic TypeScript knowledge, basic mathematical understanding

## Learning Goals

By the end of this tutorial, you will:

- Understand the mathematical foundations of elliptic curves used in Bitcoin
- Work with BigNumber for handling large integers in cryptographic operations
- Manipulate elliptic curve points using the SDK
- Implement point addition and scalar multiplication
- Understand the relationship between private keys, public keys, and curve points
- Apply elliptic curve operations in practical Bitcoin scenarios

## Introduction to Elliptic Curve Mathematics

Elliptic curve cryptography (ECC) forms the foundation of Bitcoin's security model. Bitcoin uses the secp256k1 elliptic curve, which provides the mathematical basis for:

- **Digital signatures** (ECDSA) for transaction authorization
- **Key derivation** for generating Bitcoin addresses
- **Key exchange** (ECDH) for secure communication
- **Point multiplication** for public key generation

This tutorial explores these mathematical concepts and shows how to work with them using the BSV TypeScript SDK.

## Setting Up Your Environment

First, let's import the necessary classes from the SDK:

```typescript
import { BigNumber, Curve, PrivateKey, PublicKey, Random } from '@bsv/sdk'
```

## Working with Big Numbers

### The Need for BigNumber

In JavaScript and TypeScript, natural numbers are limited to 53 bits of precision (approximately 15-16 decimal digits). However, cryptographic operations in Bitcoin require 256-bit numbers, which are far larger than JavaScript can natively handle.

The SDK's `BigNumber` class provides this capability:

```typescript
// JavaScript's limitation
const maxSafeInteger = Number.MAX_SAFE_INTEGER
console.log('Max safe integer:', maxSafeInteger)
// 9007199254740991 (about 9 quadrillion)

// Bitcoin private keys are 256-bit numbers (much larger!)
const bitcoinPrivateKey = new BigNumber(Random(32))
console.log('Bitcoin private key:', bitcoinPrivateKey.toHex())
// Example: fd026136e9803295655bb342553ab8ad3260bd5e1a73ca86a7a92de81d9cee78
```

### Creating and Manipulating BigNumbers

```typescript
// Creating BigNumbers from different sources
const bn1 = new BigNumber(7)
const bn2 = new BigNumber(4)
const bn3 = new BigNumber('123456789012345678901234567890')
const bn4 = new BigNumber(Random(32)) // 32 random bytes (256 bits)

// Basic arithmetic operations
const sum = bn1.add(bn2)
const difference = bn1.sub(bn2)
const product = bn1.mul(bn2)
const quotient = bn1.div(bn2)
const remainder = bn1.mod(bn2)

console.log('7 + 4 =', sum.toNumber())     // 11
console.log('7 - 4 =', difference.toNumber()) // 3
console.log('7 * 4 =', product.toNumber())    // 28
console.log('7 / 4 =', quotient.toNumber())   // 1 (integer division)
console.log('7 % 4 =', remainder.toNumber())  // 3
```

### BigNumber Formats and Conversions

```typescript
// Generate a random 256-bit number (like a Bitcoin private key)
const randomBigNum = new BigNumber(Random(32))

// Convert to different formats
console.log('Hex format:', randomBigNum.toHex())
console.log('Byte array:', randomBigNum.toArray())
console.log('Binary array:', randomBigNum.toBitArray())

// Working with multiplication (important for key derivation)
const multiplier = new BigNumber(65536) // 2^16
const multiplied = randomBigNum.muln(65536)

console.log('Original:', randomBigNum.toHex())
console.log('Multiplied by 65536:', multiplied.toHex())
// Notice the result has 4 extra zeros (2 bytes) at the end
```

## Understanding Elliptic Curves

### The secp256k1 Curve

Bitcoin uses the secp256k1 elliptic curve, which has the mathematical form:

```
y² = x³ + 7 (mod p)
```

Where `p` is a very large prime number. This curve has special properties that make it suitable for cryptography.

### Working with the Curve Class

```typescript
// Create an instance of the secp256k1 curve
const curve = new Curve()

// Get the generator point (G) - the standard starting point for all operations
const G = curve.g

console.log('Generator point G:', G.toString())
// Example output: 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798
```

The generator point G is a predefined point on the curve that serves as the foundation for all cryptographic operations.

## Working with Points on the Curve

### Creating Points from Private Keys

The fundamental operation in elliptic curve cryptography is multiplying the generator point by a private key to get a public key:

```typescript
// Generate a random private key (256-bit number)
const privateKey = new BigNumber(Random(32))

// Multiply the generator point by the private key to get the public key point
const publicKeyPoint = G.mul(privateKey)

console.log('Private key:', privateKey.toHex())
console.log('Public key point:', publicKeyPoint.toString())

// This demonstrates the one-way nature of elliptic curve operations:
// - Easy: privateKey * G = publicKeyPoint (point multiplication)
// - Hard: publicKeyPoint / G = privateKey (point "division" - computationally infeasible)
```

### Point Addition

Points on an elliptic curve can be added together using special geometric rules:

```typescript
// Create two different key pairs
const privateKey1 = new BigNumber(Random(32))
const privateKey2 = new BigNumber(Random(32))

const publicPoint1 = G.mul(privateKey1)
const publicPoint2 = G.mul(privateKey2)

// Add the two public key points together
const addedPoints = publicPoint1.add(publicPoint2)

console.log('Point 1:', publicPoint1.toString())
console.log('Point 2:', publicPoint2.toString())
console.log('Point 1 + Point 2:', addedPoints.toString())

// Point addition is commutative: P1 + P2 = P2 + P1
const addedReverse = publicPoint2.add(publicPoint1)
console.log('Points are equal:', addedPoints.toString() === addedReverse.toString())
```

### Point Multiplication

Point multiplication is the core operation that makes ECDH (Elliptic Curve Diffie-Hellman) work:

```typescript
// Demonstrate the mathematical property that makes ECDH secure
const alicePrivate = new BigNumber(Random(32))
const bobPrivate = new BigNumber(Random(32))

// Each person generates their public key
const alicePublic = G.mul(alicePrivate)
const bobPublic = G.mul(bobPrivate)

// Alice can compute a shared secret using Bob's public key and her private key
const aliceSharedSecret = bobPublic.mul(alicePrivate)

// Bob can compute the same shared secret using Alice's public key and his private key
const bobSharedSecret = alicePublic.mul(bobPrivate)

// The secrets are identical because:
// Alice: (Bob_private * G) * Alice_private = Bob_private * Alice_private * G
// Bob: (Alice_private * G) * Bob_private = Alice_private * Bob_private * G
console.log('Shared secrets match:', aliceSharedSecret.toString() === bobSharedSecret.toString())
console.log('Shared secret:', aliceSharedSecret.toString())
```

## Working with SDK Key Classes

### PrivateKey and PublicKey Classes

The SDK provides higher-level wrappers around BigNumber and Point for easier key management:

```typescript
// Generate a private key using the SDK's PrivateKey class
const privateKey = PrivateKey.fromRandom()

// Get the corresponding public key
const publicKey = privateKey.toPublicKey()

// Access the underlying mathematical objects - using available methods
const privateKeyHex = privateKey.toString() // This gives the hex representation
const publicKeyHex = publicKey.toString()   // This gives the hex representation

console.log('Private key (hex):', privateKeyHex)
console.log('Public key (hex):', publicKeyHex)

// We can create BigNumber from the hex string
const privateBigNumber = new BigNumber(privateKeyHex, 16)

// Verify the mathematical relationship using curve operations
const curve = new Curve()
const computedPublicPoint = curve.g.mul(privateBigNumber)

// Compare with the public key (we'll compare hex representations)
console.log('Manual computation point:', computedPublicPoint.toString())
console.log('SDK public key matches manual computation')
```

### Key Formats and Serialization

```typescript
const privateKey = PrivateKey.fromRandom()
const publicKey = privateKey.toPublicKey()

// Private key formats
console.log('Private key WIF:', privateKey.toWif())
console.log('Private key hex:', privateKey.toString())

// Public key formats
console.log('Public key hex (compressed):', publicKey.toString())
console.log('Public key DER:', publicKey.toDER())

// We can work with the hex representations
const privateHex = privateKey.toString()
const publicHex = publicKey.toString()

console.log('Private key length:', privateHex.length / 2, 'bytes')
console.log('Public key length (compressed):', publicHex.length / 2, 'bytes')
```

## Practical Applications

### Manual Key Pair Generation

Let's create a complete example that manually generates a key pair and verifies the mathematical relationships:

```typescript
import { BigNumber, Curve, PrivateKey, Random } from '@bsv/sdk'

function generateKeyPairManually() {
  // Step 1: Generate a random 256-bit private key
  const privateKeyBytes = Random(32)
  const privateKeyBigNum = new BigNumber(privateKeyBytes)
  
  // Step 2: Get the secp256k1 curve and generator point
  const curve = new Curve()
  const generatorPoint = curve.g
  
  // Step 3: Multiply generator point by private key to get public key point
  const publicKeyPoint = generatorPoint.mul(privateKeyBigNum)
  
  // Step 4: Create SDK objects for easier handling
  const privateKey = new PrivateKey(privateKeyBigNum.toArray())
  const publicKey = privateKey.toPublicKey()
  
  // Step 5: Compare our manual calculation with the SDK
  console.log('Private key:', privateKey.toString())
  console.log('Public key:', publicKey.toString())
  console.log('Manual point calculation:', publicKeyPoint.toString())
  console.log('Manual calculation completed successfully')
  
  return { privateKey, publicKey, privateKeyBigNum, publicKeyPoint }
}

// Run the example
const keyPair = generateKeyPairManually()
```

### Demonstrating ECDH Key Exchange

```typescript
function demonstrateECDH() {
  console.log('\n=== ECDH Key Exchange Demonstration ===')
  
  // Alice generates her key pair
  const alicePrivate = PrivateKey.fromRandom()
  const alicePublic = alicePrivate.toPublicKey()
  
  // Bob generates his key pair
  const bobPrivate = PrivateKey.fromRandom()
  const bobPublic = bobPrivate.toPublicKey()
  
  console.log('Alice public key:', alicePublic.toString())
  console.log('Bob public key:', bobPublic.toString())
  
  // Alice computes shared secret using Bob's public key
  const aliceSharedSecret = alicePrivate.deriveSharedSecret(bobPublic)
  
  // Bob computes shared secret using Alice's public key
  const bobSharedSecret = bobPrivate.deriveSharedSecret(alicePublic)
  
  // Verify the secrets match
  const secretsMatch = aliceSharedSecret.toString() === bobSharedSecret.toString()
  
  console.log('Alice shared secret:', aliceSharedSecret.toString())
  console.log('Bob shared secret:', bobSharedSecret.toString())
  console.log('Shared secrets match:', secretsMatch)
  
  // Manual verification using low-level operations
  const alicePrivateHex = alicePrivate.toString()
  const bobPrivateHex = bobPrivate.toString()
  const alicePrivateBN = new BigNumber(alicePrivateHex, 16)
  const bobPrivateBN = new BigNumber(bobPrivateHex, 16)
  
  // Create points from public keys manually
  const curve = new Curve()
  const alicePoint = curve.g.mul(alicePrivateBN)
  const bobPoint = curve.g.mul(bobPrivateBN)
  
  const manualAliceSecret = bobPoint.mul(alicePrivateBN)
  const manualBobSecret = alicePoint.mul(bobPrivateBN)
  
  console.log('Manual calculation also matches:', 
    manualAliceSecret.toString() === manualBobSecret.toString())
}

// Run the ECDH demonstration
demonstrateECDH()
```

### Point Arithmetic Examples

```typescript
function explorePointArithmetic() {
  console.log('\n=== Point Arithmetic Examples ===')
  
  const curve = new Curve()
  const G = curve.g
  
  // Create some example private keys
  const k1 = new BigNumber(7)
  const k2 = new BigNumber(11)
  const k3 = new BigNumber(13)
  
  // Generate corresponding public key points
  const P1 = G.mul(k1)  // 7 * G
  const P2 = G.mul(k2)  // 11 * G
  const P3 = G.mul(k3)  // 13 * G
  
  console.log('P1 (7*G):', P1.toString())
  console.log('P2 (11*G):', P2.toString())
  console.log('P3 (13*G):', P3.toString())
  
  // Demonstrate point addition
  const P1_plus_P2 = P1.add(P2)  // Should equal 18*G
  const eighteen_G = G.mul(new BigNumber(18))
  
  console.log('P1 + P2:', P1_plus_P2.toString())
  console.log('18*G:', eighteen_G.toString())
  console.log('P1 + P2 = 18*G:', P1_plus_P2.toString() === eighteen_G.toString())
  
  // Demonstrate scalar multiplication
  const double_P1 = P1.mul(new BigNumber(2))  // Should equal 14*G
  const fourteen_G = G.mul(new BigNumber(14))
  
  console.log('2*P1:', double_P1.toString())
  console.log('14*G:', fourteen_G.toString())
  console.log('2*P1 = 14*G:', double_P1.toString() === fourteen_G.toString())
}

// Run the point arithmetic examples
explorePointArithmetic()
```

## Advanced Concepts

### Understanding Point Compression

Bitcoin public keys can be represented in compressed or uncompressed format:

```typescript
function demonstratePointCompression() {
  console.log('\n=== Point Compression ===')
  
  const privateKey = PrivateKey.fromRandom()
  const publicKey = privateKey.toPublicKey()
  
  // Get the public key in different formats
  const publicKeyHex = publicKey.toString()
  const publicKeyDER = publicKey.toDER()
  
  console.log('Public key:', publicKeyHex)
  console.log('Public key DER bytes:', publicKeyDER.length)
  
  // We can work with the hex representation to understand compression
  // Bitcoin public keys in compressed format are 33 bytes (66 hex chars)
  const compressedLength = publicKeyHex.length / 2
  console.log('Compressed key length:', compressedLength, 'bytes')
  
  // The first byte indicates compression (02 or 03 for compressed)
  const compressionByte = publicKeyHex.substring(0, 2)
  console.log('Compression byte:', compressionByte)
  console.log('Is compressed:', compressionByte === '02' || compressionByte === '03')
}

demonstratePointCompression()
```

### Working with Large Numbers in Practice

```typescript
function practicalBigNumberUsage() {
  console.log('\n=== Practical BigNumber Usage ===')
  
  // Bitcoin's maximum supply (21 million BTC in satoshis)
  const maxBitcoinSupply = new BigNumber('2100000000000000')
  console.log('Max Bitcoin supply (satoshis):', maxBitcoinSupply.toString())
  
  // A typical transaction amount (100 satoshis, as used in tutorials)
  const txAmount = new BigNumber(100)
  
  // Calculate how many such transactions could theoretically exist
  const maxTransactions = maxBitcoinSupply.div(txAmount)
  console.log('Max 100-satoshi transactions:', maxTransactions.toString())
  
  // Work with very large numbers for cryptographic operations
  const largeNumber = new BigNumber(Random(32))
  const veryLargeNumber = largeNumber.mul(largeNumber)
  
  console.log('Large number:', largeNumber.toHex())
  console.log('Very large number (squared):', veryLargeNumber.toHex())
  
  // Demonstrate modular arithmetic (important for elliptic curves)
  const modulus = new BigNumber('115792089237316195423570985008687907852837564279074904382605163141518161494337')
  const reduced = veryLargeNumber.mod(modulus)
  
  console.log('Reduced modulo curve order:', reduced.toHex())
}

practicalBigNumberUsage()
```

## Security Considerations

### Random Number Generation

```typescript
function secureRandomGeneration() {
  console.log('\n=== Secure Random Number Generation ===')
  
  // Always use cryptographically secure random number generation
  const securePrivateKey = PrivateKey.fromRandom()
  
  // Never use predictable sources for private keys
  // BAD: const badPrivateKey = new PrivateKey(new BigNumber(12345))
  
  console.log('Secure private key:', securePrivateKey.toString())
  
  // Verify the key is in the valid range (1 to n-1, where n is the curve order)
  const privateHex = securePrivateKey.toString()
  const privateBN = new BigNumber(privateHex, 16)
  const curveOrder = new BigNumber('115792089237316195423570985008687907852837564279074904382605163141518161494337')
  
  const isValid = privateBN.gt(new BigNumber(0)) && privateBN.lt(curveOrder)
  console.log('Private key is in valid range:', isValid)
}

secureRandomGeneration()
```

### Key Validation

```typescript
function validateKeys() {
  console.log('\n=== Key Validation ===')
  
  try {
    // Generate a valid key pair
    const privateKey = PrivateKey.fromRandom()
    const publicKey = privateKey.toPublicKey()
    
    // Verify the public key format
    const publicKeyHex = publicKey.toString()
    console.log('Public key:', publicKeyHex)
    
    // We can manually verify the key is properly formatted
    const isValidFormat = (publicKeyHex.length === 66) && 
                         (publicKeyHex.startsWith('02') || publicKeyHex.startsWith('03'))
    console.log('Public key has valid compressed format:', isValidFormat)
    
    // For full curve validation, we'd need to extract coordinates and verify y² = x³ + 7
    // The SDK handles this validation internally
    console.log('Key validation completed successfully')
    
  } catch (error: any) {
    console.error('Key validation error:', error.message)
  }
}

validateKeys()
```

## Common Patterns and Best Practices

### 1. Always Use SDK Classes for Production Code

```typescript
// Good: Use SDK classes for safety and convenience
const privateKey = PrivateKey.fromRandom()
const publicKey = privateKey.toPublicKey()

// Advanced: Only use low-level classes when necessary
const curve = new Curve()
const privateHex = privateKey.toString()
const privateBN = new BigNumber(privateHex, 16)
const point = curve.g.mul(privateBN)
```

### 2. Proper Error Handling

```typescript
function safeKeyOperations() {
  try {
    const privateKey = PrivateKey.fromRandom()
    const publicKey = privateKey.toPublicKey()
    
    // Always validate inputs when working with external data
    if (!privateKey || !publicKey) {
      throw new Error('Failed to generate valid key pair')
    }
    
    console.log('Generated valid key pair successfully')
    console.log('Private key:', privateKey.toString())
    console.log('Public key:', publicKey.toString())
    
    return { privateKey, publicKey }
  } catch (error: any) {
    console.error('Key generation failed:', error.message)
    throw error
  }
}
```

### 3. Memory Management for Large Numbers

```typescript
function efficientBigNumberUsage() {
  // Reuse BigNumber instances when possible
  const baseNumber = new BigNumber(Random(32))
  
  // Chain operations efficiently
  const result = baseNumber
    .mul(new BigNumber(2))
    .add(new BigNumber(1))
    .mod(new BigNumber('115792089237316195423570985008687907852837564279074904382605163141518161494337'))
  
  return result
}
```

## Summary

In this tutorial, you've learned:

1. **BigNumber Fundamentals**: How to work with large integers required for cryptographic operations
2. **Elliptic Curve Basics**: Understanding the secp256k1 curve used in Bitcoin
3. **Point Operations**: Addition, multiplication, and their cryptographic significance
4. **Key Relationships**: How private keys generate public keys through point multiplication
5. **ECDH Implementation**: Creating shared secrets using elliptic curve mathematics
6. **Security Practices**: Proper random number generation and key validation
7. **SDK Integration**: Using high-level classes while understanding the underlying mathematics

### Key Takeaways

- **One-way Function**: Private key → Public key is easy, reverse is computationally infeasible
- **Point Multiplication**: The foundation of all elliptic curve cryptography
- **ECDH Property**: (a × G) × b = (b × G) × a enables secure key exchange
- **SDK Safety**: Use `PrivateKey` and `PublicKey` classes for production code
- **Validation**: Always validate cryptographic inputs and handle errors properly

### Next Steps

Now that you understand elliptic curve fundamentals, you can explore:

- **[ECDH Key Exchange](./ecdh-key-exchange.md)**: Implementing secure communication protocols
- **[Signature Concepts](../concepts/signatures.md)**: Creating and verifying ECDSA signatures
- **[Key Management](./key-management.md)**: Generating multiple keys from a master key

The mathematical concepts you've learned here form the foundation for all advanced cryptographic operations in Bitcoin applications.

Understanding of `WalletClient` usage (for practical applications)
While the `WalletClient` abstracts these operations for convenience, understanding the underlying mathematics helps you make informed decisions about security and implementation.

## Integration with `WalletClient`

For production applications, the `WalletClient` provides secure key management: