0
# Encoding and Codecs
1

2
Comprehensive encoding/decoding system for all Solana data types with support for various formats, data structures, and binary serialization.
3

4
## Capabilities
5

6
### Core Codec System
7

8
Foundation interfaces for encoding and decoding data.
9

10
```typescript { .api }
11
/**
12
 * Bidirectional encoder/decoder interface
13
 */
14
interface Codec<TFrom, TTo = TFrom> {
15
  encode(value: TFrom): TTo;
16
  decode(value: TTo): TFrom;
17
}
18

19
/**
20
 * One-way encoding interface
21
 */
22
interface Encoder<TFrom, TTo = TFrom> {
23
  encode(value: TFrom): TTo;
24
}
25

26
/**
27
 * One-way decoding interface
28
 */
29
interface Decoder<TFrom, TTo = TFrom> {
30
  decode(value: TFrom): TTo;
31
}
32

33
/**
34
 * Fixed-size codec with known byte length
35
 */
36
interface FixedSizeCodec<TFrom, TTo = TFrom> extends Codec<TFrom, TTo> {
37
  fixedSize: number;
38
}
39

40
/**
41
 * Variable-size codec with dynamic length
42
 */
43
interface VariableSizeCodec<TFrom, TTo = TFrom> extends Codec<TFrom, TTo> {
44
  getSizeFromValue(value: TFrom): number;
45
  maxSize?: number;
46
}
47

48
/**
49
 * Immutable byte array type
50
 */
51
type ReadonlyUint8Array = Readonly<Uint8Array>;
52
```
53

54
### Codec Utilities
55

56
Transform and compose codecs for complex data structures.
57

58
```typescript { .api }
59
/**
60
 * Combine separate encoder and decoder into codec
61
 * @param encoder - Encoder function
62
 * @param decoder - Decoder function
63
 * @returns Combined codec
64
 */
65
function combineCodec<TFrom, TTo>(
66
  encoder: Encoder<TFrom, TTo>,
67
  decoder: Decoder<TTo, TFrom>
68
): Codec<TFrom, TTo>;
69

70
/**
71
 * Fix codec to specific byte size
72
 * @param codec - Codec to fix size
73
 * @param size - Fixed size in bytes
74
 * @returns Fixed-size codec
75
 */
76
function fixCodecSize<TFrom, TTo>(
77
  codec: Codec<TFrom, TTo>,
78
  size: number
79
): FixedSizeCodec<TFrom, TTo>;
80

81
/**
82
 * Transform codec values through mapping functions
83
 * @param codec - Base codec
84
 * @param transform - Transform functions
85
 * @returns Transformed codec
86
 */
87
function transformCodec<TFrom, TTo, UFrom, UTo>(
88
  codec: Codec<TFrom, TTo>,
89
  transform: {
90
    encode: (value: UFrom) => TFrom;
91
    decode: (value: TTo) => UTo;
92
  }
93
): Codec<UFrom, UTo>;
94

95
/**
96
 * Reverse byte order in codec output
97
 * @param codec - Codec to reverse
98
 * @returns Codec with reversed byte order
99
 */
100
function reverseCodec<T>(codec: Codec<T, Uint8Array>): Codec<T, Uint8Array>;
101

102
/**
103
 * Add padding to codec output
104
 * @param codec - Codec to pad
105
 * @param size - Target size with padding
106
 * @returns Padded codec
107
 */
108
function padCodec<T>(codec: Codec<T, Uint8Array>, size: number): Codec<T, Uint8Array>;
109
```
110

111
### Number Codecs
112

113
Encode/decode numeric types with various sizes and endianness.
114

115
```typescript { .api }
116
/**
117
 * Unsigned 8-bit integer codec
118
 */
119
function getU8Codec(): FixedSizeCodec<number, Uint8Array>;
120

121
/**
122
 * Unsigned 16-bit integer codec
123
 */
124
function getU16Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
125

126
/**
127
 * Unsigned 32-bit integer codec
128
 */
129
function getU32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
130

131
/**
132
 * Unsigned 64-bit integer codec
133
 */
134
function getU64Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;
135

136
/**
137
 * Unsigned 128-bit integer codec
138
 */
139
function getU128Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;
140

141
/**
142
 * Signed 8-bit integer codec
143
 */
144
function getI8Codec(): FixedSizeCodec<number, Uint8Array>;
145

146
/**
147
 * Signed 16-bit integer codec
148
 */
149
function getI16Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
150

151
/**
152
 * Signed 32-bit integer codec
153
 */
154
function getI32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
155

156
/**
157
 * Signed 64-bit integer codec
158
 */
159
function getI64Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;
160

161
/**
162
 * 32-bit floating point codec
163
 */
164
function getF32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
165

166
/**
167
 * 64-bit floating point codec
168
 */
169
function getF64Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;
170

171
/**
172
 * Compact 16-bit integer codec (variable length)
173
 */
174
function getShortU16Codec(): VariableSizeCodec<number, Uint8Array>;
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
import { getU64Codec, getU32Codec } from "@solana/web3.js";
181

182
// Encode numbers to bytes
183
const u64Codec = getU64Codec();
184
const lamportsBytes = u64Codec.encode(1000000000n);
185
console.log("Encoded lamports:", lamportsBytes);
186

187
// Decode bytes back to numbers
188
const decodedLamports = u64Codec.decode(lamportsBytes);
189
console.log("Decoded lamports:", decodedLamports);
190

191
// Combine multiple number codecs
192
const u32Codec = getU32Codec();
193
const blockHeight = u32Codec.encode(150000000);
194
```
195

196
### String Codecs
197

198
Encode/decode strings and text with various base encodings.
199

200
```typescript { .api }
201
/**
202
 * UTF-8 string codec
203
 */
204
function getUtf8Codec(): VariableSizeCodec<string, Uint8Array>;
205

206
/**
207
 * Base58 encoding codec
208
 */
209
function getBase58Codec(): Codec<string, Uint8Array>;
210

211
/**
212
 * Base64 encoding codec
213
 */
214
function getBase64Codec(): Codec<string, Uint8Array>;
215

216
/**
217
 * Base16 (hexadecimal) encoding codec
218
 */
219
function getBase16Codec(): Codec<string, Uint8Array>;
220

221
/**
222
 * Base10 (decimal) encoding codec
223
 */
224
function getBase10Codec(): Codec<string, Uint8Array>;
225

226
/**
227
 * Custom base encoding codec
228
 * @param alphabet - Character alphabet for encoding
229
 * @returns BaseX codec
230
 */
231
function getBaseXCodec(alphabet: string): Codec<string, Uint8Array>;
232

233
/**
234
 * Null-terminated string codec
235
 */
236
function getNullCharactersCodec(): VariableSizeCodec<string, Uint8Array>;
237
```
238

239
**Usage Examples:**
240

241
```typescript
242
import { getBase58Codec, getUtf8Codec } from "@solana/web3.js";
243

244
// Encode/decode addresses
245
const base58Codec = getBase58Codec();
246
const addressBytes = base58Codec.encode("11111111111111111111111111111112");
247
const decodedAddress = base58Codec.decode(addressBytes);
248

249
// Encode/decode text data
250
const utf8Codec = getUtf8Codec();
251
const textBytes = utf8Codec.encode("Hello, Solana!");
252
const decodedText = utf8Codec.decode(textBytes);
253
```
254

255
### Data Structure Codecs
256

257
Encode complex data structures like arrays, objects, and unions.
258

259
```typescript { .api }
260
/**
261
 * Array codec for homogeneous collections
262
 * @param itemCodec - Codec for array items
263
 * @param config - Optional array configuration
264
 * @returns Array codec
265
 */
266
function getArrayCodec<T>(
267
  itemCodec: Codec<T, Uint8Array>,
268
  config?: {
269
    size?: FixedSizeCodec<number, Uint8Array> | number;
270
  }
271
): VariableSizeCodec<T[], Uint8Array>;
272

273
/**
274
 * Set codec for unique collections
275
 * @param itemCodec - Codec for set items
276
 * @returns Set codec
277
 */
278
function getSetCodec<T>(
279
  itemCodec: Codec<T, Uint8Array>
280
): VariableSizeCodec<Set<T>, Uint8Array>;
281

282
/**
283
 * Map codec for key-value pairs
284
 * @param keyCodec - Codec for keys
285
 * @param valueCodec - Codec for values
286
 * @returns Map codec
287
 */
288
function getMapCodec<K, V>(
289
  keyCodec: Codec<K, Uint8Array>,
290
  valueCodec: Codec<V, Uint8Array>
291
): VariableSizeCodec<Map<K, V>, Uint8Array>;
292

293
/**
294
 * Struct codec for object types
295
 * @param fields - Field codecs
296
 * @returns Struct codec
297
 */
298
function getStructCodec<T>(
299
  fields: StructCodecConfig<T>
300
): FixedSizeCodec<T, Uint8Array> | VariableSizeCodec<T, Uint8Array>;
301

302
/**
303
 * Tuple codec for fixed arrays
304
 * @param codecs - Codecs for tuple elements
305
 * @returns Tuple codec
306
 */
307
function getTupleCodec<T extends readonly unknown[]>(
308
  codecs: TupleCodecConfig<T>
309
): FixedSizeCodec<T, Uint8Array>;
310

311
/**
312
 * Enum codec for discriminated unions
313
 * @param variants - Variant configurations
314
 * @returns Enum codec
315
 */
316
function getEnumCodec<T>(
317
  variants: EnumCodecConfig<T>
318
): VariableSizeCodec<T, Uint8Array>;
319

320
/**
321
 * Union codec for tagged unions
322
 * @param variants - Union variant codecs
323
 * @returns Union codec
324
 */
325
function getUnionCodec<T>(
326
  variants: UnionCodecConfig<T>
327
): VariableSizeCodec<T, Uint8Array>;
328
```
329

330
**Usage Examples:**
331

332
```typescript
333
import { 
334
  getStructCodec, 
335
  getArrayCodec, 
336
  getU64Codec,
337
  getUtf8Codec,
338
  getAddressCodec
339
} from "@solana/web3.js";
340

341
// Define token account structure
342
interface TokenAccount {
343
  mint: Address;
344
  owner: Address;
345
  amount: bigint;
346
  state: number;
347
}
348

349
// Create struct codec
350
const tokenAccountCodec = getStructCodec({
351
  mint: getAddressCodec(),
352
  owner: getAddressCodec(), 
353
  amount: getU64Codec(),
354
  state: getU8Codec()
355
});
356

357
// Encode token account
358
const tokenAccount: TokenAccount = {
359
  mint: address("mint-address"),
360
  owner: address("owner-address"),
361
  amount: 1000000n,
362
  state: 1
363
};
364

365
const encodedAccount = tokenAccountCodec.encode(tokenAccount);
366
const decodedAccount = tokenAccountCodec.decode(encodedAccount);
367
```
368

369
### Optional and Nullable Types
370

371
Handle optional values and null types.
372

373
```typescript { .api }
374
/**
375
 * Option type for optional values
376
 */
377
type Option<T> = { __kind: 'Some'; value: T } | { __kind: 'None' };
378

379
/**
380
 * Create Some option value
381
 * @param value - Value to wrap
382
 * @returns Some option
383
 */
384
function option<T>(value: T): Option<T>;
385

386
/**
387
 * Create None option value
388
 * @returns None option
389
 */
390
function none<T>(): Option<T>;
391

392
/**
393
 * Check if option is Some
394
 * @param option - Option to check
395
 * @returns True if Some
396
 */
397
function isSome<T>(option: Option<T>): option is { __kind: 'Some'; value: T };
398

399
/**
400
 * Check if option is None
401
 * @param option - Option to check
402
 * @returns True if None
403
 */
404
function isNone<T>(option: Option<T>): option is { __kind: 'None' };
405

406
/**
407
 * Option codec for optional values
408
 * @param itemCodec - Codec for the wrapped value
409
 * @returns Option codec
410
 */
411
function getOptionCodec<T>(
412
  itemCodec: Codec<T, Uint8Array>
413
): VariableSizeCodec<Option<T>, Uint8Array>;
414

415
/**
416
 * Nullable codec (null | T)
417
 * @param itemCodec - Codec for non-null value
418
 * @returns Nullable codec
419
 */
420
function getNullableCodec<T>(
421
  itemCodec: Codec<T, Uint8Array>
422
): VariableSizeCodec<T | null, Uint8Array>;
423
```
424

425
### Specialized Codecs
426

427
Additional codec types for specific use cases.
428

429
```typescript { .api }
430
/**
431
 * Boolean codec
432
 */
433
function getBooleanCodec(): FixedSizeCodec<boolean, Uint8Array>;
434

435
/**
436
 * Raw bytes codec
437
 */
438
function getBytesCodec(): Codec<Uint8Array, Uint8Array>;
439

440
/**
441
 * Bit array codec
442
 * @param size - Number of bits
443
 * @returns Bit array codec
444
 */
445
function getBitArrayCodec(size: number): FixedSizeCodec<boolean[], Uint8Array>;
446

447
/**
448
 * Constant value codec
449
 * @param value - Constant value
450
 * @returns Constant codec
451
 */
452
function getConstantCodec<T>(value: T): FixedSizeCodec<T, Uint8Array>;
453

454
/**
455
 * Unit codec (no data)
456
 */
457
function getUnitCodec(): FixedSizeCodec<void, Uint8Array>;
458
```
459

460
## Configuration Types
461

462
```typescript { .api }
463
/**
464
 * Struct codec field configuration
465
 */
466
type StructCodecConfig<T> = {
467
  [K in keyof T]: Codec<T[K], Uint8Array>;
468
};
469

470
/**
471
 * Tuple codec configuration
472
 */
473
type TupleCodecConfig<T extends readonly unknown[]> = {
474
  [K in keyof T]: Codec<T[K], Uint8Array>;
475
};
476

477
/**
478
 * Enum variant configuration
479
 */
480
type EnumCodecConfig<T> = {
481
  [K in keyof T]: {
482
    discriminator?: number;
483
    codec?: Codec<T[K], Uint8Array>;
484
  };
485
};
486

487
/**
488
 * Union variant configuration
489
 */
490
type UnionCodecConfig<T> = Array<{
491
  tag: string | number;
492
  codec: Codec<T, Uint8Array>;
493
}>;
494

495
/**
496
 * Codec size information
497
 */
498
interface CodecSizeInfo {
499
  /** Fixed size in bytes, or null if variable */
500
  size: number | null;
501
  /** Maximum size for variable codecs */
502
  maxSize?: number;
503
  /** Minimum size for variable codecs */
504
  minSize?: number;
505
}
506
```