@microslop/ping-directory-sdk 0.1.5

package/src/ix/admin.js

@@ -0,0 +1,351 @@
+// Admin / config / owner / blocklist / pause / treasury.
+
+import { TransactionInstruction, SystemProgram, PublicKey } from '@solana/web3.js';
+import { PROGRAM_ID } from '../constants.js';
+import { borshString, u8, u16LE, u64LE, i64LE, concat, pkBytes } from '../encoding.js';
+import { ixDisc } from '../disc.js';
+import {
+  findConfigPDA, findAdminPDA, findBlocklistPDA, findGracePeriodPDA, findUsernamePDA,
+  findEd25519AccountPDA, findUidMapPDA, findUserIndexPDA, findSaleListingPDA,
+  findInventoryPDA, findProfilePhotoPDA, findReferralBalancePDA,
+  findTreasuryWalletPDA,
+} from '../pda.js';
+
+const k = (pubkey, isSigner, isWritable) => ({ pubkey, isSigner, isWritable });
+
+// ── initialize ──────────────────────────────────────────────────────
+export function initialize({ payer }) {
+  const data = ixDisc('initialize');
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(payer.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [payer] };
+}
+
+// ── add_admin (owner-only) ──────────────────────────────────────────
+export function addAdmin({ adminPubkey, owner }) {
+  const data = concat(ixDisc('add_admin'), pkBytes(adminPubkey));
+  const [configPda] = findConfigPDA();
+  const [adminPda]  = findAdminPDA(adminPubkey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(adminPda,  false, true),
+      k(owner.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+export function removeAdmin({ adminPubkey, owner }) {
+  const data = concat(ixDisc('remove_admin'), pkBytes(adminPubkey));
+  const [configPda] = findConfigPDA();
+  const [adminPda]  = findAdminPDA(adminPubkey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(adminPda,  false, true),
+      k(owner.publicKey, true, true),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+// ── two-step ownership ──────────────────────────────────────────────
+export function proposeOwner({ newOwner, owner }) {
+  const data = concat(ixDisc('propose_owner'), pkBytes(newOwner));
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(owner.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+export function acceptOwner({ newOwner }) {
+  const data = ixDisc('accept_owner');
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(newOwner.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [newOwner] };
+}
+
+// `owner` is the on-chain field name. The constraint accepts EITHER
+// the current owner OR the pending owner (LOW-26): standard two-step
+// ownership pattern letting either side abort the proposal.
+export function cancelProposeOwner({ owner, signer }) {
+  const s = owner ?? signer;
+  const data = ixDisc('cancel_propose_owner');
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(s.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [s] };
+}
+
+// ── config setters (owner-only) ─────────────────────────────────────
+function configSetterIx(name, payload, owner) {
+  const data = concat(ixDisc(name), payload);
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(owner.publicKey, true, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+export const setRegistrationFee     = ({ tier, fee, owner })   => configSetterIx('set_registration_fee', concat(u8(tier), u64LE(fee)), owner);
+export const setProPriceMonthly = ({ price, owner })       => configSetterIx('set_pro_price_monthly', u64LE(price), owner);
+export const setProPriceLifetime= ({ price, owner })       => configSetterIx('set_pro_price_lifetime', u64LE(price), owner);
+export const setSaleFee             = ({ feeBps, owner })      => configSetterIx('set_sale_fee', u16LE(feeBps), owner);
+export const setMinSalePrice        = ({ price, owner })       => configSetterIx('set_min_sale_price', u64LE(price), owner);
+export const setGracePeriod         = ({ duration, owner })    => configSetterIx('set_grace_period', i64LE(duration), owner);
+export const setUnlockDelay         = ({ delay, owner })       => configSetterIx('set_unlock_delay', i64LE(delay), owner);
+export const setUnlockWindow        = ({ window, owner })      => configSetterIx('set_unlock_window', i64LE(window), owner);
+export const setAutoUnfreezeDelay   = ({ delay, owner })       => configSetterIx('set_auto_unfreeze_delay', i64LE(delay), owner);
+// Per-MIME profile-photo fee (lamports). `mime` ∈ {0=jpeg,1=png,2=webp,3=gif};
+// fee capped at Config::MAX_PHOTO_FEE (100 SOL). Charged at init_profile_photo;
+// non-refundable on clear. Lands in Config lamports — sweepable via withdraw_treasury.
+export const setProfilePhotoFee     = ({ mime, fee, owner })   => configSetterIx('set_profile_photo_fee', concat(u8(mime), u64LE(fee)), owner);
+
+// ── pause (owner OR admin) ──────────────────────────────────────────
+function pauseIx(name, paused, signer, admin) {
+  const data = concat(ixDisc(name), u8(paused ? 1 : 0));
+  const [configPda] = findConfigPDA();
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(signer.publicKey, true, false),
+      k(adminPda ?? PROGRAM_ID, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+export const pauseRegistration = ({ paused, signer, admin = null }) =>
+  pauseIx('pause_registration', paused, signer, admin);
+export const pausePro = ({ paused, signer, admin = null }) =>
+  pauseIx('pause_pro', paused, signer, admin);
+
+// ── blocklist (owner OR admin) ──────────────────────────────────────
+export function blocklistAdd({ username, signer, admin = null, payer }) {
+  const p = payer ?? signer; // rent payer defaults to the signing owner/admin
+  const data = concat(ixDisc('blocklist_add'), borshString(username));
+  const [configPda]    = findConfigPDA();
+  const [blocklistPda] = findBlocklistPDA(username);
+  const [usernamePda]  = findUsernamePDA(username);
+  const [gracePda]     = findGracePeriodPDA(username);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, false),
+      k(blocklistPda, false, true),
+      k(usernamePda,  false, false),
+      k(gracePda,     false, false),
+      k(signer.publicKey, true, false),
+      k(adminPda ?? PROGRAM_ID, false, false),
+      k(p.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  // signer + payer may be the same wallet
+  const signers = signer.publicKey.equals(p.publicKey) ? [signer] : [signer, p];
+  return { instructions: [ix], signers };
+}
+
+export function blocklistRemove({ username, signer, admin = null }) {
+  const data = concat(ixDisc('blocklist_remove'), borshString(username));
+  const [configPda]    = findConfigPDA();
+  const [blocklistPda] = findBlocklistPDA(username);
+  const adminPda = admin ? findAdminPDA(admin)[0] : null;
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, false),
+      k(blocklistPda, false, true),
+      k(signer.publicKey, true, true),
+      k(adminPda ?? PROGRAM_ID, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [signer] };
+}
+
+// ── auto_unfreeze_username (permissionless time-gated unfreeze) ─────
+//
+// When an ed25519 key is `mark_compromised`'d, every ed25519-gated handler
+// on its bound username refuses to operate (auto-freeze). After
+// `Config.auto_unfreeze_delay` (default 1 year) elapses since the
+// `mark_compromised` call, anyone may call this handler — no owner gate,
+// no ed25519 sig — to flip the frozen username's UsernameAccount state
+// to UNREGISTERED in place (PDA preserved as a permanent slot) and reset
+// every personal field (premium, equipped cosmetics, account_type,
+// referrer) to a fresh-claim baseline. Side PDAs (Inventory, ProfilePhoto,
+// SaleListing) are closed in place if present; their rent goes to the
+// caller. UidMap is closed → caller. UserIndex is tombstoned. The
+// compromised key's `compromised_at` mark is preserved forever.
+//
+// Caller must supply:
+//   - `username`: the frozen username to release
+//   - `frozenEd25519Pubkey`: the bound (compromised) key — read from
+//     `UsernameAccount.ed25519Pubkey` before calling
+//   - `userId`: u64/BigInt — read from UidMap before calling
+//   - `caller`: signer paying tx + receiving every closed-PDA rent
+//
+// The high-level `PingDirectory.autoUnfreezeUsername` facade resolves
+// `frozenEd25519Pubkey` and `userId` from chain state automatically.
+export function autoUnfreezeUsername({
+  username, frozenEd25519Pubkey, userId, caller,
+}) {
+  if (frozenEd25519Pubkey == null) {
+    throw new Error('autoUnfreezeUsername: frozenEd25519Pubkey required');
+  }
+  if (userId == null) {
+    throw new Error('autoUnfreezeUsername: userId required');
+  }
+  if (caller == null) {
+    throw new Error('autoUnfreezeUsername: caller required');
+  }
+  const data = concat(ixDisc('auto_unfreeze_username'), borshString(username));
+  const [configPda]    = findConfigPDA();
+  const [usernamePda]  = findUsernamePDA(username);
+  const [edPda]        = findEd25519AccountPDA(frozenEd25519Pubkey);
+  const [uidMapPda]    = findUidMapPDA(username);
+  const [userIdxPda]   = findUserIndexPDA(userId);
+  const [inventoryPda] = findInventoryPDA(username);
+  const [photoPda]     = findProfilePhotoPDA(username);
+  const [salePda]      = findSaleListingPDA(username);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,    false, true),
+      k(usernamePda,  false, true),
+      k(edPda,        false, true),
+      k(uidMapPda,    false, true),
+      k(userIdxPda,   false, true),
+      k(inventoryPda, false, true),
+      k(photoPda,     false, true),
+      k(salePda,      false, true),
+      k(caller.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [caller] };
+}
+
+// ── withdraw_treasury (owner OR treasury wallet) ────────────────────
+// `signer` (alias `owner` for back-compat) sweeps the surplus to itself.
+// Pass `treasuryWalletPda` when the signer is a treasury wallet (Some);
+// omit it for the owner path (None ⇒ program id sentinel). The high-level
+// `PingDirectory.withdrawTreasury` resolves this from chain automatically.
+export function withdrawTreasury({ signer, owner, treasuryWalletPda = null }) {
+  const s = signer ?? owner;
+  const data = ixDisc('withdraw_treasury');
+  const [configPda] = findConfigPDA();
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, true),
+      k(s.publicKey, true, true),
+      k(treasuryWalletPda ?? PROGRAM_ID, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [s] };
+}
+
+// ── add_treasury_wallet / remove_treasury_wallet (owner-only) ───────
+// The owner designates / revokes addresses allowed to withdraw the
+// treasury. Mirrors add_admin / remove_admin.
+export function addTreasuryWallet({ walletPubkey, owner }) {
+  const data = concat(ixDisc('add_treasury_wallet'), pkBytes(walletPubkey));
+  const [configPda] = findConfigPDA();
+  const [twPda]     = findTreasuryWalletPDA(walletPubkey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(twPda,     false, true),
+      k(owner.publicKey, true, true),
+      k(SystemProgram.programId, false, false),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+export function removeTreasuryWallet({ walletPubkey, owner }) {
+  const data = concat(ixDisc('remove_treasury_wallet'), pkBytes(walletPubkey));
+  const [configPda] = findConfigPDA();
+  const [twPda]     = findTreasuryWalletPDA(walletPubkey);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda, false, false),
+      k(twPda,     false, true),
+      k(owner.publicKey, true, true),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}
+
+// ── admin_close_zero_referral (owner-only) ─────────────────────────
+// One-shot sweep of the dust ReferralBalance PDA at the zero-pubkey
+// seed. Holds ~0.001 SOL rent that no other handler can recover
+// (nobody can sign as `Pubkey::default()`). Reverts if balance != 0.
+// Will fail with `AccountNotInitialized` if the dust PDA was never
+// created (i.e. no no-referrer register / subscribe / shop call has
+// happened yet) — caller can interpret that as "nothing to sweep".
+export function adminCloseZeroReferral({ owner }) {
+  const data = ixDisc('admin_close_zero_referral');
+  const [configPda]   = findConfigPDA();
+  const [referralPda] = findReferralBalancePDA(PublicKey.default);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      k(configPda,   false, false),
+      k(referralPda, false, true),
+      k(owner.publicKey, true, true),
+    ],
+    data,
+  });
+  return { instructions: [ix], signers: [owner] };
+}