@xochi/client 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,527 @@
+/**
+ * Wire shapes and decoders.
+ *
+ * The worker speaks the canonical snake_case contract (`QuoteResponseSchema` in
+ * `@xochi/shared`, `public/openapi.yaml`); everything past this module is
+ * camelCase. Decoding happens HERE, once, so the trade widget and `@xochi/sdk`
+ * read a quote, an execute result and an intent status through the same code
+ * rather than through two mappers that drift.
+ */
+import type { ChainId, SelectableChainId, SettlementType, DestinationType, FeeBreakdown, FeeDenomination, Eip712TypedData, SettlementOption, QuoteResponseWire, ExecuteResponseWire, IntentStatus } from "../shared/index.js";
+/** Full destination specification */
+export interface IntentDestination {
+    type: DestinationType;
+    chainId?: ChainId;
+    shielded: boolean;
+    /**
+     * Recipient address on the destination chain, for a non-EVM settlement (Tron).
+     * The user types it; EVM routes settle to the connected wallet and omit it.
+     */
+    recipientAddress?: string;
+}
+export interface QuoteRequest {
+    wallet?: string;
+    /** Ask for pricing only. Preview quotes cannot be signed or executed. */
+    preview?: boolean;
+    /** Idempotency key for one explicit Tron deposit-route allocation. */
+    allocationKey?: string;
+    fromChainId: SelectableChainId;
+    toChainId: SelectableChainId;
+    fromToken: string;
+    toToken: string;
+    fromAmount: string;
+    deadline: number;
+    slippageBps: number;
+    trustScore?: number;
+    settlementPreference: SettlementType;
+    /** Recipient on the destination chain (non-EVM routes); omit for EVM. */
+    recipientAddress?: string;
+    /**
+     * Refund destination on the ORIGIN chain, for a deposit-route origin (Tron).
+     * Omit for EVM origins, where a refund goes back to the connected wallet.
+     * See xochi#358: without it a refund pays the on-chain deposit sender, which
+     * strands funds when the deposit came from an exchange.
+     */
+    refundAddress?: string;
+    destination?: IntentDestination;
+    /** Stealth meta-address for stealth settlements */
+    stealthMetaAddress?: {
+        spendingPubKey: string;
+        viewingPubKey: string;
+        chainId: ChainId;
+    };
+}
+/** Stealth settlement claim info (factory + salt for counterfactual SimpleAccount) */
+export interface ClaimInfo {
+    factoryAddress: string;
+    salt: number;
+}
+export interface QuoteResponse {
+    success: boolean;
+    intentId: string;
+    quoteId: string;
+    canSolve: boolean;
+    /** True when this is a non-persisted, non-executable public price preview. */
+    preview?: boolean;
+    toAmount: string;
+    minToAmount: string;
+    xochiFee: string;
+    xochiFeeRate: string;
+    /**
+     * All-in cost of this quote in basis points, measured server-side by the same
+     * fixed-cost guard that refuses an uneconomical order. Distinct from
+     * `xochiFeeRate`, which is the flat schedule rate: this one moves with route
+     * and size. Absent when the guard could not run -- render nothing, not zero.
+     */
+    costBps?: number;
+    /** Itemized layer split; absent until the worker/Riddler emit it. */
+    feeBreakdown?: FeeBreakdown;
+    /**
+     * Which token `feeBreakdown`'s layer AMOUNTS are measured in: `"origin"` =
+     * from-token base units, `"destination"` = to-token base units.
+     *
+     * On the wire so the renderer reads the denomination instead of inferring it
+     * from which branch produced the breakdown. Formatting a fee with the wrong
+     * token's decimals misstates it by the exchange rate (by 10^12 on an
+     * 18-decimal origin), and every live route today is 6 decimals on both sides,
+     * so the mistake is invisible until it is not.
+     *
+     * Absent means UNKNOWN, never a default. The worker emits it whenever it
+     * forwards a served breakdown and omits it when there is no breakdown.
+     */
+    feeDenomination?: FeeDenomination;
+    estimatedGasCost: string;
+    /**
+     * Subscribe capability for this intent's live status + race stream, served
+     * once with the quote. TREAT AS A BEARER TOKEN: possession is the entire
+     * authorization and the relay replays its recent buffer to each new
+     * subscriber. Never log it and never put it in a shared URL.
+     *
+     * Absent means no stream (an intent quoted before the field existed), which
+     * the client must read as "poll only" rather than substituting the intentId.
+     * That substitution is the bug this field exists to prevent: the id is public
+     * by construction.
+     */
+    streamTopic?: string;
+    expiry: string;
+    gasless: boolean;
+    gaslessFee?: string;
+    paymentMethod?: PaymentMethod;
+    eip712Data?: Eip712TypedData;
+    /**
+     * Origin-pull authorization served by the solver. The user signs this in
+     * addition to eip712Data; the signature is sent as pullSignature on execute.
+     * Present when the route requires origin collection (erc3009 / permit2).
+     */
+    pullAuthorization?: Eip712TypedData;
+    /**
+     * Non-EVM origin (Tron): the per-intent address the user manually sends
+     * TRC-20 to. Mutually exclusive with pullAuthorization. Only ever surfaced to
+     * the UI after depositAttestation verifies against the pinned signer.
+     */
+    depositAddress?: string;
+    /** Solver attestation over the deposit binding; verified fail-closed. */
+    depositAttestation?: string;
+    /** Deposit-acceptance deadline (unix seconds) for a deposit route. */
+    depositDeadline?: number;
+    /**
+     * The RESOLVED settlement type the quote is served under, read from
+     * `route.settlement_type`. Distinct from the value REQUESTED: the solver may
+     * serve a different one, and the v2 deposit attestation signs the resolved
+     * value. Undefined when the solver did not state it, which a deposit route
+     * must treat as a refusal rather than assuming "public" -- guessing here would
+     * silently diverge from the signed message on every quote.
+     */
+    settlementType?: SettlementType;
+    /**
+     * The served `escrow` envelope, verbatim, when the quote carried the key.
+     * Not modelled: it is held only so the `@xochi/signer` checks the machine
+     * runs at ingest can see it. This client does not run the escrow binding, so
+     * a quote whose `escrow` is anything but absent or `null` is refused before
+     * it can reach the wallet.
+     */
+    escrow?: unknown;
+    /**
+     * Echo of the requested destination recipient (non-EVM/Tron routes). The
+     * client asserts a solvable quote echoes exactly the address it asked for
+     * (fail-closed on mismatch); absent for EVM routes. See #113.
+     */
+    recipientAddress?: string;
+    settlementOptions: SettlementOption[];
+    claimInfo?: ClaimInfo;
+    error?: string;
+    /**
+     * Stable machine key for a declined quote (served beside `error`). Branch on
+     * this, never on the prose: the wire contract documents the vocabulary and
+     * says an unrecognized value is a non-retryable decline.
+     */
+    errorCategory?: string;
+    /**
+     * Smallest order (USD) that clears this route right now; served on an
+     * `amount_too_small` decline. THE number to retry with (it already covers
+     * the solver floor and the fixed-cost threshold). Moves with corridor cost,
+     * so never cache it.
+     */
+    minimumAmountUsd?: number;
+    /**
+     * The solver's own live floor (USD), for transparency copy only. An order at
+     * exactly this figure delivers almost nothing; never offer it as the retry.
+     */
+    minFillableUsd?: number;
+    destination?: IntentDestination;
+}
+export interface ExecuteRequest {
+    intentId: string;
+    quoteId: string;
+    signature: string;
+    nonce: number;
+    pullSignature?: string;
+    aztecProof?: string;
+}
+export interface ExecuteResponse {
+    success: boolean;
+    intentId: string;
+    status: IntentStatus;
+    txHash?: string;
+    /** Destination fill hash (cross-chain); usually arrives later via status/WS. */
+    receivingTxHash?: string;
+    /** Public fill receipt (Riddler #632) + its chain, when a fill resolves inline. */
+    settlementTxHash?: string;
+    settlementChainId?: ChainId;
+    bridgeTxHash?: string;
+    /** In-doubt: funds may be in flight but unconfirmed. */
+    reconciling?: boolean;
+    error?: string;
+    /**
+     * `NOT_EXECUTED_SUBSTATUS` on a `failed` the Worker wrote knowing nothing
+     * moved; the only `failed` the machine offers Retry on after an execute.
+     */
+    substatus?: string;
+    /** Note commitment for shielded settlements */
+    noteCommitment?: string;
+    /** Stealth settlement info */
+    stealthAddress?: string;
+    ephemeralPubKey?: string;
+    viewTag?: number;
+    /**
+     * Per-intent read capability (xochi#563), served once and only by a server
+     * that issues it (xochi#565, merged as `0317e84`, once deployed). Keep it
+     * with the intent and pass it as `readToken` to `getIntent` /
+     * `getIntentStatus`: a stealth intent read without it omits its on-chain
+     * legs. A token read of a shielded intent gets only the status-only view, as
+     * an anonymous read does (SPEC.md §5.1, `IntentReadOptions`).
+     * A bearer secret: never log it or put it in a URL.
+     */
+    readToken?: string;
+}
+/**
+ * An execute response as the machine receives it in `ExecuteReplied`: the
+ * bearer `readToken` removed (`const { readToken, ...response } = ...`) and
+ * kept outside the machine, so no message, model, effect or replay log holds
+ * it. The machine derives the fund-safety verdict (#226) from this response
+ * itself; a host relays it and never decides it.
+ */
+export type ExecuteReply = Omit<ExecuteResponse, "readToken"> & {
+    readToken?: never;
+};
+export type IntentMessageType = "intent_status";
+/**
+ * The status update `useIntent` applies. In-app only, never a wire shape: the
+ * status poll builds it from `/api/intent/:id/status`, and `mapStatusFrame`
+ * builds it from the stream's `IntentStatusFrame` (`@xochi/shared`).
+ */
+export interface IntentWebSocketMessage {
+    type: IntentMessageType;
+    intentId: string;
+    status: IntentStatus;
+    txHash?: string;
+    /** Destination fill hash (broadcast on cross-chain completion). */
+    receivingTxHash?: string;
+    /** Public fill receipt (Riddler #632) + its chain, broadcast on completion. */
+    settlementTxHash?: string;
+    settlementChainId?: ChainId;
+    /** In-doubt signal (broadcast when an execute lands in reconcile). */
+    reconciling?: boolean;
+    /**
+     * Riddler's granular fill substatus, verbatim; see IntentState.substatus. On
+     * a `failed`, `NOT_EXECUTED_SUBSTATUS` is the Worker's "nothing moved".
+     */
+    substatus?: string;
+    error?: string;
+    /** Machine-readable refund reason code (deposit routes) on a `refunded` status. */
+    refundReason?: string;
+    timestamp: string;
+}
+/** How the token pull + gas execution is handled */
+export type PaymentMethod = "erc3009" | "permit2" | "pimlico" | "x402" | "mpp" | "approval" | "deposit";
+export declare function isQuoteResponseWire(value: unknown): value is QuoteResponseWire & {
+    readonly escrow?: unknown;
+};
+export declare function isExecuteResponseWire(value: unknown): value is ExecuteResponseWire;
+/**
+ * Read the resolved settlement type out of the solver's opaque `route` bag.
+ *
+ * `route` is `z.record(z.string(), z.unknown())` in the contract: a passthrough
+ * the worker does not model, so it arrives untyped. Narrow it to the closed
+ * settlement vocabulary here rather than casting, and return undefined for
+ * anything unrecognised. Callers that need it (the v2 deposit attestation) must
+ * treat undefined as a refusal: a wrong guess produces a message that fails to
+ * recover, which reads as a solver outage rather than as our bug.
+ */
+export declare function readResolvedSettlementType(route: Record<string, unknown> | undefined): SettlementType | undefined;
+export declare function mapQuoteResponse(w: QuoteResponseWire & {
+    readonly escrow?: unknown;
+}): QuoteResponse;
+export declare function mapExecuteResponse(w: ExecuteResponseWire): ExecuteResponse;
+export declare const RACE_MESSAGE_TYPES: readonly ["race_started", "solver_bid", "race_won"];
+export type RaceMessageType = (typeof RACE_MESSAGE_TYPES)[number];
+/**
+ * Live race telemetry relayed from Riddler while an intent fills.
+ *
+ * DISPLAY ONLY. Intent status comes from lifecycle (`status`) frames and the status
+ * poll; nothing here may advance a swap or change what the user is told they
+ * received. `solver` is a pseudonymous handle, never an operator identity or an
+ * address, and `elapsedMs` is the server's clock (the local one is decoration).
+ */
+export interface RaceWebSocketMessage {
+    type: RaceMessageType;
+    intentId: string;
+    solver?: string;
+    /** Destination amount this bid delivers (base units, string). */
+    amountOut?: string;
+    /** Price improvement against the accepted quote, in bps. */
+    improvementBps?: number;
+    /** Solvers active on this route when the race opened (race_started only). */
+    solversActive?: number;
+    /** Server-side ms since the race opened. */
+    elapsedMs?: number;
+    timestamp: string;
+}
+export declare function isRaceWebSocketMessage(value: unknown): value is RaceWebSocketMessage;
+/**
+ * Granular origin-pull states the solver may emit that the `IntentStatus`
+ * union doesn't model, bucketed into the nearest known state. Unknown/granular
+ * strings otherwise reach `phaseFromStatus` (which drops them to the confirm
+ * screen) and fall outside the poll's in-flight set (freezing the row mid-flight
+ * -- the dead-spinner bug).
+ */
+export declare const GRANULAR_WIRE_STATUS: Readonly<Record<string, IntentStatus>>;
+/**
+ * A raw `/status` value, decoded.
+ *
+ * `mapped` is a status this build models: a union member, or one of Riddler's
+ * granular strings bucketed above. `unmapped` is any other string, and it is
+ * deliberately NOT a guess at an outcome: it buckets to `executing` so the poll
+ * runs on to a real terminal (an unrecognized string must never freeze the row),
+ * and the machine shows it as "Still confirming" (reconciling) rather than as a
+ * normal in-flight step. It can never decode to `completed`. This is the
+ * fail-closed half of the CLAUDE.md "Status-vocabulary sync" rule.
+ *
+ * `absent` is a body with no status string at all: not a Riddler status, so
+ * not a vocabulary signal. It keeps the in-flight bucket and nothing else.
+ */
+export type DecodedWireStatus = {
+    kind: "mapped";
+    status: IntentStatus;
+} | {
+    kind: "unmapped";
+    status: "executing";
+    raw: string;
+} | {
+    kind: "absent";
+    status: "executing";
+};
+export declare function decodeWireStatus(raw: unknown): DecodedWireStatus;
+/**
+ * The normalized status of an in-flight intent, read from `GET
+ * /api/intent/:id/status`.
+ */
+export interface IntentStatusData {
+    /**
+     * The intent this status is about, echoed by the worker (`intent_id` on every
+     * branch of `buildStatusDeliverable`). Carried so a consumer that merges the
+     * response into a stored record can check it is merging into the right one;
+     * null when an older worker omits it.
+     */
+    intentId: string | null;
+    status: IntentStatus;
+    /**
+     * True when the wire status was outside this build's vocabulary and `status`
+     * is only the in-flight bucket (`decodeWireStatus`). Absent means mapped.
+     */
+    unmapped?: boolean;
+    txHash: string | null;
+    receivingTxHash: string | null;
+    /** Public fill receipt (Riddler #632) + its chain; the receipt CTA keys off these. */
+    settlementTxHash: string | null;
+    settlementChainId: number | null;
+    error: string | null;
+    /** Machine-readable refund reason code (deposit routes); null otherwise. */
+    refundReason: string | null;
+    /**
+     * Riddler's granular origin-pull/fill substatus, passed through verbatim
+     * (pulling | pulled | filling | filled | refunding | ...), or on a `failed`
+     * the Worker wrote knowing nothing moved, `NOT_EXECUTED_SUBSTATUS`. NOT a
+     * status: the top-level `status` is what advances the lifecycle.
+     *
+     * It is read for two things. A `failed` after an execute offers Retry only
+     * with `not_executed` (README "Fund safety"). And it tells a user whose
+     * destination leg has already landed (`filled`) apart from one still
+     * waiting: Riddler can hold an intent at top-level `settling` with
+     * `substatus: filled` indefinitely, which is exactly the state a stuck
+     * stealth swap sits in (xochi#376): the money is delivered and the app was
+     * showing an undifferentiated "settling".
+     */
+    substatus: string | null;
+    terminal: boolean;
+    /**
+     * Present (true) when the server withheld the on-chain legs of a stealth or
+     * shielded intent from this read (xochi#563; served by xochi#565, merged as
+     * `0317e84`, once deployed): the read carried no owner proof. The tx hashes
+     * and `settlementChainId` are then null because they were withheld, not
+     * because they do not exist, and the server omits `substatus` unless it is
+     * `not_executed`. A wallet SIWE session for the intent's wallet reads them,
+     * and so does the read token of a stealth intent only: a token read of a
+     * shielded intent gets this view too (SPEC.md §5.1).
+     */
+    legsWithheld?: true;
+    /**
+     * Present only with `legsWithheld`: true once the destination fill receipt
+     * exists, standing in for the withheld `settlementTxHash`; never true on a
+     * terminal failure (`withheldSettlementConfirmed`). The machine shows it
+     * exactly as `substatus: "filled"` (delivered); it does not move `status` or
+     * `terminal`.
+     */
+    settlementConfirmed?: boolean;
+}
+/**
+ * Discriminated result of a status poll:
+ *  - `IntentStatusData` on a 200,
+ *  - `{ notFound: true }` on a definitive 404 (a definitive absence, NOT a
+ *    verdict: only a pre-dispatch row may be terminalized on it, see
+ *    `isSweepablePreDispatch`, and a "not sent yet" intent ends on it as
+ *    nothing moved once past its finish, see `IntentState.notSent`),
+ *  - `null` on a transient failure (retry on the next tick).
+ */
+export type IntentStatusResult = IntentStatusData | {
+    notFound: true;
+} | null;
+/**
+ * Statuses that are settled: no further status polling is needed. Xochi's own
+ * lifecycle vocabulary (`IntentStatus`), and the fallback the status decoder
+ * uses when the worker omits `terminal`.
+ */
+export declare const TERMINAL_INTENT_STATUSES: Readonly<Partial<Record<IntentStatus, true>>>;
+export declare function isTerminalIntentStatus(status: IntentStatus): boolean;
+/**
+ * Whether an anonymous read's `settlement_confirmed` (xochi#563) counts as a
+ * delivered fill. Only on a read that withheld the legs (the marker stands in
+ * for the withheld receipt), and only when `status` decodes (`decodeWireStatus`)
+ * to a status this build models that is not a terminal failure and not part of
+ * a refund: never on `refunded` / `failed` / `expired`, on a granular status
+ * bucketed to one (`fill_failed`, `refund_failed`), on any `refund*` status
+ * (`refunding`, `refund_pending`), or on an unmapped or absent status.
+ */
+export declare function withheldSettlementConfirmed(read: {
+    status: unknown;
+    legsWithheld: unknown;
+    settlementConfirmed: unknown;
+}): boolean;
+export interface IntentRecord {
+    id: string;
+    walletAddress: string;
+    status: IntentStatus;
+    fromChainId: ChainId;
+    toChainId: ChainId;
+    fromToken: string;
+    toToken: string;
+    /**
+     * Absent when the server did not serve it, never defaulted: a withheld or
+     * missing amount is not zero (SPEC.md §5.1). The same for `toAmount`,
+     * `createdAt` and `updatedAt`.
+     */
+    fromAmount?: string;
+    toAmount?: string;
+    quoteId: string;
+    tier: string;
+    feeRate: number;
+    settlementType: SettlementType;
+    aztecNoteHash?: string;
+    txHash?: string;
+    /** Public fill receipt (Riddler #632) + its chain, persisted at completion. */
+    settlementTxHash?: string;
+    settlementChainId?: ChainId;
+    createdAt?: string;
+    updatedAt?: string;
+    error?: string;
+    /** `NOT_EXECUTED_SUBSTATUS` on a `failed` the Worker wrote knowing nothing moved. */
+    substatus?: string;
+    destinationType?: DestinationType;
+    /** Never true on a full record: see `WithheldIntentRecord`. */
+    legsWithheld?: false;
+}
+/**
+ * `GET /api/intent/:id` read without owner proof (xochi#563; served by
+ * xochi#565 once deployed): the server's status-only view, for a stealth
+ * intent read without the read token or an owner session, and for a shielded
+ * intent read without an owner session, token or not (SPEC.md §5.1,
+ * `IntentReadOptions`). Tokens, amounts, wallet, quote, tier, fee, timestamps
+ * and every tx hash are withheld, so they are absent here rather than
+ * defaulted, and `substatus` is present only when it is `not_executed`; read
+ * with the token (stealth), or a wallet SIWE session for the intent's wallet,
+ * for the full `IntentRecord`.
+ */
+export interface WithheldIntentRecord {
+    legsWithheld: true;
+    id: string;
+    /**
+     * The served status decoded (`decodeWireStatus`): a granular one
+     * (`fill_failed`) as its bucket, an unmodelled one as `executing` with
+     * `unmapped: true`.
+     */
+    status: IntentStatus;
+    /** True when the served status was outside this build's vocabulary. Absent means mapped. */
+    unmapped?: true;
+    fromChainId?: ChainId;
+    toChainId?: ChainId;
+    settlementType?: SettlementType;
+    error?: string;
+    /** As on `IntentRecord`. */
+    substatus?: string;
+    /**
+     * True once the destination fill receipt exists (it is withheld itself);
+     * never on a terminal failure (`withheldSettlementConfirmed`).
+     */
+    settlementConfirmed: boolean;
+}
+export interface IntentRecordWire {
+    id: string;
+    wallet_address?: string;
+    status: string;
+    from_chain_id?: ChainId;
+    to_chain_id?: ChainId;
+    from_token?: string;
+    to_token?: string;
+    from_amount?: string;
+    to_amount?: string;
+    quote_id?: string;
+    tier?: string;
+    fee_rate?: number;
+    settlement_type?: SettlementType;
+    aztec_note_hash?: string;
+    tx_hash?: string;
+    settlement_tx_hash?: string | null;
+    settlement_chain_id?: ChainId | null;
+    created_at?: string;
+    updated_at?: string;
+    error?: string;
+    substatus?: string | null;
+    legs_withheld?: boolean;
+    settlement_confirmed?: boolean;
+}
+/**
+ * One `GET /api/intent/:id` body: the status-only `WithheldIntentRecord` when
+ * the server says it withheld the legs, else the full record.
+ */
+export declare function mapIntentRead(w: IntentRecordWire): IntentRecord | WithheldIntentRecord;
+export declare function mapIntentRecord(w: IntentRecordWire): IntentRecord;