0
# Solana Web3.js
1

2
Solana Web3.js is a comprehensive JavaScript/TypeScript SDK for building Solana blockchain applications. This version 2.0.0 represents a complete ground-up rewrite with modern architecture featuring full tree-shakability, functional programming patterns, composable internals, and zero dependencies. The library leverages native Ed25519 cryptography, bigint support, and Web Crypto APIs for enhanced performance and security.
3

4
## Package Information
5

6
- **Package Name**: @solana/web3.js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @solana/web3.js`
10
- **Supported Environments**: Node.js (>=20.18.0), Web browsers, React Native
11

12
## Core Imports
13

14
```typescript
15
import {
16
  // Core types
17
  Address, Signature, Lamports,
18
  // RPC client
19
  createSolanaRpc, createSolanaRpcSubscriptions,
20
  // Transaction building
21
  createTransactionMessage, compileTransaction,
22
  // Cryptography
23
  generateKeyPair, signBytes, getAddressFromPublicKey,
24
  // High-level utilities
25
  airdropFactory, sendAndConfirmTransactionFactory
26
} from "@solana/web3.js";
27
```
28

29
For CommonJS:
30

31
```javascript
32
const {
33
  createSolanaRpc,
34
  createTransactionMessage,
35
  generateKeyPair
36
} = require("@solana/web3.js");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import {
43
  createSolanaRpc,
44
  createTransactionMessage,
45
  appendTransactionMessageInstructions,
46
  setTransactionMessageFeePayer,
47
  setTransactionMessageLifetimeUsingBlockhash,
48
  compileTransaction,
49
  signTransaction,
50
  generateKeyPair,
51
  getAddressFromPublicKey,
52
  address,
53
  airdropFactory
54
} from "@solana/web3.js";
55

56
// Create RPC client
57
const rpc = createSolanaRpc("https://api.devnet.solana.com");
58

59
// Generate a key pair
60
const { privateKey, publicKey } = await generateKeyPair();
61
const myAddress = await getAddressFromPublicKey(publicKey);
62

63
// Get account info
64
const accountInfo = await rpc.getAccountInfo(myAddress).send();
65

66
// Build transaction using functional composition
67
const { value: { blockhash, lastValidBlockHeight } } = await rpc
68
  .getLatestBlockhash()
69
  .send();
70

71
// Create transaction step by step
72
const message = createTransactionMessage({ version: 0 });
73
const withInstructions = appendTransactionMessageInstructions([
74
  // Your instructions here
75
  {
76
    programId: address("11111111111111111111111111111112"),
77
    accounts: [],
78
    data: new Uint8Array()
79
  }
80
], message);
81
const withFeePayer = setTransactionMessageFeePayer(myAddress, withInstructions);
82
const compilableMessage = setTransactionMessageLifetimeUsingBlockhash(
83
  { blockhash, lastValidBlockHeight },
84
  withFeePayer
85
);
86

87
// Compile and sign transaction
88
const transaction = compileTransaction(compilableMessage);
89
const signedTransaction = await signTransaction([{ privateKey, publicKey }], transaction);
90
```
91

92
## Architecture
93

94
Solana Web3.js is built around several key architectural principles:
95

96
- **Modular Design**: Tree-shakable exports allow selective importing of only needed functionality
97
- **Functional Programming**: Immutable data structures and pure functions throughout
98
- **Type Safety**: Comprehensive TypeScript support with branded types and compile-time error checking
99
- **Factory Pattern**: High-level utilities use factory functions that accept RPC clients and return configured functions
100
- **Codec System**: Complete encoding/decoding framework for all Solana data types
101
- **Zero Dependencies**: Self-contained with no external runtime dependencies
102

103
## Capabilities
104

105
### Core Primitives
106

107
Foundation types and utilities for addresses, signatures, keys, and basic blockchain primitives.
108

109
```typescript { .api }
110
type Address<TAddress = string> = TAddress & { readonly __brand: unique symbol };
111
type Signature = string & { readonly __brand: unique symbol };
112
type Lamports = bigint & { readonly __brand: unique symbol };
113
type TransactionVersion = 0 | "legacy";
114
type Commitment = "processed" | "confirmed" | "finalized";
115

116
function address<TAddress extends string>(input: TAddress): Address<TAddress>;
117
function lamports(input: bigint | number): Lamports;
118
```
119

120
[Core Primitives](./core-primitives.md)
121

122
### Cryptography and Key Management
123

124
Ed25519 key pair generation, digital signatures, and cryptographic operations.
125

126
```typescript { .api }
127
interface CryptoKeyPair {
128
  privateKey: CryptoKey;
129
  publicKey: CryptoKey;
130
}
131

132
function generateKeyPair(): Promise<CryptoKeyPair>;
133
function signBytes(data: Uint8Array, privateKey: CryptoKey): Promise<SignatureBytes>;
134
function verifySignature(signature: SignatureBytes, data: Uint8Array, publicKey: CryptoKey): Promise<boolean>;
135
```
136

137
[Cryptography](./cryptography.md)
138

139
### RPC Communication
140

141
Complete RPC API client with support for all Solana RPC methods, subscriptions, and cluster management.
142

143
```typescript { .api }
144
function createSolanaRpc(url: string, config?: RpcConfig): Rpc<SolanaRpcMethods>;
145
function createSolanaRpcSubscriptions(url: string, config?: RpcSubscriptionsConfig): RpcSubscriptions<SolanaRpcSubscriptionsMethods>;
146

147
interface Commitment {
148
  commitment?: "processed" | "confirmed" | "finalized";
149
}
150
```
151

152
[RPC Communication](./rpc-communication.md)
153

154
### Account Management 
155

156
Account data fetching, parsing, and validation with support for various encoding formats.
157

158
```typescript { .api }
159
interface Account<TData, TAddress = Address> {
160
  address: TAddress;
161
  data: TData;
162
  executable: boolean;
163
  lamports: Lamports;
164
  programId: Address;
165
}
166

167
function fetchEncodedAccount<TAddress extends Address>(
168
  rpc: Rpc<GetAccountInfoApi>,
169
  address: TAddress,
170
  config?: FetchAccountConfig
171
): Promise<Account<Uint8Array, TAddress> | null>;
172
```
173

174
[Account Management](./account-management.md)
175

176
### Transaction Building
177

178
Comprehensive transaction message creation, compilation, and optimization with support for address lookup tables.
179

180
```typescript { .api }
181
interface TransactionMessage<TVersion = TransactionVersion> {
182
  version: TVersion;
183
  feePayer: Address;
184
  blockhash: Blockhash;
185
  instructions: IInstruction[];
186
}
187

188
function createTransactionMessage<TVersion extends TransactionVersion>(
189
  config: TransactionMessageConfig<TVersion>
190
): TransactionMessage<TVersion>;
191

192
function compileTransaction<TVersion extends TransactionVersion>(
193
  transactionMessage: CompilableTransactionMessage<TVersion>
194
): CompiledTransaction<TVersion>;
195
```
196

197
[Transaction Building](./transaction-building.md)
198

199
### Instructions and Programs
200

201
Instruction creation, program interaction, and account metadata management.
202

203
```typescript { .api }
204
interface IInstruction<TProgramAddress = Address> {
205
  programId: TProgramAddress;
206
  accounts?: IAccountMeta[];
207
  data?: Uint8Array;
208
}
209

210
interface IAccountMeta<TAddress = Address> {
211
  address: TAddress;
212
  role: AccountRole;
213
}
214
```
215

216
[Instructions and Programs](./instructions-programs.md)
217

218
### Signing and Authentication
219

220
Transaction and message signing with support for multiple signers and partial signing workflows.
221

222
```typescript { .api }
223
interface TransactionSigner<TAddress = Address> {
224
  address: TAddress;
225
  signTransaction<TTransaction extends TransactionWithSignatures>(
226
    transaction: TTransaction
227
  ): Promise<TTransaction>;
228
}
229

230
function addSigners<T extends TransactionMessage | Transaction>(
231
  transaction: T,
232
  signers: TransactionSigner[]
233
): T;
234
```
235

236
[Signing and Authentication](./signing-authentication.md)
237

238
### Encoding and Codecs
239

240
Comprehensive encoding/decoding system for all Solana data types with support for various formats.
241

242
```typescript { .api }
243
interface Codec<TFrom, TTo = TFrom> {
244
  encode(value: TFrom): TTo;
245
  decode(value: TTo): TFrom;
246
}
247

248
function getU64Codec(): Codec<bigint, Uint8Array>;
249
function getArrayCodec<T>(itemCodec: Codec<T>): Codec<T[]>;
250
function getStructCodec<T>(fields: StructCodecConfig<T>): Codec<T>;
251
```
252

253
[Encoding and Codecs](./encoding-codecs.md)
254

255
### Error Handling
256

257
Structured error system with specific error codes and contextual information for debugging.
258

259
```typescript { .api }
260
class SolanaError extends Error {
261
  readonly code: SolanaErrorCode;
262
  readonly context?: ErrorContext;
263
}
264

265
type SolanaErrorCode = 
266
  | RpcErrorCode
267
  | AddressErrorCode
268
  | AccountErrorCode
269
  | TransactionErrorCode
270
  | CryptoErrorCode;
271
```
272

273
[Error Handling](./error-handling.md)
274

275
### High-Level Utilities
276

277
Ready-to-use utilities for common operations like airdrops, transaction sending, and compute limit estimation.
278

279
```typescript { .api }
280
type AirdropFunction = (config: {
281
  recipientAddress: Address;
282
  lamports: Lamports;
283
  commitment?: Commitment;
284
}) => Promise<Signature>;
285

286
function airdropFactory(config: {
287
  rpc: Rpc<RequestAirdropApi & GetSignatureStatusesApi>;
288
  rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi>;
289
}): AirdropFunction;
290
```
291

292
[High-Level Utilities](./high-level-utilities.md)