Client-Side PDA Derivation

Clients must derive the same PDAs as on-chain seeds constraints. Use identical seed bytes, order, and program ID.

Recipe

import { getAddressEncoder, getProgramDerivedAddress } from "@solana/kit";
 
const addressEncoder = getAddressEncoder();
 
const [pda] = await getProgramDerivedAddress({
  programAddress: programId,
  seeds: ["escrow", addressEncoder.encode(maker), u64ToLeBytes(escrowId)],
});

When to reach for this: Building transactions that pass PDA accounts to Anchor instructions.

Working Example

import { address, getAddressEncoder, getProgramDerivedAddress } from "@solana/kit";
 
const programId = address("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");
 
// u64 -> 8 bytes little-endian, explicitly. Do not rely on the host's
// native byte order via BigUint64Array#buffer.
function u64ToLeBytes(value: bigint): Uint8Array {
  const bytes = new Uint8Array(8);
  new DataView(bytes.buffer).setBigUint64(0, value, true);
  return bytes;
}
 
const [escrowPda] = await getProgramDerivedAddress({
  programAddress: programId,
  // getAddressEncoder turns a base58 Address into its 32 raw bytes.
  // getBytesEncoder would NOT do this - it only passes bytes through.
  seeds: [
    new TextEncoder().encode("escrow"),
    getAddressEncoder().encode(makerAddress),
    u64ToLeBytes(BigInt(escrowId)),
  ],
});
 
// Pass escrowPda in accounts map matching IDL name "escrow"

What this demonstrates:

• Seed strings must match b"escrow" bytes
• Pubkeys encoded as 32 raw bytes
• Integers use same endianness as Rust to_le_bytes
• Program ID is the Anchor program address

Deep Dive

@solana/kit 7.0.0

Use kit helpers for PDA derivation and address encoding. Share seed builders between program (Rust constants) and client (TS module) via codegen or documented constants.

Testing

Assert client PDA matches anchor test fixtures for every seed variant.

Gotchas

• UTF-8 string vs b-string mismatch - Different seeds. Fix: Use exact ASCII seed literals.
• Big-endian integer seeds - Rust uses le on-chain. Fix: Match to_le_bytes.
• Wrong program ID in client - Derives wrong address. Fix: Read from IDL metadata or Anchor.toml.
• Optional bump passed incorrectly - Usually omit; program validates. Fix: Let on-chain constraint verify bump.
• Base58 vs bytes confusion - Encoding errors. Fix: Use kit address types.

Alternatives

FAQs

Related

• PDAs in Anchor - on-chain seeds
• Generating TS Clients - client codegen
• PDA Derivation - native derivation

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.