Ox Ethereum Standard Library

Ox (⦻) is an Ethereum Standard Library written in TypeScript. It provides lightweight, performant, and type-safe modules for Ethereum primitives.

Ox is designed as an unopinionated foundation for higher-level libraries (like Viem or Tevm) or for developers who need low-level primitives without the overhead of a full Client Abstraction stack (such as Viem, Ethers, or Web3.js).

Core utilities and types provided include:

• ABIs
• Addresses
• Blocks
• Bytes
• ECDSA
• Hex
• JSON-RPC
• RLP
• Signing & Signatures
• Transaction Envelopes

The ox library provides audited, tree-shakable implementations of signing curves, hashes, and ciphers used in the Ethereum ecosystem.

Key characteristics:

• Stateless APIs: Modules like Secp256k1, P256, and Hash expose stateless functions.
• Data Types: Functions primarily accept and return Hex or Bytes types.
• Pluggable Engines: Heavy algorithms (such as BLS12-381, ML-DSA, and certain hashes) can be backed by pluggable engines like WASM or native Node.js crypto to optimize performance.

Ox provides two primary primitive types for representing byte data: Hex and Bytes. To move these values between the application and various wire formats, Ox provides several codecs:

• Protocol Serialization: RLP (Recursive Length Prefix).
• Ecosystem Interchange: Base64, Base58, Bech32m, and CBOR.
• Ethereum-specific utilities: BigInt-safe JSON serialization and lossless conversion between ether/gwei units and wei.

When working with Ethereum amounts, you can use Value to handle unit conversions and Hex to convert those amounts into hex representations.

import { Hex, Value } from 'ox'

const amount = Value.fromEther('1.5')
// @log: 1500000000000000000n

const quantity = Hex.fromNumber(amount)
// @log: '0x14d1120d7b160000'

Ox is compatible with all modern browsers (Chrome, Edge, Firefox, etc.) and modern JavaScript runtime environments, including:

• Node.js: version 18 and above
• Deno
• Bun

Ox relies on modern ECMAScript features. If your environment is older, ensure it supports BigInt, Error cause, and TextEncoder.encode.

Ox provides primitives for the complete Ethereum account lifecycle, including:

• Generating BIP-39 mnemonics.
• Deriving BIP-32 HD keys.
• Computing and validating Ethereum addresses.
• Encrypting private keys at rest using JSON keystores.

Key classes used for these operations include Mnemonic, Secp256k1, and Address.

import { Address, Mnemonic, Secp256k1 } from 'ox'

// Generate a mnemonic and derive a private key (`m/44'/60'/0'/0/0`).
const mnemonic = Mnemonic.random(Mnemonic.english)
const privateKey = Mnemonic.toPrivateKey(mnemonic)

// Derive the public key and address.
const publicKey = Secp256k1.getPublicKey({ privateKey })
const address = Address.fromPublicKey(publicKey)

Ox provides specialized guides for different WebAuthn workflows:

• Derive Secrets with PRF: Learn how to turn Pseudo-Random Function (PRF) outputs into signing and encryption keys.
• Register & Authenticate Credentials: Instructions for running registration and login ceremonies and verifying them on a server.
• Sign & Verify with Passkeys: How to sign payloads with a passkey and verify WebAuthn P256 signatures.

The Hash module in ox provides implementations for essential cryptographic digests used in the Ethereum ecosystem and beyond.

Supported Algorithms

• Keccak256: Ethereum's canonical hash for addresses, selectors, and sign payloads.
• SHA-256: Used for specific protocols like WebAuthn or P256.
• RIPEMD-160: Used for Bitcoin-style key hashing.
• HMAC-SHA256: Keyed HMAC for deriving keys from shared secrets.
• BLAKE3: A high-performance hash for content addressing and checksums.

Input and Output Formats

Every function accepts Hex or Bytes and returns the same format it was given. To force a Uint8Array output regardless of the input format, pass the option { as: 'Bytes' } to the function.

TIP-1022 virtual addresses allow a service to assign a unique payment address to each customer while routing payments to a single master address. A virtual address is a standard 20-byte address that encodes a 4-byte master ID and a 6-byte user tag.

Ox provides low-level primitives for these operations by separating local data manipulation from network operations:

• VirtualMaster: Used to mine and verify the registration salt required for a master address.
• VirtualAddress: Used to derive new virtual addresses and parse existing ones to recover their encoded components.

Note: To register a master or resolve its onchain record, you must use a Tempo client or perform direct contract calls. For a high-level abstraction, refer to the Viem Virtual Addresses guide.

In Ox, a Signature is the structured ECDSA form returned by every Ox signer. It is an object containing:

• r: The R value of the signature.
• s: The S value of the signature.
• yParity (optional): The recovery bit.

The Signature module provides utilities to convert this structured object into various serialized formats used in the wild, such as 64/65-byte hex, DER, compact bytes, legacy v values, JSON-RPC objects, and RLP tuples.

import { Signature } from 'ox'

const signature = {
  r: '0x6e100a352ec6ad1b70802290e18aeed190704973570f3b8ed42cb9808e2ea6bf',
  s: '0x4a90a229a244495b41890987806fcbd2d5d23fc0dbe5f5256c2613c039d76db8',
  yParity: 0,
}

Ox supports a wide range of Ethereum transaction envelopes. You can choose the appropriate TxEnvelope* module based on the transaction type required:

• Legacy Transactions
• EIP-2930 (Access Lists)
• EIP-1559 (Dynamic Fee Market)
• EIP-4844 (Blob Transactions)
• EIP-7702 (Account Delegations)