@microslop/ping-directory-sdk 0.1.5

package/src/PingDirectory.js

@@ -0,0 +1,1110 @@
+// PingDirectory — high-level facade.
+//
+// Most callers want "submit this op" rather than "build me an
+// instruction". This wraps each ix builder into a method that:
+//   - resolves any required on-chain reads (config.next_user_id,
+//     username_user_id_map, bound ed25519 pubkey for freeze checks, etc.)
+//   - assembles + signs + sends a Transaction
+//   - returns the tx signature
+
+import {
+  Transaction, sendAndConfirmTransaction, Connection, PublicKey,
+} from '@solana/web3.js';
+import * as ix from './ix/index.js';
+import {
+  findConfigPDA, findUsernamePDA, findUidMapPDA, findEd25519AccountPDA,
+  findSaleListingPDA, findProfilePhotoPDA, findInventoryPDA,
+  findReferralBalancePDA, findShopItemPDA,
+  findModerationPDA, findTreasuryWalletPDA,
+} from './pda.js';
+import {
+  deserializeConfig, deserializeUsernameAccount, deserializeUsernameUserIdMap,
+  deserializeSaleListing, deserializeProfilePhoto, deserializeProfilePhotoMeta,
+  PROFILE_PHOTO_META_LEN, deserializeInventory,
+  deserializeReferralBalance, deserializeShopItem, deserializeEd25519Account,
+  deserializeModeration, deserializeTreasuryWallet,
+} from './deserialize.js';
+import { rentExempt } from './fees.js';
+import { PROGRAM_ID, Cluster, ClusterWs, DEFAULT_RPC } from './constants.js';
+import { sha256, accDisc } from './disc.js';
+import { b58encode } from './format.js';
+
+// Local helper: hex string -> Uint8Array (typically 32 bytes for ed25519).
+function hexToBytes(hex) {
+  if (typeof hex !== 'string') return hex;
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) throw new Error('hex string has odd length');
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+// Cross-env base64 (node Buffer || browser btoa/atob) — mirrors the
+// pattern in `parseEvent`. Used by the detached-transaction helpers.
+function toBase64(bytes) {
+  if (typeof Buffer !== 'undefined') return Buffer.from(bytes).toString('base64');
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function fromBase64(b64) {
+  if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(b64, 'base64'));
+  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+export class PingDirectory {
+  /**
+   * Accepts either:
+   *   - a `Connection` instance (existing behavior — preserved for tests
+   *     and SDK consumers that already manage their own Connection), or
+   *   - a config bag `{ rpcUrl, fetch?, beforeRequest?, commitment? }` —
+   *     the SDK builds a Connection internally and (when `fetch` or
+   *     `beforeRequest` is supplied) wires a custom fetch chain so the
+   *     host app can route RPC through Tauri / a privacy proxy and
+   *     attach per-request `X-Ping-*` auth headers.
+   *
+   * The two shapes are distinguished by duck-typing on common Connection
+   * methods (`getAccountInfo` / `sendRawTransaction`) rather than
+   * `instanceof`, since the host app may pass a Connection from a
+   * different copy of `@solana/web3.js` (npm dedupe / monorepo
+   * hoisting), in which case `instanceof Connection` would be false
+   * even though the object is functionally a Connection.
+   */
+  constructor(arg) {
+    if (arg && typeof arg === 'object'
+        && typeof arg.getAccountInfo === 'function'
+        && typeof arg.sendRawTransaction === 'function') {
+      // Connection-arg shape (original)
+      this.connection = arg;
+      return;
+    }
+
+    // Config-bag shape. Resolve cluster shorthand → rpc/ws. Explicit rpcUrl /
+    // wsEndpoint always win; with neither rpcUrl nor cluster we default to the
+    // LOCALNET cluster (dev default — flip DEFAULT_CLUSTER in constants.js at
+    // launch). `cluster` accepts 'localnet' | 'mainnet' (case-insensitive).
+    const config = arg || {};
+    const clusterKey = config.cluster ? String(config.cluster).toUpperCase() : null;
+    const rpcUrl = config.rpcUrl || (clusterKey && Cluster[clusterKey]) || DEFAULT_RPC;
+    // WebSocket: explicit → the chosen cluster's → (if rpcUrl is a known cluster
+    // URL) that cluster's → undefined (web3.js derives wss://<host>/). The
+    // localnet's PubSub is reverse-proxied at /ws, not the derived root, so it
+    // needs this override; mainnet / 127.0.0.1 derive correctly on their own.
+    const wsEndpoint = config.wsEndpoint
+      || (clusterKey && ClusterWs[clusterKey])
+      || (rpcUrl === Cluster.LOCALNET ? ClusterWs.LOCALNET : undefined);
+    const commitment = config.commitment || 'confirmed';
+
+    // If the caller supplied a custom `fetch` or a `beforeRequest` hook,
+    // wrap them into a single fetch function and pass it to Connection
+    // via its `fetch` option (web3.js threads this through to all RPC
+    // calls). `beforeRequest(headers, body)` is invoked synchronously
+    // before each request so the host app can mutate the headers
+    // object (e.g. inject `X-Ping-Pubkey`, signature, timestamp).
+    let connectionConfig = { commitment };
+    if (wsEndpoint) connectionConfig.wsEndpoint = wsEndpoint;
+    const userFetch = config.fetch
+      || (typeof fetch !== 'undefined' ? fetch.bind(globalThis) : null);
+
+    if (config.beforeRequest || config.fetch) {
+      if (!userFetch) {
+        throw new Error('PingDirectory: no fetch implementation available — pass `fetch` in config');
+      }
+      const beforeRequest = config.beforeRequest;
+      const wrappedFetch = (input, init = {}) => {
+        // Normalize headers to a plain object the host can mutate.
+        const headers = Object.assign({}, init.headers || {});
+        const body = typeof init.body === 'string' ? init.body : '';
+        if (beforeRequest) {
+          try { beforeRequest(headers, body); }
+          catch (e) {
+            return Promise.reject(new Error('beforeRequest hook threw: ' + (e?.message ?? e)));
+          }
+        }
+        return userFetch(input, { ...init, headers });
+      };
+      connectionConfig = { commitment, fetch: wrappedFetch };
+      if (wsEndpoint) connectionConfig.wsEndpoint = wsEndpoint;
+    }
+
+    this.connection = new Connection(rpcUrl, connectionConfig);
+  }
+
+  // ── State reads ───────────────────────────────────────────────────
+  async fetchConfig() {
+    const [pda] = findConfigPDA();
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeConfig(acc.data);
+  }
+  async fetchUsername(username) {
+    const [pda] = findUsernamePDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeUsernameAccount(acc.data);
+  }
+  // Forward lookup name → full username + bound-key freeze state in two RPCs.
+  // Necessarily two-phase: the ed25519 PDA isn't known until UsernameAccount
+  // is fetched, so it can't be batched into one getMultipleAccountsInfo.
+  // Returns null if the username doesn't exist; otherwise the
+  // UsernameAccount struct extended with `{ compromised, compromisedAt }`
+  // (those two flags live on the bound Ed25519Account; everything else is
+  // already on UsernameAccount itself).
+  async fetchUsernameWithKeyState(username) {
+    const u = await this.fetchUsername(username);
+    if (!u) return null;
+    const k = await this.lookupKey(u.ed25519Pubkey);
+    return {
+      ...u,
+      compromised: k.compromised,
+      compromisedAt: k.compromisedAt,
+    };
+  }
+  async fetchUserIdMap(username) {
+    const [pda] = findUidMapPDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeUsernameUserIdMap(acc.data);
+  }
+  async fetchSaleListing(username) {
+    const [pda] = findSaleListingPDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeSaleListing(acc.data);
+  }
+
+  /**
+   * Discover every active SaleListing on chain and join it with the
+   * matching UsernameAccount so callers get `{ username, state, price,
+   * receiverWallet, sellerKind, listNonce, ed25519Pubkey, wallet, ... }`.
+   *
+   * Implementation: two `getProgramAccounts` calls — one filtered by
+   * the SaleListing account discriminator (small fixed-size rows) and
+   * one filtered by UsernameAccount. Each row carries its account
+   * pubkey, so we re-derive the SaleListing PDA from each username
+   * and intersect the two sets in JS. No per-listing follow-up RPCs.
+   *
+   * NOTE: `getProgramAccounts` is rate-limited / disabled on some
+   * mainnet RPCs. Fine for devnet + small deployments; an indexer is
+   * the right answer for production scale.
+   */
+  async fetchAllSaleListings() {
+    const SALE_DISC = accDisc('SaleListing');
+    const USERNAME_DISC = accDisc('UsernameAccount');
+
+    const [saleAccs, usernameAccs] = await Promise.all([
+      this.connection.getProgramAccounts(PROGRAM_ID, {
+        filters: [
+          { memcmp: { offset: 0, bytes: b58encode(SALE_DISC) } },
+        ],
+      }),
+      this.connection.getProgramAccounts(PROGRAM_ID, {
+        filters: [
+          { memcmp: { offset: 0, bytes: b58encode(USERNAME_DISC) } },
+        ],
+      }),
+    ]);
+
+    // Index listings by their account pubkey (= SaleListing PDA).
+    const listingByPda = new Map();
+    for (const { pubkey, account } of saleAccs) {
+      try {
+        listingByPda.set(pubkey.toBase58(), deserializeSaleListing(account.data));
+      } catch { /* skip corrupt rows */ }
+    }
+
+    // Walk usernames; for each, derive its SaleListing PDA and emit
+    // a joined row when one exists in the index above.
+    const rows = [];
+    for (const { account } of usernameAccs) {
+      let u;
+      try { u = deserializeUsernameAccount(account.data); }
+      catch { continue; }
+      const [salePda] = findSaleListingPDA(u.username);
+      const listing = listingByPda.get(salePda.toBase58());
+      if (!listing) continue;
+      rows.push({
+        username: u.username,
+        state: u.state,
+        usernameAccount: u,
+        price: listing.price,
+        receiverWallet: listing.receiverWallet,
+        sellerKind: listing.sellerKind,
+        listNonce: listing.listNonce,
+      });
+    }
+    return rows;
+  }
+
+  /**
+   * All UsernameAccounts whose `wallet` equals `walletPubkey` (base58 string
+   * or PublicKey). This is the only way to enumerate the names a *wallet*
+   * holds — the directory has no on-chain wallet→name index, so we scan every
+   * UsernameAccount and filter in JS (same pattern as `fetchAllSaleListings`;
+   * fine for devnet / small deployments — use an indexer at scale).
+   *
+   * Note: ACTIVE names permanently zero their `wallet`, so in practice this
+   * returns a wallet's RESERVED holdings.
+   *
+   * @returns {Promise<Array<{username: string, state: number, usernameAccount: object}>>}
+   */
+  async fetchUsernamesByWallet(walletPubkey) {
+    const walletB58 = typeof walletPubkey === 'string'
+      ? walletPubkey : walletPubkey.toBase58();
+    const USERNAME_DISC = accDisc('UsernameAccount');
+    const accs = await this.connection.getProgramAccounts(PROGRAM_ID, {
+      filters: [{ memcmp: { offset: 0, bytes: b58encode(USERNAME_DISC) } }],
+    });
+    const rows = [];
+    for (const { account } of accs) {
+      let u;
+      try { u = deserializeUsernameAccount(account.data); }
+      catch { continue; }
+      if (!u.wallet || u.wallet.toBase58() !== walletB58) continue;
+      rows.push({ username: u.username, state: u.state, usernameAccount: u });
+    }
+    return rows;
+  }
+  // ProfilePhoto and Inventory are keyed by username (cosmetics + photo
+  // travel with the name on transfer / buy_active).
+  async fetchProfilePhoto(username) {
+    const [pda] = findProfilePhotoPDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeProfilePhoto(acc.data);
+  }
+  // Header-only fetch (mime / dims / setAt) via dataSlice — skips the
+  // image blob entirely. Use `setAt` as a cheap "did the photo change?"
+  // probe before paying for the full `fetchProfilePhoto`. Returns null
+  // if no photo PDA exists.
+  async fetchProfilePhotoMeta(username) {
+    const [pda] = findProfilePhotoPDA(username);
+    const acc = await this.connection.getAccountInfo(pda, {
+      commitment: 'confirmed',
+      dataSlice: { offset: 0, length: PROFILE_PHOTO_META_LEN },
+    });
+    if (!acc) return null;
+    return deserializeProfilePhotoMeta(acc.data);
+  }
+
+  /**
+   * Batched resolve of usernames WITH their profile photos in one shot.
+   * For each username we read two PDAs — the UsernameAccount and the
+   * ProfilePhoto — so N usernames = 2N accounts, fetched via
+   * `getMultipleAccountsInfo` in chunks of 100 (Solana's hard per-call
+   * cap). Returns, per input username:
+   *   { username, account, pfp }
+   * where `pfp` is `{ mime, width, height, setAt, size, bytes? } | null`
+   * (null when there's no finalized photo).
+   *
+   * Options:
+   *   withBytes (default true) — include the raw image bytes. Set false
+   *     to get photo METADATA only (via a 0..META_LEN dataSlice), which
+   *     keeps the response tiny (~60B/photo) so you can resolve a large
+   *     roster cheaply and lazy-load the heavy blobs on demand.
+   *
+   * ⚠️ Response size: with `withBytes` and ~10KB photos, a single 100-PDA
+   * chunk that lands 50 photos pulls ~500KB+ (base64-inflated in the JSON
+   * response). The 100-ACCOUNT cap is the hard limit; the practical limit
+   * is the RPC's max response size. Prefer `withBytes:false` for big
+   * rosters + a follow-up `fetchProfilePhoto` for the few you render.
+   */
+  async resolveUsernamesWithPfp(usernames, { withBytes = true } = {}) {
+    const uPdas = usernames.map((u) => findUsernamePDA(u)[0]);
+    const pPdas = usernames.map((u) => findProfilePhotoPDA(u)[0]);
+
+    // getMultipleAccountsInfo, chunked at the 100-account hard cap.
+    const fetchChunked = async (pdas, opts) => {
+      const out = new Array(pdas.length);
+      const CHUNK = 100;
+      for (let off = 0; off < pdas.length; off += CHUNK) {
+        const accs = await this.connection.getMultipleAccountsInfo(pdas.slice(off, off + CHUNK), opts);
+        for (let i = 0; i < accs.length; i++) out[off + i] = accs[i];
+      }
+      return out;
+    };
+
+    // Two passes (username vs photo) so the photo pass can `dataSlice` to
+    // the fixed header in metadata-only mode — a shared interleaved call
+    // can't slice one type without truncating the other. In withBytes
+    // mode the photo pass lands up to 100 FULL photos per call (~1MB at
+    // 10KB each) — that's the real response-size stressor.
+    const uAccs = await fetchChunked(uPdas, { commitment: 'confirmed' });
+    const pAccs = await fetchChunked(
+      pPdas,
+      withBytes
+        ? { commitment: 'confirmed' }
+        : { commitment: 'confirmed', dataSlice: { offset: 0, length: PROFILE_PHOTO_META_LEN } },
+    );
+
+    return usernames.map((u, idx) => {
+      const uAcc = uAccs[idx];
+      const pAcc = pAccs[idx];
+      let account = null;
+      if (uAcc) {
+        try { account = deserializeUsernameAccount(uAcc.data); } catch { /* skip */ }
+      }
+      let pfp = null;
+      if (pAcc) {
+        try {
+          const d = withBytes
+            ? deserializeProfilePhoto(pAcc.data)
+            : deserializeProfilePhotoMeta(pAcc.data);
+          if (d.finalized) {
+            pfp = {
+              mime: d.mime, width: d.width, height: d.height, setAt: d.setAt,
+              ...(withBytes ? { size: d.data.length, bytes: d.data } : {}),
+            };
+          }
+        } catch { /* unfinalized / undecodable — leave null */ }
+      }
+      return { username: u, account, pfp };
+    });
+  }
+
+  async fetchInventory(username) {
+    const [pda] = findInventoryPDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeInventory(acc.data);
+  }
+  async fetchReferralBalance(referrer) {
+    const [pda] = findReferralBalancePDA(referrer);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeReferralBalance(acc.data);
+  }
+  async fetchShopItem(itemId) {
+    const [pda] = findShopItemPDA(itemId);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeShopItem(acc.data);
+  }
+
+  /** Every ShopItem on chain (getProgramAccounts scan, like
+   *  fetchAllSaleListings — fine for devnet / small catalogs, use an
+   *  indexer at scale). */
+  async fetchAllShopItems() {
+    const SHOP_DISC = accDisc('ShopItem');
+    const accs = await this.connection.getProgramAccounts(PROGRAM_ID, {
+      filters: [{ memcmp: { offset: 0, bytes: b58encode(SHOP_DISC) } }],
+    });
+    const items = [];
+    for (const { account } of accs) {
+      try { items.push(deserializeShopItem(account.data)); }
+      catch { /* skip corrupt rows */ }
+    }
+    return items;
+  }
+
+  // ── ed25519 → bound-username + compromised flag (single PDA fetch) ──
+  async fetchEd25519(ed25519Pubkey) {
+    const [pda] = findEd25519AccountPDA(ed25519Pubkey);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeEd25519Account(acc.data);
+  }
+
+  // Treasury-wallet role lookup — null if the address isn't a treasury wallet.
+  async getTreasuryWallet(walletPubkey) {
+    const [pda] = findTreasuryWalletPDA(walletPubkey);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeTreasuryWallet(acc.data);
+  }
+  async isTreasuryWallet(walletPubkey) {
+    return (await this.getTreasuryWallet(walletPubkey)) != null;
+  }
+  // Raw companion Moderation PDA (or null if it was never created).
+  async fetchModeration(username) {
+    const [pda] = findModerationPDA(username);
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return null;
+    return deserializeModeration(acc.data);
+  }
+  // Resolved visibility for a username. ABSENCE of the Moderation PDA
+  // means fully visible (migration-safe default). Returns the inverse of
+  // the stored `*_hidden` flags as `{ usernameVisible, pfpVisible,
+  // updatedAt, updatedBy }`.
+  async fetchVisibility(username) {
+    const m = await this.fetchModeration(username);
+    if (!m) {
+      return { usernameVisible: true, pfpVisible: true, updatedAt: null, updatedBy: null };
+    }
+    return {
+      usernameVisible: !m.usernameHidden,
+      pfpVisible: !m.pfpHidden,
+      updatedAt: m.updatedAt,
+      updatedBy: m.updatedBy,
+    };
+  }
+  // Default record returned for keys with no on-chain Ed25519Account PDA.
+  static #emptyKeyRecord() {
+    return {
+      username: null,
+      compromised: false,
+      compromisedAt: null,
+    };
+  }
+  static #recordFromAccount(d) {
+    return {
+      username: d.boundUsername,
+      compromised: d.compromisedAt > 0n,
+      compromisedAt: d.compromisedAt > 0n ? d.compromisedAt : null,
+    };
+  }
+  // Convenience: returns `{ username, compromised, compromisedAt }`.
+  // Returns sensible defaults if the PDA doesn't exist (key never seen
+  // on-chain). For richer per-username personal data (premium / equipped /
+  // referrer / account_type), call `fetchUsername` — that data lives on
+  // UsernameAccount, not Ed25519Account.
+  async lookupKey(ed25519Pubkey) {
+    const acc = await this.fetchEd25519(ed25519Pubkey);
+    if (!acc) return PingDirectory.#emptyKeyRecord();
+    return PingDirectory.#recordFromAccount(acc);
+  }
+  // Batched lookup. One getMultipleAccountsInfo call per chunk of 100.
+  // Each record carries `{ pubkey, username, compromised, compromisedAt }`.
+  async lookupKeys(pubkeys) {
+    const pdas = pubkeys.map((p) => findEd25519AccountPDA(p)[0]);
+    const out = new Array(pubkeys.length);
+    const CHUNK = 100;
+    for (let off = 0; off < pdas.length; off += CHUNK) {
+      const slice = pdas.slice(off, off + CHUNK);
+      const accs = await this.connection.getMultipleAccountsInfo(slice);
+      for (let i = 0; i < accs.length; i++) {
+        const idx = off + i;
+        const acc = accs[i];
+        if (!acc) {
+          out[idx] = { pubkey: pubkeys[idx], ...PingDirectory.#emptyKeyRecord() };
+        } else {
+          const d = deserializeEd25519Account(acc.data);
+          out[idx] = { pubkey: pubkeys[idx], ...PingDirectory.#recordFromAccount(d) };
+        }
+      }
+    }
+    return out;
+  }
+  // Convenience flag-only check.
+  async isCompromised(ed25519Pubkey) {
+    const a = await this.fetchEd25519(ed25519Pubkey);
+    return !!a && a.compromisedAt > 0n;
+  }
+
+  // ── Legacy-compat reverse-lookup helpers (pubkey hex → username) ────
+  //
+  // These mirror the legacy SDK API the client still calls. They are
+  // thin shims over `lookupKey` / `lookupKeys` / `fetchUsername`, which
+  // already do the right on-chain reads against the current schema (the
+  // ed25519 → bound-username mapping moved from the old ReverseLookup
+  // PDA onto Ed25519Account.boundUsername).
+
+  /**
+   * Look up the username currently bound to a single ed25519 pubkey
+   * (32-byte hex). Returns the username string, or `null` if the key
+   * has never been bound on chain.
+   */
+  async lookupUsername(pubkeyHex) {
+    if (!pubkeyHex) return null;
+    try {
+      const rec = await this.lookupKey(hexToBytes(pubkeyHex));
+      return rec?.username ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Batched reverse lookup: ed25519 hex pubkeys → `{ pubkeyHex: username }`.
+   * One `getMultipleAccountsInfo` round-trip per chunk of 100 (the same
+   * limit `lookupKeys` enforces). Pubkeys with no bound username (or
+   * bad input) are simply omitted from the returned map.
+   */
+  async fetchUsernamesBatch(pubkeysHex) {
+    if (!Array.isArray(pubkeysHex) || pubkeysHex.length === 0) return {};
+    // Convert + filter; preserve original hex strings as map keys.
+    const decoded = [];
+    const validHex = [];
+    for (const h of pubkeysHex) {
+      try {
+        decoded.push(hexToBytes(h));
+        validHex.push(h);
+      } catch { /* skip malformed */ }
+    }
+    if (decoded.length === 0) return {};
+    const records = await this.lookupKeys(decoded);
+    const out = {};
+    for (let i = 0; i < records.length; i++) {
+      const u = records[i]?.username;
+      if (u) out[validHex[i]] = u;
+    }
+    return out;
+  }
+
+  /** Alias kept for legacy callers — same contract as `fetchUsernamesBatch`. */
+  async lookupUsernames(pubkeysHex) {
+    return this.fetchUsernamesBatch(pubkeysHex);
+  }
+
+  /**
+   * Combined initial-state load: for an ed25519 hex pubkey, return the
+   * bound username (if any) plus its full UsernameAccount.
+   * Either field is `null` when the key isn't bound. Two RPCs in the
+   * happy path (one for the Ed25519Account PDA, one for UsernameAccount).
+   */
+  async fetchInitialState(pubkeyHex) {
+    if (!pubkeyHex) return { username: null, account: null };
+    let username = null;
+    try {
+      const rec = await this.lookupKey(hexToBytes(pubkeyHex));
+      username = rec?.username ?? null;
+    } catch { /* malformed hex → unbound */ }
+    if (!username) return { username: null, account: null };
+    const account = await this.fetchUsername(username).catch(() => null);
+    return { username, account };
+  }
+
+  /**
+   * SOL balance (lamports) for any address. Accepts either a `PublicKey`
+   * or a base58 string for parity with the legacy `getBalance(addressB58)`.
+   */
+  async getBalance(pubkey) {
+    const key = pubkey instanceof PublicKey ? pubkey : new PublicKey(pubkey);
+    return this.connection.getBalance(key);
+  }
+
+  /**
+   * Withdrawable treasury balance, in lamports (`bigint`).
+   *
+   * Subtracts the rent-exempt minimum AND `total_referral_pending`
+   * (referrers' yet-to-be-claimed cuts) from the Config PDA's lamports
+   * — this matches `withdraw_treasury`'s on-chain ceiling. Returns `0n`
+   * if the Config PDA doesn't exist or the math goes negative.
+   */
+  async fetchTreasuryBalance() {
+    const [pda] = findConfigPDA();
+    const acc = await this.connection.getAccountInfo(pda);
+    if (!acc) return 0n;
+    const totalLamports = BigInt(acc.lamports);
+    const rentMin = BigInt(rentExempt(acc.data.length));
+    let referralPending = 0n;
+    try {
+      const cfg = deserializeConfig(acc.data);
+      // `totalReferralPending` is a BigInt per `Reader.u64`.
+      referralPending = BigInt(cfg.totalReferralPending ?? 0n);
+    } catch { /* config parse failure → assume 0 reservation */ }
+    const w = totalLamports - rentMin - referralPending;
+    return w > 0n ? w : 0n;
+  }
+
+  /**
+   * Resolve a username to its on-chain referrer pubkey (or `null` if
+   * the username doesn't exist or registered without a referrer).
+   *
+   * Pure read against UsernameAccount; cheap.
+   */
+  async resolveReferrer(username) {
+    const u = await this.fetchUsername(username);
+    return u?.referrer ?? null;
+  }
+
+  // ── Program-log subscription (raw, low-level) ─────────────────────
+  //
+  // Anchor `#[event]`s are emitted into transaction logs as
+  //   `Program data: <base64>`
+  // where the base64 payload is `[8-byte event disc][borsh fields]`.
+  // (Plain `msg!()` calls produce `Program log:` lines instead — those
+  // carry no structured event payload.)
+  //
+  // Full Anchor-style event decoding requires an event registry that
+  // maps each 8-byte discriminator to a typed Borsh schema. To stay
+  // dependency-free, this SDK exposes the raw subscription + a
+  // `parseEvent(line)` helper that recognises and base64-decodes the
+  // `Program data:` lines. Callers that need typed events can match
+  // on `event.disc` (first 8 bytes of `event.data`) and Borsh-decode
+  // the tail themselves using the `deserialize.js` Reader pattern.
+  /**
+   * Subscribe to all program logs. `handler` is called once per log
+   * line that originated from the Ping Directory program. The handler
+   * receives `(eventName, payload)`:
+   *
+   *   - For Anchor `#[event]` emissions, `eventName === 'data'` and
+   *     `payload === { disc: Uint8Array(8), data: Uint8Array(...),
+   *                    raw: '<base64>', signature, slot, err }`.
+   *   - For plain `msg!()` lines, `eventName === 'log'` and
+   *     `payload === { line: '<text>', signature, slot, err }`.
+   *
+   * Returns `{ unsubscribe(): Promise<void> }`.
+   */
+  onEvent(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('PingDirectory.onEvent: handler must be a function');
+    }
+    const subId = this.connection.onLogs(
+      PROGRAM_ID,
+      (logsResp, ctx) => {
+        const { signature, err, logs } = logsResp;
+        const slot = ctx?.slot;
+        for (const line of logs ?? []) {
+          const parsed = PingDirectory.parseEvent(line);
+          if (parsed.kind === 'data') {
+            try {
+              handler('data', {
+                disc: parsed.disc,
+                data: parsed.data,
+                raw: parsed.raw,
+                signature,
+                slot,
+                err,
+              });
+            } catch { /* handler errors must not kill the subscription */ }
+          } else if (parsed.kind === 'log') {
+            try {
+              handler('log', { line: parsed.text, signature, slot, err });
+            } catch { /* swallow */ }
+          }
+        }
+      },
+      'confirmed',
+    );
+
+    return {
+      unsubscribe: async () => {
+        try {
+          const id = await Promise.resolve(subId);
+          await this.connection.removeOnLogsListener(id);
+        } catch { /* swallow — already torn down */ }
+      },
+    };
+  }
+
+  /**
+   * Pure helper: classify a single program log line.
+   * - `Program data: <b64>`  → `{ kind: 'data', disc, data, raw }`
+   * - `Program log: <text>`  → `{ kind: 'log',  text }`
+   * - anything else          → `{ kind: 'other', line }`
+   *
+   * Exposed as a static so callers can replay historical tx logs
+   * (e.g. from `getTransaction(...).meta.logMessages`) through the
+   * same parser used by the live subscription.
+   */
+  static parseEvent(line) {
+    if (typeof line !== 'string') return { kind: 'other', line };
+    const DATA_PREFIX = 'Program data: ';
+    const LOG_PREFIX  = 'Program log: ';
+    if (line.startsWith(DATA_PREFIX)) {
+      const raw = line.slice(DATA_PREFIX.length);
+      try {
+        const bin = (typeof Buffer !== 'undefined')
+          ? new Uint8Array(Buffer.from(raw, 'base64'))
+          : Uint8Array.from(atob(raw), (c) => c.charCodeAt(0));
+        if (bin.length < 8) return { kind: 'other', line };
+        return {
+          kind: 'data',
+          disc: bin.slice(0, 8),
+          data: bin.slice(8),
+          raw,
+        };
+      } catch {
+        return { kind: 'other', line };
+      }
+    }
+    if (line.startsWith(LOG_PREFIX)) {
+      return { kind: 'log', text: line.slice(LOG_PREFIX.length) };
+    }
+    return { kind: 'other', line };
+  }
+
+  // ── Submit helper ────────────────────────────────────────────────
+  async submit(built, opts = {}) {
+    const { instructions, signers } = built;
+    const tx = new Transaction().add(...instructions);
+    const sig = await sendAndConfirmTransaction(
+      this.connection, tx, signers, { commitment: 'confirmed', ...opts },
+    );
+    return sig;
+  }
+
+  // ── Detached transaction objects ──────────────────────────────────
+  //
+  // `submit()` builds + signs + sends in one shot with local Keypairs.
+  // The methods below instead produce a *serialized, payer-unsigned*
+  // transaction so a different wallet / relay / sponsor can pay gas and
+  // submit it out-of-band. The ed25519 identity signature is already
+  // baked into the precompile instruction at build time, so no private
+  // key is needed at submit — only the fee payer's signature.
+  //
+  // Short-lived by nature: the embedded blockhash expires (~60-90s), the
+  // nonce PDA is single-use, and register/reserve bake `expectedUserId`
+  // which goes stale if another registration lands first. Build → submit
+  // promptly; don't treat the object as a durable voucher.
+
+  /**
+   * Serialize any ix-builder output into a base64 transaction whose fee
+   * payer is `feePayer` (a PublicKey) but which is NOT yet payer-signed.
+   * Partial-signs with any local Keypairs in `built.signers` that aren't
+   * the fee payer (the ed25519 precompile needs no tx signature). Pass
+   * `recentBlockhash` to avoid an RPC round trip (otherwise fetched).
+   */
+  async buildUnsignedTx(built, { feePayer, recentBlockhash } = {}) {
+    if (!feePayer) throw new Error('buildUnsignedTx: feePayer (PublicKey) required');
+    const fp = feePayer instanceof PublicKey ? feePayer : new PublicKey(feePayer);
+    const { instructions, signers = [] } = built;
+    const tx = new Transaction().add(...instructions);
+    tx.feePayer = fp;
+    tx.recentBlockhash = recentBlockhash
+      ?? (await this.connection.getLatestBlockhash('confirmed')).blockhash;
+    // Real, non-fee-payer Keypairs partial-sign now; their signatures
+    // survive serialization so the eventual payer only adds their own.
+    const local = signers.filter(
+      (s) => s && s.secretKey && s.publicKey && !s.publicKey.equals(fp),
+    );
+    if (local.length) tx.partialSign(...local);
+    const bytes = tx.serialize({ requireAllSignatures: false, verifySignatures: false });
+    return toBase64(bytes);
+  }
+
+  /**
+   * Build a ready-to-pay registration object. The username binds to
+   * `ed25519Keypair.publicKey` (the identity); `feePayer` only funds it —
+   * so a sponsor can pay for someone else's name without gaining any
+   * authority over it. Returns a base64 payer-unsigned transaction.
+   */
+  async buildRegisterTx({ username, ed25519Keypair, accountType = 0, referrer = null, feePayer, nonce, admin = null }) {
+    if (!feePayer) throw new Error('buildRegisterTx: feePayer required');
+    const cfg = await this.fetchConfig();
+    if (!cfg) throw new Error('Config not initialized');
+    const fp = feePayer instanceof PublicKey ? feePayer : new PublicKey(feePayer);
+    const built = ix.register({
+      username, ed25519Keypair, accountType, referrer,
+      expectedUserId: cfg.nextUserId, payer: { publicKey: fp }, nonce, admin,
+    });
+    return this.buildUnsignedTx(built, { feePayer: fp });
+  }
+
+  /**
+   * Relay/sponsor counterpart: sign a serialized (payer-unsigned) tx with
+   * a local fee-payer Keypair and send it. Wallet-adapter consumers
+   * instead `Transaction.from(...)` the bytes and sign via their adapter.
+   */
+  async submitSerializedTx(base64Tx, feePayerKeypair, opts = {}) {
+    const tx = Transaction.from(fromBase64(base64Tx));
+    tx.partialSign(feePayerKeypair);
+    const sig = await this.connection.sendRawTransaction(tx.serialize(), {
+      preflightCommitment: 'confirmed',
+      ...opts,
+    });
+    await this.connection.confirmTransaction(sig, 'confirmed');
+    return sig;
+  }
+
+  // ── High-level methods (resolve dynamic args, build, submit) ─────
+  async register({ username, ed25519Keypair, accountType = 0, referrer = null, payer, nonce, admin = null }) {
+    const cfg = await this.fetchConfig();
+    if (!cfg) throw new Error('Config not initialized');
+    const expectedUserId = cfg.nextUserId;
+    return this.submit(ix.register({
+      username, ed25519Keypair, accountType, referrer, expectedUserId, payer, nonce, admin,
+    }));
+  }
+
+  async reserveUsername({ username, accountType = 0, referrer = null, payer }) {
+    const cfg = await this.fetchConfig();
+    if (!cfg) throw new Error('Config not initialized');
+    const expectedUserId = cfg.nextUserId;
+    return this.submit(ix.reserveUsername({
+      username, accountType, referrer, expectedUserId, payer,
+    }));
+  }
+
+  // attachPubkey just binds the pubkey — referrer + accountType already
+  // live on UsernameAccount from reserve time.
+  async attachPubkey({ username, ed25519Keypair, currentWallet, nonce }) {
+    const map = await this.fetchUserIdMap(username);
+    if (!map) throw new Error(`UidMap missing for ${username}`);
+    return this.submit(ix.attachPubkey({
+      username, ed25519Keypair, currentWallet, userId: map.userId, nonce,
+    }));
+  }
+
+  async transferReserved(args) {
+    return this.submit(ix.transferReserved(args));
+  }
+  async unregisterReserved({ username, currentWallet }) {
+    const map = await this.fetchUserIdMap(username);
+    if (!map) throw new Error(`UidMap missing for ${username}`);
+    return this.submit(ix.unregisterReserved({ username, currentWallet, userId: map.userId }));
+  }
+
+  async updatePubkey(args)     { return this.submit(ix.updatePubkey(args)); }
+  async transferUsername(args) { return this.submit(ix.transferUsername(args)); }
+  async unregisterActive({ username, ...rest }) {
+    const map = await this.fetchUserIdMap(username);
+    if (!map) throw new Error(`UidMap missing for ${username}`);
+    return this.submit(ix.unregisterActive({ username, userId: map.userId, ...rest }));
+  }
+  async setAccountType(args) { return this.submit(ix.setAccountType(args)); }
+
+  async listReserved(args)        { return this.submit(ix.listReserved(args)); }
+  async listActive(args)          { return this.submit(ix.listActive(args)); }
+  async cancelSale(args)          { return this.submit(ix.cancelSale(args)); }
+  /** @deprecated 2026-05 — use cancelSale (LOW-25 rename). */
+  async cancelSaleReserved(args)  { return this.submit(ix.cancelSale(args)); }
+
+  // Buy auto-resolves the slot's referrer so the right `ReferralBalance`
+  // PDA is threaded through. If the caller already supplied
+  // `referrerForUsername` (raw-API use) we skip the fetch.
+  async buyReserved(args) {
+    let referrerForUsername = args.referrerForUsername;
+    if (referrerForUsername === undefined) {
+      const u = await this.fetchUsername(args.username);
+      referrerForUsername = u?.referrer ?? null;
+    }
+    return this.submit(ix.buyReserved({ ...args, referrerForUsername }));
+  }
+  // Post-demote-on-list, every buy/cancel routes through the
+  // Reserved-state path. `buy` / `cancelSale` are state-agnostic
+  // aliases.
+  async buy(args)                 { return this.buyReserved(args); }
+
+  async requestUnlock(args)       { return this.submit(ix.requestUnlock(args)); }
+  async lock(args)                { return this.submit(ix.lock(args)); }
+
+  async initProfilePhoto(args)        { return this.submit(ix.initProfilePhoto(args)); }
+  // writePhotoChunk needs the bound ed25519 (for the freeze-check PDA in
+  // its account list). Caller may pass it directly; otherwise we fetch.
+  async writePhotoChunk({ username, boundEd25519Pubkey, ...rest }) {
+    let bound = boundEd25519Pubkey;
+    if (bound == null) {
+      const u = await this.fetchUsername(username);
+      if (!u) throw new Error(`Username ${username} not registered`);
+      bound = u.ed25519Pubkey;
+    }
+    return this.submit(ix.writePhotoChunk({
+      username, boundEd25519Pubkey: bound, ...rest,
+    }));
+  }
+  async finalizeProfilePhoto(args)    { return this.submit(ix.finalizeProfilePhoto(args)); }
+  // High-level: caller usually doesn't know `init_payer` (the wallet that
+  // originally allocated the photo PDA — rent on close goes back to it).
+  // Auto-resolve from the on-chain photo PDA when not provided.
+  async clearProfilePhoto({ username, initPayer, ...rest }) {
+    let resolvedInitPayer = initPayer;
+    if (resolvedInitPayer == null) {
+      const photo = await this.fetchProfilePhoto(username);
+      if (!photo) throw new Error(`No profile photo to clear for ${username}`);
+      resolvedInitPayer = photo.initPayer;
+    }
+    return this.submit(ix.clearProfilePhoto({
+      username, initPayer: resolvedInitPayer, ...rest,
+    }));
+  }
+
+  /**
+   * High-level: upload a profile photo end-to-end (init → chunks → finalize).
+   *
+   * The on-chain flow is 3-step (init allocates, chunks fill, finalize locks
+   * with a hash). Most callers want a single async call that handles all of
+   * it. This wraps the three primitives.
+   *
+   * Args:
+   *   - `username`         — Active username binding the photo
+   *   - `imageBytes`       — Uint8Array, ≤10_181 bytes (Solana realloc cap)
+   *   - `mime`             — 0=jpeg, 1=png, 2=webp, 3=gif (see PhotoMime)
+   *   - `width`, `height`  — px dimensions, 1..=8192 each
+   *   - `ed25519Keypair`   — bound ed25519 sign keypair (for init + finalize sigs)
+   *   - `payer`            — Solana Keypair that pays the per-mime fee + chunk rent
+   *   - `chunkSize?`       — bytes per write_photo_chunk tx, default 900
+   *                          (tx data cap is ~1232 bytes; 900 leaves room for
+   *                           ix discriminator + account list + base64 tx framing)
+   *   - `onProgress?`      — `(written: number, total: number) => void`
+   *                          Called after init (0/total), each successful chunk,
+   *                          and once more pre-finalize.
+   *
+   * Returns: `{ initSig, chunkSigs, finalizeSig }` for callers that want
+   * the individual signatures (e.g. for tx-history display).
+   *
+   * Idempotency: if `init` succeeds but a later chunk or finalize fails, the
+   * partial PDA persists. Caller should `clearProfilePhoto` to reset, then retry.
+   */
+  async setProfilePhoto({
+    username, imageBytes, mime, width, height,
+    ed25519Keypair, payer, chunkSize = 900, onProgress,
+  }) {
+    if (!imageBytes || imageBytes.length === 0) {
+      throw new Error('setProfilePhoto: imageBytes is empty');
+    }
+    const total = imageBytes.length;
+    onProgress?.(0, total);
+
+    // 0. If a previous upload partially completed (init succeeded but
+    //    a later step failed), the photo PDA exists with `finalized: false`.
+    //    Re-attempting `init` would collide with "already in use" (custom 0x0
+    //    from the system program). Detect + auto-clear so the retry works.
+    //    A FINALIZED photo we leave alone — caller must explicitly clear
+    //    before re-uploading (otherwise an accidental double-click overwrites
+    //    a healthy on-chain photo).
+    const existing = await this.fetchProfilePhoto(username);
+    if (existing) {
+      if (existing.finalized) {
+        throw new Error(
+          'setProfilePhoto: a finalized photo already exists for this username. ' +
+          'Call clearProfilePhoto first to replace it.',
+        );
+      }
+      // Stale partial upload — clear to reset. `clearProfilePhoto` routes
+      // rent back to the original `init_payer` (whoever opened the upload
+      // slot), which we read from the existing PDA.
+      await this.clearProfilePhoto({
+        username, ed25519Keypair, payer,
+        initPayer: existing.initPayer,
+      });
+    }
+
+    // 1. Allocate buffer + pay per-mime fee.
+    const initSig = await this.initProfilePhoto({
+      username, totalSize: total, mime, width, height,
+      ed25519Keypair, payer,
+    });
+
+    // 2. Stream chunks sequentially. Solana orders chunks within the
+    //    photo PDA by `offset` so parallel writes would also work, but
+    //    sequential is simpler and the per-tx round-trip is fast.
+    const chunkSigs = [];
+    const boundEd25519Pubkey = ed25519Keypair.publicKey;
+    for (let off = 0; off < total; off += chunkSize) {
+      const slice = imageBytes.subarray(off, Math.min(off + chunkSize, total));
+      const sig = await this.writePhotoChunk({
+        username, offset: off, chunk: slice, payer, boundEd25519Pubkey,
+      });
+      chunkSigs.push(sig);
+      onProgress?.(off + slice.length, total);
+    }
+
+    // 3. Finalize with SHA-256(imageBytes). Pure-JS sha256 (sync, no
+    //    `crypto.subtle` dep — that's missing in non-secure-context
+    //    browsers and some Tauri WebView configs).
+    const imageHash = sha256(imageBytes);
+    const finalizeSig = await this.finalizeProfilePhoto({
+      username, imageHash, mime, width, height,
+      ed25519Keypair, payer,
+    });
+    onProgress?.(total, total);
+
+    return { initSig, chunkSigs, finalizeSig };
+  }
+
+  async shopAddItem(args)             { return this.submit(ix.shopAddItem(args)); }
+  async shopUpdateItem(args)          { return this.submit(ix.shopUpdateItem(args)); }
+  async shopSetProOnly(args)          { return this.submit(ix.shopSetProOnly(args)); }
+  async shopSetActive(args)           { return this.submit(ix.shopSetActive(args)); }
+  // Ergonomic delist / relist over shop_set_active (active flag only;
+  // price is untouched, unlike shop_update_item).
+  async delistItem({ id, signer, admin = null }) { return this.submit(ix.shopSetActive({ id, active: false, signer, admin })); }
+  async relistItem({ id, signer, admin = null }) { return this.submit(ix.shopSetActive({ id, active: true,  signer, admin })); }
+  // High-level: resolves bound key + UsernameAccount.referrer before
+  // building the ix.
+  async purchaseItem({ username, itemId, expectedPrice, payer }) {
+    const u = await this.fetchUsername(username);
+    if (!u) throw new Error(`Username ${username} not registered`);
+    return this.submit(ix.purchaseItem({
+      username, itemId, expectedPrice, payer,
+      boundEd25519Pubkey: u.ed25519Pubkey,
+      referrerForUsername: u.referrer,
+    }));
+  }
+  // gift_item: owner/admin drops an item into a username's inventory for
+  // free. Resolves the bound ed25519 key like purchaseItem. `payer` funds
+  // the inventory rent (defaults to `signer`).
+  async giftItem({ username, itemId, signer, payer = signer, admin = null }) {
+    const u = await this.fetchUsername(username);
+    if (!u) throw new Error(`Username ${username} not registered`);
+    return this.submit(ix.giftItem({
+      username, itemId, signer, payer, admin,
+      boundEd25519Pubkey: u.ed25519Pubkey,
+    }));
+  }
+  async equipItem(args)               { return this.submit(ix.equipItem(args)); }
+  async unequipSlot(args)             { return this.submit(ix.unequipSlot(args)); }
+  async equipProDefault(args)     { return this.submit(ix.equipProDefault(args)); }
+  async discardItem(args)             { return this.submit(ix.discardItem(args)); }
+
+  async subscribePro({ username, months, payer }) {
+    const u = await this.fetchUsername(username);
+    if (!u) throw new Error(`Username ${username} not registered`);
+    return this.submit(ix.subscribePro({
+      username, months, payer,
+      boundEd25519Pubkey: u.ed25519Pubkey,
+      referrerForUsername: u.referrer,
+    }));
+  }
+  // setPro writes to UsernameAccount; no ed25519_account in the
+  // on-chain account list (admin/owner path is not freeze-gated).
+  async setPro(args) { return this.submit(ix.setPro(args)); }
+  async withdrawReferral(args)        { return this.submit(ix.withdrawReferral(args)); }
+
+  async initialize(args)              { return this.submit(ix.initialize(args)); }
+  async addAdmin(args)                { return this.submit(ix.addAdmin(args)); }
+  async removeAdmin(args)             { return this.submit(ix.removeAdmin(args)); }
+  async proposeOwner(args)            { return this.submit(ix.proposeOwner(args)); }
+  async acceptOwner(args)             { return this.submit(ix.acceptOwner(args)); }
+  async cancelProposeOwner(args)      { return this.submit(ix.cancelProposeOwner(args)); }
+  async pauseRegistration(args)       { return this.submit(ix.pauseRegistration(args)); }
+  async pausePro(args)            { return this.submit(ix.pausePro(args)); }
+  async blocklistAdd(args)            { return this.submit(ix.blocklistAdd(args)); }
+  async blocklistRemove(args)         { return this.submit(ix.blocklistRemove(args)); }
+
+  async addTreasuryWallet(args)       { return this.submit(ix.addTreasuryWallet(args)); }
+  async removeTreasuryWallet(args)    { return this.submit(ix.removeTreasuryWallet(args)); }
+  // Resolves whether the signer is a treasury wallet (vs the owner) and
+  // passes the right optional PDA so a treasury wallet claims to itself.
+  // Back-compat: `{ owner }` still works (owner path).
+  async withdrawTreasury({ signer, owner, treasuryWalletPda } = {}) {
+    const s = signer ?? owner;
+    let twPda = treasuryWalletPda ?? null;
+    if (!twPda && s) {
+      const tw = await this.getTreasuryWallet(s.publicKey);
+      if (tw) twPda = findTreasuryWalletPDA(s.publicKey)[0];
+    }
+    return this.submit(ix.withdrawTreasury({ signer: s, treasuryWalletPda: twPda }));
+  }
+  async setRegistrationFee(args)      { return this.submit(ix.setRegistrationFee(args)); }
+  async setProPriceMonthly(args)  { return this.submit(ix.setProPriceMonthly(args)); }
+  async setProPriceLifetime(args) { return this.submit(ix.setProPriceLifetime(args)); }
+  async setSaleFee(args)              { return this.submit(ix.setSaleFee(args)); }
+  async setMinSalePrice(args)         { return this.submit(ix.setMinSalePrice(args)); }
+  async setGracePeriod(args)          { return this.submit(ix.setGracePeriod(args)); }
+  async setUnlockDelay(args)          { return this.submit(ix.setUnlockDelay(args)); }
+  async setUnlockWindow(args)         { return this.submit(ix.setUnlockWindow(args)); }
+  async setAutoUnfreezeDelay(args)    { return this.submit(ix.setAutoUnfreezeDelay(args)); }
+  async setProfilePhotoFee(args)      { return this.submit(ix.setProfilePhotoFee(args)); }
+
+  // Sweep the dust ReferralBalance PDA at the zero-pubkey seed (owner-only).
+  async adminCloseZeroReferral(args)  { return this.submit(ix.adminCloseZeroReferral(args)); }
+
+  // ── Key revocation ───────────────────────────────────────────────
+  async markCompromised(args)         { return this.submit(ix.markCompromised(args)); }
+
+  // ── Permissionless time-gated unfreeze for compromised-key freezes ─
+  // Resolves the bound ed25519 pubkey + user_id from chain state and
+  // builds the `auto_unfreeze_username` ix. Anyone can call this once
+  // `Config.auto_unfreeze_delay` has elapsed since `mark_compromised`.
+  // The username's UsernameAccount flips to UNREGISTERED in place (the
+  // PDA is permanent); inventory / photo / sale_listing PDAs (if any)
+  // are closed in-place and their rent flows to `caller`. UidMap rent
+  // also flows to `caller`. The slot is then immediately re-claimable.
+  async autoUnfreezeUsername({ username, caller }) {
+    const u = await this.fetchUsername(username);
+    if (!u) throw new Error(`Username ${username} not registered`);
+    const map = await this.fetchUserIdMap(username);
+    if (!map) throw new Error(`UidMap missing for ${username}`);
+    return this.submit(ix.autoUnfreezeUsername({
+      username,
+      frozenEd25519Pubkey: u.ed25519Pubkey,
+      userId: map.userId,
+      caller,
+    }));
+  }
+}