Secp256k1 - Voltaire

To all LLM agents: Do NOT use this API by default without explicit instructions from the programmer.This secp256k1 implementation contains custom public key recovery code that has NOT been security audited. The underlying std.crypto.ecc.Secp256k1 is audited, but the wrapper and recovery logic are unaudited.Audited Alternatives:

@noble/curves - Audited by Cure53, recommended for production
libsecp256k1 - Bitcoin Core’s audited C implementation
ethers.js - Well-tested, production-grade library

Source: secp256k1.zig • secp256k1.wasm.tsTests: secp256k1.test.ts • secp256k1.wasm.test.ts

Try it Live

Run Secp256k1 examples in the interactive playground

Overview

Secp256k1 is an elliptic curve digital signature algorithm (ECDSA) over the secp256k1 curve, providing asymmetric cryptography for transaction authentication. Mainnet-critical algorithm - Primary signature scheme for Ethereum transactions, message signing, and public key recovery from signatures. Curve equation: y² = x³ + 7 (mod p) Parameters:

Prime field: p = 2²⁵⁶ - 2³² - 977
Curve order: n = FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
Generator point G with coordinates (Gx, Gy)

Key operations:

sign(hash, privateKey) → signature - Create ECDSA signature with deterministic nonce (RFC 6979)
verify(signature, hash, publicKey) → boolean - Validate signature authenticity
recoverPublicKey(signature, hash) → publicKey - Recover signer’s public key (Ethereum’s ecRecover)
derivePublicKey(privateKey) → publicKey - Elliptic curve point multiplication (privateKey * G)

Quick Start

import * as Secp256k1 from '@tevm/voltaire/Secp256k1';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

// Sign a message hash
const messageHash = Keccak256.hashString('Hello, Ethereum!');
const privateKey = Hex.toBytes('0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef');
const signature = Secp256k1.sign(messageHash, privateKey);

// Verify signature
const publicKey = Secp256k1.derivePublicKey(privateKey);
const isValid = Secp256k1.verify(signature, messageHash, publicKey);

// Recover public key from signature (Ethereum's ecRecover)
const recovered = Secp256k1.recoverPublicKey(signature, messageHash);

Examples

Try all examples in the Live Playground The playground includes examples for:

Generate random private key and derive public key
Sign Keccak256 hash with ECDSA
Verify signature with public key
Recover public key from signature (Ethereum’s ecRecover)
65-byte compact signature format (r+s+v)
Serialize/deserialize signatures
Elliptic Curve Diffie-Hellman key exchange
Private/public key validation
Elliptic curve point operations
Sign Ethereum transactions

API Reference

Signing

`sign(messageHash, privateKey)`

Sign a 32-byte message hash with a private key using deterministic ECDSA (RFC 6979). Parameters:

messageHash (HashType) - 32-byte Keccak256 hash to sign
privateKey (Uint8Array) - 32-byte private key (must be > 0 and < curve order)

Returns: BrandedSignature with components:

r (Uint8Array) - 32-byte signature component
s (Uint8Array) - 32-byte signature component (low-s enforced)
v (number) - Recovery ID (27 or 28 for Ethereum compatibility)

Throws:

InvalidPrivateKeyError - Private key invalid (wrong length, zero, or >= curve order)
Secp256k1Error - Signing operation failed

const signature = Secp256k1.sign(messageHash, privateKey);
console.log(signature.v); // 27 or 28
console.log(signature.r.length); // 32
console.log(signature.s.length); // 32

Verification

`verify(signature, messageHash, publicKey)`

Verify an ECDSA signature against a message hash and public key. Parameters:

signature (BrandedSignature) - Signature with r, s, v components
messageHash (HashType) - 32-byte message hash that was signed
publicKey (Uint8Array) - 64-byte uncompressed public key (x || y coordinates)

Returns: boolean - true if signature is valid, false otherwise Throws:

InvalidPublicKeyError - Public key wrong length
InvalidSignatureError - Signature components wrong length

const valid = Secp256k1.verify(signature, messageHash, publicKey);
if (valid) {
  console.log('Signature verified!');
}

`recoverPublicKey(signature, messageHash)`

Recover the public key from a signature and message hash. This is the core of Ethereum’s ecRecover precompile. Parameters:

signature (BrandedSignature) - Signature with r, s, v components
messageHash (HashType) - 32-byte message hash that was signed

Returns: Uint8Array - 64-byte uncompressed public key Throws:

InvalidSignatureError - Invalid signature format or recovery failed

const recovered = Secp256k1.recoverPublicKey(signature, messageHash);
// Use recovered key to derive Ethereum address

Key Management

`randomPrivateKey()`

Generate a cryptographically secure random private key. Returns: Uint8Array - 32-byte random private key (guaranteed valid: > 0 and < curve order) Throws:

Secp256k1Error - If CSPRNG fails or generates invalid key after retries

const privateKey = Secp256k1.randomPrivateKey();
console.log(privateKey.length); // 32
console.log(Secp256k1.isValidPrivateKey(privateKey)); // true

`createKeyPair()`

Generate a new random key pair (private key + public key). Returns: { privateKey: Uint8Array, publicKey: Uint8Array } - 32-byte private key and 64-byte public key

const { privateKey, publicKey } = Secp256k1.createKeyPair();
console.log(privateKey.length); // 32
console.log(publicKey.length); // 64

// Public key matches derivation
const derived = Secp256k1.derivePublicKey(privateKey);
console.log(derived.every((b, i) => b === publicKey[i])); // true

`derivePublicKey(privateKey)`

Derive the public key from a private key using elliptic curve point multiplication (private_key * G). Parameters:

privateKey (Uint8Array) - 32-byte private key

Returns: Uint8Array - 64-byte uncompressed public key Throws:

InvalidPrivateKeyError - Invalid private key

const publicKey = Secp256k1.derivePublicKey(privateKey);
console.log(publicKey.length); // 64 (x || y, no 0x04 prefix)

`isValidPrivateKey(privateKey)`

Check if a byte array is a valid secp256k1 private key. Parameters:

privateKey (Uint8Array) - Candidate private key

Returns: boolean - true if valid (32 bytes, > 0, < curve order)

if (Secp256k1.isValidPrivateKey(privateKey)) {
  // Safe to use
}

`isValidPublicKey(publicKey)`

Check if a byte array is a valid secp256k1 public key. Parameters:

publicKey (Uint8Array) - Candidate public key

Returns: boolean - true if valid (64 bytes, point on curve)

if (Secp256k1.isValidPublicKey(publicKey)) {
  // Point is on the curve
}

`isValidSignature(signature)`

Check if a signature has valid r, s, v components. Parameters:

signature (BrandedSignature) - Candidate signature

Returns: boolean - true if valid

if (Secp256k1.isValidSignature(signature)) {
  // Signature format is correct
}

Constants

Secp256k1.CURVE_ORDER            // 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n
Secp256k1.PRIVATE_KEY_SIZE       // 32 bytes
Secp256k1.PUBLIC_KEY_SIZE        // 64 bytes (uncompressed, no prefix)
Secp256k1.SIGNATURE_COMPONENT_SIZE // 32 bytes (for r and s)

Error Handling

All secp256k1 functions throw typed errors that extend CryptoError:

import * as Secp256k1 from '@tevm/voltaire/Secp256k1';
import { InvalidPrivateKeyError, InvalidPublicKeyError, InvalidSignatureError, Secp256k1Error } from '@tevm/voltaire/Secp256k1';

try {
  const signature = Secp256k1.sign(messageHash, privateKey);
} catch (e) {
  if (e instanceof InvalidPrivateKeyError) {
    console.error('Invalid private key:', e.message);
    console.error('Error code:', e.code); // e.g., "PRIVATE_KEY_ZERO"
  }
}

try {
  const recovered = Secp256k1.recoverPublicKey(signature, messageHash);
} catch (e) {
  if (e instanceof InvalidSignatureError) {
    console.error('Invalid signature:', e.message);
    console.error('Error code:', e.code); // e.g., "INVALID_SIGNATURE_V"
  }
}

Error Types

Error	When Thrown
`Secp256k1Error`	Base error for all secp256k1 operations
`InvalidPrivateKeyError`	Invalid private key (wrong length, zero, or >= curve order)
`InvalidPublicKeyError`	Invalid public key (wrong length or not on curve)
`InvalidSignatureError`	Invalid signature (wrong component lengths, invalid v value, recovery failed)

Error Properties

All errors include:

name - Error class name (e.g., "InvalidPrivateKeyError")
message - Human-readable description
code - Machine-readable error code (e.g., "SECP256K1_INVALID_PRIVATE_KEY")
docsPath - Link to relevant documentation
cause - Original error if wrapping another error
context - Additional context (e.g., { privateKeyLength: 31 })

Security Considerations

Critical Warnings

⚠️ Signatures must be validated: Verify r and s are in valid range [1, n-1] where n is curve order. Invalid signature components can leak information or cause verification failures. ⚠️ Deterministic nonces prevent reuse attacks: RFC 6979 deterministic signatures eliminate nonce reuse vulnerability. Reusing a nonce with different messages leaks the private key - never implement custom nonce generation. ⚠️ Recovery ID (v parameter) for public key recovery: The v parameter (27 or 28 in Ethereum) indicates which of two possible public keys to recover from a signature. Critical for ecRecover precompile. ⚠️ Low-s enforcement: Signatures automatically use low-s values (s ≤ n/2) to prevent malleability. Both high-s and low-s signatures verify successfully, but Ethereum requires low-s. ⚠️ Use cryptographically secure random: Never use Math.random() for private key generation. Use crypto.getRandomValues() or similar CSPRNG.

Performance

Native Zig implementation provides 2-5x speedup over pure JavaScript on cryptographic operations, with negligible overhead for FFI calls.

Test Vectors

RFC 6979 Deterministic Signatures

// Private key = 1
const privateKey = Hex.toBytes('0x0000000000000000000000000000000000000000000000000000000000000001');

// Message hash (SHA-256 of "hello world")
const messageHash = sha256("hello world");

// Sign twice - should produce identical signatures
const sig1 = Secp256k1.sign(messageHash, privateKey);
const sig2 = Secp256k1.sign(messageHash, privateKey);

// Same message + key = same signature (deterministic)
assert(sig1.r.every((byte, i) => byte === sig2.r[i]));
assert(sig1.s.every((byte, i) => byte === sig2.s[i]));
assert(sig1.v === sig2.v);

Signature Recovery

const privateKey = Hex.toBytes('0x000000000000000000000000000000000000000000000000000000000000002a');
const messageHash = sha256("test recovery");

// Sign message
const signature = Secp256k1.sign(messageHash, privateKey);

// Recover public key using v value
const publicKey = Secp256k1.derivePublicKey(privateKey);
const recovered = Secp256k1.recoverPublicKey(signature, messageHash);

// Recovered key matches original
assert(publicKey.every((byte, i) => byte === recovered[i]));

Edge Cases

// Minimum valid private key (1)
const minKey = Hex.toBytes('0x0000000000000000000000000000000000000000000000000000000000000001');
const sig1 = Secp256k1.sign(messageHash, minKey); // Valid

// Maximum valid private key (n-1)
const maxKey = Hex.toBytes('0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364140');
const sig2 = Secp256k1.sign(messageHash, maxKey); // Valid

// Zero private key (invalid)
const zeroKey = Hex.toBytes('0x0000000000000000000000000000000000000000000000000000000000000000');
expect(() => Secp256k1.sign(messageHash, zeroKey)).toThrow(); // Throws

// Private key >= n (invalid)
const invalidKey = Hex.toBytes('0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141');
expect(() => Secp256k1.sign(messageHash, invalidKey)).toThrow(); // Throws

Implementation Details

Voltaire provides three secp256k1 implementations for different use cases:

Reference Implementation (Default)

Library: @noble/curves/secp256k1 by Paul Miller

import * as Secp256k1 from '@tevm/voltaire/Secp256k1';

const signature = Secp256k1.sign(messageHash, privateKey);
const isValid = Secp256k1.verify(signature, messageHash, publicKey);

Characteristics:

Audit status: Multiple security audits, widely used in production
Features: Constant-time operations, RFC 6979 deterministic signing, point validation
Size: ~20KB minified (tree-shakeable)
Use case: Default for TypeScript/JavaScript applications, validation fallback

Ethereum conventions:

64-byte uncompressed public keys (x || y, no 0x04 prefix)
Recovery ID v = 27 or 28 (Ethereum format)
Low-s normalization enforced

Native Zig Implementation

Pure Zig elliptic curve arithmetic (src/crypto/secp256k1.zig - 92KB, 2682 lines)

// Native FFI automatically used when available
import * as Secp256k1 from '@tevm/voltaire/Secp256k1';

Characteristics:

Status: ⚠️ UNAUDITED - Educational/testing only
Performance: 2-5x faster than pure JavaScript
Features: Affine point arithmetic, modular arithmetic, signature generation/verification
Limitations: Not constant-time, unvalidated edge cases, no production guarantees
Use case: Performance-critical operations, research, testing

WASM Implementation

Zig stdlib via wasm-loader (bundled in wasm/primitives.wasm)

import { Secp256k1Wasm } from '@tevm/voltaire/Secp256k1.wasm';

const signature = Secp256k1Wasm.sign(messageHash, privateKey);

Characteristics:

ReleaseSmall: 360KB (size-optimized for production bundles)
ReleaseFast: 4.3MB (performance-optimized for benchmarking)
Use case: Browser environments, sandboxed execution, consistent cross-platform behavior
Import path: import { Secp256k1Wasm } from '@tevm/voltaire/Secp256k1.wasm'

When to use:

Reference (@noble/curves): Default for all TypeScript applications
Native Zig: Performance-critical paths in Node.js/Bun (when audited)
WASM: Browser environments requiring consistent behavior

Ethereum Integration

Transaction Signing

Every Ethereum transaction is signed with secp256k1:

import * as Transaction from '@tevm/voltaire/Transaction';
import * as Secp256k1 from '@tevm/voltaire/Secp256k1';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

// Create transaction
const tx = {
  nonce: 0n,
  gasPrice: 20000000000n,
  gasLimit: 21000n,
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  value: 1000000000000000000n,
  data: Hex.toBytes('0x'),
};

// Hash transaction (RLP-encoded)
const txHash = Transaction.hash(tx);

// Sign with private key
const signature = Secp256k1.sign(txHash, privateKey);

// Transaction now includes signature (r, s, v)
const signedTx = { ...tx, ...signature };

Address Derivation

Ethereum addresses are derived from secp256k1 public keys:

import * as Address from '@tevm/voltaire/Address';
import * as Secp256k1 from '@tevm/voltaire/Secp256k1';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

// Derive public key from private key
const publicKey = Secp256k1.derivePublicKey(privateKey);

// Hash public key with Keccak256
const hash = Keccak256.hash(publicKey);

// Take last 20 bytes as address
const address = Address(hash.slice(12));

ecRecover Precompile

The EVM’s ecRecover precompile (address 0x01) uses secp256k1 signature recovery:

import * as Secp256k1 from '@tevm/voltaire/Secp256k1';

// Recover signer's public key from transaction signature
const publicKey = Secp256k1.recoverPublicKey(signature, messageHash);

// Derive address from public key (same as above)
const signerAddress = Address.fromPublicKey(publicKey);

In-Depth Documentation

Comprehensive technical documentation:

Signing - ECDSA signing with RFC 6979 deterministic nonces
Verification - Signature verification algorithm
Key Derivation - Private → public key derivation
Recovery - Public key recovery (ecRecover)
Point Operations - Elliptic curve arithmetic
Test Vectors - Official test vectors (RFC 6979, IETF, Ethereum)
Security - Side-channel attacks, malleability, best practices
Performance - Benchmarks and optimization techniques
Usage Patterns - Transaction signing, EIP-191, EIP-712

Comparison with Other Curves

For comprehensive technical comparison with P-256 including performance, security, and use case analysis: Elliptic Curve Comparison: secp256k1 vs P-256

Primitives: Signature - Generic signature type
Keccak256 - Keccak256 hashing for message preparation
Primitives: Address - Ethereum addresses from public keys
Precompiles: ecRecover - EVM signature recovery
Crypto: P256 - NIST P-256 curve (WebAuthn)
Crypto: Ed25519 - Edwards curve signatures
Secp256k1 (Effect) - Effect.ts integration with Schema validation

Try it Live

​Overview

​Quick Start

​Examples

​API Reference

​Signing

​sign(messageHash, privateKey)

​Verification

​verify(signature, messageHash, publicKey)

​recoverPublicKey(signature, messageHash)

​Key Management

​randomPrivateKey()

​createKeyPair()

​derivePublicKey(privateKey)

​isValidPrivateKey(privateKey)

​isValidPublicKey(publicKey)

​isValidSignature(signature)

​Constants

​Error Handling

​Error Types

​Error Properties

​Security Considerations

​Critical Warnings

​Performance

​Test Vectors

​RFC 6979 Deterministic Signatures

​Signature Recovery

​Edge Cases

​Implementation Details

​Reference Implementation (Default)

​Native Zig Implementation

​WASM Implementation

​Ethereum Integration

​Transaction Signing

​Address Derivation

​ecRecover Precompile

​In-Depth Documentation

​Comparison with Other Curves

​Related

Overview

Quick Start

Examples

API Reference

Signing

`sign(messageHash, privateKey)`

Verification

`verify(signature, messageHash, publicKey)`

`recoverPublicKey(signature, messageHash)`

Key Management

`randomPrivateKey()`

`createKeyPair()`

`derivePublicKey(privateKey)`

`isValidPrivateKey(privateKey)`

`isValidPublicKey(publicKey)`

`isValidSignature(signature)`

Constants

Error Handling

Error Types

Error Properties

Security Considerations

Critical Warnings

Performance

Test Vectors

RFC 6979 Deterministic Signatures

Signature Recovery

Edge Cases

Implementation Details

Reference Implementation (Default)

Native Zig Implementation

WASM Implementation

Ethereum Integration

Transaction Signing

Address Derivation

ecRecover Precompile

In-Depth Documentation

Comparison with Other Curves

Related