@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/math.d.ts

@@ -0,0 +1,67 @@
+export type CentsString = string;
+/** Parse a wire amount (`"50250"`). Rejects signs, decimals, leading zeros and more than 16 digits. */
+export declare function parseCents(value: unknown, name?: string): bigint;
+/** Signed cents for statement totals and refund fees, where negative means credit (`"-1005"`). */
+export declare function parseSignedCents(value: unknown, name?: string): bigint;
+export declare function centsToString(value: bigint): CentsString;
+/**
+ * Platform fee on one line: floor(x · bps / 10 000), integer only. The one
+ * rule for debits and credits alike, the same in card_policy and Axum
+ * statements (contracts.md §1.5, review fixes 2026-10-04). Rounding down means
+ * split refunds never credit more than one refund of the same total, and a
+ * period's fees never pass fee(budget). Vectors: shared/cards/fee-vectors.json.
+ */
+export declare function feeCents(amountCents: bigint, feeBps: number): bigint;
+/**
+ * A refund on a hold returns at most what it captured and hasn't refunded:
+ * `refunded + amount <= captured`. Returns the amount when it fits, `null`
+ * when card_policy (or Axum, for a closed hold) sends it to review instead.
+ */
+export declare function refundableCents(capturedCents: bigint, refundedCents: bigint, amountCents: bigint): bigint | null;
+/**
+ * The most the owner can owe for one period: budget + fee(budget). $500 @ 50 bps → $502.50.
+ * A hard limit: card_policy bills no debit (purchase, forced post, late capture)
+ * past the period budget, and floor fees sum to at most fee(budget). Issuer
+ * charges past it are booked for review, never onto the owner's statement.
+ */
+export declare function maxObligationCents(budgetCents: bigint, feeBps: number): bigint;
+/** available = budget − (captured + reserved), floored at zero. */
+export declare function availableCents(budgetCents: bigint, capturedCents: bigint, reservedCents: bigint): bigint;
+/** Outstanding after a capture: += amount + fee(amount). */
+export declare function outstandingAfterCapture(outstandingCents: bigint, capturedCents: bigint, feeBps: number): bigint;
+/** Outstanding after a refund: −= min(refund + fee(refund), outstanding). */
+export declare function outstandingAfterRefund(outstandingCents: bigint, refundCents: bigint, feeBps: number): bigint;
+export type StatementLineInput = {
+    kind: "purchase" | "refund" | "adjustment_debit" | "adjustment_credit";
+    amountCents: bigint;
+};
+export type StatementTotals = {
+    purchasesCents: bigint;
+    refundsCents: bigint;
+    /** Signed: refund fees are negative, using the same floor formula. */
+    feeCents: bigint;
+    /** Signed: negative means the period ended in credit. */
+    totalCents: bigint;
+};
+/** Statement totals (contracts.md §7.1): total = purchases − refunds + Σ per-line fees. */
+export declare function statementTotals(lines: readonly StatementLineInput[], feeBps: number): StatementTotals;
+/** Exact dollars for people: 50250n → "$502.50". No rounding is ever applied. */
+export declare function formatUsdCents(value: bigint | CentsString): string;
+/** 50 → "0.5%", 125 → "1.25%", 0 → "0%". */
+export declare function formatFeeBps(feeBps: number): string;
+/** USD stablecoin base units for a statement repayment: cents × 10^(decimals−2). USDC (6) → ×10 000. */
+export declare function centsToTokenBaseUnits(cents: bigint, decimals: number): bigint;
+/** Owner-facing review numbers before signing `set_policy` (PLAN F). */
+export declare function policyReviewSummary(budgetCents: bigint, maxPurchaseCents: bigint, feeBps: number): {
+    budgetCents: string;
+    maxPurchaseCents: string;
+    feeBps: number;
+    feeCentsAtFullBudget: string;
+    maxObligationCents: string;
+    display: {
+        budget: string;
+        maxPurchase: string;
+        fee: string;
+        maxObligation: string;
+    };
+};

package/dist/cards/math.js

@@ -0,0 +1,138 @@
+/*
+ * Card money math. Every value is an integer number of US cents (contracts.md
+ * preamble): bigint in code, decimal-integer strings on the wire, never a
+ * float and never a JS number for anything persisted.
+ */
+const CENTS_PATTERN = /^(0|[1-9][0-9]{0,15})$/;
+const BPS_DENOMINATOR = 10000n;
+/** Parse a wire amount (`"50250"`). Rejects signs, decimals, leading zeros and more than 16 digits. */
+export function parseCents(value, name = "amountCents") {
+    if (typeof value === "bigint") {
+        if (value < 0n)
+            throw new Error(`${name} can't be negative`);
+        return value;
+    }
+    if (typeof value !== "string" || !CENTS_PATTERN.test(value)) {
+        throw new Error(`${name} must be a whole number of cents written as a string, like "2000"`);
+    }
+    return BigInt(value);
+}
+/** Signed cents for statement totals and refund fees, where negative means credit (`"-1005"`). */
+export function parseSignedCents(value, name = "amountCents") {
+    if (typeof value === "string" && value.startsWith("-") && value !== "-0")
+        return -parseCents(value.slice(1), name);
+    return parseCents(value, name);
+}
+export function centsToString(value) {
+    if (value < 0n)
+        throw new Error("cents can't be negative on the wire");
+    return value.toString();
+}
+/**
+ * Platform fee on one line: floor(x · bps / 10 000), integer only. The one
+ * rule for debits and credits alike, the same in card_policy and Axum
+ * statements (contracts.md §1.5, review fixes 2026-10-04). Rounding down means
+ * split refunds never credit more than one refund of the same total, and a
+ * period's fees never pass fee(budget). Vectors: shared/cards/fee-vectors.json.
+ */
+export function feeCents(amountCents, feeBps) {
+    assertBps(feeBps);
+    if (amountCents < 0n)
+        throw new Error("amount can't be negative");
+    return (amountCents * BigInt(feeBps)) / BPS_DENOMINATOR;
+}
+/**
+ * A refund on a hold returns at most what it captured and hasn't refunded:
+ * `refunded + amount <= captured`. Returns the amount when it fits, `null`
+ * when card_policy (or Axum, for a closed hold) sends it to review instead.
+ */
+export function refundableCents(capturedCents, refundedCents, amountCents) {
+    return refundedCents + amountCents <= capturedCents ? amountCents : null;
+}
+/**
+ * The most the owner can owe for one period: budget + fee(budget). $500 @ 50 bps → $502.50.
+ * A hard limit: card_policy bills no debit (purchase, forced post, late capture)
+ * past the period budget, and floor fees sum to at most fee(budget). Issuer
+ * charges past it are booked for review, never onto the owner's statement.
+ */
+export function maxObligationCents(budgetCents, feeBps) {
+    return budgetCents + feeCents(budgetCents, feeBps);
+}
+/** available = budget − (captured + reserved), floored at zero. */
+export function availableCents(budgetCents, capturedCents, reservedCents) {
+    const used = capturedCents + reservedCents;
+    return used >= budgetCents ? 0n : budgetCents - used;
+}
+/** Outstanding after a capture: += amount + fee(amount). */
+export function outstandingAfterCapture(outstandingCents, capturedCents, feeBps) {
+    return outstandingCents + capturedCents + feeCents(capturedCents, feeBps);
+}
+/** Outstanding after a refund: −= min(refund + fee(refund), outstanding). */
+export function outstandingAfterRefund(outstandingCents, refundCents, feeBps) {
+    const credit = refundCents + feeCents(refundCents, feeBps);
+    return credit >= outstandingCents ? 0n : outstandingCents - credit;
+}
+/** Statement totals (contracts.md §7.1): total = purchases − refunds + Σ per-line fees. */
+export function statementTotals(lines, feeBps) {
+    let purchasesCents = 0n;
+    let refundsCents = 0n;
+    let fees = 0n;
+    for (const line of lines) {
+        if (line.amountCents < 0n)
+            throw new Error("statement line amounts are unsigned; use the line kind for direction");
+        const debit = line.kind === "purchase" || line.kind === "adjustment_debit";
+        if (debit) {
+            purchasesCents += line.amountCents;
+            fees += feeCents(line.amountCents, feeBps);
+        }
+        else {
+            refundsCents += line.amountCents;
+            fees -= feeCents(line.amountCents, feeBps);
+        }
+    }
+    // Never clamp: a negative total is a credit the owner is owed, not zero.
+    return { purchasesCents, refundsCents, feeCents: fees, totalCents: purchasesCents - refundsCents + fees };
+}
+/** Exact dollars for people: 50250n → "$502.50". No rounding is ever applied. */
+export function formatUsdCents(value) {
+    const cents = typeof value === "bigint" ? value : parseSignedCents(value);
+    const negative = cents < 0n;
+    const abs = negative ? -cents : cents;
+    const dollars = (abs / 100n).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const rest = (abs % 100n).toString().padStart(2, "0");
+    return `${negative ? "-" : ""}$${dollars}.${rest}`;
+}
+/** 50 → "0.5%", 125 → "1.25%", 0 → "0%". */
+export function formatFeeBps(feeBps) {
+    assertBps(feeBps);
+    const whole = Math.trunc(feeBps / 100);
+    const frac = (feeBps % 100).toString().padStart(2, "0").replace(/0+$/, "");
+    return frac ? `${whole}.${frac}%` : `${whole}%`;
+}
+/** USD stablecoin base units for a statement repayment: cents × 10^(decimals−2). USDC (6) → ×10 000. */
+export function centsToTokenBaseUnits(cents, decimals) {
+    if (!Number.isInteger(decimals) || decimals < 2)
+        throw new Error("token must have at least 2 decimals");
+    return cents * 10n ** BigInt(decimals - 2);
+}
+/** Owner-facing review numbers before signing `set_policy` (PLAN F). */
+export function policyReviewSummary(budgetCents, maxPurchaseCents, feeBps) {
+    const obligation = maxObligationCents(budgetCents, feeBps);
+    return {
+        budgetCents: centsToString(budgetCents),
+        maxPurchaseCents: centsToString(maxPurchaseCents),
+        feeBps,
+        feeCentsAtFullBudget: centsToString(obligation - budgetCents),
+        maxObligationCents: centsToString(obligation),
+        display: {
+            budget: formatUsdCents(budgetCents),
+            maxPurchase: formatUsdCents(maxPurchaseCents),
+            fee: formatFeeBps(feeBps),
+            maxObligation: formatUsdCents(obligation),
+        },
+    };
+}
+function assertBps(feeBps) {
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 1_000)
+        throw new Error("feeBps must be a whole number from 0 to 1000");
+}

package/dist/cards/merchants.d.ts

@@ -0,0 +1,23 @@
+export type CardSandboxMerchant = {
+    ref: string;
+    displayName: string;
+    acceptorId: string;
+    /** Statement descriptor the issuer shows (Lithic `merchant.descriptor`). */
+    descriptor: string;
+    /** What the shop sells, in plain words. */
+    sells: string;
+    mcc: number;
+    /** Fixture role: the approved shop and the one a card should decline. */
+    fixture: "approved" | "unapproved";
+};
+export declare const CARD_SANDBOX_MERCHANTS: readonly CardSandboxMerchant[];
+/** Lithic's limit on `merchant_acceptor_id`. */
+export declare const MAX_ACCEPTOR_ID_LENGTH = 15;
+/** Plain names for the merchant categories the dashboard offers. */
+export declare const CARD_MCC_NAMES: Readonly<Record<number, string>>;
+export declare function cardMerchantByRef(ref: string): CardSandboxMerchant | undefined;
+/** Matches the connector's `merchant_by_acceptor` (trimmed, case-insensitive). */
+export declare function cardMerchantByAcceptorId(acceptorId: string): CardSandboxMerchant | undefined;
+/** Allowlist hashes for `set_policy`. Throws on an unknown shop so nothing is silently dropped. */
+export declare function merchantIdHashesForRefs(refs: readonly string[]): Promise<Uint8Array[]>;
+export declare function mccLabel(mcc: number): string;

package/dist/cards/merchants.js

@@ -0,0 +1,38 @@
+import { merchantIdHash } from "./hash.js";
+export const CARD_SANDBOX_MERCHANTS = [
+    { ref: "demo-approved", displayName: "ChainPay demo shop", acceptorId: "DEMO-DATAAPI", descriptor: "DATA API CREDITS", sells: "Data API credits", mcc: 5734, fixture: "approved" },
+    { ref: "demo-unapproved", displayName: "Unlisted test shop", acceptorId: "DEMO-OTHERSHOP", descriptor: "UNAPPROVED SHOP", sells: "Anything else", mcc: 5999, fixture: "unapproved" },
+];
+/** Lithic's limit on `merchant_acceptor_id`. */
+export const MAX_ACCEPTOR_ID_LENGTH = 15;
+/** Plain names for the merchant categories the dashboard offers. */
+export const CARD_MCC_NAMES = {
+    4816: "Online services",
+    5045: "Computers and electronics",
+    5734: "Software",
+    5817: "Digital goods",
+    5942: "Books",
+    5999: "Other retail",
+    7372: "Data and computer services",
+    4121: "Rides",
+};
+export function cardMerchantByRef(ref) {
+    return CARD_SANDBOX_MERCHANTS.find((merchant) => merchant.ref === ref);
+}
+/** Matches the connector's `merchant_by_acceptor` (trimmed, case-insensitive). */
+export function cardMerchantByAcceptorId(acceptorId) {
+    const wanted = acceptorId.trim().toUpperCase();
+    return CARD_SANDBOX_MERCHANTS.find((merchant) => merchant.acceptorId === wanted);
+}
+/** Allowlist hashes for `set_policy`. Throws on an unknown shop so nothing is silently dropped. */
+export async function merchantIdHashesForRefs(refs) {
+    return Promise.all(refs.map((ref) => {
+        const merchant = cardMerchantByRef(ref);
+        if (!merchant)
+            throw new Error(`"${ref}" isn't a registered shop`);
+        return merchantIdHash(merchant.acceptorId);
+    }));
+}
+export function mccLabel(mcc) {
+    return CARD_MCC_NAMES[mcc] ? `${CARD_MCC_NAMES[mcc]} (${String(mcc).padStart(4, "0")})` : `Category ${String(mcc).padStart(4, "0")}`;
+}

package/dist/cards/pda.d.ts

@@ -0,0 +1,42 @@
+import type { Address } from "../types.js";
+/** `["card_binding", owner, card_id]` (base, public). */
+export declare function deriveCardBindingAddress(owner: Address, cardId: Uint8Array, programId?: Address): Address;
+/** `["card_policy", binding]` (delegated to the TEE, private). */
+export declare function deriveCardPolicyAddress(binding: Address, programId?: Address): Address;
+/** `["card_period", binding]` (delegated to the TEE, private). */
+export declare function deriveCardPeriodAddress(binding: Address, programId?: Address): Address;
+/** `["res", policy, auth_id_hash]` (PER-only). Its existence is the replay guard. */
+export declare function deriveReservationAddress(policy: Address, authIdHash: Uint8Array, programId?: Address): Address;
+/** `["auth_guard", policy]` (PER-only): replay guard for closed reservations. */
+export declare function deriveAuthGuardAddress(policy: Address, programId?: Address): Address;
+/** `["intent", policy, intent_id]` (PER-only); intent_id is 16 bytes. */
+export declare function deriveCheckoutIntentAddress(policy: Address, intentId: Uint8Array, programId?: Address): Address;
+/** `["card_commit", binding]` (base, public, never delegated). */
+export declare function deriveCardCommitmentAddress(binding: Address, programId?: Address): Address;
+/**
+ * `["repay_agent", binding]` (base, system-owned, lamport-only). The owner's ChainPay
+ * repayment mandate names it as `approved_agent`; it signs only inside `repay_statement`.
+ */
+export declare function deriveRepayAgentAddress(binding: Address, programId?: Address): Address;
+/** MagicBlock permission PDA for a private account: `["permission:", account]` under the permission program. */
+export declare function derivePermissionAddress(account: Address): Address;
+/** Delegation-program escrow that pays for the card's Magic Actions: `["balance", policy, 255]`. */
+export declare function deriveCardEscrowAddress(escrowAuthority: Address, index?: number): Address;
+export declare function deriveDelegationBufferAddress(account: Address, programId?: Address): Address;
+export declare function deriveDelegationRecordAddress(account: Address): Address;
+export declare function deriveDelegationMetadataAddress(account: Address): Address;
+export declare function deriveMagicFeeVaultAddress(validator: Address): Address;
+export type CardAccounts = {
+    binding: Address;
+    policy: Address;
+    period: Address;
+    commitment: Address;
+    escrow: Address;
+    policyPermission: Address;
+    periodPermission: Address;
+};
+/** Every address one card owns, from the owner wallet and the 32-byte card id. */
+export declare function deriveCardAccounts(owner: Address, cardId: Uint8Array, programId?: Address): CardAccounts;
+/** Card ids travel as 64-char lowercase hex (Convex key `card:<cardId hex>`). */
+export declare function cardIdFromHex(value: string): Uint8Array;
+export declare function cardIdToHex(cardId: Uint8Array): string;

package/dist/cards/pda.js

@@ -0,0 +1,93 @@
+import { PublicKey } from "@solana/web3.js";
+import { bytes32, publicKey } from "../encoding.js";
+import { CARD_SEEDS, DELEGATION_PROGRAM_ID, PERMISSION_PROGRAM_ID, resolveCardPolicyProgramId, } from "./constants.js";
+function pda(seeds, programId) {
+    return PublicKey.findProgramAddressSync(seeds, publicKey(programId))[0].toBase58();
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+/** `["card_binding", owner, card_id]` (base, public). */
+export function deriveCardBindingAddress(owner, cardId, programId) {
+    return pda([utf8(CARD_SEEDS.binding), publicKey(owner).toBytes(), bytes32(cardId, "cardId")], resolveCardPolicyProgramId(programId));
+}
+/** `["card_policy", binding]` (delegated to the TEE, private). */
+export function deriveCardPolicyAddress(binding, programId) {
+    return pda([utf8(CARD_SEEDS.policy), publicKey(binding).toBytes()], resolveCardPolicyProgramId(programId));
+}
+/** `["card_period", binding]` (delegated to the TEE, private). */
+export function deriveCardPeriodAddress(binding, programId) {
+    return pda([utf8(CARD_SEEDS.period), publicKey(binding).toBytes()], resolveCardPolicyProgramId(programId));
+}
+/** `["res", policy, auth_id_hash]` (PER-only). Its existence is the replay guard. */
+export function deriveReservationAddress(policy, authIdHash, programId) {
+    return pda([utf8(CARD_SEEDS.reservation), publicKey(policy).toBytes(), bytes32(authIdHash, "authIdHash")], resolveCardPolicyProgramId(programId));
+}
+/** `["auth_guard", policy]` (PER-only): replay guard for closed reservations. */
+export function deriveAuthGuardAddress(policy, programId) {
+    return pda([utf8(CARD_SEEDS.authGuard), publicKey(policy).toBytes()], resolveCardPolicyProgramId(programId));
+}
+/** `["intent", policy, intent_id]` (PER-only); intent_id is 16 bytes. */
+export function deriveCheckoutIntentAddress(policy, intentId, programId) {
+    if (intentId.length !== 16)
+        throw new Error("intentId must be exactly 16 bytes");
+    return pda([utf8(CARD_SEEDS.intent), publicKey(policy).toBytes(), new Uint8Array(intentId)], resolveCardPolicyProgramId(programId));
+}
+/** `["card_commit", binding]` (base, public, never delegated). */
+export function deriveCardCommitmentAddress(binding, programId) {
+    return pda([utf8(CARD_SEEDS.commitment), publicKey(binding).toBytes()], resolveCardPolicyProgramId(programId));
+}
+/**
+ * `["repay_agent", binding]` (base, system-owned, lamport-only). The owner's ChainPay
+ * repayment mandate names it as `approved_agent`; it signs only inside `repay_statement`.
+ */
+export function deriveRepayAgentAddress(binding, programId) {
+    return pda([utf8(CARD_SEEDS.repayAgent), publicKey(binding).toBytes()], resolveCardPolicyProgramId(programId));
+}
+/** MagicBlock permission PDA for a private account: `["permission:", account]` under the permission program. */
+export function derivePermissionAddress(account) {
+    return pda([utf8("permission:"), publicKey(account).toBytes()], PERMISSION_PROGRAM_ID);
+}
+/** Delegation-program escrow that pays for the card's Magic Actions: `["balance", policy, 255]`. */
+export function deriveCardEscrowAddress(escrowAuthority, index = 255) {
+    if (!Number.isInteger(index) || index < 0 || index > 255)
+        throw new Error("escrow index must be 0..255");
+    return pda([utf8("balance"), publicKey(escrowAuthority).toBytes(), Uint8Array.of(index)], DELEGATION_PROGRAM_ID);
+}
+export function deriveDelegationBufferAddress(account, programId) {
+    return pda([utf8("buffer"), publicKey(account).toBytes()], resolveCardPolicyProgramId(programId));
+}
+export function deriveDelegationRecordAddress(account) {
+    return pda([utf8("delegation"), publicKey(account).toBytes()], DELEGATION_PROGRAM_ID);
+}
+export function deriveDelegationMetadataAddress(account) {
+    return pda([utf8("delegation-metadata"), publicKey(account).toBytes()], DELEGATION_PROGRAM_ID);
+}
+export function deriveMagicFeeVaultAddress(validator) {
+    return pda([utf8("magic-fee-vault"), publicKey(validator).toBytes()], DELEGATION_PROGRAM_ID);
+}
+/** Every address one card owns, from the owner wallet and the 32-byte card id. */
+export function deriveCardAccounts(owner, cardId, programId) {
+    const binding = deriveCardBindingAddress(owner, cardId, programId);
+    const policy = deriveCardPolicyAddress(binding, programId);
+    const period = deriveCardPeriodAddress(binding, programId);
+    return {
+        binding,
+        policy,
+        period,
+        commitment: deriveCardCommitmentAddress(binding, programId),
+        escrow: deriveCardEscrowAddress(policy),
+        policyPermission: derivePermissionAddress(policy),
+        periodPermission: derivePermissionAddress(period),
+    };
+}
+/** Card ids travel as 64-char lowercase hex (Convex key `card:<cardId hex>`). */
+export function cardIdFromHex(value) {
+    const hex = value.trim().toLowerCase().replace(/^0x/, "");
+    if (!/^[0-9a-f]{64}$/.test(hex))
+        throw new Error("cardId must be 32 bytes of hex");
+    return Uint8Array.from({ length: 32 }, (_, i) => Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16));
+}
+export function cardIdToHex(cardId) {
+    return Array.from(bytes32(cardId, "cardId"), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/cards/private-repayment.d.ts

@@ -0,0 +1,198 @@
+export declare const MAGICBLOCK_PAYMENTS_API = "https://payments.magicblock.app";
+export declare const PRIVATE_REPAYMENT_METHOD = "magicblock_private_payments";
+export declare const PRIVATE_REPAYMENT_DEVNET_USDC = "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
+export declare const EPHEMERAL_SPL_PROGRAM = "SPLxh1LVZzEkX99H6rqYizhytLWPZVV296zyYDPagv2";
+export type PrivateRepaymentAttempt = {
+    attemptId: string;
+    state: "awaiting_settlement" | "verified" | "mismatch";
+    method: typeof PRIVATE_REPAYMENT_METHOD;
+    statementId: string;
+    cluster: "devnet";
+    apiCluster: "devnet-private";
+    api: string;
+    mint: string;
+    amountCents: string;
+    amountBaseUnits: string;
+    recipientWallet: string;
+    recipientTokenAccount: string;
+    clientRefId: string;
+    transfer: {
+        visibility: "private";
+        fromBalance: "ephemeral";
+        toBalance: "base";
+        split: 1;
+        exactOut: true;
+        minDelayMs: string;
+        maxDelayMs: string;
+        memo: null;
+    };
+    vault: {
+        program: string;
+        vault: string;
+        vaultTokenAccount: string;
+        custody: string;
+    };
+    verification: {
+        kind: "magicblock_queue_settlement";
+        commitment: "finalized";
+        checks: string[];
+        notVerifiable: string[];
+        public: string[];
+        hidden: string[];
+    };
+    label: string;
+};
+export type PrivateRepaymentResult = {
+    state: "discharged" | "partner_confirmed" | "repayment_observed";
+    statement: unknown;
+} | {
+    state: "repayment_mismatch";
+    mismatch: string[];
+    statement: unknown;
+};
+export declare class PrivateRepaymentError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(status: number, code: string, message: string, retryable?: boolean);
+}
+type Fetch = typeof fetch;
+/** Refuse anything but the Devnet USDC private route ChainPay verifies. */
+export declare function assertPayableAttempt(attempt: PrivateRepaymentAttempt): void;
+/**
+ * The vault and deposit model in plain words, for the opt-in step. Every line
+ * is true of the route this module pays through; none claims more than
+ * ChainPay verifies.
+ */
+export declare function privateRepaymentDisclosure(attempt: Pick<PrivateRepaymentAttempt, "amountBaseUnits" | "amountCents">): string[];
+export type ChainPayRoutesOptions = {
+    /** Axum base URL, e.g. https://relay.example. */
+    baseUrl: string;
+    /** Owner session bearer. Never an MCP connection: agents can't repay. */
+    ownerSession: string;
+    fetch?: Fetch;
+};
+/** Get or create the open attempt (idempotent). */
+export declare function preparePrivateRepayment(opts: ChainPayRoutesOptions, cardId: string, statementId: string, clientOperationId: string): Promise<PrivateRepaymentAttempt>;
+/**
+ * Ask ChainPay to verify the settlement. A `settlement_pending` error is
+ * retryable: MagicBlock's queue pays out after the transfer, usually within
+ * seconds.
+ */
+export declare function submitPrivateRepayment(opts: ChainPayRoutesOptions, cardId: string, statementId: string, attemptId: string): Promise<PrivateRepaymentResult>;
+/** Poll `submit` until the settlement is found (or `timeoutMs` passes). */
+export declare function waitForPrivateRepayment(opts: ChainPayRoutesOptions, cardId: string, statementId: string, attemptId: string, { timeoutMs, intervalMs, sleep }?: {
+    timeoutMs?: number | undefined;
+    intervalMs?: number | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+}): Promise<PrivateRepaymentResult>;
+/** The owner's wallet. Transactions travel as base64 wire bytes. */
+export type PrivateRepaymentSigner = {
+    publicKey: string;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+    /** Sign (not send) a serialized transaction; return the signed base64. */
+    signTransaction(transactionBase64: string): Promise<string>;
+};
+export type MagicBlockOptions = {
+    api?: string;
+    fetch?: Fetch;
+};
+type Built = {
+    kind: string;
+    transactionBase64: string;
+    sendTo: "base" | "ephemeral";
+    sendRpcEndpoint?: string;
+    recentBlockhash: string;
+    lastValidBlockHeight: number;
+    requiredSigners: string[];
+    fees?: {
+        lamports: string;
+        tokens: string;
+    };
+};
+/**
+ * Wallet challenge login for private reads and rollup sends. The token lives
+ * in memory only: never store it, log it or send it to ChainPay.
+ */
+export declare function magicblockLogin(signer: PrivateRepaymentSigner, opts?: MagicBlockOptions): Promise<string>;
+export declare function privateBalance(owner: string, mint: string, token: string, opts?: MagicBlockOptions): Promise<bigint>;
+type DecodedInstruction = {
+    programId: string;
+    accounts: string[];
+    data: Uint8Array;
+};
+type DecodedTransaction = {
+    signers: string[];
+    instructions: DecodedInstruction[];
+};
+/**
+ * Decode a serialized legacy (or v0 without lookup tables) transaction: its
+ * signers and every instruction with resolved account keys. Lookup tables
+ * can't be checked offline, so they are refused.
+ */
+export declare function decodeBuiltTransaction(base64: string): DecodedTransaction;
+/**
+ * Before the owner signs a MagicBlock-built transaction, check it does
+ * exactly what the statement says (review F1): only the expected programs,
+ * the owner as the only signer, and the one amount-bearing instruction moving
+ * the expected amount of the attempt's mint (to the attempt's recipient, for
+ * the transfer).
+ */
+export declare function verifyBuiltTransaction(built: Pick<Built, "transactionBase64">, expect: {
+    kind: "deposit" | "transfer";
+    owner: string;
+    mint: string;
+    amountBaseUnits: bigint;
+    recipientWallet?: string;
+    clientRefId?: string;
+    minDelayMs?: string;
+    maxDelayMs?: string;
+}): void;
+export type PayStep = {
+    step: "login";
+} | {
+    step: "balance";
+    privateBalance: string;
+} | {
+    step: "deposit";
+    amountBaseUnits: string;
+    signature?: string;
+} | {
+    step: "transfer";
+    signature?: string;
+    outcome: "sent" | "unknown";
+};
+export type PayPrivatelyInput = {
+    attempt: PrivateRepaymentAttempt;
+    signer: PrivateRepaymentSigner;
+    /**
+     * Submit a signed base-layer (Devnet) transaction and resolve with its
+     * signature once confirmed. The browser passes its wallet adapter's
+     * connection; MagicBlock's own send endpoint is the fallback.
+     */
+    sendBase?: (signedBase64: string, built: {
+        recentBlockhash: string;
+        lastValidBlockHeight: number;
+    }) => Promise<string>;
+    onStep?: (step: PayStep) => void;
+    magicblock?: MagicBlockOptions;
+    /** Poll for the deposit to show up as private balance. */
+    waitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Pay the attempt privately: deposit any shortfall into MagicBlock's vault,
+ * then one private transfer to the partner tagged with the attempt reference.
+ * Call only after the owner opted in on `privateRepaymentDisclosure`.
+ *
+ * A rollup send can report an error even though the transfer landed (seen
+ * live on Devnet: "block height exceeded" for a transfer that settled), so a
+ * failed transfer send resolves as `outcome: "unknown"`; ask ChainPay
+ * (`waitForPrivateRepayment`) before paying again.
+ */
+export declare function payStatementPrivately(input: PayPrivatelyInput): Promise<{
+    depositSignature?: string;
+    transferSignature?: string;
+    transferOutcome: "sent" | "unknown";
+}>;
+export {};