@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/token.js

@@ -0,0 +1,55 @@
+import { PublicKey } from "@solana/web3.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, } from "./constants.js";
+import { instruction, meta, publicKey, systemProgramMeta, tokenProgramAddress, } from "./encoding.js";
+export function deriveAssociatedTokenAddress(owner, mint, tokenProgram) {
+    // The ATA program derives addresses from owner, token program, and mint.
+    // Keeping this helper in the SDK avoids making callers duplicate the
+    // classic SPL versus Token-2022 distinction.
+    return PublicKey.findProgramAddressSync([
+        publicKey(owner).toBytes(),
+        publicKey(tokenProgramAddress(tokenProgram)).toBytes(),
+        publicKey(mint).toBytes(),
+    ], publicKey(ASSOCIATED_TOKEN_PROGRAM_ID))[0].toBase58();
+}
+export function buildCreateAssociatedTokenAccountInstruction(input) {
+    const associatedTokenAccount = deriveAssociatedTokenAddress(input.owner, input.mint, input.tokenProgram);
+    return instruction("create_associated_token_account", ASSOCIATED_TOKEN_PROGRAM_ID, [
+        meta(input.payer, true, true),
+        meta(associatedTokenAccount, true),
+        meta(input.owner),
+        meta(input.mint),
+        systemProgramMeta(),
+        meta(tokenProgramAddress(input.tokenProgram)),
+    ], 
+    // 1 is CreateIdempotent. Empty data is the legacy Create, which fails
+    // when the account already exists and Phantom shows that as a red banner.
+    new Uint8Array([1]));
+}
+export function associatedTokenProgramAddress() {
+    return ASSOCIATED_TOKEN_PROGRAM_ID;
+}
+export function readTokenAccountFields(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.length < 165)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const delegateOption = view.getUint32(72, true);
+    return {
+        mint: new PublicKey(bytes.slice(0, 32)).toBase58(),
+        owner: new PublicKey(bytes.slice(32, 64)).toBase58(),
+        balance: view.getBigUint64(64, true),
+        delegate: delegateOption === 0 ? null : new PublicKey(bytes.slice(76, 108)).toBase58(),
+        delegatedAmount: bytes.length >= 129 ? view.getBigUint64(121, true) : 0n,
+    };
+}
+export function paymentPreflightContextFromTokenAccount(data) {
+    const fields = readTokenAccountFields(data);
+    if (!fields)
+        return null;
+    return {
+        sourceBalance: fields.balance,
+        sourceOwner: fields.owner,
+        delegate: fields.delegate,
+        delegatedAmount: fields.delegatedAmount,
+    };
+}

package/dist/transaction-reader.d.ts

@@ -0,0 +1,10 @@
+/** Read-only official codec boundary. Construction defaults to legacy; v1 compile is explicit. */
+export declare function decodeSupportedTransaction(bytes: Uint8Array): {
+    transaction: Readonly<{
+        messageBytes: import("@solana/transactions").TransactionMessageBytes;
+        signatures: import("@solana/transactions").SignaturesMap;
+    }>;
+    message: import("@solana/transaction-messages").CompiledTransactionMessage & Readonly<{
+        lifetimeToken: string;
+    }>;
+};

package/dist/transaction-reader.js

@@ -0,0 +1,18 @@
+import { getTransactionDecoder, getTransactionEncoder } from "@solana/transactions";
+import { getCompiledTransactionMessageDecoder, getCompiledTransactionMessageEncoder } from "@solana/transaction-messages";
+/** Read-only official codec boundary. Construction defaults to legacy; v1 compile is explicit. */
+export function decodeSupportedTransaction(bytes) {
+    if (bytes.length === 0 || bytes.length > 4096)
+        throw new Error("Transaction exceeds the supported wire size");
+    const transaction = getTransactionDecoder().decode(bytes);
+    const message = getCompiledTransactionMessageDecoder().decode(transaction.messageBytes);
+    if (message.version !== 1 && bytes.length > 1232)
+        throw new Error("Legacy/v0 transaction exceeds 1232 bytes");
+    const canonicalMessage = getCompiledTransactionMessageEncoder().encode(message);
+    if (canonicalMessage.length !== transaction.messageBytes.length || canonicalMessage.some((value, index) => value !== transaction.messageBytes[index]))
+        throw new Error("Noncanonical transaction message bytes");
+    const canonical = getTransactionEncoder().encode(transaction);
+    if (canonical.length !== bytes.length || canonical.some((value, index) => value !== bytes[index]))
+        throw new Error("Noncanonical transaction wire bytes");
+    return { transaction, message };
+}

package/dist/transaction-v1.d.ts

@@ -0,0 +1,18 @@
+import type { Address, ChainPayInstruction, PreparedTransaction } from "./types.js";
+/** Dashboard and unsigned wallets stay on this unless compile is called with version 1. */
+export declare const DEFAULT_TRANSACTION_VERSION: "legacy";
+export type ProductionTransactionVersion = typeof DEFAULT_TRANSACTION_VERSION | 1;
+/** Explicit v1 budgets. Defaults are unused; v1 treats omitted limits as zero. */
+export declare const V1_COMPUTE_UNIT_LIMIT = 200000;
+export declare const V1_LOADED_ACCOUNTS_DATA_SIZE_LIMIT = 65536;
+export type V1CompileOptions = {
+    version: 1;
+    lifetime: {
+        blockhash: string;
+        lastValidBlockHeight: bigint;
+    };
+    computeUnitLimit: number;
+    loadedAccountsDataSizeLimit: number;
+};
+export declare function systemTransferInstruction(from: Address, to: Address, lamports: bigint): ChainPayInstruction;
+export declare function compileV1TransactionBytes(prepared: PreparedTransaction, options: V1CompileOptions): Uint8Array;

package/dist/transaction-v1.js

@@ -0,0 +1,73 @@
+import { address as kitAddress } from "@solana/addresses";
+import { AccountRole } from "@solana/instructions";
+import { appendTransactionMessageInstructions, createTransactionMessage, setTransactionMessageComputeUnitLimit, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, setTransactionMessageLoadedAccountsDataSizeLimit, } from "@solana/transaction-messages";
+import { compileTransaction, getTransactionEncoder } from "@solana/transactions";
+import { SYSTEM_PROGRAM_ID } from "./constants.js";
+import { address } from "./encoding.js";
+/** Dashboard and unsigned wallets stay on this unless compile is called with version 1. */
+export const DEFAULT_TRANSACTION_VERSION = "legacy";
+/** Explicit v1 budgets. Defaults are unused; v1 treats omitted limits as zero. */
+export const V1_COMPUTE_UNIT_LIMIT = 200_000;
+export const V1_LOADED_ACCOUNTS_DATA_SIZE_LIMIT = 65_536;
+function accountRole(key) {
+    if (key.isSigner && key.isWritable)
+        return AccountRole.WRITABLE_SIGNER;
+    if (key.isSigner)
+        return AccountRole.READONLY_SIGNER;
+    if (key.isWritable)
+        return AccountRole.WRITABLE;
+    return AccountRole.READONLY;
+}
+function kitInstruction(instruction) {
+    return {
+        programAddress: kitAddress(address(instruction.programId)),
+        accounts: instruction.keys.map((key) => ({
+            address: kitAddress(address(key.address)),
+            role: accountRole(key),
+        })),
+        data: instruction.data,
+    };
+}
+export function systemTransferInstruction(from, to, lamports) {
+    if (lamports <= 0n)
+        throw new Error("amount must be positive");
+    const data = new Uint8Array(12);
+    data[0] = 2;
+    const view = new DataView(data.buffer);
+    view.setBigUint64(4, lamports, true);
+    return {
+        name: "system_transfer",
+        programId: SYSTEM_PROGRAM_ID,
+        keys: [
+            { address: address(from), isSigner: true, isWritable: true },
+            { address: address(to), isSigner: false, isWritable: true },
+        ],
+        data,
+    };
+}
+export function compileV1TransactionBytes(prepared, options) {
+    if (options.version !== 1)
+        throw new Error("compileV1TransactionBytes requires version 1");
+    if (options.computeUnitLimit <= 0 || options.computeUnitLimit > 1_400_000) {
+        throw new Error("V1 compute unit limit must be explicit and at most 1400000");
+    }
+    if (options.loadedAccountsDataSizeLimit <= 0 || options.loadedAccountsDataSizeLimit > 64 * 1024 * 1024) {
+        throw new Error("V1 loaded accounts data size limit must be explicit and at most 64 MiB");
+    }
+    if (prepared.instructions.length === 0)
+        throw new Error("A prepared transaction needs instructions");
+    const feePayer = prepared.feePayer ?? prepared.requiredSigners[0];
+    if (!feePayer)
+        throw new Error("A prepared transaction needs a fee payer");
+    const empty = createTransactionMessage({ version: 1 });
+    const withFeePayer = setTransactionMessageFeePayer(kitAddress(address(feePayer)), empty);
+    const withLifetime = setTransactionMessageLifetimeUsingBlockhash({
+        blockhash: options.lifetime.blockhash,
+        lastValidBlockHeight: options.lifetime.lastValidBlockHeight,
+    }, withFeePayer);
+    const withCompute = setTransactionMessageComputeUnitLimit(options.computeUnitLimit, withLifetime);
+    const withDataLimit = setTransactionMessageLoadedAccountsDataSizeLimit(options.loadedAccountsDataSizeLimit, withCompute);
+    const withInstructions = appendTransactionMessageInstructions(prepared.instructions.map(kitInstruction), withDataLimit);
+    const compiled = compileTransaction(withInstructions);
+    return new Uint8Array(getTransactionEncoder().encode(compiled));
+}

package/dist/types.d.ts

@@ -0,0 +1,267 @@
+export type Address = string;
+export type TokenProgram = "spl-token" | "token-2022";
+export type AccountMeta = {
+    address: Address;
+    isSigner: boolean;
+    isWritable: boolean;
+};
+export type ChainPayInstruction = {
+    name: string;
+    programId: Address;
+    keys: AccountMeta[];
+    data: Uint8Array;
+};
+export type PreparedTransaction = {
+    instructions: ChainPayInstruction[];
+    requiredSigners: Address[];
+    feePayer?: Address;
+};
+export type PaymentSubmission = {
+    signature: string;
+    slot?: bigint;
+    status?: "submitted" | "confirmed";
+};
+export type PaymentSubmissionAdapter = {
+    submit(prepared: PreparedTransaction): Promise<PaymentSubmission>;
+    confirm?(signature: string): Promise<{
+        slot?: bigint;
+    }>;
+};
+export type MandateStatus = "active" | "paused" | "revoked" | "expired";
+export type PaymentStatus = "prepared" | "submitted" | "confirmed" | "failed";
+export type Mandate = {
+    address: Address;
+    owner: Address;
+    approvedAgent: Address;
+    sourceTokenAccount: Address;
+    allowedMint: Address;
+    /** Populated only when decoding a legacy fixed-recipient mandate. */
+    legacyAllowedRecipient?: Address;
+    maxPerPayment: bigint;
+    totalLimit: bigint;
+    amountSpent: bigint;
+    paymentCount: bigint;
+    expiresAtSlot: bigint;
+    maxPaymentCount: bigint;
+    cooldownSlots: bigint;
+    lastPaymentSlot: bigint;
+    paused: boolean;
+    revoked: boolean;
+    status: MandateStatus;
+    tokenProgram?: TokenProgram;
+    /** Present for nonce-scoped mandates; absent for legacy accounts. */
+    mandateNonce?: Address;
+    /** Unix timestamp from the oldest confirmed transaction for this PDA. */
+    createdAt?: number;
+    /** Slot from the oldest confirmed transaction for this PDA. */
+    createdAtSlot?: bigint;
+};
+export type SupportedAsset = {
+    address: Address;
+    authority: Address;
+    mint: Address;
+    tokenProgram: Address;
+    enabled: boolean;
+    bump: number;
+};
+export type AssociatedTokenAccountPreparation = {
+    asset: SupportedAsset;
+    address: Address;
+    owner: Address;
+    mint: Address;
+    tokenProgram: TokenProgram;
+    status: "ready" | "missing";
+    /** Present only when the canonical account is missing. The SDK never submits it. */
+    transaction?: PreparedTransaction;
+};
+export type TokenCapabilityProfile = {
+    mint: Address;
+    tokenProgram: TokenProgram;
+    compatible: boolean;
+    mintExtensions: string[];
+    sourceAccountExtensions: string[];
+    recipientAccountExtensions: string[];
+    blockers: string[];
+    warnings: string[];
+    transferFee?: {
+        basisPoints: number;
+        maximumFee: bigint;
+    };
+    transferHookProgram?: Address;
+};
+/** One line of what was bought. Amounts are base units of the request mint. */
+export type PaymentRequestLineItem = {
+    label: string;
+    /** Unsigned integer string in base units of the request mint. */
+    amount?: string;
+    /** Unsigned decimal string, for example "1" or "2.5". */
+    quantity?: string;
+};
+export type PaymentRequestPayload = {
+    version: 1;
+    cluster: "devnet" | "mainnet-beta";
+    merchant: Address;
+    invoice: string;
+    mint: Address;
+    tokenProgram: TokenProgram;
+    recipient: Address;
+    amount: string;
+    decimals: number;
+    nonce: string;
+    expiresAtSlot?: string;
+    resource?: string;
+    /**
+     * Seller's plain description of what is being bought. Signed with the rest
+     * of the payload, so it is part of the invoice hash when present.
+     */
+    description?: string;
+    lineItems?: PaymentRequestLineItem[];
+};
+export type SignedPaymentRequest = {
+    payload: PaymentRequestPayload;
+    signature: string;
+};
+export type PaymentRequestVerification = {
+    valid: boolean;
+    payload: PaymentRequestPayload;
+    invoiceHash: Uint8Array;
+    reason?: string;
+};
+export type PaymentRequest = {
+    mandate: Address;
+    invoiceHash: Uint8Array;
+    paymentId: Uint8Array;
+    signatureReference: Uint8Array;
+    mint: Address;
+    recipient: Address;
+    amount: bigint;
+    tokenProgram?: TokenProgram;
+};
+/**
+ * Mandate policy values the program copied into a v2 receipt at payment time.
+ * Every value is the mandate's state immediately after this payment.
+ */
+export type ReceiptPolicyLimits = {
+    maxPerPayment: bigint;
+    totalLimit: bigint;
+    amountSpentAfter: bigint;
+    paymentCountAfter: bigint;
+    /** 0 means no payment-count cap. */
+    maxPaymentCount: bigint;
+    expiresAtSlot: bigint;
+    cooldownSlots: bigint;
+};
+export type ReceiptPolicySnapshot = ReceiptPolicyLimits & {
+    /** Layout version byte from the receipt. 1 is the first snapshot layout. */
+    version: number;
+};
+/**
+ * Where the limits shown beside a receipt came from.
+ * - on-chain: written by the program into the receipt account itself.
+ * - relay-observed: read from the mandate by the ChainPay relay after the
+ *   payment finalized. Not stored on Solana, and later payments in the same
+ *   observation window may already be counted.
+ * - not-recorded: neither exists for this receipt.
+ */
+export type ReceiptPolicySource = "on-chain" | "relay-observed" | "not-recorded";
+export type ReceiptPolicy = {
+    source: "on-chain";
+    limits: ReceiptPolicyLimits;
+} | {
+    source: "relay-observed";
+    limits: ReceiptPolicyLimits;
+    observedAtSlot: bigint;
+    /**
+     * The mandate had paid again after this receipt when the relay read it,
+     * so `amountSpentAfter` and `paymentCountAfter` include later payments.
+     */
+    includesLaterPayments: boolean;
+} | {
+    source: "not-recorded";
+};
+export type PaymentReceipt = {
+    address: Address;
+    mandate: Address;
+    invoiceHash: Uint8Array;
+    paymentId: Uint8Array;
+    mint: Address;
+    recipient: Address;
+    sourceTokenAccount: Address;
+    recipientTokenAccount: Address;
+    amount: bigint;
+    agent: Address;
+    executedAtSlot: bigint;
+    /** Replay lock from settle. Not seller delivery and not the transaction signature. */
+    signatureReference: Uint8Array;
+    status: PaymentStatus;
+    onChainStatus: number;
+    bump: number;
+    transactionSignature?: string;
+    /**
+     * Policy snapshot from a v2 (371-byte) receipt. Null for an original
+     * 282-byte receipt or when the program wrote no snapshot.
+     */
+    policySnapshot: ReceiptPolicySnapshot | null;
+};
+export type PolicyCheck = {
+    name: string;
+    ok: boolean;
+    message: string;
+};
+/** Verified source token account fields supplied by preparePayment. */
+export type PaymentPreflightContext = {
+    sourceBalance: bigint;
+    sourceOwner: Address;
+    delegate: Address | null;
+    delegatedAmount: bigint;
+};
+export type PaymentPreflight = {
+    valid: boolean;
+    currentSlot: bigint;
+    checks: PolicyCheck[];
+};
+export type BatchPreflightEntry = {
+    request: PaymentRequest;
+    mandate: Mandate;
+    agent?: Address;
+    receiptAlreadyExists?: boolean;
+    sourceContext?: PaymentPreflightContext;
+};
+export type PaymentBatchPreflight = {
+    valid: boolean;
+    currentSlot: bigint;
+    entries: Array<{
+        request: PaymentRequest;
+        mandate: Address;
+        preflight: PaymentPreflight;
+    }>;
+    batchChecks: PolicyCheck[];
+};
+export type PreparedPayment = {
+    request: PaymentRequest;
+    mandate: Mandate;
+    receiptAddress: Address;
+    instruction: ChainPayInstruction;
+    transaction: PreparedTransaction;
+    preflight: PaymentPreflight;
+    capabilityProfile?: TokenCapabilityProfile;
+};
+export type PaymentExecutionResult = {
+    status: "submitted" | "confirmed" | "failed";
+    receiptAddress: Address;
+    signature?: string;
+    slot?: bigint;
+    error?: string;
+    /** Set when the receipt already existed: nothing new was paid. */
+    code?: "DuplicateInvoice";
+};
+export type PreparedMandate = {
+    mandateAddress: Address;
+    configAddress: Address;
+    transaction: PreparedTransaction;
+};
+export type ChainPayClientOptions = {
+    rpcUrl?: string;
+    programId?: Address;
+    commitment?: "processed" | "confirmed" | "finalized";
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/x402-adapt.d.ts

@@ -0,0 +1,20 @@
+import type { TokenProgram } from "./types.js";
+import type { PreparePaymentInput } from "./payment.js";
+import { type CustomChallengeOption, type StandardV2Option, type DetectedChallenge } from "./x402-challenge.js";
+export type X402PrepareFields = {
+    mint: string;
+    recipient: string;
+    amount: string;
+    resource: string;
+    tokenProgram: TokenProgram;
+    invoiceHash: string;
+    paymentId: string;
+    signatureReference: string;
+    nonce: string;
+    merchantOwner?: string;
+};
+export declare function standardV2RecipientTokenAccount(option: StandardV2Option, tokenProgram: TokenProgram): string;
+export declare function customChallengeToPrepareFields(option: CustomChallengeOption, tokenProgram: TokenProgram): Promise<X402PrepareFields>;
+export declare function standardV2ChallengeToPrepareFields(option: StandardV2Option, tokenProgram: TokenProgram): Promise<X402PrepareFields>;
+export declare function toPreparePaymentInput(mandate: string, fields: X402PrepareFields): Promise<PreparePaymentInput>;
+export declare function detectedChallengeToPrepareFields(detected: DetectedChallenge, tokenProgram: TokenProgram): Promise<X402PrepareFields>;

package/dist/x402-adapt.js

@@ -0,0 +1,62 @@
+import { hexToBytes } from "./receipt.js";
+import { deriveAssociatedTokenAddress } from "./token.js";
+import { deriveX402PaymentReferences } from "./x402.js";
+export function standardV2RecipientTokenAccount(option, tokenProgram) {
+    return deriveAssociatedTokenAddress(option.merchantOwner, option.asset, tokenProgram);
+}
+export async function customChallengeToPrepareFields(option, tokenProgram) {
+    const references = await deriveX402PaymentReferences({
+        mint: option.mint,
+        recipient: option.recipient,
+        amount: option.amount,
+        resource: option.resource,
+        tokenProgram,
+        ...(option.nonce ? { nonce: option.nonce } : {}),
+        ...(option.expiresAtSlot ? { expiresAtSlot: option.expiresAtSlot } : {}),
+    });
+    return {
+        mint: option.mint,
+        recipient: option.recipient,
+        amount: option.amount,
+        resource: option.resource,
+        tokenProgram,
+        ...references,
+    };
+}
+export async function standardV2ChallengeToPrepareFields(option, tokenProgram) {
+    const recipient = standardV2RecipientTokenAccount(option, tokenProgram);
+    const references = await deriveX402PaymentReferences({
+        mint: option.asset,
+        recipient,
+        amount: option.amount,
+        resource: option.resource,
+        tokenProgram,
+    });
+    return {
+        mint: option.asset,
+        recipient,
+        amount: option.amount,
+        resource: option.resource,
+        tokenProgram,
+        merchantOwner: option.merchantOwner,
+        ...references,
+    };
+}
+export async function toPreparePaymentInput(mandate, fields) {
+    return {
+        mandate,
+        invoiceHash: hexToBytes(fields.invoiceHash, "invoiceHash"),
+        paymentId: hexToBytes(fields.paymentId, "paymentId"),
+        signatureReference: hexToBytes(fields.signatureReference, "signatureReference"),
+        mint: fields.mint,
+        recipient: fields.recipient,
+        amount: BigInt(fields.amount),
+        tokenProgram: fields.tokenProgram,
+    };
+}
+export async function detectedChallengeToPrepareFields(detected, tokenProgram) {
+    if (detected.kind === "custom") {
+        return customChallengeToPrepareFields(detected.option, tokenProgram);
+    }
+    return standardV2ChallengeToPrepareFields(detected.option, tokenProgram);
+}

package/dist/x402-challenge.d.ts

@@ -0,0 +1,116 @@
+export declare const CUSTOM_X402_VERSION: "x402/1.0";
+export declare const SOLANA_DEVNET_CAIP2 = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+export declare const CUSTOM_NETWORK: "solana-devnet";
+export declare const CUSTOM_PROTOCOL: "chainpay-custom-x402/1.0";
+export declare const STANDARD_V2_PROTOCOL: "x402-v2";
+export declare const CUSTOM_PROTOCOL_LABEL = "ChainPay custom receipt-proof flow (x402/1.0). Proof is a settled signature and receipt PDA, not a standard x402 v2 sponsor countersign.";
+export declare const STANDARD_V2_PROTOCOL_LABEL = "Standard x402 v2 exact SVM. Proof is a partially signed transaction for sponsor countersign. ChainPay does not operate a facilitator.";
+export type X402ProtocolCode = "malformed" | "unsupported_network" | "unsupported_scheme" | "resource_mismatch" | "conflicting_protocols";
+export declare class X402ProtocolError extends Error {
+    readonly code: X402ProtocolCode;
+    constructor(code: X402ProtocolCode, message: string);
+}
+export type CustomChallengeOption = {
+    protocol: typeof CUSTOM_PROTOCOL;
+    protocolLabel: string;
+    proofKind: "settled-receipt-pda";
+    network: typeof CUSTOM_NETWORK;
+    scheme: "exact";
+    mint: string;
+    recipient: string;
+    amount: string;
+    resource: string;
+    tokenProgram?: "spl-token" | "token-2022";
+    nonce?: string;
+    expiresAtSlot?: string;
+};
+export type StandardV2Option = {
+    protocol: typeof STANDARD_V2_PROTOCOL;
+    protocolLabel: string;
+    proofKind: "partially-signed-sponsored-transaction";
+    network: typeof SOLANA_DEVNET_CAIP2;
+    scheme: "exact";
+    amount: string;
+    asset: string;
+    merchantOwner: string;
+    resource: string;
+    maxTimeoutSeconds?: number;
+    feePayer?: string;
+};
+export type DetectedChallenge = {
+    kind: "custom";
+    option: CustomChallengeOption;
+    envelope: Record<string, unknown>;
+} | {
+    kind: "standard-v2";
+    option: StandardV2Option;
+    envelope: Record<string, unknown>;
+};
+export declare function canonicalU64String(value: unknown, name: string, allowZero?: boolean): string;
+export declare function decodePaymentRequiredWire(value: string): unknown;
+export declare function paymentRequiredDocumentsFromResponse(headers: {
+    get(name: string): string | null;
+}, body?: {
+    parsed?: unknown;
+}): unknown[];
+export declare function parsePaymentRequiredDocument(value: unknown, expectedResource?: string): DetectedChallenge;
+export declare function detectAndParsePaymentRequired(documents: unknown[], expectedResource?: string): DetectedChallenge;
+/** Alias for agent/SDK callers: parse HTTP 402 headers and body into a detected challenge. */
+export declare function detectPaymentChallenge(headers: {
+    get(name: string): string | null;
+}, body: {
+    parsed?: unknown;
+}, expectedResource?: string): DetectedChallenge;
+export declare function parsePaymentRequiredFromResponse(headers: {
+    get(name: string): string | null;
+}, body: {
+    parsed?: unknown;
+}, expectedResource?: string): DetectedChallenge;
+export declare function customReceiptProofDocument(signature: string, receiptPDA: string): {
+    version: "x402/1.0";
+    scheme: "exact";
+    network: "solana-devnet";
+    payload: {
+        signature: string;
+        receiptPDA: string;
+    };
+};
+export type UnsupportedSponsorResult = {
+    action: "x402_unsupported_sponsor";
+    mode: "unsupported-sponsor";
+    protocol: typeof STANDARD_V2_PROTOCOL;
+    protocolLabel: string;
+    proofKind: "partially-signed-sponsored-transaction";
+    network: typeof SOLANA_DEVNET_CAIP2;
+    scheme: "exact";
+    amount: string;
+    asset: string;
+    merchantOwner: string;
+    resource: string;
+    sponsorAvailable: false;
+    wouldSettle: false;
+    reason: "facilitator_required";
+    message: string;
+    derivedRecipientTokenAccount?: string;
+    mandateQuote?: {
+        status: "ready" | "needs_details" | "blocked";
+        preflightValid?: boolean;
+        checks?: Array<{
+            key: string;
+            label: string;
+            status: string;
+            detail: string;
+        }>;
+    };
+};
+export declare function unsupportedSponsorResult(option: StandardV2Option, extras?: Pick<UnsupportedSponsorResult, "derivedRecipientTokenAccount" | "mandateQuote">): UnsupportedSponsorResult;
+export type MppUnsupportedResult = {
+    action: "mpp_unsupported";
+    mode: "unsupported-mpp";
+    message: string;
+    wwwAuthenticate?: string;
+    intent?: string;
+    method?: string;
+    challengeId?: string;
+};
+export declare function parseMppWwwAuthenticate(value: string | null): MppUnsupportedResult | null;