@bsv/sdk
Version:
BSV Blockchain Software Development Kit
284 lines • 11.8 kB
TypeScript
import BigNumber from './BigNumber.js';
import Signature from './Signature.js';
import PublicKey from './PublicKey.js';
import Point from './Point.js';
import { PointInFiniteField } from './Polynomial.js';
/**
* @class KeyShares
*
* This class is used to store the shares of a private key.
*
* @param shares - An array of shares
* @param threshold - The number of shares required to recombine the private key
*
* @returns KeyShares
*
* @example
* const key = PrivateKey.fromShares(shares)
*
*/
export declare class KeyShares {
points: PointInFiniteField[];
threshold: number;
integrity: string;
constructor(points: PointInFiniteField[], threshold: number, integrity: string);
static fromBackupFormat(shares: string[]): KeyShares;
toBackupFormat(): string[];
}
/**
* Represents a Private Key, which is a secret that can be used to generate signatures in a cryptographic system.
*
* The `PrivateKey` class extends from the `BigNumber` class. It offers methods to create signatures, verify them,
* create a corresponding public key and derive a shared secret from a public key.
*
* @extends {BigNumber}
* @see {@link BigNumber} for more information on BigNumber.
*/
export default class PrivateKey extends BigNumber {
/**
* Generates a private key randomly.
*
* @method fromRandom
* @static
* @returns The newly generated Private Key.
*
* @example
* const privateKey = PrivateKey.fromRandom();
*/
static fromRandom(): PrivateKey;
/**
* Generates a private key from a string.
*
* @method fromString
* @static
* @param str - The string to generate the private key from.
* @param base - The base of the string.
* @returns The generated Private Key.
* @throws Will throw an error if the string is not valid.
**/
static fromString(str: string, base?: number | 'hex'): PrivateKey;
/**
* Generates a private key from a hexadecimal string.
*
* @method fromHex
* @static
* @param {string} str - The hexadecimal string representing the private key. The string must represent a valid private key in big-endian format.
* @returns {PrivateKey} The generated Private Key instance.
* @throws {Error} If the string is not a valid hexadecimal or represents an invalid private key.
**/
static fromHex(str: string): PrivateKey;
/**
* Generates a private key from a WIF (Wallet Import Format) string.
*
* @method fromWif
* @static
* @param wif - The WIF string to generate the private key from.
* @param base - The base of the string.
* @returns The generated Private Key.
* @throws Will throw an error if the string is not a valid WIF.
**/
static fromWif(wif: string, prefixLength?: number): PrivateKey;
/**
* @constructor
*
* @param number - The number (various types accepted) to construct a BigNumber from. Default is 0.
*
* @param base - The base of number provided. By default is 10. Ignored if number is BigNumber.
*
* @param endian - The endianness provided. By default is 'big endian'. Ignored if number is BigNumber.
*
* @param modN - Optional. Default 'apply. If 'apply', apply modN to input to guarantee a valid PrivateKey. If 'error', if input is out of field throw new Error('Input is out of field'). If 'nocheck', assumes input is in field.
*
* @example
* import PrivateKey from './PrivateKey';
* import BigNumber from './BigNumber';
* const privKey = new PrivateKey(new BigNumber('123456', 10, 'be'));
*/
constructor(number?: BigNumber | number | string | number[], base?: number | 'be' | 'le' | 'hex', endian?: 'be' | 'le', modN?: 'apply' | 'nocheck' | 'error');
/**
* A utility function to check that the value of this PrivateKey lies in the field limited by curve.n
* @returns { inField, modN } where modN is this PrivateKey's current BigNumber value mod curve.n, and inField is true only if modN equals current BigNumber value.
*/
checkInField(): {
inField: boolean;
modN: BigNumber;
};
/**
* @returns true if the PrivateKey's current BigNumber value lies in the field limited by curve.n
*/
isValid(): boolean;
/**
* Signs a message using the private key.
*
* @method sign
* @param msg - The message (array of numbers or string) to be signed.
* @param enc - If 'hex' the string will be treated as hex, utf8 otherwise.
* @param forceLowS - If true (the default), the signature will be forced to have a low S value.
* @param customK — If provided, uses a custom K-value for the signature. Provie a function that returns a BigNumber, or the BigNumber itself.
* @returns A digital signature generated from the hash of the message and the private key.
*
* @example
* const privateKey = PrivateKey.fromRandom();
* const signature = privateKey.sign('Hello, World!');
*/
sign(msg: number[] | string, enc?: 'hex' | 'utf8', forceLowS?: boolean, customK?: ((iter: number) => BigNumber) | BigNumber): Signature;
/**
* Verifies a message's signature using the public key associated with this private key.
*
* @method verify
* @param msg - The original message which has been signed.
* @param sig - The signature to be verified.
* @param enc - The data encoding method.
* @returns Whether or not the signature is valid.
*
* @example
* const privateKey = PrivateKey.fromRandom();
* const signature = privateKey.sign('Hello, World!');
* const isSignatureValid = privateKey.verify('Hello, World!', signature);
*/
verify(msg: number[] | string, sig: Signature, enc?: 'hex'): boolean;
/**
* Converts the private key to its corresponding public key.
*
* The public key is generated by multiplying the base point G of the curve and the private key.
*
* @method toPublicKey
* @returns The generated PublicKey.
*
* @example
* const privateKey = PrivateKey.fromRandom();
* const publicKey = privateKey.toPublicKey();
*/
toPublicKey(): PublicKey;
/**
* Converts the private key to a Wallet Import Format (WIF) string.
*
* Base58Check encoding is used for encoding the private key.
* The prefix
*
* @method toWif
* @returns The WIF string.
*
* @param prefix defaults to [0x80] for mainnet, set it to [0xef] for testnet.
*
* @throws Error('Value is out of field') if current BigNumber value is out of field limited by curve.n
*
* @example
* const privateKey = PrivateKey.fromRandom();
* const wif = privateKey.toWif();
* const testnetWif = privateKey.toWif([0xef]);
*/
toWif(prefix?: number[]): string;
/**
* Base58Check encodes the hash of the public key associated with this private key with a prefix to indicate locking script type.
* Defaults to P2PKH for mainnet, otherwise known as a "Bitcoin Address".
*
* @param prefix defaults to [0x00] for mainnet, set to [0x6f] for testnet or use the strings 'testnet' or 'mainnet'
*
* @returns Returns the address encoding associated with the hash of the public key associated with this private key.
*
* @example
* const address = privkey.toAddress()
* const address = privkey.toAddress('mainnet')
* const testnetAddress = privkey.toAddress([0x6f])
* const testnetAddress = privkey.toAddress('testnet')
*/
toAddress(prefix?: number[] | string): string;
/**
* Converts this PrivateKey to a hexadecimal string.
*
* @method toHex
* @param length - The minimum length of the hex string
* @returns Returns a string representing the hexadecimal value of this BigNumber.
*
* @example
* const bigNumber = new BigNumber(255);
* const hex = bigNumber.toHex();
*/
toHex(): string;
/**
* Converts this PrivateKey to a string representation.
*
* @method toString
* @param {number | 'hex'} [base='hex'] - The base for representing the number. Default is hexadecimal ('hex').
* @param {number} [padding=64] - The minimum number of digits for the output string. Default is 64, ensuring a 256-bit representation in hexadecimal.
* @returns {string} A string representation of the PrivateKey in the specified base, padded to the specified length.
*
**/
toString(base?: number | 'hex', padding?: number): string;
/**
* Derives a shared secret from the public key.
*
* @method deriveSharedSecret
* @param key - The public key to derive the shared secret from.
* @returns The derived shared secret (a point on the curve).
* @throws Will throw an error if the public key is not valid.
*
* @example
* const privateKey = PrivateKey.fromRandom();
* const publicKey = privateKey.toPublicKey();
* const sharedSecret = privateKey.deriveSharedSecret(publicKey);
*/
deriveSharedSecret(key: PublicKey): Point;
/**
* Derives a child key with BRC-42.
* @param publicKey The public key of the other party
* @param invoiceNumber The invoice number used to derive the child key
* @param cacheSharedSecret Optional function to cache shared secrets
* @param retrieveCachedSharedSecret Optional function to retrieve shared secrets from the cache
* @returns The derived child key.
*/
deriveChild(publicKey: PublicKey, invoiceNumber: string, cacheSharedSecret?: ((priv: PrivateKey, pub: Point, point: Point) => void), retrieveCachedSharedSecret?: ((priv: PrivateKey, pub: Point) => (Point | undefined))): PrivateKey;
/**
* Splits the private key into shares using Shamir's Secret Sharing Scheme.
*
* @param threshold The minimum number of shares required to reconstruct the private key.
* @param totalShares The total number of shares to generate.
* @param prime The prime number to be used in Shamir's Secret Sharing Scheme.
* @returns An array of shares.
*
* @example
* const key = PrivateKey.fromRandom()
* const shares = key.toKeyShares(2, 5)
*/
toKeyShares(threshold: number, totalShares: number): KeyShares;
/**
* @method toBackupShares
*
* Creates a backup of the private key by splitting it into shares.
*
*
* @param threshold The number of shares which will be required to reconstruct the private key.
* @param totalShares The number of shares to generate for distribution.
* @returns
*/
toBackupShares(threshold: number, totalShares: number): string[];
/**
*
* @method fromBackupShares
*
* Creates a private key from backup shares.
*
* @param shares
* @returns PrivateKey
*
* @example
*
* const share1 = '3znuzt7DZp8HzZTfTh5MF9YQKNX3oSxTbSYmSRGrH2ev.2Nm17qoocmoAhBTCs8TEBxNXCskV9N41rB2PckcgYeqV.2.35449bb9'
* const share2 = 'Cm5fuUc39X5xgdedao8Pr1kvCSm8Gk7Cfenc7xUKcfLX.2juyK9BxCWn2DiY5JUAgj9NsQ77cc9bWksFyW45haXZm.2.35449bb9'
*
* const recoveredKey = PrivateKey.fromBackupShares([share1, share2])
*/
static fromBackupShares(shares: string[]): PrivateKey;
/**
* Combines shares to reconstruct the private key.
*
* @param shares An array of points (shares) to be used to reconstruct the private key.
* @param threshold The minimum number of shares required to reconstruct the private key.
*
* @returns The reconstructed private key.
*
**/
static fromKeyShares(keyShares: KeyShares): PrivateKey;
}
//# sourceMappingURL=PrivateKey.d.ts.map