@faremeter/payment-solana 0.16.0 → 0.17.1

package/dist/src/exact/verify.js

@@ -1,9 +1,13 @@
 import { isValidationError } from "@faremeter/types";
 import { parseSetComputeUnitLimitInstruction, parseSetComputeUnitPriceInstruction, } from "@solana-program/compute-budget";
-import { findAssociatedTokenPda, parseCreateAssociatedTokenInstruction, parseTransferCheckedInstruction, TOKEN_PROGRAM_ADDRESS, } from "@solana-program/token";
+import { findAssociatedTokenPda, parseTransferCheckedInstruction, TOKEN_PROGRAM_ADDRESS, } from "@solana-program/token";
 import { address, } from "@solana/kit";
 import { PaymentRequirementsExtra } from "./facilitator.js";
 import { logger } from "./logger.js";
+const LIGHTHOUSE_PROGRAM_ADDRESS = address("L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95");
+function isLighthouseInstruction(instruction) {
+    return instruction.programAddress === LIGHTHOUSE_PROGRAM_ADDRESS;
+}
 function verifyComputeUnitLimitInstruction(instruction) {
     if (!instruction.data) {
         return { valid: false };
@@ -65,29 +69,12 @@ async function verifyTransferInstruction(instruction, paymentRequirements, desti
         logger.error("Dropping transfer where the source is the facilitator");
         return false;
     }
-    return (transfer.data.amount === BigInt(paymentRequirements.maxAmountRequired) &&
+    if (transfer.data.amount === BigInt(paymentRequirements.amount) &&
         transfer.accounts.mint.address === paymentRequirements.asset &&
-        transfer.accounts.destination.address === destination);
-}
-function verifyCreateATAInstruction(instruction, facilitatorAddress) {
-    if (!instruction.data || !instruction.accounts) {
-        return false;
-    }
-    try {
-        const createInstruction = parseCreateAssociatedTokenInstruction({
-            accounts: instruction.accounts,
-            programAddress: instruction.programAddress,
-            data: new Uint8Array(instruction.data),
-        });
-        if (createInstruction.accounts.payer.address === facilitatorAddress) {
-            logger.error("Dropping transaction where the facilitator pays for a token account creation");
-            return false;
-        }
-        return true;
-    }
-    catch {
-        return false;
+        transfer.accounts.destination.address === destination) {
+        return transfer.accounts.authority.address;
     }
+    return false;
 }
 export async function isValidTransaction(transactionMessage, paymentRequirements, facilitatorAddress, maxPriorityFee) {
     const extra = PaymentRequirementsExtra(paymentRequirements.extra);
@@ -103,50 +90,33 @@ export async function isValidTransaction(transactionMessage, paymentRequirements
         tokenProgram: TOKEN_PROGRAM_ADDRESS,
     });
     const instructions = transactionMessage.instructions;
-    const facilitatorBase58 = facilitatorAddress.toBase58();
-    if (instructions.length === 3) {
-        // Make typescript happy...
-        const [ix0, ix1, ix2] = instructions;
-        if (!ix0 || !ix1 || !ix2) {
-            return false;
-        }
-        const limitResult = verifyComputeUnitLimitInstruction(ix0);
-        const priceResult = verifyComputeUnitPriceInstruction(ix1);
-        if (!limitResult.valid || !priceResult.valid) {
-            return false;
-        }
-        if (maxPriorityFee !== undefined &&
-            limitResult.units !== undefined &&
-            priceResult.microLamports !== undefined) {
-            const priorityFee = calculatePriorityFee(limitResult.units, priceResult.microLamports);
-            if (priorityFee > maxPriorityFee) {
-                logger.error(`Priority fee ${priorityFee} exceeds maximum ${maxPriorityFee}`);
-                return false;
-            }
-        }
-        return await verifyTransferInstruction(ix2, paymentRequirements, destination, facilitatorBase58);
+    if (instructions.length < 3 || instructions.length > 5) {
+        return false;
     }
-    else if (instructions.length === 4) {
-        const [ix0, ix1, ix2, ix3] = instructions;
-        if (!ix0 || !ix1 || !ix2 || !ix3) {
-            return false;
-        }
-        const limitResult = verifyComputeUnitLimitInstruction(ix0);
-        const priceResult = verifyComputeUnitPriceInstruction(ix1);
-        if (!limitResult.valid || !priceResult.valid) {
+    const [ix0, ix1, ix2, ...rest] = instructions;
+    if (!ix0 || !ix1 || !ix2) {
+        return false;
+    }
+    const limitResult = verifyComputeUnitLimitInstruction(ix0);
+    const priceResult = verifyComputeUnitPriceInstruction(ix1);
+    if (!limitResult.valid || !priceResult.valid) {
+        return false;
+    }
+    if (maxPriorityFee !== undefined &&
+        limitResult.units !== undefined &&
+        priceResult.microLamports !== undefined) {
+        const priorityFee = calculatePriorityFee(limitResult.units, priceResult.microLamports);
+        if (priorityFee > maxPriorityFee) {
+            logger.error(`Priority fee ${priorityFee} exceeds maximum ${maxPriorityFee}`);
             return false;
         }
-        if (maxPriorityFee !== undefined &&
-            limitResult.units !== undefined &&
-            priceResult.microLamports !== undefined) {
-            const priorityFee = calculatePriorityFee(limitResult.units, priceResult.microLamports);
-            if (priorityFee > maxPriorityFee) {
-                logger.error(`Priority fee ${priorityFee} exceeds maximum ${maxPriorityFee}`);
-                return false;
-            }
-        }
-        return (verifyCreateATAInstruction(ix2, facilitatorBase58) &&
-            (await verifyTransferInstruction(ix3, paymentRequirements, destination, facilitatorBase58)));
     }
-    return false;
+    if (!rest.every(isLighthouseInstruction)) {
+        logger.error("Dropping transaction with non-Lighthouse trailing instructions");
+        return false;
+    }
+    const payer = await verifyTransferInstruction(ix2, paymentRequirements, destination, facilitatorAddress);
+    if (!payer)
+        return false;
+    return { payer };
 }

package/dist/src/exact/verify.test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env pnpm tsx
+export {};
+//# sourceMappingURL=verify.test.d.ts.map

package/dist/src/exact/verify.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.test.d.ts","sourceRoot":"","sources":["../../../src/exact/verify.test.ts"],"names":[],"mappings":""}

package/dist/src/exact/verify.test.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env pnpm tsx
+import t from "tap";
+import { isValidTransaction } from "./verify.js";
+import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from "@solana-program/compute-budget";
+import { findAssociatedTokenPda, getTransferCheckedInstruction, TOKEN_PROGRAM_ADDRESS, } from "@solana-program/token";
+import { address, appendTransactionMessageInstructions, createTransactionMessage, generateKeyPairSigner, pipe, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, } from "@solana/kit";
+function createRequirements(overrides) {
+    return {
+        scheme: "exact",
+        network: "solana-devnet",
+        maxTimeoutSeconds: 30,
+        ...overrides,
+    };
+}
+const LIGHTHOUSE_PROGRAM_ADDRESS = address("L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95");
+const FAKE_BLOCKHASH = "EETubP46DHLkT9hAFKy4x2BoFUqUFvKjiiNVY3CaYRi3";
+function buildTxMessage(instructions, feePayer) {
+    return pipe(createTransactionMessage({ version: 0 }), (msg) => setTransactionMessageFeePayer(feePayer.address, msg), (msg) => setTransactionMessageLifetimeUsingBlockhash({ blockhash: FAKE_BLOCKHASH, lastValidBlockHeight: 1000n }, msg), (msg) => appendTransactionMessageInstructions(instructions, msg));
+}
+async function createFixtures() {
+    const facilitator = await generateKeyPairSigner();
+    const sender = await generateKeyPairSigner();
+    const receiver = await generateKeyPairSigner();
+    const mint = await generateKeyPairSigner();
+    const [senderATA] = await findAssociatedTokenPda({
+        mint: mint.address,
+        owner: sender.address,
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+    });
+    const [receiverATA] = await findAssociatedTokenPda({
+        mint: mint.address,
+        owner: receiver.address,
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+    });
+    const [facilitatorATA] = await findAssociatedTokenPda({
+        mint: mint.address,
+        owner: facilitator.address,
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+    });
+    const amount = 1000000n;
+    const decimals = 6;
+    const requirements = createRequirements({
+        amount: amount.toString(),
+        payTo: receiver.address.toString(),
+        asset: mint.address.toString(),
+        extra: {
+            feePayer: facilitator.address.toString(),
+        },
+    });
+    const computeLimitIx = getSetComputeUnitLimitInstruction({
+        units: 50_000,
+    });
+    const computePriceIx = getSetComputeUnitPriceInstruction({
+        microLamports: 1n,
+    });
+    const transferIx = getTransferCheckedInstruction({
+        source: senderATA,
+        mint: mint.address,
+        destination: receiverATA,
+        authority: sender.address,
+        amount,
+        decimals,
+    });
+    return {
+        facilitator,
+        sender,
+        receiver,
+        mint,
+        senderATA,
+        receiverATA,
+        facilitatorATA,
+        amount,
+        decimals,
+        requirements,
+        computeLimitIx,
+        computePriceIx,
+        transferIx,
+    };
+}
+function makeLighthouseIx(data) {
+    return {
+        programAddress: LIGHTHOUSE_PROGRAM_ADDRESS,
+        data: new Uint8Array(data ?? [0]),
+    };
+}
+await t.test("isValidTransaction", async (t) => {
+    await t.test("accepts valid 3-instruction transaction", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts valid 4-instruction transaction with one lighthouse ix", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, makeLighthouseIx()], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts valid 5-instruction transaction with two lighthouse ixs", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeLighthouseIx([1]),
+            makeLighthouseIx([2]),
+        ], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("rejects transaction with fewer than 3 instructions", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction with more than 5 instructions", async (t) => {
+        const f = await createFixtures();
+        const extras = Array.from({ length: 3 }, (_, i) => makeLighthouseIx([i]));
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, ...extras], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction with wrong fee payer", async (t) => {
+        const f = await createFixtures();
+        const wrongPayer = await generateKeyPairSigner();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], wrongPayer);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("throws when extra is missing feePayer", async (t) => {
+        const f = await createFixtures();
+        const badRequirements = {
+            ...f.requirements,
+            extra: {},
+        };
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        await t.rejects(isValidTransaction(txMsg, badRequirements, f.facilitator.address));
+        t.end();
+    });
+    await t.test("rejects transaction with swapped compute budget instructions", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computePriceIx, f.computeLimitIx, f.transferIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("accepts transaction within priority fee limit", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, 100_000);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("rejects transaction exceeding priority fee limit", async (t) => {
+        const f = await createFixtures();
+        const highLimitIx = getSetComputeUnitLimitInstruction({
+            units: 200_000,
+        });
+        const highPriceIx = getSetComputeUnitPriceInstruction({
+            microLamports: 10000000n,
+        });
+        const txMsg = buildTxMessage([highLimitIx, highPriceIx, f.transferIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, 100), false);
+        t.end();
+    });
+    await t.test("rejects transaction exceeding priority fee limit with lighthouse ixs", async (t) => {
+        const f = await createFixtures();
+        const highLimitIx = getSetComputeUnitLimitInstruction({
+            units: 200_000,
+        });
+        const highPriceIx = getSetComputeUnitPriceInstruction({
+            microLamports: 10000000n,
+        });
+        const txMsg = buildTxMessage([highLimitIx, highPriceIx, f.transferIx, makeLighthouseIx()], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, 100), false);
+        t.end();
+    });
+    await t.test("rejects trailing non-lighthouse instruction", async (t) => {
+        const f = await createFixtures();
+        const randomSigner = await generateKeyPairSigner();
+        const fakeIx = {
+            programAddress: randomSigner.address,
+            data: new Uint8Array([0]),
+        };
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, fakeIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects mixed lighthouse and non-lighthouse trailing instructions", async (t) => {
+        const f = await createFixtures();
+        const randomSigner = await generateKeyPairSigner();
+        const fakeIx = {
+            programAddress: randomSigner.address,
+            data: new Uint8Array([0]),
+        };
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeLighthouseIx(),
+            fakeIx,
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction with wrong transfer amount", async (t) => {
+        const f = await createFixtures();
+        const wrongAmountIx = getTransferCheckedInstruction({
+            source: f.senderATA,
+            mint: f.mint.address,
+            destination: f.receiverATA,
+            authority: f.sender.address,
+            amount: f.amount + 1n,
+            decimals: f.decimals,
+        });
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongAmountIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction with wrong mint", async (t) => {
+        const f = await createFixtures();
+        const wrongMint = await generateKeyPairSigner();
+        const [wrongMintSenderATA] = await findAssociatedTokenPda({
+            mint: wrongMint.address,
+            owner: f.sender.address,
+            tokenProgram: TOKEN_PROGRAM_ADDRESS,
+        });
+        const [wrongMintReceiverATA] = await findAssociatedTokenPda({
+            mint: wrongMint.address,
+            owner: f.receiver.address,
+            tokenProgram: TOKEN_PROGRAM_ADDRESS,
+        });
+        const wrongMintIx = getTransferCheckedInstruction({
+            source: wrongMintSenderATA,
+            mint: wrongMint.address,
+            destination: wrongMintReceiverATA,
+            authority: f.sender.address,
+            amount: f.amount,
+            decimals: f.decimals,
+        });
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongMintIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction with wrong destination", async (t) => {
+        const f = await createFixtures();
+        const wrongReceiver = await generateKeyPairSigner();
+        const [wrongReceiverATA] = await findAssociatedTokenPda({
+            mint: f.mint.address,
+            owner: wrongReceiver.address,
+            tokenProgram: TOKEN_PROGRAM_ADDRESS,
+        });
+        const wrongDestIx = getTransferCheckedInstruction({
+            source: f.senderATA,
+            mint: f.mint.address,
+            destination: wrongReceiverATA,
+            authority: f.sender.address,
+            amount: f.amount,
+            decimals: f.decimals,
+        });
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongDestIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction where facilitator is transfer authority", async (t) => {
+        const f = await createFixtures();
+        const badIx = getTransferCheckedInstruction({
+            source: f.senderATA,
+            mint: f.mint.address,
+            destination: f.receiverATA,
+            authority: f.facilitator.address,
+            amount: f.amount,
+            decimals: f.decimals,
+        });
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    await t.test("rejects transaction where source is facilitator ATA", async (t) => {
+        const f = await createFixtures();
+        const badIx = getTransferCheckedInstruction({
+            source: f.facilitatorATA,
+            mint: f.mint.address,
+            destination: f.receiverATA,
+            authority: f.sender.address,
+            amount: f.amount,
+            decimals: f.decimals,
+        });
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address), false);
+        t.end();
+    });
+    t.end();
+});

package/dist/src/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * @title Solana Payment Package
+ * @sidebarTitle Payment Solana
+ * @description Solana payment handlers for SPL tokens and exact payment schemes
+ * @packageDocumentation
+ */
+/**
+ * @title Solana Exact Payment Scheme
+ * @sidebarTitle Payment Solana / Exact
+ * @description SPL token transfer payment handlers for Solana
+ */
 export * as exact from "./exact/index.js";
+/**
+ * @title SPL Token Utilities
+ * @sidebarTitle Payment Solana / SPL Token
+ * @description SPL token balance and account utilities
+ */
 export * as splToken from "./splToken.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -1,2 +1,18 @@
+/**
+ * @title Solana Payment Package
+ * @sidebarTitle Payment Solana
+ * @description Solana payment handlers for SPL tokens and exact payment schemes
+ * @packageDocumentation
+ */
+/**
+ * @title Solana Exact Payment Scheme
+ * @sidebarTitle Payment Solana / Exact
+ * @description SPL token transfer payment handlers for Solana
+ */
 export * as exact from "./exact/index.js";
+/**
+ * @title SPL Token Utilities
+ * @sidebarTitle Payment Solana / SPL Token
+ * @description SPL token balance and account utilities
+ */
 export * as splToken from "./splToken.js";

package/dist/src/splToken.d.ts

@@ -1,12 +1,38 @@
 import type { Rpc } from "@solana/rpc";
 import type { GetTokenAccountBalanceApi } from "@solana/rpc-api";
 import { Base58Address } from "@faremeter/types/solana";
+/**
+ * Arguments for retrieving an SPL token balance.
+ */
 export interface GetTokenBalanceArgs {
+    /** The SPL token mint address */
     asset: Base58Address;
+    /** The wallet address to check the balance for */
     account: Base58Address;
+    /** Solana RPC client with token balance API support */
     rpcClient: Rpc<GetTokenAccountBalanceApi>;
 }
+/**
+ * Checks if an error indicates a token account was not found.
+ *
+ * This handles various error formats from Solana RPC responses,
+ * including TokenAccountNotFoundError and AccountNotFoundError names,
+ * as well as message-based detection.
+ *
+ * @param e - The error to check
+ * @returns True if the error indicates the account does not exist
+ */
 export declare function isAccountNotFoundError(e: unknown): boolean;
+/**
+ * Retrieves the SPL token balance for an account.
+ *
+ * Looks up the associated token account (ATA) for the given wallet and
+ * mint, then fetches the token balance. Returns null if the account
+ * does not exist.
+ *
+ * @param args - The asset, account, and RPC client
+ * @returns The balance amount and decimals, or null if the account does not exist
+ */
 export declare function getTokenBalance(args: GetTokenBalanceArgs): Promise<{
     amount: bigint;
     decimals: number;

package/dist/src/splToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"splToken.d.ts","sourceRoot":"","sources":["../../src/splToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAMxD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,EAAE,GAAG,CAAC,yBAAyB,CAAC,CAAC;CAC3C;AAGD,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,WAkBhD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB;;;UA4B9D"}
+{"version":3,"file":"splToken.d.ts","sourceRoot":"","sources":["../../src/splToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAMxD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,kDAAkD;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,uDAAuD;IACvD,SAAS,EAAE,GAAG,CAAC,yBAAyB,CAAC,CAAC;CAC3C;AAED;;;;;;;;;GASG;AAEH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,WAkBhD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB;;;UA4B9D"}

package/dist/src/splToken.js

@@ -1,6 +1,16 @@
 import { address } from "@solana/addresses";
 import { Base58Address } from "@faremeter/types/solana";
 import { findAssociatedTokenPda, TOKEN_PROGRAM_ADDRESS, } from "@solana-program/token";
+/**
+ * Checks if an error indicates a token account was not found.
+ *
+ * This handles various error formats from Solana RPC responses,
+ * including TokenAccountNotFoundError and AccountNotFoundError names,
+ * as well as message-based detection.
+ *
+ * @param e - The error to check
+ * @returns True if the error indicates the account does not exist
+ */
 // XXX - There has got to be a better way to do this.
 export function isAccountNotFoundError(e) {
     if (!e || !(e instanceof Error)) {
@@ -16,6 +26,16 @@ export function isAccountNotFoundError(e) {
     }
     return false;
 }
+/**
+ * Retrieves the SPL token balance for an account.
+ *
+ * Looks up the associated token account (ATA) for the given wallet and
+ * mint, then fetches the token balance. Returns null if the account
+ * does not exist.
+ *
+ * @param args - The asset, account, and RPC client
+ * @returns The balance amount and decimals, or null if the account does not exist
+ */
 export async function getTokenBalance(args) {
     const { asset, account, rpcClient } = args;
     const owner = address(account);