proof-of-take-sdk 3.1.2 → 4.0.0

package/dist/instructions/confirmedPostOnX.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.confirmedPostOnX = confirmedPostOnX;
 const pdaManager_1 = require("../utils/pdaManager");
 const programHelpers_1 = require("../utils/programHelpers");
+const constants_1 = require("../utils/constants");
 const signerHelpers_1 = require("../utils/signerHelpers");
 const conversions_1 = require("../utils/conversions");
 const tierPenalty_1 = require("../utils/tierPenalty");
@@ -20,6 +21,7 @@ const optimistic_1 = require("../optimistic");
 async function confirmedPostOnX(options) {
     // Guardrail: this program uses a 21-window schedule (0..20).
     const windowNumber = (0, conversions_1.toWindowNumberBn)(options.windowNumber);
+    const tokenMint = options.tokenMint ?? constants_1.MIZD_TOKEN_MINT;
     const program = (0, programHelpers_1.getProgram)(options.connection);
     const curr = options.currentAccounts || {};
     const pdas = pdaManager_1.PDAManager.deriveConfirmedPostPdas({
@@ -28,6 +30,7 @@ async function confirmedPostOnX(options) {
         windowNumber,
         tier: options.tier,
         miztakeShaHash: options.miztakeShaHash,
+        tokenMint,
     });
     const accounts = {
         seasonSettings: pdas.seasonSettings,
@@ -35,6 +38,7 @@ async function confirmedPostOnX(options) {
         season: pdas.season,
         rewardWindow: pdas.rewardWindow,
         userWindowParticipation: pdas.userWindowParticipation,
+        tokenMint,
         miztake: pdas.miztake,
         admin: options.adminKey,
     };
@@ -46,6 +50,12 @@ async function confirmedPostOnX(options) {
         feePayer: options.feePayer,
         admin: options.adminKey,
     });
+    // Safety: confirmations should always be paid by the admin wallet.
+    // If a caller accidentally sets the user as fee payer (common in bots),
+    // the tx will fail when users have 0 SOL.
+    if (!feePayer.equals(options.adminKey)) {
+        throw new Error("confirmedPostOnX: feePayer must be adminKey (admin pays tx fees for confirmations)");
+    }
     const signers = (0, signerHelpers_1.buildSigners)([(0, signerHelpers_1.asAdminSigner)(options.adminKey)], feePayer);
     // OPTIMISTIC UPDATES
     let updatedAccounts = undefined;

package/dist/instructions/createMiztake.d.ts

@@ -11,6 +11,8 @@ export interface CreateMiztakeOptions {
     user: PublicKey;
     admin: PublicKey;
     seasonNumber: BN;
+    /** Token mint this season is scoped to (used for PDA derivation). Defaults to MIZD_TOKEN_MINT. */
+    tokenMint?: PublicKey;
     windowNumber: WindowNumberLike;
     /** Tier number: 0=copper, 1=silver, 2=gold, 3=platinum, 4=mithril */
     tier: TierNumber;
@@ -55,8 +57,7 @@ export type CreateMiztakeResult = StandardInstructionResultWithPdasAndAccounts<C
  * Create a new miztake
  *
  * Requires dual signature: user + admin
- * User pays for miztake, user_stats, and user_window_participation accounts
- * Admin pays for reward_window account (if needed)
+ * Admin pays for all account creations (miztake, user_stats, user_window_participation, reward_window)
  *
  * @param options - Create miztake options
  * @returns Instructions, signers, PDAs, and optimistically updated accounts

package/dist/instructions/createMiztake.js

@@ -7,6 +7,7 @@ const web3_js_1 = require("@solana/web3.js");
 const types_1 = require("../types");
 const pdaManager_1 = require("../utils/pdaManager");
 const programHelpers_1 = require("../utils/programHelpers");
+const constants_1 = require("../utils/constants");
 const signerHelpers_1 = require("../utils/signerHelpers");
 const conversions_1 = require("../utils/conversions");
 const optimistic_1 = require("../optimistic");
@@ -15,8 +16,7 @@ const enumHelpers_1 = require("../utils/enumHelpers");
  * Create a new miztake
  *
  * Requires dual signature: user + admin
- * User pays for miztake, user_stats, and user_window_participation accounts
- * Admin pays for reward_window account (if needed)
+ * Admin pays for all account creations (miztake, user_stats, user_window_participation, reward_window)
  *
  * @param options - Create miztake options
  * @returns Instructions, signers, PDAs, and optimistically updated accounts
@@ -42,6 +42,7 @@ const enumHelpers_1 = require("../utils/enumHelpers");
  */
 async function createMiztake(options) {
     const program = (0, programHelpers_1.getProgram)(options.connection);
+    const tokenMint = options.tokenMint ?? constants_1.MIZD_TOKEN_MINT;
     // Guardrail: this program uses a 21-window schedule (0..20).
     const windowNumber = (0, conversions_1.toWindowNumberBn)(options.windowNumber);
     const shaHash = (0, conversions_1.toSha256HexString)(options.params.shaHash);
@@ -53,6 +54,7 @@ async function createMiztake(options) {
         windowNumber,
         user: options.user,
         tier: options.tier,
+        tokenMint,
     });
     // Build typed accounts object
     const accounts = {
@@ -64,6 +66,7 @@ async function createMiztake(options) {
         seasonMembership: pdas.seasonMembership,
         rewardWindow: pdas.rewardWindow,
         userWindowParticipation: pdas.userWindowParticipation,
+        tokenMint,
         user: options.user,
         admin: options.admin,
         systemProgram: web3_js_1.SystemProgram.programId,

package/dist/instructions/initializeBondingCurve.d.ts

@@ -0,0 +1,24 @@
+import { BN } from "@coral-xyz/anchor";
+import { Connection, PublicKey } from "@solana/web3.js";
+import { StandardInstructionResultWithPdas } from "../types/instructionResults";
+export interface InitializeBondingCurveOptions {
+    connection: Connection;
+    /** Must be the on-chain root admin (ADMIN_PUBLIC_KEY). */
+    admin?: PublicKey;
+    /** Initial MIZD inventory deposited into the vault (base units). */
+    initialMizdDepositUnits: BN;
+    /** Initial SOL reserve deposited into the curve PDA (lamports). */
+    initialSolDepositLamports: BN;
+    /** Virtual SOL reserve (lamports). */
+    virtualSolReserveLamports?: BN;
+    /** Virtual MIZD reserve (base units). */
+    virtualMizdReserveUnits?: BN;
+    /** Fee in bps (0..=10000). Default 0. */
+    feeBps?: number;
+    feePayer?: PublicKey;
+}
+export declare function initializeBondingCurve(opts: InitializeBondingCurveOptions): Promise<StandardInstructionResultWithPdas<{
+    bondingCurve: PublicKey;
+    mizdVault: PublicKey;
+    adminMizdAta: PublicKey;
+}>>;

package/dist/instructions/initializeBondingCurve.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeBondingCurve = initializeBondingCurve;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const instructionResultHelpers_1 = require("../utils/instructionResultHelpers");
+const constants_1 = require("../utils/constants");
+const pdaManager_1 = require("../utils/pdaManager");
+const programHelpers_1 = require("../utils/programHelpers");
+const signerHelpers_1 = require("../utils/signerHelpers");
+async function initializeBondingCurve(opts) {
+    const program = (0, programHelpers_1.getProgram)(opts.connection);
+    const admin = opts.admin ?? constants_1.ADMIN_PUBLIC_KEY;
+    const pdas = pdaManager_1.PDAManager.deriveBondingCurvePdas();
+    const adminMizdAta = (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, admin);
+    const accounts = {
+        bondingCurve: pdas.bondingCurve,
+        mizdVault: pdas.mizdVault,
+        mizdMint: constants_1.MIZD_TOKEN_MINT,
+        admin,
+        adminMizdAta,
+        associatedTokenProgram: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
+        tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    };
+    const instruction = await program.methods
+        .initializeBondingCurve(opts.initialMizdDepositUnits, opts.initialSolDepositLamports, opts.virtualSolReserveLamports ?? new anchor_1.BN(0), opts.virtualMizdReserveUnits ?? new anchor_1.BN(0), opts.feeBps ?? 0)
+        .accounts(accounts)
+        .instruction();
+    const feePayer = (0, signerHelpers_1.resolveFeePayer)({ feePayer: opts.feePayer, admin });
+    const signers = (0, signerHelpers_1.buildSigners)([(0, signerHelpers_1.asAdminSigner)(admin)], feePayer);
+    return (0, instructionResultHelpers_1.singleInstruction)(instruction, {
+        signers,
+        pdas: { bondingCurve: pdas.bondingCurve, mizdVault: pdas.mizdVault, adminMizdAta },
+    });
+}

package/dist/instructions/initializeRewardWindow.d.ts

@@ -12,6 +12,8 @@ export interface InitializeRewardWindowOptions {
     admin: PublicKey;
     seasonNumber: SeasonNumberLike;
     windowNumber: WindowNumberLike;
+    /** Token mint this season is scoped to (used for PDA derivation). Defaults to MIZD_TOKEN_MINT. */
+    tokenMint?: PublicKey;
     feePayer?: PublicKey;
 }
 /**

package/dist/instructions/initializeRewardWindow.js

@@ -7,6 +7,7 @@ const programHelpers_1 = require("../utils/programHelpers");
 const signerHelpers_1 = require("../utils/signerHelpers");
 const instructionResultHelpers_1 = require("../utils/instructionResultHelpers");
 const conversions_1 = require("../utils/conversions");
+const constants_1 = require("../utils/constants");
 /**
  * Initialize (materialize) a missing RewardWindow PDA (root-admin only).
  *
@@ -17,13 +18,15 @@ async function initializeRewardWindow(options) {
     const program = (0, programHelpers_1.getProgram)(options.connection);
     const seasonNumberBn = (0, conversions_1.toSeasonNumberBn)(options.seasonNumber);
     const windowNumberBn = (0, conversions_1.toWindowNumberBn)(options.windowNumber);
+    const tokenMint = options.tokenMint ?? constants_1.MIZD_TOKEN_MINT;
     const [seasonSettings] = (0, pdas_1.getSeasonSettingsPda)();
-    const [season] = (0, pdas_1.getSeasonPda)(seasonNumberBn);
-    const [rewardWindow] = (0, pdas_1.getRewardWindowPda)(seasonNumberBn, windowNumberBn);
+    const [season] = (0, pdas_1.getSeasonPda)(seasonNumberBn, tokenMint);
+    const [rewardWindow] = (0, pdas_1.getRewardWindowPda)(seasonNumberBn, windowNumberBn, tokenMint);
     const accounts = {
         seasonSettings,
         season,
         rewardWindow,
+        tokenMint,
         admin: options.admin,
         systemProgram: web3_js_1.SystemProgram.programId,
     };

package/dist/instructions/initializeSeasonVault.d.ts

@@ -12,6 +12,6 @@ import { StandardInstructionResultWithPdas } from "../types/instructionResults";
  * @param feePayer - Optional separate fee payer for transaction fees
  * @returns Instructions, signers array, and vault PDA
  */
-export declare function initializeSeasonVault(connection: Connection, admin: PublicKey, seasonNumber: BN, feePayer?: PublicKey): Promise<StandardInstructionResultWithPdas<{
+export declare function initializeSeasonVault(connection: Connection, admin: PublicKey, seasonNumber: BN, tokenMint?: PublicKey, feePayer?: PublicKey): Promise<StandardInstructionResultWithPdas<{
     vault: PublicKey;
 }>>;

package/dist/instructions/initializeSeasonVault.js

@@ -19,12 +19,13 @@ const instructionResultHelpers_1 = require("../utils/instructionResultHelpers");
  * @param feePayer - Optional separate fee payer for transaction fees
  * @returns Instructions, signers array, and vault PDA
  */
-async function initializeSeasonVault(connection, admin, seasonNumber, feePayer) {
+async function initializeSeasonVault(connection, admin, seasonNumber, tokenMint = constants_1.MIZD_TOKEN_MINT, feePayer) {
     const program = (0, programHelpers_1.getProgram)(connection);
-    const [vaultPda] = (0, pdas_1.getSeasonDepositVaultPda)(seasonNumber);
+    const [vaultPda] = (0, pdas_1.getSeasonDepositVaultPda)(seasonNumber, tokenMint);
     const accounts = {
         seasonDepositVault: vaultPda,
         mizdMint: constants_1.MIZD_TOKEN_MINT,
+        tokenMint,
         admin: admin,
         tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
         systemProgram: web3_js_1.SystemProgram.programId,

package/dist/instructions/joinSeason.d.ts

@@ -3,12 +3,14 @@ import { Connection, PublicKey } from "@solana/web3.js";
 import { Season, SeasonMembership, SeasonSettings, TierNumber } from "../types";
 import { StandardInstructionResultWithPdas } from "../types/instructionResults";
 /**
- * Options for joinSeason instruction
+ * Options for joinSeason instruction (joining an existing season)
  */
 export interface JoinSeasonOptions {
     connection: Connection;
     user: PublicKey;
     seasonNumber: BN;
+    /** Token mint this season is scoped to (used for PDA derivation). Defaults to MIZD_TOKEN_MINT. */
+    tokenMint?: PublicKey;
     /** Tier number: 0=copper, 1=silver, 2=gold, 3=platinum, 4=mithril */
     tier: TierNumber;
     /** Optional referrer (PublicKey.default means no referrer) */
@@ -17,6 +19,24 @@ export interface JoinSeasonOptions {
     referrerTier?: TierNumber;
     /** If true, root admin funds join fee + deposit (currently only allowed for tier=0 on-chain). */
     star?: boolean;
+    /** If true, join uses launchpad mode (SOL in, virtual tokens escrowed; no SPL token accounts needed). */
+    launchpad?: boolean;
+    /** Launchpad slippage cap (lamports). Only used when launchpad=true. Defaults to u64::MAX. */
+    maxSolInLamports?: BN;
+    /**
+     * Launchpad slippage ergonomics:
+     * - Provide `expectedSolInLamports` (your quote) and `maxSlippageBps` and the program will enforce
+     *   `sol_required <= expected * (1 + bps/10_000)`.
+     * - If both this and `maxSolInLamports` are provided, the program uses the tighter cap.
+     */
+    expectedSolInLamports?: BN;
+    /** Max slippage in basis points (0..=10_000). Used only when expectedSolInLamports > 0. */
+    maxSlippageBps?: number;
+    /**
+     * Star flag prompt: a short message (max 33 chars) displayed when users raise their flag.
+     * Only used when initializing a new season (first join). Ignored when joining existing season.
+     */
+    starFlagPrompt?: string;
     /** Optional injected timestamp (seconds) for optimistic state calculation */
     now?: BN;
     feePayer?: PublicKey;
@@ -25,12 +45,51 @@ export interface JoinSeasonOptions {
         season?: Season;
     };
 }
+/**
+ * Options for initializing a new season (first joiner).
+ * Requires starFlagPrompt since it will be stored in the Season account.
+ */
+export type JoinSeasonAndInitializeOptions = Omit<JoinSeasonOptions, "starFlagPrompt"> & {
+    /**
+     * Star flag prompt: a short message (max 33 chars) displayed when users raise their flag.
+     * REQUIRED when initializing a new season.
+     */
+    starFlagPrompt: string;
+};
+/**
+ * Options for the classic (non-launchpad) joinSeason wrapper.
+ * This avoids exposing nullable optional accounts to app code.
+ */
+export type JoinSeasonClassicOptions = Omit<JoinSeasonOptions, "launchpad" | "maxSolInLamports" | "expectedSolInLamports" | "maxSlippageBps"> & {
+    launchpad?: never;
+    maxSolInLamports?: never;
+    expectedSolInLamports?: never;
+    maxSlippageBps?: never;
+};
+/**
+ * Options for the launchpad joinSeason wrapper.
+ * (No SPL token accounts needed; user pays SOL to the pool PDA.)
+ */
+export type JoinSeasonLaunchpadOptions = Omit<JoinSeasonOptions, "launchpad" | "maxSolInLamports" | "expectedSolInLamports" | "maxSlippageBps"> & {
+    launchpad?: never;
+    /** Optional hard cap in lamports (0 disables this cap on-chain). */
+    maxSolInLamports?: BN;
+    /** Optional expected SOL in lamports for bps slippage protection (0 disables on-chain). */
+    expectedSolInLamports?: BN;
+    /** Optional max slippage bps (0 disables on-chain). */
+    maxSlippageBps?: number;
+};
 type JoinSeasonPdas = {
     seasonSettings: PublicKey;
     season: PublicKey;
     seasonMembership: PublicKey;
+    moonpool: PublicKey;
+    moonpoolTreasury: PublicKey;
+    launchpadTokenMint: PublicKey;
+    sunpool: PublicKey;
     seasonDepositVault: PublicKey;
-    seasonEscrowVault: PublicKey;
+    userJoinCredit: PublicKey;
+    userJoinCreditVault: PublicKey;
 };
 type JoinSeasonUpdatedAccounts = {
     seasonSettings?: SeasonSettings;
@@ -42,7 +101,7 @@ type JoinSeasonUpdatedAccounts = {
  *
  * Signers: user + root admin (root admin pays for signup-rewards vault ATA creation when a referrer is present)
  * User pays for season (if needed) and membership accounts
- * Transfers full tier deposit from user to vault, then escrows the pre-join portion
+ * Transfers active deposit into the season vault; the late-join escrow portion is converted into non-withdrawable join credit
  *
  * IMPORTANT: If providing a referrer, you MUST also provide referrerTier.
  * The referrerTier must match the tier the referrer actually joined the season with.
@@ -52,4 +111,34 @@ type JoinSeasonUpdatedAccounts = {
  * @returns Instructions, signers, PDAs, and optimistically created/updated accounts
  */
 export declare function joinSeason(options: JoinSeasonOptions): Promise<StandardInstructionResultWithPdas<JoinSeasonPdas, JoinSeasonUpdatedAccounts>>;
+/**
+ * Convenience wrapper: classic (non-launchpad) joinSeason.
+ * - Keeps the existing MIZD-based join behavior.
+ * - App code never passes nullable optional accounts.
+ */
+export declare function joinSeasonClassic(options: JoinSeasonClassicOptions): Promise<StandardInstructionResultWithPdas<JoinSeasonPdas, JoinSeasonUpdatedAccounts>>;
+/**
+ * Convenience wrapper: launchpad joinSeason.
+ * - Uses SOL in + virtual token escrow.
+ * - App code never passes nullable optional accounts.
+ */
+export declare function joinSeasonLaunchpad(options: JoinSeasonLaunchpadOptions): Promise<StandardInstructionResultWithPdas<JoinSeasonPdas, JoinSeasonUpdatedAccounts>>;
+/**
+ * Join season AND initialize it (first joiner).
+ * Use this when you know the season doesn't exist yet.
+ *
+ * @param options - Options with REQUIRED starFlagPrompt
+ * @throws Error if starFlagPrompt is empty or exceeds 33 characters
+ */
+export declare function joinSeasonAndInitialize(options: JoinSeasonAndInitializeOptions): Promise<StandardInstructionResultWithPdas<JoinSeasonPdas, JoinSeasonUpdatedAccounts>>;
+/**
+ * Join season AND initialize it in launchpad mode (first joiner).
+ * Use this when you know the season doesn't exist yet and want launchpad mode.
+ *
+ * @param options - Options with REQUIRED starFlagPrompt
+ * @throws Error if starFlagPrompt is empty or exceeds 33 characters
+ */
+export declare function joinSeasonLaunchpadAndInitialize(options: Omit<JoinSeasonLaunchpadOptions, "starFlagPrompt"> & {
+    starFlagPrompt: string;
+}): Promise<StandardInstructionResultWithPdas<JoinSeasonPdas, JoinSeasonUpdatedAccounts>>;
 export {};

package/dist/instructions/joinSeason.js

@@ -1,25 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.joinSeason = joinSeason;
+exports.joinSeasonClassic = joinSeasonClassic;
+exports.joinSeasonLaunchpad = joinSeasonLaunchpad;
+exports.joinSeasonAndInitialize = joinSeasonAndInitialize;
+exports.joinSeasonLaunchpadAndInitialize = joinSeasonLaunchpadAndInitialize;
 const anchor_1 = require("@coral-xyz/anchor");
 const web3_js_1 = require("@solana/web3.js");
 const spl_token_1 = require("@solana/spl-token");
-const types_1 = require("../types");
 const pdaManager_1 = require("../utils/pdaManager");
 const constants_1 = require("../utils/constants");
 const programHelpers_1 = require("../utils/programHelpers");
 const signerHelpers_1 = require("../utils/signerHelpers");
 const optimistic_1 = require("../optimistic");
-const pdas_1 = require("../utils/pdas");
-const tierPenalty_1 = require("../utils/tierPenalty");
-const enumHelpers_1 = require("../utils/enumHelpers");
 const remainingAccounts_1 = require("../utils/remainingAccounts");
 /**
  * Join a season
  *
  * Signers: user + root admin (root admin pays for signup-rewards vault ATA creation when a referrer is present)
  * User pays for season (if needed) and membership accounts
- * Transfers full tier deposit from user to vault, then escrows the pre-join portion
+ * Transfers active deposit into the season vault; the late-join escrow portion is converted into non-withdrawable join credit
  *
  * IMPORTANT: If providing a referrer, you MUST also provide referrerTier.
  * The referrerTier must match the tier the referrer actually joined the season with.
@@ -30,20 +30,44 @@ const remainingAccounts_1 = require("../utils/remainingAccounts");
  */
 async function joinSeason(options) {
     const program = (0, programHelpers_1.getProgram)(options.connection);
-    const pdas = pdaManager_1.PDAManager.deriveJoinSeasonPdas({
+    const tokenMint = options.tokenMint ?? constants_1.MIZD_TOKEN_MINT;
+    const launchpad = options.launchpad ?? false;
+    const pdasBase = pdaManager_1.PDAManager.deriveJoinSeasonPdas({
         user: options.user,
         seasonNumber: options.seasonNumber,
         tier: options.tier,
+        tokenMint,
     });
-    const rootAdminTokenAccount = (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, constants_1.ADMIN_PUBLIC_KEY);
-    const userMizdAta = (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, options.user);
+    const rootAdminTokenAccount = launchpad
+        ? null
+        : (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, constants_1.ADMIN_PUBLIC_KEY);
+    const userMizdAta = launchpad
+        ? null
+        : (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, options.user);
+    // Join credit PDA + its vault ATA (owner is off-curve PDA, so allowOwnerOffCurve=true).
+    const userJoinCreditVault = launchpad
+        ? null
+        : (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, pdasBase.userJoinCredit, true);
+    const pdas = {
+        ...pdasBase,
+        userJoinCreditVault: userJoinCreditVault ?? web3_js_1.PublicKey.default,
+    };
     const accounts = {
         seasonSettings: pdas.seasonSettings,
         season: pdas.season,
         seasonMembership: pdas.seasonMembership,
-        seasonDepositVault: pdas.seasonDepositVault,
-        seasonEscrowVault: pdas.seasonEscrowVault,
+        // SECURITY: Pool accounts are now MANDATORY (non-optional) to prevent bypassing
+        // the mode check. The on-chain program validates pool state to ensure
+        // subsequent seasons use the same mode (launchpad/classic) as the first season.
+        moonpool: pdas.moonpool,
+        moonpoolTreasury: pdas.moonpoolTreasury,
+        launchpadTokenMint: pdas.launchpadTokenMint,
+        sunpool: pdas.sunpool,
+        seasonDepositVault: launchpad ? null : pdas.seasonDepositVault,
+        userJoinCredit: launchpad ? null : pdas.userJoinCredit,
+        userJoinCreditVault: launchpad ? null : userJoinCreditVault,
         mizdMint: constants_1.MIZD_TOKEN_MINT,
+        tokenMint,
         rootAdmin: constants_1.ADMIN_PUBLIC_KEY,
         rootAdminTokenAccount,
         // Always pass the canonical ATA; it may not exist yet (created on-chain with root admin as payer).
@@ -51,6 +75,7 @@ async function joinSeason(options) {
         user: options.user,
         associatedTokenProgram: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
         tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        token2022Program: spl_token_1.TOKEN_2022_PROGRAM_ID,
         systemProgram: web3_js_1.SystemProgram.programId,
     };
     const referrer = options.referrer ?? web3_js_1.PublicKey.default;
@@ -65,12 +90,13 @@ async function joinSeason(options) {
             tier: options.tier,
             referrer,
             referrerTier: options.referrerTier,
+            tokenMint,
         })
         : [];
     const methodBuilder = program.methods
         // Anchor expects BN for u64 args.
         // referrerTier defaults to 0 if no referrer (ignored on-chain)
-        .joinSeason(options.seasonNumber, options.tier, referrer, options.referrerTier ?? 0, options.star ?? false)
+        .joinSeason(options.seasonNumber, options.tier, referrer, options.referrerTier ?? 0, options.star ?? false, launchpad, options.maxSolInLamports ?? new anchor_1.BN(0), options.expectedSolInLamports ?? new anchor_1.BN(0), options.maxSlippageBps ?? 0, options.starFlagPrompt ?? "")
         .accounts(accounts);
     if (remainingAccounts.length > 0) {
         methodBuilder.remainingAccounts(remainingAccounts);
@@ -86,41 +112,26 @@ async function joinSeason(options) {
     let newSeasonMembership;
     let updatedSeason;
     if (curr.seasonSettings) {
-        const [, bump] = (0, pdas_1.getSeasonMembershipPda)(options.seasonNumber, options.user, options.tier);
-        // Mirror on-chain join_season.rs:
-        // current_window = (now - season.started_at) / window_duration (integer division)
-        // joined_window_number = current_window (after bounds checks)
-        const totalWindows = curr.seasonSettings.totalWindowsPerSeason;
-        const depositTier = (0, tierPenalty_1.tierNumberToDepositTier)(options.tier);
-        const perWindowPenalty = (0, tierPenalty_1.getTierPenaltyPerWindow)(depositTier);
-        const depositFull = perWindowPenalty.muln(totalWindows);
-        let joinedWindowNumber = new anchor_1.BN(0);
-        if (curr.season) {
-            if ((0, enumHelpers_1.isSeasonState)(curr.season.seasonState, types_1.SeasonState.Uninitialized)) {
-                // On-chain: season is initialized with started_at = now, so elapsed = 0 -> current_window = 0
-                joinedWindowNumber = new anchor_1.BN(0);
-            }
-            else if (curr.seasonSettings.windowDuration &&
-                !curr.seasonSettings.windowDuration.isZero()) {
-                const startedAt = curr.season.startedAt;
-                const elapsed = now.gte(startedAt) ? now.sub(startedAt) : new anchor_1.BN(0);
-                joinedWindowNumber = elapsed.div(curr.seasonSettings.windowDuration);
-            }
-        }
-        // If this would fail on-chain (current_window >= total_windows), skip optimistic updates.
-        if (joinedWindowNumber.gte(new anchor_1.BN(totalWindows))) {
+        const optimistic = (0, optimistic_1.computeJoinSeasonOptimistic)({
+            user: options.user,
+            seasonNumber: options.seasonNumber,
+            tier: options.tier,
+            referrer: options.referrer ?? web3_js_1.PublicKey.default,
+            tokenMint,
+            now,
+            star: options.star ?? false,
+            seasonSettings: curr.seasonSettings,
+            ...(curr.season ? { season: curr.season } : {}),
+        });
+        if (optimistic.kind === "skip") {
             return {
                 instructions: [instruction],
                 signers,
                 pdas,
             };
         }
-        const depositEscrowed = perWindowPenalty.mul(joinedWindowNumber);
-        const depositActive = depositFull.sub(depositEscrowed);
-        newSeasonMembership = (0, optimistic_1.initializeSeasonMembership)(options.user, options.seasonNumber, depositTier, options.referrer ?? web3_js_1.PublicKey.default, depositActive, depositEscrowed, now, joinedWindowNumber, bump, options.star ?? false);
-        if (curr.season) {
-            updatedSeason = (0, optimistic_1.updateSeasonForJoin)(curr.season, depositActive, depositTier, joinedWindowNumber, totalWindows);
-        }
+        newSeasonMembership = optimistic.newSeasonMembership;
+        updatedSeason = optimistic.updatedSeason;
     }
     return {
         instructions: [instruction],
@@ -139,4 +150,70 @@ async function joinSeason(options) {
             : {}),
     };
 }
+/**
+ * Convenience wrapper: classic (non-launchpad) joinSeason.
+ * - Keeps the existing MIZD-based join behavior.
+ * - App code never passes nullable optional accounts.
+ */
+async function joinSeasonClassic(options) {
+    // IMPORTANT: With `exactOptionalPropertyTypes`, we must OMIT optional props (not set them to `undefined`).
+    return joinSeason({ ...options, launchpad: false });
+}
+/**
+ * Convenience wrapper: launchpad joinSeason.
+ * - Uses SOL in + virtual token escrow.
+ * - App code never passes nullable optional accounts.
+ */
+async function joinSeasonLaunchpad(options) {
+    // IMPORTANT: With `exactOptionalPropertyTypes`, we must OMIT optional props (not set them to `undefined`).
+    const { maxSolInLamports, expectedSolInLamports, maxSlippageBps, ...rest } = options;
+    return joinSeason({
+        ...rest,
+        launchpad: true,
+        ...(maxSolInLamports ? { maxSolInLamports } : {}),
+        ...(expectedSolInLamports ? { expectedSolInLamports } : {}),
+        ...(typeof maxSlippageBps === "number" ? { maxSlippageBps } : {}),
+    });
+}
+/**
+ * Join season AND initialize it (first joiner).
+ * Use this when you know the season doesn't exist yet.
+ *
+ * @param options - Options with REQUIRED starFlagPrompt
+ * @throws Error if starFlagPrompt is empty or exceeds 33 characters
+ */
+async function joinSeasonAndInitialize(options) {
+    // Validate starFlagPrompt
+    if (!options.starFlagPrompt || options.starFlagPrompt.length === 0) {
+        throw new Error("starFlagPrompt is required when initializing a new season");
+    }
+    if (options.starFlagPrompt.length > 33) {
+        throw new Error("starFlagPrompt cannot exceed 33 characters");
+    }
+    return joinSeason(options);
+}
+/**
+ * Join season AND initialize it in launchpad mode (first joiner).
+ * Use this when you know the season doesn't exist yet and want launchpad mode.
+ *
+ * @param options - Options with REQUIRED starFlagPrompt
+ * @throws Error if starFlagPrompt is empty or exceeds 33 characters
+ */
+async function joinSeasonLaunchpadAndInitialize(options) {
+    // Validate starFlagPrompt
+    if (!options.starFlagPrompt || options.starFlagPrompt.length === 0) {
+        throw new Error("starFlagPrompt is required when initializing a new season");
+    }
+    if (options.starFlagPrompt.length > 33) {
+        throw new Error("starFlagPrompt cannot exceed 33 characters");
+    }
+    const { maxSolInLamports, expectedSolInLamports, maxSlippageBps, ...rest } = options;
+    return joinSeason({
+        ...rest,
+        launchpad: true,
+        ...(maxSolInLamports ? { maxSolInLamports } : {}),
+        ...(expectedSolInLamports ? { expectedSolInLamports } : {}),
+        ...(typeof maxSlippageBps === "number" ? { maxSlippageBps } : {}),
+    });
+}
 // getTierPenaltyPerWindow imported from ../utils/tierPenalty

package/dist/instructions/sellMizd.d.ts

@@ -0,0 +1,19 @@
+import { BN } from "@coral-xyz/anchor";
+import { Connection, PublicKey } from "@solana/web3.js";
+import { StandardInstructionResultWithPdas } from "../types/instructionResults";
+export interface SellMizdOptions {
+    connection: Connection;
+    user: PublicKey;
+    /** MIZD input (base units). */
+    mizdInUnits: BN;
+    /** Slippage protection: minimum SOL out (lamports). */
+    minSolOutLamports: BN;
+    /** Must be the on-chain root admin (ADMIN_PUBLIC_KEY); required signer on-chain. */
+    admin?: PublicKey;
+    feePayer?: PublicKey;
+}
+export declare function sellMizd(opts: SellMizdOptions): Promise<StandardInstructionResultWithPdas<{
+    bondingCurve: PublicKey;
+    mizdVault: PublicKey;
+    userMizdAta: PublicKey;
+}>>;

package/dist/instructions/sellMizd.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sellMizd = sellMizd;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const instructionResultHelpers_1 = require("../utils/instructionResultHelpers");
+const constants_1 = require("../utils/constants");
+const pdaManager_1 = require("../utils/pdaManager");
+const programHelpers_1 = require("../utils/programHelpers");
+const signerHelpers_1 = require("../utils/signerHelpers");
+async function sellMizd(opts) {
+    const program = (0, programHelpers_1.getProgram)(opts.connection);
+    const admin = opts.admin ?? constants_1.ADMIN_PUBLIC_KEY;
+    const pdas = pdaManager_1.PDAManager.deriveBondingCurvePdas();
+    const userMizdAta = (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, opts.user);
+    const accounts = {
+        bondingCurve: pdas.bondingCurve,
+        mizdVault: pdas.mizdVault,
+        mizdMint: constants_1.MIZD_TOKEN_MINT,
+        admin,
+        user: opts.user,
+        userMizdAta,
+        associatedTokenProgram: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
+        tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    };
+    const instruction = await program.methods
+        .sellMizd(opts.mizdInUnits, opts.minSolOutLamports)
+        .accounts(accounts)
+        .instruction();
+    const feePayer = (0, signerHelpers_1.resolveFeePayer)({ feePayer: opts.feePayer, admin });
+    const signers = (0, signerHelpers_1.buildSigners)([(0, signerHelpers_1.asAdminSigner)(admin), (0, signerHelpers_1.asUserSigner)(opts.user)], feePayer);
+    return (0, instructionResultHelpers_1.singleInstruction)(instruction, {
+        signers,
+        pdas: {
+            bondingCurve: pdas.bondingCurve,
+            mizdVault: pdas.mizdVault,
+            userMizdAta,
+        },
+    });
+}