@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/commitment.d.ts

@@ -0,0 +1,86 @@
+import type { Address } from "../types.js";
+import type { CardCommitment, CardPeriod, CardPolicy } from "./accounts.js";
+export declare const COMMITMENT_LEAF_COUNT = 16;
+export type CommitmentLeafIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
+export type DisclosedLeaf = {
+    i: number;
+    /** hex of the leaf's value bytes. */
+    value: string;
+    /** hex of sha256(master_salt || i). Reveals nothing about other leaves. */
+    leafSalt: string;
+    /** 4 sibling hashes (hex), bottom-up. */
+    proof: string[];
+};
+export type DisclosureBundle = {
+    v: 1;
+    /** CardBinding address (base58); the commitment PDA is derived from it. */
+    binding: Address;
+    commitmentSeq: string;
+    leaves: DisclosedLeaf[];
+    /** Reserved by contracts §9; not produced or checked by this version. */
+    ledger?: {
+        eventBytes: string;
+        subsequentHashes: string[];
+    };
+};
+/** Leaf value bytes, fixed per index (hashes.rs `leaf_values`). */
+export declare function commitmentLeafValues(policy: CardPolicy, period: CardPeriod): Promise<Uint8Array[]>;
+export declare function leafSalt(masterSalt: Uint8Array, index: number): Promise<Uint8Array>;
+export declare function leafHash(index: number, salt: Uint8Array, value: Uint8Array): Promise<Uint8Array>;
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Promise<Uint8Array>;
+/** Root for the given policy, period and checkpoint salt (hashes.rs `commitment_root`). */
+export declare function commitmentRoot(policy: CardPolicy, period: CardPeriod, masterSalt: Uint8Array): Promise<Uint8Array>;
+/** Owner side: disclose only the picked leaves. `masterSalt` comes from the owner's encrypted recovery record. */
+export declare function buildDisclosureBundle(input: {
+    policy: CardPolicy;
+    period: CardPeriod;
+    masterSalt: Uint8Array;
+    commitmentSeq: bigint;
+    indices: readonly number[];
+}): Promise<DisclosureBundle>;
+/** `/verify/card#disclose=<base64url(JSON)>`. The fragment never reaches a server. */
+export declare function encodeDisclosureFragment(bundle: DisclosureBundle): string;
+/** Strict parse: unknown shapes are rejected, never partially trusted. */
+export declare function decodeDisclosureFragment(fragment: string): DisclosureBundle;
+export type DisclosureLeafCheck = {
+    i: number;
+    ok: boolean;
+    field: CommitmentFieldView;
+};
+export type DisclosureCheck = {
+    state: "verified";
+    seq: string;
+    root: string;
+    writtenSlot: string;
+    leaves: DisclosureLeafCheck[];
+} | {
+    state: "mismatch";
+    seq: string;
+    root: string;
+    writtenSlot: string;
+    leaves: DisclosureLeafCheck[];
+} | {
+    state: "superseded";
+    bundleSeq: string;
+    chainSeq: string;
+    leaves: DisclosureLeafCheck[];
+} | {
+    state: "wrong_card";
+    leaves: DisclosureLeafCheck[];
+};
+export declare function recomputeDisclosedRoot(leaf: DisclosedLeaf): Promise<Uint8Array>;
+/**
+ * Check every disclosed field against the public commitment account. The
+ * commitment holds only its latest root, so a record from an older checkpoint
+ * is reported as superseded rather than guessed at.
+ */
+export declare function verifyDisclosureBundle(bundle: DisclosureBundle, commitment: CardCommitment): Promise<DisclosureCheck>;
+export type CommitmentFieldView = {
+    i: number;
+    label: string;
+    value: string;
+    detail?: string;
+};
+export declare const COMMITMENT_FIELD_LABELS: Record<number, string>;
+/** Human-readable value for one leaf. Exact cents; malformed bytes say so instead of guessing. */
+export declare function describeCommitmentLeaf(i: number, value: Uint8Array): CommitmentFieldView;

package/dist/cards/commitment.js

@@ -0,0 +1,288 @@
+import { PublicKey } from "@solana/web3.js";
+import { formatFeeBps, formatUsdCents } from "./math.js";
+/*
+ * Salted commitment leaves and single-field disclosure (contracts.md §1.6, §9).
+ *
+ * Byte layouts mirror programs/card_policy/src/hashes.rs exactly. The owner
+ * builds a disclosure bundle for the fields they pick; anyone recomputes the
+ * leaf and its Merkle path against the public CardCommitment root. This is an
+ * integrity check against ChainPay's on-chain commitment, not a zero-knowledge
+ * proof: the disclosed values are shown in the clear.
+ */
+export const COMMITMENT_LEAF_COUNT = 16;
+const LEAF_DOMAIN = "chainpay-card-leaf:v1\n";
+const DISCLOSURE_PARAM = "disclose";
+// --------------------------------------------------------------- bytes
+const enc = new TextEncoder();
+async function sha256(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        joined.set(part, offset);
+        offset += part.length;
+    }
+    return new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", joined.buffer));
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(value) {
+    if (typeof value !== "string" || value.length % 2 !== 0 || !/^[0-9a-f]*$/.test(value))
+        throw new Error("Expected lowercase hex");
+    return Uint8Array.from(value.match(/../g) ?? [], (pair) => parseInt(pair, 16));
+}
+function le(value, bytes, signed = false) {
+    const out = new Uint8Array(bytes);
+    const view = new DataView(out.buffer);
+    if (bytes === 2)
+        view.setUint16(0, Number(value), true);
+    else if (bytes === 4)
+        view.setUint32(0, Number(value), true);
+    else if (signed)
+        view.setBigInt64(0, value, true);
+    else
+        view.setBigUint64(0, value, true);
+    return out;
+}
+function cat(...parts) {
+    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function compareBytes(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return a.length - b.length;
+}
+const RECOVERY_BYTE = { normal: 0, recovery_frozen: 1, restored_pending_reconcile: 2 };
+// --------------------------------------------------------------- leaves
+/** Leaf value bytes, fixed per index (hashes.rs `leaf_values`). */
+export async function commitmentLeafValues(policy, period) {
+    const merchants = [...policy.merchantIdHashes].sort(compareBytes);
+    const mccs = [...policy.mccs].sort((a, b) => a - b);
+    return [
+        new PublicKey(policy.binding).toBytes(),
+        le(BigInt(policy.policyVersion), 4),
+        le(policy.budgetCents, 8),
+        le(policy.maxPurchaseCents, 8),
+        le(BigInt(policy.maxPurchasesPerPeriod), 2),
+        await sha256(...merchants),
+        await sha256(cat(...mccs.map((mcc) => le(BigInt(mcc), 2)))),
+        cat(le(policy.expiresAt, 8, true), Uint8Array.of(policy.recurringAllowed ? 1 : 0), le(BigInt(policy.feeBps), 2)),
+        cat(le(BigInt(period.periodIndex), 4), le(period.periodStart, 8, true), le(period.periodEnd, 8, true)),
+        le(period.capturedCents, 8),
+        le(period.reservedCents, 8),
+        le(period.refundedCents, 8),
+        le(BigInt(period.purchasesCount), 2),
+        le(policy.statementOutstandingCents, 8),
+        Uint8Array.of(policy.frozen ? 1 : 0, RECOVERY_BYTE[policy.recoveryState]),
+        cat(policy.ledgerHead, le(policy.ledgerSeq, 8)),
+    ];
+}
+export function leafSalt(masterSalt, index) {
+    if (masterSalt.length !== 32)
+        throw new Error("master salt must be 32 bytes");
+    return sha256(masterSalt, Uint8Array.of(index));
+}
+export function leafHash(index, salt, value) {
+    return sha256(enc.encode(LEAF_DOMAIN), Uint8Array.of(index), salt, value);
+}
+export function nodeHash(left, right) {
+    return sha256(Uint8Array.of(1), left, right);
+}
+async function levels(leaves) {
+    if (leaves.length !== COMMITMENT_LEAF_COUNT)
+        throw new Error(`a commitment has exactly ${COMMITMENT_LEAF_COUNT} leaves`);
+    const out = [leaves];
+    while (out[out.length - 1].length > 1) {
+        const level = out[out.length - 1];
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(await nodeHash(level[i], level[i + 1]));
+        out.push(next);
+    }
+    return out;
+}
+/** Root for the given policy, period and checkpoint salt (hashes.rs `commitment_root`). */
+export async function commitmentRoot(policy, period, masterSalt) {
+    const values = await commitmentLeafValues(policy, period);
+    const leaves = await Promise.all(values.map(async (value, i) => leafHash(i, await leafSalt(masterSalt, i), value)));
+    const tree = await levels(leaves);
+    return tree[tree.length - 1][0];
+}
+/** Owner side: disclose only the picked leaves. `masterSalt` comes from the owner's encrypted recovery record. */
+export async function buildDisclosureBundle(input) {
+    const indices = [...new Set(input.indices)].sort((a, b) => a - b);
+    if (indices.length === 0)
+        throw new Error("Pick at least one field to share");
+    if (indices.some((i) => !Number.isInteger(i) || i < 0 || i >= COMMITMENT_LEAF_COUNT))
+        throw new Error("Unknown field");
+    const values = await commitmentLeafValues(input.policy, input.period);
+    const salts = await Promise.all(values.map((_, i) => leafSalt(input.masterSalt, i)));
+    const leaves = await Promise.all(values.map((value, i) => leafHash(i, salts[i], value)));
+    const tree = await levels(leaves);
+    return {
+        v: 1,
+        binding: new PublicKey(input.policy.binding).toBase58(),
+        commitmentSeq: input.commitmentSeq.toString(),
+        leaves: indices.map((i) => {
+            const proof = [];
+            let idx = i;
+            for (let depth = 0; depth < tree.length - 1; depth += 1) {
+                proof.push(bytesToHex(tree[depth][idx ^ 1]));
+                idx >>= 1;
+            }
+            return { i, value: bytesToHex(values[i]), leafSalt: bytesToHex(salts[i]), proof };
+        }),
+    };
+}
+// --------------------------------------------------------------- fragment
+function toBase64Url(text) {
+    let binary = "";
+    for (const byte of enc.encode(text))
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+    const binary = globalThis.atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+/** `/verify/card#disclose=<base64url(JSON)>`. The fragment never reaches a server. */
+export function encodeDisclosureFragment(bundle) {
+    return `${DISCLOSURE_PARAM}=${toBase64Url(JSON.stringify(bundle))}`;
+}
+/** Strict parse: unknown shapes are rejected, never partially trusted. */
+export function decodeDisclosureFragment(fragment) {
+    const match = fragment.match(/(?:^#?|&)disclose=([A-Za-z0-9_-]+)/);
+    if (!match)
+        throw new Error("No shared card record in this link");
+    let raw;
+    try {
+        raw = JSON.parse(fromBase64Url(match[1]));
+    }
+    catch {
+        throw new Error("The shared card record in this link can't be read");
+    }
+    if (raw.v !== 1)
+        throw new Error("Unsupported card record version");
+    if (typeof raw.binding !== "string")
+        throw new Error("The card record has no card link");
+    new PublicKey(raw.binding);
+    if (typeof raw.commitmentSeq !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(raw.commitmentSeq))
+        throw new Error("The card record has no commitment number");
+    if (!Array.isArray(raw.leaves) || raw.leaves.length === 0 || raw.leaves.length > COMMITMENT_LEAF_COUNT)
+        throw new Error("The card record has no fields");
+    const seen = new Set();
+    const leaves = raw.leaves.map((leaf) => {
+        if (!leaf || !Number.isInteger(leaf.i) || leaf.i < 0 || leaf.i >= COMMITMENT_LEAF_COUNT || seen.has(leaf.i))
+            throw new Error("The card record has an unknown field");
+        seen.add(leaf.i);
+        hexToBytes(leaf.value);
+        if (hexToBytes(leaf.leafSalt).length !== 32)
+            throw new Error("A field's salt has the wrong length");
+        if (!Array.isArray(leaf.proof) || leaf.proof.length !== 4 || leaf.proof.some((node) => typeof node !== "string" || hexToBytes(node).length !== 32))
+            throw new Error("A field's proof has the wrong shape");
+        return { i: leaf.i, value: leaf.value, leafSalt: leaf.leafSalt, proof: [...leaf.proof] };
+    });
+    return { v: 1, binding: raw.binding, commitmentSeq: raw.commitmentSeq, leaves };
+}
+export async function recomputeDisclosedRoot(leaf) {
+    let acc = await leafHash(leaf.i, hexToBytes(leaf.leafSalt), hexToBytes(leaf.value));
+    let idx = leaf.i;
+    for (const sibling of leaf.proof) {
+        const node = hexToBytes(sibling);
+        acc = idx % 2 === 0 ? await nodeHash(acc, node) : await nodeHash(node, acc);
+        idx >>= 1;
+    }
+    return acc;
+}
+/**
+ * Check every disclosed field against the public commitment account. The
+ * commitment holds only its latest root, so a record from an older checkpoint
+ * is reported as superseded rather than guessed at.
+ */
+export async function verifyDisclosureBundle(bundle, commitment) {
+    const described = bundle.leaves.map((leaf) => ({ i: leaf.i, ok: false, field: describeCommitmentLeaf(leaf.i, hexToBytes(leaf.value)) }));
+    if (new PublicKey(commitment.binding).toBase58() !== new PublicKey(bundle.binding).toBase58())
+        return { state: "wrong_card", leaves: described };
+    const bindingLeaf = bundle.leaves.find((leaf) => leaf.i === 0);
+    if (bindingLeaf && bindingLeaf.value !== bytesToHex(new PublicKey(bundle.binding).toBytes()))
+        return { state: "wrong_card", leaves: described };
+    if (commitment.seq.toString() !== bundle.commitmentSeq) {
+        return { state: "superseded", bundleSeq: bundle.commitmentSeq, chainSeq: commitment.seq.toString(), leaves: described };
+    }
+    const root = bytesToHex(commitment.root);
+    const leaves = await Promise.all(bundle.leaves.map(async (leaf, n) => ({ ...described[n], ok: bytesToHex(await recomputeDisclosedRoot(leaf)) === root })));
+    const base = { seq: commitment.seq.toString(), root, writtenSlot: commitment.writtenSlot.toString(), leaves };
+    return leaves.every((leaf) => leaf.ok) ? { state: "verified", ...base } : { state: "mismatch", ...base };
+}
+export const COMMITMENT_FIELD_LABELS = {
+    0: "Card",
+    1: "Rules version",
+    2: "Budget per period",
+    3: "Max per purchase",
+    4: "Purchases allowed per period",
+    5: "Shop list fingerprint",
+    6: "Category list fingerprint",
+    7: "End date and fee",
+    8: "Period",
+    9: "Charged this period",
+    10: "Held right now",
+    11: "Refunded this period",
+    12: "Purchases this period",
+    13: "Owed on the statement",
+    14: "Frozen",
+    15: "Activity log position",
+};
+function readLe(bytes, offset, size, signed = false) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (size === 2)
+        return BigInt(view.getUint16(offset, true));
+    if (size === 4)
+        return BigInt(view.getUint32(offset, true));
+    return signed ? view.getBigInt64(offset, true) : view.getBigUint64(offset, true);
+}
+function dateFromSeconds(seconds) {
+    const ms = Number(seconds) * 1000;
+    return Number.isFinite(ms) && Math.abs(ms) <= 8.64e15 ? new Date(ms).toISOString().slice(0, 10) : `unix ${seconds}`;
+}
+const EXPECTED_LENGTH = { 0: 32, 1: 4, 2: 8, 3: 8, 4: 2, 5: 32, 6: 32, 7: 11, 8: 20, 9: 8, 10: 8, 11: 8, 12: 2, 13: 8, 14: 2, 15: 40 };
+/** Human-readable value for one leaf. Exact cents; malformed bytes say so instead of guessing. */
+export function describeCommitmentLeaf(i, value) {
+    const label = COMMITMENT_FIELD_LABELS[i] ?? `Field ${i}`;
+    if (value.length !== EXPECTED_LENGTH[i])
+        return { i, label, value: "Unreadable value" };
+    const cents = (offset = 0) => formatUsdCents(readLe(value, offset, 8));
+    switch (i) {
+        case 0: return { i, label, value: new PublicKey(value).toBase58() };
+        case 1: return { i, label, value: `Version ${readLe(value, 0, 4)}` };
+        case 2:
+        case 3:
+        case 9:
+        case 10:
+        case 11:
+        case 13: return { i, label, value: cents() };
+        case 4: {
+            const n = readLe(value, 0, 2);
+            return { i, label, value: n === 0n ? "No count limit" : n.toString() };
+        }
+        case 12: return { i, label, value: readLe(value, 0, 2).toString() };
+        case 5:
+        case 6: return { i, label, value: bytesToHex(value).slice(0, 16), detail: bytesToHex(value) };
+        case 7: {
+            const end = readLe(value, 0, 8, true);
+            const fee = Number(readLe(value, 9, 2));
+            return { i, label, value: `${end === 0n ? "No end date" : `Ends ${dateFromSeconds(end)}`} · fee ${fee <= 1000 ? formatFeeBps(fee) : `${fee} bps`}`, detail: value[8] ? "Repeat charges allowed" : "No repeat charges" };
+        }
+        case 8: return { i, label, value: `Period ${readLe(value, 0, 4)}`, detail: `${dateFromSeconds(readLe(value, 4, 8, true))} to ${dateFromSeconds(readLe(value, 12, 8, true))}` };
+        case 14: return { i, label, value: value[0] ? "Frozen" : "Not frozen", detail: ["Normal", "Frozen for recovery", "Restored, waiting for confirmation"][value[1]] ?? "Unknown recovery state" };
+        case 15: return { i, label, value: `Event ${readLe(value, 32, 8)}`, detail: bytesToHex(value.slice(0, 32)) };
+        default: return { i, label, value: bytesToHex(value) };
+    }
+}

package/dist/cards/constants.d.ts

@@ -0,0 +1,160 @@
+import type { Address } from "../types.js";
+/**
+ * card_policy program ID on Devnet (contracts.md Changelog, Lane 1 / 1A;
+ * `address` in programs/card_policy/idl/card_policy.json). Every builder and
+ * PDA helper takes an explicit `programId` and falls back to this value.
+ */
+export declare const CARD_POLICY_PROGRAM_ID: Address;
+export declare function resolveCardPolicyProgramId(programId?: Address): Address;
+/** MagicBlock Devnet TEE (Private Ephemeral Rollup). Tokens go in the query string; never log the full URL. */
+export declare const DEVNET_TEE_URL = "https://devnet-tee.magicblock.app";
+export declare const DEVNET_TEE_WS_URL = "wss://devnet-tee.magicblock.app";
+/** The only validator `delegate_card` accepts on Devnet (contracts.md §1). */
+export declare const DEVNET_TEE_VALIDATOR: Address;
+export declare const TEE_VALIDATOR_ALLOWLIST: readonly Address[];
+export declare const DELEGATION_PROGRAM_ID: Address;
+export declare const MAGIC_PROGRAM_ID: Address;
+export declare const MAGIC_CONTEXT_ID: Address;
+export declare const PERMISSION_PROGRAM_ID: Address;
+export declare const EPHEMERAL_VAULT_ID: Address;
+export declare const CARD_SEEDS: {
+    readonly binding: "card_binding";
+    readonly policy: "card_policy";
+    readonly period: "card_period";
+    readonly reservation: "res";
+    readonly intent: "intent";
+    readonly commitment: "card_commit";
+    /** Per-card replay guard for closed reservations (PER only). */
+    readonly authGuard: "auth_guard";
+    /** Lamport-only base PDA: the `approved_agent` of the owner's repayment mandate. */
+    readonly repayAgent: "repay_agent";
+};
+export declare const MAX_MERCHANTS = 8;
+export declare const MAX_MCCS = 16;
+/** owner + authorizer + 4 finance readers. */
+export declare const MAX_MEMBERS = 6;
+/** $10,000 sandbox cap on any budget (contracts.md §1.3 #6). */
+export declare const MAX_BUDGET_CENTS = 1000000n;
+export declare const MIN_PERIOD_SECONDS = 86400;
+export declare const MAX_FEE_BPS = 1000;
+/** A checkout intent may live at most 10 minutes. */
+export declare const MAX_INTENT_TTL_SECONDS = 600;
+export declare const CARD_ISSUER: {
+    readonly lithic_sandbox: 1;
+    readonly card_sim: 2;
+};
+/** EphemeralPermission member flags used by card_policy (MagicBlock permission program). */
+export declare const PERMISSION_FLAGS: {
+    readonly AUTHORITY: 1;
+    readonly TX_LOGS: 2;
+    readonly TX_BALANCES: 4;
+    readonly TX_MESSAGE: 8;
+};
+/** Anchor instruction discriminators: sha256("global:<name>")[0..8]. */
+export declare const CARD_POLICY_DISCRIMINATORS: {
+    readonly initCard: Uint8Array<ArrayBuffer>;
+    readonly delegateCard: Uint8Array<ArrayBuffer>;
+    readonly initPermission: Uint8Array<ArrayBuffer>;
+    readonly updatePermission: Uint8Array<ArrayBuffer>;
+    readonly syncPermission: Uint8Array<ArrayBuffer>;
+    readonly setPolicy: Uint8Array<ArrayBuffer>;
+    readonly openCheckoutIntent: Uint8Array<ArrayBuffer>;
+    readonly cancelCheckoutIntent: Uint8Array<ArrayBuffer>;
+    readonly closeCheckoutIntent: Uint8Array<ArrayBuffer>;
+    readonly authorize: Uint8Array<ArrayBuffer>;
+    readonly adjustReservation: Uint8Array<ArrayBuffer>;
+    readonly capture: Uint8Array<ArrayBuffer>;
+    readonly reverse: Uint8Array<ArrayBuffer>;
+    readonly refund: Uint8Array<ArrayBuffer>;
+    readonly recordDispute: Uint8Array<ArrayBuffer>;
+    readonly recordException: Uint8Array<ArrayBuffer>;
+    readonly resolveException: Uint8Array<ArrayBuffer>;
+    readonly rollPeriod: Uint8Array<ArrayBuffer>;
+    readonly freeze: Uint8Array<ArrayBuffer>;
+    readonly unfreeze: Uint8Array<ArrayBuffer>;
+    readonly recoveryFreeze: Uint8Array<ArrayBuffer>;
+    readonly restore: Uint8Array<ArrayBuffer>;
+    readonly confirmReconciled: Uint8Array<ArrayBuffer>;
+    readonly checkpoint: Uint8Array<ArrayBuffer>;
+    readonly writeCommitment: Uint8Array<ArrayBuffer>;
+    readonly wipeCard: Uint8Array<ArrayBuffer>;
+    readonly closeCard: Uint8Array<ArrayBuffer>;
+    readonly recordRepayment: Uint8Array<ArrayBuffer>;
+    readonly closeReservation: Uint8Array<ArrayBuffer>;
+    /** Base layer: the card's repay agent pays a statement by ChainPay `execute_payment` CPI. */
+    readonly repayStatement: Uint8Array<ArrayBuffer>;
+    /** PER: MagicBlock private payment, authorizer-attested (no ChainPay receipt). */
+    readonly recordPrivateRepayment: Uint8Array<ArrayBuffer>;
+};
+export type CardPolicyInstructionName = keyof typeof CARD_POLICY_DISCRIMINATORS;
+/** Anchor account discriminators: sha256("account:<Name>")[0..8]. */
+export declare const CARD_ACCOUNT_DISCRIMINATORS: {
+    readonly cardBinding: Uint8Array<ArrayBuffer>;
+    readonly cardPolicy: Uint8Array<ArrayBuffer>;
+    readonly cardPeriod: Uint8Array<ArrayBuffer>;
+    readonly reservation: Uint8Array<ArrayBuffer>;
+    readonly checkoutIntent: Uint8Array<ArrayBuffer>;
+    readonly cardCommitment: Uint8Array<ArrayBuffer>;
+    /** Zero-copy, 8 KB: the last 256 closed reservations' auth ids. */
+    readonly authGuard: Uint8Array<ArrayBuffer>;
+};
+/** `CardPolicyError` codes (contracts.md §1.4). Append only. */
+export declare const CARD_POLICY_ERRORS: {
+    readonly 6000: "Unauthorized";
+    readonly 6001: "ValidatorNotAllowed";
+    readonly 6002: "PolicyNotSet";
+    readonly 6003: "InvalidPolicy";
+    readonly 6004: "CardFrozen";
+    readonly 6005: "RecoveryFrozen";
+    readonly 6006: "PolicyExpired";
+    readonly 6007: "IntentInvalid";
+    readonly 6008: "IntentExpired";
+    readonly 6009: "IntentStale";
+    readonly 6010: "MerchantMismatch";
+    readonly 6011: "MerchantNotAllowed";
+    readonly 6012: "MccNotAllowed";
+    readonly 6013: "CurrencyMismatch";
+    readonly 6014: "AmountExceedsIntent";
+    readonly 6015: "AmountExceedsMax";
+    readonly 6016: "BudgetExceeded";
+    readonly 6017: "VelocityExceeded";
+    readonly 6018: "RecurringNotAllowed";
+    readonly 6019: "DuplicateAuthorization";
+    readonly 6020: "DuplicateCapture";
+    readonly 6021: "ReservationClosed";
+    readonly 6022: "PeriodNotEnded";
+    readonly 6023: "DisclosureBlocked";
+    readonly 6024: "MemberLimit";
+    readonly 6025: "ExceptionsOpen";
+    readonly 6026: "NotInRecovery";
+    readonly 6027: "StaleCommitment";
+    readonly 6028: "OpenReservations";
+    readonly 6029: "OutstandingBalance";
+    readonly 6030: "MathOverflow";
+    readonly 6031: "AuthorizerChangeRequiresFreeze";
+    readonly 6032: "DuplicateRepayment";
+    readonly 6033: "MemberNotFound";
+    readonly 6034: "PermissionNotInitialized";
+    readonly 6035: "InvalidAmount";
+    readonly 6036: "NoOpenExceptions";
+    readonly 6037: "ReconDigestMismatch";
+    readonly 6038: "RepaymentExceedsOutstanding";
+    readonly 6039: "InvalidAccount";
+    readonly 6040: "PrefundTooLow";
+    readonly 6041: "NotWiped";
+    readonly 6042: "InvalidEventId";
+    readonly 6043: "DuplicateEvent";
+    readonly 6044: "EphemeralAccountsOpen";
+    readonly 6045: "ReservationNotFinal";
+    readonly 6046: "CoSignerRequired";
+    readonly 6047: "RefundExceedsCapture";
+    readonly 6048: "CaptureLimit";
+    readonly 6049: "BudgetBelowCommitted";
+    readonly 6050: "InvalidRepaymentReceipt";
+    readonly 6051: "RepaymentRecipientMismatch";
+    readonly 6052: "RepaymentExceedsReceipt";
+    readonly 6053: "InvalidRepaymentMandate";
+};
+export type CardPolicyErrorCode = keyof typeof CARD_POLICY_ERRORS;
+export type CardPolicyErrorName = (typeof CARD_POLICY_ERRORS)[CardPolicyErrorCode];
+export declare function cardPolicyErrorName(code: number): CardPolicyErrorName | undefined;