​

primitives/Signature

​

Classes

​

InvalidAlgorithmError

​

Example

throw new InvalidAlgorithmError(
  'DER encoding only supported for ECDSA signatures',
  {
    value: algorithm,
    expected: 'secp256k1 or p256',
    code: 'SIGNATURE_INVALID_ALGORITHM',
    docsPath: '/primitives/signature/to-der#error-handling'
  }
)

​

Extends

• InvalidSignatureError

​

Constructors

Constructor

new InvalidAlgorithmError(message, options?): InvalidAlgorithmError

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​

Properties

cause?

optional cause: Error

Inherited from

code

code: string

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

context?

optional context: Record<string, unknown>

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

docsPath?

optional docsPath: string

Example

'/primitives/address/from-hex#error-handling'

Inherited from

name

name: string

Inherited from

​

Methods

getErrorChain()

getErrorChain(): string

Returns

Inherited from

toJSON()

toJSON(): Record<string, unknown>

Returns

Inherited from

​

InvalidDERError

​

Example

throw new InvalidDERError(
  'Expected SEQUENCE tag (0x30)',
  {
    value: tag,
    expected: '0x30',
    code: 'SIGNATURE_INVALID_DER',
    docsPath: '/primitives/signature/from-der#error-handling'
  }
)

​

Extends

• InvalidFormatError

​

Constructors

Constructor

new InvalidDERError(message, options?): InvalidDERError

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​

Properties

cause?

optional cause: Error

Inherited from

code

code: string

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

context?

optional context: Record<string, unknown>

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

docsPath?

optional docsPath: string

Example

'/primitives/address/from-hex#error-handling'

Inherited from

expected

expected: string

Inherited from

name

name: string

Inherited from

value

value: unknown

Inherited from

​

Methods

getErrorChain()

getErrorChain(): string

Returns

Inherited from

toJSON()

toJSON(): Record<string, unknown>

Returns

Inherited from

​

InvalidSignatureFormatError

​

Example

throw new InvalidSignatureFormatError(
  'Unsupported signature value type',
  {
    value: typeof input,
    expected: 'Uint8Array or signature object',
    code: 'SIGNATURE_INVALID_FORMAT',
    docsPath: '/primitives/signature/from#error-handling'
  }
)

​

Extends

• InvalidFormatError

​

Constructors

Constructor

new InvalidSignatureFormatError(message, options?): InvalidSignatureFormatError

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​

Properties

cause?

optional cause: Error

Inherited from

code

code: string

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

context?

optional context: Record<string, unknown>

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

docsPath?

optional docsPath: string

Example

'/primitives/address/from-hex#error-handling'

Inherited from

expected

expected: string

Inherited from

name

name: string

Inherited from

value

value: unknown

Inherited from

​

Methods

getErrorChain()

getErrorChain(): string

Returns

Inherited from

toJSON()

toJSON(): Record<string, unknown>

Returns

Inherited from

​

InvalidSignatureLengthError

​

Example

throw new InvalidSignatureLengthError(
  'Compact signature must be 64 bytes',
  {
    value: sig.length,
    expected: '64 bytes',
    code: 'SIGNATURE_INVALID_LENGTH',
    docsPath: '/primitives/signature/from-compact#error-handling'
  }
)

​

Extends

• InvalidLengthError

​

Constructors

Constructor

new InvalidSignatureLengthError(message, options?): InvalidSignatureLengthError

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​

Properties

cause?

optional cause: Error

Inherited from

code

code: string

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

context?

optional context: Record<string, unknown>

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

docsPath?

optional docsPath: string

Example

'/primitives/address/from-hex#error-handling'

Inherited from

expected

expected: string

Inherited from

name

name: string

Inherited from

value

value: unknown

Inherited from

​

Methods

getErrorChain()

getErrorChain(): string

Returns

Inherited from

toJSON()

toJSON(): Record<string, unknown>

Returns

Inherited from

​

NonCanonicalSignatureError

​

Example

throw new NonCanonicalSignatureError(
  's value is not in canonical form',
  {
    value: s,
    expected: 's < n/2',
    code: 'SIGNATURE_NON_CANONICAL',
    docsPath: '/primitives/signature/canonical#error-handling'
  }
)

​

Extends

• InvalidSignatureError

​

Constructors

Constructor

new NonCanonicalSignatureError(message, options?): NonCanonicalSignatureError

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​

Properties

cause?

optional cause: Error

Inherited from

code

code: string

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

context?

optional context: Record<string, unknown>

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

docsPath?

optional docsPath: string

Example

'/primitives/address/from-hex#error-handling'

Inherited from

name

name: string

Inherited from

​

Methods

getErrorChain()

getErrorChain(): string

Returns

Inherited from

toJSON()

toJSON(): Record<string, unknown>

Returns

Inherited from

​

Type Aliases

​

SignatureAlgorithm

SignatureAlgorithm = "secp256k1" | "p256" | "ed25519"

​

SignatureType

SignatureType = Uint8Array & object

• For ECDSA (secp256k1, p256): r (32 bytes) + s (32 bytes) + optional v (1 byte for secp256k1)
• For Ed25519: signature (64 bytes)

​

Type Declaration

[brand]

readonly [brand]: "Signature"

algorithm

readonly algorithm: SignatureAlgorithm

v?

readonly optional v: number

​

Variables

​

COMPONENT_SIZE

const COMPONENT_SIZE: 32 = 32

​

ECDSA_SIZE

const ECDSA_SIZE: 64 = 64

​

ECDSA_WITH_V_SIZE

const ECDSA_WITH_V_SIZE: 65 = 65

​

ED25519_SIZE

const ED25519_SIZE: 64 = 64

​

RECOVERY_ID_MAX

const RECOVERY_ID_MAX: 28 = 28

​

RECOVERY_ID_MIN

const RECOVERY_ID_MIN: 27 = 27

​

Signature

const Signature: object

​

Type Declaration

equals()

equals: (a, b) => boolean

Parameters

a

b

Returns

Example

const isEqual = Signature.equals(sig1, sig2);

from()

from: (value) => SignatureType

Parameters

value

Returns

Throws

Throws

Example

// From compact bytes (64 bytes, defaults to secp256k1)
const sig1 = Signature.from(bytes64);

// From object with r, s, v
const sig2 = Signature.from({ r, s, v: 27, algorithm: 'secp256k1' });

// From Ed25519
const sig3 = Signature.from({ signature: bytes64, algorithm: 'ed25519' });

fromBytes()

fromBytes: (bytes, algorithmOrV?) => SignatureType

• 64 bytes: ECDSA r+s (with optional EIP-2098 yParity in bit 255) or Ed25519 signature
• 65 bytes: ECDSA r+s+v (secp256k1 only)

Parameters

bytes

algorithmOrV?

Returns

Throws

Example

// 64 bytes - defaults to secp256k1
const sig1 = Signature.fromBytes(bytes64);

// 65 bytes with v
const sig2 = Signature.fromBytes(bytes65);

// Explicit algorithm
const sig3 = Signature.fromBytes(bytes64, 'ed25519');

// Explicit v value (overrides EIP-2098 encoding)
const sig4 = Signature.fromBytes(bytes64, 0);

fromCompact()

fromCompact: (bytes, algorithmOrV) => SignatureType

Parameters

bytes

algorithmOrV

Returns

Throws

Example

// EIP-2098: Extract yParity from bit 255 of s (64 bytes)
const sig1 = Signature.fromCompact(bytes64, 'secp256k1');

// Explicit v value (64 bytes)
const sig2 = Signature.fromCompact(bytes64, 0);

// Legacy: 65 bytes with v at end
const sig3 = Signature.fromCompact(bytes65, 'secp256k1');

// Ed25519 (64 bytes)
const sig4 = Signature.fromCompact(bytes64, 'ed25519');

fromDER()

fromDER: (der, algorithm, v?) => SignatureType

Parameters

der

algorithm

v?

Returns

Throws

Example

const sig = Signature.fromDER(derBytes, 'secp256k1', 27);

fromEd25519()

fromEd25519: (signature) => SignatureType

Parameters

signature

Returns

Throws

Example

const sig = Signature.fromEd25519(signature);

fromHex()

fromHex: (value, algorithm?) => SignatureType

• 128 hex chars (64 bytes): ECDSA r+s or Ed25519 signature
• 130 hex chars (65 bytes): ECDSA r+s+v

Parameters

value

algorithm?

Returns

Throws

Throws

Example

// 128 hex chars (64 bytes) - defaults to secp256k1
const sig1 = Signature.fromHex("0x1234...");

// 130 hex chars (65 bytes) - includes v
const sig2 = Signature.fromHex("0x1234...ab");

// Ed25519 (128 hex chars)
const sig3 = Signature.fromHex("0x1234...", "ed25519");

// P256 (128 hex chars)
const sig4 = Signature.fromHex("0x1234...", "p256");

fromP256()

fromP256: (r, s) => SignatureType

Parameters

r

s

Returns

Example

const sig = Signature.fromP256(rBytes, sBytes);

fromRpc()

fromRpc: (rpc) => SignatureType

Parameters

rpc

r

s

v?

yParity?

Returns

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromRpc({
  r: '0x...',
  s: '0x...',
  yParity: '0x0'
});

fromSecp256k1()

fromSecp256k1: (r, s, v?) => SignatureType

Parameters

r

s

v?

Returns

Example

const sig = Signature.fromSecp256k1(rBytes, sBytes, 27);

fromTuple()

fromTuple: (tuple, chainId?) => SignatureType

Parameters

tuple

chainId?

Returns

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromTuple([0, r, s]);
// With chain ID for EIP-155
const sig155 = Signature.fromTuple([0, r, s], 1);

getAlgorithm()

getAlgorithm: (signature) => SignatureAlgorithm

Parameters

signature

Returns

Example

const algorithm = Signature.getAlgorithm(sig);
// "secp256k1" | "p256" | "ed25519"

getR()

getR: (signature) => HashType

Parameters

signature

Returns

Throws

Example

const r = Signature.getR(sig);

getS()

getS: (signature) => HashType

Parameters

signature

Returns

Throws

Example

const s = Signature.getS(sig);

getV()

getV: (signature) => number | undefined

Parameters

signature

Returns

Throws

Example

const v = Signature.getV(sig);

is()

is: (value) => value is SignatureType

Parameters

value

Returns

Example

if (Signature.is(value)) {
  console.log(value.algorithm);
}

isCanonical()

isCanonical: (signature) => boolean

Parameters

signature

Returns

Example

if (!Signature.isCanonical(sig)) {
  sig = Signature.normalize(sig);
}

normalize()

normalize: (signature) => SignatureType

Parameters

signature

Returns

Example

const normalized = Signature.normalize(sig);

toBytes()

toBytes: (signature) => Uint8Array<ArrayBufferLike>

Parameters

signature

Returns

Example

const bytes = Signature.toBytes(sig);
// Returns r + s (64 bytes) for ECDSA or signature (64 bytes) for Ed25519

toCompact()

toCompact: (signature) => Uint8Array<ArrayBufferLike>

Parameters

signature

Returns

Example

const compact = Signature.toCompact(sig);
// Returns r + s (64 bytes) with yParity encoded in bit 255 of s (EIP-2098)

toDER()

toDER: (signature) => Uint8Array<ArrayBufferLike>

Parameters

signature

Returns

Throws

Example

const der = Signature.toDER(sig);
// Returns DER-encoded SEQUENCE of r and s integers

toHex()

toHex: (signature, includeV?) => string

• ECDSA without v: 128 hex chars (64 bytes: r + s)
• ECDSA with v: 130 hex chars (65 bytes: r + s + v)
• Ed25519: 128 hex chars (64 bytes)

Parameters

signature

includeV?

Returns

Example

const hex = Signature.toHex(sig);
// Returns "0x..." (130 chars with v, 128 chars without)

// Exclude v even if present
const hexNoV = Signature.toHex(sig, false);
// Returns "0x..." (128 chars)

toRpc()

toRpc: (signature) => object

Parameters

signature

Returns

r

r: string

s

s: string

v?

optional v: string

yParity

yParity: string

Throws

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromSecp256k1(r, s, 27);
const rpc = Signature.toRpc(sig);
// { r: '0x...', s: '0x...', yParity: '0x0', v: '0x1b' }

toTuple()

toTuple: (signature) => [number, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>]

Parameters

signature

Returns

Throws

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromSecp256k1(r, s, 27);
const [yParity, r, s] = Signature.toTuple(sig);

verify()

verify: (signature, _message, _publicKey) => boolean

Parameters

signature

_message

_publicKey

Returns

Throws

Example

const isValid = Signature.verify(sig, message, publicKey);

​

Functions

​

equals()

equals(a, b): boolean

​

Parameters

a

b

​

Returns

​

Example

const isEqual = Signature.equals(sig1, sig2);

​

from()

from(value): SignatureType

​

Parameters

value

​

Returns

​

Throws

​

Throws

​

Example

// From compact bytes (64 bytes, defaults to secp256k1)
const sig1 = Signature.from(bytes64);

// From object with r, s, v
const sig2 = Signature.from({ r, s, v: 27, algorithm: 'secp256k1' });

// From Ed25519
const sig3 = Signature.from({ signature: bytes64, algorithm: 'ed25519' });

​

fromBytes()

fromBytes(bytes, algorithmOrV?): SignatureType

• 64 bytes: ECDSA r+s (with optional EIP-2098 yParity in bit 255) or Ed25519 signature
• 65 bytes: ECDSA r+s+v (secp256k1 only)

​

Parameters

bytes

algorithmOrV?

​

Returns

​

Throws

​

Example

// 64 bytes - defaults to secp256k1
const sig1 = Signature.fromBytes(bytes64);

// 65 bytes with v
const sig2 = Signature.fromBytes(bytes65);

// Explicit algorithm
const sig3 = Signature.fromBytes(bytes64, 'ed25519');

// Explicit v value (overrides EIP-2098 encoding)
const sig4 = Signature.fromBytes(bytes64, 0);

​

fromCompact()

fromCompact(bytes, algorithmOrV): SignatureType

​

Parameters

bytes

algorithmOrV

​

Returns

​

Throws

​

Example

// EIP-2098: Extract yParity from bit 255 of s (64 bytes)
const sig1 = Signature.fromCompact(bytes64, 'secp256k1');

// Explicit v value (64 bytes)
const sig2 = Signature.fromCompact(bytes64, 0);

// Legacy: 65 bytes with v at end
const sig3 = Signature.fromCompact(bytes65, 'secp256k1');

// Ed25519 (64 bytes)
const sig4 = Signature.fromCompact(bytes64, 'ed25519');

​

fromDER()

fromDER(der, algorithm, v?): SignatureType

​

Parameters

der

algorithm

v?

​

Returns

​

Throws

​

Example

const sig = Signature.fromDER(derBytes, 'secp256k1', 27);

​

fromEd25519()

fromEd25519(signature): SignatureType

​

Parameters

signature

​

Returns

​

Throws

​

Example

const sig = Signature.fromEd25519(signature);

​

fromHex()

fromHex(value, algorithm?): SignatureType

• 128 hex chars (64 bytes): ECDSA r+s or Ed25519 signature
• 130 hex chars (65 bytes): ECDSA r+s+v

​

Parameters

value

algorithm?

​

Returns

​

Throws

​

Throws

​

Example

// 128 hex chars (64 bytes) - defaults to secp256k1
const sig1 = Signature.fromHex("0x1234...");

// 130 hex chars (65 bytes) - includes v
const sig2 = Signature.fromHex("0x1234...ab");

// Ed25519 (128 hex chars)
const sig3 = Signature.fromHex("0x1234...", "ed25519");

// P256 (128 hex chars)
const sig4 = Signature.fromHex("0x1234...", "p256");

​

fromP256()

fromP256(r, s): SignatureType

​

Parameters

r

s

​

Returns

​

Example

const sig = Signature.fromP256(rBytes, sBytes);

​

fromRpc()

fromRpc(rpc): SignatureType

​

Parameters

rpc

r

s

v?

yParity?

​

Returns

​

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromRpc({
  r: '0x...',
  s: '0x...',
  yParity: '0x0'
});

​

fromSecp256k1()

fromSecp256k1(r, s, v?): SignatureType

​

Parameters

r

s

v?

​

Returns

​

Example

const sig = Signature.fromSecp256k1(rBytes, sBytes, 27);

​

fromTuple()

fromTuple(tuple, chainId?): SignatureType

​

Parameters

tuple

chainId?

​

Returns

​

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromTuple([0, r, s]);
// With chain ID for EIP-155
const sig155 = Signature.fromTuple([0, r, s], 1);

​

getAlgorithm()

getAlgorithm(signature): SignatureAlgorithm

​

Parameters

signature

​

Returns

​

Example

const algorithm = Signature.getAlgorithm(sig);
// "secp256k1" | "p256" | "ed25519"

​

getR()

getR(signature): HashType

​

Parameters

signature

​

Returns

​

Throws

​

Example

const r = Signature.getR(sig);

​

getS()

getS(signature): HashType

​

Parameters

signature

​

Returns

​

Throws

​

Example

const s = Signature.getS(sig);

​

getV()

getV(signature): number | undefined

​

Parameters

signature

​

Returns

​

Throws

​

Example

const v = Signature.getV(sig);

​

is()

is(value): value is SignatureType

​

Parameters

value

​

Returns

​

Example

if (Signature.is(value)) {
  console.log(value.algorithm);
}

​

isCanonical()

isCanonical(signature): boolean

​

Parameters

signature

​

Returns

​

Example

if (!Signature.isCanonical(sig)) {
  sig = Signature.normalize(sig);
}

​

normalize()

normalize(signature): SignatureType

​

Parameters

signature

​

Returns

​

Example

const normalized = Signature.normalize(sig);

​

toBytes()

toBytes(signature): Uint8Array<ArrayBufferLike>

​

Parameters

signature

​

Returns

​

Example

const bytes = Signature.toBytes(sig);
// Returns r + s (64 bytes) for ECDSA or signature (64 bytes) for Ed25519

​

toCompact()

toCompact(signature): Uint8Array<ArrayBufferLike>

​

Parameters

signature

​

Returns

​

Example

const compact = Signature.toCompact(sig);
// Returns r + s (64 bytes) with yParity encoded in bit 255 of s (EIP-2098)

​

toDER()

toDER(signature): Uint8Array<ArrayBufferLike>

​

Parameters

signature

​

Returns

​

Throws

​

Example

const der = Signature.toDER(sig);
// Returns DER-encoded SEQUENCE of r and s integers

​

toHex()

toHex(signature, includeV?): string

• ECDSA without v: 128 hex chars (64 bytes: r + s)
• ECDSA with v: 130 hex chars (65 bytes: r + s + v)
• Ed25519: 128 hex chars (64 bytes)

​

Parameters

signature

includeV?

​

Returns

​

Example

const hex = Signature.toHex(sig);
// Returns "0x..." (130 chars with v, 128 chars without)

// Exclude v even if present
const hexNoV = Signature.toHex(sig, false);
// Returns "0x..." (128 chars)

​

toRpc()

toRpc(signature): object

​

Parameters

signature

​

Returns

r

r: string

s

s: string

v?

optional v: string

yParity

yParity: string

​

Throws

​

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromSecp256k1(r, s, 27);
const rpc = Signature.toRpc(sig);
// { r: '0x...', s: '0x...', yParity: '0x0', v: '0x1b' }

​

toTuple()

toTuple(signature): [number, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>]

​

Parameters

signature

​

Returns

​

Throws

​

Example

import * as Signature from './primitives/Signature/index.js';
const sig = Signature.fromSecp256k1(r, s, 27);
const [yParity, r, s] = Signature.toTuple(sig);

​

verify()