@microslop/ping-directory-sdk 0.1.5

package/src/constants.js

@@ -0,0 +1,103 @@
+// Constants mirroring `programs/ping-directory/src/{lib,utils/message_tags,state/*}.rs`.
+// Bumping any value here = on-chain breaking change.
+
+import { PublicKey } from '@solana/web3.js';
+
+export const PROGRAM_ID = new PublicKey('638WoGuZRYWBasJeeX4kkd4kdUB4MQ68K9P73GhBXduE');
+export const ED25519_PROGRAM = new PublicKey('Ed25519SigVerify111111111111111111111111111');
+export const SYSTEM_PROGRAM = new PublicKey('11111111111111111111111111111111');
+export const SYSVAR_INSTRUCTIONS = new PublicKey('Sysvar1nstructions1111111111111111111111111');
+
+// Clusters this program is deployed to. (Callers can still pass their own
+// Connection/rpcUrl; these are convenience defaults — see PingDirectory's
+// `cluster` option.)
+//   • LOCALNET — shared dev localnet (solana-test-validator behind a reverse proxy).
+//   • MAINNET  — not live yet (not deployed to mainnet-beta as of writing).
+export const Cluster = Object.freeze({
+  LOCALNET: 'https://sol-net.local.microslop.software',
+  MAINNET: 'https://api.mainnet-beta.solana.com',
+});
+
+// PubSub WebSocket endpoints for clusters whose WS is NOT where web3.js derives
+// it (wss://<rpc-host>/). The localnet's PubSub is reverse-proxied at `/ws`;
+// mainnet derives correctly so it has no entry. PingDirectory applies these
+// automatically when you pass `cluster` (or a matching `rpcUrl`).
+export const ClusterWs = Object.freeze({
+  LOCALNET: 'wss://sol-net.local.microslop.software/ws',
+});
+
+// Default cluster when a caller specifies neither `cluster` nor `rpcUrl`.
+// Localnet during dev — flip to 'MAINNET' at launch.
+export const DEFAULT_CLUSTER = 'LOCALNET';
+export const DEFAULT_RPC = Cluster[DEFAULT_CLUSTER];
+export const DEFAULT_WS = ClusterWs[DEFAULT_CLUSTER];
+
+// Re-exported for callers that need the seed string directly.
+export { Seeds as SeedNames };
+
+// ── Ed25519 message-tag discriminators (mirror utils/message_tags.rs) ──
+export const MessageTags = Object.freeze({
+  REGISTER:            0x01,
+  UNREGISTER:          0x02,
+  UPDATE_PUBKEY:       0x03,
+  TRANSFER_USERNAME:   0x04,
+  CANCEL_SALE:         0x05,
+  REQUEST_UNLOCK:      0x06,
+  LOCK:                0x07,
+  SET_ACCOUNT_TYPE:    0x08,
+  // 0x09 is the on-chain tag for finalize_profile_photo. Two aliases for
+  // client clarity (both resolve to byte 0x09).
+  SET_PROFILE_PHOTO:   0x09,
+  FINALIZE_PROFILE_PHOTO: 0x09,
+  CLEAR_PROFILE_PHOTO: 0x0A,
+  EQUIP_ITEM:          0x0B,
+  UNEQUIP_SLOT:        0x0C,
+  EQUIP_PRO_DEFAULT: 0x13,
+  ATTACH_PUBKEY:       0x0D,
+  LIST_ACTIVE:         0x0E,
+  BUY_ACTIVE:          0x0F,
+  INIT_PROFILE_PHOTO:  0x10,
+  DISCARD_ITEM:        0x11,
+  MARK_COMPROMISED:    0x12,
+});
+
+// ── State discriminators ───────────────────────────────────────────────
+export const UsernameState = Object.freeze({ RESERVED: 0, ACTIVE: 1, UNREGISTERED: 2 });
+export const ListingKind   = Object.freeze({ RESERVED: 0, ACTIVE: 1 });
+export const GraceKind     = Object.freeze({ WALLET: 0, ED25519: 1 });
+export const PhotoMime     = Object.freeze({ JPEG: 0, PNG: 1, WEBP: 2, GIF: 3 });
+export const ItemKind      = Object.freeze({ NAMEPLATE: 0, MESSAGE_BUBBLE: 1, NAME_FONT: 2, BADGE: 3 });
+export const AccountType   = Object.freeze({ USER: 0, GROUP: 1 });
+export const UserIndexStatus = Object.freeze({ ACTIVE: 0, UNREGISTERED: 1 });
+
+// ── PDA seed strings (mirror state/*.rs SEED constants) ────────────────
+export const Seeds = Object.freeze({
+  CONFIG:        'config',
+  USERNAME:      'username',
+  REVERSE:       'reverse',
+  NONCE:         'nonce',
+  GRACE:         'grace',
+  SALE:          'sale',
+  REFERRAL:      'referral',
+  USER_INDEX:    'user_idx',
+  UID_MAP:       'uid_map',
+  ADMIN:         'admin',
+  TREASURY_WALLET: 'treasury_wallet',
+  MODERATION:    'moderation',
+  BLOCKED:       'blocked',
+  SHOP_ITEM:     'shop_item',
+  INVENTORY:     'inventory',
+  PROFILE_PHOTO: 'profile_photo',
+  ED25519:       'ed25519',
+});
+
+// ── Hard caps and policy constants ─────────────────────────────────────
+export const MAX_USERNAME_LEN = 20;
+export const MAX_INVENTORY    = 64;        // Inventory::MAX_OWNED
+export const MAX_PHOTO_BYTES  = 10_181;    // ProfilePhoto::MAX_DATA_SIZE
+export const MAX_PHOTO_DIM    = 8192;      // ProfilePhoto::MAX_DIMENSION
+export const BPS_DENOMINATOR  = 10_000;
+export const REFERRAL_BPS     = 1_000;     // 10%
+
+// ── Tx-fee + compute budget defaults ──────────────────────────────────
+export const COMPUTE_BUDGET_PROGRAM = new PublicKey('ComputeBudget111111111111111111111111111111');

package/src/deserialize.js

@@ -0,0 +1,322 @@
+// Borsh deserializers for state accounts. Each strips the 8-byte
+// Anchor discriminator and parses the remaining bytes per the layout
+// in `programs/ping-directory/src/state/*.rs`.
+
+import { PublicKey } from '@solana/web3.js';
+
+class Reader {
+  constructor(bytes) {
+    this.b = bytes;
+    this.i = 0;
+    this.dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  /** True iff `n` more bytes remain to be read. Used by deserializers
+   *  that want to gracefully accept accounts written under an older
+   *  (shorter) schema — see `deserializeUsernameAccount` which treats
+   *  the trailing `equippedBadge` field as optional for back-compat
+   *  with pre-BADGE-slot accounts. */
+  has(n) { return this.i + n <= this.b.length; }
+  u8()    { return this.b[this.i++]; }
+  bool()  { return this.u8() !== 0; }
+  u16()   { const v = this.dv.getUint16(this.i, true); this.i += 2; return v; }
+  u32()   { const v = this.dv.getUint32(this.i, true); this.i += 4; return v; }
+  u64()   { const v = this.dv.getBigUint64(this.i, true); this.i += 8; return v; }
+  i64()   { const v = this.dv.getBigInt64(this.i, true); this.i += 8; return v; }
+  bytes(n) { const out = this.b.slice(this.i, this.i + n); this.i += n; return out; }
+  pubkey() { return new PublicKey(this.bytes(32)); }
+  pubkeyBytes() { return new Uint8Array(this.bytes(32)); }
+  string() { const n = this.u32(); return new TextDecoder().decode(this.bytes(n)); }
+  optionPubkey() {
+    const tag = this.u8();
+    if (tag === 0) return null;
+    if (tag === 1) return this.pubkey();
+    throw new Error(`Bad option tag ${tag}`);
+  }
+  optionU32() {
+    const tag = this.u8();
+    if (tag === 0) return null;
+    if (tag === 1) return this.u32();
+    throw new Error(`Bad option tag ${tag}`);
+  }
+  vecU32() {
+    const n = this.u32();
+    const out = new Array(n);
+    for (let i = 0; i < n; i++) out[i] = this.u32();
+    return out;
+  }
+  vecU8() {
+    const n = this.u32();
+    return this.bytes(n);
+  }
+}
+
+const stripDisc = (data) => new Uint8Array(data.slice(8));
+
+// ── Config ──────────────────────────────────────────────────────────
+export function deserializeConfig(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    owner: r.pubkey(),
+    registrationFees: Array.from({ length: 7 }, () => r.u64()),
+    proMonthlyPrice: r.u64(),
+    proLifetimePrice: r.u64(),
+    saleFeeBps: r.u16(),
+    minSalePrice: r.u64(),
+    gracePeriod: r.i64(),
+    unlockDelay: r.i64(),
+    unlockWindow: r.i64(),
+    autoUnfreezeDelay: r.i64(),
+    // Per-MIME init_profile_photo fee (lamports). Indexed by ProfilePhoto::MIME_*
+    // (0=jpeg, 1=png, 2=webp, 3=gif). Owner-tunable via set_profile_photo_fee.
+    profilePhotoFees: Array.from({ length: 4 }, () => r.u64()),
+    registrationPaused: r.bool(),
+    proPaused: r.bool(),
+    totalRegistered: r.u64(),
+    totalReferralPending: r.u64(),
+    nextUserId: r.u64(),
+    pendingOwner: r.pubkey(),
+    bump: r.u8(),
+  };
+}
+
+// ── UsernameAccount ─────────────────────────────────────────────────
+//
+// Source-of-truth for personal data: premium, equipped cosmetics,
+// referrer, account_type live here (they survive key rotation, since
+// state is keyed by username).
+//
+// `state` ∈ {0 = RESERVED, 1 = ACTIVE, 2 = UNREGISTERED}. UNREGISTERED
+// is a tombstone: the PDA persists forever (paid once per name) and
+// is reused by re-registration via `init_if_needed`.
+export function deserializeUsernameAccount(data) {
+  const r = new Reader(stripDisc(data));
+  // Account schema version is encoded in the total allocation size
+  // (Anchor reserves the full struct SIZE at PDA init, so the byte
+  // length is fixed per-version regardless of which Option fields
+  // are populated). 172 bytes (stripped) = pre-BADGE-slot schema;
+  // 177 bytes = current schema with `equipped_badge`. Reading past
+  // the old layout's bump would consume the bump byte as the next
+  // Option tag and crash on "Bad option tag <bump value>".
+  const hasBadgeSlot = r.b.length >= 177;
+  return {
+    username: r.string(),
+    state: r.u8(),
+    wallet: r.pubkey(),
+    ed25519Pubkey: r.pubkeyBytes(),
+    referrer: r.optionPubkey(),
+    proUntil: r.i64(),
+    proLifetime: r.bool(),
+    registeredAt: r.i64(),
+    attachedAt: r.i64(),
+    accountType: r.u8(),
+    unlockRequestedAt: r.i64(),
+    equippedNameplate: r.optionU32(),
+    equippedBubble: r.optionU32(),
+    equippedNameFont: r.optionU32(),
+    // Custom badge equipped from the shop. When null AND the username is
+    // premium, clients should render the implicit "default premium badge".
+    // See `isPro(usernameAccount, nowSec)` for the activation check.
+    //
+    // Back-compat: pre-BADGE-slot accounts end immediately after
+    // `equippedNameFont` + `bump`. Use the schema-version flag computed
+    // from `r.b.length` above (177+ bytes = new layout includes the
+    // badge slot). A buffer-remaining-bytes heuristic doesn't work
+    // because Anchor zero-pads to the full reserved size, so trailing
+    // padding looks identical to a populated badge slot until the
+    // option tag is checked.
+    equippedBadge: hasBadgeSlot ? r.optionU32() : null,
+    bump: r.u8(),
+  };
+}
+
+// True iff the username currently has premium — lifetime-granted (admin/owner
+// flag, see `set_pro`) or within paid time (`subscribe_pro` extended
+// `pro_until`). Mirrors the on-chain `UsernameAccount::is_pro` helper.
+//
+// `usernameAccount` is a result of `deserializeUsernameAccount` (or
+// `sdk.fetchUsername`). `nowSec` is a unix-ts in seconds; defaults to wall
+// clock. Passes through `BigInt` comparisons so the caller can stay BigInt
+// throughout.
+//
+// UX note: clients use this to decide whether to render the implicit
+// "default premium" cosmetic in any empty equipped slot
+// (`equippedNameplate / Bubble / NameFont / Badge`).
+export function isPro(usernameAccount, nowSec = Math.floor(Date.now() / 1000)) {
+  if (!usernameAccount) return false;
+  if (usernameAccount.proLifetime) return true;
+  const now = typeof nowSec === 'bigint' ? nowSec : BigInt(nowSec);
+  const until = typeof usernameAccount.proUntil === 'bigint'
+    ? usernameAccount.proUntil
+    : BigInt(usernameAccount.proUntil ?? 0);
+  return until > now;
+}
+
+// ── Ed25519Account (bound username + compromised flag) ──────────────
+//
+// `boundUsername` is `string | null` (the username currently controlled
+// by this key, or null when not bound).
+// `compromisedAt` is a BigInt unix-ts. `0n` = not marked. One-way.
+export function deserializeEd25519Account(data) {
+  const r = new Reader(stripDisc(data));
+  // bound_username: Option<String>
+  const tag = r.u8();
+  let boundUsername = null;
+  if (tag === 1) {
+    boundUsername = r.string();
+  } else if (tag !== 0) {
+    throw new Error(`Bad option tag ${tag}`);
+  }
+  return {
+    boundUsername,
+    compromisedAt: r.i64(),
+    bump: r.u8(),
+  };
+}
+
+// ── SaleListing ─────────────────────────────────────────────────────
+export function deserializeSaleListing(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    price: r.u64(),
+    receiverWallet: r.pubkey(),
+    sellerKind: r.u8(),
+    listNonce: new Uint8Array(r.bytes(16)),
+    bump: r.u8(),
+  };
+}
+
+// ── GracePeriod ─────────────────────────────────────────────────────
+export function deserializeGracePeriod(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    originalKind: r.u8(),
+    originalPubkey: r.pubkeyBytes(),
+    until: r.i64(),
+    bump: r.u8(),
+  };
+}
+
+// ── ReferralBalance ─────────────────────────────────────────────────
+export function deserializeReferralBalance(data) {
+  const r = new Reader(stripDisc(data));
+  return { balance: r.u64(), bump: r.u8() };
+}
+
+// ── ProfilePhoto ────────────────────────────────────────────────────
+export function deserializeProfilePhoto(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    finalized: r.bool(),
+    mime: r.u8(),
+    width: r.u16(),
+    height: r.u16(),
+    setAt: r.i64(),
+    initPayer: r.pubkey(),
+    data: r.vecU8(),
+    bump: r.u8(),
+  };
+}
+
+// Header-only decode — everything before the variable `data` blob. Pair
+// with a `dataSlice` fetch so callers can read mime/dims/setAt without
+// pulling the up-to-10KB image. `setAt` is the cheap change signal: it
+// bumps on every finalize, so a client can decide whether to refetch the
+// full photo. (The cryptographic hash is NOT on the account — it lives
+// only in the ProfilePhotoSet event / the indexer.)
+export const PROFILE_PHOTO_META_LEN = 54; // 8 disc + 1+1+2+2+8 + 32 init_payer
+export function deserializeProfilePhotoMeta(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    finalized: r.bool(),
+    mime: r.u8(),
+    width: r.u16(),
+    height: r.u16(),
+    setAt: r.i64(),
+    initPayer: r.pubkey(),
+  };
+}
+
+// ── Inventory ───────────────────────────────────────────────────────
+export function deserializeInventory(data) {
+  const r = new Reader(stripDisc(data));
+  return { ownedItems: r.vecU32(), bump: r.u8() };
+}
+
+// ── ShopItem ────────────────────────────────────────────────────────
+export function deserializeShopItem(data) {
+  const r = new Reader(stripDisc(data));
+  const out = {
+    id: r.u32(),
+    kind: r.u8(),
+    price: r.u64(),
+    active: r.bool(),
+    metadata: r.string(),
+    bump: r.u8(),
+  };
+  // `pro_only` was appended after launch. ShopItem accounts written
+  // before the Pro-purchase gate lack the trailing byte — decode them
+  // as `false` (freely purchasable) rather than throwing.
+  out.proOnly = r.has(1) ? r.bool() : false;
+  return out;
+}
+
+// ── Admin ───────────────────────────────────────────────────────────
+export function deserializeAdmin(data) {
+  const r = new Reader(stripDisc(data));
+  return { bump: r.u8() };
+}
+
+// ── TreasuryWallet ──────────────────────────────────────────────────
+// Existence of the PDA at [b"treasury_wallet", pubkey] = the address may
+// withdraw the treasury. Empty struct (just a bump), mirrors Admin.
+export function deserializeTreasuryWallet(data) {
+  const r = new Reader(stripDisc(data));
+  return { bump: r.u8() };
+}
+
+// ── Blocklist ───────────────────────────────────────────────────────
+export function deserializeBlocklist(data) {
+  const r = new Reader(stripDisc(data));
+  return { bump: r.u8() };
+}
+
+// ── Moderation (companion visibility PDA) ───────────────────────────
+// Lives at [b"moderation", username]. ABSENCE of the PDA = fully
+// visible (the deserializer is only called when the PDA exists). The
+// stored flags are `*_hidden`; callers usually want the inverse
+// (`visible`) — `PingDirectory.fetchVisibility` does that mapping.
+export function deserializeModeration(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    usernameHidden: r.bool(),
+    pfpHidden: r.bool(),
+    updatedAt: r.i64(),
+    updatedBy: r.pubkey(),
+    bump: r.u8(),
+  };
+}
+
+// ── Nonce ───────────────────────────────────────────────────────────
+export function deserializeNonce(data) {
+  const r = new Reader(stripDisc(data));
+  return { bump: r.u8() };
+}
+
+// ── UserIndex ───────────────────────────────────────────────────────
+export function deserializeUserIndex(data) {
+  const r = new Reader(stripDisc(data));
+  return {
+    username: r.string(),
+    originalEd25519Pubkey: r.pubkeyBytes(),
+    registeredAt: r.i64(),
+    status: r.u8(),
+    bump: r.u8(),
+  };
+}
+
+// ── UsernameUserIdMap ───────────────────────────────────────────────
+export function deserializeUsernameUserIdMap(data) {
+  const r = new Reader(stripDisc(data));
+  return { userId: r.u64(), bump: r.u8() };
+}
+

package/src/disc.js

@@ -0,0 +1,76 @@
+// Anchor discriminator helpers.
+//
+// Instruction disc = sha256("global:<snake_case_name>")[0..8]
+// Account     disc = sha256("account:<PascalCaseStructName>")[0..8]
+//
+// Inline SHA-256 (pure JS, sync) so the SDK works in browser + Node
+// without `node:crypto`. Implementation follows FIPS 180-4.
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+/** Sync SHA-256 of a string or `Uint8Array`. Returns 32-byte `Uint8Array`.
+ *  Pure-JS so it works in any runtime (browser without secure-context,
+ *  Node, Tauri WebView, etc.) — no `crypto.subtle` / `node:crypto` dep. */
+export function sha256(input) {
+  const bytes = typeof input === 'string' ? new TextEncoder().encode(input) : input;
+  const len = bytes.length;
+  const padLen = ((len + 9 + 63) & ~63) - len;
+  const buf = new Uint8Array(len + padLen);
+  buf.set(bytes);
+  buf[len] = 0x80;
+  const bitLen = BigInt(len) * 8n;
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(buf.length - 8, Number(bitLen >> 32n) >>> 0, false);
+  dv.setUint32(buf.length - 4, Number(bitLen & 0xffffffffn) >>> 0, false);
+
+  let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+  let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+
+  const w = new Uint32Array(64);
+  for (let i = 0; i < buf.length; i += 64) {
+    for (let t = 0; t < 16; t++) w[t] = dv.getUint32(i + t * 4, false);
+    for (let t = 16; t < 64; t++) {
+      const s0 = ((w[t-15] >>> 7) | (w[t-15] << 25)) ^ ((w[t-15] >>> 18) | (w[t-15] << 14)) ^ (w[t-15] >>> 3);
+      const s1 = ((w[t-2] >>> 17) | (w[t-2] << 15)) ^ ((w[t-2] >>> 19) | (w[t-2] << 13)) ^ (w[t-2] >>> 10);
+      w[t] = (w[t-16] + s0 + w[t-7] + s1) >>> 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let t = 0; t < 64; t++) {
+      const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + S1 + ch + K[t] + w[t]) >>> 0;
+      const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+      const mj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + mj) >>> 0;
+      h = g; g = f; f = e; e = (d + t1) >>> 0;
+      d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h0 = (h0 + a) >>> 0; h1 = (h1 + b) >>> 0; h2 = (h2 + c) >>> 0; h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0; h5 = (h5 + f) >>> 0; h6 = (h6 + g) >>> 0; h7 = (h7 + h) >>> 0;
+  }
+
+  const out = new Uint8Array(32);
+  const odv = new DataView(out.buffer);
+  odv.setUint32(0,  h0, false); odv.setUint32(4,  h1, false);
+  odv.setUint32(8,  h2, false); odv.setUint32(12, h3, false);
+  odv.setUint32(16, h4, false); odv.setUint32(20, h5, false);
+  odv.setUint32(24, h6, false); odv.setUint32(28, h7, false);
+  return out;
+}
+
+export function ixDisc(name) {
+  return sha256(`global:${name}`).slice(0, 8);
+}
+
+export function accDisc(name) {
+  return sha256(`account:${name}`).slice(0, 8);
+}

package/src/encoding.js

@@ -0,0 +1,130 @@
+// Pure-JS encoding helpers for Borsh + ed25519 message construction.
+// We don't depend on the `borsh` package — the program's structs are
+// simple enough that hand-rolled serialization is clearer and avoids the
+// "what version of borsh" hazard.
+
+import nacl from 'tweetnacl';
+import { Ed25519Program, PublicKey } from '@solana/web3.js';
+
+// ── Endian-aware integer encoders ───────────────────────────────────
+export function u8(n) {
+  const b = new Uint8Array(1); b[0] = n & 0xff; return b;
+}
+export function u16LE(n) {
+  const b = new Uint8Array(2);
+  new DataView(b.buffer).setUint16(0, n, true);
+  return b;
+}
+export function u32LE(n) {
+  const b = new Uint8Array(4);
+  new DataView(b.buffer).setUint32(0, n, true);
+  return b;
+}
+export function u64LE(n) {
+  const b = new Uint8Array(8);
+  const v = BigInt(n);
+  new DataView(b.buffer).setBigUint64(0, v, true);
+  return b;
+}
+export function i64LE(n) {
+  const b = new Uint8Array(8);
+  new DataView(b.buffer).setBigInt64(0, BigInt(n), true);
+  return b;
+}
+
+// ── Borsh helpers ──────────────────────────────────────────────────
+// Borsh string = u32 length prefix (little-endian) + UTF-8 bytes.
+export function borshString(s) {
+  const utf = new TextEncoder().encode(s);
+  return concat(u32LE(utf.length), utf);
+}
+// Borsh Option<T> = 0 (None) or 1 + T (Some).
+export function borshOptionPubkey(pk) {
+  if (pk == null) return new Uint8Array([0]);
+  return concat(new Uint8Array([1]), pkBytes(pk));
+}
+// Borsh Vec<u8> = u32 length prefix + bytes.
+export function borshBytes(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  return concat(u32LE(arr.length), arr);
+}
+
+// ── Pubkey helpers ─────────────────────────────────────────────────
+//
+// Duck-typed instead of `instanceof PublicKey` so we correctly handle
+// `PublicKey` instances that came from a *different copy* of
+// `@solana/web3.js` than the one bundled inside the SDK's own
+// `node_modules`. That dual-instance hazard fires whenever a host app
+// (or a script) hoists web3.js separately from the SDK — `instanceof`
+// returns `false` for objects functionally identical to ours, the
+// fallback path silently returns an empty `Uint8Array`, and the on-chain
+// program rejects the malformed instruction with `InstructionDidNotDeserialize`.
+//
+// Accepted shapes:
+//   - any PublicKey-like with a `.toBytes()` method (from any web3.js copy)
+//   - a 32-byte `Uint8Array` (already-raw bytes)
+//   - `null` / `undefined` → 32 zero bytes (matches `Pubkey::default()`)
+export function pkBytes(p) {
+  if (p == null) return new Uint8Array(32);
+  // Length-validate Uint8Array inputs so a non-32-byte buffer doesn't
+  // silently pass through and produce malformed ix bytes on chain. The
+  // old early-return `if (p instanceof Uint8Array) return p;` accepted
+  // any length; on-chain failure was `InstructionDidNotDeserialize`
+  // instead of a clear client-side error.
+  if (p instanceof Uint8Array) {
+    if (p.length !== 32) {
+      throw new Error(`pkBytes: Uint8Array must be 32 bytes, got ${p.length}`);
+    }
+    return p;
+  }
+  if (typeof p.toBytes === 'function') {
+    const b = p.toBytes();
+    if (b instanceof Uint8Array && b.length === 32) return b;
+  }
+  // ArrayBuffer / Array-like with numeric indices (be permissive but safe).
+  if (Array.isArray(p) || (p && typeof p.length === 'number')) {
+    const arr = new Uint8Array(p);
+    if (arr.length === 32) return arr;
+  }
+  throw new Error('pkBytes: expected a PublicKey-like or 32-byte Uint8Array');
+}
+
+// ── Concatenation ──────────────────────────────────────────────────
+export function concat(...parts) {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) { out.set(p, off); off += p.length; }
+  return out;
+}
+
+// ── Random bytes (for nonces) ──────────────────────────────────────
+export function randomBytes(n) {
+  return nacl.randomBytes(n);
+}
+
+// 16-byte nonce — match the program's Nonce PDA seed shape.
+export function randomNonce() {
+  return nacl.randomBytes(16);
+}
+
+// ── Ed25519 signing + precompile ix ────────────────────────────────
+//
+// The program's `verify_ed25519_signature` scans the instructions sysvar
+// for any preceding ed25519 precompile whose pubkey AND message match.
+// We build a single precompile per signed handler call.
+export function buildEd25519Ix(keyPair, message) {
+  const sig = nacl.sign.detached(message, keyPair.secretKey);
+  return Ed25519Program.createInstructionWithPublicKey({
+    publicKey: keyPair.publicKey,
+    message,
+    signature: sig,
+  });
+}
+
+// Tagged signed-message convenience: prepend the 1-byte instruction tag
+// and concatenate the body parts (already Uint8Arrays).
+export function signedMsg(tag, ...parts) {
+  return concat(new Uint8Array([tag]), ...parts);
+}