UNPKG

ox

Version:

Ethereum Standard Library

662 lines 22 kB
import * as Bytes from './Bytes.js'; import * as Errors from './Errors.js'; import * as Hex from './Hex.js'; import type { Compute, ExactPartial, OneOf } from './internal/types.js'; /** Root type for an ECDSA signature. */ export type Signature<recovered extends boolean = true, numberType = number> = Compute<recovered extends true ? { r: Hex.Hex; s: Hex.Hex; yParity: numberType; } : { r: Hex.Hex; s: Hex.Hex; yParity?: numberType | undefined; }>; /** RPC-formatted ECDSA signature. `yParity` is hex-encoded. */ export type Rpc<recovered extends boolean = true> = Signature<recovered, Hex.Hex>; /** (Legacy) ECDSA signature. */ export type Legacy<numberType = number> = { r: Hex.Hex; s: Hex.Hex; v: numberType; }; /** RPC-formatted (Legacy) ECDSA signature. */ export type LegacyRpc = Legacy<Hex.Hex>; export type Tuple = readonly [yParity: Hex.Hex, r: Hex.Hex, s: Hex.Hex]; /** * Asserts that a Signature is valid. * * @example * ```ts twoslash * // @errors: 2322 * import { Signature } from 'ox' * * Signature.assert({ * r: '-0x6e1c1f59ee1cf25b75a8d57b3c89e7e6b3b1da823df8b3b89497f30c1f000000', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @error: InvalidSignatureRError: * // @error: Value `-0x...` is an invalid r value. * // @error: r must be a positive integer less than 2^256. * ``` * * @param signature - The signature object to assert. */ export declare function assert(signature: ExactPartial<Signature>, options?: assert.Options): asserts signature is Signature; export declare namespace assert { type Options = { /** Whether or not the signature should be recovered (contain `yParity`). */ recovered?: boolean; }; type ErrorType = MissingPropertiesError | InvalidRError | InvalidSError | InvalidYParityError | Errors.GlobalErrorType; } /** * Deserializes a {@link ox#Bytes.Bytes} signature into a structured {@link ox#Signature.Signature}. * * @example * ```ts twoslash * // @noErrors * import { Signature } from 'ox' * * Signature.fromBytes(new Uint8Array([128, 3, 131, ...])) * // @log: { r: '0x6e10...', s: '0x4a90...', yParity: 0 } * ``` * * @param signature - The serialized signature. * @returns The deserialized {@link ox#Signature.Signature}. */ export declare function fromBytes(signature: Bytes.Bytes): Signature; export declare namespace fromBytes { type ErrorType = Errors.GlobalErrorType; } /** * Deserializes a {@link ox#Hex.Hex} signature into a structured {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * Signature.fromHex( * '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db81c' * ) * // @log: { r: '0x6e10...', s: '0x4a90...', yParity: 0 } * ``` * * @param serialized - The serialized signature. * @returns The deserialized {@link ox#Signature.Signature}. */ export declare function fromHex(signature: Hex.Hex): Signature; export declare namespace fromHex { type ErrorType = Hex.from.ErrorType | InvalidSerializedSizeError | Errors.GlobalErrorType; } /** * Extracts a {@link ox#Signature.Signature} from an arbitrary object that may include signature properties. * * @example * ```ts twoslash * // @noErrors * import { Signature } from 'ox' * * Signature.extract({ * baz: 'barry', * foo: 'bar', * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1, * zebra: 'stripes' * }) * // @log: { * // @log: r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * // @log: s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * // @log: yParity: 1 * // @log: } * ``` * * @param value - The arbitrary object to extract the signature from. * @returns The extracted {@link ox#Signature.Signature}. */ export declare function extract(value: extract.Value): Signature | undefined; export declare namespace extract { type Value = { r?: Hex.Hex | undefined; s?: Hex.Hex | undefined; yParity?: number | Hex.Hex | undefined; v?: number | Hex.Hex | undefined; }; type ErrorType = Errors.GlobalErrorType; } /** * Instantiates a typed {@link ox#Signature.Signature} object from a {@link ox#Signature.Signature}, {@link ox#Signature.Legacy}, {@link ox#Bytes.Bytes}, or {@link ox#Hex.Hex}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * Signature.from({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: { * // @log: r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * // @log: s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * // @log: yParity: 1 * // @log: } * ``` * * @example * ### From Serialized * * ```ts twoslash * import { Signature } from 'ox' * * Signature.from( * '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db801' * ) * // @log: { * // @log: r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * // @log: s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * // @log: yParity: 1, * // @log: } * ``` * * @example * ### From Legacy * * ```ts twoslash * import { Signature } from 'ox' * * Signature.from({ * r: '0x68a020a21f5d20c5cf6c9b4d2dccdcdd14a9f7b9c2eb19d3d3acdb2a1a9c1f50', * s: '0x7e8d44a4a8a3e3a4c6a3c1a3c3a3c1a3c1a3c1a3c1a3c1a3c1a3c1a3c1a3c1a4', * v: 27 * }) * // @log: { * // @log: r: '0x68a020a21f5d20c5cf6c9b4d2dccdcdd14a9f7b9c2eb19d3d3acdb2a1a9c1f50', * // @log: s: '0x7e8d44a4a8a3e3a4c6a3c1a3c3a3c1a3c1a3c1a3c1a3c1a3c1a3c1a3c1a3c1a4', * // @log: yParity: 0 * // @log: } * ``` * * @param signature - The signature value to instantiate. * @returns The instantiated {@link ox#Signature.Signature}. */ export declare function from<const signature extends OneOf<Signature<boolean> | Rpc<boolean> | Legacy | LegacyRpc> | Hex.Hex | Bytes.Bytes>(signature: signature | OneOf<Signature<boolean> | Rpc<boolean> | Legacy | LegacyRpc> | Hex.Hex | Bytes.Bytes): from.ReturnType<signature>; export declare namespace from { type ReturnType<signature extends OneOf<Signature<boolean> | Rpc<boolean> | Legacy | LegacyRpc> | Hex.Hex | Bytes.Bytes> = signature extends Signature<boolean> & { v?: undefined; } ? signature : Signature; type ErrorType = assert.ErrorType | fromBytes.ErrorType | fromHex.ErrorType | vToYParity.ErrorType | Errors.GlobalErrorType; } /** * Converts a DER-encoded signature to a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * // @noErrors * import { Signature } from 'ox' * * const signature = Signature.fromDerBytes(new Uint8Array([132, 51, 23, ...])) * // @log: { * // @log: r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * // @log: s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * // @log: } * ``` * * @param signature - The DER-encoded signature to convert. * @returns The {@link ox#Signature.Signature}. */ export declare function fromDerBytes(signature: Bytes.Bytes): Signature<false>; export declare namespace fromDerBytes { type ErrorType = Errors.GlobalErrorType; } /** * Converts a DER-encoded signature to a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.fromDerHex( * '0x304402206e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf02204a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8' * ) * // @log: { * // @log: r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * // @log: s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * // @log: } * ``` * * @param signature - The DER-encoded signature to convert. * @returns The {@link ox#Signature.Signature}. */ export declare function fromDerHex(signature: Hex.Hex): Signature<false>; export declare namespace fromDerHex { type ErrorType = Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Legacy} into a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const legacy = Signature.fromLegacy({ * r: '0x01', * s: '0x02', * v: 28 * }) * // @log: { r: '0x01', s: '0x02', yParity: 1 } * ``` * * @param signature - The {@link ox#Signature.Legacy} to convert. * @returns The converted {@link ox#Signature.Signature}. */ export declare function fromLegacy(signature: Legacy | LegacyRpc): Signature; export declare namespace fromLegacy { type ErrorType = vToYParity.ErrorType | Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Rpc} into a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.fromRpc({ * r: '0x635dc2033e60185bb36709c29c75d64ea51dfbd91c32ef4be198e4ceb169fb4d', * s: '0x50c2667ac4c771072746acfdcf1f1483336dcca8bd2df47cd83175dbe60f0540', * yParity: '0x0' * }) * ``` * * @param signature - The {@link ox#Signature.Rpc} to convert. * @returns The converted {@link ox#Signature.Signature}. */ export declare function fromRpc(signature: { r: Hex.Hex; s: Hex.Hex; yParity?: Hex.Hex | undefined; v?: Hex.Hex | undefined; }): Signature; export declare namespace fromRpc { type ErrorType = Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Tuple} to a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.fromTuple([ * '0x01', * '0x7b', * '0x1c8' * ]) * // @log: { * // @log: r: '0x000000000000000000000000000000000000000000000000000000000000007b', * // @log: s: '0x00000000000000000000000000000000000000000000000000000000000001c8', * // @log: yParity: 1, * // @log: } * ``` * * @param tuple - The {@link ox#Signature.Tuple} to convert. * @returns The {@link ox#Signature.Signature}. */ export declare function fromTuple(tuple: Tuple): Signature; export declare namespace fromTuple { type ErrorType = assert.ErrorType | Errors.GlobalErrorType; } /** * Serializes a {@link ox#Signature.Signature} to {@link ox#Bytes.Bytes}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.toBytes({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: Uint8Array [102, 16, 10, ...] * ``` * * @param signature - The signature to serialize. * @returns The serialized signature. */ export declare function toBytes(signature: Signature<boolean>): Bytes.Bytes; export declare namespace toBytes { type ErrorType = toHex.ErrorType | Bytes.fromHex.ErrorType | Errors.GlobalErrorType; } /** * Encodes a {@link ox#Signature.Signature} as a 64-byte compact byte * representation (`r ++ s`, big-endian, 32 bytes each). * * Used for signature inputs that omit the recovery byte (e.g. ECDSA verify). * * @example * ```ts twoslash * import { Signature } from 'ox' * * const bytes = Signature.toCompactBytes({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: Uint8Array [110, 16, 10, ...] // 64 bytes * ``` * * @param signature - The signature to encode. * @returns The 64-byte compact representation. */ export declare function toCompactBytes(signature: Signature<boolean>): Bytes.Bytes; export declare namespace toCompactBytes { type ErrorType = Bytes.fromHex.ErrorType | Errors.GlobalErrorType; } /** * Decodes a 64-byte compact byte representation (`r ++ s`, big-endian) into a * {@link ox#Signature.Signature} (without recovery). * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.fromCompactBytes( * new Uint8Array(64) * ) * // @log: { r: '0x00...0000', s: '0x00...0000' } * ``` * * @param bytes - The 64-byte compact representation. * @returns The decoded {@link ox#Signature.Signature}. */ export declare function fromCompactBytes(bytes: Bytes.Bytes): Signature<false>; export declare namespace fromCompactBytes { type ErrorType = Hex.fromBytes.ErrorType | Errors.GlobalErrorType; } /** * Encodes a {@link ox#Signature.Signature} as a 65-byte recovered byte * representation (`yParity ++ r ++ s`, big-endian). * * @example * ```ts twoslash * import { Signature } from 'ox' * * const bytes = Signature.toRecoveredBytes({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: Uint8Array [1, 110, 16, ...] // 65 bytes * ``` * * @param signature - The signature to encode. * @returns The 65-byte recovered representation. */ export declare function toRecoveredBytes(signature: Signature): Bytes.Bytes; export declare namespace toRecoveredBytes { type ErrorType = Bytes.fromNumber.ErrorType | Errors.GlobalErrorType; } /** * Decodes a 65-byte recovered byte representation (`yParity ++ r ++ s`, * big-endian) into a {@link ox#Signature.Signature}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.fromRecoveredBytes( * new Uint8Array(65) * ) * // @log: { r: '0x00...0000', s: '0x00...0000', yParity: 0 } * ``` * * @param bytes - The 65-byte recovered representation. * @returns The decoded {@link ox#Signature.Signature}. */ export declare function fromRecoveredBytes(bytes: Bytes.Bytes): Signature; export declare namespace fromRecoveredBytes { type ErrorType = Hex.fromBytes.ErrorType | Errors.GlobalErrorType; } /** * Serializes a {@link ox#Signature.Signature} to {@link ox#Hex.Hex}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.toHex({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db81c' * ``` * * @param signature - The signature to serialize. * @returns The serialized signature. */ export declare function toHex(signature: Signature<boolean>): Hex.Hex; export declare namespace toHex { type ErrorType = Hex.concat.ErrorType | Hex.fromNumber.ErrorType | Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Signature} to DER-encoded format. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.from({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8' * }) * * const signature_der = Signature.toDerBytes(signature) * // @log: Uint8Array [132, 51, 23, ...] * ``` * * @param signature - The signature to convert. * @returns The DER-encoded signature. */ export declare function toDerBytes(signature: Signature<boolean>): Bytes.Bytes; export declare namespace toDerBytes { type ErrorType = Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Signature} to DER-encoded format. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.from({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8' * }) * * const signature_der = Signature.toDerHex(signature) * // @log: '0x304402206e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf02204a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8' * ``` * * @param signature - The signature to convert. * @returns The DER-encoded signature. */ export declare function toDerHex(signature: Signature<boolean>): Hex.Hex; export declare namespace toDerHex { type ErrorType = Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Signature} into a {@link ox#Signature.Legacy}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const legacy = Signature.toLegacy({ * r: '0x01', * s: '0x02', * yParity: 1 * }) * // @log: { r: '0x01', s: '0x02', v: 28 } * ``` * * @param signature - The {@link ox#Signature.Signature} to convert. * @returns The converted {@link ox#Signature.Legacy}. */ export declare function toLegacy(signature: Signature): Legacy; export declare namespace toLegacy { type ErrorType = yParityToV.ErrorType | Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Signature} into a {@link ox#Signature.Rpc}. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signature = Signature.toRpc({ * r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * ``` * * @param signature - The {@link ox#Signature.Signature} to convert. * @returns The converted {@link ox#Signature.Rpc}. */ export declare function toRpc(signature: toRpc.Input): Rpc; export declare namespace toRpc { /** Numberish input accepted by {@link ox#Signature.(toRpc:function)}. */ type Input = Signature<true, Hex.Hex | number>; type ErrorType = Errors.GlobalErrorType; } /** * Converts a {@link ox#Signature.Signature} to a serialized {@link ox#Signature.Tuple} to be used for signatures in Transaction Envelopes, EIP-7702 Authorization Lists, etc. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const signatureTuple = Signature.toTuple({ * r: '0x000000000000000000000000000000000000000000000000000000000000007b', * s: '0x00000000000000000000000000000000000000000000000000000000000001c8', * yParity: 1 * }) * // @log: [yParity: '0x01', r: '0x7b', s: '0x1c8'] * ``` * * @param signature - The {@link ox#Signature.Signature} to convert. * @returns The {@link ox#Signature.Tuple}. */ export declare function toTuple(signature: Signature): Tuple; export declare namespace toTuple { type ErrorType = Errors.GlobalErrorType; } /** * Validates a Signature. Returns `true` if the signature is valid, `false` otherwise. * * @example * ```ts twoslash * // @errors: 2322 * import { Signature } from 'ox' * * const valid = Signature.validate({ * r: '-0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf', * s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8', * yParity: 1 * }) * // @log: false * ``` * * @param signature - The signature object to assert. */ export declare function validate(signature: ExactPartial<Signature>, options?: validate.Options): boolean; export declare namespace validate { type Options = { /** Whether or not the signature should be recovered (contain `yParity`). */ recovered?: boolean; }; type ErrorType = Errors.GlobalErrorType; } /** * Converts a ECDSA `v` value to a `yParity` value. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const yParity = Signature.vToYParity(28) * // @log: 1 * ``` * * @param v - The ECDSA `v` value to convert. * @returns The `yParity` value. */ export declare function vToYParity(v: number): Signature['yParity']; export declare namespace vToYParity { type ErrorType = InvalidVError | Errors.GlobalErrorType; } /** * Converts a ECDSA `v` value to a `yParity` value. * * @example * ```ts twoslash * import { Signature } from 'ox' * * const v = Signature.yParityToV(1) * // @log: 28 * ``` * * @param yParity - The ECDSA `yParity` value to convert. * @returns The `v` value. */ export declare function yParityToV(yParity: number): number; export declare namespace yParityToV { type ErrorType = InvalidVError | Errors.GlobalErrorType; } /** Thrown when the serialized signature is of an invalid size. */ export declare class InvalidSerializedSizeError extends Errors.BaseError { readonly name = "Signature.InvalidSerializedSizeError"; constructor({ signature }: { signature: Hex.Hex | Bytes.Bytes; }); } /** Thrown when the signature is missing either an `r`, `s`, or `yParity` property. */ export declare class MissingPropertiesError extends Errors.BaseError { readonly name = "Signature.MissingPropertiesError"; constructor({ signature }: { signature: unknown; }); } /** Thrown when the signature has an invalid `r` value. */ export declare class InvalidRError extends Errors.BaseError { readonly name = "Signature.InvalidRError"; constructor({ value }: { value: unknown; }); } /** Thrown when the signature has an invalid `s` value. */ export declare class InvalidSError extends Errors.BaseError { readonly name = "Signature.InvalidSError"; constructor({ value }: { value: unknown; }); } /** Thrown when the signature has an invalid `yParity` value. */ export declare class InvalidYParityError extends Errors.BaseError { readonly name = "Signature.InvalidYParityError"; constructor({ value }: { value: unknown; }); } /** Thrown when the signature has an invalid `v` value. */ export declare class InvalidVError extends Errors.BaseError { readonly name = "Signature.InvalidVError"; constructor({ value }: { value: number; }); } //# sourceMappingURL=Signature.d.ts.map