@microslop/ping-directory-sdk 0.1.5

package/src/ix/identity.js

@@ -0,0 +1,418 @@
+// Identity instructions: reserve, register (atomic), attach_pubkey,
+// transfer_reserved, unregister_reserved, update_pubkey, transfer_username,
+// unregister_active, set_account_type.
+
+import { TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import {
+  borshString, borshOptionPubkey, u8, u64LE, randomNonce,
+  buildEd25519Ix, signedMsg, pkBytes, concat,
+} from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findUsernamePDA, findEd25519AccountPDA, findNoncePDA,
+  findGracePeriodPDA, findReferralBalancePDA, findUserIndexPDA, findUidMapPDA,
+  findBlocklistPDA, findSaleListingPDA, findProfilePhotoPDA, findAdminPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// ── reserve_username ─────────────────────────────────────────────────
+export function reserveUsername({ username, accountType = 0, referrer = null, expectedUserId, payer }) {
+  const data = concat(
+    ixDisc('reserve_username'),
+    borshString(username),
+    u8(accountType),
+    borshOptionPubkey(referrer),
+    u64LE(expectedUserId),
+  );
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [userIdxPda]   = findUserIndexPDA(expectedUserId);
+  const [uidMapPda]    = findUidMapPDA(username);
+  const [referralPda]  = findReferralBalancePDA(referrer);
+  const [blocklistPda] = findBlocklistPDA(username);
+  const [graceCheck]   = findGracePeriodPDA(username);
+
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, true),
+      k(userIdxPda,   false, true),
+      k(uidMapPda,    false, true),
+      k(referralPda,  false, true),
+      k(blocklistPda, false, false),
+      k(graceCheck,   false, true),
+      k(payer.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [payer] };
+}
+
+// ── register (atomic reserve+attach) ─────────────────────────────────
+//
+// Signed message body (after 2026-05 update — MEDIUM-10):
+//   TAG_REGISTER(1) || pubkey(32) || nonce(16) || username
+//     || referrer_present(1) || referrer_bytes(32) || account_type(1)
+//
+// The 1-byte presence prefix disambiguates `None` (0x00 || zeros) from
+// `Some(Pubkey::default())` (0x01 || zeros) on the wire. The on-chain
+// handler also rejects `Some(Pubkey::default())` explicitly.
+export function register({
+  username, ed25519Keypair, accountType = 0, referrer = null,
+  expectedUserId, payer, nonce = randomNonce(), admin = null,
+}) {
+  const referrerPresent = referrer ? 1 : 0;
+  const refBytes = referrer ? pkBytes(referrer) : new Uint8Array(32);
+  const msg = signedMsg(
+    MessageTags.REGISTER,
+    ed25519Keypair.publicKey,
+    nonce,
+    new TextEncoder().encode(username),
+    u8(referrerPresent),
+    refBytes,
+    u8(accountType),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('register'),
+    borshString(username),
+    ed25519Keypair.publicKey,
+    nonce,
+    borshOptionPubkey(referrer),
+    u8(accountType),
+    u64LE(expectedUserId),
+  );
+
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [ed25519Pda]   = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]     = findNoncePDA(nonce);
+  const [referralPda]  = findReferralBalancePDA(referrer);
+  const [userIdxPda]   = findUserIndexPDA(expectedUserId);
+  const [uidMapPda]    = findUidMapPDA(username);
+  const [blocklistPda] = findBlocklistPDA(username);
+  const [graceCheck]   = findGracePeriodPDA(username);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, true),
+      k(ed25519Pda,   false, true),
+      k(noncePda,     false, true),
+      k(referralPda,  false, true),
+      k(userIdxPda,   false, true),
+      k(uidMapPda,    false, true),
+      k(blocklistPda, false, false),
+      k(graceCheck,   false, true),
+      k(payer.publicKey, true, true),
+      k(adminPda ?? PROGRAM_ID, false, false),         // admin Option (seed-bound to payer)
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// ── attach_pubkey (Reserved → Active) ────────────────────────────────
+//
+// Reserved-side fields (referrer + account_type) were already persisted
+// on UsernameAccount at reserve time, so attach takes only the username
+// + new pubkey + nonce.
+//
+// Signed message body: TAG_ATTACH_PUBKEY(1) || pubkey(32) || nonce(16) || username
+export function attachPubkey({
+  username, ed25519Keypair, currentWallet, userId, nonce = randomNonce(),
+}) {
+  if (userId == null) throw new Error('attachPubkey: userId required');
+
+  const msg = signedMsg(
+    MessageTags.ATTACH_PUBKEY,
+    ed25519Keypair.publicKey,
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('attach_pubkey'),
+    borshString(username),
+    ed25519Keypair.publicKey,
+    nonce,
+  );
+
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [ed25519Pda]  = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]    = findNoncePDA(nonce);
+  const [salePda]     = findSaleListingPDA(username);
+  const [uidMapPda]   = findUidMapPDA(username);
+  const [userIdxPda]  = findUserIndexPDA(userId);
+
+  // `config` was added at the head of `AttachPubkey` so the handler
+  // can honor `registration_paused` (MEDIUM-9). Order must match the
+  // on-chain accounts struct exactly.
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, true),
+      k(ed25519Pda,  false, true),
+      k(salePda,     false, false),
+      k(userIdxPda,  false, true),
+      k(uidMapPda,   false, false),
+      k(noncePda,    false, true),
+      k(currentWallet.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [currentWallet] };
+}
+
+// ── transfer_reserved (no nonce) ─────────────────────────────────────
+export function transferReserved({ username, newWallet, currentWallet }) {
+  const data = concat(
+    ixDisc('transfer_reserved'),
+    borshString(username),
+    pkBytes(newWallet),
+  );
+  const [usernamePda] = findUsernamePDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda, false, true),
+      k(salePda,     false, false),
+      k(currentWallet.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [currentWallet] };
+}
+
+export function unregisterReserved({ username, currentWallet, userId }) {
+  if (userId == null) throw new Error('unregisterReserved: userId required');
+  const data = concat(ixDisc('unregister_reserved'), borshString(username));
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const [gracePda]    = findGracePeriodPDA(username);
+  const [uidMapPda]   = findUidMapPDA(username);
+  const [userIdxPda]  = findUserIndexPDA(userId);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, true),
+      k(usernamePda, false, true),
+      k(salePda,     false, false),
+      k(gracePda,    false, true),
+      k(uidMapPda,   false, true),
+      k(userIdxPda,  false, true),
+      k(currentWallet.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [currentWallet] };
+}
+
+// ── update_pubkey (key rotation; auto-freeze gated on old key) ───────
+//
+// Account list mirrors `programs/.../update_pubkey.rs`.
+// No Inventory or ProfilePhoto in the account list — those are seeded by
+// username, so they need no migration.
+export function updatePubkey({
+  username, currentEd25519Keypair, newEd25519Pubkey, currentEd25519Pubkey,
+  payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.UPDATE_PUBKEY,
+    pkBytes(newEd25519Pubkey),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(currentEd25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('update_pubkey'),
+    borshString(username),
+    pkBytes(newEd25519Pubkey),
+    nonce,
+  );
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [oldEdPda]     = findEd25519AccountPDA(pkBytes(currentEd25519Pubkey));
+  const [newEdPda]     = findEd25519AccountPDA(pkBytes(newEd25519Pubkey));
+  const [noncePda]     = findNoncePDA(nonce);
+  const [salePda]      = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, true),
+      k(oldEdPda,    false, true),
+      k(newEdPda,    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] };
+}
+
+// ── transfer_username (auto-freeze gated) ────────────────────────────
+//
+// Account list mirrors `programs/.../transfer_username.rs`. Includes
+// `profile_photo_check` (seeded by username) — must be empty.
+export function transferUsername({
+  username, currentEd25519Keypair, newEd25519Pubkey, currentEd25519Pubkey,
+  payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.TRANSFER_USERNAME,
+    pkBytes(newEd25519Pubkey),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(currentEd25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('transfer_username'),
+    borshString(username),
+    pkBytes(newEd25519Pubkey),
+    nonce,
+  );
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [oldEdPda]     = findEd25519AccountPDA(pkBytes(currentEd25519Pubkey));
+  const [newEdPda]     = findEd25519AccountPDA(pkBytes(newEd25519Pubkey));
+  const [noncePda]     = findNoncePDA(nonce);
+  const [salePda]      = findSaleListingPDA(username);
+  const [photoCheck]   = findProfilePhotoPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, true),
+      k(oldEdPda,    false, true),
+      k(newEdPda,    false, true),
+      k(noncePda,    false, true),
+      k(salePda,     false, false),
+      k(photoCheck,  false, false),
+      k(payer.publicKey, true, true),
+      k(SYSVAR_INSTRUCTIONS, false, false),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ed, ix], signers: [payer] };
+}
+
+// ── unregister_active (auto-freeze gated; UsernameAccount permanent) ──
+//
+// Note: the on-chain handler now flips UsernameAccount.state →
+// UNREGISTERED rather than closing it (the PDA stays open forever).
+// `username_user_id_map` is the only account that gets closed — its
+// rent goes to `refund_to`.
+export function unregisterActive({
+  username, currentEd25519Keypair, currentEd25519Pubkey,
+  refundTo, payer, userId, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.UNREGISTER,
+    pkBytes(currentEd25519Pubkey),
+    pkBytes(refundTo),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(currentEd25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('unregister_active'),
+    borshString(username),
+    pkBytes(refundTo),
+    nonce,
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(pkBytes(currentEd25519Pubkey));
+  const [gracePda]    = findGracePeriodPDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const [photoCheck]  = findProfilePhotoPDA(username);
+  const [uidMapPda]   = findUidMapPDA(username);
+  const [userIdxPda]  = findUserIndexPDA(userId);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(refundTo,     false, true),
+      k(usernamePda,  false, true),
+      k(edPda,        false, true),
+      k(gracePda,     false, true),
+      k(salePda,      false, false),
+      k(photoCheck,   false, false),
+      k(uidMapPda,    false, true),
+      k(userIdxPda,   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] };
+}
+
+// ── set_account_type (lock-gated; auto-freeze gated) ─────────────────
+//
+// account_type lives on UsernameAccount; the bound key's Ed25519Account
+// PDA is included for the on-chain auto-freeze check.
+export function setAccountType({
+  username, ed25519Keypair, accountType, payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.SET_ACCOUNT_TYPE,
+    u8(accountType),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('set_account_type'),
+    borshString(username),
+    u8(accountType),
+    nonce,
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      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] };
+}

package/src/ix/index.js

@@ -0,0 +1,10 @@
+// Aggregate re-export of every instruction builder.
+
+export * from './identity.js';
+export * from './marketplace.js';
+export * from './lock.js';
+export * from './photo.js';
+export * from './shop.js';
+export * from './pro.js';
+export * from './admin.js';
+export * from './revoke.js';

package/src/ix/lock.js

@@ -0,0 +1,63 @@
+// Lock / unlock: request_unlock + lock.
+
+import { TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import { borshString, randomNonce, buildEd25519Ix, signedMsg, concat } from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findUsernamePDA, findNoncePDA, findSaleListingPDA,
+  findEd25519AccountPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// request_unlock now also threads the bound key's Ed25519Account so the
+// program can run `require_not_frozen` on the auto-freeze gate.
+export function requestUnlock({ username, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(MessageTags.REQUEST_UNLOCK, nonce, new TextEncoder().encode(username));
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+  const data = concat(ixDisc('request_unlock'), borshString(username), nonce);
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [noncePda]    = findNoncePDA(nonce);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      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] };
+}
+
+// lock now also threads the bound key's Ed25519Account (auto-freeze gate).
+export function lock({ username, ed25519Keypair, payer, nonce = randomNonce() }) {
+  const msg = signedMsg(MessageTags.LOCK, nonce, new TextEncoder().encode(username));
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+  const data = concat(ixDisc('lock'), borshString(username), nonce);
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  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(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] };
+}

package/src/ix/marketplace.js

@@ -0,0 +1,198 @@
+// Marketplace: list_reserved, list_active, buy_reserved, cancel_sale.
+
+import { TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PROGRAM_ID, SYSVAR_INSTRUCTIONS, MessageTags } from '../constants.js';
+import {
+  borshString, u64LE, randomNonce,
+  buildEd25519Ix, signedMsg, pkBytes, concat,
+} from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findUsernamePDA, findSaleListingPDA,
+  findEd25519AccountPDA, findNoncePDA, findProfilePhotoPDA,
+  findReferralBalancePDA,
+} from '../pda.js';
+import { PublicKey } from '@solana/web3.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// ── list_reserved (wallet-auth, no nonce) ────────────────────────────
+//
+// On-chain `ListReserved` has 5 accounts: config, username_account,
+// sale_listing(init, payer=current_wallet), current_wallet(mut Signer),
+// system_program. The signer also funds rent — there's no separate
+// payer. The on-chain handler no longer threads a Nonce PDA: wallet-auth
+// has no signed-message body, so Solana's outer-tx-signature uniqueness
+// already prevents replay. `nonce` and `payer` args kept for API
+// back-compat (ignored — payer rejected if different from currentWallet).
+export function listReserved({ username, price, receiverWallet, currentWallet, payer, nonce: _nonce }) {
+  if (payer && payer !== currentWallet && payer.publicKey?.toBase58?.() !== currentWallet.publicKey.toBase58()) {
+    throw new Error('listReserved: `payer` must equal `currentWallet` (on-chain handler funds rent from the signing wallet)');
+  }
+  const data = concat(
+    ixDisc('list_reserved'),
+    borshString(username),
+    u64LE(price),
+    pkBytes(receiverWallet),
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, false),
+      k(salePda,     false, true),
+      k(currentWallet.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [currentWallet] };
+}
+
+// ── list_active (demote-and-list) ────────────────────────────────────
+//
+// Demotes the username from Active to Reserved as part of listing:
+//   - clears `bound_username` on Ed25519Account (PDA stays open so
+//     `compromised_at` / `pfp_banned_until` survive — closing here would
+//     let a banned key wipe its ban via re-register, MEDIUM-5)
+//   - closes ProfilePhoto PDA if one exists (rent → receiver_wallet)
+//   - mutates UsernameAccount: state=Reserved, wallet=receiver_wallet,
+//     ed25519_pubkey=zero, attached_at=0, unlock_requested_at=0,
+//     equipped_* = None. (premium / inventory / account_type / referrer
+//     stay — slot-bound.)
+//
+// Requires the seller's ed25519 sig (LIST_ACTIVE precompile message)
+// + the unlock window to be open (same gate as transfer/unregister).
+export function listActive({
+  username, price, receiverWallet, ed25519Keypair,
+  payer, nonce = randomNonce(),
+}) {
+  const msg = signedMsg(
+    MessageTags.LIST_ACTIVE,
+    u64LE(price),
+    pkBytes(receiverWallet),
+    nonce,
+    new TextEncoder().encode(username),
+  );
+  const ed = buildEd25519Ix(ed25519Keypair, msg);
+
+  const data = concat(
+    ixDisc('list_active'),
+    borshString(username),
+    u64LE(price),
+    pkBytes(receiverWallet),
+    nonce,
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [edPda]       = findEd25519AccountPDA(ed25519Keypair.publicKey);
+  const [photoPda]    = findProfilePhotoPDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const [noncePda]    = findNoncePDA(nonce);
+  // `receiver_wallet` appears twice: once as an instruction arg (above)
+  // and once as a mutable account for rent destination. Both share the
+  // same pubkey thanks to the program's `address = receiver_wallet`
+  // constraint.
+  const receiverPk = receiverWallet instanceof PublicKey
+    ? receiverWallet
+    : new PublicKey(pkBytes(receiverWallet));
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(usernamePda, false, true),
+      k(edPda,       false, true),
+      k(photoPda,    false, true),
+      k(receiverPk,  false, true),
+      k(salePda,     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] };
+}
+
+// ── buy_reserved (with expected_price + expected_receiver per #3) ────
+//
+// Pass `referrerForUsername` so the SDK can derive the `ReferralBalance`
+// PDA the program needs as an account (lazy-init, seeded by the
+// referrer pubkey or `Pubkey::default()` when no referrer is set). The
+// `PingDirectory.buy()` wrapper fetches this off the UsernameAccount;
+// raw callers must supply it (`null` when the slot has no referrer).
+export function buyReserved({
+  username, expectedPrice, expectedReceiver, receiverWallet, buyer,
+  referrerForUsername = null,
+  nonce: _nonce,
+}) {
+  // Nonce PDA removed (wallet-auth, no signed-message body to replay).
+  const data = concat(
+    ixDisc('buy_reserved'),
+    borshString(username),
+    u64LE(expectedPrice),
+    pkBytes(expectedReceiver),
+  );
+  const [configPda]   = findConfigPDA();
+  const [usernamePda] = findUsernamePDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  // ReferralBalance PDA seed: referrer pubkey, or `Pubkey::default()`
+  // (32 zero bytes) when the slot has no referrer.
+  const referrerKey = referrerForUsername
+    ? (referrerForUsername instanceof PublicKey
+        ? referrerForUsername
+        : new PublicKey(pkBytes(referrerForUsername)))
+    : PublicKey.default;
+  const [referralPda] = findReferralBalancePDA(referrerKey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, true),
+      k(salePda,      false, true),
+      k(receiverWallet, false, true),
+      k(referralPda,  false, true),
+      k(buyer.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [buyer] };
+}
+
+// buy_active was removed in the demote-on-list rewrite. After
+// `list_active` demotes the username to Reserved, every listing buys
+// through the wallet-auth `buyReserved` path below. Re-exported as
+// `buy` (alias) for clarity at callsites that don't care about
+// Reserved-vs-Active provenance.
+
+// ── cancel_sale (wallet-auth, no nonce) ──────────────────────────────
+// Single cancel path after the demote-on-list rewrite. The `_reserved`
+// suffix was retired in 2026-05 (LOW-25) — every listing settles via
+// the wallet-auth path because `list_active` demotes the username.
+export function cancelSale({ username, receiverWallet, currentWallet }) {
+  const data = concat(ixDisc('cancel_sale'), borshString(username));
+  const [usernamePda] = findUsernamePDA(username);
+  const [salePda]     = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(usernamePda,    false, false),
+      k(salePda,        false, true),
+      k(receiverWallet, false, true),
+      k(currentWallet.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [currentWallet] };
+}
+
+// Buy alias for state-agnostic call sites. Program has only `buy_reserved`
+// + `cancel_sale` after the demote-on-list rewrite.
+export const buy = buyReserved;
+// Back-compat alias for SDK callers still importing the old name.
+export const cancelSaleReserved = cancelSale;