@microslop/ping-directory-sdk 0.1.5

package/src/ix/photo.js

@@ -0,0 +1,173 @@
+// Profile photo: init / write_chunk / finalize / clear.
+//
+// ProfilePhoto is keyed by username (`[b"profile_photo", username]`).
+// All four handlers operate on this same PDA. The first three thread
+// the bound key's Ed25519Account for the on-chain auto-freeze check;
+// `clear_profile_photo` intentionally does NOT — the user must always
+// be able to clear their photo (required to satisfy the
+// "photo cleared first" preconditions on transfer / sale / unregister).
+
+import { TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import {
+  borshString, borshBytes, u8, u16LE, u32LE, randomNonce,
+  buildEd25519Ix, signedMsg, concat,
+} from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findUsernamePDA, findProfilePhotoPDA, findNoncePDA, findSaleListingPDA,
+  findEd25519AccountPDA, findConfigPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+export function initProfilePhoto({
+  username, totalSize, mime, width, height, ed25519Keypair, payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.INIT_PROFILE_PHOTO,
+    payer.publicKey.toBytes(),
+    u32LE(totalSize),
+    u8(mime),
+    u16LE(width),
+    u16LE(height),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('init_profile_photo'),
+    borshString(username),
+    u32LE(totalSize),
+    u8(mime),
+    u16LE(width),
+    u16LE(height),
+    nonce,
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [photoPda]    = findProfilePhotoPDA(username);
+  const [noncePda]    = findNoncePDA(nonce);
+  const [salePda]     = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      // `config` is mut: per-MIME fee is transferred from `payer` into the
+      // Config PDA's lamports (sweepable later via `withdraw_treasury`).
+      k(configPda,   false, true),
+      k(usernamePda, false, false),
+      k(edPda,       false, false),
+      k(photoPda,    false, true),
+      k(noncePda,    false, true),
+      k(salePda,     false, false),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// write_photo_chunk: wallet-auth (`payer == profile_photo.init_payer`).
+// Caller must supply `boundEd25519Pubkey` (read from UsernameAccount)
+// so we can include the bound key's Ed25519Account for the freeze check.
+export function writePhotoChunk({ username, offset, chunk, payer, boundEd25519Pubkey }) {
+  if (boundEd25519Pubkey == null) {
+    throw new Error('writePhotoChunk: boundEd25519Pubkey required');
+  }
+  const data = concat(
+    ixDisc('write_photo_chunk'),
+    borshString(username),
+    u32LE(offset),
+    borshBytes(chunk),
+  );
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(boundEd25519Pubkey);
+  const [photoPda]    = findProfilePhotoPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, false),
+      k(edPda,       false, false),
+      k(photoPda,    false, true),
+      k(payer.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [payer] };
+}
+
+export function finalizeProfilePhoto({
+  username, imageHash, mime, width, height, ed25519Keypair, payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.FINALIZE_PROFILE_PHOTO,
+    imageHash,
+    u8(mime),
+    u16LE(width),
+    u16LE(height),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('finalize_profile_photo'),
+    borshString(username),
+    imageHash,
+    nonce,
+  );
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [photoPda]    = findProfilePhotoPDA(username);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, false),
+      k(edPda,       false, false),
+      k(photoPda,    false, true),
+      k(noncePda,    false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// clear_profile_photo is now freeze-gated (MEDIUM-6, 2026-05): the
+// handler reads `ed25519_account` to check `compromised_at`. SDK must
+// thread the Ed25519Account PDA in the same slot order as the on-chain
+// `ClearProfilePhoto` struct.
+export function clearProfilePhoto({
+  username, ed25519Keypair, initPayer, payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(MessageTags.CLEAR_PROFILE_PHOTO, nonce, new TextEncoder().encode(username));
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('clear_profile_photo'), borshString(username), nonce);
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [photoPda]    = findProfilePhotoPDA(username);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, false),
+      k(edPda,       false, false),
+      k(photoPda,    false, true),
+      k(initPayer,   false, true),
+      k(noncePda,    false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}

package/src/ix/pro.js

@@ -0,0 +1,91 @@
+// Premium: subscribe_pro (open-payer), set_pro (admin/owner toggle).
+
+import { TransactionInstruction, SystemProgram, PublicKey } from '@solana/web3.js';
+import { PROGRAM_ID } from '../constants.js';
+import { borshString, u8, concat } from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findUsernamePDA, findReferralBalancePDA, findAdminPDA,
+  findEd25519AccountPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// subscribe_pro: writes pro_until / pro_lifetime onto
+// UsernameAccount. The username's stored referrer (also on UsernameAccount)
+// gets credited 10%.
+//
+// Caller must supply:
+//   - `boundEd25519Pubkey`: the username's bound ed25519 key (read from
+//     `UsernameAccount.ed25519Pubkey`). Required for the on-chain
+//     auto-freeze gate.
+//   - `referrerForUsername`: the referrer recorded on UsernameAccount.referrer
+//     (Pubkey | null). Used to derive the referral PDA.
+export function subscribePro({
+  username, months, payer, boundEd25519Pubkey, referrerForUsername = null,
+}) {
+  if (boundEd25519Pubkey == null) {
+    throw new Error('subscribePro: boundEd25519Pubkey required');
+  }
+  const data = concat(ixDisc('subscribe_pro'), borshString(username), u8(months));
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(boundEd25519Pubkey);
+  const refKey = referrerForUsername ?? PublicKey.default;
+  const [referralPda] = findReferralBalancePDA(refKey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, true),
+      k(edPda,        false, false),
+      k(referralPda,  false, true),
+      k(payer.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [payer] };
+}
+
+// set_pro: forever=true → owner-only; forever=false → owner OR admin.
+// Caller passes admin Pubkey (or null) — required field but only consulted
+// if signer != owner. Writes the lifetime flag onto UsernameAccount.
+//
+// On-chain handler does NOT include ed25519_account (no auto-freeze gate
+// for owner/admin admin-paths).
+export function setPro({ username, forever, signer, admin = null }) {
+  const data = concat(ixDisc('set_pro'), borshString(username), u8(forever ? 1 : 0));
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, true),
+      k(signer.publicKey, true, false),
+      // Anchor's `Option<Account>` accepts the program id when None.
+      k(adminPda ?? PROGRAM_ID, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+export function withdrawReferral({ recipient }) {
+  const data = ixDisc('withdraw_referral');
+  const [configPda]   = findConfigPDA();
+  const [referralPda] = findReferralBalancePDA(recipient.publicKey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(referralPda,  false, true),
+      k(recipient.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [recipient] };
+}

package/src/ix/revoke.js

@@ -0,0 +1,41 @@
+// Key revocation: mark_compromised.
+
+import { TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import { randomNonce, buildEd25519Ix, signedMsg, concat } from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import { findEd25519AccountPDA, findNoncePDA } from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// Signed message body (after 2026-05 update — LOW-15):
+//   TAG_MARK_COMPROMISED(1) || pubkey(32) || payer(32) || nonce(16)
+// Binding `payer` is consistency with other economic-side-effect ixes
+// (not exploitable today — outcome is identical regardless of payer).
+export function markCompromised({ ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(
+    MessageTags.MARK_COMPROMISED,
+    ed25519Keypair.publicKey,
+    payer.publicKey.toBytes(),
+    nonce,
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('mark_compromised'), ed25519Keypair.publicKey, nonce);
+
+  const [edPda]    = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda] = findNoncePDA(nonce);
+
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(edPda,           false, true),
+      k(noncePda,        false, true),
+      k(payer.publicKey, true,  true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}

package/src/ix/shop.js

@@ -0,0 +1,322 @@
+// Shop / cosmetics: shop_add_item, shop_update_item, purchase_item,
+// equip_item, unequip_slot, discard_item.
+//
+// Inventory PDA is keyed by username (cosmetics travel with the name).
+// Equipped slots live on UsernameAccount. The bound key's Ed25519Account
+// is threaded for the on-chain auto-freeze check.
+
+import { TransactionInstruction, SystemProgram, PublicKey } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import {
+  borshString, u8, u32LE, u64LE, randomNonce,
+  buildEd25519Ix, signedMsg, concat,
+} from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findUsernamePDA, findShopItemPDA, findInventoryPDA,
+  findReferralBalancePDA, findNoncePDA, findSaleListingPDA,
+  findEd25519AccountPDA, findAdminPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// ── shop_add_item (owner OR admin) ──────────────────────────────────
+export function shopAddItem({ id, kind, price, metadata, signer, admin = null }) {
+  const data = concat(
+    ixDisc('shop_add_item'),
+    u32LE(id),
+    u8(kind),
+    u64LE(price),
+    borshString(metadata),
+  );
+  const [configPda]  = findConfigPDA();
+  const [shopPda]    = findShopItemPDA(id);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(shopPda,   false, true),
+      k(signer.publicKey, true, true),                 // signer (init payer)
+      k(adminPda ?? PROGRAM_ID, false, false),         // admin Option (seed-bound to signer)
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+// ── shop_update_item (owner OR admin; metadata immutable post-add) ──
+export function shopUpdateItem({ id, price, active, signer, admin = null }) {
+  const data = concat(ixDisc('shop_update_item'), u32LE(id), u64LE(price), u8(active ? 1 : 0));
+  const [configPda] = findConfigPDA();
+  const [shopPda]   = findShopItemPDA(id);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(shopPda,   false, true),
+      k(signer.publicKey, true, false),
+      k(adminPda ?? PROGRAM_ID, false, false),         // admin Option (seed-bound to signer)
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+// ── shop_set_pro_only (owner-only) ──────────────────────────────────
+//
+// Toggles the Pro-purchase gate on an existing item. Additive to
+// `shopAddItem` (its arg list is unchanged); call this afterwards to
+// mark an item Pro-only. Owners only — same auth shape as shopUpdateItem.
+export function shopSetProOnly({ id, proOnly, signer, admin = null }) {
+  const data = concat(ixDisc('shop_set_pro_only'), u32LE(id), u8(proOnly ? 1 : 0));
+  const [configPda] = findConfigPDA();
+  const [shopPda]   = findShopItemPDA(id);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(shopPda,   false, true),
+      k(signer.publicKey, true, false),
+      k(adminPda ?? PROGRAM_ID, false, false),         // admin Option (seed-bound to signer)
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+// ── shop_set_active (owner-only) ────────────────────────────────────
+//
+// Delist (active=false) / relist (active=true) without touching price.
+// The ShopItem account stays on chain when delisted, so the catalog
+// remembers it was once listed (client renders a "Retired" state).
+export function shopSetActive({ id, active, signer, admin = null }) {
+  const data = concat(ixDisc('shop_set_active'), u32LE(id), u8(active ? 1 : 0));
+  const [configPda] = findConfigPDA();
+  const [shopPda]   = findShopItemPDA(id);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(shopPda,   false, true),
+      k(signer.publicKey, true, false),
+      k(adminPda ?? PROGRAM_ID, false, false),         // admin Option (seed-bound to signer)
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+// ── purchase_item (open-payer; auto-freeze gated) ───────────────────
+//
+// Caller must supply:
+//   - `boundEd25519Pubkey`: bound key from UsernameAccount.ed25519Pubkey
+//   - `referrerForUsername`: UsernameAccount.referrer (Pubkey | null) —
+//     used to derive the referral PDA seed.
+export function purchaseItem({
+  username, itemId, expectedPrice, payer, boundEd25519Pubkey, referrerForUsername = null,
+}) {
+  if (boundEd25519Pubkey == null) {
+    throw new Error('purchaseItem: boundEd25519Pubkey required');
+  }
+  const data = concat(
+    ixDisc('purchase_item'),
+    borshString(username),
+    u32LE(itemId),
+    u64LE(expectedPrice),
+  );
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [edPda]        = findEd25519AccountPDA(boundEd25519Pubkey);
+  const [shopPda]      = findShopItemPDA(itemId);
+  const [inventoryPda] = findInventoryPDA(username);
+  const refKey = referrerForUsername ?? PublicKey.default;
+  const [referralPda]  = findReferralBalancePDA(refKey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, false),
+      k(edPda,        false, false),
+      k(shopPda,      false, false),
+      k(inventoryPda, false, true),
+      k(referralPda,  false, true),
+      k(payer.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [payer] };
+}
+
+// ── gift_item (owner OR admin; drops an item into a username's inventory) ──
+//
+// Two signers: `signer` is the owner/admin authority; `payer` funds the
+// inventory rent (defaults to `signer`). admin Option is seed-bound to
+// signer.key() and sits BETWEEN signer and payer (position 6).
+export function giftItem({ username, itemId, boundEd25519Pubkey, signer, payer = signer, admin = null }) {
+  if (boundEd25519Pubkey == null) {
+    throw new Error('giftItem: boundEd25519Pubkey required');
+  }
+  const data = concat(ixDisc('gift_item'), borshString(username), u32LE(itemId));
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [edPda]        = findEd25519AccountPDA(boundEd25519Pubkey);
+  const [shopPda]      = findShopItemPDA(itemId);
+  const [inventoryPda] = findInventoryPDA(username);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, false),               // 0 config
+      k(usernamePda,  false, false),               // 1 username_account
+      k(edPda,        false, false),               // 2 ed25519_account
+      k(shopPda,      false, false),               // 3 shop_item
+      k(inventoryPda, false, true),                // 4 inventory (init_if_needed, payer=payer)
+      k(signer.publicKey, true, false),            // 5 signer (authority, NOT mut)
+      k(adminPda ?? PROGRAM_ID, false, false),     // 6 admin Option (seed-bound to signer)
+      k(payer.publicKey, true, true),              // 7 payer (mut, rent funder)
+      k(SystemProgram.programId, false, false),    // 8 system_program
+    ],
+    data,
+  });
+  const signers = signer.publicKey.equals(payer.publicKey) ? [signer] : [signer, payer];
+  return { instructions: [ix], signers };
+}
+
+// ── equip_item (ed25519; auto-freeze gated) ─────────────────────────
+//
+// Equipped slots live on UsernameAccount. Inventory PDA is keyed by
+// username.
+export function equipItem({ username, itemId, kind, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(
+    MessageTags.EQUIP_ITEM,
+    u32LE(itemId),
+    u8(kind),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('equip_item'), borshString(username), u32LE(itemId), nonce);
+  const [usernamePda]  = findUsernamePDA(username);
+  const [edPda]        = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [shopPda]      = findShopItemPDA(itemId);
+  const [inventoryPda] = findInventoryPDA(username);
+  const [noncePda]     = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda,  false, true),
+      k(edPda,        false, false),
+      k(shopPda,      false, false),
+      k(inventoryPda, false, false),
+      k(noncePda,     false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// ── unequip_slot (ed25519; auto-freeze gated) ───────────────────────
+//
+// Unequips a slot on UsernameAccount.
+export function unequipSlot({ username, kind, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(MessageTags.UNEQUIP_SLOT, u8(kind), nonce, new TextEncoder().encode(username));
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('unequip_slot'), borshString(username), u8(kind), nonce);
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, true),
+      k(edPda,       false, false),
+      k(noncePda,    false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// ── equip_pro_default (ed25519; premium-gated, auto-freeze gated)
+//
+// Sets `equipped_X = Some(0)` for the given kind — the per-kind
+// premium-default sentinel. No item_id arg (always 0), no inventory
+// check (ID 0 is never inventoried). On-chain handler reverts with
+// `RequiresPro` if the username isn't currently premium.
+//
+// `subscribe_pro` already auto-equips Some(0) into empty slots, so
+// the most common path to use this builder is "premium user with a
+// custom equip wants to switch back to the default chip" — typically
+// after an explicit unequip.
+export function equipProDefault({ username, kind, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(
+    MessageTags.EQUIP_PRO_DEFAULT,
+    u8(kind),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('equip_pro_default'), borshString(username), u8(kind), nonce);
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, true),
+      k(edPda,       false, false),
+      k(noncePda,    false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// ── discard_item (ed25519; auto-freeze gated; requires no listing) ──
+//
+// Removes an item from Inventory; auto-clears matching equipped slots
+// on UsernameAccount.
+export function discardItem({ username, itemId, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(MessageTags.DISCARD_ITEM, u32LE(itemId), nonce, new TextEncoder().encode(username));
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(ixDisc('discard_item'), borshString(username), u32LE(itemId), nonce);
+  const [usernamePda]  = findUsernamePDA(username);
+  const [edPda]        = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [inventoryPda] = findInventoryPDA(username);
+  const [salePda]      = findSaleListingPDA(username);
+  const [noncePda]     = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda,  false, true),
+      k(edPda,        false, false),
+      k(inventoryPda, false, true),
+      k(salePda,      false, false),
+      k(noncePda,     false, true),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}