0
# @polkadot/wasm-crypto
1

2
@polkadot/wasm-crypto is a WebAssembly interface layer that provides high-performance cryptographic functions for blockchain applications in the Polkadot ecosystem. It wraps Rust-based cryptographic implementations compiled to WebAssembly, offering superior performance for cryptographic operations that are essential for blockchain applications but may not have pure JavaScript implementations (particularly sr25519).
3

4
## Package Information
5

6
- **Package Name**: @polkadot/wasm-crypto
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @polkadot/wasm-crypto`
10

11
## Core Imports
12

13
```typescript
14
import { waitReady, isReady, bip39Generate, sr25519Sign } from "@polkadot/wasm-crypto";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { waitReady, isReady, bip39Generate, sr25519Sign } = require("@polkadot/wasm-crypto");
21
```
22

23
### Specialized Initialization Imports
24

25
```typescript
26
import { initWasm } from "@polkadot/wasm-crypto/initOnlyWasm";
27
import { initWasm } from "@polkadot/wasm-crypto/initWasmAsm";
28
import { initWasm } from "@polkadot/wasm-crypto/initOnlyAsm";
29
import { initWasm } from "@polkadot/wasm-crypto/initNone";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { waitReady, bip39Generate, sr25519KeypairFromSeed, sr25519Sign } from "@polkadot/wasm-crypto";
36

37
// Initialize WASM interface
38
await waitReady();
39

40
// Generate BIP39 mnemonic
41
const mnemonic = bip39Generate(12);
42
console.log("Mnemonic:", mnemonic);
43

44
// Create sr25519 keypair
45
const seed = new Uint8Array(32).fill(1); // Example seed
46
const keypair = sr25519KeypairFromSeed(seed);
47

48
// Sign a message
49
const message = new TextEncoder().encode("Hello world");
50
const signature = sr25519Sign(keypair.slice(32), keypair.slice(0, 32), message);
51
```
52

53
## Architecture
54

55
@polkadot/wasm-crypto is built around several key components:
56

57
- **Bridge System**: Global bridge interface (`bridge`) managing communication between JavaScript and WebAssembly
58
- **WASM Wrapper Functions**: All cryptographic functions use a `withWasm` wrapper that ensures WASM initialization
59
- **Initialization Strategies**: Multiple initialization modules supporting different deployment scenarios (WASM-only, ASM.js fallback, automatic detection)
60
- **Type Safety**: Full TypeScript integration with proper type definitions for all cryptographic operations
61
- **Error Handling**: Consistent error handling for uninitialized WASM interface
62

63
## Capabilities
64

65
### Initialization and Status
66

67
Core initialization functions and status checking for the WASM interface.
68

69
```typescript { .api }
70
function waitReady(): Promise<boolean>;
71
function isReady(): boolean;
72
```
73

74
### BIP39 Mnemonic Operations
75

76
BIP39 mnemonic phrase generation, validation, and derivation functions for seed phrase handling.
77

78
```typescript { .api }
79
function bip39Generate(words: 12 | 15 | 18 | 21 | 24): string;
80
function bip39Validate(phrase: string): boolean;
81
function bip39ToSeed(phrase: string, password: string): Uint8Array;
82
function bip39ToMiniSecret(phrase: string, password: string): Uint8Array;
83
function bip39ToEntropy(phrase: string): Uint8Array;
84
```
85

86
[BIP39 Operations](./bip39.md)
87

88
### Sr25519 Digital Signatures
89

90
Sr25519 signature scheme implementation with keypair generation, signing, verification, and key derivation.
91

92
```typescript { .api }
93
function sr25519KeypairFromSeed(seed: Uint8Array): Uint8Array;
94
function sr25519Sign(pubkey: Uint8Array, secret: Uint8Array, message: Uint8Array): Uint8Array;
95
function sr25519Verify(signature: Uint8Array, message: Uint8Array, pubkey: Uint8Array): boolean;
96
function sr25519DeriveKeypairHard(pair: Uint8Array, cc: Uint8Array): Uint8Array;
97
function sr25519DeriveKeypairSoft(pair: Uint8Array, cc: Uint8Array): Uint8Array;
98
function sr25519DerivePublicSoft(pubkey: Uint8Array, cc: Uint8Array): Uint8Array;
99
function sr25519Agree(pubkey: Uint8Array, secret: Uint8Array): Uint8Array;
100
```
101

102
[Sr25519 Signatures](./sr25519.md)
103

104
### Ed25519 Digital Signatures
105

106
Ed25519 signature scheme implementation with keypair generation, signing, and verification.
107

108
```typescript { .api }
109
function ed25519KeypairFromSeed(seed: Uint8Array): Uint8Array;
110
function ed25519Sign(pubkey: Uint8Array, seckey: Uint8Array, message: Uint8Array): Uint8Array;
111
function ed25519Verify(signature: Uint8Array, message: Uint8Array, pubkey: Uint8Array): boolean;
112
```
113

114
[Ed25519 Signatures](./ed25519.md)
115

116
### Secp256k1 ECDSA Operations
117

118
Secp256k1 elliptic curve cryptography functions including key generation, signing, recovery, and key compression.
119

120
```typescript { .api }
121
function secp256k1FromSeed(seckey: Uint8Array): Uint8Array;
122
function secp256k1Sign(msgHash: Uint8Array, seckey: Uint8Array): Uint8Array;
123
function secp256k1Recover(msgHash: Uint8Array, sig: Uint8Array, recovery: number): Uint8Array;
124
function secp256k1Compress(pubkey: Uint8Array): Uint8Array;
125
function secp256k1Expand(pubkey: Uint8Array): Uint8Array;
126
```
127

128
[Secp256k1 Operations](./secp256k1.md)
129

130
### Cryptographic Hashing
131

132
Various cryptographic hash functions including SHA, BLAKE2b, Keccak, and HMAC variants.
133

134
```typescript { .api }
135
function blake2b(data: Uint8Array, key: Uint8Array, size: number): Uint8Array;
136
function sha256(data: Uint8Array): Uint8Array;
137
function sha512(data: Uint8Array): Uint8Array;
138
function keccak256(data: Uint8Array): Uint8Array;
139
function keccak512(data: Uint8Array): Uint8Array;
140
function hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array;
141
function hmacSha512(key: Uint8Array, data: Uint8Array): Uint8Array;
142
function twox(data: Uint8Array, rounds: number): Uint8Array;
143
```
144

145
[Hashing Functions](./hashing.md)
146

147
### Key Derivation Functions
148

149
Password-based key derivation functions for generating cryptographic keys from passwords.
150

151
```typescript { .api }
152
function pbkdf2(data: Uint8Array, salt: Uint8Array, rounds: number): Uint8Array;
153
function scrypt(password: Uint8Array, salt: Uint8Array, log2n: number, r: number, p: number): Uint8Array;
154
```
155

156
[Key Derivation](./key-derivation.md)
157

158
### VRF (Verifiable Random Functions)
159

160
Verifiable Random Function implementation for generating and verifying cryptographically secure random values.
161

162
```typescript { .api }
163
function vrfSign(secret: Uint8Array, context: Uint8Array, message: Uint8Array, extra: Uint8Array): Uint8Array;
164
function vrfVerify(pubkey: Uint8Array, context: Uint8Array, message: Uint8Array, extra: Uint8Array, outAndProof: Uint8Array): boolean;
165
```
166

167
[VRF Functions](./vrf.md)
168

169
## Core Types
170

171
```typescript { .api }
172
interface Bridge {
173
  readonly wasm: WasmCryptoInstance | null;
174
  readonly type: string;
175
}
176

177
interface PackageInfo {
178
  readonly name: string;
179
  readonly version: string;
180
  readonly path: string;
181
  readonly type: string;
182
}
183
```
184

185
## Global Objects
186

187
```typescript { .api }
188
const bridge: Bridge;
189
const packageInfo: PackageInfo;
190
```
191

192
## Error Handling
193

194
All cryptographic functions throw an `Error` if the WASM interface has not been initialized:
195

196
```
197
"The WASM interface has not been initialized. Ensure that you wait for the initialization Promise with waitReady() from @polkadot/wasm-crypto (or cryptoWaitReady() from @polkadot/util-crypto) before attempting to use WASM-only interfaces."
198
```
199

200
Always call `await waitReady()` before using any cryptographic functions to ensure proper initialization.