# Private Keys

## Overview

The `PrivateKey` class is a fundamental component of the BSV TypeScript SDK that handles elliptic curve private key operations. Private keys are 256-bit numbers used to sign transactions and prove ownership of Bitcoin.

## Purpose

This component provides:

* Private key generation from random data or WIF (Wallet Import Format)
* DER signature creation and verification
* Public key derivation
* WIF encoding/decoding
* Message signing capabilities

## Basic Usage

### Generating a New Private Key

```typescript
import { PrivateKey } from '@bsv/sdk'

// Generate a random private key
const privateKey = PrivateKey.fromRandom()

// Get the private key as hex string
const hex = privateKey.toHex()

// Get WIF (Wallet Import Format) representation
const wif = privateKey.toWif()
```

### Creating from Existing Key Material

```typescript
// From WIF string
const privateKey = PrivateKey.fromWif('L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ')

// From hex string
const privateKey = PrivateKey.fromHex('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')

// From random bytes
const privateKey = PrivateKey.fromRandom()
```

## Key Features

### 1. Signature Generation

Create DER-encoded signatures for transaction signing:

```typescript
const privateKey = PrivateKey.fromRandom()
const message = 'Hello BSV'
const messageHash = Hash.sha256(Buffer.from(message))

// Create signature
const signature = privateKey.sign(messageHash)

// Get DER encoding
const derSignature = signature.toDER()
```

### 2. Public Key Derivation

Derive the corresponding public key:

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

console.log('Public Key:', publicKey.toHex())
console.log('Address:', publicKey.toAddress())
```

### 3. WIF Encoding/Decoding

WIF (Wallet Import Format) provides a compact representation:

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

// Export to WIF
const wif = privateKey.toWif()
console.log('WIF:', wif)

// Import from WIF
const imported = PrivateKey.fromWif(wif)
```

### 4. Message Signing

Sign arbitrary messages for authentication:

```typescript
const privateKey = PrivateKey.fromRandom()
const message = 'Prove ownership'

// Sign message
const signature = privateKey.signMessage(message)

// Verify with public key
const publicKey = privateKey.toPublicKey()
const isValid = publicKey.verifyMessage(message, signature)
```

## API Reference

### Constructor

```typescript
constructor(number?: BigNumber, compressed?: boolean)
```

* `number`: The private key as a BigNumber (optional)
* `compressed`: Whether to use compressed format (default: true)

### Static Methods

* `fromRandom(): PrivateKey` - Generate random private key
* `fromWif(wif: string): PrivateKey` - Import from WIF
* `fromHex(hex: string): PrivateKey` - Import from hex string
* `fromString(str: string): PrivateKey` - Import from hex or WIF string

### Instance Methods

* `toWif(): string` - Export to WIF format
* `toHex(): string` - Export to hex string
* `toPublicKey(): PublicKey` - Derive public key
* `sign(hash: number[]): Signature` - Sign a hash
* `signMessage(message: string): Signature` - Sign a message
* `verify(hash: number[], signature: Signature): boolean` - Verify signature

## Common Patterns

### Deterministic Key Generation

```typescript
import { PrivateKey, Hash } from '@bsv/sdk'

// Generate from seed phrase (simplified example)
function keyFromSeed(seed: string, index: number): PrivateKey {
  const hash = Hash.sha256(Buffer.from(`${seed}:${index}`))
  return PrivateKey.fromHex(hash.toString('hex'))
}

const key1 = keyFromSeed('my secret seed', 0)
const key2 = keyFromSeed('my secret seed', 1)
```

### Secure Key Storage

```typescript
import { PrivateKey } from '@bsv/sdk'
import { encrypt, decrypt } from './encryption-utils'

// Store encrypted private key
function storeKey(privateKey: PrivateKey, password: string): string {
  const wif = privateKey.toWif()
  return encrypt(wif, password)
}

// Retrieve and decrypt
function retrieveKey(encrypted: string, password: string): PrivateKey {
  const wif = decrypt(encrypted, password)
  return PrivateKey.fromWif(wif)
}
```

### Transaction Signing Pattern

```typescript
import { PrivateKey, Transaction } from '@bsv/sdk'

async function signTransaction(
  tx: Transaction,
  privateKey: PrivateKey,
  inputIndex: number
): Promise<void> {
  const publicKey = privateKey.toPublicKey()

  // Sign the input
  await tx.sign(inputIndex, privateKey, publicKey)
}
```

## Security Considerations

### 1. Key Generation

Always use cryptographically secure random number generation:

```typescript
// ✅ GOOD - Uses secure random
const privateKey = PrivateKey.fromRandom()

// ❌ BAD - Never use predictable sources
const badKey = PrivateKey.fromHex('0000000000000000000000000000000000000000000000000000000000000001')
```

### 2. Key Storage

Never store private keys in plain text:

```typescript
// ❌ BAD - Plain text storage
localStorage.setItem('privateKey', privateKey.toWif())

// ✅ GOOD - Encrypted storage
const encrypted = encryptKey(privateKey.toWif(), userPassword)
localStorage.setItem('encryptedKey', encrypted)
```

### 3. Memory Management

Clear sensitive data when no longer needed:

```typescript
function usePrivateKey(wif: string) {
  const privateKey = PrivateKey.fromWif(wif)

  try {
    // Use the key
    const signature = privateKey.sign(messageHash)
    return signature
  } finally {
    // Clear from memory (implementation dependent)
    wif = null
  }
}
```

## Related Components

* [Public Keys](/bsv-code-academy/sdk-components-reference/sdk-components/public-keys.md) - Derive public keys from private keys
* [Signatures](/bsv-code-academy/sdk-components-reference/sdk-components/signatures.md) - Work with ECDSA signatures
* [HD Wallets](/bsv-code-academy/sdk-components-reference/sdk-components/hd-wallets.md) - Hierarchical deterministic key derivation
* [Transaction](/bsv-code-academy/sdk-components-reference/sdk-components/transaction.md) - Sign transactions with private keys

## Code Examples

### Complete Working Examples

See these code features for full implementations:

* [Generate Private Key](/bsv-code-academy/code-features/code-features/generate-private-key.md)
* [Sign Transaction](/bsv-code-academy/code-features/code-features/sign-transaction.md)
* [Create Wallet](/bsv-code-academy/code-features/code-features/create-wallet.md)

### Example: Complete Key Management

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

class KeyManager {
  private privateKey: PrivateKey
  private publicKey: PublicKey

  constructor(wif?: string) {
    if (wif) {
      this.privateKey = PrivateKey.fromWif(wif)
    } else {
      this.privateKey = PrivateKey.fromRandom()
    }
    this.publicKey = this.privateKey.toPublicKey()
  }

  getAddress(): string {
    return this.publicKey.toAddress()
  }

  sign(messageHash: number[]): Signature {
    return this.privateKey.sign(messageHash)
  }

  export(): string {
    return this.privateKey.toWif()
  }

  verify(messageHash: number[], signature: Signature): boolean {
    return this.publicKey.verify(messageHash, signature)
  }
}

// Usage
const manager = new KeyManager()
console.log('Address:', manager.getAddress())

const exported = manager.export()
const restored = new KeyManager(exported)
```

## Best Practices

1. **Never hardcode private keys** in source code
2. **Use WIF format** for human-readable key export
3. **Always verify** signatures after creating them
4. **Use compressed keys** (default) to save space
5. **Implement proper key backup** procedures
6. **Test with testnet keys** before using mainnet
7. **Use HD wallets** (BRC-42) for multiple addresses

## Troubleshooting

### Common Issues

**Invalid WIF string:**

```typescript
try {
  const key = PrivateKey.fromWif(userInput)
} catch (error) {
  console.error('Invalid WIF format')
}
```

**Signature verification fails:**

```typescript
const signature = privateKey.sign(hash)
const valid = publicKey.verify(hash, signature)

if (!valid) {
  // Check that hash is correct
  // Ensure using matching public key
  // Verify signature wasn't corrupted
}
```

## Further Reading

* [ECDSA on Wikipedia](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)
* [WIF Format](https://en.bitcoin.it/wiki/Wallet_import_format)
* [BRC-42: Key Derivation](/bsv-code-academy/sdk-components-reference/sdk-components/brc-42.md)

## Status

✅ **Complete** - Production ready


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.bsvblockchain.org/bsv-code-academy/sdk-components-reference/sdk-components/private-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.