@mooring-live/x402-client 0.0.0-stage → 0.1.0

package/dist/denial.d.ts

@@ -0,0 +1,81 @@
+import { type xdr } from "@stellar/stellar-sdk";
+export type DenialReason = "frozen" | "cancelled" | "expired" | "not_allowlisted" | "over_per_tx_cap" | "over_budget" | "wrong_token" | "insufficient_balance" | "bad_signature" | "wrong_context" | "unknown";
+/**
+ * Where a payment was denied.
+ *
+ * - `precheck`  — the local policy mirror, before anything is signed.
+ * - `simulate`  — the card's `__check_auth`, in the enforcing simulation the
+ *   client runs after signing and before handing the payload to a facilitator.
+ * - `verify`    — the facilitator refused the payload.
+ * - `settle`    — the settlement transaction failed on-chain.
+ */
+export type DenialStage = "precheck" | "simulate" | "verify" | "settle";
+/** Card contract error codes that mean "policy denied". */
+export declare const CARD_ERROR_CODES: Record<number, DenialReason>;
+/**
+ * Every contract error the card can raise (`CardError`, codes 1..13), with a
+ * short user-facing sentence for each. This is the full table: unlike
+ * `CARD_ERROR_CODES` (1..8, payment denials only), it also covers the owner
+ * operations the web app surfaces (`set_policy`, `set_label`, allowlist
+ * management, freeze/cancel/withdraw) so their errors can be shown directly
+ * without a separate mapping.
+ */
+export declare const CARD_ERRORS: Record<number, string>;
+/** Parses a Soroban `Error(Contract, #N)` from an error/diagnostic string. */
+export declare function classifyContractError(text: string): {
+    code: number;
+    reason: DenialReason;
+} | null;
+/**
+ * Reads the card's own `__check_auth` verdict out of a transaction's diagnostic
+ * events.
+ *
+ * The card's address alone is not evidence: it appears in the `transfer`
+ * arguments of every diagnostic this transaction can produce, and the token's
+ * own error codes overlap the card's 1-8 range — a SAC balance error would be
+ * read as a policy decision. What identifies an auth failure is the host's
+ * event, which names the failing account and its error together:
+ *
+ *   ["failed account authentication with error", <card>, Error(Contract, #N)]
+ *
+ * so the reason is taken from that event and nowhere else. Anything that does
+ * not match returns `null`, and the caller reports `unknown`.
+ */
+export declare function cardDenialFromEvents(events: readonly xdr.DiagnosticEvent[], card: string): {
+    code: number;
+    reason: DenialReason;
+} | null;
+export declare class CardPolicyDenied extends Error {
+    readonly reason: DenialReason;
+    readonly stage: DenialStage;
+    readonly contractError?: number;
+    readonly detail?: string;
+    constructor(reason: DenialReason, stage: DenialStage, opts?: {
+        contractError?: number;
+        detail?: string;
+    });
+}
+/**
+ * Why a payment did not deliver the resource, when the card's policy is *not*
+ * the reason. `CardPolicyDenied` means exactly one thing — the card refused —
+ * so everything else lands here:
+ *
+ * - `rejected`    — the facilitator (or the transport) refused the payment
+ *   before anything was submitted: a malformed payload, a fee above the
+ *   facilitator's ceiling, an expiration it will not accept, a 5xx. Nothing
+ *   was spent.
+ * - `unconfirmed` — the settlement state is unknown or contradictory: the
+ *   server reported a failure for a transaction the ledger accepted, or the
+ *   transaction was never observed. The card may have been debited; reconcile
+ *   `transaction` against the network before retrying.
+ */
+export declare class PaymentError extends Error {
+    readonly kind: "rejected" | "unconfirmed";
+    readonly transaction?: string;
+    readonly detail?: string;
+    constructor(opts: {
+        kind: "rejected" | "unconfirmed";
+        transaction?: string;
+        detail?: string;
+    });
+}

package/dist/denial.js

@@ -0,0 +1,116 @@
+import { humanizeEvents } from "@stellar/stellar-sdk";
+/** Card contract error codes that mean "policy denied". */
+export const CARD_ERROR_CODES = {
+    1: "bad_signature",
+    2: "wrong_context",
+    3: "frozen",
+    4: "cancelled",
+    5: "expired",
+    6: "not_allowlisted",
+    7: "over_per_tx_cap",
+    8: "over_budget",
+};
+/**
+ * Every contract error the card can raise (`CardError`, codes 1..13), with a
+ * short user-facing sentence for each. This is the full table: unlike
+ * `CARD_ERROR_CODES` (1..8, payment denials only), it also covers the owner
+ * operations the web app surfaces (`set_policy`, `set_label`, allowlist
+ * management, freeze/cancel/withdraw) so their errors can be shown directly
+ * without a separate mapping.
+ */
+export const CARD_ERRORS = {
+    1: "The signature is not valid for this card.",
+    2: "This action is not the one payment the card's agent key is allowed to sign.",
+    3: "This card is frozen.",
+    4: "This card has been cancelled.",
+    5: "This card has expired.",
+    6: "This merchant is not on the card's allowlist.",
+    7: "This payment is over the card's per-transaction cap.",
+    8: "This would put the card over its budget for the current period.",
+    9: "The amount must be a positive number.",
+    10: "The card's merchant allowlist is full.",
+    11: "That policy is not valid (check the budget, cap and expiry values).",
+    12: "This action is not allowed in the card's current state.",
+    13: "That label is not valid (it must be 1 to 32 bytes).",
+};
+const CONTRACT_ERROR = /Error\(Contract, #(\d+)\)/;
+/** Parses a Soroban `Error(Contract, #N)` from an error/diagnostic string. */
+export function classifyContractError(text) {
+    const m = CONTRACT_ERROR.exec(text);
+    if (!m)
+        return null;
+    const code = Number(m[1]);
+    return { code, reason: CARD_ERROR_CODES[code] ?? "unknown" };
+}
+/** The host's phrase that attributes an authorization failure to an account. */
+const AUTH_FAILURE = "failed account authentication with error";
+/**
+ * Reads the card's own `__check_auth` verdict out of a transaction's diagnostic
+ * events.
+ *
+ * The card's address alone is not evidence: it appears in the `transfer`
+ * arguments of every diagnostic this transaction can produce, and the token's
+ * own error codes overlap the card's 1-8 range — a SAC balance error would be
+ * read as a policy decision. What identifies an auth failure is the host's
+ * event, which names the failing account and its error together:
+ *
+ *   ["failed account authentication with error", <card>, Error(Contract, #N)]
+ *
+ * so the reason is taken from that event and nowhere else. Anything that does
+ * not match returns `null`, and the caller reports `unknown`.
+ */
+export function cardDenialFromEvents(events, card) {
+    for (const e of humanizeEvents([...events])) {
+        const data = e.data;
+        if (!Array.isArray(data) || data.length < 3)
+            continue;
+        if (data[0] !== AUTH_FAILURE || data[1] !== card)
+            continue;
+        const err = data[2];
+        if (err?.type !== "contract" || typeof err.code !== "number")
+            continue;
+        return { code: err.code, reason: CARD_ERROR_CODES[err.code] ?? "unknown" };
+    }
+    return null;
+}
+export class CardPolicyDenied extends Error {
+    reason;
+    stage;
+    contractError;
+    detail;
+    constructor(reason, stage, opts = {}) {
+        super(`card policy denied (${reason}) at ${stage}${opts.contractError ? ` [contract error #${opts.contractError}]` : ""}${opts.detail ? `: ${opts.detail}` : ""}`);
+        this.name = "CardPolicyDenied";
+        this.reason = reason;
+        this.stage = stage;
+        this.contractError = opts.contractError;
+        this.detail = opts.detail;
+    }
+}
+/**
+ * Why a payment did not deliver the resource, when the card's policy is *not*
+ * the reason. `CardPolicyDenied` means exactly one thing — the card refused —
+ * so everything else lands here:
+ *
+ * - `rejected`    — the facilitator (or the transport) refused the payment
+ *   before anything was submitted: a malformed payload, a fee above the
+ *   facilitator's ceiling, an expiration it will not accept, a 5xx. Nothing
+ *   was spent.
+ * - `unconfirmed` — the settlement state is unknown or contradictory: the
+ *   server reported a failure for a transaction the ledger accepted, or the
+ *   transaction was never observed. The card may have been debited; reconcile
+ *   `transaction` against the network before retrying.
+ */
+export class PaymentError extends Error {
+    kind;
+    transaction;
+    detail;
+    constructor(opts) {
+        super(`payment ${opts.kind}${opts.transaction ? ` (tx ${opts.transaction})` : ""}${opts.detail ? `: ${opts.detail}` : ""}`);
+        this.name = "PaymentError";
+        this.kind = opts.kind;
+        this.transaction = opts.transaction;
+        this.detail = opts.detail;
+    }
+}
+//# sourceMappingURL=denial.js.map

package/dist/denial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"denial.js","sourceRoot":"","sources":["../src/denial.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { signCardAuthEntries } from "./signer.js";
+export { CARD_ERROR_CODES, CARD_ERRORS, CardPolicyDenied, PaymentError, cardDenialFromEvents, classifyContractError, } from "./denial.js";
+export type { DenialReason, DenialStage } from "./denial.js";
+export { reconcileSettlement } from "./reconcile.js";
+export type { SettlementOutcome } from "./reconcile.js";
+export { precheck } from "./precheck.js";
+export type { PaymentTerms } from "./precheck.js";
+export { readCardInfo, readMerchants } from "./card.js";
+export type { CardInfo, CardPolicy, CardState } from "./card.js";
+export { CardExactStellarScheme } from "./scheme.js";
+export type { CardSchemeOptions, StellarNetwork } from "./scheme.js";
+export { createMooringClient, createMooringFetch, getSettlement } from "./client.js";
+export type { MooringClientOptions, Settlement } from "./client.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { signCardAuthEntries } from "./signer.js";
+export { CARD_ERROR_CODES, CARD_ERRORS, CardPolicyDenied, PaymentError, cardDenialFromEvents, classifyContractError, } from "./denial.js";
+export { reconcileSettlement } from "./reconcile.js";
+export { precheck } from "./precheck.js";
+export { readCardInfo, readMerchants } from "./card.js";
+export { CardExactStellarScheme } from "./scheme.js";
+export { createMooringClient, createMooringFetch, getSettlement } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/precheck.d.ts

@@ -0,0 +1,12 @@
+import type { CardInfo } from "./card.js";
+import type { DenialReason } from "./denial.js";
+export interface PaymentTerms {
+    payTo: string;
+    amount: string;
+    asset: string;
+}
+/**
+ * Local mirror of the card's on-chain policy, evaluated before signing so the agent
+ * never submits a payment the card will reject. Order matches the contract.
+ */
+export declare function precheck(info: CardInfo, merchants: string[], req: PaymentTerms, nowSeconds: number): DenialReason | null;

package/dist/precheck.js

@@ -0,0 +1,25 @@
+/**
+ * Local mirror of the card's on-chain policy, evaluated before signing so the agent
+ * never submits a payment the card will reject. Order matches the contract.
+ */
+export function precheck(info, merchants, req, nowSeconds) {
+    const amount = BigInt(req.amount);
+    if (req.asset !== info.token)
+        return "wrong_token";
+    if (info.state === 1)
+        return "frozen";
+    if (info.state === 2)
+        return "cancelled";
+    if (BigInt(nowSeconds) >= info.policy.expiry)
+        return "expired";
+    if (!merchants.includes(req.payTo))
+        return "not_allowlisted";
+    if (amount > info.policy.max_per_tx)
+        return "over_per_tx_cap";
+    if (amount > info.remaining)
+        return "over_budget";
+    if (amount > info.balance)
+        return "insufficient_balance";
+    return null;
+}
+//# sourceMappingURL=precheck.js.map

package/dist/precheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precheck.js","sourceRoot":"","sources":["../src/precheck.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAc,EAAE,SAAmB,EAAE,GAAiB,EAAE,UAAkB;IACjG,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK;QAAE,OAAO,aAAa,CAAC;IACnD,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtC,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IACzC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC/D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAC7D,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,OAAO,iBAAiB,CAAC;IAC9D,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS;QAAE,OAAO,aAAa,CAAC;IAClD,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO;QAAE,OAAO,sBAAsB,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/reconcile.d.ts

@@ -0,0 +1,37 @@
+import { type xdr } from "@stellar/stellar-sdk";
+import type { StellarNetwork } from "./scheme.js";
+/** What the ledger says about a settlement transaction. */
+export type SettlementOutcome = {
+    status: "SUCCESS";
+} | {
+    status: "FAILED";
+    events: xdr.DiagnosticEvent[];
+} | {
+    status: "NOT_FOUND";
+};
+/** Reconciliation window: ~10 s, one RPC read per second. */
+export declare const RECONCILE_ATTEMPTS = 10;
+export declare const RECONCILE_DELAY_MS = 1000;
+/**
+ * Asks the network what actually happened to a settlement transaction.
+ *
+ * The facilitator answers `settle_exact_stellar_transaction_failed` both for a
+ * transaction the ledger rejected *and* for one it simply stopped waiting for
+ * (its own poll gives up after `maxTimeoutSeconds`), so its "failed" cannot be
+ * read as "the payment did not happen" — inclusion can follow the answer. This
+ * asks the RPC directly and distinguishes the three real outcomes:
+ *
+ * - `SUCCESS`   — the payment settled; the card was debited even though the
+ *   server reported a failure and withheld the resource.
+ * - `FAILED`    — the ledger rejected it; `events` carry the reason, including
+ *   the card's own `__check_auth` verdict when that is what refused.
+ * - `NOT_FOUND` — still not visible when the window closed; the settlement
+ *   state is unknown.
+ *
+ * An RPC error is treated as "not seen yet", not as an answer: a reconciliation
+ * we could not complete must never be reported as a failed payment.
+ */
+export declare function reconcileSettlement(rpcUrl: string, network: StellarNetwork, hash: string, opts?: {
+    attempts?: number;
+    delayMs?: number;
+}): Promise<SettlementOutcome>;

package/dist/reconcile.js

@@ -0,0 +1,44 @@
+import { rpc } from "@stellar/stellar-sdk";
+/** Reconciliation window: ~10 s, one RPC read per second. */
+export const RECONCILE_ATTEMPTS = 10;
+export const RECONCILE_DELAY_MS = 1000;
+/**
+ * Asks the network what actually happened to a settlement transaction.
+ *
+ * The facilitator answers `settle_exact_stellar_transaction_failed` both for a
+ * transaction the ledger rejected *and* for one it simply stopped waiting for
+ * (its own poll gives up after `maxTimeoutSeconds`), so its "failed" cannot be
+ * read as "the payment did not happen" — inclusion can follow the answer. This
+ * asks the RPC directly and distinguishes the three real outcomes:
+ *
+ * - `SUCCESS`   — the payment settled; the card was debited even though the
+ *   server reported a failure and withheld the resource.
+ * - `FAILED`    — the ledger rejected it; `events` carry the reason, including
+ *   the card's own `__check_auth` verdict when that is what refused.
+ * - `NOT_FOUND` — still not visible when the window closed; the settlement
+ *   state is unknown.
+ *
+ * An RPC error is treated as "not seen yet", not as an answer: a reconciliation
+ * we could not complete must never be reported as a failed payment.
+ */
+export async function reconcileSettlement(rpcUrl, network, hash, opts = {}) {
+    const attempts = opts.attempts ?? RECONCILE_ATTEMPTS;
+    const delayMs = opts.delayMs ?? RECONCILE_DELAY_MS;
+    const server = new rpc.Server(rpcUrl, { allowHttp: network === "stellar:testnet" });
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const tx = await server.getTransaction(hash);
+            if (tx.status === "SUCCESS")
+                return { status: "SUCCESS" };
+            if (tx.status === "FAILED")
+                return { status: "FAILED", events: tx.diagnosticEventsXdr ?? [] };
+        }
+        catch {
+            /* not visible yet, or the RPC hiccuped: keep waiting */
+        }
+        if (i < attempts - 1)
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    return { status: "NOT_FOUND" };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAY,MAAM,sBAAsB,CAAC;AASrD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AACrC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAc,EACd,OAAuB,EACvB,IAAY,EACZ,OAAgD,EAAE;IAElD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,kBAAkB,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,kBAAkB,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,KAAK,iBAAiB,EAAE,CAAC,CAAC;IAEpF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,EAAE,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YAC1D,IAAI,EAAE,CAAC,MAAM,KAAK,QAAQ;gBAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,mBAAmB,IAAI,EAAE,EAAE,CAAC;QAChG,CAAC;QAAC,MAAM,CAAC;YACP,wDAAwD;QAC1D,CAAC;QACD,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjC,CAAC"}

package/dist/scheme.d.ts

@@ -0,0 +1,87 @@
+import { Keypair, contract } from "@stellar/stellar-sdk";
+import type { PaymentPayloadResult, PaymentRequirements, SchemeNetworkClient } from "@x402/core/types";
+import { CardPolicyDenied, PaymentError } from "./denial.js";
+export type StellarNetwork = "stellar:testnet" | "stellar:pubnet";
+/**
+ * How far ahead the card's auth entry may be valid.
+ *
+ * The facilitator computes `maxLedger = currentLedger + ceil(maxTimeoutSeconds
+ * / estimatedLedgerSeconds)` and rejects an entry more than 2 ledgers beyond
+ * it (`invalid_exact_stellar_signature_expiration_too_far`). Its estimate is
+ * sampled from Horizon, so it can be slower than the 5 s the stock client
+ * assumes — on pubnet it usually is. Aiming low costs nothing: the expiry only
+ * has to outlive settlement, and a shorter one is never rejected.
+ */
+export declare function authExpirationLedgers(maxTimeoutSeconds: number): number;
+export interface CardSchemeOptions {
+    /** Card contract address (C...). The card is the payer. */
+    card: string;
+    /** Agent keypair registered as the card's signer. */
+    agent: Keypair;
+    network: StellarNetwork;
+    /** Required on pubnet; optional on testnet. */
+    rpcUrl?: string;
+    /** Called when the card rejects the payment in the enforcing simulation. */
+    onDenial?: (denial: CardPolicyDenied) => void;
+    /** Called when the payment fails for a reason that is not the card's policy. */
+    onPaymentError?: (error: PaymentError) => void;
+}
+/**
+ * x402 "exact" scheme client whose payer is a Mooring card (a Soroban custom
+ * account). It produces exactly the same payload as `@x402/stellar`'s
+ * `ExactStellarScheme` — one `invokeHostFunction` calling
+ * `asset.transfer(card, payTo, amount)`, re-simulated after signing, returned
+ * as a base64 transaction envelope. Only the signing differs: the card's auth
+ * entries are signed by the agent key through `signCardAuthEntries`, so
+ * `__check_auth` enforces the budget, allowlist and expiry at settlement.
+ */
+export declare class CardExactStellarScheme implements SchemeNetworkClient {
+    readonly scheme = "exact";
+    readonly findDefaultAsset: import("@x402/core/types").FindDefaultAsset<import("@x402/core/types").DefaultAsset>;
+    private readonly card;
+    private readonly agent;
+    private readonly network;
+    private readonly rpcUrl;
+    private readonly passphrase;
+    private readonly onDenial?;
+    private readonly onPaymentError?;
+    constructor(opts: CardSchemeOptions);
+    /** Throws unless the requirements are an `exact` payment this client can make. */
+    validateRequirements(req: PaymentRequirements): void;
+    createPaymentPayload(x402Version: number, req: PaymentRequirements): Promise<PaymentPayloadResult>;
+    /**
+     * Turns a failed enforcing simulation into a typed denial when it was the
+     * card's `__check_auth` that said no.
+     *
+     * The card's address alone is not evidence: it appears in the `transfer`
+     * arguments of every diagnostic this transaction can produce, and the token's
+     * own error codes overlap the card's 1–8 range — a SAC balance error would be
+     * read as a policy decision. What identifies an auth failure is the host's
+     * phrase, which names the failing account and its error together:
+     *
+     *   ["failed account authentication with error", <card>, Error(Contract, #N)]
+     *
+     * so the reason is taken from that fragment and nowhere else. Anything that
+     * does not match stays an ordinary error.
+     */
+    private denialFromCard;
+    /**
+     * Refuses to build a payment whose card auth entry the deployed facilitator
+     * cannot decode.
+     *
+     * `buildTransfer` asks the RPC to record legacy v1 `ADDRESS` credentials
+     * (`useUpgradedAuth: false`) because OZ Channels rejects CAP-71 `ADDRESS_V2`
+     * as `invalid_exact_stellar_payload_malformed`. That flag is transitional —
+     * it becomes a no-op from protocol 28 — and an RPC or SDK that ignores it
+     * would otherwise produce a payload that is signed, sent and refused with a
+     * reason that says nothing about why. This checks what was actually
+     * recorded, and fails before the agent key signs anything.
+     */
+    private assertLegacyCardCredentials;
+    /** Builds and simulates `asset.transfer(from, to, amount)` (SEP-41). */
+    protected buildTransfer(asset: string, from: string, to: string, amount: bigint): Promise<contract.AssembledTransaction<unknown>>;
+    /** Signs the card's auth entries with the agent key. */
+    protected sign(tx: contract.AssembledTransaction<unknown>, expirationLedger: number): Promise<void>;
+    /** Current ledger sequence, used as the auth-entry expiration base. */
+    protected latestLedger(): Promise<number>;
+}