@xochi/client 0.0.0-stage → 0.1.1

package/dist/esm/machine/phase.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Swap flow phase: the presentation phase of the intent lifecycle.
+ */
+import type { IntentStatus } from "../shared/index.js";
+export type SwapPhase = "confirm" | "awaiting-wallet" | "deposit" | "submitting" | "bridging" | "settling" | "success" | "refunded" | "failed" | "may-have-moved" | "not-sent" | "pending";
+/**
+ * Derive the modal phase from intent status.
+ *
+ * - Wallet rejection sets status back to "quoted" (with error "Signature
+ *   rejected"), so soft-cancel returns to the confirm surface automatically.
+ * - Only "failed" maps to the failure view (Retry). A `failed` the caller
+ *   marks `mayHaveMoved` maps to "may-have-moved" instead. An `executing` the
+ *   caller marks `notSent` maps to "not-sent". An in-doubt swap
+ *   keeps a non-failure status (executing/bridging/settling); when the caller
+ *   knows it is reconciling, it surfaces as "pending" ("still confirming"),
+ *   never as a failure. This covers both the slow-fill reconcile flip and the
+ *   #226 fail-closed success:false downgrade (funds moved, settlement
+ *   unconfirmed).
+ */
+export declare function phaseFromStatus(status: IntentStatus, opts?: {
+    reconciling?: boolean;
+    mayHaveMoved?: boolean;
+    notSent?: boolean;
+}): SwapPhase;

package/dist/esm/machine/phase.js

@@ -0,0 +1,42 @@
+/**
+ * Swap flow phase: the presentation phase of the intent lifecycle.
+ */
+/**
+ * Derive the modal phase from intent status.
+ *
+ * - Wallet rejection sets status back to "quoted" (with error "Signature
+ *   rejected"), so soft-cancel returns to the confirm surface automatically.
+ * - Only "failed" maps to the failure view (Retry). A `failed` the caller
+ *   marks `mayHaveMoved` maps to "may-have-moved" instead. An `executing` the
+ *   caller marks `notSent` maps to "not-sent". An in-doubt swap
+ *   keeps a non-failure status (executing/bridging/settling); when the caller
+ *   knows it is reconciling, it surfaces as "pending" ("still confirming"),
+ *   never as a failure. This covers both the slow-fill reconcile flip and the
+ *   #226 fail-closed success:false downgrade (funds moved, settlement
+ *   unconfirmed).
+ */
+export function phaseFromStatus(status, opts = {}) {
+    switch (status) {
+        case "signing":
+            return "awaiting-wallet";
+        case "awaiting_deposit":
+            return "deposit";
+        case "executing":
+            if (opts.notSent)
+                return "not-sent";
+            return opts.reconciling ? "pending" : "submitting";
+        case "bridging":
+            return opts.reconciling ? "pending" : "bridging";
+        case "settling":
+            return opts.reconciling ? "pending" : "settling";
+        case "completed":
+            return "success";
+        case "refunded":
+            return "refunded";
+        case "failed":
+            return opts.mayHaveMoved ? "may-have-moved" : "failed";
+        // idle | pending | quoting | quoted | expired -> the confirm surface
+        default:
+            return "confirm";
+    }
+}

package/dist/esm/machine/quoteChecks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `@xochi/signer` value checks the machine runs on a signable (pull-route)
+ * quote at ingest, adapted to the machine's request and refusal shapes.
+ *
+ * `assertIntentMatchesRequest` holds the served XochiIntent to the request that
+ * produced it (wallet, chains, tokens, recipient, settlement preference, amount,
+ * and the intent deadline against the wall clock). `assertPullMatchesIntent`
+ * then holds the origin pull to that intent (chain, token, amount, expiry, the
+ * Permit2 contract) and, where the caller pinned one, its recipient.
+ *
+ * Both are additive to the machine's own gates (`validateSolverPin`,
+ * `validatePayoutPin`, the recipient echo, the claim-info factory), which keep
+ * running where they always ran.
+ */
+import { type PinnedPullRecipients, type QuoteRequestParams } from "@xochi/signer";
+import type { QuoteRequest, QuoteResponse } from "./wire.js";
+/**
+ * The request in the signer's snake_case parameter spelling.
+ *
+ * Built from the request the machine SENT (already trimmed by
+ * `buildQuoteRequest`), never from the panel state, so the checks compare the
+ * served terms against the bytes that asked for them. The widget only quotes
+ * exact-input, so `swap_kind` is stated rather than left to the signer's default.
+ */
+export declare function quoteRequestParams(request: QuoteRequest): QuoteRequestParams;
+export type SignableQuoteCheck = {
+    ok: true;
+} | {
+    ok: false;
+    kind: "intent_mismatch" | "pull_mismatch";
+    reason: string;
+};
+/**
+ * Run both signer checks over a quote that carries an intent to sign.
+ *
+ * `pullRecipients` is the CALLER's pin (per chain, per method); it is never
+ * derived from `/api/capabilities`. Absent, the pull's recipient is left to the
+ * machine's own solver allowlist, and the signer still binds chain, token,
+ * amount and expiry.
+ */
+export declare function checkSignableQuote(request: QuoteRequest, quote: QuoteResponse, pullRecipients: PinnedPullRecipients | undefined): SignableQuoteCheck;

package/dist/esm/machine/quoteChecks.js

@@ -0,0 +1,78 @@
+/**
+ * The `@xochi/signer` value checks the machine runs on a signable (pull-route)
+ * quote at ingest, adapted to the machine's request and refusal shapes.
+ *
+ * `assertIntentMatchesRequest` holds the served XochiIntent to the request that
+ * produced it (wallet, chains, tokens, recipient, settlement preference, amount,
+ * and the intent deadline against the wall clock). `assertPullMatchesIntent`
+ * then holds the origin pull to that intent (chain, token, amount, expiry, the
+ * Permit2 contract) and, where the caller pinned one, its recipient.
+ *
+ * Both are additive to the machine's own gates (`validateSolverPin`,
+ * `validatePayoutPin`, the recipient echo, the claim-info factory), which keep
+ * running where they always ran.
+ */
+import { XochiIntentMismatchError, assertIntentMatchesRequest, assertPullMatchesIntent, } from "@xochi/signer";
+/**
+ * The request in the signer's snake_case parameter spelling.
+ *
+ * Built from the request the machine SENT (already trimmed by
+ * `buildQuoteRequest`), never from the panel state, so the checks compare the
+ * served terms against the bytes that asked for them. The widget only quotes
+ * exact-input, so `swap_kind` is stated rather than left to the signer's default.
+ */
+export function quoteRequestParams(request) {
+    return {
+        wallet: request.wallet,
+        from_chain_id: request.fromChainId,
+        to_chain_id: request.toChainId,
+        from_token: request.fromToken,
+        to_token: request.toToken,
+        from_amount: request.fromAmount,
+        swap_kind: "exact_input",
+        settlement_preference: request.settlementPreference,
+        recipient_address: request.recipientAddress,
+        refund_address: request.refundAddress,
+        stealth_spending_pub_key: request.stealthMetaAddress?.spendingPubKey,
+        stealth_viewing_pub_key: request.stealthMetaAddress?.viewingPubKey,
+    };
+}
+/**
+ * Run both signer checks over a quote that carries an intent to sign.
+ *
+ * `pullRecipients` is the CALLER's pin (per chain, per method); it is never
+ * derived from `/api/capabilities`. Absent, the pull's recipient is left to the
+ * machine's own solver allowlist, and the signer still binds chain, token,
+ * amount and expiry.
+ */
+export function checkSignableQuote(request, quote, pullRecipients) {
+    // The signer reads the wire spelling: `eip712`, `pull_authorization`, and the
+    // raw `escrow` envelope, which it refuses (this client runs no escrow binding).
+    const served = {
+        eip712: quote.eip712Data,
+        pull_authorization: quote.pullAuthorization,
+        escrow: quote.escrow,
+    };
+    try {
+        assertIntentMatchesRequest(quoteRequestParams(request), served);
+    }
+    catch (err) {
+        return { ok: false, kind: "intent_mismatch", reason: refusalReason(err) };
+    }
+    try {
+        assertPullMatchesIntent(served, { expectedPullRecipients: pullRecipients });
+    }
+    catch (err) {
+        return { ok: false, kind: "pull_mismatch", reason: refusalReason(err) };
+    }
+    return { ok: true };
+}
+/**
+ * The signer's own message for its mismatch class. Anything else still refuses
+ * (fail closed) and is labelled as unexpected so it is not read as a verdict.
+ */
+function refusalReason(err) {
+    if (err instanceof XochiIntentMismatchError)
+        return err.message;
+    return `verification failed unexpectedly: ${err instanceof Error ? err.message : String(err)}`;
+}

package/dist/esm/machine/receipt.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The Receipt: what the user is told about a trade, as data.
+ *
+ * Every slot is a discriminated union, and the shapes are chosen so the three
+ * claims the trade receipt must never make cannot even be written down:
+ *
+ *  - A payout floor. `PayoutSlot` has no minimum field at all. The contract is
+ *    "exactly this, or a full refund" (`min_to_amount` is never enforced on any
+ *    settlement path), so there is nowhere to put an "estimated min".
+ *  - A shielded payout with a hidden amount. Every `SettlementDisclosure`
+ *    variant fixes `amount: "visible"`; Shielded hides the recipient's account,
+ *    never the amount.
+ *  - A host-supplied number. Amounts and costs are `Served<...>`, a brand only
+ *    this package can apply, and only to figures read off the worker's own
+ *    response. A host (an embedding page, a prop, a query string) has no way to
+ *    construct one without a cast.
+ */
+import type { SettlementType } from "../shared/index.js";
+import type { QuoteResponse } from "./wire.js";
+import type { SwapPhase } from "./phase.js";
+import type { SignRefusal } from "./state.js";
+declare const SERVED: unique symbol;
+/** A figure read off the solver/worker's own response. Constructed only here. */
+export type Served<T extends string | number> = T & {
+    readonly [SERVED]: true;
+};
+/** The one payout promise. */
+export type PayoutSlot = {
+    kind: "none";
+}
+/** An anonymous, unsignable price: the same amount, marked as a preview. */
+ | {
+    kind: "preview";
+    amount: Served<string>;
+}
+/** "Receive exactly X, or get a full refund." */
+ | {
+    kind: "exact";
+    amount: Served<string>;
+    otherwise: "full_refund";
+};
+/** The one cost figure: the served all-in `cost_bps`, never reconstructed. */
+export type CostSlot = {
+    kind: "none";
+}
+/** The guard could not run. "Unavailable", never zero. */
+ | {
+    kind: "unavailable";
+} | {
+    kind: "served";
+    bps: Served<number>;
+    totalUsd: Served<string> | null;
+};
+/** What the settlement mode hides and what it leaves on-chain. */
+export type SettlementDisclosure = {
+    mode: "public";
+    recipient: "visible";
+    amount: "visible";
+    recipientAction: "none";
+} | {
+    mode: "stealth";
+    recipient: "one_time_address";
+    amount: "visible";
+    recipientAction: "claim";
+} | {
+    mode: "shielded";
+    recipient: "private_account";
+    amount: "visible";
+    recipientAction: "none";
+};
+/** The held quote, as the receipt panel shows it. */
+export type QuoteSlot = {
+    kind: "none";
+} | {
+    kind: "loading";
+} | {
+    kind: "declined";
+    reason: string | null;
+}
+/**
+ * A quote is on screen. `refreshing` means a replacement is being fetched
+ * while the held one stays mounted (its figures dim rather than vanish).
+ */
+ | {
+    kind: "ready";
+    executable: boolean;
+    refreshing: boolean;
+    expiresInSec: number | null;
+};
+/** Where the signing ceremony stands. */
+export type SigningSlot = {
+    kind: "unavailable";
+}
+/** A deposit route: no signature at all; confirming reveals the address. */
+ | {
+    kind: "deposit";
+} | {
+    kind: "ready";
+    signatures: 1 | 2;
+} | {
+    kind: "in_wallet";
+    step: 1 | 2;
+    of: 1 | 2;
+}
+/** Deep-link wallets: signature 1 is held, waiting for the user's tap for 2. */
+ | {
+    kind: "awaiting_second";
+} | {
+    kind: "submitted";
+}
+/**
+ * The Worker answered the execute not-accepted (the solver is busy), and the
+ * same signed request is sent again automatically at `retryAt` (unix
+ * seconds). This is resend `resend` of at most `of`. The phase stays
+ * `submitting`. Suggested copy, which makes no funds claim (the signed
+ * request stays executable during the wait): "Solver busy. Resending in Ns
+ * (retry r of n)." with "Keep this tab open. If it closes, this tab will not
+ * resend the order."
+ */
+ | {
+    kind: "busy";
+    retryAt: number;
+    resend: number;
+    of: number;
+}
+/** The sign ceremony was refused before funds could move; the quote is still on screen. */
+ | {
+    kind: "refused";
+    refusal: SignRefusal;
+};
+export interface Receipt {
+    phase: SwapPhase;
+    quote: QuoteSlot;
+    payout: PayoutSlot;
+    cost: CostSlot;
+    settlement: SettlementDisclosure;
+    signing: SigningSlot;
+}
+/**
+ * The payout promise a quote makes. Only a quote the solver can fill makes one;
+ * `minToAmount` is never read.
+ */
+export declare function payoutOf(quote: QuoteResponse | null): PayoutSlot;
+/**
+ * The cost a quote states. Absent (or unusable) `cost_bps` is `unavailable`, so
+ * a renderer cannot fall back to a figure of its own making.
+ */
+export declare function costOf(quote: QuoteResponse | null): CostSlot;
+/** What a settlement mode hides and what it leaves visible. */
+export declare function settlementDisclosure(mode: SettlementType): SettlementDisclosure;
+export {};

package/dist/esm/machine/receipt.js

@@ -0,0 +1,64 @@
+/**
+ * The Receipt: what the user is told about a trade, as data.
+ *
+ * Every slot is a discriminated union, and the shapes are chosen so the three
+ * claims the trade receipt must never make cannot even be written down:
+ *
+ *  - A payout floor. `PayoutSlot` has no minimum field at all. The contract is
+ *    "exactly this, or a full refund" (`min_to_amount` is never enforced on any
+ *    settlement path), so there is nowhere to put an "estimated min".
+ *  - A shielded payout with a hidden amount. Every `SettlementDisclosure`
+ *    variant fixes `amount: "visible"`; Shielded hides the recipient's account,
+ *    never the amount.
+ *  - A host-supplied number. Amounts and costs are `Served<...>`, a brand only
+ *    this package can apply, and only to figures read off the worker's own
+ *    response. A host (an embedding page, a prop, a query string) has no way to
+ *    construct one without a cast.
+ */
+function served(value) {
+    return value;
+}
+/**
+ * The payout promise a quote makes. Only a quote the solver can fill makes one;
+ * `minToAmount` is never read.
+ */
+export function payoutOf(quote) {
+    if (!quote?.canSolve)
+        return { kind: "none" };
+    const amount = served(quote.toAmount);
+    return quote.preview
+        ? { kind: "preview", amount }
+        : { kind: "exact", amount, otherwise: "full_refund" };
+}
+/**
+ * The cost a quote states. Absent (or unusable) `cost_bps` is `unavailable`, so
+ * a renderer cannot fall back to a figure of its own making.
+ */
+export function costOf(quote) {
+    if (!quote)
+        return { kind: "none" };
+    const bps = quote.costBps;
+    if (bps === undefined || !Number.isFinite(bps) || bps < 0)
+        return { kind: "unavailable" };
+    const totalUsd = quote.feeBreakdown?.totalUsd;
+    return { kind: "served", bps: served(bps), totalUsd: totalUsd ? served(totalUsd) : null };
+}
+const DISCLOSURES = {
+    public: { mode: "public", recipient: "visible", amount: "visible", recipientAction: "none" },
+    stealth: {
+        mode: "stealth",
+        recipient: "one_time_address",
+        amount: "visible",
+        recipientAction: "claim",
+    },
+    shielded: {
+        mode: "shielded",
+        recipient: "private_account",
+        amount: "visible",
+        recipientAction: "none",
+    },
+};
+/** What a settlement mode hides and what it leaves visible. */
+export function settlementDisclosure(mode) {
+    return DISCLOSURES[mode];
+}

package/dist/esm/machine/recipientEcho.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Recipient-echo guard for non-EVM (Tron) destination routes.
+ *
+ * These routes settle to a user-typed destination address rather than the
+ * connected wallet, and a deposit route carries no wallet signature to bind it.
+ * Recipient integrity therefore rides on the authenticated quote channel
+ * (client <-> Xochi worker): when the client asked for a specific recipient, the
+ * solvable quote MUST echo exactly that address. A mismatch (or a missing echo
+ * on a solvable quote) means the recipient the quote would bind is not the one
+ * the user chose, so the quote is rejected rather than signed/executed. See #113.
+ *
+ * Base58 (Tron) is case-sensitive, so the comparison is verbatim -- no
+ * normalization. EVM routes send no recipient (they settle to the connected
+ * wallet), so there is nothing to check and this returns null.
+ */
+export declare function recipientEchoError(requested: string | undefined, quoted: string | undefined): "recipient_unconfirmed" | "recipient_mismatch" | null;

package/dist/esm/machine/recipientEcho.js

@@ -0,0 +1,24 @@
+/**
+ * Recipient-echo guard for non-EVM (Tron) destination routes.
+ *
+ * These routes settle to a user-typed destination address rather than the
+ * connected wallet, and a deposit route carries no wallet signature to bind it.
+ * Recipient integrity therefore rides on the authenticated quote channel
+ * (client <-> Xochi worker): when the client asked for a specific recipient, the
+ * solvable quote MUST echo exactly that address. A mismatch (or a missing echo
+ * on a solvable quote) means the recipient the quote would bind is not the one
+ * the user chose, so the quote is rejected rather than signed/executed. See #113.
+ *
+ * Base58 (Tron) is case-sensitive, so the comparison is verbatim -- no
+ * normalization. EVM routes send no recipient (they settle to the connected
+ * wallet), so there is nothing to check and this returns null.
+ */
+export function recipientEchoError(requested, quoted) {
+    // No recipient requested: EVM route settling to the connected wallet.
+    if (!requested)
+        return null;
+    // Requested a recipient but the solvable quote did not echo one back.
+    if (!quoted)
+        return "recipient_unconfirmed";
+    return requested === quoted ? null : "recipient_mismatch";
+}

package/dist/esm/machine/solverPin.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Fail-closed pin for origin-pull authorizations: binds both WHERE the funds go
+ * and HOW MUCH, before the wallet signs.
+ *
+ * Two axes can move funds on the origin leg. The recipient (pull `to` for
+ * ERC-3009, `spender` for Permit2) decides who collects. The amount (`value` for
+ * ERC-3009, `permitted.amount` for Permit2) decides how much. The user's
+ * signature is the on-chain authority for both (ERC-3009 moves exactly `value`,
+ * Permit2 caps the pull at `permitted.amount`), so a pull whose amount exceeds
+ * the intended input can overdraw the wallet even to a correctly-pinned
+ * recipient. This pin binds the recipient to an operator allowlist AND the amount
+ * to the intended input, refusing to sign on either mismatch. The trust anchors
+ * are the client's own config and the user's own quoted amount, neither of which
+ * the quote server can influence.
+ *
+ * Defense in depth: the Xochi worker independently refuses to serve a quote whose
+ * pull amount does not equal `from_amount` (packages/worker-lib), and the
+ * on-chain token / Permit2 contract verifies the signature over the amount
+ * actually pulled. So a compromised quote server cannot overdraw even if this
+ * client check is bypassed.
+ *
+ * Permit2 has no on-chain recipient guard (the spender chooses the recipient at
+ * call time), so its recipient is ALWAYS fail-closed: an unpinned permit2 pull is
+ * rejected. ERC-3009 binds `to` in the signed digest and the token enforces
+ * `msg.sender == to`, so an unpinned `to` stays bounded (accepted unless a hard
+ * pin is requested). Once an allowlist is configured, both methods enforce it.
+ *
+ * Mirrors the raxol agent-side pin (`solver_allowed?/2`). See GitHub #333
+ * (recipient pin) and the #170 origin-leg amount binding.
+ */
+import type { Eip712TypedData } from "../shared/index.js";
+export interface SolverPinConfig {
+    /**
+     * Lowercased addresses valid as an ERC-3009 pull `to` (the solver collection
+     * EOA, or the verified per-chain XochiPull USDC contract once #591 flips). This
+     * class NEVER accepts a Permit2 spender: the two roles are distinct addresses
+     * with distinct on-chain authority, so mixing them would let one impersonate the
+     * other.
+     */
+    erc3009Allowlist: string[];
+    /**
+     * Lowercased addresses valid as a Permit2 `spender` (the verified
+     * XochiPullPermit2 contract, #591 sibling / PULL2). Distinct from the ERC-3009
+     * class above so a solver EOA can never stand in as the Permit2 spender.
+     */
+    permit2Allowlist: string[];
+    /** When true, ERC-3009 also requires a pin (Permit2 always does). */
+    requirePin: boolean;
+}
+export type SolverPinField = "pull_to" | "pull_spender" | "pull_type" | "pull_amount" | "payout_amount" | "payout_recipient";
+export type SolverPinResult = {
+    ok: true;
+} | {
+    ok: false;
+    field: SolverPinField;
+    reason: string;
+};
+/** What the client rendered, and therefore what the user agreed to receive. */
+export interface PayoutPinExpectation {
+    /** Destination-token smallest units: the `toAmount` shown in the panel. */
+    toAmount: string;
+    /**
+     * Who the panel said would be paid: the connected wallet on a same-VM route,
+     * or the user-entered destination address on a non-EVM one.
+     *
+     * Typed as possibly-undefined on purpose. The caller's wallet address is
+     * `string | undefined`, and the honest handling of "we do not know who this
+     * was for" is to refuse, not to assert it away with a cast. Casting also loses
+     * to the pre-commit `eslint --fix`, which strips assertions it deems
+     * unnecessary.
+     */
+    recipient: string | undefined;
+}
+/**
+ * Validate a served origin-pull authorization against the solver pin. Returns
+ * `{ ok: true }` when the wallet may sign, or `{ ok: false, field, reason }` to
+ * abort before signing.
+ *
+ * `expectedAmount` is the intended input amount (origin-token smallest units, the
+ * user's own quoted `from_amount`). The pull is rejected unless its collected
+ * amount equals it, so a served pull cannot overdraw beyond what the user meant
+ * to spend even when the recipient is correctly pinned.
+ */
+export declare function validateSolverPin(pull: Eip712TypedData, config: SolverPinConfig, expectedAmount: bigint): SolverPinResult;
+/**
+ * Bind the DESTINATION leg of the intent payload to what the client rendered,
+ * before the wallet signs it.
+ *
+ * `validateSolverPin` above protects the origin leg: how much leaves the wallet
+ * and who collects it. This is the mirror for the other end -- how much comes
+ * back and who receives it -- and it exists because those two fields are the only
+ * ones a user cannot verify by reading a wallet prompt. A payload whose
+ * `toAmount` is lower than the number on screen, or whose `recipient` is an
+ * address the user never chose, produces a wallet prompt that looks entirely
+ * normal.
+ *
+ * The trust anchor is the same as the origin pin's and that is the whole point:
+ * the expectation comes from the client's own rendered quote, never from another
+ * field of the same served response. The Xochi worker independently refuses to
+ * serve a quote whose `eip712.message.toAmount` disagrees with the `to_amount` it
+ * advertises (`servedPayoutMismatch`, packages/worker-lib), so against a healthy
+ * backend this check never fires. It covers what that one structurally cannot:
+ * anything that reaches the payload after the worker has vouched for it, or a
+ * worker that is itself compromised. A firing check here is an incident, not a
+ * tuning problem.
+ *
+ * Fail-closed on a missing or unreadable field: never sign a payout we cannot
+ * read.
+ */
+export declare function validatePayoutPin(intent: Eip712TypedData, expected: PayoutPinExpectation): SolverPinResult;