@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/cards/instructions.d.ts

@@ -0,0 +1,302 @@
+import type { Address, ChainPayInstruction } from "../types.js";
+import { type CardPolicyInstructionName } from "./constants.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 declare const CARD_POLICY_ACCOUNT_ORDER_PROVISIONAL = false;
+export type PolicyArgs = {
+    budgetCents: bigint;
+    maxPurchaseCents: bigint;
+    /** 0 = no count limit. */
+    maxPurchasesPerPeriod: number;
+    periodSeconds: number;
+    currency: string;
+    merchantIdHashes: Uint8Array[];
+    mccs: number[];
+    /** 0 = no expiry. Unix seconds. */
+    expiresAt: bigint;
+    recurringAllowed: boolean;
+    feeBps: number;
+    authorizer: Address;
+};
+export type RestoreArgs = {
+    policy: PolicyArgs;
+    periodIndex: number;
+    capturedCents: bigint;
+    reservedCents: bigint;
+    refundedCents: bigint;
+    purchasesCount: number;
+    /** Exception debits booked this period (program 1A review: after `purchases_count`). */
+    exceptionCents: bigint;
+    statementOutstandingCents: bigint;
+    ledgerHead: Uint8Array;
+    ledgerSeq: bigint;
+    reconDigest: Uint8Array;
+};
+export type PermissionOp = {
+    kind: "add_reader";
+    pubkey: Address;
+} | {
+    kind: "remove_reader";
+    pubkey: Address;
+};
+export type CardInstructionArgs = {
+    initCard: {
+        cardId: Uint8Array;
+        issuer: number;
+        issuerCardRefHash: Uint8Array;
+        prefundLamports: bigint;
+    };
+    delegateCard: {
+        validator: Address;
+    };
+    initPermission: {
+        authorizer: Address;
+    };
+    updatePermission: {
+        op: PermissionOp;
+    };
+    syncPermission: Record<string, never>;
+    setPolicy: {
+        policy: PolicyArgs;
+    };
+    openCheckoutIntent: {
+        intentId: Uint8Array;
+        agent: Address;
+        merchantIdHash: Uint8Array;
+        mcc: number;
+        maxAmountCents: bigint;
+        currency: string;
+        expiresAt: bigint;
+    };
+    cancelCheckoutIntent: Record<string, never>;
+    closeCheckoutIntent: Record<string, never>;
+    authorize: {
+        authIdHash: Uint8Array;
+        intentId: Uint8Array;
+        amountCents: bigint;
+        currency: string;
+        merchantIdHash: Uint8Array;
+        mcc: number;
+        merchantInitiated: boolean;
+        singleMessage: boolean;
+    };
+    adjustReservation: {
+        newAmountCents: bigint;
+    };
+    capture: {
+        amountCents: bigint;
+        captureIdHash: Uint8Array;
+    };
+    reverse: {
+        amountCents: bigint;
+        reason: number;
+        eventIdHash: Uint8Array;
+    };
+    refund: {
+        amountCents: bigint;
+        eventIdHash: Uint8Array;
+    };
+    recordDispute: {
+        state: number;
+        eventIdHash: Uint8Array;
+    };
+    recordException: {
+        kind: number;
+        amountCents: bigint;
+        eventIdHash: Uint8Array;
+    };
+    resolveException: {
+        eventIdHash: Uint8Array;
+        resolution: number;
+    };
+    rollPeriod: Record<string, never>;
+    freeze: {
+        reason: number;
+    };
+    unfreeze: Record<string, never>;
+    recoveryFreeze: {
+        reason: number;
+    };
+    restore: {
+        restore: RestoreArgs;
+    };
+    confirmReconciled: {
+        reconDigest: Uint8Array;
+    };
+    checkpoint: {
+        masterSalt: Uint8Array;
+        seq: bigint;
+    };
+    writeCommitment: {
+        root: Uint8Array;
+        seq: bigint;
+        policyVersion: number;
+        periodIndex: number;
+    };
+    wipeCard: Record<string, never>;
+    closeReservation: Record<string, never>;
+    closeCard: Record<string, never>;
+    recordRepayment: {
+        statementDigest: Uint8Array;
+        amountCents: bigint;
+    };
+    repayStatement: {
+        statementDigest: Uint8Array;
+        amount: bigint;
+    };
+    recordPrivateRepayment: {
+        statementDigest: Uint8Array;
+        amountCents: bigint;
+    };
+};
+export declare function encodeCardInstructionData<K extends CardPolicyInstructionName>(name: K, args: CardInstructionArgs[K]): Uint8Array;
+export type DecodedCardInstruction = {
+    [K in CardPolicyInstructionName]: {
+        name: K;
+        args: CardInstructionArgs[K];
+    };
+}[CardPolicyInstructionName];
+export declare function decodeCardInstructionData(data: Uint8Array): DecodedCardInstruction;
+/**
+ * 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 declare function policyArgsProblems(p: PolicyArgs): string[];
+type CardRef = {
+    owner: Address;
+    cardId: Uint8Array;
+};
+export declare function buildInitCardInstruction(input: CardRef & {
+    issuer: number;
+    issuerCardRefHash: Uint8Array;
+    prefundLamports: bigint;
+}, programId?: Address): ChainPayInstruction;
+export declare function buildDelegateCardInstruction(input: CardRef & {
+    validator: Address;
+}, programId?: Address): ChainPayInstruction;
+/** PER. Owner creates the private permissions for policy and period. */
+export declare function buildInitPermissionInstruction(input: CardRef & {
+    authorizer: Address;
+}, programId?: Address): ChainPayInstruction;
+/**
+ * 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 declare function buildUpdatePermissionInstruction(input: CardRef & {
+    op: PermissionOp;
+    ephemeralAccounts?: Address[];
+}, programId?: Address): ChainPayInstruction;
+/**
+ * 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 declare function buildSetPolicyInstruction(input: CardRef & {
+    policy: PolicyArgs;
+    coSigner?: Address;
+}, programId?: Address): ChainPayInstruction;
+/** PER. Owner freeze (reason 1). The authorizer variant lives in Axum. */
+export declare function buildFreezeInstruction(input: CardRef & {
+    signer?: Address;
+    reason?: number;
+}, programId?: Address): ChainPayInstruction;
+/** PER. Owner only. Never built or sent by an agent tool. */
+export declare function buildUnfreezeInstruction(input: CardRef, programId?: Address): ChainPayInstruction;
+export declare function buildResolveExceptionInstruction(input: CardRef & {
+    eventIdHash: Uint8Array;
+    resolution: number;
+}, programId?: Address): ChainPayInstruction;
+export declare function buildCancelCheckoutIntentInstruction(input: CardRef & {
+    intentId: Uint8Array;
+    signer?: Address;
+}, programId?: Address): ChainPayInstruction;
+/**
+ * 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 declare function buildRestoreInstruction(input: CardRef & {
+    authorizer: Address;
+    restore: RestoreArgs;
+}, programId?: Address): ChainPayInstruction;
+/**
+ * PER. Owner or authorizer closes a consumed, cancelled or expired intent and
+ * its permission, returning the rent to the card prefund.
+ */
+export declare function buildCloseCheckoutIntentInstruction(input: CardRef & {
+    intentId: Uint8Array;
+    signer?: Address;
+}, programId?: Address): ChainPayInstruction;
+export type RepayStatementInput = CardRef & {
+    /** The owner's ChainPay mandate whose `approvedAgent` is this card's repay agent. */
+    mandate: Address;
+    mint: Address;
+    sourceTokenAccount: Address;
+    /** The partner token account the statement's `payWith` names. */
+    recipientTokenAccount: Address;
+    /** 32-byte statement digest; becomes the receipt's `invoice_hash`. */
+    statementDigest: Uint8Array;
+    /** Exact base units of `mint` (the statement's amount due). */
+    amount: bigint;
+    tokenProgram?: Address;
+    chainpayProgramId?: Address;
+};
+/**
+ * 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 declare function buildRepayStatementInstruction(input: RepayStatementInput, programId?: Address): {
+    instruction: ChainPayInstruction;
+    receipt: Address;
+    repayAgent: Address;
+};
+export declare function buildConfirmReconciledInstruction(input: CardRef & {
+    reconDigest: Uint8Array;
+}, programId?: Address): ChainPayInstruction;
+/**
+ * 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 declare function buildCloseReservationInstruction(input: CardRef & {
+    authIdHash: Uint8Array;
+    signer?: Address;
+}, programId?: Address): ChainPayInstruction;
+/**
+ * `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 declare function buildWipeCardInstruction(input: CardRef & {
+    ephemeralAccounts?: Address[];
+}, programId?: Address): ChainPayInstruction;
+export declare function buildCloseCardInstruction(input: CardRef, programId?: Address): ChainPayInstruction;
+/**
+ * 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 declare function buildWriteCommitmentInstruction(input: CardRef & {
+    root: Uint8Array;
+    seq: bigint;
+    policyVersion: number;
+    periodIndex: number;
+}, programId?: Address): ChainPayInstruction;
+export {};