@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/instructions.js

@@ -0,0 +1,474 @@
+import { instruction, meta } from "../encoding.js";
+import { DEFAULT_PROGRAM_ID, SPL_TOKEN_PROGRAM_ID, SYSTEM_PROGRAM_ID } from "../constants.js";
+import { deriveAssetAddress, deriveConfigAddress, deriveReceiptAddress } from "../pda.js";
+import { CARD_POLICY_DISCRIMINATORS, DELEGATION_PROGRAM_ID, EPHEMERAL_VAULT_ID, MAGIC_CONTEXT_ID, MAGIC_PROGRAM_ID, MAX_BUDGET_CENTS, MAX_FEE_BPS, MAX_MCCS, MAX_MERCHANTS, MIN_PERIOD_SECONDS, PERMISSION_PROGRAM_ID, TEE_VALIDATOR_ALLOWLIST, resolveCardPolicyProgramId, } from "./constants.js";
+import { currencyBytes } from "./accounts.js";
+import { BorshReader, BorshWriter } from "./layout.js";
+import { deriveAuthGuardAddress, deriveCardAccounts, deriveCheckoutIntentAddress, deriveDelegationBufferAddress, deriveDelegationMetadataAddress, deriveDelegationRecordAddress, derivePermissionAddress, deriveRepayAgentAddress, deriveReservationAddress, } from "./pda.js";
+/**
+ * Instruction data follows contracts.md §1.3 (Anchor discriminator + Borsh
+ * args in the listed order). Account lists, discriminators and arg layouts
+ * are checked against the deployed program's IDL
+ * (programs/card_policy/idl/card_policy.json, Devnet
+ * H3aetJdQXG8EeJSCHZrpQa8iKHBw8e1p9fSPjTUsB93n) by test/cards-idl.test.mjs,
+ * including the `#[delegate]` macro accounts of `delegate_card`.
+ */
+export const CARD_POLICY_ACCOUNT_ORDER_PROVISIONAL = false;
+const empty = { encode() { }, decode: () => ({}) };
+function writePolicy(w, p) {
+    if (p.merchantIdHashes.length > MAX_MERCHANTS)
+        throw new Error(`At most ${MAX_MERCHANTS} merchants`);
+    if (p.mccs.length > MAX_MCCS)
+        throw new Error(`At most ${MAX_MCCS} MCCs`);
+    w.u64(p.budgetCents, "budgetCents")
+        .u64(p.maxPurchaseCents, "maxPurchaseCents")
+        .u16(p.maxPurchasesPerPeriod, "maxPurchasesPerPeriod")
+        .u32(p.periodSeconds, "periodSeconds")
+        .fixed(currencyBytes(p.currency), 3, "currency")
+        .u32(p.merchantIdHashes.length);
+    p.merchantIdHashes.forEach((hash, i) => w.fixed(hash, 32, `merchantIdHashes[${i}]`));
+    w.u32(p.mccs.length);
+    p.mccs.forEach((mcc, i) => w.u16(mcc, `mccs[${i}]`));
+    w.i64(p.expiresAt, "expiresAt").bool(p.recurringAllowed).u16(p.feeBps, "feeBps").pubkey(p.authorizer);
+}
+function readVecLength(r, max, name) {
+    const length = r.u32(`${name}.length`);
+    if (length > max)
+        throw new Error(`${name} exceeds ${max} entries`);
+    return length;
+}
+function readPolicy(r) {
+    const budgetCents = r.u64("budgetCents");
+    const maxPurchaseCents = r.u64("maxPurchaseCents");
+    const maxPurchasesPerPeriod = r.u16("maxPurchasesPerPeriod");
+    const periodSeconds = r.u32("periodSeconds");
+    const currency = String.fromCharCode(...r.fixed(3, "currency"));
+    const merchantIdHashes = Array.from({ length: readVecLength(r, MAX_MERCHANTS, "merchantIdHashes") }, (_, i) => r.fixed(32, `merchantIdHashes[${i}]`));
+    const mccs = Array.from({ length: readVecLength(r, MAX_MCCS, "mccs") }, (_, i) => r.u16(`mccs[${i}]`));
+    return {
+        budgetCents,
+        maxPurchaseCents,
+        maxPurchasesPerPeriod,
+        periodSeconds,
+        currency,
+        merchantIdHashes,
+        mccs,
+        expiresAt: r.i64("expiresAt"),
+        recurringAllowed: r.bool("recurringAllowed"),
+        feeBps: r.u16("feeBps"),
+        authorizer: r.pubkey("authorizer"),
+    };
+}
+const CODECS = {
+    initCard: {
+        encode: (w, a) => { w.fixed(a.cardId, 32, "cardId").u8(a.issuer, "issuer").fixed(a.issuerCardRefHash, 32, "issuerCardRefHash").u64(a.prefundLamports, "prefundLamports"); },
+        decode: (r) => ({ cardId: r.fixed(32, "cardId"), issuer: r.u8("issuer"), issuerCardRefHash: r.fixed(32, "issuerCardRefHash"), prefundLamports: r.u64("prefundLamports") }),
+    },
+    delegateCard: { encode: (w, a) => { w.pubkey(a.validator); }, decode: (r) => ({ validator: r.pubkey("validator") }) },
+    initPermission: { encode: (w, a) => { w.pubkey(a.authorizer); }, decode: (r) => ({ authorizer: r.pubkey("authorizer") }) },
+    updatePermission: {
+        encode: (w, a) => { w.u8(a.op.kind === "add_reader" ? 0 : a.op.kind === "remove_reader" ? 1 : 255).pubkey(a.op.pubkey); },
+        decode: (r) => {
+            const tag = r.u8("op");
+            if (tag > 1)
+                throw new Error(`Unknown permission op ${tag}`);
+            return { op: { kind: tag === 0 ? "add_reader" : "remove_reader", pubkey: r.pubkey("op.pubkey") } };
+        },
+    },
+    syncPermission: empty,
+    setPolicy: { encode: (w, a) => writePolicy(w, a.policy), decode: (r) => ({ policy: readPolicy(r) }) },
+    openCheckoutIntent: {
+        encode: (w, a) => { w.fixed(a.intentId, 16, "intentId").pubkey(a.agent).fixed(a.merchantIdHash, 32, "merchantIdHash").u16(a.mcc, "mcc").u64(a.maxAmountCents, "maxAmountCents").fixed(currencyBytes(a.currency), 3, "currency").i64(a.expiresAt, "expiresAt"); },
+        decode: (r) => ({ intentId: r.fixed(16, "intentId"), agent: r.pubkey("agent"), merchantIdHash: r.fixed(32, "merchantIdHash"), mcc: r.u16("mcc"), maxAmountCents: r.u64("maxAmountCents"), currency: String.fromCharCode(...r.fixed(3, "currency")), expiresAt: r.i64("expiresAt") }),
+    },
+    cancelCheckoutIntent: empty,
+    closeCheckoutIntent: empty,
+    authorize: {
+        encode: (w, a) => { w.fixed(a.authIdHash, 32, "authIdHash").fixed(a.intentId, 16, "intentId").u64(a.amountCents, "amountCents").fixed(currencyBytes(a.currency), 3, "currency").fixed(a.merchantIdHash, 32, "merchantIdHash").u16(a.mcc, "mcc").bool(a.merchantInitiated).bool(a.singleMessage); },
+        decode: (r) => ({ authIdHash: r.fixed(32, "authIdHash"), intentId: r.fixed(16, "intentId"), amountCents: r.u64("amountCents"), currency: String.fromCharCode(...r.fixed(3, "currency")), merchantIdHash: r.fixed(32, "merchantIdHash"), mcc: r.u16("mcc"), merchantInitiated: r.bool("merchantInitiated"), singleMessage: r.bool("singleMessage") }),
+    },
+    adjustReservation: { encode: (w, a) => { w.u64(a.newAmountCents, "newAmountCents"); }, decode: (r) => ({ newAmountCents: r.u64("newAmountCents") }) },
+    capture: {
+        encode: (w, a) => { w.u64(a.amountCents, "amountCents").fixed(a.captureIdHash, 32, "captureIdHash"); },
+        decode: (r) => ({ amountCents: r.u64("amountCents"), captureIdHash: r.fixed(32, "captureIdHash") }),
+    },
+    reverse: {
+        encode: (w, a) => { w.u64(a.amountCents, "amountCents").u8(a.reason, "reason").fixed(a.eventIdHash, 32, "eventIdHash"); },
+        decode: (r) => ({ amountCents: r.u64("amountCents"), reason: r.u8("reason"), eventIdHash: r.fixed(32, "eventIdHash") }),
+    },
+    refund: {
+        encode: (w, a) => { w.u64(a.amountCents, "amountCents").fixed(a.eventIdHash, 32, "eventIdHash"); },
+        decode: (r) => ({ amountCents: r.u64("amountCents"), eventIdHash: r.fixed(32, "eventIdHash") }),
+    },
+    recordDispute: {
+        encode: (w, a) => { w.u8(a.state, "state").fixed(a.eventIdHash, 32, "eventIdHash"); },
+        decode: (r) => ({ state: r.u8("state"), eventIdHash: r.fixed(32, "eventIdHash") }),
+    },
+    recordException: {
+        encode: (w, a) => { w.u8(a.kind, "kind").u64(a.amountCents, "amountCents").fixed(a.eventIdHash, 32, "eventIdHash"); },
+        decode: (r) => ({ kind: r.u8("kind"), amountCents: r.u64("amountCents"), eventIdHash: r.fixed(32, "eventIdHash") }),
+    },
+    resolveException: {
+        encode: (w, a) => { w.fixed(a.eventIdHash, 32, "eventIdHash").u8(a.resolution, "resolution"); },
+        decode: (r) => ({ eventIdHash: r.fixed(32, "eventIdHash"), resolution: r.u8("resolution") }),
+    },
+    rollPeriod: empty,
+    freeze: { encode: (w, a) => { w.u8(a.reason, "reason"); }, decode: (r) => ({ reason: r.u8("reason") }) },
+    unfreeze: empty,
+    recoveryFreeze: { encode: (w, a) => { w.u8(a.reason, "reason"); }, decode: (r) => ({ reason: r.u8("reason") }) },
+    restore: {
+        encode: (w, a) => {
+            const s = a.restore;
+            writePolicy(w, s.policy);
+            w.u32(s.periodIndex, "periodIndex").u64(s.capturedCents, "capturedCents").u64(s.reservedCents, "reservedCents").u64(s.refundedCents, "refundedCents")
+                .u16(s.purchasesCount, "purchasesCount").u64(s.exceptionCents, "exceptionCents").u64(s.statementOutstandingCents, "statementOutstandingCents")
+                .fixed(s.ledgerHead, 32, "ledgerHead").u64(s.ledgerSeq, "ledgerSeq").fixed(s.reconDigest, 32, "reconDigest");
+        },
+        decode: (r) => ({
+            restore: {
+                policy: readPolicy(r),
+                periodIndex: r.u32("periodIndex"),
+                capturedCents: r.u64("capturedCents"),
+                reservedCents: r.u64("reservedCents"),
+                refundedCents: r.u64("refundedCents"),
+                purchasesCount: r.u16("purchasesCount"),
+                exceptionCents: r.u64("exceptionCents"),
+                statementOutstandingCents: r.u64("statementOutstandingCents"),
+                ledgerHead: r.fixed(32, "ledgerHead"),
+                ledgerSeq: r.u64("ledgerSeq"),
+                reconDigest: r.fixed(32, "reconDigest"),
+            },
+        }),
+    },
+    confirmReconciled: { encode: (w, a) => { w.fixed(a.reconDigest, 32, "reconDigest"); }, decode: (r) => ({ reconDigest: r.fixed(32, "reconDigest") }) },
+    checkpoint: {
+        encode: (w, a) => { w.fixed(a.masterSalt, 32, "masterSalt").u64(a.seq, "seq"); },
+        decode: (r) => ({ masterSalt: r.fixed(32, "masterSalt"), seq: r.u64("seq") }),
+    },
+    writeCommitment: {
+        encode: (w, a) => { w.fixed(a.root, 32, "root").u64(a.seq, "seq").u32(a.policyVersion, "policyVersion").u32(a.periodIndex, "periodIndex"); },
+        decode: (r) => ({ root: r.fixed(32, "root"), seq: r.u64("seq"), policyVersion: r.u32("policyVersion"), periodIndex: r.u32("periodIndex") }),
+    },
+    wipeCard: empty,
+    closeCard: empty,
+    closeReservation: empty,
+    recordRepayment: {
+        encode: (w, a) => { w.fixed(a.statementDigest, 32, "statementDigest").u64(a.amountCents, "amountCents"); },
+        decode: (r) => ({ statementDigest: r.fixed(32, "statementDigest"), amountCents: r.u64("amountCents") }),
+    },
+    repayStatement: {
+        encode: (w, a) => { w.fixed(a.statementDigest, 32, "statementDigest").u64(a.amount, "amount"); },
+        decode: (r) => ({ statementDigest: r.fixed(32, "statementDigest"), amount: r.u64("amount") }),
+    },
+    recordPrivateRepayment: {
+        encode: (w, a) => { w.fixed(a.statementDigest, 32, "statementDigest").u64(a.amountCents, "amountCents"); },
+        decode: (r) => ({ statementDigest: r.fixed(32, "statementDigest"), amountCents: r.u64("amountCents") }),
+    },
+};
+export function encodeCardInstructionData(name, args) {
+    const w = new BorshWriter().bytes(CARD_POLICY_DISCRIMINATORS[name]);
+    CODECS[name].encode(w, args);
+    return w.toBytes();
+}
+export function decodeCardInstructionData(data) {
+    if (data.length < 8)
+        throw new Error("Instruction data is truncated");
+    for (const name of Object.keys(CARD_POLICY_DISCRIMINATORS)) {
+        const disc = CARD_POLICY_DISCRIMINATORS[name];
+        if (disc.every((byte, i) => data[i] === byte)) {
+            const r = new BorshReader(data, 8);
+            const args = CODECS[name].decode(r);
+            if (r.remaining() !== 0)
+                throw new Error(`${name} has ${r.remaining()} unexpected trailing bytes`);
+            return { name, args };
+        }
+    }
+    throw new Error("Unknown card_policy instruction discriminator");
+}
+/**
+ * Client-side mirror of the `set_policy` validation (contracts.md §1.3 #6).
+ * The program is the authority; this only stops an owner from signing a
+ * transaction that is certain to fail. Returns plain-language problems.
+ */
+export function policyArgsProblems(p) {
+    const problems = [];
+    if (p.maxPurchaseCents <= 0n)
+        problems.push("Max purchase must be more than $0.");
+    if (p.maxPurchaseCents > p.budgetCents)
+        problems.push("Max purchase can't be more than the budget.");
+    if (p.budgetCents > MAX_BUDGET_CENTS)
+        problems.push("Budget can't be more than $10,000 in the sandbox.");
+    if (p.periodSeconds < MIN_PERIOD_SECONDS)
+        problems.push("A period must be at least one day.");
+    if (p.currency !== "USD")
+        problems.push("Cards only spend USD.");
+    if (!Number.isInteger(p.feeBps) || p.feeBps < 0 || p.feeBps > MAX_FEE_BPS)
+        problems.push("Fee can't be more than 10%.");
+    if (p.merchantIdHashes.length === 0 && p.mccs.length === 0)
+        problems.push("Pick at least one shop or merchant category.");
+    if (p.merchantIdHashes.length > MAX_MERCHANTS)
+        problems.push(`At most ${MAX_MERCHANTS} shops.`);
+    if (p.mccs.length > MAX_MCCS)
+        problems.push(`At most ${MAX_MCCS} merchant categories.`);
+    const hashes = new Set(p.merchantIdHashes.map((hash) => Array.from(hash).join(",")));
+    if (hashes.size !== p.merchantIdHashes.length)
+        problems.push("A shop is listed twice.");
+    if (new Set(p.mccs).size !== p.mccs.length)
+        problems.push("A merchant category is listed twice.");
+    return problems;
+}
+function build(name, snake, programId, keys, args) {
+    return instruction(snake, resolveCardPolicyProgramId(programId), keys, encodeCardInstructionData(name, args));
+}
+/** OwnerCardEvent: owner (signer), policy (mut), period (mut). */
+function ownerEventKeys(owner, a) {
+    return [meta(owner, false, true), meta(a.policy, true), meta(a.period, true)];
+}
+// ------------------------------------------------ owner-signed (browser) builders
+export function buildInitCardInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("initCard", "init_card", programId, [
+        meta(input.owner, true, true),
+        meta(a.binding, true),
+        meta(a.policy, true),
+        meta(a.period, true),
+        meta(a.commitment, true),
+        meta(SYSTEM_PROGRAM_ID),
+    ], { cardId: input.cardId, issuer: input.issuer, issuerCardRefHash: input.issuerCardRefHash, prefundLamports: input.prefundLamports });
+}
+export function buildDelegateCardInstruction(input, programId) {
+    if (!TEE_VALIDATOR_ALLOWLIST.includes(input.validator))
+        throw new Error("Validator is not an allowed TEE validator");
+    const id = resolveCardPolicyProgramId(programId);
+    const a = deriveCardAccounts(input.owner, input.cardId, id);
+    const delegated = (account) => [
+        meta(deriveDelegationBufferAddress(account, id), true),
+        meta(deriveDelegationRecordAddress(account), true),
+        meta(deriveDelegationMetadataAddress(account), true),
+        meta(account, true),
+    ];
+    return build("delegateCard", "delegate_card", id, [
+        meta(input.owner, true, true),
+        meta(a.binding),
+        ...delegated(a.policy),
+        ...delegated(a.period),
+        meta(id),
+        meta(DELEGATION_PROGRAM_ID),
+        meta(SYSTEM_PROGRAM_ID),
+    ], { validator: input.validator });
+}
+function permissionKeys(owner, cardId, programId) {
+    const a = deriveCardAccounts(owner, cardId, programId);
+    return [
+        meta(owner, false, true),
+        meta(a.policy, true),
+        meta(a.period, true),
+        meta(a.policyPermission, true),
+        meta(a.periodPermission, true),
+        meta(EPHEMERAL_VAULT_ID, true),
+        meta(MAGIC_PROGRAM_ID),
+        meta(PERMISSION_PROGRAM_ID),
+    ];
+}
+/** PER. Owner creates the private permissions for policy and period. */
+export function buildInitPermissionInstruction(input, programId) {
+    return build("initPermission", "init_permission", programId, permissionKeys(input.owner, input.cardId, programId), { authorizer: input.authorizer });
+}
+/** `[ephemeral account, its permission]` pairs, as `wipe_card` and `update_permission` take them in remaining_accounts. */
+function ephemeralPairs(accounts) {
+    return (accounts ?? []).flatMap((account) => [meta(account, true), meta(derivePermissionAddress(account), true)]);
+}
+/**
+ * PER. Owner adds or removes a read-only finance reader. There is no "make public" op.
+ * `ephemeralAccounts` (open Reservations/CheckoutIntents) are re-synced in the same
+ * transaction, so removing a reader also revokes their view of open holds at once.
+ */
+export function buildUpdatePermissionInstruction(input, programId) {
+    if (input.op.kind !== "add_reader" && input.op.kind !== "remove_reader")
+        throw new Error("Only add_reader and remove_reader are allowed");
+    return build("updatePermission", "update_permission", programId, [...permissionKeys(input.owner, input.cardId, programId), ...ephemeralPairs(input.ephemeralAccounts)], { op: input.op });
+}
+/**
+ * PER. The owner signs this over their own TEE connection. Rejects a policy the program would reject.
+ *
+ * Once the card's policy is set, changing the credit terms (the authorizer, the
+ * fee, a larger budget or a shorter period) also needs ChainPay's current
+ * authorizer as `coSigner`: it rides as an extra signer account and the
+ * program refuses the change without it. The authorizer is never the owner.
+ */
+export function buildSetPolicyInstruction(input, programId) {
+    const problems = policyArgsProblems(input.policy);
+    if (input.policy.authorizer === input.owner)
+        problems.push("The authorizer can't be the owner.");
+    if (input.coSigner !== undefined && input.coSigner === input.owner)
+        problems.push("The co-signer must be ChainPay's authorizer, not the owner.");
+    if (problems.length)
+        throw new Error(problems.join(" "));
+    // set_policy shares the CardPermissions account struct; the co-signer is the first remaining account.
+    const keys = permissionKeys(input.owner, input.cardId, programId);
+    if (input.coSigner !== undefined)
+        keys.push(meta(input.coSigner, false, true));
+    return build("setPolicy", "set_policy", programId, keys, { policy: input.policy });
+}
+/** PER. Owner freeze (reason 1). The authorizer variant lives in Axum. */
+export function buildFreezeInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("freeze", "freeze", programId, [meta(input.signer ?? input.owner, false, true), meta(a.policy, true), meta(a.period)], { reason: input.reason ?? 1 });
+}
+/** PER. Owner only. Never built or sent by an agent tool. */
+export function buildUnfreezeInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("unfreeze", "unfreeze", programId, ownerEventKeys(input.owner, a), {});
+}
+export function buildResolveExceptionInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("resolveException", "resolve_exception", programId, ownerEventKeys(input.owner, a), { eventIdHash: input.eventIdHash, resolution: input.resolution });
+}
+export function buildCancelCheckoutIntentInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("cancelCheckoutIntent", "cancel_checkout_intent", programId, [
+        meta(input.signer ?? input.owner, false, true),
+        meta(a.policy),
+        meta(deriveCheckoutIntentAddress(a.policy, input.intentId, programId), true),
+    ], {});
+}
+/**
+ * PER. Co-signed: owner and the card's member authorizer must both sign
+ * (program 1A review), so the owner alone can't rewrite counters or debt.
+ * Axum signs as authorizer first; the owner checks and adds a signature.
+ */
+export function buildRestoreInstruction(input, programId) {
+    if (input.authorizer === input.owner)
+        throw new Error("The authorizer can't be the owner");
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("restore", "restore", programId, [
+        meta(input.owner, false, true),
+        meta(input.authorizer, false, true),
+        meta(a.policy, true),
+        meta(a.period, true),
+    ], { restore: input.restore });
+}
+/**
+ * PER. Owner or authorizer closes a consumed, cancelled or expired intent and
+ * its permission, returning the rent to the card prefund.
+ */
+export function buildCloseCheckoutIntentInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    const intent = deriveCheckoutIntentAddress(a.policy, input.intentId, programId);
+    return build("closeCheckoutIntent", "close_checkout_intent", programId, [
+        meta(input.signer ?? input.owner, false, true),
+        meta(a.policy, true),
+        meta(intent, true),
+        meta(derivePermissionAddress(intent), true),
+        meta(EPHEMERAL_VAULT_ID, true),
+        meta(MAGIC_PROGRAM_ID),
+        meta(PERMISSION_PROGRAM_ID),
+    ], {});
+}
+/**
+ * Base layer, owner-signed. card_policy's repay agent PDA `["repay_agent", binding]`
+ * signs ChainPay `execute_payment` by CPI, so ChainPay enforces the mandate and creates
+ * the receipt `["receipt", mandate, statementDigest]`. The owner pays the receipt rent.
+ * Returns the receipt address the Axum relay verifies and `record_repayment` re-checks on PER.
+ */
+export function buildRepayStatementInstruction(input, programId) {
+    if (input.amount <= 0n)
+        throw new Error("Repayment amount must be positive");
+    const id = resolveCardPolicyProgramId(programId);
+    const chainpay = input.chainpayProgramId ?? DEFAULT_PROGRAM_ID;
+    const a = deriveCardAccounts(input.owner, input.cardId, id);
+    const repayAgent = deriveRepayAgentAddress(a.binding, id);
+    const receipt = deriveReceiptAddress(input.mandate, input.statementDigest, chainpay);
+    const ix = build("repayStatement", "repay_statement", id, [
+        meta(input.owner, true, true),
+        meta(a.binding),
+        meta(repayAgent, true),
+        meta(deriveConfigAddress(chainpay)),
+        meta(deriveAssetAddress(input.mint, chainpay)),
+        meta(input.mandate, true),
+        meta(receipt, true),
+        meta(input.mint),
+        meta(input.sourceTokenAccount, true),
+        meta(input.recipientTokenAccount, true),
+        meta(input.tokenProgram ?? SPL_TOKEN_PROGRAM_ID),
+        meta(SYSTEM_PROGRAM_ID),
+        meta(chainpay),
+    ], { statementDigest: input.statementDigest, amount: input.amount });
+    return { instruction: ix, receipt, repayAgent };
+}
+export function buildConfirmReconciledInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("confirmReconciled", "confirm_reconciled", programId, ownerEventKeys(input.owner, a), { reconDigest: input.reconDigest });
+}
+/**
+ * PER. Owner or authorizer closes a final Reservation (fully captured, reversed
+ * or expired; nothing held; no open dispute) and its permission. The rent goes
+ * back to the card prefund and the auth id moves into the card's AuthGuard
+ * ring, so a replayed issuer authorization still gets `DuplicateAuthorization`.
+ * Axum normally does this; the owner can too.
+ */
+export function buildCloseReservationInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    const reservation = deriveReservationAddress(a.policy, input.authIdHash, programId);
+    const guard = deriveAuthGuardAddress(a.policy, programId);
+    return build("closeReservation", "close_reservation", programId, [
+        meta(input.signer ?? input.owner, false, true),
+        meta(a.policy, true),
+        meta(a.period),
+        meta(reservation, true),
+        meta(derivePermissionAddress(reservation), true),
+        meta(guard, true),
+        meta(derivePermissionAddress(guard), true),
+        meta(EPHEMERAL_VAULT_ID, true),
+        meta(MAGIC_PROGRAM_ID),
+        meta(PERMISSION_PROGRAM_ID),
+    ], {});
+}
+/**
+ * `ephemeralAccounts` lists every live Reservation and CheckoutIntent of the
+ * card, plus its AuthGuard once a reservation was ever closed
+ * (`deriveAuthGuardAddress`); each goes in remaining_accounts as
+ * [account, its permission] so the program can close it. Omitting one leaves
+ * private data behind (`EphemeralAccountsOpen`).
+ */
+export function buildWipeCardInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    const remaining = ephemeralPairs(input.ephemeralAccounts);
+    return build("wipeCard", "wipe_card", programId, [
+        meta(input.owner, true, true),
+        meta(a.policy, true),
+        meta(a.period, true),
+        meta(a.policyPermission, true),
+        meta(a.periodPermission, true),
+        meta(EPHEMERAL_VAULT_ID, true),
+        meta(MAGIC_CONTEXT_ID, true),
+        meta(MAGIC_PROGRAM_ID),
+        meta(PERMISSION_PROGRAM_ID),
+        ...remaining,
+    ], {});
+}
+export function buildCloseCardInstruction(input, programId) {
+    const a = deriveCardAccounts(input.owner, input.cardId, programId);
+    return build("closeCard", "close_card", programId, [
+        meta(input.owner, true, true),
+        meta(a.binding, true),
+        meta(a.policy, true),
+        meta(a.period, true),
+    ], {});
+}
+/**
+ * Base layer `#[action]`. Account order is fixed by contracts.md §1.3 #24:
+ * commitment, binding, source_program, escrow_auth (= policy PDA), escrow (signer).
+ * Only the delegation program can satisfy the escrow signer; exposed for tests and card-sim.
+ */
+export function buildWriteCommitmentInstruction(input, programId) {
+    const id = resolveCardPolicyProgramId(programId);
+    const a = deriveCardAccounts(input.owner, input.cardId, id);
+    return build("writeCommitment", "write_commitment", id, [
+        meta(a.commitment, true),
+        meta(a.binding),
+        meta(id),
+        meta(a.policy),
+        meta(a.escrow, false, true),
+    ], { root: input.root, seq: input.seq, policyVersion: input.policyVersion, periodIndex: input.periodIndex });
+}

package/dist/cards/layout.d.ts

@@ -0,0 +1,33 @@
+import type { Address } from "../types.js";
+/** Little-endian Borsh writer for the fixed card_policy layouts. */
+export declare class BorshWriter {
+    private readonly parts;
+    u8(value: number, name?: string): this;
+    u16(value: number, name?: string): this;
+    u32(value: number, name?: string): this;
+    u64(value: bigint, name?: string): this;
+    i64(value: bigint, name?: string): this;
+    bool(value: boolean): this;
+    fixed(value: Uint8Array, length: number, name: string): this;
+    pubkey(value: Address, _name?: string): this;
+    bytes(value: Uint8Array): this;
+    toBytes(): Uint8Array;
+}
+/** Little-endian Borsh reader. Every read is bounds-checked. */
+export declare class BorshReader {
+    private readonly data;
+    offset: number;
+    private readonly view;
+    constructor(data: Uint8Array, offset?: number);
+    private need;
+    u8(name?: string): number;
+    u16(name?: string): number;
+    u32(name?: string): number;
+    u64(name?: string): bigint;
+    i64(name?: string): bigint;
+    bool(name?: string): boolean;
+    fixed(length: number, name: string): Uint8Array;
+    pubkey(name?: string): Address;
+    remaining(): number;
+}
+export declare const ZERO_ADDRESS: Address;

package/dist/cards/layout.js

@@ -0,0 +1,137 @@
+import { PublicKey } from "@solana/web3.js";
+import { publicKey } from "../encoding.js";
+const U64_MAX = 18446744073709551615n;
+const I64_MIN = -9223372036854775808n;
+const I64_MAX = 9223372036854775807n;
+/** Little-endian Borsh writer for the fixed card_policy layouts. */
+export class BorshWriter {
+    parts = [];
+    u8(value, name = "u8") {
+        if (!Number.isInteger(value) || value < 0 || value > 0xff)
+            throw new Error(`${name} must fit in u8`);
+        this.parts.push(Uint8Array.of(value));
+        return this;
+    }
+    u16(value, name = "u16") {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffff)
+            throw new Error(`${name} must fit in u16`);
+        const bytes = new Uint8Array(2);
+        new DataView(bytes.buffer).setUint16(0, value, true);
+        this.parts.push(bytes);
+        return this;
+    }
+    u32(value, name = "u32") {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff)
+            throw new Error(`${name} must fit in u32`);
+        const bytes = new Uint8Array(4);
+        new DataView(bytes.buffer).setUint32(0, value, true);
+        this.parts.push(bytes);
+        return this;
+    }
+    u64(value, name = "u64") {
+        if (typeof value !== "bigint" || value < 0n || value > U64_MAX)
+            throw new Error(`${name} must fit in u64`);
+        const bytes = new Uint8Array(8);
+        new DataView(bytes.buffer).setBigUint64(0, value, true);
+        this.parts.push(bytes);
+        return this;
+    }
+    i64(value, name = "i64") {
+        if (typeof value !== "bigint" || value < I64_MIN || value > I64_MAX)
+            throw new Error(`${name} must fit in i64`);
+        const bytes = new Uint8Array(8);
+        new DataView(bytes.buffer).setBigInt64(0, value, true);
+        this.parts.push(bytes);
+        return this;
+    }
+    bool(value) {
+        this.parts.push(Uint8Array.of(value ? 1 : 0));
+        return this;
+    }
+    fixed(value, length, name) {
+        if (!(value instanceof Uint8Array) || value.length !== length)
+            throw new Error(`${name} must be exactly ${length} bytes`);
+        this.parts.push(new Uint8Array(value));
+        return this;
+    }
+    pubkey(value, _name = "pubkey") {
+        this.parts.push(publicKey(value).toBytes());
+        return this;
+    }
+    bytes(value) {
+        this.parts.push(new Uint8Array(value));
+        return this;
+    }
+    toBytes() {
+        const total = this.parts.reduce((sum, part) => sum + part.length, 0);
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const part of this.parts) {
+            out.set(part, offset);
+            offset += part.length;
+        }
+        return out;
+    }
+}
+/** Little-endian Borsh reader. Every read is bounds-checked. */
+export class BorshReader {
+    data;
+    offset;
+    view;
+    constructor(data, offset = 0) {
+        this.data = data;
+        this.offset = offset;
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    need(length, name) {
+        if (this.offset + length > this.data.length)
+            throw new Error(`Data ended while reading ${name}`);
+    }
+    u8(name = "u8") {
+        this.need(1, name);
+        return this.data[this.offset++];
+    }
+    u16(name = "u16") {
+        this.need(2, name);
+        const value = this.view.getUint16(this.offset, true);
+        this.offset += 2;
+        return value;
+    }
+    u32(name = "u32") {
+        this.need(4, name);
+        const value = this.view.getUint32(this.offset, true);
+        this.offset += 4;
+        return value;
+    }
+    u64(name = "u64") {
+        this.need(8, name);
+        const value = this.view.getBigUint64(this.offset, true);
+        this.offset += 8;
+        return value;
+    }
+    i64(name = "i64") {
+        this.need(8, name);
+        const value = this.view.getBigInt64(this.offset, true);
+        this.offset += 8;
+        return value;
+    }
+    bool(name = "bool") {
+        const value = this.u8(name);
+        if (value > 1)
+            throw new Error(`${name} is not a valid bool`);
+        return value === 1;
+    }
+    fixed(length, name) {
+        this.need(length, name);
+        const value = new Uint8Array(this.data.slice(this.offset, this.offset + length));
+        this.offset += length;
+        return value;
+    }
+    pubkey(name = "pubkey") {
+        return new PublicKey(this.fixed(32, name)).toBase58();
+    }
+    remaining() {
+        return this.data.length - this.offset;
+    }
+}
+export const ZERO_ADDRESS = PublicKey.default.toBase58();