honeyb-vault-client

Generated TypeScript client for the HoneyB Vault Solana program, built on @solana/kit (the successor to @solana/web3.js).

The src/generated/ directory is auto-generated by Codama from the Shank IDL — do not edit it by hand. Add custom helpers in src/index.ts (scaffolded once and preserved across regenerations). This README, package.json, and tsconfig.json are likewise scaffolded once and then yours to edit.

Generating / regenerating

From the repo root (regenerates both the Rust and TypeScript clients):

npm install            # once, installs Codama + renderers
npm run generate-clients

The generator reads idl/honeyb_vault.json, injects PDA seed definitions, and rewrites src/generated/. It only touches src/generated/ and refreshes the @solana/* dependency versions in package.json; all other files here are left alone. See the root CLAUDE.md for the full IDL → client pipeline.

After regenerating, rebuild dist/ so the compiled type declarations stay in sync with the new src/generated/:

npm run build           # refreshes dist/index.d.ts (+ dist/index.js)

TypeScript consumers typecheck against dist/*.d.ts, not the raw source (see Installing in a webapp below), so a stale dist/ leaves them on the old client.

Installing in a webapp

@solana/kit is a peer dependency — install it alongside the client:

npm install @solana/kit
# then add this client (e.g. via workspace path or a published package)

The package dual-exports so bundlers and typecheckers each get what they need:

• import / default → src/index.ts (raw TypeScript) — bundlers (Vite, Next.js, esbuild) transpile it directly; no build step needed for bundling.
• types → dist/index.d.ts (compiled declarations) — typecheckers read these instead of the raw source.

Why the split: the generated code uses enums, which trip strict consumer compiler flags such as erasableSyntaxOnly when the raw src/ is pulled into the consumer's own tsc program (TS1294). Pointing types at the built .d.ts keeps those consumers compiling (and skipLibCheck skips it entirely), while bundlers still get the raw source. Run npm run build after every regeneration so dist/ matches src/generated/.

⚠️ Program address is a placeholder

The program has no declare_id! and no deployed ID yet, so the embedded HONEYB_VAULT_PROGRAM_PROGRAM_ADDRESS is the IDL placeholder (11111111111111111111111111111111).

Until a real ID exists, pass { programAddress } to every PDA finder and instruction builder. Once you have the deployed ID, set it in the IDL (metadata.address) and regenerate to bake it in.

import { address } from '@solana/kit';

// Replace with the deployed program ID.
export const VAULT_PROGRAM_ADDRESS = address('11111111111111111111111111111111');

What's generated

• instructions/ — getInitVaultInstruction(...), getJoinMintQueueInstruction(...), … (one per program instruction)
• accounts/ — fetchVault(...), decodeVault(...) and the decoded types (Vault, ProgramConfig, …)
• pdas/ — typed PDA finders: findProgramConfigPda, findVaultPda, findUserHoneybAccountPda, findEpochYieldPda, etc.
• types/ — shared structs (VaultConfig, MerkleEntry, UserList, …)
• errors/ — the program's custom error codes/messages
• programs/ — the program address constant and instruction identifiers

Example: derive PDAs, fetch state, build an instruction

import {
  createSolanaRpc,
  appendTransactionMessageInstruction,
  pipe,
} from '@solana/kit';
import {
  findVaultPda,
  findUserHoneybAccountPda,
  fetchVault,
  getInitiateRedemptionInstruction,
} from 'honeyb-vault-client';
import { VAULT_PROGRAM_ADDRESS } from './config';

const rpc = createSolanaRpc('https://api.devnet.solana.com');
const vaultId = 0n;

// 1. Derive PDAs (pass the real program address — see caveat above).
const [vault] = await findVaultPda({ vaultId }, { programAddress: VAULT_PROGRAM_ADDRESS });
const [userHoneybAccount] = await findUserHoneybAccountPda(
  { user: userAddress, vaultId },
  { programAddress: VAULT_PROGRAM_ADDRESS },
);

// 2. Read & decode on-chain state.
const vaultAccount = await fetchVault(rpc, vault);
console.log('current epoch:', vaultAccount.data.epoch);

// 3. Build an instruction (also override programAddress until the ID is baked in).
const ix = getInitiateRedemptionInstruction(
  {
    payer,            // TransactionSigner
    user,             // TransactionSigner
    programConfig,
    userHoneybAccount,
    redemptionHoneybAccount,
    vault,
    epochRedemption,
    redemptionRecord,
    honeybMint,
    amount: 1_000_000n,
  },
  { programAddress: VAULT_PROGRAM_ADDRESS },
);

// 4. Add `ix` to a transaction message and send with @solana/kit as usual.

Account addresses not derivable as PDAs (USDC accounts, mints, the user's wallet) come from your app/wallet context; the find*Pda helpers cover everything the program derives.