@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/payment-request.d.ts

@@ -0,0 +1,37 @@
+import type { PaymentReceipt, PaymentRequestPayload, PaymentRequestVerification, SignedPaymentRequest } from "./types.js";
+/** Bounds for the optional "what was bought" fields. The relay enforces the same. */
+export declare const MAX_PAYMENT_REQUEST_DESCRIPTION_LENGTH = 280;
+export declare const MAX_PAYMENT_REQUEST_LINE_ITEMS = 20;
+export declare const MAX_PAYMENT_REQUEST_LINE_ITEM_LABEL_LENGTH = 120;
+/**
+ * Check the optional description and line items. Returns a reason when they
+ * are out of bounds, otherwise undefined.
+ */
+export declare function paymentRequestPurposeError(payload: PaymentRequestPayload): string | undefined;
+export declare function canonicalPaymentRequest(payload: PaymentRequestPayload): string;
+export declare function verifyPaymentRequest(request: SignedPaymentRequest, currentSlot?: bigint): Promise<PaymentRequestVerification>;
+export declare function paymentRequestTokenProgramAddress(request: PaymentRequestPayload): string;
+export type ReceiptPurchaseMismatch = "amount" | "mint" | "recipient";
+export type ReceiptPurchaseVerification = {
+    /** Merchant signature is valid and the request hashes to the receipt's invoice hash. */
+    valid: boolean;
+    /** `valid`, and the receipt paid the amount, mint, and recipient the request named. */
+    matched: boolean;
+    signatureValid: boolean;
+    hashMatches: boolean;
+    /** Fields the receipt paid differently from the request. Empty when matched. */
+    mismatches: ReceiptPurchaseMismatch[];
+    payload: PaymentRequestPayload;
+    invoiceHash: Uint8Array;
+    reason?: string;
+};
+/**
+ * Check that a merchant-signed request is the one a settled receipt paid:
+ * the signature verifies, and sha256 of its canonical form equals the
+ * receipt's invoice hash. Request expiry is not enforced, because a request
+ * that has since expired is still the request that was paid.
+ *
+ * The program binds the invoice hash, not the request's amount, mint, or
+ * recipient, so those are compared too and reported as mismatches.
+ */
+export declare function verifyReceiptPurchase(receipt: Pick<PaymentReceipt, "invoiceHash" | "amount" | "mint" | "recipientTokenAccount">, signedRequest: SignedPaymentRequest): Promise<ReceiptPurchaseVerification>;

package/dist/payment-request.js

@@ -0,0 +1,218 @@
+import { PublicKey } from "@solana/web3.js";
+import { address, tokenProgramAddress } from "./encoding.js";
+const MAX_U64 = 18446744073709551615n;
+/** Bounds for the optional "what was bought" fields. The relay enforces the same. */
+export const MAX_PAYMENT_REQUEST_DESCRIPTION_LENGTH = 280;
+export const MAX_PAYMENT_REQUEST_LINE_ITEMS = 20;
+export const MAX_PAYMENT_REQUEST_LINE_ITEM_LABEL_LENGTH = 120;
+const MAX_QUANTITY_LENGTH = 32;
+function orderedLineItem(item) {
+    // Canonical order is label, amount, quantity; absent fields are omitted.
+    if (!item || typeof item !== "object")
+        return item;
+    return {
+        label: item.label,
+        ...(item.amount === undefined ? {} : { amount: item.amount }),
+        ...(item.quantity === undefined ? {} : { quantity: item.quantity }),
+    };
+}
+function orderedPayload(payload) {
+    return {
+        version: 1,
+        cluster: payload.cluster,
+        merchant: address(payload.merchant),
+        invoice: payload.invoice,
+        mint: address(payload.mint),
+        tokenProgram: payload.tokenProgram,
+        recipient: address(payload.recipient),
+        amount: payload.amount,
+        decimals: payload.decimals,
+        nonce: payload.nonce,
+        ...(payload.expiresAtSlot === undefined ? {} : { expiresAtSlot: payload.expiresAtSlot }),
+        ...(payload.resource === undefined ? {} : { resource: payload.resource }),
+        // Included only when present, after resource, so a request without them
+        // keeps the exact canonical bytes and invoice hash it always had.
+        ...(payload.description === undefined ? {} : { description: payload.description }),
+        ...(payload.lineItems === undefined
+            ? {}
+            : { lineItems: Array.isArray(payload.lineItems) ? payload.lineItems.map(orderedLineItem) : payload.lineItems }),
+    };
+}
+/** Length in Unicode code points, the unit the relay counts in. */
+function codePoints(value) {
+    return Array.from(value).length;
+}
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+/**
+ * Check the optional description and line items. Returns a reason when they
+ * are out of bounds, otherwise undefined.
+ */
+export function paymentRequestPurposeError(payload) {
+    if (payload.description !== undefined) {
+        const description = payload.description;
+        if (typeof description !== "string"
+            || !description.trim()
+            || codePoints(description) > MAX_PAYMENT_REQUEST_DESCRIPTION_LENGTH) {
+            return `Description must be 1 to ${MAX_PAYMENT_REQUEST_DESCRIPTION_LENGTH} characters`;
+        }
+        if (CONTROL_CHARACTER.test(description))
+            return "Description must be a single line of text";
+    }
+    if (payload.lineItems !== undefined) {
+        const items = payload.lineItems;
+        if (!Array.isArray(items) || items.length === 0 || items.length > MAX_PAYMENT_REQUEST_LINE_ITEMS) {
+            return `Line items must contain 1 to ${MAX_PAYMENT_REQUEST_LINE_ITEMS} items`;
+        }
+        for (const item of items) {
+            if (!item || typeof item !== "object")
+                return "Each line item must be an object";
+            if (typeof item.label !== "string"
+                || !item.label.trim()
+                || codePoints(item.label) > MAX_PAYMENT_REQUEST_LINE_ITEM_LABEL_LENGTH
+                || CONTROL_CHARACTER.test(item.label)) {
+                return `Each line item label must be one line of 1 to ${MAX_PAYMENT_REQUEST_LINE_ITEM_LABEL_LENGTH} characters`;
+            }
+            if (item.amount !== undefined) {
+                if (typeof item.amount !== "string" || !/^\d+$/.test(item.amount) || BigInt(item.amount) > MAX_U64) {
+                    return "Line item amount must be an unsigned integer string in base units";
+                }
+            }
+            if (item.quantity !== undefined) {
+                if (typeof item.quantity !== "string"
+                    || item.quantity.length > MAX_QUANTITY_LENGTH
+                    || !/^\d+(\.\d+)?$/.test(item.quantity)) {
+                    return "Line item quantity must be an unsigned decimal string";
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function canonicalPaymentRequest(payload) {
+    return JSON.stringify(orderedPayload(payload));
+}
+function base64Bytes(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(normalized);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+async function sha256(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", value.slice().buffer);
+    return new Uint8Array(digest);
+}
+function validationError(payload, reason) {
+    return { valid: false, payload, invoiceHash: new Uint8Array(32), reason };
+}
+export async function verifyPaymentRequest(request, currentSlot) {
+    if (request.payload.version !== 1)
+        return validationError(request.payload, "Unsupported payment request version");
+    const payload = orderedPayload(request.payload);
+    try {
+        if (payload.version !== 1)
+            return validationError(payload, "Unsupported payment request version");
+        if (payload.cluster !== "devnet" && payload.cluster !== "mainnet-beta") {
+            return validationError(payload, "Unsupported Solana cluster");
+        }
+        if (!payload.invoice.trim() || !payload.nonce.trim()) {
+            return validationError(payload, "Payment request invoice and nonce are required");
+        }
+        if (!/^\d+$/.test(payload.amount))
+            return validationError(payload, "Amount must be an unsigned integer string");
+        const amount = BigInt(payload.amount);
+        if (amount <= 0n || amount > MAX_U64)
+            return validationError(payload, "Amount must fit in u64 and be positive");
+        if (!Number.isInteger(payload.decimals) || payload.decimals < 0 || payload.decimals > 255) {
+            return validationError(payload, "Decimals must be between 0 and 255");
+        }
+        if (payload.tokenProgram !== "spl-token" && payload.tokenProgram !== "token-2022") {
+            return validationError(payload, "Unsupported token program");
+        }
+        address(payload.merchant);
+        address(payload.mint);
+        address(payload.recipient);
+        const purposeError = paymentRequestPurposeError(payload);
+        if (purposeError)
+            return validationError(payload, purposeError);
+        if (payload.expiresAtSlot !== undefined) {
+            if (!/^\d+$/.test(payload.expiresAtSlot))
+                return validationError(payload, "Expiry slot must be an unsigned integer");
+            if (currentSlot !== undefined && BigInt(payload.expiresAtSlot) <= currentSlot) {
+                return validationError(payload, "Payment request has expired");
+            }
+        }
+        const signature = base64Bytes(request.signature);
+        if (signature.length !== 64)
+            return validationError(payload, "Ed25519 signature must be 64 bytes");
+        const merchant = new PublicKey(payload.merchant).toBytes();
+        const key = await globalThis.crypto.subtle.importKey("raw", merchant.slice().buffer, { name: "Ed25519" }, false, ["verify"]);
+        const message = new TextEncoder().encode(canonicalPaymentRequest(payload));
+        const validSignature = await globalThis.crypto.subtle.verify("Ed25519", key, signature.slice().buffer, message.slice().buffer);
+        if (!validSignature)
+            return validationError(payload, "Payment request signature is invalid");
+        const invoiceHash = await sha256(message);
+        return { valid: true, payload, invoiceHash };
+    }
+    catch (error) {
+        return validationError(payload, error instanceof Error ? error.message : String(error));
+    }
+}
+export function paymentRequestTokenProgramAddress(request) {
+    return tokenProgramAddress(request.tokenProgram);
+}
+function bytesEqual(left, right) {
+    return left.length === right.length && left.every((byte, index) => byte === right[index]);
+}
+/**
+ * Check that a merchant-signed request is the one a settled receipt paid:
+ * the signature verifies, and sha256 of its canonical form equals the
+ * receipt's invoice hash. Request expiry is not enforced, because a request
+ * that has since expired is still the request that was paid.
+ *
+ * The program binds the invoice hash, not the request's amount, mint, or
+ * recipient, so those are compared too and reported as mismatches.
+ */
+export async function verifyReceiptPurchase(receipt, signedRequest) {
+    const verification = await verifyPaymentRequest(signedRequest);
+    const base = {
+        payload: verification.payload,
+        invoiceHash: verification.invoiceHash,
+        mismatches: [],
+    };
+    if (!verification.valid) {
+        return {
+            ...base,
+            valid: false,
+            matched: false,
+            signatureValid: false,
+            hashMatches: false,
+            reason: verification.reason,
+        };
+    }
+    if (!bytesEqual(verification.invoiceHash, receipt.invoiceHash)) {
+        return {
+            ...base,
+            valid: false,
+            matched: false,
+            signatureValid: true,
+            hashMatches: false,
+            reason: "This request is not the one this receipt paid: its hash differs from the receipt's invoice hash",
+        };
+    }
+    const payload = verification.payload;
+    const mismatches = [];
+    if (BigInt(payload.amount) !== receipt.amount)
+        mismatches.push("amount");
+    if (payload.mint !== receipt.mint)
+        mismatches.push("mint");
+    if (payload.recipient !== receipt.recipientTokenAccount)
+        mismatches.push("recipient");
+    return {
+        ...base,
+        valid: true,
+        matched: mismatches.length === 0,
+        signatureValid: true,
+        hashMatches: true,
+        mismatches,
+        ...(mismatches.length ? { reason: `The receipt paid a different ${mismatches.join(", ")} than the request named` } : {}),
+    };
+}

package/dist/payment.d.ts

@@ -0,0 +1,40 @@
+import type { Address, BatchPreflightEntry, ChainPayInstruction, Mandate, PaymentBatchPreflight, PaymentPreflight, PaymentPreflightContext, PaymentRequest, PreparedTransaction, TokenProgram } from "./types.js";
+export declare const DUPLICATE_INVOICE_MESSAGE = "This invoice was already paid. Nothing new was submitted.";
+/**
+ * The receipt for this mandate and invoice hash already exists, so the invoice
+ * was paid before. Raised before anything is built, signed, or sent. The
+ * program would refuse the payment anyway; this says why in plain words.
+ */
+export declare class DuplicateInvoiceError extends Error {
+    readonly code: "DuplicateInvoice";
+    readonly receiptAddress: Address;
+    constructor(receiptAddress: Address);
+}
+export declare function isDuplicateInvoiceError(error: unknown): error is DuplicateInvoiceError;
+/**
+ * True when a simulation or send error says the receipt account already
+ * exists ("Allocate: account ... already in use"). Matches only when the
+ * message names this payment's receipt, so an unrelated account collision is
+ * still reported as itself.
+ */
+export declare function isReceiptAlreadyInUse(message: string, receiptAddress: Address): boolean;
+export type PreparePaymentInput = {
+    mandate: Address;
+    invoiceHash: Uint8Array;
+    paymentId: Uint8Array;
+    signatureReference: Uint8Array;
+    mint: Address;
+    recipient: Address;
+    amount: bigint;
+    tokenProgram?: TokenProgram;
+};
+export declare function preparePayment(input: PreparePaymentInput): PaymentRequest;
+export declare function buildExecutePaymentInstruction(request: PaymentRequest, agent: Address, mandate: Mandate, programId?: Address): ChainPayInstruction;
+export declare function preflightPayment(request: PaymentRequest, mandate: Mandate, currentSlot: bigint, agent?: Address, receiptAlreadyExists?: boolean, sourceContext?: PaymentPreflightContext): PaymentPreflight;
+/**
+ * Run per-payment preflight plus cumulative batch checks grouped by mandate.
+ * Dashboard batch import uses the same cumulative rules when source context
+ * is supplied for each row.
+ */
+export declare function preflightPaymentBatch(entries: BatchPreflightEntry[], currentSlot: bigint): PaymentBatchPreflight;
+export declare function preparedPaymentTransaction(instructionData: ChainPayInstruction, agent: Address): PreparedTransaction;

package/dist/payment.js

@@ -0,0 +1,214 @@
+import { DEFAULT_PROGRAM_ID, SYSTEM_PROGRAM_ID } from "./constants.js";
+import { address, bytes32, encodePayment, instruction, meta, publicKey, tokenProgramAddress, } from "./encoding.js";
+import { deriveAssetAddress, deriveConfigAddress, deriveReceiptAddress } from "./pda.js";
+export const DUPLICATE_INVOICE_MESSAGE = "This invoice was already paid. Nothing new was submitted.";
+/**
+ * The receipt for this mandate and invoice hash already exists, so the invoice
+ * was paid before. Raised before anything is built, signed, or sent. The
+ * program would refuse the payment anyway; this says why in plain words.
+ */
+export class DuplicateInvoiceError extends Error {
+    code = "DuplicateInvoice";
+    receiptAddress;
+    constructor(receiptAddress) {
+        super(DUPLICATE_INVOICE_MESSAGE);
+        this.name = "DuplicateInvoiceError";
+        this.receiptAddress = receiptAddress;
+    }
+}
+export function isDuplicateInvoiceError(error) {
+    return error instanceof DuplicateInvoiceError
+        || (typeof error === "object" && error !== null && error.code === "DuplicateInvoice");
+}
+/**
+ * True when a simulation or send error says the receipt account already
+ * exists ("Allocate: account ... already in use"). Matches only when the
+ * message names this payment's receipt, so an unrelated account collision is
+ * still reported as itself.
+ */
+export function isReceiptAlreadyInUse(message, receiptAddress) {
+    return message.includes("already in use") && message.includes(receiptAddress);
+}
+export function preparePayment(input) {
+    publicKey(input.mandate);
+    publicKey(input.mint);
+    publicKey(input.recipient);
+    const untrustedRemainingAccounts = input.remainingAccounts;
+    if (untrustedRemainingAccounts?.length) {
+        throw new Error("Caller-supplied remainingAccounts are not accepted; ChainPay must resolve extension accounts from verified on-chain state");
+    }
+    bytes32(input.invoiceHash, "invoiceHash");
+    bytes32(input.paymentId, "paymentId");
+    bytes32(input.signatureReference, "signatureReference");
+    if (input.invoiceHash.length !== 32) {
+        throw new Error("invoiceHash must be 32 bytes");
+    }
+    if (input.paymentId.length !== 32) {
+        throw new Error("paymentId must be 32 bytes");
+    }
+    if (input.signatureReference.length !== 32) {
+        throw new Error("signatureReference must be 32 bytes");
+    }
+    if (input.amount <= 0n) {
+        throw new Error("amount must be positive");
+    }
+    return {
+        ...input,
+        invoiceHash: new Uint8Array(input.invoiceHash),
+        paymentId: new Uint8Array(input.paymentId),
+        signatureReference: new Uint8Array(input.signatureReference),
+    };
+}
+export function buildExecutePaymentInstruction(request, agent, mandate, programId = DEFAULT_PROGRAM_ID) {
+    publicKey(agent);
+    if (address(request.mandate) !== mandate.address) {
+        throw new Error("Payment request mandate does not match the loaded mandate");
+    }
+    const tokenProgram = request.tokenProgram ?? mandate.tokenProgram;
+    if (!tokenProgram) {
+        throw new Error("Token program is required to build an execute_payment instruction");
+    }
+    return instruction("execute_payment", programId, [
+        meta(deriveConfigAddress(programId)),
+        meta(deriveAssetAddress(mandate.allowedMint, programId)),
+        meta(mandate.address, true),
+        meta(deriveReceiptAddress(mandate.address, request.invoiceHash, programId), true),
+        meta(agent, true, true),
+        meta(request.mint),
+        meta(mandate.sourceTokenAccount, true),
+        meta(request.recipient, true),
+        meta(tokenProgramAddress(tokenProgram)),
+        meta(SYSTEM_PROGRAM_ID),
+    ], encodePayment(request));
+}
+function check(name, ok, message) {
+    return { name, ok, message };
+}
+function sourceAccountChecks(request, mandate, context) {
+    return [
+        check("source_owner", address(context.sourceOwner) === mandate.owner, address(context.sourceOwner) === mandate.owner
+            ? "Source token account owner matches the mandate owner"
+            : "Source token account owner does not match the mandate owner"),
+        check("source_balance", request.amount <= context.sourceBalance, request.amount <= context.sourceBalance
+            ? "Source token account balance covers this payment"
+            : "Source token account balance is insufficient for this payment"),
+        check("delegate_identity", context.delegate !== null && address(context.delegate) === mandate.address, context.delegate !== null && address(context.delegate) === mandate.address
+            ? "Source token account delegates spending authority to this mandate"
+            : "Source token account is not delegated to this mandate"),
+        check("delegated_amount", context.delegatedAmount > 0n && request.amount <= context.delegatedAmount, context.delegatedAmount > 0n && request.amount <= context.delegatedAmount
+            ? "Remaining delegated allowance covers this payment"
+            : context.delegatedAmount <= 0n
+                ? "Source token account has no remaining delegated allowance"
+                : "Payment exceeds the remaining delegated allowance"),
+    ];
+}
+export function preflightPayment(request, mandate, currentSlot, agent, receiptAlreadyExists = false, sourceContext) {
+    const checks = [
+        check("mandate_status", mandate.status === "active", mandate.status === "active"
+            ? "Mandate is active"
+            : `Mandate is ${mandate.status}`),
+        check("approved_agent", agent === undefined || address(agent) === mandate.approvedAgent, agent === undefined || address(agent) === mandate.approvedAgent
+            ? "Payment agent matches the mandate"
+            : "Payment agent does not match the mandate"),
+        check("mint", address(request.mint) === mandate.allowedMint, address(request.mint) === mandate.allowedMint
+            ? "Payment mint matches the mandate"
+            : "Payment mint does not match the mandate"),
+        check("recipient", address(request.recipient) !== SYSTEM_PROGRAM_ID, address(request.recipient) !== SYSTEM_PROGRAM_ID
+            ? "Payment recipient is specified for this request"
+            : "Payment recipient must be specified"),
+        check("amount_positive", request.amount > 0n, request.amount > 0n ? "Payment amount is positive" : "Payment amount must be positive"),
+        check("per_payment_limit", request.amount <= mandate.maxPerPayment, request.amount <= mandate.maxPerPayment
+            ? "Payment is within the per-payment limit"
+            : "Payment exceeds the per-payment limit"),
+        check("total_limit", request.amount >= 0n && mandate.amountSpent + request.amount <= mandate.totalLimit, request.amount >= 0n && mandate.amountSpent + request.amount <= mandate.totalLimit
+            ? "Payment is within the total spend limit"
+            : "Payment exceeds the total spend limit"),
+        check("payment_count_limit", mandate.maxPaymentCount === 0n || mandate.paymentCount + 1n <= mandate.maxPaymentCount, mandate.maxPaymentCount === 0n || mandate.paymentCount + 1n <= mandate.maxPaymentCount
+            ? "Payment is within the payment-count limit"
+            : "Payment exceeds the payment-count limit"),
+        check("cooldown", mandate.lastPaymentSlot === 0n || currentSlot >= mandate.lastPaymentSlot + mandate.cooldownSlots, mandate.lastPaymentSlot === 0n || currentSlot >= mandate.lastPaymentSlot + mandate.cooldownSlots
+            ? "Mandate cooldown has elapsed"
+            : "Mandate cooldown is still active"),
+        check("expiry", mandate.expiresAtSlot > currentSlot, mandate.expiresAtSlot > currentSlot ? "Mandate has not expired" : "Mandate has expired"),
+        check("invoice_hash", request.invoiceHash.some((byte) => byte !== 0), request.invoiceHash.some((byte) => byte !== 0)
+            ? "Invoice hash is non-zero"
+            : "Invoice hash must not be all zeroes"),
+        check("payment_id", request.paymentId.some((byte) => byte !== 0), request.paymentId.some((byte) => byte !== 0)
+            ? "Payment ID is non-zero"
+            : "Payment ID must not be all zeroes"),
+        check("signature_reference", request.signatureReference.some((byte) => byte !== 0), request.signatureReference.some((byte) => byte !== 0)
+            ? "Signature reference is non-zero"
+            : "Signature reference must not be all zeroes"),
+        check("duplicate_invoice", !receiptAlreadyExists, receiptAlreadyExists
+            ? "This invoice hash already has a receipt under the mandate"
+            : "No receipt exists for this invoice hash"),
+        check("token_program", request.tokenProgram === undefined ||
+            mandate.tokenProgram === undefined ||
+            request.tokenProgram === mandate.tokenProgram, request.tokenProgram === undefined ||
+            mandate.tokenProgram === undefined ||
+            request.tokenProgram === mandate.tokenProgram
+            ? "Token program matches the loaded mandate context"
+            : "Token program does not match the source token account"),
+        ...(sourceContext ? sourceAccountChecks(request, mandate, sourceContext) : []),
+    ];
+    return { valid: checks.every((item) => item.ok), currentSlot, checks };
+}
+function batchChecksForMandateGroup(group, mandate) {
+    const totalAmount = group.reduce((total, entry) => total + entry.request.amount, 0n);
+    const checks = [
+        check("batch_total_limit", mandate.amountSpent + totalAmount <= mandate.totalLimit, mandate.amountSpent + totalAmount <= mandate.totalLimit
+            ? "Batch total is within the mandate spending limit"
+            : "Together, these payments exceed the mandate total spending limit"),
+        check("batch_payment_count", mandate.maxPaymentCount === 0n || mandate.paymentCount + BigInt(group.length) <= mandate.maxPaymentCount, mandate.maxPaymentCount === 0n || mandate.paymentCount + BigInt(group.length) <= mandate.maxPaymentCount
+            ? "Batch size is within the mandate payment-count limit"
+            : "Together, these payments exceed the mandate payment-count limit"),
+        check("batch_cooldown", group.length <= 1 || mandate.cooldownSlots === 0n, group.length <= 1 || mandate.cooldownSlots === 0n
+            ? "Batch respects the mandate cooldown policy"
+            : "This mandate has a cooldown and can only settle once per atomic batch"),
+    ];
+    const context = group.find((entry) => entry.sourceContext)?.sourceContext;
+    if (context) {
+        checks.push(check("batch_source_balance", totalAmount <= context.sourceBalance, totalAmount <= context.sourceBalance
+            ? "Source token account balance covers the batch total"
+            : "Source token account balance is insufficient for the batch total"), check("batch_delegated_amount", context.delegatedAmount > 0n && totalAmount <= context.delegatedAmount, context.delegatedAmount > 0n && totalAmount <= context.delegatedAmount
+            ? "Remaining delegated allowance covers the batch total"
+            : context.delegatedAmount <= 0n
+                ? "Source token account has no remaining delegated allowance for this batch"
+                : "Batch total exceeds the remaining delegated allowance"));
+    }
+    return checks;
+}
+/**
+ * Run per-payment preflight plus cumulative batch checks grouped by mandate.
+ * Dashboard batch import uses the same cumulative rules when source context
+ * is supplied for each row.
+ */
+export function preflightPaymentBatch(entries, currentSlot) {
+    const preparedEntries = entries.map((entry) => ({
+        request: entry.request,
+        mandate: address(entry.mandate.address),
+        preflight: preflightPayment(entry.request, entry.mandate, currentSlot, entry.agent, entry.receiptAlreadyExists ?? false, entry.sourceContext),
+    }));
+    const groups = new Map();
+    for (const entry of entries) {
+        const key = address(entry.mandate.address);
+        const group = groups.get(key) ?? [];
+        group.push(entry);
+        groups.set(key, group);
+    }
+    const batchChecks = [...groups.values()].flatMap((group) => batchChecksForMandateGroup(group, group[0].mandate));
+    const valid = preparedEntries.every((entry) => entry.preflight.valid) && batchChecks.every((item) => item.ok);
+    return {
+        valid,
+        currentSlot,
+        entries: preparedEntries,
+        batchChecks,
+    };
+}
+export function preparedPaymentTransaction(instructionData, agent) {
+    return {
+        instructions: [instructionData],
+        requiredSigners: [agent],
+        feePayer: agent,
+    };
+}

package/dist/pda.d.ts

@@ -0,0 +1,13 @@
+import type { Address } from "./types.js";
+export declare function deriveConfigAddress(programId?: Address): Address;
+export declare function deriveLegacyMandateAddress(owner: Address, programId?: Address): Address;
+export declare function deriveMintMandateAddress(owner: Address, allowedMint: Address, programId?: Address): Address;
+export declare function deriveVersionedMandateAddress(owner: Address, allowedMint: Address, mandateNonce: Address, programId?: Address): Address;
+/**
+ * Derive a mandate address. Without a mint this returns the legacy
+ * owner-scoped address; with a mint it returns the production mint-scoped
+ * address used by new mandates.
+ */
+export declare function deriveMandateAddress(owner: Address, programId?: Address, allowedMint?: Address): Address;
+export declare function deriveReceiptAddress(mandate: Address, invoiceHash: Uint8Array, programId?: Address): Address;
+export declare function deriveAssetAddress(mint: Address, programId?: Address): Address;

package/dist/pda.js

@@ -0,0 +1,36 @@
+import { PublicKey } from "@solana/web3.js";
+import { CONFIG_SEED, ASSET_SEED, DEFAULT_PROGRAM_ID, MANDATE_SEED, RECEIPT_SEED, } from "./constants.js";
+import { bytes32, publicKey } from "./encoding.js";
+export function deriveConfigAddress(programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(CONFIG_SEED)], publicKey(programId))[0].toBase58();
+}
+export function deriveLegacyMandateAddress(owner, programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(MANDATE_SEED), publicKey(owner).toBytes()], publicKey(programId))[0].toBase58();
+}
+export function deriveMintMandateAddress(owner, allowedMint, programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(MANDATE_SEED), publicKey(owner).toBytes(), publicKey(allowedMint).toBytes()], publicKey(programId))[0].toBase58();
+}
+export function deriveVersionedMandateAddress(owner, allowedMint, mandateNonce, programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([
+        Buffer.from(MANDATE_SEED),
+        publicKey(owner).toBytes(),
+        publicKey(allowedMint).toBytes(),
+        publicKey(mandateNonce).toBytes(),
+    ], publicKey(programId))[0].toBase58();
+}
+/**
+ * Derive a mandate address. Without a mint this returns the legacy
+ * owner-scoped address; with a mint it returns the production mint-scoped
+ * address used by new mandates.
+ */
+export function deriveMandateAddress(owner, programId = DEFAULT_PROGRAM_ID, allowedMint) {
+    return allowedMint === undefined
+        ? deriveLegacyMandateAddress(owner, programId)
+        : deriveMintMandateAddress(owner, allowedMint, programId);
+}
+export function deriveReceiptAddress(mandate, invoiceHash, programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(RECEIPT_SEED), publicKey(mandate).toBytes(), bytes32(invoiceHash, "invoiceHash")], publicKey(programId))[0].toBase58();
+}
+export function deriveAssetAddress(mint, programId = DEFAULT_PROGRAM_ID) {
+    return PublicKey.findProgramAddressSync([Buffer.from(ASSET_SEED), publicKey(mint).toBytes()], publicKey(programId))[0].toBase58();
+}

package/dist/receipt-export.d.ts

@@ -0,0 +1,55 @@
+import type { PaymentReceipt, PaymentRequestPayload, ReceiptPolicy } from "./types.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 declare function receiptPolicy(receipt: Pick<PaymentReceipt, "policySnapshot">, relayObserved?: ReceiptPolicy | null): ReceiptPolicy;
+/**
+ * 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 declare function relayObservedPolicy(value: unknown): ReceiptPolicy | null;
+export declare function receiptExplorerUrl(receipt: Pick<PaymentReceipt, "address" | "transactionSignature">, cluster?: "devnet" | "mainnet-beta"): string;
+export type ReceiptCsvRow = {
+    receipt: PaymentReceipt;
+    /** Verified mint decimals. Null keeps amounts in labeled base units. */
+    decimals: number | null;
+    symbol?: string;
+    /** Unix seconds from getBlockTime for the executed slot. Null when unknown. */
+    blockTime?: number | null;
+    /** Defaults to the receipt's own snapshot, else "not-recorded". */
+    policy?: ReceiptPolicy;
+    /** From the merchant-signed request, only after verifyReceiptPurchase. */
+    purpose?: Partial<Pick<PaymentRequestPayload, "invoice" | "description" | "lineItems">>;
+    verifyUrl?: string;
+    explorerUrl?: string;
+    /** From the mandate request the owner accepted, when one is linked. */
+    poNumber?: string;
+    /**
+     * The Order match pill as the reader saw it ("Matched", "Payee differs",
+     * "No order", ...). Empty when it was not checked. A check, not a guarantee.
+     */
+    orderMatch?: string;
+};
+/**
+ * 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 declare const RECEIPT_CSV_HEADERS: readonly ["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"];
+/**
+ * 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 declare function csvCell(value: string): string;
+/**
+ * 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 declare function receiptsToCsv(rows: readonly ReceiptCsvRow[]): string;