Client side
Suggest an editThe code that talks to your program builds transactions, sends them to the network, fetches account data, and connects users' wallets. That client code is TypeScript, where the most mature libraries and the most production code live. The client also decides which accounts each instruction receives, so the program cannot assume they are the right ones.
The client builds the instruction and picks its accounts
An instruction has three parts: the address of the program to call, an ordered list of accounts with a signer flag and a writable flag on each, and the bytes of instruction data. The instructions and transactions lesson covers the format. The client assembles all three. With @solana/web3.js, the base client library, a call to the deposit instruction from the program structure lesson looks like this:
// Without Anchor: assemble the instruction from raw parts
const instruction = new TransactionInstruction({
programId: new PublicKey("Fg6PaFpoGXkYsidMpWxqSWPg2J9eRMK8RnPwYxNb8nN"),
keys: [
{ pubkey: vault, isSigner: false, isWritable: true },
{ pubkey: user.publicKey, isSigner: true, isWritable: false },
],
data: Buffer.concat([
Buffer.from([242, 35, 198, 137, 82, 225, 242, 182]), // discriminator of deposit
new BN(100).toArrayLike(Buffer, "le", 8), // amount
]),
});The data starts with the discriminator, 8 bytes that tell an Anchor program which instruction to run, and the arguments follow it. The IDL lists the discriminator of every instruction.
The program takes no part in building this object. Whoever writes the client fills the keys array, so they decide which account lands in each position. Your own frontend passes the accounts you intended. An attacker writes a different client and passes whatever accounts help them, and the program receives both lists in the same form. The program does not choose its accounts, so it has to check them, and that is the job of the types and constraints on every field of an Accounts struct.
The Anchor client builds the instruction from the IDL
@coral-xyz/anchor, the client SDK for Anchor, wraps web3.js. It reads the program's IDL and gives you a typed method for every instruction, so you don't construct raw TransactionInstruction objects by hand:
import { Program, BN } from "@coral-xyz/anchor";
import type { MyProgram } from "./target/types/my_program";
import IDL from "./target/idl/my_program.json";
const program = new Program<MyProgram>(IDL, provider);
// Typed method calls. The compiler knows the instruction takes a u64,
// the field names of `.accounts()` come from the IDL, everything checks.
await program.methods
.deposit(new BN(100))
.accounts({
vault,
depositor: user.publicKey,
})
.rpc();You write less code, and TypeScript catches your mistakes at compile time instead of letting them fail at runtime in production. The types come from target/types/my_program.ts, which anchor build writes next to the IDL. Without the <MyProgram> type parameter, program.methods accepts any arguments. The client still picks the accounts: .accounts({...}) is the same list, with field names from the IDL in place of positions. vault is the address of a Vault account the program created earlier.
The provider passed to Program holds the two things every call needs: a connection to an RPC node and a wallet that signs.
Every request goes through a connection to an RPC node
The Connection is a thin wrapper around the JSON-RPC API the validator exposes. Fetching account data, sending transactions, and subscribing to changes all go through this object. A script builds the provider from a connection and a keypair it loads from a file:
import { readFileSync } from "fs";
import { Connection, Keypair, clusterApiUrl } from "@solana/web3.js";
import { AnchorProvider, Wallet } from "@coral-xyz/anchor";
// Connect to devnet, the public testing cluster.
const connection = new Connection(clusterApiUrl("devnet"), "confirmed");
// Load the keypair that signs and pays fees. Keypair.generate() makes a new one.
const user = Keypair.fromSecretKey(
Uint8Array.from(JSON.parse(readFileSync("./my-key.json", "utf-8"))),
);
const provider = new AnchorProvider(connection, new Wallet(user), {
commitment: "confirmed",
});The second argument to Connection, "confirmed", is the commitment level. It controls how strict the RPC is about what counts as "known." Higher commitment means more validators have agreed, but it also means slightly higher latency. For reads where you want to make sure the transaction has actually landed, "confirmed" is the standard choice. For the strictest possible read after a transaction has been finalized, use "finalized". The provider has its own commitment, and .rpc() returns once the transaction reaches it. Its default is "processed", lower than the connection's "confirmed", so a read right after .rpc() can return the account as it was before the write. The example sets the provider to "confirmed" as well.
A signed transaction does not stay valid for long. It carries a recent blockhash, and validators reject it once that blockhash is more than about 150 blocks old. If the transaction was not confirmed by then, it will not land, and the client has to build and sign a new one. The client can also simulate a transaction before sending it. The simulation returns the result and the compute units consumed, so a transaction that would fail shows up before it is sent. The fees and compute units lesson uses the same simulation to set the compute unit limit.
Account data comes back as raw bytes until the IDL decodes it
The basic primitive for reading is getAccountInfo:
const accountInfo = await connection.getAccountInfo(vault);
if (accountInfo === null) {
console.log("account doesn't exist");
} else {
console.log("owner:", accountInfo.owner.toBase58());
console.log("lamports:", accountInfo.lamports);
console.log("data:", accountInfo.data); // a Buffer of raw bytes
}accountInfo.data is a raw Buffer of bytes. Web3.js doesn't know what those bytes mean. If you want to read the fields of an Anchor account, you have to decode them according to the layout the program uses. The Anchor client does that with the IDL:
const vaultAccount = await program.account.vault.fetch(vault);
console.log("total:", vaultAccount.total.toNumber()); // typed Vault structA script holds the key, a frontend asks the wallet to sign
Every transaction needs at least one signer, and that signer pays the fee. In scripts and backends, you usually hold the keypair yourself. You load it from a file or an environment variable into a Keypair object, as the connection example does with user, and your code uses it to sign transactions directly. You'll use this in your test files and in any off-chain automation you write.
To send an instruction you built by hand, add it to a Transaction and call sendAndConfirmTransaction with the connection, the transaction, and an array of signers. That one call signs, sends, and waits for confirmation.
In frontends, you never hold the keypair. The user's private key lives in their browser wallet (Phantom, Backpack, Solflare), and your code asks the wallet to sign through the wallet adapter, a library that abstracts over which wallet the user installed.
Your app never sees the user's private key, so it cannot leak it. The library also handles wallet detection, connection state, and account changes. In React projects you wrap your app in a WalletProvider and use the useWallet() hook to get the currently connected wallet's pubkey and signing functions.
Four packages cover the client side
| Package | What it gives you |
|---|---|
@solana/web3.js | The primitives: Connection for talking to an RPC node, Keypair for holding a private key, Transaction and TransactionInstruction for building transactions. |
@coral-xyz/anchor | The Anchor client: typed methods for every instruction and decoded accounts, both from the IDL. |
@solana/wallet-adapter-react | The connection between a frontend and browser wallets like Phantom, Backpack, and Solflare. |
@solana/kit | The newer modular successor to web3.js, with a slightly different API. |
For this course we'll stick with @solana/web3.js version 1, because @coral-xyz/anchor and bankrun depend on it. Install it as @solana/web3.js@1. The current release on npm is version 3, where Keypair.generate() returns a promise and findProgramAddressSync no longer exists, so the code in this course does not compile against it. You should still recognize @solana/kit when you see it in newer projects.