@scure/sr25519/index.d.ts

Audited & minimal implementation of sr25519 (polkadot) cryptography, with Merlin and Strobe

import { ristretto255 } from '@noble/curves/ed25519.js';
import { type TArg, type TRet } from '@noble/hashes/utils.js';
type Point = typeof ristretto255.Point.BASE;
type Data = string | Uint8Array;
declare class Strobe128 {
    state: Uint8Array;
    state32: Uint32Array;
    pos: number;
    posBegin: number;
    curFlags: number;
    constructor(protocolLabel: Data);
    private keccakF1600;
    private runF;
    private absorb;
    private squeeze;
    private overwrite;
    private beginOp;
    metaAD(data: Data, more: boolean): void;
    AD(data: Data, more: boolean): void;
    PRF(len: number, more: boolean): Uint8Array;
    KEY(data: Data, more: boolean): void;
    clone(): Strobe128;
    clean(): void;
}
declare class Merlin {
    strobe: Strobe128;
    constructor(label: Data);
    appendMessage(label: Data, message: Data): void;
    challengeBytes(label: Data, len: number): Uint8Array;
    clean(): void;
}
declare class SigningContext extends Merlin {
    constructor(name: string);
    label(label: Data): void;
    bytes(bytes: Uint8Array): this;
    protoName(label: Data): void;
    commitPoint(label: Data, point: Point): void;
    challengeScalar(label: Data): bigint;
    witnessScalar(label: Data, random: Uint8Array, nonceSeeds?: Uint8Array[]): bigint;
    witnessBytes(label: Data, len: number, random: Uint8Array, nonceSeeds?: Uint8Array[]): Uint8Array;
}
/**
 * Derives the public key for an sr25519 secret key.
 * @param secretKey - 64-byte secret key returned by `secretFromSeed()`
 * @returns 32-byte sr25519 public key
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Derive the public key bytes for a freshly expanded sr25519 secret key.
 * ```ts
 * import { getPublicKey, secretFromSeed } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const secretKey = secretFromSeed(randomBytes(32));
 * getPublicKey(secretKey);
 * ```
 */
export declare function getPublicKey(secretKey: TArg<Uint8Array>): TRet<Uint8Array>;
/**
 * Expands a 32-byte seed into a 64-byte sr25519 secret key.
 * @param seed - 32-byte seed
 * @returns 64-byte secret key
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Turn seed material into the sr25519 secret-key format used by the rest of the API.
 * ```ts
 * import { secretFromSeed } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * secretFromSeed(randomBytes(32));
 * ```
 */
export declare function secretFromSeed(seed: TArg<Uint8Array>): TRet<Uint8Array>;
/**
 * Converts a schnorrkel-style 96-byte keypair into the sr25519 key format used by this package.
 * @param pair - 96-byte keypair in schnorrkel
 * `to_half_ed25519_bytes()` layout: `secret.to_ed25519_bytes() || public.to_bytes()`
 * @returns 96-byte normalized keypair
 * @throws If the embedded public key does not match the secret key material. {@link Error}
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Normalize a compatible 96-byte keypair assembled from this package's secret/public key outputs.
 * ```ts
 * import { fromKeypair, getPublicKey, secretFromSeed } from '@scure/sr25519';
 * import { concatBytes, randomBytes } from '@noble/hashes/utils.js';
 * // Build the package's 64-byte secret format: scalar || nonce.
 * const secretKey = secretFromSeed(randomBytes(32));
 * // Assemble the 96-byte pair accepted by fromKeypair(): secret || pub.
 * const pair = concatBytes(secretKey, getPublicKey(secretKey));
 * // Re-encode and validate the pair before passing it to other APIs.
 * const normalized = fromKeypair(pair);
 * // Reuse the normalized 64-byte secret half with package APIs.
 * const publicKey = getPublicKey(normalized.subarray(0, 64));
 * ```
 */
export declare function fromKeypair(pair: TArg<Uint8Array>): TRet<Uint8Array>;
/**
 * Signs a message with sr25519.
 * @param secretKey - 64-byte secret key returned by `secretFromSeed()`
 * @param message - message bytes to sign
 * @param random - optional 32-byte nonce seed
 * @returns 64-byte signature
 * @throws On malformed sr25519 key or point data during signing. {@link Error}
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Sign a message with sr25519, using built-in nonce generation.
 * ```ts
 * import { secretFromSeed, sign } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const secretKey = secretFromSeed(randomBytes(32));
 * sign(secretKey, new Uint8Array([1, 2, 3]));
 * ```
 */
export declare function sign(secretKey: TArg<Uint8Array>, message: TArg<Uint8Array>, random?: TArg<Uint8Array>): TRet<Uint8Array>;
/**
 * Verifies an sr25519 signature.
 * @param message - message bytes that were signed
 * @param signature - 64-byte signature returned by `sign()`
 * @param publicKey - 32-byte public key returned by `getPublicKey()`
 * @returns `true` when the signature is valid
 * @throws If the signature marker or decoded sr25519 point data is invalid. {@link Error}
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Verify the signature against the same message and derived public key.
 * ```ts
 * import { getPublicKey, secretFromSeed, sign, verify } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const secretKey = secretFromSeed(randomBytes(32));
 * const message = new Uint8Array([1, 2, 3]);
 * const signature = sign(secretKey, message);
 * verify(message, signature, getPublicKey(secretKey));
 * ```
 */
export declare function verify(message: TArg<Uint8Array>, signature: TArg<Uint8Array>, publicKey: TArg<Uint8Array>): boolean;
/**
 * Computes an sr25519 shared secret.
 * @param secretKey - 64-byte secret key returned by `secretFromSeed()`
 * @param publicKey - peer 32-byte public key
 * @returns 32-byte shared secret
 * @throws If the peer public key is invalid or encodes the identity point. {@link Error}
 * @throws On wrong argument types. {@link TypeError}
 * @throws On wrong argument lengths. {@link RangeError}
 * @example
 * Compute the shared secret from one party's secret key and the other party's public key.
 * ```ts
 * import { getPublicKey, getSharedSecret, secretFromSeed } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const alice = secretFromSeed(randomBytes(32));
 * const bob = secretFromSeed(randomBytes(32));
 * getSharedSecret(alice, getPublicKey(bob));
 * ```
 */
export declare function getSharedSecret(secretKey: TArg<Uint8Array>, publicKey: TArg<Uint8Array>): TRet<Uint8Array>;
/**
 * Hierarchical deterministic key derivation helpers for sr25519.
 * @example
 * Derive a hardened child secret using a random 32-byte chain code.
 * ```ts
 * import { HDKD, secretFromSeed } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const secretKey = secretFromSeed(randomBytes(32));
 * HDKD.secretHard(secretKey, randomBytes(32));
 * ```
 */
export declare const HDKD: TRet<{
    secretSoft(secretKey: Uint8Array, chainCode: Uint8Array, random?: Uint8Array): Uint8Array;
    publicSoft(publicKey: Uint8Array, chainCode: Uint8Array): Uint8Array;
    secretHard(secretKey: Uint8Array, chainCode: Uint8Array): Uint8Array;
}>;
type VRF = {
    sign(msg: Uint8Array, secretKey: Uint8Array, ctx: Uint8Array, extra: Uint8Array, random?: Uint8Array): Uint8Array;
    verify(msg: Uint8Array, signature: Uint8Array, publicKey: Uint8Array, ctx?: Uint8Array, extra?: Uint8Array): boolean;
};
/**
 * Verifiable random function helpers built on sr25519.
 * @example
 * Generate and verify a VRF proof for the message.
 * ```ts
 * import { getPublicKey, secretFromSeed, vrf } from '@scure/sr25519';
 * import { randomBytes } from '@noble/hashes/utils.js';
 * const secretKey = secretFromSeed(randomBytes(32));
 * const msg = new Uint8Array([1, 2, 3]);
 * const sig = vrf.sign(msg, secretKey);
 * vrf.verify(msg, sig, getPublicKey(secretKey));
 * ```
 */
export declare const vrf: TRet<VRF>;
export declare const __tests: {
    Strobe128: typeof Strobe128;
    Merlin: typeof Merlin;
    SigningContext: typeof SigningContext;
};
export {};
//# sourceMappingURL=index.d.ts.map