# Class BSV::Primitives::PrivateKey <a id="class-BSV-Primitives-PrivateKey"></a>

**Inherits:** `Object`

A secp256k1 private key for signing transactions and deriving public keys.

Can be created from random entropy, raw bytes, hex, or WIF (Wallet Import
Format). Produces deterministic ECDSA signatures via {ECDSA}.

**@example Generate a new random key**
```ruby
key = BSV::Primitives::PrivateKey.generate
key.to_wif #=> "5J..."
```

**@example Import from WIF**
```ruby
key = BSV::Primitives::PrivateKey.from_wif('5HueCGU8rMjxEX...')
key.public_key.address #=> "1GAeh..."
```

## Constants
### `MAINNET_PREFIX` <a id="constant-MAINNET_PREFIX"></a> <a id="MAINNET_PREFIX-constant"></a>
WIF version prefix for mainnet private keys.

### `TESTNET_PREFIX` <a id="constant-TESTNET_PREFIX"></a> <a id="TESTNET_PREFIX-constant"></a>
WIF version prefix for testnet private keys.

## Attributes
### `bn` [R] <a id="attribute-i-bn"></a> <a id="bn-instance_method"></a>
- **@return** [OpenSSL::BN] the private key as a big number

## Public Class Methods
### `from_backup_shares(shares)` <a id="method-c-from_backup_shares"></a> <a id="from_backup_shares-class_method"></a>
Reconstruct a private key from backup-format share strings.
- **@param** `shares` [Array<String>] backup-format share strings
- **@return** [PrivateKey]

### `from_bytes(bytes)` <a id="method-c-from_bytes"></a> <a id="from_bytes-class_method"></a>
Create a private key from raw 32-byte big-endian encoding.
- **@param** `bytes` [String] 32-byte binary string
- **@return** [PrivateKey]

### `from_hex(hex)` <a id="method-c-from_hex"></a> <a id="from_hex-class_method"></a>
Create a private key from a hex string.
- **@param** `hex` [String] 64-character hex-encoded private key
- **@return** [PrivateKey]

### `from_key_shares(key_shares)` <a id="method-c-from_key_shares"></a> <a id="from_key_shares-class_method"></a>
Reconstruct a private key from a {KeyShares} object.

Evaluates the Lagrange polynomial at x=0 to recover the secret, then checks
the integrity hash against the reconstructed public key.
- **@param** `key_shares` [KeyShares] the shares to combine
- **@raise** [ArgumentError] if there are too few shares, duplicates, or integrity fails
- **@return** [PrivateKey] the reconstructed private key

### `from_wif(wif_string)` <a id="method-c-from_wif"></a> <a id="from_wif-class_method"></a>
Create a private key from Wallet Import Format (WIF).

Supports both compressed and uncompressed WIF encodings, and both mainnet and
testnet prefixes.
- **@param** `wif_string` [String] Base58Check-encoded WIF string
- **@raise** [ArgumentError] if the WIF prefix, length, or compression flag is invalid
- **@return** [PrivateKey]

### `generate()` <a id="method-c-generate"></a> <a id="generate-class_method"></a>
Generate a new random private key using secure random bytes.
- **@return** [PrivateKey] a cryptographically random private key

## Public Instance Methods
### `derive_child(public_key, invoice_number)` <a id="method-i-derive_child"></a> <a id="derive_child-instance_method"></a>
Derive a child private key using BRC-42 key derivation.

Computes HMAC-SHA256(key: ECDH_shared_secret, msg: invoice_number) and adds it
to this private key's scalar mod n. The corresponding public key can be
derived without the private key using {PublicKey#derive_child}.
- **@param** `public_key` [PublicKey] the counterparty's public key
- **@param** `invoice_number` [String] the invoice number (UTF-8)
- **@return** [PrivateKey] the derived child private key

### `derive_shared_secret(public_key)` <a id="method-i-derive_shared_secret"></a> <a id="derive_shared_secret-instance_method"></a>
Derive an ECDH shared secret with another party's public key.

Computes the shared point by multiplying the given public key by this private
key's scalar. The result is commutative:
    alice_priv.derive_shared_secret(bob_pub) ==
      bob_priv.derive_shared_secret(alice_pub)

Uses constant-time scalar multiplication to protect the private key scalar
from timing side-channels.

This is the foundational primitive for BRC-42 key derivation, BRC-77/78
messaging, and ECIES encryption.
- **@param** `public_key` [PublicKey] the other party's public key
- **@return** [PublicKey] the shared secret as a public key (curve point)

### `initialize(bn)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
- **@param** `bn` [OpenSSL::BN] the private key scalar (must be 1 < bn < N)
- **@raise** [ArgumentError] if bn is not an OpenSSL::BN or is out of range
- **@return** [PrivateKey] a new instance of PrivateKey

### `public_key()` <a id="method-i-public_key"></a> <a id="public_key-instance_method"></a>
Derive the corresponding public key.

Uses constant-time scalar multiplication to protect the private key scalar
from timing side-channels during derivation.
- **@return** [PublicKey] the public key for this private key

### `sign(hash)` <a id="method-i-sign"></a> <a id="sign-instance_method"></a>
Sign a 32-byte hash using deterministic ECDSA (RFC 6979).
- **@param** `hash` [String] 32-byte message digest to sign
- **@return** [Signature] the DER-encodable signature

### `to_backup_shares(threshold, total_shares)` <a id="method-i-to_backup_shares"></a> <a id="to_backup_shares-instance_method"></a>
Serialise this key as Shamir backup share strings.

Convenience wrapper around {#to_key_shares} and {KeyShares#to_backup_format}.
- **@param** `threshold` [Integer] minimum shares needed to reconstruct
- **@param** `total_shares` [Integer] total shares to generate
- **@return** [Array<String>] backup-format share strings

### `to_bytes()` <a id="method-i-to_bytes"></a> <a id="to_bytes-instance_method"></a>
Serialise the private key as 32-byte big-endian binary.
- **@return** [String] 32-byte binary string (zero-padded)

### `to_hex()` <a id="method-i-to_hex"></a> <a id="to_hex-instance_method"></a>
Serialise the private key as a 64-character hex string.
- **@return** [String] hex-encoded private key

### `to_key_shares(threshold, total_shares)` <a id="method-i-to_key_shares"></a> <a id="to_key_shares-instance_method"></a>
Split this private key into Shamir's Secret Sharing shares.

Generates `total_shares` evaluation points on a random polynomial whose
y-intercept encodes this key. Any `threshold` of them suffice to reconstruct
the key. X-coordinates are derived via HMAC-SHA-512 over a 64-byte random
seed, ensuring uniqueness even under partial RNG failure.
- **@param** `threshold` [Integer] minimum shares needed to reconstruct (>= 2)
- **@param** `total_shares` [Integer] total shares to generate (>= threshold)
- **@raise** [ArgumentError] if parameters are out of range
- **@return** [KeyShares]

### `to_wif(network: = :mainnet)` <a id="method-i-to_wif"></a> <a id="to_wif-instance_method"></a>
Serialise the private key in Wallet Import Format (WIF).

Always produces a compressed WIF (the 0x01 compression flag is appended). BSV
exclusively uses compressed public keys; uncompressed WIF export is not
supported ("construct only what's valid").

The `from_wif` parser continues to accept both compressed and uncompressed WIF
for import compatibility with legacy wallets.
- **@param** `network` [Symbol] +:mainnet+ or +:testnet+
- **@return** [String] Base58Check-encoded WIF string (compressed format)