or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-management.mdcore-primitives.mdcryptography.mdencoding-codecs.mderror-handling.mdhigh-level-utilities.mdindex.mdinstructions-programs.mdrpc-communication.mdsigning-authentication.mdtransaction-building.md
tile.json

tessl/npm-solana--web3-js

Comprehensive JavaScript SDK for building Solana blockchain applications with modern architecture and type safety

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@solana/web3.js@2.0.x

To install, run

npx @tessl/cli install tessl/npm-solana--web3-js@2.0.0

index.mddocs/

Solana Web3.js

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.

Package Information

  • Package Name: @solana/web3.js
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @solana/web3.js
  • Supported Environments: Node.js (>=20.18.0), Web browsers, React Native

Core Imports

import {
  // Core types
  Address, Signature, Lamports,
  // RPC client
  createSolanaRpc, createSolanaRpcSubscriptions,
  // Transaction building
  createTransactionMessage, compileTransaction,
  // Cryptography
  generateKeyPair, signBytes, getAddressFromPublicKey,
  // High-level utilities
  airdropFactory, sendAndConfirmTransactionFactory
} from "@solana/web3.js";

For CommonJS:

const {
  createSolanaRpc,
  createTransactionMessage,
  generateKeyPair
} = require("@solana/web3.js");

Basic Usage

import {
  createSolanaRpc,
  createTransactionMessage,
  appendTransactionMessageInstructions,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  compileTransaction,
  signTransaction,
  generateKeyPair,
  getAddressFromPublicKey,
  address,
  airdropFactory
} from "@solana/web3.js";

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

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

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

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

// Create transaction step by step
const message = createTransactionMessage({ version: 0 });
const withInstructions = appendTransactionMessageInstructions([
  // Your instructions here
  {
    programId: address("11111111111111111111111111111112"),
    accounts: [],
    data: new Uint8Array()
  }
], message);
const withFeePayer = setTransactionMessageFeePayer(myAddress, withInstructions);
const compilableMessage = setTransactionMessageLifetimeUsingBlockhash(
  { blockhash, lastValidBlockHeight },
  withFeePayer
);

// Compile and sign transaction
const transaction = compileTransaction(compilableMessage);
const signedTransaction = await signTransaction([{ privateKey, publicKey }], transaction);

Architecture

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

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

Capabilities

Core Primitives

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

type Address<TAddress = string> = TAddress & { readonly __brand: unique symbol };
type Signature = string & { readonly __brand: unique symbol };
type Lamports = bigint & { readonly __brand: unique symbol };
type TransactionVersion = 0 | "legacy";
type Commitment = "processed" | "confirmed" | "finalized";

function address<TAddress extends string>(input: TAddress): Address<TAddress>;
function lamports(input: bigint | number): Lamports;

Core Primitives

Cryptography and Key Management

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

interface CryptoKeyPair {
  privateKey: CryptoKey;
  publicKey: CryptoKey;
}

function generateKeyPair(): Promise<CryptoKeyPair>;
function signBytes(data: Uint8Array, privateKey: CryptoKey): Promise<SignatureBytes>;
function verifySignature(signature: SignatureBytes, data: Uint8Array, publicKey: CryptoKey): Promise<boolean>;

Cryptography

RPC Communication

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

function createSolanaRpc(url: string, config?: RpcConfig): Rpc<SolanaRpcMethods>;
function createSolanaRpcSubscriptions(url: string, config?: RpcSubscriptionsConfig): RpcSubscriptions<SolanaRpcSubscriptionsMethods>;

interface Commitment {
  commitment?: "processed" | "confirmed" | "finalized";
}

RPC Communication

Account Management

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

interface Account<TData, TAddress = Address> {
  address: TAddress;
  data: TData;
  executable: boolean;
  lamports: Lamports;
  programId: Address;
}

function fetchEncodedAccount<TAddress extends Address>(
  rpc: Rpc<GetAccountInfoApi>,
  address: TAddress,
  config?: FetchAccountConfig
): Promise<Account<Uint8Array, TAddress> | null>;

Account Management

Transaction Building

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

interface TransactionMessage<TVersion = TransactionVersion> {
  version: TVersion;
  feePayer: Address;
  blockhash: Blockhash;
  instructions: IInstruction[];
}

function createTransactionMessage<TVersion extends TransactionVersion>(
  config: TransactionMessageConfig<TVersion>
): TransactionMessage<TVersion>;

function compileTransaction<TVersion extends TransactionVersion>(
  transactionMessage: CompilableTransactionMessage<TVersion>
): CompiledTransaction<TVersion>;

Transaction Building

Instructions and Programs

Instruction creation, program interaction, and account metadata management.

interface IInstruction<TProgramAddress = Address> {
  programId: TProgramAddress;
  accounts?: IAccountMeta[];
  data?: Uint8Array;
}

interface IAccountMeta<TAddress = Address> {
  address: TAddress;
  role: AccountRole;
}

Instructions and Programs

Signing and Authentication

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

interface TransactionSigner<TAddress = Address> {
  address: TAddress;
  signTransaction<TTransaction extends TransactionWithSignatures>(
    transaction: TTransaction
  ): Promise<TTransaction>;
}

function addSigners<T extends TransactionMessage | Transaction>(
  transaction: T,
  signers: TransactionSigner[]
): T;

Signing and Authentication

Encoding and Codecs

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

interface Codec<TFrom, TTo = TFrom> {
  encode(value: TFrom): TTo;
  decode(value: TTo): TFrom;
}

function getU64Codec(): Codec<bigint, Uint8Array>;
function getArrayCodec<T>(itemCodec: Codec<T>): Codec<T[]>;
function getStructCodec<T>(fields: StructCodecConfig<T>): Codec<T>;

Encoding and Codecs

Error Handling

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

class SolanaError extends Error {
  readonly code: SolanaErrorCode;
  readonly context?: ErrorContext;
}

type SolanaErrorCode = 
  | RpcErrorCode
  | AddressErrorCode
  | AccountErrorCode
  | TransactionErrorCode
  | CryptoErrorCode;

Error Handling

High-Level Utilities

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

type AirdropFunction = (config: {
  recipientAddress: Address;
  lamports: Lamports;
  commitment?: Commitment;
}) => Promise<Signature>;

function airdropFactory(config: {
  rpc: Rpc<RequestAirdropApi & GetSignatureStatusesApi>;
  rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi>;
}): AirdropFunction;

High-Level Utilities