Class BSV::Primitives::PrivateKey ¶

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

key = BSV::Primitives::PrivateKey.generate
key.to_wif #=> "5J..."

@example Import from WIF

key = BSV::Primitives::PrivateKey.from_wif('5HueCGU8rMjxEX...')
key.public_key.address #=> "1GAeh..."

Constants¶

MAINNET_PREFIX ¶

WIF version prefix for mainnet private keys.

TESTNET_PREFIX ¶

WIF version prefix for testnet private keys.

Attributes¶

bn [R] ¶

• @return [OpenSSL::BN] the private key as a big number

Public Class Methods¶

from_backup_shares(shares) ¶

Reconstruct a private key from backup-format share strings. - @param shares [Array] backup-format share strings - @return [PrivateKey]

from_bytes(bytes) ¶

Create a private key from raw 32-byte big-endian encoding. - @param bytes [String] 32-byte binary string - @return [PrivateKey]

from_hex(hex) ¶

Create a private key from a hex string. - @param hex [String] 64-character hex-encoded private key - @return [PrivateKey]

from_key_shares(key_shares) ¶

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) ¶

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() ¶

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) ¶

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) ¶

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)

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) ¶

• @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() ¶

Derive the corresponding public key. - @return [PublicKey] the public key for this private key

sign(hash) ¶

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) ¶

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] backup-format share strings

to_bytes() ¶

Serialise the private key as 32-byte big-endian binary. - @return [String] 32-byte binary string (zero-padded)

to_hex() ¶

Serialise the private key as a 64-character hex string. - @return [String] hex-encoded private key

to_key_shares(threshold, total_shares) ¶

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, compressed: = true) ¶

Serialise the private key in Wallet Import Format (WIF). - @param network [Symbol] +:mainnet+ or +:testnet+ - @param compressed [Boolean] whether to flag for compressed public key derivation - @return [String] Base58Check-encoded WIF string