@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/receipt-export.js

@@ -0,0 +1,149 @@
+import { bytesToHex, formatExactTokenAmount } from "./receipt.js";
+/**
+ * The limits beside a receipt, preferring the snapshot the program wrote into
+ * the receipt itself. A relay observation is used only when there is none.
+ */
+export function receiptPolicy(receipt, relayObserved) {
+    const snapshot = receipt.policySnapshot;
+    if (snapshot) {
+        const { version: _version, ...limits } = snapshot;
+        return { source: "on-chain", limits };
+    }
+    if (relayObserved?.source === "relay-observed")
+        return relayObserved;
+    return { source: "not-recorded" };
+}
+function u64Field(value) {
+    if (typeof value !== "string" || !/^\d+$/.test(value))
+        return null;
+    const parsed = BigInt(value);
+    return parsed <= 18446744073709551615n ? parsed : null;
+}
+/**
+ * Read the `policy` object the ChainPay relay returns from
+ * `GET /v1/receipts/{receipt}`. Only a well-formed relay observation is
+ * accepted; anything else is null, never a guessed limit. An "on-chain" value
+ * from the relay is ignored because the receipt account is read directly.
+ */
+export function relayObservedPolicy(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const policy = value;
+    if (policy.source !== "relay-observed")
+        return null;
+    const fields = {
+        maxPerPayment: u64Field(policy.max_per_payment),
+        totalLimit: u64Field(policy.total_limit),
+        amountSpentAfter: u64Field(policy.amount_spent_after),
+        paymentCountAfter: u64Field(policy.payment_count_after),
+        maxPaymentCount: u64Field(policy.max_payment_count),
+        expiresAtSlot: u64Field(policy.expires_at_slot),
+        cooldownSlots: u64Field(policy.cooldown_slots),
+    };
+    const observedAtSlot = u64Field(policy.observed_at_slot);
+    if (observedAtSlot === null || Object.values(fields).some((field) => field === null))
+        return null;
+    return {
+        source: "relay-observed",
+        limits: fields,
+        observedAtSlot,
+        includesLaterPayments: policy.includes_later_payments === true,
+    };
+}
+export function receiptExplorerUrl(receipt, cluster = "devnet") {
+    const suffix = cluster === "devnet" ? "?cluster=devnet" : "";
+    return receipt.transactionSignature
+        ? `https://explorer.solana.com/tx/${receipt.transactionSignature}${suffix}`
+        : `https://explorer.solana.com/address/${receipt.address}${suffix}`;
+}
+/**
+ * Accounting tools read the first five columns; the rest let a reader trace
+ * every row back to Solana. New columns are appended so existing imports keep
+ * their column positions.
+ */
+export const RECEIPT_CSV_HEADERS = [
+    "Date",
+    "Description",
+    "Amount",
+    "Payee",
+    "Reference",
+    "Token",
+    "Agent",
+    "Spending permission",
+    "Per-payment limit",
+    "Total limit",
+    "Spent after",
+    "Limits source",
+    "Receipt",
+    "Verify URL",
+    "Explorer URL",
+    "PO number",
+    "Order match",
+];
+/** Exact decimal, trailing zeros trimmed. Unknown decimals stay labeled base units. */
+function exactAmount(value, decimals) {
+    const exact = formatExactTokenAmount(value, decimals);
+    if (exact.displayKind === "base-units")
+        return `${exact.baseUnits} base units`;
+    return exact.display.includes(".") ? exact.display.replace(/0+$/, "").replace(/\.$/, "") : exact.display;
+}
+function isoDate(blockTime) {
+    if (blockTime === null || blockTime === undefined || !Number.isFinite(blockTime))
+        return "";
+    return new Date(blockTime * 1000).toISOString().slice(0, 10);
+}
+/**
+ * One CSV cell. A value a spreadsheet would run as a formula (leading =, +,
+ * -, @, tab, or carriage return) is prefixed with an apostrophe so it stays
+ * text. Then RFC 4180 quoting: wrap in quotes when the value holds a comma,
+ * quote, or line break, doubling inner quotes.
+ */
+export function csvCell(value) {
+    const safe = /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
+    return /[",\r\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+}
+function description(purpose) {
+    if (purpose?.description)
+        return purpose.description;
+    if (purpose?.lineItems?.length)
+        return purpose.lineItems.map((item) => item.label).join("; ");
+    return "";
+}
+function rowCells(row) {
+    const { receipt, decimals } = row;
+    const policy = row.policy ?? receiptPolicy(receipt);
+    const limits = policy.source === "not-recorded" ? null : policy.limits;
+    // A relay read taken after a later payment no longer says what was spent
+    // after this one. Leave the cell empty rather than show a larger number.
+    const spentAfterKnown = limits && !(policy.source === "relay-observed" && policy.includesLaterPayments);
+    const payee = receipt.recipientTokenAccount;
+    return [
+        isoDate(row.blockTime),
+        description(row.purpose),
+        exactAmount(receipt.amount, decimals),
+        payee,
+        row.purpose?.invoice ?? bytesToHex(receipt.invoiceHash),
+        row.symbol ?? receipt.mint,
+        receipt.agent,
+        receipt.mandate,
+        limits ? exactAmount(limits.maxPerPayment, decimals) : "",
+        limits ? exactAmount(limits.totalLimit, decimals) : "",
+        spentAfterKnown ? exactAmount(limits.amountSpentAfter, decimals) : "",
+        policy.source,
+        receipt.address,
+        row.verifyUrl ?? "",
+        row.explorerUrl ?? receiptExplorerUrl(receipt),
+        row.poNumber ?? "",
+        row.orderMatch ?? "",
+    ];
+}
+/**
+ * One CSV of receipts with QuickBooks-friendly leading columns (Date,
+ * Description, Amount, Payee, Reference), then the ChainPay columns. Amounts
+ * are exact decimals from base units, never floating point. CRLF line
+ * endings, header row always present.
+ */
+export function receiptsToCsv(rows) {
+    const lines = [RECEIPT_CSV_HEADERS.map(csvCell), ...rows.map((row) => rowCells(row).map(csvCell))];
+    return lines.map((cells) => cells.join(",")).join("\r\n") + "\r\n";
+}

package/dist/receipt.d.ts

@@ -0,0 +1,108 @@
+import type { Address, Mandate, PaymentReceipt, PaymentStatus } from "./types.js";
+import { decodePaymentReceipt } from "./accounts.js";
+export type ReceiptAccountView = {
+    address: Address;
+    owner: Address;
+    data: Uint8Array | Buffer;
+};
+export type ReceiptValidationCode = "wrong_owner" | "wrong_discriminator" | "truncated" | "pda_mismatch" | "unsettled" | "not_found";
+export type ReceiptReadFailure = {
+    valid: false;
+    code: ReceiptValidationCode;
+    reason: string;
+};
+export type ReceiptReadSuccess = {
+    valid: true;
+    receipt: PaymentReceipt;
+    programId: Address;
+    derivedAddress: Address;
+    settled: boolean;
+};
+export type ReceiptReadResult = ReceiptReadSuccess | ReceiptReadFailure;
+export type ReadReceiptOptions = {
+    programId?: Address;
+    requireSettled?: boolean;
+    transactionSignature?: string;
+};
+export type TokenAmountDisplay = {
+    /** Exact unsigned integer string of base units. Never a JS Number. */
+    baseUnits: string;
+    decimals: number | null;
+    /**
+     * Decimal-inserted UI amount when a supported mint owner and decimals
+     * are known. Otherwise the exact base-unit string. Never rounded.
+     */
+    display: string;
+    displayKind: "ui-amount" | "base-units";
+};
+export type MintDecimalsRead = {
+    ok: true;
+    decimals: number;
+} | {
+    ok: false;
+    reason: "unsupported_owner" | "truncated" | "not_a_mint" | "missing";
+};
+export type CurrentMandateRead = {
+    status: "present";
+    mandate: Mandate;
+} | {
+    status: "absent";
+} | {
+    status: "unavailable";
+    reason: string;
+};
+export type PublicReceiptProof = {
+    receipt: ReceiptReadResult;
+    amount: TokenAmountDisplay | null;
+    currentMandate: CurrentMandateRead;
+};
+export declare function createReceiptReference(address: Address, mandate: Address, invoiceHash: Uint8Array, status: PaymentStatus): Pick<PaymentReceipt, "address" | "mandate" | "invoiceHash" | "status">;
+export declare function receiptAddress(mandate: Address, invoiceHash: Uint8Array, programId?: Address): Address;
+export { decodePaymentReceipt };
+export declare function bytesToHex(value: Uint8Array): string;
+export declare function hexToBytes(value: string, name: string): Uint8Array;
+export declare function readVerifiedMintDecimals(account: {
+    owner: Address;
+    data: Uint8Array | Buffer;
+} | null | undefined): MintDecimalsRead;
+/**
+ * Format a u64 token amount without Number conversion or rounding.
+ * Unknown decimals stay exact base units so a public card never invents
+ * a UI amount.
+ */
+export declare function formatExactTokenAmount(amount: bigint, decimals?: number | null): TokenAmountDisplay;
+export declare function amountDisplayFromMint(amount: bigint, mintAccount?: {
+    owner: Address;
+    data: Uint8Array | Buffer;
+} | null): TokenAmountDisplay;
+/**
+ * Optional current-mandate enrichment. Independent of creation history
+ * and source token metadata. Missing or undecodable accounts never
+ * become fabricated limits.
+ */
+export declare function readCurrentMandateFields(account: ReceiptAccountView | null | undefined, options?: {
+    programId?: Address;
+    currentSlot?: bigint;
+    expectedAddress?: Address;
+}): CurrentMandateRead;
+/**
+ * Validating receipt reader for public `/verify` and shared ledger cards.
+ * Confirms program owner, discriminator, length, PDA seeds
+ * `["receipt", mandate, invoice_hash]`, and optional settled status.
+ * `signatureReference` is never treated as seller delivery.
+ */
+export declare function readPaymentReceiptAccount(account: ReceiptAccountView, options?: ReadReceiptOptions): ReceiptReadResult;
+/** Public verify path: same checks plus settled status. */
+export declare function readPublicSettledReceipt(account: ReceiptAccountView, options?: Omit<ReadReceiptOptions, "requireSettled">): ReceiptReadResult;
+export declare function requirePaymentReceiptAccount(account: ReceiptAccountView, options?: ReadReceiptOptions): PaymentReceipt;
+export declare function assemblePublicReceiptProof(input: {
+    receiptAccount: ReceiptAccountView;
+    programId?: Address;
+    mintAccount?: {
+        owner: Address;
+        data: Uint8Array | Buffer;
+    } | null;
+    mandateAccount?: ReceiptAccountView | null;
+    currentSlot?: bigint;
+    transactionSignature?: string;
+}): PublicReceiptProof;

package/dist/receipt.js

@@ -0,0 +1,213 @@
+import { decodeCurrentMandateFields, decodePaymentReceipt } from "./accounts.js";
+import { ACCOUNT_DISCRIMINATORS, DEFAULT_PROGRAM_ID, RECEIPT_ACCOUNT_LENGTH, RECEIPT_STATUS_SETTLED, SPL_TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, } from "./constants.js";
+import { address } from "./encoding.js";
+import { deriveReceiptAddress } from "./pda.js";
+const MAX_U64 = 18446744073709551615n;
+const ACCOUNT_DISCRIMINATOR_LENGTH = 8;
+function accountBytes(data) {
+    return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+function discriminatorsEqual(data, expected) {
+    for (let index = 0; index < expected.length; index += 1) {
+        if (data[index] !== expected[index])
+            return false;
+    }
+    return true;
+}
+function failure(code, reason) {
+    return { valid: false, code, reason };
+}
+export function createReceiptReference(address, mandate, invoiceHash, status) {
+    return { address, mandate, invoiceHash, status };
+}
+export function receiptAddress(mandate, invoiceHash, programId = DEFAULT_PROGRAM_ID) {
+    return deriveReceiptAddress(mandate, invoiceHash, programId);
+}
+export { decodePaymentReceipt };
+export function bytesToHex(value) {
+    return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function hexToBytes(value, name) {
+    const normalized = value.startsWith("0x") ? value.slice(2) : value;
+    if (!/^[0-9a-fA-F]+$/.test(normalized) || normalized.length !== 64) {
+        throw new Error(`${name} must be exactly 32 bytes encoded as hexadecimal`);
+    }
+    const bytes = new Uint8Array(32);
+    for (let index = 0; index < 32; index += 1) {
+        bytes[index] = Number.parseInt(normalized.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Read mint decimals only after confirming the account owner is a supported
+ * token program. Callers must not inspect the decimals byte first.
+ */
+/** SPL Mint account length. Token-2022 mints pad to 165 and then tag themselves. */
+const MINT_LEN = 82;
+/** Offset of the Token-2022 `account_type` discriminator. */
+const ACCOUNT_TYPE_OFFSET = 165;
+/** `account_type` value meaning Mint. A token account is 2. */
+const ACCOUNT_TYPE_MINT = 1;
+export function readVerifiedMintDecimals(account) {
+    if (!account)
+        return { ok: false, reason: "missing" };
+    const owner = address(account.owner);
+    if (owner !== SPL_TOKEN_PROGRAM_ID && owner !== TOKEN_2022_PROGRAM_ID) {
+        return { ok: false, reason: "unsupported_owner" };
+    }
+    const data = accountBytes(account.data);
+    if (data.length <= 44)
+        return { ok: false, reason: "truncated" };
+    // `data[44]` is the decimals byte of an SPL Mint, but a 165-byte token account
+    // is owned by the same programs and would put part of its `owner` pubkey at
+    // that offset, yielding an arbitrary 0-255 as decimals and a confidently wrong
+    // amount. Accept only a base mint (exactly 82 bytes) or a Token-2022 mint,
+    // which pads to 165 and tags `account_type = 1` at offset 165.
+    const isBaseMint = data.length === MINT_LEN;
+    const isExtendedMint = data.length > ACCOUNT_TYPE_OFFSET && data[ACCOUNT_TYPE_OFFSET] === ACCOUNT_TYPE_MINT;
+    if (!isBaseMint && !isExtendedMint)
+        return { ok: false, reason: "not_a_mint" };
+    return { ok: true, decimals: data[44] };
+}
+/**
+ * Format a u64 token amount without Number conversion or rounding.
+ * Unknown decimals stay exact base units so a public card never invents
+ * a UI amount.
+ */
+export function formatExactTokenAmount(amount, decimals) {
+    if (amount < 0n || amount > MAX_U64) {
+        throw new Error("amount must fit in an unsigned 64-bit integer");
+    }
+    const baseUnits = amount.toString();
+    if (decimals === null
+        || decimals === undefined
+        || !Number.isInteger(decimals)
+        || decimals < 0
+        || decimals > 255) {
+        return { baseUnits, decimals: null, display: baseUnits, displayKind: "base-units" };
+    }
+    if (decimals === 0) {
+        return { baseUnits, decimals, display: baseUnits, displayKind: "ui-amount" };
+    }
+    const padded = baseUnits.padStart(decimals + 1, "0");
+    const whole = padded.slice(0, padded.length - decimals);
+    const fraction = padded.slice(padded.length - decimals);
+    return { baseUnits, decimals, display: `${whole}.${fraction}`, displayKind: "ui-amount" };
+}
+export function amountDisplayFromMint(amount, mintAccount) {
+    const mint = readVerifiedMintDecimals(mintAccount);
+    return formatExactTokenAmount(amount, mint.ok ? mint.decimals : null);
+}
+/**
+ * Optional current-mandate enrichment. Independent of creation history
+ * and source token metadata. Missing or undecodable accounts never
+ * become fabricated limits.
+ */
+export function readCurrentMandateFields(account, options = {}) {
+    if (!account)
+        return { status: "absent" };
+    const programId = address(options.programId ?? DEFAULT_PROGRAM_ID);
+    try {
+        if (address(account.owner) !== programId) {
+            return { status: "unavailable", reason: "Mandate account is not owned by the ChainPay program" };
+        }
+        if (options.expectedAddress !== undefined && address(account.address) !== address(options.expectedAddress)) {
+            return { status: "unavailable", reason: "Mandate account address does not match the receipt mandate" };
+        }
+        return {
+            status: "present",
+            mandate: decodeCurrentMandateFields(account.data, account.address, options.currentSlot),
+        };
+    }
+    catch (error) {
+        return {
+            status: "unavailable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Validating receipt reader for public `/verify` and shared ledger cards.
+ * Confirms program owner, discriminator, length, PDA seeds
+ * `["receipt", mandate, invoice_hash]`, and optional settled status.
+ * `signatureReference` is never treated as seller delivery.
+ */
+export function readPaymentReceiptAccount(account, options = {}) {
+    const programId = address(options.programId ?? DEFAULT_PROGRAM_ID);
+    let requestedAddress;
+    try {
+        requestedAddress = address(account.address);
+    }
+    catch {
+        return failure("not_found", "Receipt address is not a valid Solana public key");
+    }
+    try {
+        if (address(account.owner) !== programId) {
+            return failure("wrong_owner", "Receipt account is not owned by the ChainPay program");
+        }
+    }
+    catch {
+        return failure("wrong_owner", "Receipt account is not owned by the ChainPay program");
+    }
+    const data = accountBytes(account.data);
+    if (data.length < ACCOUNT_DISCRIMINATOR_LENGTH) {
+        return failure("truncated", "PaymentReceipt account data is truncated");
+    }
+    if (!discriminatorsEqual(data, ACCOUNT_DISCRIMINATORS.paymentReceipt)) {
+        return failure("wrong_discriminator", "Invalid PaymentReceipt account discriminator");
+    }
+    if (data.length < RECEIPT_ACCOUNT_LENGTH) {
+        return failure("truncated", "PaymentReceipt account data is truncated");
+    }
+    const receipt = decodePaymentReceipt(data, requestedAddress, options.transactionSignature);
+    const derivedAddress = deriveReceiptAddress(receipt.mandate, receipt.invoiceHash, programId);
+    if (derivedAddress !== requestedAddress) {
+        return failure("pda_mismatch", "Receipt address does not match PDA seeds [\"receipt\", mandate, invoice_hash]");
+    }
+    const settled = receipt.onChainStatus === RECEIPT_STATUS_SETTLED;
+    if ((options.requireSettled ?? false) && !settled) {
+        return failure("unsettled", "Receipt is not settled");
+    }
+    return {
+        valid: true,
+        receipt,
+        programId,
+        derivedAddress,
+        settled,
+    };
+}
+/** Public verify path: same checks plus settled status. */
+export function readPublicSettledReceipt(account, options = {}) {
+    return readPaymentReceiptAccount(account, { ...options, requireSettled: true });
+}
+export function requirePaymentReceiptAccount(account, options = {}) {
+    const result = readPaymentReceiptAccount(account, options);
+    if (!result.valid)
+        throw new Error(result.reason);
+    return result.receipt;
+}
+export function assemblePublicReceiptProof(input) {
+    const receipt = readPublicSettledReceipt(input.receiptAccount, {
+        programId: input.programId,
+        transactionSignature: input.transactionSignature,
+    });
+    if (!receipt.valid) {
+        return {
+            receipt,
+            amount: null,
+            currentMandate: readCurrentMandateFields(input.mandateAccount, {
+                programId: input.programId,
+                currentSlot: input.currentSlot,
+            }),
+        };
+    }
+    return {
+        receipt,
+        amount: amountDisplayFromMint(receipt.receipt.amount, input.mintAccount),
+        currentMandate: readCurrentMandateFields(input.mandateAccount, {
+            programId: input.programId,
+            currentSlot: input.currentSlot,
+            expectedAddress: receipt.receipt.mandate,
+        }),
+    };
+}

package/dist/solana.d.ts

@@ -0,0 +1,5 @@
+import { Connection, Transaction, TransactionInstruction } from "@solana/web3.js";
+import type { ChainPayInstruction, PreparedTransaction } from "./types.js";
+export declare function toWeb3Instruction(instruction: ChainPayInstruction): TransactionInstruction;
+export declare function toWeb3Transaction(prepared: PreparedTransaction, recentBlockhash: string): Transaction;
+export { Connection };

package/dist/solana.js

@@ -0,0 +1,20 @@
+import { Connection, Transaction, TransactionInstruction, } from "@solana/web3.js";
+import { publicKey } from "./encoding.js";
+export function toWeb3Instruction(instruction) {
+    return new TransactionInstruction({
+        programId: publicKey(instruction.programId),
+        keys: instruction.keys.map((key) => ({
+            pubkey: publicKey(key.address),
+            isSigner: key.isSigner,
+            isWritable: key.isWritable,
+        })),
+        data: Buffer.from(instruction.data),
+    });
+}
+export function toWeb3Transaction(prepared, recentBlockhash) {
+    const feePayer = prepared.feePayer ?? prepared.requiredSigners[0];
+    if (!feePayer)
+        throw new Error("A prepared transaction needs a fee payer");
+    return new Transaction({ feePayer: publicKey(feePayer), recentBlockhash }).add(...prepared.instructions.map(toWeb3Instruction));
+}
+export { Connection };

package/dist/token-capabilities.d.ts

@@ -0,0 +1,9 @@
+import { type Commitment, type Connection } from "@solana/web3.js";
+import type { Address, TokenCapabilityProfile, TokenProgram } from "./types.js";
+export declare function inspectTokenCapabilities(connection: Connection, input: {
+    mint: Address;
+    sourceTokenAccount: Address;
+    recipientTokenAccount: Address;
+    tokenProgram: TokenProgram;
+    commitment?: Commitment;
+}): Promise<TokenCapabilityProfile>;

package/dist/token-capabilities.js

@@ -0,0 +1,139 @@
+import { AccountState, ExtensionType, TOKEN_2022_PROGRAM_ID as SPL_TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID as SPL_TOKEN_PROGRAM_ID, getAccount, getCpiGuard, getDefaultAccountState, getEpochFee, getExtensionTypes, getMemoTransfer, getMint, getPausableConfig, getTransferFeeConfig, getTransferHook, } from "@solana/spl-token";
+import { PublicKey } from "@solana/web3.js";
+import { publicKey } from "./encoding.js";
+const CONFIDENTIAL_TRANSFER_FEE_CONFIG = 16;
+const CONFIDENTIAL_TRANSFER_FEE_AMOUNT = 17;
+const KNOWN_MINT_EXTENSIONS = new Set([
+    ExtensionType.TransferFeeConfig,
+    ExtensionType.MintCloseAuthority,
+    ExtensionType.ConfidentialTransferMint,
+    ExtensionType.DefaultAccountState,
+    ExtensionType.NonTransferable,
+    ExtensionType.InterestBearingConfig,
+    ExtensionType.PermanentDelegate,
+    ExtensionType.TransferHook,
+    CONFIDENTIAL_TRANSFER_FEE_CONFIG,
+    ExtensionType.MetadataPointer,
+    ExtensionType.TokenMetadata,
+    ExtensionType.GroupPointer,
+    ExtensionType.TokenGroup,
+    ExtensionType.GroupMemberPointer,
+    ExtensionType.TokenGroupMember,
+    ExtensionType.ScaledUiAmountConfig,
+    ExtensionType.PausableConfig,
+    ExtensionType.PermissionedBurn,
+]);
+const KNOWN_ACCOUNT_EXTENSIONS = new Set([
+    ExtensionType.TransferFeeAmount,
+    ExtensionType.ConfidentialTransferAccount,
+    ExtensionType.ImmutableOwner,
+    ExtensionType.MemoTransfer,
+    ExtensionType.CpiGuard,
+    ExtensionType.NonTransferableAccount,
+    ExtensionType.TransferHookAccount,
+    CONFIDENTIAL_TRANSFER_FEE_AMOUNT,
+    ExtensionType.PausableAccount,
+]);
+function extensionName(extension) {
+    if (extension === CONFIDENTIAL_TRANSFER_FEE_CONFIG)
+        return "ConfidentialTransferFeeConfig";
+    if (extension === CONFIDENTIAL_TRANSFER_FEE_AMOUNT)
+        return "ConfidentialTransferFeeAmount";
+    return ExtensionType[extension] ?? `UnknownExtension(${extension})`;
+}
+function unexpectedExtensions(extensions, known, scope) {
+    return extensions
+        .filter((extension) => !known.has(extension))
+        .map((extension) => `${scope} has unsupported ${extensionName(extension)}`);
+}
+export async function inspectTokenCapabilities(connection, input) {
+    const programId = input.tokenProgram === "token-2022"
+        ? SPL_TOKEN_2022_PROGRAM_ID
+        : SPL_TOKEN_PROGRAM_ID;
+    const mintAddress = publicKey(input.mint);
+    const commitment = input.commitment ?? "confirmed";
+    const [mint, source, recipient] = await Promise.all([
+        getMint(connection, mintAddress, commitment, programId),
+        getAccount(connection, publicKey(input.sourceTokenAccount), commitment, programId),
+        getAccount(connection, publicKey(input.recipientTokenAccount), commitment, programId),
+    ]);
+    const blockers = [];
+    const warnings = [];
+    if (!mint.isInitialized)
+        blockers.push("mint is not initialized");
+    if (!source.isInitialized)
+        blockers.push("source token account is not initialized");
+    if (!recipient.isInitialized)
+        blockers.push("recipient token account is not initialized");
+    if (!source.mint.equals(mintAddress))
+        blockers.push("source token account mint does not match payment mint");
+    if (!recipient.mint.equals(mintAddress))
+        blockers.push("recipient token account mint does not match payment mint");
+    if (source.isFrozen)
+        blockers.push("source token account is frozen");
+    if (recipient.isFrozen)
+        blockers.push("recipient token account is frozen");
+    const mintExtensions = input.tokenProgram === "token-2022" ? getExtensionTypes(mint.tlvData) : [];
+    const sourceExtensions = input.tokenProgram === "token-2022" ? getExtensionTypes(source.tlvData) : [];
+    const recipientExtensions = input.tokenProgram === "token-2022" ? getExtensionTypes(recipient.tlvData) : [];
+    let transferFee;
+    let transferHookProgram;
+    if (input.tokenProgram === "token-2022") {
+        blockers.push(...unexpectedExtensions(mintExtensions, KNOWN_MINT_EXTENSIONS, "mint"));
+        blockers.push(...unexpectedExtensions(sourceExtensions, KNOWN_ACCOUNT_EXTENSIONS, "source account"));
+        blockers.push(...unexpectedExtensions(recipientExtensions, KNOWN_ACCOUNT_EXTENSIONS, "recipient account"));
+        if (mintExtensions.includes(ExtensionType.NonTransferable)) {
+            blockers.push("mint is non-transferable");
+        }
+        if (sourceExtensions.includes(ExtensionType.NonTransferableAccount) || recipientExtensions.includes(ExtensionType.NonTransferableAccount)) {
+            blockers.push("payment uses a non-transferable token account");
+        }
+        const feeConfig = getTransferFeeConfig(mint);
+        if (feeConfig) {
+            const epoch = BigInt((await connection.getEpochInfo(commitment)).epoch);
+            const fee = getEpochFee(feeConfig, epoch);
+            transferFee = {
+                basisPoints: fee.transferFeeBasisPoints,
+                maximumFee: fee.maximumFee,
+            };
+            if (fee.transferFeeBasisPoints !== 0 || fee.maximumFee !== 0n) {
+                blockers.push("non-zero transfer fees require gross/net/withheld-fee receipt support");
+            }
+        }
+        const hook = getTransferHook(mint);
+        if (hook && !hook.programId.equals(PublicKey.default)) {
+            transferHookProgram = hook.programId.toBase58();
+            blockers.push("active transfer hook requires verified on-chain extra-account resolution and a Devnet-tested adapter");
+        }
+        const memo = getMemoTransfer(recipient);
+        if (memo?.requireIncomingTransferMemos) {
+            blockers.push("recipient requires an incoming memo, but the memo-aware settlement adapter is not enabled");
+        }
+        const cpiGuard = getCpiGuard(source);
+        if (cpiGuard?.lockCpi) {
+            blockers.push("source account CPI guard blocks the current Anchor delegate transfer path");
+        }
+        const pausable = getPausableConfig(mint);
+        if (pausable?.paused)
+            blockers.push("mint transfers are paused");
+        const defaultState = getDefaultAccountState(mint);
+        if (defaultState?.state === AccountState.Frozen) {
+            warnings.push("mint defaults new token accounts to frozen; current source and recipient were checked individually");
+        }
+        if (mintExtensions.includes(ExtensionType.ConfidentialTransferMint)) {
+            warnings.push("confidential extension is present; ChainPay uses only the transparent transfer_checked balance path");
+        }
+    }
+    return {
+        mint: mint.address.toBase58(),
+        tokenProgram: input.tokenProgram,
+        compatible: blockers.length === 0,
+        mintExtensions: mintExtensions.map(extensionName),
+        sourceAccountExtensions: sourceExtensions.map(extensionName),
+        recipientAccountExtensions: recipientExtensions.map(extensionName),
+        blockers,
+        warnings,
+        ...(transferFee ? { transferFee } : {}),
+        ...(transferHookProgram ? { transferHookProgram } : {}),
+    };
+}

package/dist/token.d.ts

@@ -0,0 +1,18 @@
+import type { Address, ChainPayInstruction, PaymentPreflightContext, TokenProgram } from "./types.js";
+export declare function deriveAssociatedTokenAddress(owner: Address, mint: Address, tokenProgram: TokenProgram): Address;
+export declare function buildCreateAssociatedTokenAccountInstruction(input: {
+    payer: Address;
+    owner: Address;
+    mint: Address;
+    tokenProgram: TokenProgram;
+}): ChainPayInstruction;
+export declare function associatedTokenProgramAddress(): Address;
+export type TokenAccountFields = {
+    mint: Address;
+    owner: Address;
+    balance: bigint;
+    delegate: Address | null;
+    delegatedAmount: bigint;
+};
+export declare function readTokenAccountFields(data: Uint8Array | Buffer): TokenAccountFields | null;
+export declare function paymentPreflightContextFromTokenAccount(data: Uint8Array | Buffer): PaymentPreflightContext | null;