0
# Core Primitives
1

2
Foundation types and utilities for addresses, signatures, keys, and basic blockchain primitives in Solana Web3.js.
3

4
## Capabilities
5

6
### Address System
7

8
Addresses in Solana are base58-encoded strings representing account identifiers. The library provides branded types for type safety.
9

10
```typescript { .api }
11
/**
12
 * Branded string type for Solana addresses ensuring type safety
13
 */
14
type Address<TAddress = string> = TAddress & { readonly __brand: unique symbol };
15

16
/**
17
 * Create and validate a Solana address from string
18
 * @param input - Base58-encoded address string
19
 * @returns Validated Address type
20
 * @throws SolanaError if input is not a valid address
21
 */
22
function address<TAddress extends string>(input: TAddress): Address<TAddress>;
23

24
/**
25
 * Type guard to check if a value is a valid Address
26
 * @param input - Value to check
27
 * @returns True if input is an Address
28
 */
29
function isAddress(input: unknown): input is Address;
30

31
/**
32
 * Assert that a value is a valid Address, throwing if not
33
 * @param input - Value to assert
34
 * @throws SolanaError if input is not a valid Address
35
 */
36
function assertIsAddress(input: unknown): asserts input is Address;
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { address, isAddress } from "@solana/web3.js";
43

44
// Create address from string
45
const myAddress = address("11111111111111111111111111111112");
46

47
// Type guard usage
48
if (isAddress(someValue)) {
49
  // someValue is now typed as Address
50
  console.log("Valid address:", someValue);
51
}
52

53
// Assertion usage
54
assertIsAddress(userInput); // Throws if invalid
55
console.log("Definitely an address:", userInput);
56
```
57

58
### Program Derived Addresses (PDAs)
59

60
PDAs are deterministic addresses derived from program IDs and seeds, used for programmatic account management.
61

62
```typescript { .api }
63
/**
64
 * Program derived address with its bump seed
65
 */
66
type ProgramDerivedAddress<TAddress = Address> = readonly [TAddress, ProgramDerivedAddressBump];
67

68
/**
69
 * Bump seed value for PDA derivation (0-255)
70
 */
71
type ProgramDerivedAddressBump = number & { readonly __brand: unique symbol };
72

73
/**
74
 * Derive a Program Derived Address from seeds and program ID
75
 * @param config - Seeds and program ID for derivation
76
 * @returns PDA tuple with address and bump
77
 */
78
function getProgramDerivedAddress(config: {
79
  seeds: Uint8Array[];
80
  programId: Address;
81
}): Promise<ProgramDerivedAddress>;
82

83
/**
84
 * Type guard for Program Derived Addresses
85
 * @param input - Value to check
86
 * @returns True if input is a PDA
87
 */
88
function isProgramDerivedAddress(input: unknown): input is ProgramDerivedAddress;
89

90
/**
91
 * Create address using seed derivation
92
 * @param config - Base address, seed, and program ID
93
 * @returns Derived address
94
 */
95
function createAddressWithSeed(config: {
96
  baseAddress: Address;
97
  seed: string;
98
  programId: Address;
99
}): Address;
100
```
101

102
### Signature System
103

104
Digital signatures for transaction and message authentication using Ed25519 cryptography.
105

106
```typescript { .api }
107
/**
108
 * Branded string type for Ed25519 signatures
109
 */
110
type Signature = string & { readonly __brand: unique symbol };
111

112
/**
113
 * Raw signature bytes (64 bytes for Ed25519)
114
 */
115
type SignatureBytes = Uint8Array & { readonly __brand: unique symbol };
116

117
/**
118
 * Type guard to check if a value is a valid Signature
119
 * @param input - Value to check
120
 * @returns True if input is a Signature
121
 */
122
function isSignature(input: unknown): input is Signature;
123

124
/**
125
 * Assert that a value is a valid Signature
126
 * @param input - Value to assert
127
 * @throws SolanaError if input is not a valid Signature
128
 */
129
function assertIsSignature(input: unknown): asserts input is Signature;
130
```
131

132
### Lamports (SOL Units)
133

134
Lamports are the smallest unit of SOL, with 1 SOL = 1 billion lamports.
135

136
```typescript { .api }
137
/**
138
 * Branded bigint type for lamport amounts ensuring precision
139
 */
140
type Lamports = bigint & { readonly __brand: unique symbol };
141

142
/**
143
 * Create lamports amount from number or bigint
144
 * @param input - Amount in lamports
145
 * @returns Branded Lamports type
146
 */
147
function lamports(input: bigint | number): Lamports;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import { lamports } from "@solana/web3.js";
154

155
// Create lamport amounts
156
const oneSOL = lamports(1_000_000_000n);
157
const halfSOL = lamports(500_000_000);
158

159
// Arithmetic operations preserve type safety
160
const total = lamports(BigInt(oneSOL) + BigInt(halfSOL));
161
```
162

163
### Slot and Timestamp Types
164

165
Blockchain-specific numeric types for slots and timestamps.
166

167
```typescript { .api }
168
/**
169
 * Branded bigint for Solana slot numbers
170
 */
171
type Slot = bigint & { readonly __brand: unique symbol };
172

173
/**
174
 * Branded bigint for Unix timestamps
175
 */
176
type UnixTimestamp = bigint & { readonly __brand: unique symbol };
177
```
178

179
### Blockhash System
180

181
Block identifiers used for transaction lifetime management.
182

183
```typescript { .api }
184
/**
185
 * Branded string type for block hashes
186
 */
187
type Blockhash = string & { readonly __brand: unique symbol };
188
```
189

190
### Commitment Levels
191

192
Transaction and account state confirmation levels.
193

194
```typescript { .api }
195
/**
196
 * Commitment level for RPC requests
197
 */
198
type Commitment = "processed" | "confirmed" | "finalized";
199

200
/**
201
 * Commitment configuration object
202
 */
203
interface CommitmentConfig {
204
  commitment?: Commitment;
205
}
206
```
207

208
**Usage Examples:**
209

210
```typescript
211
import { createSolanaRpc } from "@solana/web3.js";
212

213
const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
214

215
// Use different commitment levels
216
const processedInfo = await rpc.getAccountInfo(address, {
217
  commitment: "processed"
218
}).send();
219

220
const finalizedInfo = await rpc.getAccountInfo(address, {
221
  commitment: "finalized"
222
}).send();
223
```
224

225
## Address Codec System
226

227
Advanced address encoding and decoding utilities.
228

229
```typescript { .api }
230
/**
231
 * Get encoder for Address types
232
 * @returns Codec encoder for addresses
233
 */
234
function getAddressEncoder(): Encoder<Address, Uint8Array>;
235

236
/**
237
 * Get decoder for Address types
238
 * @returns Codec decoder for addresses
239
 */
240
function getAddressDecoder(): Decoder<Uint8Array, Address>;
241

242
/**
243
 * Get combined codec for Address types
244
 * @returns Full address codec for encoding/decoding
245
 */
246
function getAddressCodec(): Codec<Address, Uint8Array>;
247

248
/**
249
 * Get comparison function for addresses
250
 * @returns Function to compare two addresses
251
 */
252
function getAddressComparator(): (a: Address, b: Address) => number;
253
```
254

255
## Cryptographic Utilities
256

257
Low-level cryptographic utilities for address validation.
258

259
```typescript { .api }
260
/**
261
 * Check if compressed point bytes represent a valid curve point
262
 * @param bytes - 32-byte compressed point
263
 * @returns True if bytes are on the Ed25519 curve
264
 */
265
function compressedPointBytesAreOnCurve(bytes: Uint8Array): boolean;
266

267
/**
268
 * Convert CryptoKey public key to Address
269
 * @param publicKey - CryptoKey containing public key
270
 * @returns Solana address derived from public key
271
 */
272
function getAddressFromPublicKey(publicKey: CryptoKey): Promise<Address>;
273
```
274

275
## Types
276

277
```typescript { .api }
278
/**
279
 * Configuration for address validation
280
 */
281
interface AddressConfig {
282
  /**
283
   * Whether to perform strict validation
284
   * @default true
285
   */
286
  strict?: boolean;
287
}
288

289
/**
290
 * Result of address operations
291
 */
292
interface AddressResult<T = Address> {
293
  /**
294
   * The validated address
295
   */
296
  address: T;
297
  /**
298
   * Whether validation was successful
299
   */
300
  valid: boolean;
301
  /**
302
   * Error message if validation failed
303
   */
304
  error?: string;
305
}
306
```