proof-of-take-sdk 3.0.7 → 3.0.9

package/dist/utils/pdas.js

@@ -15,6 +15,7 @@ const web3_js_1 = require("@solana/web3.js");
 const constants_1 = require("./constants");
 const conversions_1 = require("./conversions");
 const tierPenalty_1 = require("./tierPenalty");
+const tierSeeds_1 = require("./tierSeeds");
 const conversions_2 = require("./conversions");
 /**
  * PDA (Program Derived Address) derivation helpers
@@ -61,11 +62,11 @@ function getSeasonPda(seasonNumber) {
  *   seeds = ["season_membership", season_number_le_u64, user_pubkey_bytes, tier_u8]
  *
  * Tier mapping (u8):
- * 1 = copper, 2 = silver, 3 = gold, 4 = platinum, 5 = mithril
+ * 0 = copper, 1 = silver, 2 = gold, 3 = platinum, 4 = mithril
  *
  * @param seasonNumber - The season number
  * @param user - The user's public key
- * @param tier - Tier number (1..=5)
+ * @param tier - Tier number (0..=4)
  */
 function getSeasonMembershipPda(seasonNumber, user, tier) {
     const t = (0, tierPenalty_1.assertValidTierNumber)(tier);
@@ -74,7 +75,7 @@ function getSeasonMembershipPda(seasonNumber, user, tier) {
         Buffer.from("season_membership"),
         seasonBn.toArrayLike(Buffer, "le", 8),
         user.toBuffer(),
-        Buffer.from([t]),
+        Buffer.from([(0, tierSeeds_1.toTierSeedByte)(t)]),
     ], constants_1.PROGRAM_ID);
 }
 /**
@@ -97,7 +98,7 @@ function getRewardWindowPda(seasonNumber, windowNumber) {
  *
  * @param seasonNumber - The season number
  * @param user - The user's public key
- * @param tier - Tier number (1..=5)
+ * @param tier - Tier number (0..=4)
  * @param windowNumber - The window number
  */
 function getUserWindowParticipationPda(seasonNumber, user, tier, windowNumber) {
@@ -107,7 +108,7 @@ function getUserWindowParticipationPda(seasonNumber, user, tier, windowNumber) {
         Buffer.from("user_window"),
         seasonBn.toArrayLike(Buffer, "le", 8),
         user.toBuffer(),
-        Buffer.from([t]),
+        Buffer.from([(0, tierSeeds_1.toTierSeedByte)(t)]),
         windowNumber.toArrayLike(Buffer, "le", 8),
     ], constants_1.PROGRAM_ID);
 }
@@ -132,7 +133,7 @@ function getSeasonEscrowVaultPda(seasonNumber) {
  *
  * @param seasonNumber - The season number
  * @param referredUser - The referred user's public key (the user who missed)
- * @param tier - Tier number (1..=5)
+ * @param tier - Tier number (0..=4)
  * @param windowNumber - The window number
  */
 function getReferralPenaltyClaimPda(seasonNumber, referredUser, tier, windowNumber) {
@@ -142,7 +143,7 @@ function getReferralPenaltyClaimPda(seasonNumber, referredUser, tier, windowNumb
         Buffer.from(constants_1.REFERRAL_PENALTY_CLAIM_SEED),
         seasonBn.toArrayLike(Buffer, "le", 8),
         referredUser.toBuffer(),
-        Buffer.from([t]),
+        Buffer.from([(0, tierSeeds_1.toTierSeedByte)(t)]),
         windowNumber.toArrayLike(Buffer, "le", 8),
     ], constants_1.PROGRAM_ID);
 }

package/dist/utils/programErrors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Helpers for working with Solana/Anchor program errors.
+ *
+ * Goal: prefer checking errors by numeric code (stable) instead of string names
+ * (which may differ by casing between IDL vs generated TS types).
+ */
+/**
+ * Try to extract a custom program error code (Anchor error code number).
+ *
+ * Returns `null` if the code cannot be determined.
+ */
+export declare function getCustomProgramErrorCode(err: unknown): number | null;
+export declare function isCustomProgramErrorCode(err: unknown, code: number): boolean;

package/dist/utils/programErrors.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Helpers for working with Solana/Anchor program errors.
+ *
+ * Goal: prefer checking errors by numeric code (stable) instead of string names
+ * (which may differ by casing between IDL vs generated TS types).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCustomProgramErrorCode = getCustomProgramErrorCode;
+exports.isCustomProgramErrorCode = isCustomProgramErrorCode;
+/**
+ * Try to extract a custom program error code (Anchor error code number).
+ *
+ * Returns `null` if the code cannot be determined.
+ */
+function getCustomProgramErrorCode(err) {
+    const e = err;
+    // AnchorError shape (Anchor v0.30+ commonly nests under `.error`)
+    const anchorCode = e?.error?.errorCode?.number ??
+        e?.error?.errorCode?.code ??
+        e?.errorCode?.number ??
+        e?.errorCode?.code;
+    if (typeof anchorCode === "number")
+        return anchorCode;
+    // web3.js TransactionError: { InstructionError: [idx, { Custom: code }] }
+    const ixErr = e?.instructionError ?? e?.err ?? e?.error;
+    const instrErr = ixErr?.InstructionError ?? e?.InstructionError;
+    if (Array.isArray(instrErr) && instrErr.length >= 2) {
+        const detail = instrErr[1];
+        const custom = detail?.Custom ?? detail?.custom;
+        if (typeof custom === "number")
+            return custom;
+    }
+    // Fallback: parse from message/logs: "custom program error: 0x1793"
+    const text = (typeof e?.message === "string" ? e.message : "") +
+        "\n" +
+        (Array.isArray(e?.logs) ? e.logs.join("\n") : "");
+    const m = text.match(/custom program error:\s*0x([0-9a-f]+)/i);
+    if (m?.[1]) {
+        const code = Number.parseInt(m[1], 16);
+        return Number.isFinite(code) ? code : null;
+    }
+    return null;
+}
+function isCustomProgramErrorCode(err, code) {
+    return getCustomProgramErrorCode(err) === code;
+}

package/dist/utils/remainingAccounts.d.ts

@@ -0,0 +1,17 @@
+import type { AccountMeta } from "@solana/web3.js";
+import { PublicKey } from "@solana/web3.js";
+import type { BN } from "@coral-xyz/anchor";
+import type { TierNumber } from "../types";
+/**
+ * Build remaining accounts for joinSeason when a referrer is present.
+ *
+ * On-chain expects (when referrer != PublicKey.default):
+ * - remaining_accounts[0]: referrer SeasonMembership PDA (writable)
+ * - remaining_accounts[1]: referrer authority wallet (readonly)
+ * - remaining_accounts[2]: referrer MIZD ATA (writable; may be uninitialized and will be created)
+ */
+export declare function getJoinSeasonRemainingAccounts(params: {
+    seasonNumber: BN;
+    tier: TierNumber;
+    referrer: PublicKey;
+}): AccountMeta[];

package/dist/utils/remainingAccounts.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getJoinSeasonRemainingAccounts = getJoinSeasonRemainingAccounts;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const pdas_1 = require("./pdas");
+const constants_1 = require("./constants");
+/**
+ * Build remaining accounts for joinSeason when a referrer is present.
+ *
+ * On-chain expects (when referrer != PublicKey.default):
+ * - remaining_accounts[0]: referrer SeasonMembership PDA (writable)
+ * - remaining_accounts[1]: referrer authority wallet (readonly)
+ * - remaining_accounts[2]: referrer MIZD ATA (writable; may be uninitialized and will be created)
+ */
+function getJoinSeasonRemainingAccounts(params) {
+    if (params.referrer.equals(web3_js_1.PublicKey.default))
+        return [];
+    const [referrerSeasonMembership] = (0, pdas_1.getSeasonMembershipPda)(params.seasonNumber, params.referrer, params.tier);
+    const referrerMizdAta = (0, spl_token_1.getAssociatedTokenAddressSync)(constants_1.MIZD_TOKEN_MINT, params.referrer);
+    return [
+        {
+            pubkey: referrerSeasonMembership,
+            isWritable: true,
+            isSigner: false,
+        },
+        {
+            pubkey: params.referrer,
+            isWritable: false,
+            isSigner: false,
+        },
+        {
+            pubkey: referrerMizdAta,
+            isWritable: true,
+            isSigner: false,
+        },
+    ];
+}

package/dist/utils/signerHelpers.d.ts

@@ -7,6 +7,26 @@ export interface SignerInfo {
     publicKey: PublicKey;
     role: SignerRole;
 }
+/**
+ * Resolve fee payer for this SDK.
+ *
+ * Policy:
+ * - If `feePayer` is provided, use it.
+ * - Else if an instruction-specific `admin` key is provided, use it.
+ * - Else fall back to global `ADMIN_PUBLIC_KEY`.
+ */
+export declare function resolveFeePayer(params?: {
+    feePayer?: PublicKey | undefined;
+    admin?: PublicKey | undefined;
+}): PublicKey;
+/** Back-compat alias (admin pays by default). */
+export declare function getDefaultFeePayer(feePayer?: PublicKey): PublicKey;
+export declare const asAdminSigner: (publicKey: PublicKey) => SignerInfo;
+export declare const asUserSigner: (publicKey: PublicKey) => SignerInfo;
+export declare const asClaimantSigner: (publicKey: PublicKey) => SignerInfo;
+export declare const asCurrentAdminSigner: (publicKey: PublicKey) => SignerInfo;
+export declare const asFeePayerSigner: (publicKey: PublicKey) => SignerInfo;
+export declare const asPayerSigner: (publicKey: PublicKey) => SignerInfo;
 /**
  * Build signers array with optional fee payer
  * Automatically deduplicates if fee payer is already in required signers

package/dist/utils/signerHelpers.js

@@ -1,6 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.asPayerSigner = exports.asFeePayerSigner = exports.asCurrentAdminSigner = exports.asClaimantSigner = exports.asUserSigner = exports.asAdminSigner = void 0;
+exports.resolveFeePayer = resolveFeePayer;
+exports.getDefaultFeePayer = getDefaultFeePayer;
 exports.buildSigners = buildSigners;
+const constants_1 = require("./constants");
+/**
+ * Resolve fee payer for this SDK.
+ *
+ * Policy:
+ * - If `feePayer` is provided, use it.
+ * - Else if an instruction-specific `admin` key is provided, use it.
+ * - Else fall back to global `ADMIN_PUBLIC_KEY`.
+ */
+function resolveFeePayer(params) {
+    return params?.feePayer ?? params?.admin ?? constants_1.ADMIN_PUBLIC_KEY;
+}
+/** Back-compat alias (admin pays by default). */
+function getDefaultFeePayer(feePayer) {
+    return resolveFeePayer({ feePayer });
+}
+// ---- Signer constructors (to avoid ad-hoc role strings) ----
+const asAdminSigner = (publicKey) => ({
+    publicKey,
+    role: "admin",
+});
+exports.asAdminSigner = asAdminSigner;
+const asUserSigner = (publicKey) => ({
+    publicKey,
+    role: "user",
+});
+exports.asUserSigner = asUserSigner;
+const asClaimantSigner = (publicKey) => ({
+    publicKey,
+    role: "claimant",
+});
+exports.asClaimantSigner = asClaimantSigner;
+const asCurrentAdminSigner = (publicKey) => ({
+    publicKey,
+    role: "currentAdmin",
+});
+exports.asCurrentAdminSigner = asCurrentAdminSigner;
+const asFeePayerSigner = (publicKey) => ({
+    publicKey,
+    role: "feePayer",
+});
+exports.asFeePayerSigner = asFeePayerSigner;
+const asPayerSigner = (publicKey) => ({
+    publicKey,
+    role: "payer",
+});
+exports.asPayerSigner = asPayerSigner;
 /**
  * Build signers array with optional fee payer
  * Automatically deduplicates if fee payer is already in required signers
@@ -11,11 +61,20 @@ exports.buildSigners = buildSigners;
  */
 function buildSigners(requiredSigners, feePayer) {
     const signers = [...requiredSigners];
-    if (feePayer) {
-        const alreadyIncluded = signers.some((s) => s.publicKey.equals(feePayer));
-        if (!alreadyIncluded) {
-            signers.push({ publicKey: feePayer, role: "feePayer" });
-        }
+    if (!feePayer) {
+        return signers;
+    }
+    // If fee payer is already among required signers (e.g. admin), move that signer to the front
+    // while preserving its original role. This ensures builders that default to signers[0] will
+    // still behave correctly, and avoids requiring a separate "feePayer" wallet mapping.
+    const existingIdx = signers.findIndex((s) => s.publicKey.equals(feePayer));
+    if (existingIdx >= 0) {
+        const existing = signers.splice(existingIdx, 1)[0];
+        signers.unshift(existing);
+        return signers;
     }
+    // Otherwise, include an explicit fee payer signer (callers must provide a wallet for role "feePayer").
+    const role = feePayer.equals(constants_1.ADMIN_PUBLIC_KEY) ? "admin" : "feePayer";
+    signers.unshift({ publicKey: feePayer, role });
     return signers;
 }

package/dist/utils/tierPenalty.d.ts

@@ -1,11 +1,11 @@
 import { BN } from "@coral-xyz/anchor";
 import { SeasonDepositTier, TierNumber } from "../types";
 /**
- * Validate and normalize a tier number (1..=5).
+ * Validate and normalize a tier number (0..=4).
  */
 export declare function assertValidTierNumber(tier: number): TierNumber;
 /**
- * Convert numeric tier (1..=5) to the Anchor enum representation.
+ * Convert numeric tier (0..=4) to the Anchor enum representation.
  */
 export declare function tierNumberToDepositTier(tier: number): SeasonDepositTier;
 /**

package/dist/utils/tierPenalty.js

@@ -3,31 +3,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertValidTierNumber = assertValidTierNumber;
 exports.tierNumberToDepositTier = tierNumberToDepositTier;
 exports.getTierPenaltyPerWindow = getTierPenaltyPerWindow;
-const anchor_1 = require("@coral-xyz/anchor");
 const depositTier_1 = require("./depositTier");
+const season_1 = require("../constants/season");
 /**
- * Validate and normalize a tier number (1..=5).
+ * Validate and normalize a tier number (0..=4).
  */
 function assertValidTierNumber(tier) {
-    if (!Number.isInteger(tier) || tier < 1 || tier > 5) {
-        throw new Error("Invalid tier: must be an integer between 1 and 5");
+    if (!Number.isInteger(tier) || tier < 0 || tier > 4) {
+        throw new Error("Invalid tier: must be an integer between 0 and 4");
     }
     return tier;
 }
 /**
- * Convert numeric tier (1..=5) to the Anchor enum representation.
+ * Convert numeric tier (0..=4) to the Anchor enum representation.
  */
 function tierNumberToDepositTier(tier) {
     switch (assertValidTierNumber(tier)) {
-        case 1:
+        case 0:
             return { copper: {} };
-        case 2:
+        case 1:
             return { silver: {} };
-        case 3:
+        case 2:
             return { gold: {} };
-        case 4:
+        case 3:
             return { platinum: {} };
-        case 5:
+        case 4:
             return { mithril: {} };
     }
     // unreachable
@@ -40,17 +40,18 @@ function tierNumberToDepositTier(tier) {
  * to mirror on-chain accounting (refund vs bonus portions).
  */
 function getTierPenaltyPerWindow(tier) {
-    // Base units (7 decimals): 1 MIZD = 10_000_000
+    // Base units (7 decimals): 1 MIZD = MIZD_DECIMALS
+    void season_1.MIZD_DECIMALS; // doc-only; keep TS/ESLint from flagging as unused in some configs
     switch ((0, depositTier_1.getDepositTierName)(tier)) {
         case "copper":
-            return new anchor_1.BN(1000000); // 0.1 MIZD
+            return season_1.MIZD_DECIMALS_BN.divn(10); // 0.1 MIZD
         case "silver":
-            return new anchor_1.BN(10000000); // 1 MIZD
+            return season_1.MIZD_DECIMALS_BN; // 1 MIZD
         case "gold":
-            return new anchor_1.BN(100000000); // 10 MIZD
+            return season_1.MIZD_DECIMALS_BN.muln(10); // 10 MIZD
         case "platinum":
-            return new anchor_1.BN(1000000000); // 100 MIZD
+            return season_1.MIZD_DECIMALS_BN.muln(100); // 100 MIZD
         case "mithril":
-            return new anchor_1.BN(10000000000); // 1,000 MIZD
+            return season_1.MIZD_DECIMALS_BN.muln(1000); // 1,000 MIZD
     }
 }

package/dist/utils/tierSeeds.d.ts

@@ -0,0 +1,8 @@
+import type { TierNumber } from "../types";
+/**
+ * Canonical tier encoding used for PDA seeds across the program.
+ *
+ * IMPORTANT: The tier byte is part of PDA seeds for several accounts (e.g. SeasonMembership,
+ * UserWindowParticipation, ReferralPenaltyClaim). Changing this mapping changes addresses.
+ */
+export declare function toTierSeedByte(tier: TierNumber): number;

package/dist/utils/tierSeeds.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toTierSeedByte = toTierSeedByte;
+/**
+ * Canonical tier encoding used for PDA seeds across the program.
+ *
+ * IMPORTANT: The tier byte is part of PDA seeds for several accounts (e.g. SeasonMembership,
+ * UserWindowParticipation, ReferralPenaltyClaim). Changing this mapping changes addresses.
+ */
+function toTierSeedByte(tier) {
+    // Currently the TierNumber union is already the canonical seed byte (0..4),
+    // but keeping this indirection makes future tier encoding changes a 1-line edit.
+    return tier;
+}

package/dist/utils/transactionBuilder.d.ts

@@ -35,6 +35,7 @@ export declare class TransactionBuilder {
     private connection;
     private wallets;
     constructor(connection: Connection, wallets: Map<string, WalletAdapter>);
+    private getFeePayerFromSigners;
     /**
      * Build a transaction from instructions
      */

package/dist/utils/transactionBuilder.js

@@ -12,6 +12,14 @@ class TransactionBuilder {
         this.connection = connection;
         this.wallets = wallets;
     }
+    getFeePayerFromSigners(signers) {
+        const explicit = signers.find((s) => s.role === "feePayer")?.publicKey;
+        const fallback = signers[0]?.publicKey;
+        if (!explicit && !fallback) {
+            throw new Error("At least one signer required");
+        }
+        return explicit ?? fallback;
+    }
     /**
      * Build a transaction from instructions
      */
@@ -60,11 +68,8 @@ class TransactionBuilder {
      * Build, sign, and send a transaction
      */
     async buildSignAndSend(instructions, signers, options) {
-        // Determine fee payer (first signer by default)
-        const feePayer = signers[0]?.publicKey;
-        if (!feePayer) {
-            throw new Error("At least one signer required");
-        }
+        // Determine fee payer (explicit feePayer role preferred; else first signer)
+        const feePayer = this.getFeePayerFromSigners(signers);
         // Build transaction
         const transaction = await this.buildTransaction(instructions, feePayer, options);
         // Sign transaction
@@ -84,10 +89,7 @@ class TransactionBuilder {
      * Simulate a transaction without sending
      */
     async simulate(instructions, signers) {
-        const feePayer = signers[0]?.publicKey;
-        if (!feePayer) {
-            throw new Error("At least one signer required for simulation");
-        }
+        const feePayer = this.getFeePayerFromSigners(signers);
         const transaction = await this.buildTransaction(instructions, feePayer);
         try {
             const simulation = await this.connection.simulateTransaction(transaction);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proof-of-take-sdk",
-  "version": "3.0.7",
+  "version": "3.0.9",
   "description": "TypeScript SDK for Proof of Take Solana program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",