> ## Documentation Index
> Fetch the complete documentation index at: https://cosmos-docs-cosmjs-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @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.

```bash theme={"system"}
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` |

```typescript theme={"system"}
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` |

```typescript theme={"system"}
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

```typescript theme={"system"}
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.

```typescript theme={"system"}
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>`        |

<Info>
  Ed25519 hashes the message internally. Do not pre-hash the message before signing.
</Info>

```typescript theme={"system"}
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.

```typescript theme={"system"}
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

```typescript theme={"system"}
type HdPath = readonly Slip10RawIndex[];

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

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

```typescript theme={"system"}
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

<Warning>
  `Argon2id` is deprecated and will be removed in a future release. Use `argon2id` from `@noble/hashes` directly instead. See [cosmos/cosmjs#1796](https://github.com/cosmos/cosmjs/issues/1796).
</Warning>

Password-based key derivation.

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

```typescript theme={"system"}
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` |

```typescript theme={"system"}
import { Random } from "@cosmjs/crypto";

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