@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/client.js

@@ -0,0 +1,493 @@
+import { Connection, } from "@solana/web3.js";
+import { DEFAULT_PROGRAM_ID, DEVNET_RPC_URL, RECEIPT_ACCOUNT_LENGTHS, SPL_TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, } from "./constants.js";
+import { decodeMandate, decodeProtocolConfig, decodeSupportedAsset } from "./accounts.js";
+import { address, publicKey, tokenProgramFromAddress, } from "./encoding.js";
+import { buildApproveDelegateInstruction, buildCreateMandateTransaction, buildInitializeConfigInstruction, buildPauseMandateInstruction, buildRevokeDelegateInstruction, buildRevokeMandateInstruction, buildRegisterAssetInstruction, buildSetAssetStatusInstruction, buildUpdateMandateInstruction, } from "./mandate.js";
+import { DUPLICATE_INVOICE_MESSAGE, DuplicateInvoiceError, buildExecutePaymentInstruction, isDuplicateInvoiceError, isReceiptAlreadyInUse, preflightPayment, preparePayment as preparePaymentRequest, preparedPaymentTransaction, } from "./payment.js";
+import { deriveAssetAddress, deriveConfigAddress, deriveReceiptAddress } from "./pda.js";
+import { buildCreateAssociatedTokenAccountInstruction, deriveAssociatedTokenAddress, paymentPreflightContextFromTokenAccount, readTokenAccountFields, } from "./token.js";
+import { amountDisplayFromMint, readCurrentMandateFields, readPaymentReceiptAccount, readPublicSettledReceipt, readVerifiedMintDecimals, } from "./receipt.js";
+import { inspectTokenCapabilities } from "./token-capabilities.js";
+export class ChainPayClient {
+    connection;
+    programId;
+    commitment;
+    constructor(options = {}) {
+        if (options instanceof Connection) {
+            this.connection = options;
+            this.programId = DEFAULT_PROGRAM_ID;
+            this.commitment = "confirmed";
+            return;
+        }
+        this.connection = new Connection(options.rpcUrl ?? DEVNET_RPC_URL, options.commitment ?? "confirmed");
+        this.programId = address(options.programId ?? DEFAULT_PROGRAM_ID);
+        this.commitment = options.commitment ?? "confirmed";
+    }
+    async getCurrentSlot() {
+        return BigInt(await this.connection.getSlot(this.commitment));
+    }
+    async getConfig() {
+        const account = await this.getProgramAccount(deriveConfigAddress(this.programId));
+        return account ? decodeProtocolConfig(account.data, account.address) : null;
+    }
+    async getMandateCreationMetadata(mandateAddress) {
+        try {
+            let before;
+            let oldest;
+            // Signatures are returned newest first. Walk pages so updates and
+            // payments do not make the creation time look newer than it is.
+            const historyCommitment = this.commitment === "finalized" ? "finalized" : "confirmed";
+            for (let page = 0; page < 100; page += 1) {
+                const options = { limit: 100 };
+                if (before)
+                    options.before = before;
+                const signatures = await this.connection.getSignaturesForAddress(publicKey(mandateAddress), options, historyCommitment);
+                if (signatures.length === 0)
+                    break;
+                oldest = signatures[signatures.length - 1];
+                if (signatures.length < 100)
+                    break;
+                before = oldest.signature;
+            }
+            if (!oldest)
+                return {};
+            return {
+                ...(oldest.blockTime === null ? {} : { createdAt: oldest.blockTime }),
+                createdAtSlot: BigInt(oldest.slot),
+            };
+        }
+        catch {
+            // History is display metadata only. A temporary history RPC failure
+            // must not hide a valid mandate or block payment preparation.
+            return {};
+        }
+    }
+    async getMandate(mandateAddress) {
+        const currentSlot = await this.getCurrentSlot();
+        const account = await this.getProgramAccount(mandateAddress);
+        if (!account)
+            return null;
+        const decoded = decodeMandate(account.data, account.address, currentSlot);
+        const source = await this.connection.getAccountInfo(publicKey(decoded.sourceTokenAccount), this.commitment);
+        const tokenProgram = source ? tokenProgramFromAddress(source.owner.toBase58()) : undefined;
+        const creation = await this.getMandateCreationMetadata(decoded.address);
+        return { ...decoded, tokenProgram, ...creation };
+    }
+    async getMandatesByOwner(owner) {
+        const currentSlot = await this.getCurrentSlot();
+        const accounts = await this.connection.getProgramAccounts(publicKey(this.programId), {
+            commitment: this.commitment,
+            filters: [
+                { dataSize: 235 },
+                { memcmp: { offset: 8, bytes: owner } },
+            ],
+        });
+        const sourceAccounts = new Map();
+        return Promise.all(accounts.map(async (account) => {
+            const address = account.pubkey.toBase58();
+            const decoded = decodeMandate(new Uint8Array(account.account.data), address, currentSlot);
+            let sourceRequest = sourceAccounts.get(decoded.sourceTokenAccount);
+            if (!sourceRequest) {
+                sourceRequest = this.connection.getAccountInfo(publicKey(decoded.sourceTokenAccount), this.commitment);
+                sourceAccounts.set(decoded.sourceTokenAccount, sourceRequest);
+            }
+            const source = await sourceRequest;
+            const tokenProgram = source ? tokenProgramFromAddress(source.owner.toBase58()) : undefined;
+            const creation = await this.getMandateCreationMetadata(decoded.address);
+            return { ...decoded, tokenProgram, ...creation };
+        }));
+    }
+    async getSupportedAsset(mint) {
+        const assetAddress = deriveAssetAddress(mint, this.programId);
+        const account = await this.getProgramAccount(assetAddress);
+        return account ? decodeSupportedAsset(account.data, account.address) : null;
+    }
+    async getSupportedAssets() {
+        const accounts = await this.connection.getProgramAccounts(publicKey(this.programId), {
+            commitment: this.commitment,
+            filters: [{ dataSize: 106 }],
+        });
+        return accounts
+            .map((account) => decodeSupportedAsset(new Uint8Array(account.account.data), account.pubkey.toBase58()))
+            .sort((left, right) => left.mint.localeCompare(right.mint));
+    }
+    /**
+     * Inspect the canonical token account for one enabled registry asset and,
+     * when absent, return an unsigned creation transaction for wallet review.
+     */
+    async prepareAssociatedTokenAccount(input) {
+        const mint = address(input.mint);
+        const asset = await this.getSupportedAsset(mint);
+        if (!asset || !asset.enabled) {
+            throw new Error(`Asset is not enabled in the ChainPay registry: ${mint}`);
+        }
+        return this.prepareAssociatedTokenAccountForAsset(asset, input.owner, input.payer);
+    }
+    /** Inspect every enabled registry asset. Disabled assets are intentionally excluded. */
+    async prepareRegisteredAssetTokenAccounts(owner, payer) {
+        const assets = (await this.getSupportedAssets()).filter((asset) => asset.enabled);
+        return Promise.all(assets.map((asset) => (this.prepareAssociatedTokenAccountForAsset(asset, owner, payer))));
+    }
+    async prepareAssociatedTokenAccountForAsset(asset, ownerInput, payerInput) {
+        const owner = address(ownerInput);
+        const payer = address(payerInput ?? owner);
+        const mint = address(asset.mint);
+        const tokenProgram = tokenProgramFromAddress(asset.tokenProgram);
+        if (!tokenProgram) {
+            throw new Error(`Registry asset uses an unsupported token program: ${asset.tokenProgram}`);
+        }
+        const mintAccount = await this.connection.getAccountInfo(publicKey(mint), this.commitment);
+        if (!mintAccount)
+            throw new Error(`Mint account not found: ${mint}`);
+        const mintProgram = tokenProgramFromAddress(mintAccount.owner.toBase58());
+        if (!mintProgram) {
+            throw new Error(`Mint is not owned by a supported token program: ${mintAccount.owner.toBase58()}`);
+        }
+        const verifiedMint = readVerifiedMintDecimals({
+            owner: mintAccount.owner.toBase58(),
+            data: new Uint8Array(mintAccount.data),
+        });
+        if (!verifiedMint.ok)
+            throw new Error(`Mint account data is invalid: ${mint}`);
+        if (mintProgram !== tokenProgram) {
+            throw new Error(`Registry token program does not match mint owner for ${mint}`);
+        }
+        const associatedTokenAccount = deriveAssociatedTokenAddress(owner, mint, tokenProgram);
+        const existing = await this.connection.getAccountInfo(publicKey(associatedTokenAccount), this.commitment);
+        const base = {
+            asset,
+            address: associatedTokenAccount,
+            owner,
+            mint,
+            tokenProgram,
+        };
+        if (existing) {
+            if (existing.owner.toBase58() !== asset.tokenProgram) {
+                throw new Error(`Canonical token account is owned by an unexpected program: ${associatedTokenAccount}`);
+            }
+            const fields = readTokenAccountFields(new Uint8Array(existing.data));
+            if (!fields || fields.owner !== owner || fields.mint !== mint) {
+                throw new Error(`Canonical token account data is invalid: ${associatedTokenAccount}`);
+            }
+            return { ...base, status: "ready" };
+        }
+        return {
+            ...base,
+            status: "missing",
+            transaction: {
+                instructions: [buildCreateAssociatedTokenAccountInstruction({
+                        payer,
+                        owner,
+                        mint,
+                        tokenProgram,
+                    })],
+                requiredSigners: [payer],
+                feePayer: payer,
+            },
+        };
+    }
+    async getPayment(lookup) {
+        const receiptAddress = typeof lookup === "string"
+            ? address(lookup)
+            : deriveReceiptAddress(lookup.mandate, lookup.invoiceHash, this.programId);
+        const account = await this.getProgramAccount(receiptAddress);
+        if (!account)
+            return null;
+        const result = readPaymentReceiptAccount({ address: account.address, owner: this.programId, data: account.data }, { programId: this.programId, requireSettled: false });
+        if (!result.valid)
+            throw new Error(result.reason);
+        return result.receipt;
+    }
+    /**
+     * Current mandate account fields only. Does not page creation history or
+     * load source token metadata. Public verify uses this for optional
+     * enrichment; failure must not invalidate a settled receipt.
+     */
+    async getCurrentMandateFields(mandateAddress) {
+        const currentSlot = await this.getCurrentSlot();
+        try {
+            const account = await this.getProgramAccount(mandateAddress);
+            return readCurrentMandateFields(account ? { address: account.address, owner: this.programId, data: account.data } : null, { programId: this.programId, currentSlot, expectedAddress: mandateAddress });
+        }
+        catch (error) {
+            return {
+                status: "unavailable",
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async getVerifiedSettledPayment(receiptAddress) {
+        const normalized = address(receiptAddress);
+        const info = await this.connection.getAccountInfo(publicKey(normalized), this.commitment);
+        if (!info) {
+            return { valid: false, code: "not_found", reason: "Receipt account not found" };
+        }
+        return readPublicSettledReceipt({ address: normalized, owner: info.owner.toBase58(), data: new Uint8Array(info.data) }, { programId: this.programId });
+    }
+    async readPublicReceipt(receiptAddress) {
+        const receipt = await this.getVerifiedSettledPayment(receiptAddress);
+        if (!receipt.valid) {
+            return { receipt, amount: null, currentMandate: { status: "absent" } };
+        }
+        let mintAccount = null;
+        try {
+            const mintInfo = await this.connection.getAccountInfo(publicKey(receipt.receipt.mint), this.commitment);
+            if (mintInfo) {
+                mintAccount = { owner: mintInfo.owner.toBase58(), data: new Uint8Array(mintInfo.data) };
+            }
+        }
+        catch {
+            mintAccount = null;
+        }
+        let currentMandate = { status: "absent" };
+        try {
+            currentMandate = await this.getCurrentMandateFields(receipt.receipt.mandate);
+        }
+        catch (error) {
+            currentMandate = {
+                status: "unavailable",
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+        return {
+            receipt,
+            amount: amountDisplayFromMint(receipt.receipt.amount, mintAccount),
+            currentMandate,
+        };
+    }
+    async getPaymentsByMandate(mandateAddress) {
+        const mandate = address(mandateAddress);
+        // RPC filters match one exact size, and original and snapshot receipts
+        // coexist after the program upgrade. Ask for each size; a query that
+        // asked for only one would silently drop the other half of the history.
+        const pages = await Promise.all(RECEIPT_ACCOUNT_LENGTHS.map((dataSize) => (this.connection.getProgramAccounts(publicKey(this.programId), {
+            commitment: this.commitment,
+            filters: [
+                { dataSize },
+                { memcmp: { offset: 8, bytes: mandate } },
+            ],
+        }))));
+        const seen = new Set();
+        const accounts = pages.flat().filter((account) => {
+            const key = account.pubkey.toBase58();
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        const historyCommitment = this.commitment === "finalized" ? "finalized" : "confirmed";
+        const receipts = await Promise.all(accounts.map(async (account) => {
+            let transactionSignature;
+            try {
+                const history = await this.connection.getSignaturesForAddress(account.pubkey, { limit: 1 }, historyCommitment);
+                transactionSignature = history[0]?.signature;
+            }
+            catch {
+                // The receipt itself remains verifiable if transaction history is
+                // temporarily unavailable. The dashboard can retry enrichment.
+            }
+            const result = readPaymentReceiptAccount({
+                address: account.pubkey.toBase58(),
+                owner: account.account.owner.toBase58(),
+                data: new Uint8Array(account.account.data),
+            }, { programId: this.programId, requireSettled: false, transactionSignature });
+            // The getProgramAccounts filter is dataSize plus a memcmp on the mandate;
+            // it does not check the receipt discriminator. Any program-owned account of
+            // a receipt size matching those bytes lands here, and a partially initialized or
+            // future account type would otherwise reject the whole Promise.all and
+            // empty an owner's entire history. Skip the row, keep the rest.
+            return result.valid ? result.receipt : null;
+        }));
+        return receipts.filter((receipt) => receipt !== null).sort((left, right) => (left.executedAtSlot === right.executedAtSlot
+            ? right.address.localeCompare(left.address)
+            : left.executedAtSlot > right.executedAtSlot ? -1 : 1));
+    }
+    async getTokenProgram(accountAddress) {
+        const account = await this.connection.getAccountInfo(publicKey(accountAddress), this.commitment);
+        if (!account)
+            throw new Error(`Token account not found: ${accountAddress}`);
+        const tokenProgram = tokenProgramFromAddress(account.owner.toBase58());
+        if (!tokenProgram)
+            throw new Error(`Unsupported token program: ${account.owner.toBase58()}`);
+        return tokenProgram;
+    }
+    async getMintDecimals(mint) {
+        const account = await this.connection.getAccountInfo(publicKey(mint), this.commitment);
+        if (!account)
+            throw new Error(`Mint account not found: ${mint}`);
+        const decimals = readVerifiedMintDecimals({
+            owner: account.owner.toBase58(),
+            data: new Uint8Array(account.data),
+        });
+        if (!decimals.ok && decimals.reason === "unsupported_owner") {
+            throw new Error(`Mint is not owned by a supported token program: ${account.owner.toBase58()}`);
+        }
+        if (!decimals.ok)
+            throw new Error("Mint account data is truncated");
+        return decimals.decimals;
+    }
+    async buildCreateMandate(input, owner) {
+        const mintProgram = await this.getTokenProgram(input.allowedMint);
+        if (mintProgram !== input.tokenProgram) {
+            throw new Error(`Mint token program is ${mintProgram}, but mandate requested ${input.tokenProgram}`);
+        }
+        const sourceProgram = await this.getTokenProgram(input.sourceTokenAccount);
+        if (sourceProgram !== input.tokenProgram) {
+            throw new Error(`Source token account uses ${sourceProgram}, but mandate requested ${input.tokenProgram}`);
+        }
+        const decimals = await this.getMintDecimals(input.allowedMint);
+        return buildCreateMandateTransaction(input, owner, this.programId, decimals);
+    }
+    buildInitializeConfig(supportedMints, authority) {
+        return {
+            instructions: [buildInitializeConfigInstruction(supportedMints, authority, this.programId)],
+            requiredSigners: [authority],
+            feePayer: authority,
+        };
+    }
+    buildUpdateMandate(input, owner, mandateAddress) {
+        return {
+            instructions: [buildUpdateMandateInstruction(input, owner, this.programId, mandateAddress)],
+            requiredSigners: [owner],
+            feePayer: owner,
+        };
+    }
+    buildRegisterAsset(mint, tokenProgram, authority) {
+        return {
+            instructions: [buildRegisterAssetInstruction({ mint, tokenProgram }, authority, this.programId)],
+            requiredSigners: [authority],
+            feePayer: authority,
+        };
+    }
+    buildSetAssetStatus(mint, authority, enabled) {
+        return {
+            instructions: [buildSetAssetStatusInstruction(mint, authority, enabled, this.programId)],
+            requiredSigners: [authority],
+            feePayer: authority,
+        };
+    }
+    buildPauseMandate(owner, mandateAddress) {
+        return {
+            instructions: [buildPauseMandateInstruction(owner, this.programId, mandateAddress)],
+            requiredSigners: [owner],
+            feePayer: owner,
+        };
+    }
+    buildRevokeMandate(owner, mandateAddress) {
+        return {
+            instructions: [buildRevokeMandateInstruction(owner, this.programId, mandateAddress)],
+            requiredSigners: [owner],
+            feePayer: owner,
+        };
+    }
+    buildRevokeDelegate(sourceTokenAccount, owner, tokenProgram) {
+        return {
+            instructions: [buildRevokeDelegateInstruction(sourceTokenAccount, owner, tokenProgram)],
+            requiredSigners: [owner],
+            feePayer: owner,
+        };
+    }
+    buildApproveDelegate(input) {
+        return {
+            instructions: [buildApproveDelegateInstruction(input)],
+            requiredSigners: [input.owner],
+            feePayer: input.owner,
+        };
+    }
+    async preparePayment(input, agent) {
+        const mandate = await this.getMandate(input.mandate);
+        if (!mandate)
+            throw new Error(`Mandate not found: ${input.mandate}`);
+        const tokenProgram = input.tokenProgram ?? mandate.tokenProgram ?? await this.getTokenProgram(mandate.sourceTokenAccount);
+        const untrustedRemainingAccounts = input.remainingAccounts;
+        if (untrustedRemainingAccounts?.length) {
+            throw new Error("Caller-supplied remainingAccounts are not accepted; extension accounts must be resolved from verified on-chain state");
+        }
+        const request = preparePaymentRequest({ ...input, tokenProgram });
+        const receiptAddress = deriveReceiptAddress(mandate.address, request.invoiceHash, this.programId);
+        // The receipt PDA is derived from mandate and invoice hash, so an existing
+        // account means this invoice is already paid. Stop before building anything.
+        const existingReceipt = await this.getPayment(receiptAddress);
+        if (existingReceipt !== null)
+            throw new DuplicateInvoiceError(receiptAddress);
+        const asset = await this.getSupportedAsset(input.mint);
+        const expectedProgram = tokenProgram === "token-2022" ? TOKEN_2022_PROGRAM_ID : SPL_TOKEN_PROGRAM_ID;
+        if (!asset || !asset.enabled) {
+            throw new Error("Payment mint is not enabled in the ChainPay SupportedAsset registry");
+        }
+        if (asset.mint !== input.mint || asset.tokenProgram !== expectedProgram) {
+            throw new Error("SupportedAsset mint or token program does not match the payment request");
+        }
+        const capabilityProfile = await inspectTokenCapabilities(this.connection, {
+            mint: input.mint,
+            sourceTokenAccount: mandate.sourceTokenAccount,
+            recipientTokenAccount: input.recipient,
+            tokenProgram,
+            commitment: this.commitment,
+        });
+        if (!capabilityProfile.compatible) {
+            throw new Error(`Token capability check failed: ${capabilityProfile.blockers.join("; ")}`);
+        }
+        const currentSlot = await this.getCurrentSlot();
+        const executionAgent = agent ?? mandate.approvedAgent;
+        const sourceAccountInfo = await this.connection.getAccountInfo(publicKey(mandate.sourceTokenAccount), this.commitment);
+        const sourceContext = sourceAccountInfo
+            ? paymentPreflightContextFromTokenAccount(new Uint8Array(sourceAccountInfo.data))
+            : undefined;
+        const preflight = preflightPayment(request, mandate, currentSlot, executionAgent, false, sourceContext ?? undefined);
+        const instruction = buildExecutePaymentInstruction(request, executionAgent, mandate, this.programId);
+        return {
+            request,
+            mandate,
+            receiptAddress,
+            instruction,
+            transaction: preparedPaymentTransaction(instruction, executionAgent),
+            preflight,
+            capabilityProfile,
+        };
+    }
+    async executePayment(prepared, adapter) {
+        try {
+            const submission = await adapter.submit(prepared.transaction);
+            let status = submission.status ?? "submitted";
+            let slot = submission.slot;
+            if (adapter.confirm) {
+                const confirmation = await adapter.confirm(submission.signature);
+                status = "confirmed";
+                slot = confirmation.slot ?? slot;
+            }
+            return {
+                status,
+                receiptAddress: prepared.receiptAddress,
+                signature: submission.signature,
+                slot,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isDuplicateInvoiceError(error) || isReceiptAlreadyInUse(message, prepared.receiptAddress)) {
+                return {
+                    status: "failed",
+                    receiptAddress: prepared.receiptAddress,
+                    code: "DuplicateInvoice",
+                    error: DUPLICATE_INVOICE_MESSAGE,
+                };
+            }
+            return {
+                status: "failed",
+                receiptAddress: prepared.receiptAddress,
+                error: message,
+            };
+        }
+    }
+    async getProgramAccount(accountAddress) {
+        const normalized = address(accountAddress);
+        const info = await this.connection.getAccountInfo(publicKey(normalized), this.commitment);
+        if (!info)
+            return null;
+        if (info.owner.toBase58() !== this.programId) {
+            throw new Error(`Account ${normalized} is not owned by ChainPay program`);
+        }
+        return { address: normalized, data: new Uint8Array(info.data) };
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,44 @@
+import type { Address } from "./types.js";
+export declare const DEFAULT_PROGRAM_ID: Address;
+export declare const DEVNET_RPC_URL = "https://api.devnet.solana.com";
+export declare const SYSTEM_PROGRAM_ID: Address;
+export declare const SPL_TOKEN_PROGRAM_ID: Address;
+export declare const TOKEN_2022_PROGRAM_ID: Address;
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID: Address;
+/** SPL Memo v2. Accepts a memo with no signer accounts. */
+export declare const MEMO_PROGRAM_ID: Address;
+export declare const DISCRIMINATORS: {
+    readonly initializeConfig: Uint8Array<ArrayBuffer>;
+    readonly createMandate: Uint8Array<ArrayBuffer>;
+    readonly executePayment: Uint8Array<ArrayBuffer>;
+    readonly pauseMandate: Uint8Array<ArrayBuffer>;
+    readonly revokeMandate: Uint8Array<ArrayBuffer>;
+    readonly updateMandate: Uint8Array<ArrayBuffer>;
+    readonly registerAsset: Uint8Array<ArrayBuffer>;
+    readonly setAssetStatus: Uint8Array<ArrayBuffer>;
+    readonly approveChecked: Uint8Array<ArrayBuffer>;
+    readonly revokeDelegate: Uint8Array<ArrayBuffer>;
+};
+export declare const ACCOUNT_DISCRIMINATORS: {
+    readonly protocolConfig: Uint8Array<ArrayBuffer>;
+    readonly supportedAsset: Uint8Array<ArrayBuffer>;
+    readonly paymentMandate: Uint8Array<ArrayBuffer>;
+    readonly paymentReceipt: Uint8Array<ArrayBuffer>;
+};
+export declare const MANDATE_SEED = "mandate";
+export declare const MANDATE_NONCE_PREFIX: Uint8Array<ArrayBuffer>;
+export declare const CONFIG_SEED = "config";
+export declare const RECEIPT_SEED = "receipt";
+export declare const ASSET_SEED = "asset";
+export declare const RECEIPT_STATUS_SETTLED = 1;
+/** Original PaymentReceipt account size. Still the minimum any reader accepts. */
+export declare const RECEIPT_ACCOUNT_LENGTH = 282;
+/**
+ * PaymentReceipt with the policy snapshot appended after `bump`. Offsets of
+ * every original field are unchanged, so a v2 receipt is a v1 receipt plus a
+ * tail. Both sizes exist on chain at once after the program upgrade.
+ */
+export declare const RECEIPT_ACCOUNT_LENGTH_V2 = 371;
+/** Every receipt account size a discovery query must ask for. */
+export declare const RECEIPT_ACCOUNT_LENGTHS: readonly [282, 371];
+export declare const MANDATE_ACCOUNT_LENGTH = 235;

package/dist/constants.js

@@ -0,0 +1,43 @@
+export const DEFAULT_PROGRAM_ID = "3H9TV1EPR2BAQgVmcMqpufiZKPXbAMnjHp13LA9Lndv4";
+export const DEVNET_RPC_URL = "https://api.devnet.solana.com";
+export const SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
+export const SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export const TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+export const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+/** SPL Memo v2. Accepts a memo with no signer accounts. */
+export const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+export const DISCRIMINATORS = {
+    initializeConfig: Uint8Array.from([208, 127, 21, 1, 194, 190, 196, 70]),
+    createMandate: Uint8Array.from([230, 170, 158, 68, 33, 169, 16, 158]),
+    executePayment: Uint8Array.from([86, 4, 7, 7, 120, 139, 232, 139]),
+    pauseMandate: Uint8Array.from([192, 108, 97, 124, 56, 229, 236, 3]),
+    revokeMandate: Uint8Array.from([252, 97, 140, 119, 67, 43, 177, 108]),
+    updateMandate: Uint8Array.from([69, 131, 248, 29, 105, 50, 139, 30]),
+    registerAsset: Uint8Array.from([21, 80, 155, 149, 117, 207, 235, 16]),
+    setAssetStatus: Uint8Array.from([58, 54, 181, 102, 68, 238, 240, 245]),
+    approveChecked: Uint8Array.from([13]),
+    revokeDelegate: Uint8Array.from([5]),
+};
+export const ACCOUNT_DISCRIMINATORS = {
+    protocolConfig: Uint8Array.from([207, 91, 250, 28, 152, 179, 215, 209]),
+    supportedAsset: Uint8Array.from([129, 27, 96, 192, 89, 180, 227, 200]),
+    paymentMandate: Uint8Array.from([139, 106, 43, 122, 82, 211, 96, 162]),
+    paymentReceipt: Uint8Array.from([168, 198, 209, 4, 60, 235, 126, 109]),
+};
+export const MANDATE_SEED = "mandate";
+export const MANDATE_NONCE_PREFIX = Uint8Array.from([67, 80, 78, 79, 78, 67, 69, 33]);
+export const CONFIG_SEED = "config";
+export const RECEIPT_SEED = "receipt";
+export const ASSET_SEED = "asset";
+export const RECEIPT_STATUS_SETTLED = 1;
+/** Original PaymentReceipt account size. Still the minimum any reader accepts. */
+export const RECEIPT_ACCOUNT_LENGTH = 282;
+/**
+ * PaymentReceipt with the policy snapshot appended after `bump`. Offsets of
+ * every original field are unchanged, so a v2 receipt is a v1 receipt plus a
+ * tail. Both sizes exist on chain at once after the program upgrade.
+ */
+export const RECEIPT_ACCOUNT_LENGTH_V2 = 371;
+/** Every receipt account size a discovery query must ask for. */
+export const RECEIPT_ACCOUNT_LENGTHS = [RECEIPT_ACCOUNT_LENGTH, RECEIPT_ACCOUNT_LENGTH_V2];
+export const MANDATE_ACCOUNT_LENGTH = 235;

package/dist/crossmint-adapt.d.ts

@@ -0,0 +1,43 @@
+import type { PreparePaymentInput } from "./payment.js";
+import type { Address, ChainPayInstruction, PreparedTransaction, TokenProgram } from "./types.js";
+import { CROSSMINT_CONNECTOR, type CrossmintPaymentTerms } from "./crossmint-order.js";
+export type CrossmintPrepareFields = {
+    connector: typeof CROSSMINT_CONNECTOR;
+    connectorLabel: string;
+    orderId: string;
+    mint: Address;
+    recipient: Address;
+    amount: string;
+    tokenProgram: TokenProgram;
+    invoiceHash: string;
+    paymentId: string;
+    signatureReference: string;
+};
+/** Terms plus the references the receipt PDA is derived from. */
+export declare function crossmintTermsToPrepareFields(terms: CrossmintPaymentTerms): Promise<CrossmintPrepareFields>;
+export declare function crossmintFieldsToPreparePaymentInput(mandate: Address, fields: CrossmintPrepareFields): PreparePaymentInput;
+/** One call from a raw Crossmint order response to a ChainPay payment input. */
+export declare function crossmintOrderToPreparePaymentInput(mandate: Address, order: unknown, expected?: {
+    mint?: Address;
+    tokenProgram?: TokenProgram;
+}): Promise<{
+    terms: CrossmintPaymentTerms;
+    fields: CrossmintPrepareFields;
+    input: PreparePaymentInput;
+}>;
+/**
+ * Crossmint's order memo as a top-level SPL Memo instruction with no accounts.
+ *
+ * Crossmint's own preparation has the payer sign the memo. In ChainPay the
+ * approved agent signs and pays fees, never the owner, so the memo names no
+ * signer; the memo program accepts an unsigned memo. The bytes are Crossmint's
+ * memo exactly, because Crossmint matches a payment to its order by this text.
+ */
+export declare function crossmintMemoInstruction(memo: string): ChainPayInstruction;
+/**
+ * The transaction a Crossmint checkout signs: the unchanged mandate payment,
+ * then Crossmint's memo. Nothing else is added and nothing is dropped; a
+ * prepared payment that is not exactly one `execute_payment` is refused.
+ * The receipt PDA and invoice hash are untouched: they come from the order id.
+ */
+export declare function crossmintPaymentTransaction(prepared: PreparedTransaction, terms: Pick<CrossmintPaymentTerms, "memo">): PreparedTransaction;