@xochi/client 0.0.0-stage → 0.1.2

package/dist/cjs/machine/machine.d.ts

@@ -0,0 +1,411 @@
+/**
+ * The quote -> sign -> execute -> status lifecycle as a pure state machine.
+ *
+ *     update(model, msg) -> [model, effects]
+ *
+ * `update` is the only place lifecycle state changes. Everything it cannot do
+ * itself -- an HTTP call, a wallet prompt, a timer, a log line -- it asks for as
+ * an `Effect`, which is plain JSON. A host (the React interpreter in the widget,
+ * or a headless integrator) performs the effect and feeds the outcome back as a
+ * `Msg`. Every `Msg` is stamped with the clock and tab visibility it was
+ * observed under, so a recorded msg log replays to the same models, effects and
+ * receipts with no mocks.
+ *
+ * The one exception to that clock is the fund-safety checks from
+ * `@xochi/signer` that run at quote ingest: they bound the intent deadline and
+ * the deposit window against the WALL clock, and take no `now` argument by
+ * design, since an injectable clock on a security assertion is a bypass.
+ *
+ * No DOM, no fetch, no React, no wagmi, no console: the machine compiles
+ * against `lib: ["ES2020"]` alone (tsconfig.machine.json).
+ */
+import type { ChainId, Eip712TypedData, IntentStatus, SelectableChainId, SettlementType } from "../shared/index.js";
+import { type PinnedPullRecipients } from "@xochi/signer";
+import { type SolverPinConfig } from "./solverPin.js";
+import { type IntentState, type StructuredError } from "./state.js";
+import type { ExecuteReply, ExecuteRequest, IntentStatusResult, IntentWebSocketMessage, QuoteRequest, QuoteResponse } from "./wire.js";
+/** Amount edits settle for this long before a quote is requested. */
+export declare const QUOTE_DEBOUNCE_MS = 500;
+/**
+ * Refresh this long before expiry. Exported so the panel countdown pill can
+ * align "New price in Ns" with the actual refresh instant.
+ */
+export declare const QUOTE_REFRESH_BUFFER_MS = 5000;
+/**
+ * After this many polls in one phase without reaching a terminal state, flip the
+ * modal from an indefinite "Submitting" spinner to the reassuring "Still
+ * confirming" (safe-to-close) view. Reconciliation/webhooks still resolve it;
+ * this only fixes the feedback gap. ~90s at the shared cadence.
+ */
+export declare const RECONCILE_AFTER_ATTEMPTS: number;
+/**
+ * If a wallet signature prompt never resolves (a mobile deep-link that failed to
+ * re-open the wallet), stop waiting after this and surface a retry. Long enough
+ * for a real human to review + sign, short enough to recover from a dead prompt.
+ */
+export declare const SIGN_PROMPT_TIMEOUT_MS = 90000;
+export interface StealthMetaAddress {
+    spendingPubKey: string;
+    viewingPubKey: string;
+    chainId: ChainId;
+}
+export interface WalletContext {
+    /** Connected account, or null with no wallet. */
+    address: string | null;
+    /**
+     * The wallet's ACTUAL chain (it may be one the app has no config for,
+     * xochi#539), or null when none is reported.
+     */
+    chainId: number | null;
+    /**
+     * A deep-link wallet (mobile WalletConnect) that will not re-open for a
+     * second back-to-back prompt, so the pull signature waits for a user tap.
+     */
+    stepwise: boolean;
+}
+/** The trade the host's form describes, plus the wallet it is connected with. */
+export interface Context {
+    /** Origin can be non-EVM (a Tron deposit route); destination too. */
+    fromChainId: SelectableChainId;
+    toChainId: SelectableChainId;
+    fromToken: string;
+    toToken: string;
+    settlementPreference: SettlementType;
+    trustScore: number;
+    slippageBps: number;
+    /** Recipient on the destination chain (non-EVM routes); null for EVM. */
+    recipientAddress: string | null;
+    /** Refund destination on a deposit-route ORIGIN; null for EVM origins. */
+    refundAddress: string | null;
+    stealthMetaAddress: StealthMetaAddress | null;
+    /** The confirm surface is open: pre-expiry refreshes run silently. */
+    paused: boolean;
+    wallet: WalletContext;
+}
+export interface MachineConfig {
+    /** The build's pinned origin-pull recipients (fail-closed, see solverPin.ts). */
+    solverPin: SolverPinConfig;
+    /**
+     * The caller's per-chain, per-method pull-recipient pin, handed to
+     * `@xochi/signer`'s `assertPullMatchesIntent` at quote ingest. A chain absent
+     * from it is left to `solverPin`; a chain present without the method in use
+     * refuses. Never built from `/api/capabilities`: an advertisement arrives over
+     * the same channel as the quote it would vouch for.
+     */
+    pullRecipients?: PinnedPullRecipients;
+    /**
+     * The pinned deposit-attestation signer (0x address). `null` refuses every
+     * deposit route. Caller-supplied for the same reason as `pullRecipients`.
+     */
+    depositAttestationSigner: string | null;
+}
+export type TimerName = "debounce" | "refresh" | "expiry" | "poll" | "signPrompt" | "execute";
+export type ApiCall = {
+    op: "quote";
+    flight: string;
+    request: QuoteRequest;
+    forceRefresh: boolean;
+} | {
+    op: "execute";
+    flow: string;
+    request: ExecuteRequest;
+} | {
+    op: "status";
+    intentId: string;
+    gen: number;
+    attempt: number;
+};
+export type WalletCall = 
+/**
+ * Prove the wallet to the worker (SIWE) before allocating a deposit route.
+ * Non-interactive means "only if a session already exists": a background
+ * refresh never opens a surprise wallet prompt.
+ */
+{
+    op: "ensureSession";
+    flight: string;
+    interactive: boolean;
+} | {
+    op: "signTypedData";
+    flow: string;
+    purpose: "intent" | "pull";
+    typedData: Eip712TypedData;
+    /** The wallet's current chain, which the host binds into the domain. */
+    chainId: number | null;
+}
+/** One-time token approval for the origin pull (base units). */
+ | {
+    op: "ensureApproval";
+    flow: string;
+    amount: string;
+} | {
+    op: "resetApproval";
+};
+export type TimerCall = {
+    op: "set";
+    timer: TimerName;
+    ms: number;
+    repeat: boolean;
+} | {
+    op: "clear";
+    timer: TimerName;
+};
+export type MachineEvent = {
+    kind: "log";
+    level: "debug" | "warn" | "error";
+    message: string;
+    data: unknown[];
+}
+/** The outcome of one explicit deposit-route allocation (`AllocateRequested.ref`). */
+ | {
+    kind: "allocation";
+    ref: string;
+    ok: boolean;
+};
+export type Effect = {
+    type: "Api";
+    call: ApiCall;
+} | {
+    type: "Wallet";
+    call: WalletCall;
+} | {
+    type: "Timer";
+    call: TimerCall;
+} | {
+    type: "Emit";
+    event: MachineEvent;
+};
+/** A failure the host observed, already classified (the machine sees no Error objects). */
+export interface ErrorReport {
+    /** The wallet said the user declined (EIP-1193 4001 and kin). */
+    rejected: boolean;
+    /**
+     * What `intent.error` becomes: a StructuredError for an API failure (code +
+     * retryAfter), the message for an Error, null for a non-Error throw (the
+     * machine then supplies its own fallback copy).
+     */
+    value: string | StructuredError | null;
+    /** For the log line only. */
+    detail: string;
+    /**
+     * Execute only, and only from `ApiError.notAccepted`: the server proved it
+     * refused before accepting anything, so the machine may send the SAME
+     * request again at `value.retryAfter` (`decideExecuteResend`). Anything but
+     * `true` is a thrown execute like any other: the poll decides it.
+     */
+    notAccepted?: boolean;
+}
+export type Outcome<T> = ({
+    ok: true;
+} & T) | {
+    ok: false;
+    error: ErrorReport;
+};
+export type MsgBody = {
+    type: "ContextChanged";
+    ctx: Context;
+} | {
+    type: "QuoteRequested";
+    amount: string;
+}
+/** `key` is a fresh idempotency key, used only if none is held for this amount. */
+ | {
+    type: "AllocateRequested";
+    key: string;
+    ref: string;
+} | {
+    type: "RefreshRequested";
+} | {
+    type: "SignRequested";
+} | {
+    type: "PullSignRequested";
+} | {
+    type: "CancelSignRequested";
+} | {
+    type: "ResetRequested";
+} | {
+    type: "ResumeRequested";
+    intentId: string;
+    status: IntentStatus;
+    owner: string;
+    depositDeadline: number | null;
+    /**
+     * The record's `substatus` as `getIntent` returns it now
+     * (`IntentRecord.substatus`). A resumed `failed` offers Retry only with
+     * `NOT_EXECUTED_SUBSTATUS`; any other, or none, resumes as "may have
+     * moved" (README "Fund safety"). Read it from the Worker at resume, never
+     * from host storage: the machine trusts it as it trusts every reply the
+     * host relays, and a stored copy can be stale or altered.
+     */
+    substatus?: string | null;
+} | {
+    type: "VisibilityChanged";
+} | {
+    type: "StreamStatus";
+    message: IntentWebSocketMessage;
+} | {
+    type: "TimerFired";
+    timer: TimerName;
+} | {
+    type: "SessionReplied";
+    flight: string;
+    result: "ok" | "refused" | "skipped";
+} | {
+    type: "QuoteReplied";
+    flight: string;
+    result: Outcome<{
+        quote: QuoteResponse;
+    }>;
+} | {
+    type: "SignReplied";
+    flow: string;
+    purpose: "intent" | "pull";
+    result: Outcome<{
+        signature: string;
+    }>;
+} | {
+    type: "ApprovalReplied";
+    flow: string;
+    result: Outcome<{
+        approved: boolean;
+    }>;
+}
+/**
+ * The execute response with its `readToken` removed (`ExecuteReply`): the
+ * host keeps the bearer secret outside the machine and relays the rest. The
+ * machine itself decides failed vs in doubt (#226); a reply it cannot read
+ * as an execute response for this intent is in doubt, like a thrown execute.
+ */
+ | {
+    type: "ExecuteReplied";
+    flow: string;
+    result: Outcome<{
+        response: ExecuteReply;
+    }>;
+} | {
+    type: "StatusReplied";
+    gen: number;
+    attempt: number;
+    result: Outcome<{
+        status: IntentStatusResult;
+    }>;
+};
+/** Every message carries the clock and tab visibility it was observed under. */
+export type Msg = MsgBody & {
+    now: number;
+    hidden: boolean;
+};
+export interface QuoteFlight {
+    id: string;
+    /** Waiting on the wallet session or the quote itself. */
+    stage: "session" | "api";
+    amount: string;
+    /**
+     * Refresh in place without churning the confirm surface: no "quoting" flash,
+     * and a failed refresh keeps the last good quote.
+     */
+    silent: boolean;
+    forceRefresh: boolean;
+    allocate: {
+        key: string;
+        ref: string;
+    } | null;
+    /** The context the request was built from, held so the gates check that deal. */
+    ctx: Context;
+    depositOrigin: boolean;
+    preview: boolean;
+    request: QuoteRequest | null;
+}
+export interface SignFlow {
+    id: string;
+    /** Which user action started this leg: Confirm, or the "Sign 2 of 2" tap. */
+    origin: "sign" | "pull";
+    stage: "intent" | "approval" | "pull" | "execute";
+    intentSignature: string | null;
+    /** Stage `execute`: the request dispatched and its not-accepted resends. */
+    execute?: ExecuteAttempt;
+}
+/**
+ * The execute of a sign flow. `request` is held so an execute the server did
+ * not accept (`ErrorReport.notAccepted`) is sent again unchanged; `resendAt`
+ * (epoch ms) is set only while waiting for that resend, with no request in
+ * flight, and `error` is the refusal shown if the wait ends in Retry.
+ */
+export interface ExecuteAttempt {
+    request: ExecuteRequest;
+    resends: number;
+    resendAt: number | null;
+    error: string | StructuredError | null;
+}
+export interface PollState {
+    key: string;
+    intentId: string;
+    gen: number;
+    /** Every poll performed in this arming (what the reconcile escalation counts). */
+    polls: number;
+    /**
+     * The newest attempt answered so far. Replies can land out of order (a timer
+     * read and an off-interval read in flight together).
+     */
+    answered: number;
+    /** Elapsed intervals with nothing observed (the give-up budget). */
+    spent: number;
+    max: number;
+    stopped: boolean;
+}
+export interface Model {
+    config: MachineConfig;
+    ctx: Context;
+    hidden: boolean;
+    intent: IntentState;
+    /** The pay amount (base units) the panel last asked to quote. */
+    amount: string;
+    allocationKey: string | null;
+    awaitingPull: boolean;
+    isSigningPull: boolean;
+    /** The intent signature held between signature 1 and the deferred pull. */
+    pendingIntentSig: string | null;
+    quoteExpiresIn: number | null;
+    /** When the signed intent went to the solver (fill clock start). */
+    submittedAt: number | null;
+    /**
+     * Submit -> filled, set only on an inline (execute-reply) completion: a
+     * poll-observed completion is up to a poll interval late.
+     */
+    clientFillMs: number | null;
+    notFoundReported: string | null;
+    seq: number;
+    flights: QuoteFlight[];
+    sign: SignFlow | null;
+    poll: PollState | null;
+    refresh: {
+        amount: string;
+        hasAllocatedDeposit: boolean;
+    } | null;
+    /**
+     * The trade (`tradeKey`) the held quote was requested for. With
+     * `intent.quotedFromAmount` it decides whether the quote on screen still
+     * describes the form (`holdsCurrentQuote`); null until a quote lands.
+     */
+    quotedTrade: string | null;
+    /**
+     * Deposit address -> the intent it was attested for, for every deposit route
+     * verified this session (keyed as `@xochi/signer`'s `recordDepositAddress`
+     * keys it). A per-session tripwire, not a ledger: a fresh `init` clears it.
+     */
+    seenDepositAddresses: Readonly<Record<string, string>>;
+    /** Last-evaluated keys of the reactive rules in `settle`. */
+    watched: {
+        wallet: string;
+        upgrade: string;
+        expiry: string | null;
+    };
+}
+export declare function init(config: MachineConfig, ctx: Context, hidden?: boolean): Model;
+export declare function update(model: Model, msg: Msg): [Model, Effect[]];
+/**
+ * The held quote still describes the trade on the form: the amount and every
+ * request field it was quoted for. Confirm and the receipt's signing slot both
+ * read it, so neither offers to sign a quote for a trade the user has edited.
+ */
+export declare function holdsCurrentQuote(m: Model): boolean;