0
# Address Management
1

2
SS58 address encoding, decoding, and validation with support for multi-signature and derived addresses. The SS58 format is used across the Polkadot ecosystem for human-readable addresses.
3

4
## Capabilities
5

6
### Encode Address
7

8
Encodes a public key to an SS58 address format with optional network prefix.
9

10
```typescript { .api }
11
/**
12
 * Encode a public key or address to SS58 format
13
 * @param key - The public key or address to encode
14
 * @param ss58Format - Network prefix (default: generic Substrate)
15
 * @returns SS58-encoded address string
16
 */
17
function encodeAddress(key: string | Uint8Array, ss58Format?: number): string;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { encodeAddress, sr25519PairFromSeed } from "@polkadot/util-crypto";
24

25
const seed = new Uint8Array(32); // Your seed
26
const pair = sr25519PairFromSeed(seed);
27

28
// Generic Substrate address (prefix 42)
29
const genericAddress = encodeAddress(pair.publicKey);
30

31
// Polkadot address (prefix 0)
32
const polkadotAddress = encodeAddress(pair.publicKey, 0);
33

34
// Kusama address (prefix 2)
35
const kusamaAddress = encodeAddress(pair.publicKey, 2);
36
```
37

38
### Decode Address
39

40
Decodes an SS58 address to extract the public key bytes.
41

42
```typescript { .api }
43
/**
44
 * Decode an SS58 address to public key bytes
45
 * @param address - SS58 address string to decode
46
 * @param ignoreChecksum - Skip checksum validation (default: false)
47
 * @param prefix - Expected network prefix for validation
48
 * @returns Public key as Uint8Array (32 bytes)
49
 */
50
function decodeAddress(address: string, ignoreChecksum?: boolean, prefix?: number): Uint8Array;
51
```
52

53
**Usage Example:**
54

55
```typescript
56
import { decodeAddress } from "@polkadot/util-crypto";
57

58
const address = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
59
const publicKey = decodeAddress(address);
60
console.log(publicKey.length); // 32
61
```
62

63
### Check Address
64

65
Validates an SS58 address format and checksum.
66

67
```typescript { .api }
68
/**
69
 * Check if an SS58 address is valid
70
 * @param address - Address string to validate
71
 * @param prefix - Expected network prefix for validation
72
 * @returns Tuple of [isValid, errorMessage]
73
 */
74
function checkAddress(address: string, prefix?: number): [boolean, string | null];
75
```
76

77
**Usage Example:**
78

79
```typescript
80
import { checkAddress } from "@polkadot/util-crypto";
81

82
const [isValid, error] = checkAddress("5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY");
83
if (isValid) {
84
  console.log("Valid address");
85
} else {
86
  console.log("Invalid address:", error);
87
}
88
```
89

90
### Address Equality
91

92
Compares two addresses for equality, handling different formats.
93

94
```typescript { .api }
95
/**
96
 * Compare two addresses for equality
97
 * @param a - First address
98
 * @param b - Second address
99
 * @returns true if addresses represent the same public key
100
 */
101
function addressEq(a: string, b: string): boolean;
102
```
103

104
### Is Address
105

106
Checks if a string is a valid SS58 address format.
107

108
```typescript { .api }
109
/**
110
 * Check if string is a valid SS58 address
111
 * @param address - String to check
112
 * @param ignoreChecksum - Skip checksum validation
113
 * @param prefix - Expected network prefix
114
 * @returns true if valid address format
115
 */
116
function isAddress(address: string, ignoreChecksum?: boolean, prefix?: number): boolean;
117
```
118

119
### Validate Address
120

121
Validates an SS58 address and returns detailed information.
122

123
```typescript { .api }
124
/**
125
 * Validate SS58 address with detailed response
126
 * @param address - Address to validate
127
 * @param prefix - Expected network prefix
128
 * @returns Validation result with details
129
 */
130
function validateAddress(address: string, prefix?: number): boolean;
131
```
132

133
### Address Checksum
134

135
Validates the checksum portion of an SS58 address.
136

137
```typescript { .api }
138
/**
139
 * Check SS58 address checksum validity
140
 * @param address - Address to check
141
 * @returns true if checksum is valid
142
 */
143
function checkAddressChecksum(address: string): boolean;
144
```
145

146
### Derive Address
147

148
Derives an SS58 address directly from a public key.
149

150
```typescript { .api }
151
/**
152
 * Derive SS58 address from public key
153
 * @param publicKey - Public key bytes
154
 * @param prefix - Network prefix
155
 * @returns SS58 address string
156
 */
157
function deriveAddress(publicKey: Uint8Array, prefix?: number): string;
158
```
159

160
### Multi-Signature Addresses
161

162
Creates multi-signature addresses from threshold and signatories.
163

164
```typescript { .api }
165
/**
166
 * Create multi-signature key and address
167
 * @param threshold - Minimum required signatures
168
 * @param signatories - Array of public keys or addresses
169
 * @param prefix - Network prefix
170
 * @returns Multi-signature public key
171
 */
172
function createKeyMulti(threshold: number, signatories: (Uint8Array | string)[], prefix?: number): Uint8Array;
173

174
/**
175
 * Encode multi-signature address
176
 * @param who - Threshold and signatories or multi-sig public key
177
 * @param prefix - Network prefix
178
 * @returns Multi-signature address
179
 */
180
function encodeMultiAddress(who: Uint8Array | [number, (Uint8Array | string)[]], prefix?: number): string;
181
```
182

183
### Derived Keys and Addresses
184

185
Creates derived keys and addresses for hierarchical key management.
186

187
```typescript { .api }
188
/**
189
 * Create derived key from public key and chain code
190
 * @param publicKey - Parent public key
191
 * @param chainCode - Chain code for derivation
192
 * @param prefix - Network prefix
193
 * @returns Derived public key
194
 */
195
function createKeyDerived(publicKey: Uint8Array, chainCode: Uint8Array, prefix?: number): Uint8Array;
196

197
/**
198
 * Encode derived address
199
 * @param publicKey - Public key
200
 * @param chainCode - Chain code
201
 * @param prefix - Network prefix
202
 * @returns Derived address
203
 */
204
function encodeDerivedAddress(publicKey: Uint8Array, chainCode: Uint8Array, prefix?: number): string;
205
```
206

207
### Address Utilities
208

209
Additional utilities for address handling.
210

211
```typescript { .api }
212
/**
213
 * Sort addresses array
214
 * @param addresses - Array of addresses to sort
215
 * @param prefix - Network prefix
216
 * @returns Sorted addresses array
217
 */
218
function sortAddresses(addresses: string[], prefix?: number): string[];
219

220
/**
221
 * Set global SS58 format (deprecated)
222
 * @param prefix - Default network prefix
223
 */
224
function setSS58Format(prefix: number): void;
225
```
226

227
### EVM Compatibility
228

229
Functions for converting between SS58 and Ethereum addresses.
230

231
```typescript { .api }
232
/**
233
 * Convert SS58 address to EVM format
234
 * @param address - SS58 address
235
 * @returns EVM address bytes
236
 */
237
function addressToEvm(address: string): Uint8Array;
238

239
/**
240
 * Convert EVM address to SS58 format
241
 * @param evmAddress - EVM address bytes
242
 * @param prefix - SS58 network prefix
243
 * @param hashType - Hash algorithm to use
244
 * @returns SS58 address
245
 */
246
function evmToAddress(evmAddress: Uint8Array, prefix?: number, hashType?: 'blake2' | 'keccak'): string;
247
```
248

249
## Common Network Prefixes
250

251
- **0**: Polkadot
252
- **1**: Bare Sr25519
253
- **2**: Kusama
254
- **5**: Astar
255
- **42**: Generic Substrate (default)
256
- **1284**: Moonbeam
257
- **1285**: Moonriver
258

259
## Notes
260

261
- All public keys should be 32 bytes for sr25519/ed25519 or 33 bytes for secp256k1
262
- Invalid addresses will throw errors during decoding
263
- Checksum validation helps prevent typos in addresses
264
- Multi-signature addresses require careful threshold management