@cosmjs/crypto

Cryptographic primitives for blockchain applications

Low-level cryptographic library providing hashing, signing, HD key derivation, and encryption. Wraps @noble/* libraries with type safety and a consistent API.

npm install @cosmjs/crypto

Hashing

Convenience Functions

Function	Parameters	Returns	Output Size
sha256	data: Uint8Array	Uint8Array	32 bytes
sha512	data: Uint8Array	Uint8Array	64 bytes
keccak256	data: Uint8Array	Uint8Array	32 bytes
ripemd160	data: Uint8Array	Uint8Array	20 bytes

Incremental Hashing Classes

For large data, use the class API with update() for incremental hashing:

Class	Methods
Sha256	constructor(data?: Uint8Array), update(data: Uint8Array): Sha256, digest(): Uint8Array
Sha512	constructor(data?: Uint8Array), update(data: Uint8Array): Sha512, digest(): Uint8Array
Keccak256	constructor(data?: Uint8Array), update(data: Uint8Array): Keccak256, digest(): Uint8Array
Ripemd160	constructor(data?: Uint8Array), update(data: Uint8Array): Ripemd160, digest(): Uint8Array

import { sha256, Sha256, keccak256 } from "@cosmjs/crypto";

const hash = sha256(new Uint8Array([1, 2, 3]));

const hasher = new Sha256();
hasher.update(chunk1);
hasher.update(chunk2);
const incrementalHash = hasher.digest();

Hmac

Method	Parameters	Returns
constructor	hashFunctionConstructor: new () => HashFunction, originalKey: Uint8Array	Hmac
update	data: Uint8Array	Hmac
digest	—	Uint8Array

import { Hmac, Sha256 } from "@cosmjs/crypto";

const hmac = new Hmac(Sha256, key);
hmac.update(message);
const mac = hmac.digest();

Secp256k1

Elliptic curve operations for Cosmos, Bitcoin, and Ethereum signing.

Method	Parameters	Returns
makeKeypair (static)	privkey: Uint8Array	Secp256k1Keypair
createSignature (static)	messageHash: Uint8Array, privkey: Uint8Array	ExtendedSecp256k1Signature
verifySignature (static)	signature: Secp256k1Signature, messageHash: Uint8Array, pubkey: Uint8Array	boolean
recoverPubkey (static)	signature: ExtendedSecp256k1Signature, messageHash: Uint8Array	Uint8Array
compressPubkey (static)	pubkey: Uint8Array	Uint8Array
uncompressPubkey (static)	pubkey: Uint8Array	Uint8Array
trimRecoveryByte (static)	signature: Uint8Array	Uint8Array

Types

interface Secp256k1Keypair {
  readonly pubkey: Uint8Array;
  readonly privkey: Uint8Array;
}

The interface itself does not constrain the byte length of pubkey. When produced by makeKeypair, the key is always 65 bytes (uncompressed). Use compressPubkey() before passing it to Cosmos nodes, which expect 33-byte compressed keys.

import { Secp256k1, sha256 } from "@cosmjs/crypto";

const keypair = Secp256k1.makeKeypair(privkey);
const hash = sha256(message);
const signature = Secp256k1.createSignature(hash, keypair.privkey);
const valid = Secp256k1.verifySignature(signature, hash, keypair.pubkey);

Secp256k1Signature / ExtendedSecp256k1Signature

Property	Type	Description
recovery	number	0–3 (extended only)

Method	Parameters	Returns	Description
r(length?)	length?: number	Uint8Array	r component, optionally zero-padded to length bytes
s(length?)	length?: number	Uint8Array	s component, optionally zero-padded to length bytes
toFixedLength()	—	Uint8Array	64 bytes for Secp256k1Signature, 65 bytes for ExtendedSecp256k1Signature
toDer()	—	Uint8Array	DER-encoded signature
fromFixedLength(data) (static)	data: Uint8Array	Secp256k1Signature / ExtendedSecp256k1Signature	64-byte input for base class, 65-byte for extended
fromDer(data) (static)	data: Uint8Array	Secp256k1Signature	Parse DER-encoded signature

Ed25519

Edwards-curve digital signature algorithm for fast, deterministic signing.

Method	Parameters	Returns
makeKeypair (static)	privKey: Uint8Array (32-byte seed)	Promise<Ed25519Keypair>
createSignature (static)	message: Uint8Array, keyPair: Ed25519Keypair	Promise<Uint8Array>
verifySignature (static)	signature: Uint8Array, message: Uint8Array, pubkey: Uint8Array	Promise<boolean>

Ed25519 hashes the message internally. Do not pre-hash the message before signing.

import { Ed25519 } from "@cosmjs/crypto";

const keypair = await Ed25519.makeKeypair(seed32bytes);
const signature = await Ed25519.createSignature(message, keypair);
const valid = await Ed25519.verifySignature(signature, message, keypair.pubkey);

BIP-39 Mnemonics

Bip39

Method	Parameters	Returns
encode (static)	entropy: Uint8Array	EnglishMnemonic
decode (static)	mnemonic: EnglishMnemonic	Uint8Array
mnemonicToSeed (static)	mnemonic: EnglishMnemonic, password?: string	Promise<Uint8Array>

EnglishMnemonic

Validates and wraps a BIP-39 English mnemonic string. Throws on invalid input.

import { Bip39, EnglishMnemonic, Random } from "@cosmjs/crypto";

const mnemonic = Bip39.encode(Random.getBytes(32));  // 24 words
const mnemonic12 = Bip39.encode(Random.getBytes(16)); // 12 words

const validated = new EnglishMnemonic("your mnemonic words ...");
const seed = await Bip39.mnemonicToSeed(validated);

SLIP-10 HD Key Derivation

Slip10

Method	Parameters	Returns
derivePath (static)	curve: Slip10Curve, seed: Uint8Array, path: HdPath	Slip10Result

Path Utilities

Function	Parameters	Returns
stringToPath	input: string	HdPath
pathToString	path: HdPath	string
slip10CurveFromString	curveString: string	Slip10Curve

Types

type HdPath = readonly Slip10RawIndex[];

interface Slip10Result {
  readonly chainCode: Uint8Array;
  readonly privkey: Uint8Array;
}

enum Slip10Curve {
  Secp256k1 = "Bitcoin seed",
  Ed25519 = "ed25519 seed",
}

import { Slip10, Slip10Curve, stringToPath, Bip39, EnglishMnemonic } from "@cosmjs/crypto";

const mnemonic = new EnglishMnemonic("your mnemonic ...");
const seed = await Bip39.mnemonicToSeed(mnemonic);
const hdPath = stringToPath("m/44'/118'/0'/0/0");
const { privkey } = Slip10.derivePath(Slip10Curve.Secp256k1, seed, hdPath);

Encryption

Xchacha20poly1305Ietf

Authenticated encryption using XChaCha20-Poly1305.

Method	Parameters	Returns
encrypt (static)	message: Uint8Array, key: Uint8Array, nonce: Uint8Array	Promise<Uint8Array>
decrypt (static)	ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array	Promise<Uint8Array>

The constant xchacha20NonceLength is 24.

Argon2id

Argon2id is deprecated and will be removed in a future release. Use argon2id from @noble/hashes directly instead. See cosmos/cosmjs#1796.

Password-based key derivation.

Method	Parameters	Returns
execute (static)	password: string, salt: Uint8Array (must be 16 bytes), options: Argon2idOptions	Promise<Uint8Array>

interface Argon2idOptions {
  readonly outputLength: number;
  readonly opsLimit: number;
  readonly memLimitKib: number;
}

Random

Cryptographically secure random number generation.

Method	Parameters	Returns
getBytes (static)	count: number	Uint8Array

import { Random } from "@cosmjs/crypto";

const nonce = Random.getBytes(24);
const privkey = Random.getBytes(32);