@microslop/ping-directory-sdk 0.1.5

package/src/fees.js

@@ -0,0 +1,102 @@
+// Deterministic transaction-fee math (no RPC required).
+//
+// Ported from the legacy SDK (helpers.js). Mirrors `Config::fee_for_length`
+// and the per-account `SIZE` constants in the Anchor program's `state/*.rs`.
+
+/** Format lamports as a SOL string with 4 decimals (matches the legacy SDK behavior). */
+export function lamportsToSol(lamports) {
+  // The legacy SDK returned a string; clients depend on the exact formatting.
+  const n = typeof lamports === 'bigint' ? Number(lamports) : lamports;
+  return (n / 1_000_000_000).toFixed(4);
+}
+
+/** Inverse of lamportsToSol — parse a SOL string/number to integer lamports. */
+export function solToLamports(sol) {
+  return Math.round(parseFloat(sol) * 1e9);
+}
+
+/** Solana rent-exempt minimum (lamports) for a given account data size in bytes. */
+export function rentExempt(dataSize) {
+  return Math.ceil((128 + dataSize) * 6960);
+}
+
+/**
+ * Tiered registration fee selector for `Config::registration_fees` (length 7).
+ * Tiers 1..=6 = exact username length, tier 7 = "7 or more".
+ */
+export function feeForLength(registrationFees, len) {
+  const idx = len >= 7 ? 6 : Math.max(0, len - 1);
+  return registrationFees[idx];
+}
+
+/** Solana base tx fee: 5,000 lamports per signature. */
+export function txFee(numSignatures = 1) {
+  return numSignatures * 5000;
+}
+
+// Account sizes (mirror const SIZE in `state/*.rs`).
+const ACCOUNT_SIZES = {
+  usernameAccount: 8 + (4 + 20) + 32 + (1 + 32) + (1 + 32) + 8 + 8 + 1 + 8 + 1 + 16 + 16 + (1 + 4) * 3 + 1,
+  reverseLookup:   8 + (4 + 20) + 1,
+  keyHistory:      8 + 4 + 1,
+  nonce:           8 + 1,
+  saleListing:     8 + 8 + 32 + 1,
+  pendingRecovery: 8 + 32 + 8 + 1,
+  gracePeriod:     8 + 32 + 8 + 1,
+  walletLink:      8 + (4 + 20) + 1,
+  inventory:       8 + 4 + 128 * 4 + 1,
+  shopItem:        8 + 4 + 1 + 8 + 1 + (4 + 512) + 1,
+  stakedBalance:   8 + 8 + 8 + 16 + 1,
+};
+
+/** Add ~10% buffer for priority fees / compute budget. */
+function withBuffer(lamports) {
+  return Math.ceil(lamports * 1.1);
+}
+
+/**
+ * Estimated transaction fees (lamports) for each operation.
+ * Includes base tx fee + rent for new PDAs + ~10% buffer for priority/compute.
+ * Does NOT include program fees (registration_fee, etc). Deterministic — no RPC.
+ */
+export const txFees = {
+  // Register also creates a WalletLink (the wallet is bound atomically).
+  register: withBuffer(
+    txFee(2)
+    + rentExempt(ACCOUNT_SIZES.usernameAccount)
+    + rentExempt(ACCOUNT_SIZES.reverseLookup)
+    + rentExempt(ACCOUNT_SIZES.keyHistory)
+    + rentExempt(ACCOUNT_SIZES.nonce)
+    + rentExempt(ACCOUNT_SIZES.walletLink)
+  ),
+  unregister: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce) + rentExempt(ACCOUNT_SIZES.gracePeriod)),
+  updatePubkey: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.reverseLookup) + rentExempt(ACCOUNT_SIZES.nonce)),
+  transferUsername: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.reverseLookup) + rentExempt(ACCOUNT_SIZES.nonce)),
+  requestUnlock: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  lock: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  walletLock: withBuffer(txFee(1)),
+  listForSale: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.saleListing) + rentExempt(ACCOUNT_SIZES.nonce)),
+  buyUsername: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.reverseLookup)),
+  cancelSale: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  // Swap mode: closes old WalletLink (rent refund) and inits new one (rent cost).
+  // Net rent delta is 0; only tx + nonce rent count.
+  associateWallet: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  removeWallet: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  initiateRecovery: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.pendingRecovery)),
+  finalizeRecovery: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.reverseLookup)),
+  vetoRecovery: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  subscribePro: withBuffer(txFee(1)),
+  setAccountType: withBuffer(txFee(2) + rentExempt(ACCOUNT_SIZES.nonce)),
+  withdrawReferral: withBuffer(txFee(1)),
+  // Shop / staking
+  shopAddItem: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.shopItem)),
+  shopUpdateItem: withBuffer(txFee(1)),
+  // First purchase initializes the Inventory PDA; subsequent purchases reuse it.
+  // We charge the rent every call to be conservative for fee estimates.
+  purchaseItem: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.inventory)),
+  equipItem: withBuffer(txFee(1)),
+  unequipSlot: withBuffer(txFee(1)),
+  stake: withBuffer(txFee(1) + rentExempt(ACCOUNT_SIZES.stakedBalance)),
+  extendStake: withBuffer(txFee(1)),
+  claimStake: withBuffer(txFee(1)),
+};

package/src/format.js

@@ -0,0 +1,149 @@
+// Address / hex / base58 formatting helpers.
+//
+// Ported from the legacy SDK (encoding.js + helpers.js) so the v1.0.0
+// SDK is a drop-in replacement at client callsites.
+//
+// Pure JS — no new runtime deps. We inline a minimal SHA3-256 (Keccak f1600
+// with SHA-3 padding 0x06) here so we don't pull in @noble/hashes just for
+// the .ping address checksum.
+
+// ── Hex helpers ─────────────────────────────────────────────────────
+
+/** Encode a Uint8Array as lowercase hex (no `0x` prefix). */
+export function bytesToHex(bytes) {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Decode a hex string (no `0x` prefix, even length) into a Uint8Array. */
+export function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+  return bytes;
+}
+
+// ── Base58 (Bitcoin alphabet) ───────────────────────────────────────
+
+const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+/** Base58 encode arbitrary bytes (Bitcoin alphabet). */
+export function b58encode(bytes) {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  if (zeros === bytes.length) return '1'.repeat(bytes.length);
+  let num = 0n;
+  for (const b of bytes) num = num * 256n + BigInt(b);
+  let str = '';
+  while (num > 0n) { str = B58[Number(num % 58n)] + str; num /= 58n; }
+  return '1'.repeat(zeros) + str;
+}
+
+// ── Base32 (RFC 4648, no padding) ───────────────────────────────────
+
+const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function base32Encode(bytes) {
+  let bits = 0, val = 0, out = '';
+  for (const b of bytes) {
+    val = (val << 8) | b;
+    bits += 8;
+    while (bits >= 5) { bits -= 5; out += B32[(val >>> bits) & 31]; }
+  }
+  if (bits > 0) out += B32[(val << (5 - bits)) & 31];
+  return out;
+}
+
+// ── Minimal SHA3-256 (Keccak f1600, SHA-3 padding 0x06) ─────────────
+// ~60 LOC pure JS. Only used by pingChecksum below.
+
+const KECCAK_RC = [
+  0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n,
+  0x000000000000808bn, 0x0000000080000001n, 0x8000000080008081n, 0x8000000000008009n,
+  0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+  0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n,
+  0x8000000000008002n, 0x8000000000000080n, 0x000000000000800an, 0x800000008000000an,
+  0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const KECCAK_R = [0,1,62,28,27,36,44,6,55,20,3,10,43,25,39,41,45,15,21,8,18,2,61,56,14];
+const MASK64 = 0xffffffffffffffffn;
+const rotl64 = (x, n) => (((x << BigInt(n)) | (x >> BigInt(64 - n))) & MASK64);
+
+function keccakF1600(s) {
+  for (let r = 0; r < 24; r++) {
+    // θ
+    const C = new Array(5);
+    for (let x = 0; x < 5; x++) C[x] = s[x] ^ s[x+5] ^ s[x+10] ^ s[x+15] ^ s[x+20];
+    const D = new Array(5);
+    for (let x = 0; x < 5; x++) D[x] = C[(x+4)%5] ^ rotl64(C[(x+1)%5], 1);
+    for (let i = 0; i < 25; i++) s[i] ^= D[i % 5];
+    // ρ + π
+    const B = new Array(25);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) {
+      B[y + ((2*x + 3*y) % 5) * 5] = rotl64(s[x + y*5], KECCAK_R[x + y*5]);
+    }
+    // χ
+    for (let y = 0; y < 5; y++) for (let x = 0; x < 5; x++) {
+      s[x + y*5] = B[x + y*5] ^ ((~B[((x+1)%5) + y*5]) & MASK64 & B[((x+2)%5) + y*5]);
+    }
+    // ι
+    s[0] ^= KECCAK_RC[r];
+  }
+}
+
+function sha3_256(data) {
+  // SHA3-256: rate = 136 bytes, output 32 bytes, domain pad 0x06.
+  const rate = 136;
+  // Pad
+  const padLen = rate - (data.length % rate);
+  const padded = new Uint8Array(data.length + padLen);
+  padded.set(data, 0);
+  padded[data.length] = 0x06;
+  padded[padded.length - 1] |= 0x80;
+  // Absorb
+  const state = new Array(25).fill(0n);
+  for (let off = 0; off < padded.length; off += rate) {
+    for (let i = 0; i < rate / 8; i++) {
+      let lane = 0n;
+      for (let j = 0; j < 8; j++) lane |= BigInt(padded[off + i*8 + j]) << BigInt(j*8);
+      state[i] ^= lane;
+    }
+    keccakF1600(state);
+  }
+  // Squeeze 32 bytes
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 4; i++) {
+    let lane = state[i];
+    for (let j = 0; j < 8; j++) { out[i*8 + j] = Number(lane & 0xffn); lane >>= 8n; }
+  }
+  return out;
+}
+
+// ── Ping address encoding ───────────────────────────────────────────
+// Domain-separated checksum + base32 + ".ping" suffix.
+
+const PING_VERSION = 0x01;
+const PING_DOMAIN = new TextEncoder().encode('.ping checksum');
+
+function pingChecksum(pkBytes) {
+  const buf = new Uint8Array(PING_DOMAIN.length + pkBytes.length + 1);
+  buf.set(PING_DOMAIN, 0);
+  buf.set(pkBytes, PING_DOMAIN.length);
+  buf[buf.length - 1] = PING_VERSION;
+  const d = sha3_256(buf);
+  return new Uint8Array([d[0], d[1]]);
+}
+
+/**
+ * Convert a 32-byte Ed25519 pubkey to a .ping address.
+ * Format: base32(pk || checksum2 || version1).toLowerCase() + ".ping"
+ */
+export function pubkeyBytesToPingAddress(pkBytes) {
+  if (!(pkBytes instanceof Uint8Array) || pkBytes.length !== 32) {
+    throw new Error('pubkeyBytesToPingAddress: expected 32-byte Uint8Array');
+  }
+  const cs = pingChecksum(pkBytes);
+  const payload = new Uint8Array(35);
+  payload.set(pkBytes, 0);
+  payload.set(cs, 32);
+  payload[34] = PING_VERSION;
+  return base32Encode(payload).toLowerCase() + '.ping';
+}

package/src/identicon.js

@@ -0,0 +1,364 @@
+/**
+ * Ping Identicon Generator (v2)
+ *
+ * Generates deterministic identicons from Ed25519 hex pubkeys with a
+ * built-in foreground icon overlay (user / group). Designed to give a
+ * recognizable "this is a user" or "this is a group" cue at any size,
+ * while still varying the background uniquely per pubkey.
+ *
+ * Pipeline:
+ *   1. seed RNG from the input
+ *   2. pick one of 5 background styles (Pixels, Diamonds, Plasma, Slab,
+ *      Voronoi) based on a hash of first/middle/last 4 chars
+ *   3. paint the background
+ *   4. read the average color of the central 40% of the canvas
+ *   5. derive a foreground that's the perceptual *negative* of the
+ *      background (complementary hue, inverted lightness, high
+ *      saturation) — guarantees readable contrast and visual interest
+ *   6. paint a centered user / group silhouette in that foreground
+ *
+ * Usage:
+ *   drawIdenticon(canvas, '<hex pubkey>', 64);                    // user
+ *   drawIdenticon(canvas, '<hex pubkey>', 64, { kind: 'group' }); // group
+ *   drawIdenticon(canvas, '<addr>.ping',  64);                    // ping addr also accepted
+ *
+ * Backward compat — `drawIdenticon(canvas, key, size)` continues to
+ * work and renders a user-kind avatar. The 20-style legacy API has
+ * been retired; `IDENTICON_STYLE_COUNT === 5` now.
+ */
+
+// ── Seeded RNG ──────────────────────────────────────────────────────
+function hashStr(str) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+  return h;
+}
+function seededRand(seed) {
+  let s = seed | 0;
+  return () => { s = (s * 16807 + 0) % 2147483647; return (s & 0x7fffffff) / 0x7fffffff; };
+}
+function pick(rand, arr) { return arr[Math.floor(rand() * arr.length)]; }
+
+// ── Palettes ────────────────────────────────────────────────────────
+const PALETTES = [
+  ['#7c3aed', '#a78bfa', '#6d28d9', '#4c1d95', '#1e1b4b'],
+  ['#8b5cf6', '#c4b5fd', '#5b21b6', '#7e22ce', '#2e1065'],
+  ['#7c3aed', '#22d3ee', '#6d28d9', '#0891b2', '#1e1b4b'],
+  ['#9333ea', '#a855f7', '#7e22ce', '#6366f1', '#312e81'],
+  ['#8b5cf6', '#34d399', '#6d28d9', '#059669', '#1e1b4b'],
+  ['#a78bfa', '#f472b6', '#7c3aed', '#ec4899', '#2e1065'],
+  ['#6366f1', '#818cf8', '#4f46e5', '#3730a3', '#1e1b4b'],
+  ['#8b5cf6', '#fbbf24', '#6d28d9', '#d97706', '#2e1065'],
+];
+
+const BG = ['#0d0d1a', '#12121e', '#151525', '#0a0a14', '#100e1e', '#0e0c18'];
+
+/** Normalize input to a hex pubkey string (strip .ping suffix if present). */
+function normalizeKey(input) {
+  if (!input) return '';
+  return input.replace(/\.ping$/i, '');
+}
+
+/**
+ * Pick style index from first 4 + middle 4 + last 4 chars of the key.
+ * Combines their char codes for better distribution across all styles.
+ */
+function pickStyle(key) {
+  if (key.length < 12) return Math.abs(hashStr(key)) % STYLES.length;
+  const mid = Math.floor(key.length / 2);
+  const combined =
+    hashStr(key.slice(0, 4)) ^
+    hashStr(key.slice(mid - 2, mid + 2)) ^
+    hashStr(key.slice(-4));
+  return Math.abs(combined) % STYLES.length;
+}
+
+function setup(input) {
+  const key = normalizeKey(input);
+  const h = hashStr(key);
+  const rand = seededRand(h);
+  const pal = PALETTES[Math.abs(h) % PALETTES.length];
+  const bg = BG[Math.abs(h >> 3) % BG.length];
+  return { key, h, rand, pal, bg };
+}
+
+// ── Backgrounds (5 curated styles) ──────────────────────────────────
+
+function drawPixels(ctx, size, rand, pal, bg) {
+  ctx.fillStyle = bg;
+  ctx.fillRect(0, 0, size, size);
+  const g = 5, cs = size / g, half = Math.ceil(g / 2);
+  const cells = [];
+  for (let y = 0; y < g; y++) {
+    cells[y] = [];
+    for (let x = 0; x < half; x++) cells[y][x] = rand() > 0.4;
+    for (let x = half; x < g; x++) cells[y][x] = cells[y][g - 1 - x];
+  }
+  for (let y = 0; y < g; y++) {
+    for (let x = 0; x < g; x++) {
+      if (!cells[y][x]) continue;
+      ctx.fillStyle = pick(rand, pal);
+      ctx.globalAlpha = 0.6 + rand() * 0.4;
+      ctx.fillRect(x * cs, y * cs, cs, cs);
+    }
+  }
+  ctx.globalAlpha = 1;
+}
+
+function drawDiamonds(ctx, size, rand, pal, bg) {
+  ctx.fillStyle = bg;
+  ctx.fillRect(0, 0, size, size);
+  const g = 4, cs = size / g;
+  ctx.save();
+  ctx.translate(size / 2, size / 2);
+  ctx.rotate(Math.PI / 4);
+  ctx.translate(-size / 2, -size / 2);
+  for (let y = -1; y <= g + 1; y++) {
+    for (let x = -1; x <= g + 1; x++) {
+      if (rand() <= 0.35) continue;
+      ctx.fillStyle = pick(rand, pal);
+      ctx.globalAlpha = 0.3 + rand() * 0.6;
+      const p = cs * 0.1;
+      ctx.fillRect(x * cs + p, y * cs + p, cs - p * 2, cs - p * 2);
+    }
+  }
+  ctx.restore();
+  ctx.globalAlpha = 1;
+}
+
+function drawPlasma(ctx, size, rand, pal, bg) {
+  const img = ctx.createImageData(size, size);
+  const freqs = [rand() * 0.08 + 0.02, rand() * 0.08 + 0.02, rand() * 0.06 + 0.01];
+  const phases = [rand() * 10, rand() * 10, rand() * 10];
+  const hex2rgb = (hex) => [
+    parseInt(hex.slice(1, 3), 16),
+    parseInt(hex.slice(3, 5), 16),
+    parseInt(hex.slice(5, 7), 16),
+  ];
+  const c1 = hex2rgb(pal[0]);
+  const c2 = hex2rgb(pal[1]);
+  const c3 = hex2rgb(pal[3] || pal[0]);
+  const bgc = hex2rgb(bg);
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const v =
+        (Math.sin(x * freqs[0] + phases[0]) +
+          Math.sin(y * freqs[1] + phases[1]) +
+          Math.sin((x + y) * freqs[2] + phases[2])) /
+        3;
+      const t = (v + 1) / 2;
+      const col =
+        t < 0.33
+          ? c1.map((c, i) => Math.round(bgc[i] + (c - bgc[i]) * (t / 0.33)))
+          : t < 0.66
+          ? c1.map((c, i) => Math.round(c + (c2[i] - c) * ((t - 0.33) / 0.33)))
+          : c2.map((c, i) => Math.round(c + (c3[i] - c) * ((t - 0.66) / 0.34)));
+      const idx = (y * size + x) * 4;
+      img.data[idx] = col[0];
+      img.data[idx + 1] = col[1];
+      img.data[idx + 2] = col[2];
+      img.data[idx + 3] = 255;
+    }
+  }
+  ctx.putImageData(img, 0, 0);
+}
+
+function drawSlab(ctx, size, rand, pal) {
+  const angle = rand() * Math.PI * 2;
+  const x1 = size / 2 + Math.cos(angle) * size / 2;
+  const y1 = size / 2 + Math.sin(angle) * size / 2;
+  const x2 = size / 2 - Math.cos(angle) * size / 2;
+  const y2 = size / 2 - Math.sin(angle) * size / 2;
+  const grad = ctx.createLinearGradient(x1, y1, x2, y2);
+  grad.addColorStop(0, pal[0]);
+  grad.addColorStop(0.5, pal[1]);
+  grad.addColorStop(1, pal[3] || pal[2]);
+  ctx.fillStyle = grad;
+  ctx.fillRect(0, 0, size, size);
+  ctx.globalAlpha = 0.06;
+  for (let i = 0; i < size * size * 0.03; i++) {
+    ctx.fillStyle = rand() > 0.5 ? '#fff' : '#000';
+    ctx.fillRect(Math.floor(rand() * size), Math.floor(rand() * size), 1, 1);
+  }
+  ctx.globalAlpha = 1;
+}
+
+function drawVoronoi(ctx, size, rand, pal, bg) {
+  ctx.fillStyle = bg;
+  ctx.fillRect(0, 0, size, size);
+  const n = 6 + Math.floor(rand() * 6);
+  const seeds = [];
+  const colors = [];
+  for (let i = 0; i < n; i++) {
+    seeds.push([rand() * size, rand() * size]);
+    colors.push(pick(rand, pal));
+  }
+  const hex2rgb = (hex) => [
+    parseInt(hex.slice(1, 3), 16),
+    parseInt(hex.slice(3, 5), 16),
+    parseInt(hex.slice(5, 7), 16),
+  ];
+  const rgbs = colors.map(hex2rgb);
+  const img = ctx.createImageData(size, size);
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      let minD = Infinity;
+      let minI = 0;
+      for (let i = 0; i < n; i++) {
+        const d = (x - seeds[i][0]) ** 2 + (y - seeds[i][1]) ** 2;
+        if (d < minD) { minD = d; minI = i; }
+      }
+      const idx = (y * size + x) * 4;
+      img.data[idx] = rgbs[minI][0];
+      img.data[idx + 1] = rgbs[minI][1];
+      img.data[idx + 2] = rgbs[minI][2];
+      img.data[idx + 3] = 200;
+    }
+  }
+  ctx.putImageData(img, 0, 0);
+  ctx.globalAlpha = 1;
+}
+
+const STYLES = [drawPixels, drawDiamonds, drawPlasma, drawSlab, drawVoronoi];
+
+const STYLE_NAMES = ['Pixels', 'Diamonds', 'Plasma', 'Slab', 'Voronoi'];
+
+// ── Foreground color = black or white based on background luminance ─
+//
+// The earlier implementation read the central 40% of the canvas via
+// `ctx.getImageData()` to compute Rec. 709 luminance from the actual
+// pixels. That triggers Tor Browser's canvas-fingerprint defense
+// (modal "allow site to access HTML5 canvas image data?" prompt) on
+// every avatar render — unacceptable UX. The inputs are deterministic
+// (palette + bg are a function of the seed), so we approximate the
+// central-area average colour analytically: weighted blend of palette
+// average with the background, then Rec. 709 luma. The 0.55 cutoff
+// matches the old behaviour and keeps the bias toward a white icon
+// (dark silhouettes on mid-bright backgrounds disappear faster than
+// the inverse). The cosmetic diff vs. true sampling is small because
+// the central area is dominated by bg + a few palette daubs across
+// every style — and a small drop shadow on the icon keeps the edge
+// legible regardless.
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+function pickIconFg(pal, bg) {
+  // Approximate central-region coverage: backgrounds fill the canvas
+  // with `bg` first then paint palette colours over the top. The
+  // central 40% sees roughly 35% palette pixels averaged across the 5
+  // styles (Slab is highest, Pixels/Diamonds lowest); 0.35 is a
+  // pragmatic single number that lands close on all five.
+  const PALETTE_WEIGHT = 0.35;
+  let pr = 0, pg = 0, pb = 0;
+  for (const c of pal) {
+    const { r, g, b } = hexToRgb(c);
+    pr += r; pg += g; pb += b;
+  }
+  pr /= pal.length; pg /= pal.length; pb /= pal.length;
+  const bgc = hexToRgb(bg);
+  const r = pr * PALETTE_WEIGHT + bgc.r * (1 - PALETTE_WEIGHT);
+  const g = pg * PALETTE_WEIGHT + bgc.g * (1 - PALETTE_WEIGHT);
+  const b = pb * PALETTE_WEIGHT + bgc.b * (1 - PALETTE_WEIGHT);
+  const luma = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  return luma > 0.55 ? '#000' : '#fff';
+}
+
+// ── Icon overlays — black or white silhouettes ─────────────────────
+
+function drawUserIcon(ctx, size, color) {
+  const cx = size / 2;
+  const cy = size / 2;
+  ctx.save();
+  ctx.fillStyle = color;
+  // Head
+  ctx.beginPath();
+  ctx.arc(cx, cy - size * 0.12, size * 0.14, 0, Math.PI * 2);
+  ctx.fill();
+  // Shoulders / body — half-disc
+  ctx.beginPath();
+  ctx.arc(cx, cy + size * 0.34, size * 0.30, Math.PI, 0);
+  ctx.fill();
+  ctx.restore();
+}
+
+function drawGroupIcon(ctx, size, color) {
+  const cx = size / 2;
+  const cy = size / 2;
+  ctx.save();
+  ctx.fillStyle = color;
+  // Three people with depth — back-left + back-right peeking, front
+  // person centered + larger drawn last so it occludes the back row.
+  // Reads as a cluster, not a face.
+  ctx.beginPath();
+  ctx.arc(cx - size * 0.22, cy - size * 0.18, size * 0.095, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(cx - size * 0.22, cy + size * 0.20, size * 0.20, Math.PI, 0);
+  ctx.fill();
+
+  ctx.beginPath();
+  ctx.arc(cx + size * 0.22, cy - size * 0.18, size * 0.095, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(cx + size * 0.22, cy + size * 0.20, size * 0.20, Math.PI, 0);
+  ctx.fill();
+
+  // Front-center person
+  ctx.beginPath();
+  ctx.arc(cx, cy - size * 0.06, size * 0.13, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(cx, cy + size * 0.34, size * 0.26, Math.PI, 0);
+  ctx.fill();
+  ctx.restore();
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Draw an identicon onto a canvas element.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {string} input — hex pubkey or ping address
+ * @param {number} size — pixel size (canvas will be set to size × size)
+ * @param {object} [opts]
+ * @param {'user' | 'group'} [opts.kind='user'] — which icon overlay to paint
+ */
+export function drawIdenticon(canvas, input, size, opts) {
+  const kind = (opts && opts.kind) || 'user';
+  const { rand, pal, bg } = setup(input);
+  const styleIdx = pickStyle(normalizeKey(input));
+  const drawFn = STYLES[styleIdx];
+
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext('2d');
+  ctx.clearRect(0, 0, size, size);
+
+  drawFn(ctx, size, rand, pal, bg);
+  const fg = pickIconFg(pal, bg);
+  if (kind === 'group') drawGroupIcon(ctx, size, fg);
+  else drawUserIcon(ctx, size, fg);
+}
+
+/**
+ * Returns which style index (0..N-1) an input maps to.
+ * @param {string} input — hex pubkey or ping address
+ * @returns {number}
+ */
+export function getIdenticonStyle(input) {
+  return pickStyle(normalizeKey(input));
+}
+
+/** Total number of background styles available (currently 5). */
+export const IDENTICON_STYLE_COUNT = STYLES.length;
+
+/** Human-readable names for each style index, parallel to STYLES. */
+export const IDENTICON_STYLE_NAMES = STYLE_NAMES.slice();

package/src/index.js

@@ -0,0 +1,58 @@
+// Pure-JS SDK for Ping Directory v2.
+//
+// Primary entry: `PingDirectory` — construct one per app/connection.
+// Lower-level utilities (PDA finders, Borsh deserializers, ix builders,
+// constants) are also re-exported for advanced flows.
+
+export { PingDirectory } from './PingDirectory.js';
+export { walletSignAndSend } from './wallet.js';
+
+export {
+  PROGRAM_ID, ED25519_PROGRAM, SYSTEM_PROGRAM, SYSVAR_INSTRUCTIONS, COMPUTE_BUDGET_PROGRAM,
+  Cluster, ClusterWs, DEFAULT_CLUSTER, DEFAULT_RPC, DEFAULT_WS,
+  MessageTags, UsernameState, ListingKind, GraceKind, PhotoMime, ItemKind,
+  AccountType, UserIndexStatus, Seeds,
+  MAX_USERNAME_LEN, MAX_INVENTORY, MAX_PHOTO_BYTES, MAX_PHOTO_DIM,
+  BPS_DENOMINATOR, REFERRAL_BPS,
+} from './constants.js';
+
+// Explicit named re-exports (NOT `export *`): TypeScript doesn't surface
+// `export *` from a types-less JS package to consumers, so the names must be
+// listed — same as every other re-export in this file.
+export {
+  findPDA, findConfigPDA, findUsernamePDA, findEd25519AccountPDA, findNoncePDA,
+  findGracePeriodPDA, findSaleListingPDA, findReferralBalancePDA, findUserIndexPDA,
+  findUidMapPDA, findAdminPDA, findTreasuryWalletPDA, findBlocklistPDA,
+  findModerationPDA, findShopItemPDA, findInventoryPDA, findProfilePhotoPDA,
+} from './pda.js';
+export {
+  deserializeConfig, deserializeUsernameAccount, isPro, deserializeEd25519Account,
+  deserializeSaleListing, deserializeGracePeriod, deserializeReferralBalance,
+  deserializeProfilePhoto, PROFILE_PHOTO_META_LEN, deserializeProfilePhotoMeta,
+  deserializeInventory, deserializeShopItem, deserializeAdmin, deserializeTreasuryWallet,
+  deserializeBlocklist, deserializeModeration, deserializeNonce, deserializeUserIndex,
+  deserializeUsernameUserIdMap,
+} from './deserialize.js';
+export * as ix from './ix/index.js';
+export {
+  u8, u16LE, u32LE, u64LE, i64LE,
+  borshString, borshOptionPubkey, borshBytes,
+  randomBytes, randomNonce,
+  buildEd25519Ix, signedMsg, concat, pkBytes,
+} from './encoding.js';
+
+export {
+  bytesToHex, hexToBytes,
+  b58encode,
+  pubkeyBytesToPingAddress,
+} from './format.js';
+
+export {
+  lamportsToSol, solToLamports,
+  rentExempt, feeForLength, txFee, txFees,
+} from './fees.js';
+
+export {
+  drawIdenticon, getIdenticonStyle,
+  IDENTICON_STYLE_COUNT, IDENTICON_STYLE_NAMES,
+} from './identicon.js';