1---
2title: Codecs Reference
3description: Data encoding and decoding patterns for numbers, strings, structs, arrays, enums, discriminated unions, and common account/instruction codecs.
4---
5 
6# Solana Kit Codecs Reference
7 
8## Direction
9 
10- **`encode()`**: values → `Uint8Array`
11- **`decode()`**: `Uint8Array` → values
12 
13## Codec Types
14 
15```ts
16// Full codec
17const codec: Codec<number> = getU32Codec();
18codec.encode(42);     // Uint8Array
19codec.decode(bytes);  // number
20 
21// Encoder only (tree-shaking)
22const encoder: Encoder<number> = getU32Encoder();
23 
24// Decoder only
25const decoder: Decoder<number> = getU32Decoder();
26```
27 
28## Number Codecs
29 
30```ts
31// Unsigned
32getU8Codec();   // 1 byte
33getU16Codec();  // 2 bytes (little-endian default)
34getU32Codec();  // 4 bytes
35getU64Codec();  // 8 bytes (bigint)
36getU128Codec(); // 16 bytes (bigint)
37 
38// Signed
39getI8Codec();  getI16Codec();  getI32Codec();  getI64Codec();
40 
41// Float
42getF32Codec();  getF64Codec();
43 
44// Big-endian
45getU16Codec({ endian: Endian.Big });
46```
47 
48## String Codecs
49 
50```ts
51// UTF-8 (variable)
52const utf8 = getUtf8Codec();
53 
54// With size prefix (common)
55const prefixed = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
56 
57// Fixed size
58const fixed = fixCodecSize(getUtf8Codec(), 32);
59 
60// Base58 (addresses)
61const base58 = getBase58Codec();
62```
63 
64## Struct Codec
65 
66```ts
67type MyStruct = { id: number; name: string; balance: bigint };
68 
69const codec = getStructCodec([
70  ['id', getU32Codec()],
71  ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
72  ['balance', getU64Codec()],
73]);
74 
75const bytes = codec.encode({ id: 1, name: 'Alice', balance: 1000n });
76const data = codec.decode(bytes);
77```
78 
79## Array & Tuple
80 
81```ts
82// Array with size prefix
83const arr = addCodecSizePrefix(getArrayCodec(getU32Codec()), getU32Codec());
84 
85// Fixed array
86const fixed = fixCodecSize(getArrayCodec(getU32Codec()), 10);
87 
88// Tuple
89const point = getTupleCodec([getI32Codec(), getI32Codec()]);
90```
91 
92## Enum
93 
94```ts
95enum Direction { Up, Down, Left, Right }
96const codec = getEnumCodec(Direction);
97codec.encode(Direction.Up);  // [0]
98```
99 
100## Discriminated Union
101 
102```ts
103type Shape =
104  | { __kind: 'circle'; radius: number }
105  | { __kind: 'rectangle'; width: number; height: number };
106 
107const codec = getDiscriminatedUnionCodec([
108  ['circle', getStructCodec([['radius', getU32Codec()]])],
109  ['rectangle', getStructCodec([
110    ['width', getU32Codec()],
111    ['height', getU32Codec()],
112  ])],
113]);
114```
115 
116## Boolean & Nullable
117 
118```ts
119const bool = getBooleanCodec();        // 1 byte
120const u32Bool = getBooleanCodec({ size: 4 });
121 
122const nullable = getNullableCodec(getU32Codec());
123nullable.encode(null);  // [0]
124nullable.encode(42);    // [1, 42, 0, 0, 0]
125```
126 
127## Options (Rust Option)
128 
129```ts
130import { some, none, isSome, getOptionCodec } from '@solana/options';
131 
132const opt = getOptionCodec(getU32Codec());
133opt.encode(some(42));  // [1, 42, 0, 0, 0]
134opt.encode(none());    // [0]
135```
136 
137## Bytes
138 
139```ts
140const bytes = getBytesCodec();
141const fixed32 = fixCodecSize(getBytesCodec(), 32);  // pubkeys
142```
143 
144## Composition Helpers
145 
146```ts
147// Size prefix
148const prefixed = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
149 
150// Fixed size
151const fixed = fixCodecSize(getUtf8Codec(), 32);
152 
153// Transform
154const upper = transformCodec(
155  getUtf8Codec(),
156  (v) => v.toUpperCase(),  // before encode
157  (v) => v.toLowerCase(),  // after decode
158);
159 
160// Offset
161const offset = offsetCodec(getU32Codec(), { preOffset: 4 });
162```
163 
164## Common Patterns
165 
166### Account Decoder
167 
168```ts
169const tokenDecoder: Decoder<TokenAccount> = getStructDecoder([
170  ['mint', fixDecoderSize(getBytesDecoder(), 32)],
171  ['owner', fixDecoderSize(getBytesDecoder(), 32)],
172  ['amount', getU64Decoder()],
173  ['delegate', getOptionDecoder(fixDecoderSize(getBytesDecoder(), 32))],
174  ['state', getU8Decoder()],
175]);
176```
177 
178### Instruction Encoder
179 
180```ts
181const transferEncoder: Encoder<{ discriminator: number; amount: bigint }> =
182  getStructEncoder([
183    ['discriminator', getU8Encoder()],
184    ['amount', getU64Encoder()],
185  ]);
186 
187const data = transferEncoder.encode({ discriminator: 3, amount: 1000000n });
188```