0
# Cryptography and Key Management
1

2
Ed25519 key pair generation, digital signatures, and cryptographic operations for Solana blockchain interactions.
3

4
## Capabilities
5

6
### Key Pair Generation
7

8
Generate Ed25519 key pairs for signing transactions and deriving addresses.
9

10
```typescript { .api }
11
/**
12
 * Standard Web Crypto API key pair interface
13
 */
14
interface CryptoKeyPair {
15
  privateKey: CryptoKey;
16
  publicKey: CryptoKey;
17
}
18

19
/**
20
 * Generate a new Ed25519 key pair using Web Crypto API
21
 * @returns Promise resolving to a CryptoKeyPair
22
 */
23
function generateKeyPair(): Promise<CryptoKeyPair>;
24

25
/**
26
 * Create key pair from raw byte array containing both private and public key data
27
 * @param bytes - ReadonlyUint8Array containing key pair data
28
 * @param extractable - Whether the keys should be extractable (optional, defaults to false)
29
 * @returns Promise resolving to a CryptoKeyPair
30
 */
31
function createKeyPairFromBytes(bytes: ReadonlyUint8Array, extractable?: boolean): Promise<CryptoKeyPair>;
32

33
/**
34
 * Create key pair from private key bytes only
35
 * @param bytes - 32-byte private key as ReadonlyUint8Array
36
 * @param extractable - Whether the keys should be extractable (defaults to false)
37
 * @returns Promise resolving to a CryptoKeyPair with derived public key
38
 */
39
function createKeyPairFromPrivateKeyBytes(bytes: ReadonlyUint8Array, extractable?: boolean): Promise<CryptoKeyPair>;
40

41
/**
42
 * Import private key from raw bytes
43
 * @param bytes - 32-byte private key as ReadonlyUint8Array
44
 * @param extractable - Whether the key should be extractable (optional, defaults to false)
45
 * @returns Promise resolving to a CryptoKey
46
 */
47
function createPrivateKeyFromBytes(bytes: ReadonlyUint8Array, extractable?: boolean): Promise<CryptoKey>;
48

49
/**
50
 * Derive public key from private key
51
 * @param privateKey - CryptoKey containing private key
52
 * @param extractable - Whether the public key should be extractable (defaults to false)
53
 * @returns Promise resolving to public key CryptoKey
54
 */
55
function getPublicKeyFromPrivateKey(privateKey: CryptoKey, extractable?: boolean): Promise<CryptoKey>;
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { generateKeyPair, createKeyPairFromPrivateKeyBytes, getAddressFromPublicKey } from "@solana/web3.js";
62

63
// Generate a new key pair
64
const keyPair = await generateKeyPair();
65
const { privateKey, publicKey } = keyPair;
66

67
// Derive address from public key
68
const address = await getAddressFromPublicKey(publicKey);
69
console.log("Address:", address);
70

71
// Import existing key pair from private key bytes
72
const existingPrivateKeyBytes = new Uint8Array(32); // Your private key bytes
73
const importedKeyPair = await createKeyPairFromPrivateKeyBytes(existingPrivateKeyBytes);
74
```
75

76
### Digital Signatures
77

78
Sign data and verify signatures using Ed25519 cryptography.
79

80
```typescript { .api }
81
/**
82
 * Raw signature bytes (64 bytes for Ed25519)
83
 */
84
type SignatureBytes = Uint8Array & { readonly __brand: unique symbol };
85

86
/**
87
 * Sign arbitrary data with a private key
88
 * @param key - CryptoKey containing private key
89
 * @param data - Data to sign as ReadonlyUint8Array
90
 * @returns Promise resolving to signature bytes
91
 */
92
function signBytes(key: CryptoKey, data: ReadonlyUint8Array): Promise<SignatureBytes>;
93

94
/**
95
 * Verify a signature against data and public key
96
 * @param key - CryptoKey containing public key
97
 * @param signature - Signature bytes to verify
98
 * @param data - Original data that was signed as ReadonlyUint8Array
99
 * @returns Promise resolving to true if signature is valid
100
 */
101
function verifySignature(key: CryptoKey, signature: SignatureBytes, data: ReadonlyUint8Array): Promise<boolean>;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { generateKeyPair, signBytes, verifySignature } from "@solana/web3.js";
108

109
// Generate key pair for signing
110
const { privateKey, publicKey } = await generateKeyPair();
111

112
// Sign some data
113
const message = new TextEncoder().encode("Hello, Solana!");
114
const signature = await signBytes(privateKey, message);
115

116
// Verify the signature
117
const isValid = await verifySignature(publicKey, signature, message);
118
console.log("Signature valid:", isValid); // true
119
```
120

121
### Signature Validation
122

123
Utilities for working with signature strings and validation.
124

125
```typescript { .api }
126
/**
127
 * Branded string type for base58-encoded signatures
128
 */
129
type Signature = string & { readonly __brand: unique symbol };
130

131
/**
132
 * Type guard to check if a string is a valid Signature
133
 * @param putativeSignature - String to check
134
 * @returns True if input is a valid Signature
135
 */
136
function isSignature(putativeSignature: string): putativeSignature is Signature;
137

138
/**
139
 * Assert that a string is a valid Signature
140
 * @param putativeSignature - String to assert
141
 * @throws Error if input is not a valid Signature
142
 */
143
function assertIsSignature(putativeSignature: string): asserts putativeSignature is Signature;
144

145
/**
146
 * Convert a string to a Signature type (with validation)
147
 * @param putativeSignature - String to convert
148
 * @returns Signature type
149
 */
150
function signature(putativeSignature: string): Signature;
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { signature, isSignature } from "@solana/web3.js";
157

158
// Convert and validate signature string
159
const signatureString = "2Kb...ABC"; // Base58 signature string
160
const sig = signature(signatureString);
161

162
// Type guard usage
163
if (isSignature(signatureString)) {
164
  console.log("Valid signature format");
165
}
166
```
167

168
## Key Management Best Practices
169

170
### Secure Key Storage
171

172
```typescript
173
import { generateKeyPair } from "@solana/web3.js";
174

175
// Generate key pair
176
const keyPair = await generateKeyPair();
177

178
// For client-side storage (browser)
179
// Store in IndexedDB or secure key management system
180
// NEVER store private keys in localStorage or sessionStorage
181

182
// For server-side storage (Node.js)
183
// Store in encrypted format with proper key derivation
184
// Consider using hardware security modules (HSMs) for production
185
```
186

187
### Key Derivation
188

189
```typescript
190
import { 
191
  createKeyPairFromPrivateKeyBytes,
192
  getAddressFromPublicKey 
193
} from "@solana/web3.js";
194

195
// Derive multiple addresses from a master key
196
async function deriveAddresses(masterPrivateKey: Uint8Array, count: number): Promise<Address[]> {
197
  const addresses: Address[] = [];
198
  
199
  for (let i = 0; i < count; i++) {
200
    // Create deterministic private key (implement your own derivation logic)
201
    const derivedPrivateKey = deriveChildKey(masterPrivateKey, i);
202
    
203
    // Create key pair
204
    const keyPair = await createKeyPairFromPrivateKeyBytes(derivedPrivateKey);
205
    
206
    // Get address
207
    const address = await getAddressFromPublicKey(keyPair.publicKey);
208
    addresses.push(address);
209
  }
210
  
211
  return addresses;
212
}
213
```
214

215
## Types
216

217
```typescript { .api }
218
/**
219
 * Raw signature bytes (64 bytes for Ed25519)
220
 */
221
type SignatureBytes = Uint8Array & { readonly __brand: unique symbol };
222

223
/**
224
 * Branded string type for base58-encoded signatures
225
 */
226
type Signature = string & { readonly __brand: unique symbol };
227
```