@xochi/client 0.0.0-stage → 0.1.1

package/dist/esm/machine/wire.js

@@ -0,0 +1,266 @@
+/**
+ * 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 { ExecuteResponseSchema, QuoteResponseSchema, READ_TOKEN_PATTERN, isSettlementType, isIntentStatus, } from "../shared/index.js";
+// ============================================================
+// Wire adapters: snake_case wire (worker/openapi) -> camelCase app types
+//
+// The worker emits the canonical snake_case contract (see QuoteResponseSchema
+// in @xochi/shared and public/openapi.yaml). The React app stays camelCase;
+// intentAPI.ts maps at the client boundary via these helpers. The `eip712`
+// value is verbatim EIP-712 typed data -- its internal keys are already the
+// standard camelCase and pass through unchanged.
+// ============================================================
+/**
+ * The response contracts as the client applies them: every declared field is
+ * held to its schema (a `fee_breakdown` without `gas_floor`, a non-string
+ * `eip712`, a numeric `claim_info.factory_address` all fail), but an
+ * undeclared top-level key is let through rather than failing the whole
+ * quote, so an additive server field does not take every client down. The
+ * decoders read the original object, never the parse output, so the EIP-712
+ * payloads reach the wallet byte-for-byte as served.
+ */
+const QUOTE_RESPONSE = QuoteResponseSchema.passthrough();
+const EXECUTE_RESPONSE = ExecuteResponseSchema.passthrough();
+export function isQuoteResponseWire(value) {
+    return QUOTE_RESPONSE.safeParse(value).success;
+}
+export function isExecuteResponseWire(value) {
+    return EXECUTE_RESPONSE.safeParse(value).success;
+}
+/**
+ * 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 function readResolvedSettlementType(route) {
+    const value = route?.settlement_type;
+    // Reuses the shared predicate rather than re-listing the vocabulary. A second
+    // copy of the closed set compiles fine and silently refuses every deposit
+    // quote on whichever settlement type it forgot.
+    return typeof value === "string" && isSettlementType(value) ? value : undefined;
+}
+export function mapQuoteResponse(w) {
+    return {
+        success: w.success,
+        intentId: w.intent_id,
+        quoteId: w.quote_id,
+        canSolve: w.can_solve,
+        preview: w.preview,
+        toAmount: w.to_amount ?? "0",
+        minToAmount: w.min_to_amount ?? "0",
+        xochiFee: w.xochi_fee ?? "0",
+        xochiFeeRate: w.xochi_fee_rate ?? "",
+        costBps: w.cost_bps,
+        feeBreakdown: w.fee_breakdown
+            ? {
+                tier: w.fee_breakdown.tier,
+                assetClass: w.fee_breakdown.asset_class,
+                gasFloor: {
+                    amount: w.fee_breakdown.gas_floor.amount,
+                    usd: w.fee_breakdown.gas_floor.usd,
+                },
+                solverFeeBps: w.fee_breakdown.solver_fee_bps,
+                solverFee: w.fee_breakdown.solver_fee,
+                priceImpactBps: w.fee_breakdown.price_impact_bps,
+                priceImpact: w.fee_breakdown.price_impact,
+                venueFeeBps: w.fee_breakdown.venue_fee_bps,
+                venueFee: w.fee_breakdown.venue_fee,
+                routingFeeBps: w.fee_breakdown.routing_fee_bps,
+                routingFee: w.fee_breakdown.routing_fee,
+                totalBps: w.fee_breakdown.total_bps,
+                totalFee: w.fee_breakdown.total_fee,
+                totalUsd: w.fee_breakdown.total_usd,
+                surplusSharePct: w.fee_breakdown.surplus_share_pct,
+            }
+            : undefined,
+        // Passed through, never defaulted. An absent field means the server did not
+        // state the denomination, which the renderer has to be able to tell apart
+        // from a server that said "origin".
+        feeDenomination: w.fee_denomination,
+        estimatedGasCost: w.estimated_gas_cost ?? "",
+        // Passed through, never defaulted and never backfilled from intent_id.
+        streamTopic: w.stream_topic,
+        expiry: w.expiry,
+        gasless: w.gasless ?? false,
+        gaslessFee: w.gasless_fee,
+        paymentMethod: w.payment_method,
+        eip712Data: w.eip712,
+        pullAuthorization: w.pull_authorization,
+        depositAddress: w.deposit_address,
+        depositAttestation: w.deposit_attestation,
+        depositDeadline: w.deposit_deadline,
+        settlementType: readResolvedSettlementType(w.route),
+        recipientAddress: w.recipient_address,
+        settlementOptions: w.settlement_options ?? [],
+        claimInfo: w.claim_info
+            ? { factoryAddress: w.claim_info.factory_address, salt: w.claim_info.salt }
+            : undefined,
+        error: w.error,
+        errorCategory: w.error_category,
+        minimumAmountUsd: w.minimum_amount_usd,
+        minFillableUsd: w.min_fillable_usd,
+        // Passed through untouched, never interpreted: the signer refuses it.
+        ...("escrow" in w ? { escrow: w.escrow } : {}),
+    };
+}
+export function mapExecuteResponse(w) {
+    return {
+        success: w.success,
+        intentId: w.intent_id,
+        status: w.status,
+        txHash: w.tx_hash,
+        receivingTxHash: w.receiving_tx_hash,
+        settlementTxHash: w.settlement_tx_hash,
+        settlementChainId: w.settlement_chain_id,
+        bridgeTxHash: w.bridge_tx_hash,
+        reconciling: w.reconciling,
+        error: w.error,
+        ...(typeof w.substatus === "string" ? { substatus: w.substatus } : {}),
+        noteCommitment: w.note_commitment,
+        stealthAddress: w.stealth_address,
+        ephemeralPubKey: w.ephemeral_pub_key,
+        viewTag: w.view_tag,
+        // The decoders read the raw body, not the parse output, so the schema's
+        // drop of a malformed token does not reach here: check it again.
+        readToken: typeof w.read_token === "string" && READ_TOKEN_PATTERN.test(w.read_token)
+            ? w.read_token
+            : undefined,
+    };
+}
+// ============================================================
+// Race Stream Messages
+// ============================================================
+export const RACE_MESSAGE_TYPES = ["race_started", "solver_bid", "race_won"];
+export function isRaceWebSocketMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.type === "string" &&
+        RACE_MESSAGE_TYPES.includes(obj.type) &&
+        typeof obj.intentId === "string");
+}
+// ============================================================
+// Intent status (GET /api/intent/:id/status)
+// ============================================================
+/**
+ * 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 const GRANULAR_WIRE_STATUS = {
+    pulling: "executing",
+    pulled: "executing",
+    filling: "settling",
+    filled: "completed",
+    refunding: "settling",
+    pull_failed: "failed",
+    fill_failed: "failed",
+    refund_failed: "failed",
+};
+export function decodeWireStatus(raw) {
+    if (typeof raw !== "string")
+        return { kind: "absent", status: "executing" };
+    if (isIntentStatus(raw))
+        return { kind: "mapped", status: raw };
+    const bucket = GRANULAR_WIRE_STATUS[raw];
+    if (bucket)
+        return { kind: "mapped", status: bucket };
+    return { kind: "unmapped", status: "executing", raw };
+}
+/**
+ * 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 const TERMINAL_INTENT_STATUSES = {
+    completed: true,
+    failed: true,
+    expired: true,
+    refunded: true,
+};
+export function isTerminalIntentStatus(status) {
+    return TERMINAL_INTENT_STATUSES[status] === true;
+}
+/**
+ * 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 function withheldSettlementConfirmed(read) {
+    if (read.legsWithheld !== true || read.settlementConfirmed !== true)
+        return false;
+    const decoded = decodeWireStatus(read.status);
+    if (decoded.kind !== "mapped")
+        return false;
+    if (typeof read.status === "string" && read.status.startsWith("refund"))
+        return false;
+    return !(isTerminalIntentStatus(decoded.status) && decoded.status !== "completed");
+}
+/**
+ * One `GET /api/intent/:id` body: the status-only `WithheldIntentRecord` when
+ * the server says it withheld the legs, else the full record.
+ */
+export function mapIntentRead(w) {
+    if (w.legs_withheld !== true)
+        return mapIntentRecord(w);
+    const decoded = decodeWireStatus(w.status);
+    return {
+        legsWithheld: true,
+        id: w.id,
+        status: decoded.status,
+        ...(decoded.kind === "unmapped" ? { unmapped: true } : {}),
+        fromChainId: w.from_chain_id,
+        toChainId: w.to_chain_id,
+        settlementType: w.settlement_type,
+        error: w.error,
+        ...(typeof w.substatus === "string" ? { substatus: w.substatus } : {}),
+        settlementConfirmed: withheldSettlementConfirmed({
+            status: w.status,
+            legsWithheld: w.legs_withheld,
+            settlementConfirmed: w.settlement_confirmed,
+        }),
+    };
+}
+export function mapIntentRecord(w) {
+    return {
+        id: w.id,
+        walletAddress: w.wallet_address ?? "",
+        status: w.status,
+        fromChainId: w.from_chain_id,
+        toChainId: w.to_chain_id,
+        fromToken: w.from_token ?? "",
+        toToken: w.to_token ?? "",
+        fromAmount: w.from_amount,
+        toAmount: w.to_amount,
+        quoteId: w.quote_id ?? "",
+        tier: w.tier ?? "",
+        feeRate: w.fee_rate ?? 0,
+        settlementType: w.settlement_type ?? "public",
+        aztecNoteHash: w.aztec_note_hash,
+        txHash: w.tx_hash,
+        settlementTxHash: w.settlement_tx_hash ?? undefined,
+        settlementChainId: w.settlement_chain_id ?? undefined,
+        createdAt: w.created_at,
+        updatedAt: w.updated_at,
+        error: w.error,
+        ...(typeof w.substatus === "string" ? { substatus: w.substatus } : {}),
+    };
+}

package/dist/esm/shared/api.d.ts

@@ -0,0 +1,9 @@
+/**
+ * API types shared by the client and the Worker.
+ */
+import type { SettlementType } from "./intents.js";
+export interface SettlementOption {
+    type: SettlementType;
+    available: boolean;
+    reason?: string;
+}

package/dist/esm/shared/api.js

@@ -0,0 +1,4 @@
+/**
+ * API types shared by the client and the Worker.
+ */
+export {};

package/dist/esm/shared/chains.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Chain Definitions
+ *
+ * Supported chains and their configuration.
+ *
+ * `CHAIN_REGISTRY` is the ONE literal in this file: the `ChainId` union, every
+ * display/lookup map and `SUPPORTED_CHAIN_IDS` are derived from it. `SUPPORTED_CHAIN_IDS`
+ * is typed `readonly ChainId[]`, so a hand-maintained copy that omitted a chain compiled
+ * cleanly and silently excluded it from `isChainId`, `SETTLEABLE_CHAIN_IDS` and the
+ * capabilities fallback; the per-chain maps outside this file (`tokens.ts`) fail to
+ * compile until they carry a new registry entry.
+ */
+/**
+ * One supported EVM chain. `explorer` is an origin with no trailing path.
+ * `nativeCurrency` is the gas token symbol (defaults to "ETH" if omitted).
+ */
+export interface ChainDefinition {
+    readonly id: number;
+    readonly name: string;
+    readonly shortName: string;
+    readonly explorer: string;
+    readonly nativeCurrency?: string;
+}
+/**
+ * The single source of truth for supported EVM chains.
+ *
+ * Keyed by slug rather than by id for two reasons: the slugs are themselves
+ * public API (`CHAIN_IDS.base`), and string keys preserve insertion order, so
+ * `SUPPORTED_CHAIN_IDS` keeps its declared order. Integer-like keys would be
+ * re-sorted ascending by the runtime, which would silently reorder the
+ * `/api/capabilities` fallback payload built from that array.
+ *
+ * Non-EVM and virtual chains are deliberately NOT here: Tron (base58 addresses,
+ * TronWeb signing, hash-route explorer) and the Aztec virtual source chain (0)
+ * are display-only, and join the extended maps below through their own
+ * constants. EVM-only code (viem/wagmi/RPC) must never receive those ids.
+ *
+ * Short names are the compact UI labels; explorers are the origins the link
+ * helpers below build on (one map, so per-component explorer maps cannot
+ * drift).
+ */
+export declare const CHAIN_REGISTRY: {
+    readonly ethereum: {
+        readonly id: 1;
+        readonly name: "Ethereum";
+        readonly shortName: "ETH";
+        readonly explorer: "https://etherscan.io";
+    };
+    readonly optimism: {
+        readonly id: 10;
+        readonly name: "Optimism";
+        readonly shortName: "OP";
+        readonly explorer: "https://optimistic.etherscan.io";
+    };
+    readonly polygon: {
+        readonly id: 137;
+        readonly name: "Polygon";
+        readonly shortName: "POLY";
+        readonly explorer: "https://polygonscan.com";
+        readonly nativeCurrency: "POL";
+    };
+    readonly arbitrum: {
+        readonly id: 42161;
+        readonly name: "Arbitrum";
+        readonly shortName: "ARB";
+        readonly explorer: "https://arbiscan.io";
+    };
+    readonly base: {
+        readonly id: 8453;
+        readonly name: "Base";
+        readonly shortName: "BASE";
+        readonly explorer: "https://basescan.org";
+    };
+    readonly robinhood: {
+        readonly id: 4663;
+        readonly name: "Robinhood";
+        readonly shortName: "HOOD";
+        readonly explorer: "https://robinhoodchain.blockscout.com";
+    };
+    readonly arc: {
+        readonly id: 5042;
+        readonly name: "Arc";
+        readonly shortName: "ARC";
+        readonly explorer: "https://explorer.arc.io";
+        readonly nativeCurrency: "USDC";
+    };
+    readonly gnosis: {
+        readonly id: 100;
+        readonly name: "Gnosis";
+        readonly shortName: "GNO";
+        readonly explorer: "https://gnosisscan.io";
+        readonly nativeCurrency: "xDAI";
+    };
+};
+/** Slug of a supported chain: the `CHAIN_REGISTRY` keys. */
+export type ChainSlug = keyof typeof CHAIN_REGISTRY;
+/** Supported L1/L2 chain IDs, derived from `CHAIN_REGISTRY`. */
+export type ChainId = (typeof CHAIN_REGISTRY)[ChainSlug]["id"];
+/** Aztec virtual chain ID for shielded operations */
+export type AztecChainId = 0;
+/**
+ * Extended chain ID: every UI-renderable chain beyond the core EVM `ChainId`.
+ * Includes the Aztec virtual source chain (0) and non-EVM destinations (Tron).
+ * Used for `Token.chainId` and the display maps (`EXTENDED_CHAIN_NAMES`,
+ * `CHAIN_ICONS`). EVM-only code (viem/wagmi/RPC) must never receive these.
+ */
+export type ExtendedChainId = ChainId | AztecChainId | TronChainId;
+/**
+ * Tron mainnet chain id. Tron is non-EVM (base58 addresses, TronWeb signing),
+ * so it is deliberately kept OUT of the EVM `ChainId` union -- EVM-only code
+ * (viem, wagmi, contract reads) must never receive it. UI-level chain selection
+ * uses `SelectableChainId` below.
+ */
+export declare const TRON_CHAIN_ID = 728126428;
+export type TronChainId = typeof TRON_CHAIN_ID;
+/** Tron display names (Tron is outside CHAIN_REGISTRY, being non-EVM). */
+export declare const TRON_CHAIN_NAME = "Tron";
+export declare const TRON_SHORT_NAME = "TRON";
+/**
+ * Chains a user can pick in the trade UI: every EVM chain plus Tron. Components
+ * that only do chain *selection* (selectors, route display) accept this wider
+ * union; anything that touches an EVM RPC stays on `ChainId`.
+ */
+export type SelectableChainId = ChainId | TronChainId;
+/** Type guard for the Tron mainnet chain id. */
+export declare function isTronChainId(value: unknown): value is TronChainId;
+/**
+ * Type guard for any chain the UI can render a link/name for (every EVM `ChainId`
+ * plus Tron). Guards raw `settlementChainId` values from Riddler -- which adds
+ * chains on its own cadence -- so an unknown id falls back to inference instead of
+ * producing a dead `href=""` or a `View undefined tx` label.
+ */
+export declare function isSelectableChainId(value: unknown): value is SelectableChainId;
+/**
+ * Robinhood Chain (4663): an Arbitrum Orbit L2 whose native stablecoin is USDG
+ * (Global Dollar, Paxos). It has no USDC. The solver settles USDC<->USDG (and
+ * other stablecoin) cross-asset corridors to and from it. It is fully EVM (0x
+ * addresses, EIP-712 signing, Permit2 pull on USDG) and a first-class member
+ * of `ChainId`: the trade UI lists Robinhood + USDG, so the per-chain token
+ * maps carry it. USDG is a first-class token (see USDG_ADDRESSES in
+ * tokens.ts), never shoehorned into USDC_ADDRESSES (that map is Permit2-free
+ * ERC-3009 USDC only, and USDG supports neither ERC-3009 nor EIP-2612).
+ * `ROBINHOOD_CHAIN_ID` is kept for readable references and the settleable
+ * guards below.
+ */
+export declare const ROBINHOOD_CHAIN_ID = 4663;
+export type RobinhoodChainId = typeof ROBINHOOD_CHAIN_ID;
+/** Type guard for the Robinhood Chain id. */
+export declare function isRobinhoodChainId(value: unknown): value is RobinhoodChainId;
+/**
+ * Arc chain id. Arc is Circle's EVM-compatible L1 where USDC is the native
+ * gas token (18 dec protocol-level, 6 dec ERC-20). No WETH, no ETH --
+ * stablecoin-only chain. Feature-flagged behind ARC_LIVE.
+ */
+export declare const ARC_CHAIN_ID = 5042;
+export type ArcChainId = typeof ARC_CHAIN_ID;
+/** Type guard for the Arc chain id. */
+export declare function isArcChainId(value: unknown): value is ArcChainId;
+/**
+ * Gnosis Chain id. Native gas is xDAI. Xochi lists a single token here,
+ * Monerium EURe (18 dec, no ERC-3009, Permit2 pull); there is no WETH or USDC
+ * leg. Feature-flagged in the UI behind GNOSIS_LIVE.
+ */
+export declare const GNOSIS_CHAIN_ID = 100;
+export type GnosisChainId = typeof GNOSIS_CHAIN_ID;
+/** Type guard for the Gnosis Chain id. */
+export declare function isGnosisChainId(value: unknown): value is GnosisChainId;
+/**
+ * Slug -> chain id, derived from the registry, plus the Aztec virtual chain
+ * (0), which has no registry entry because it is not an EVM chain.
+ */
+type ChainIdsBySlug = {
+    readonly [K in ChainSlug]: (typeof CHAIN_REGISTRY)[K]["id"];
+} & {
+    readonly aztec: AztecChainId;
+};
+/** All supported chain IDs */
+export declare const CHAIN_IDS: ChainIdsBySlug;
+/** Chain names for display */
+export declare const CHAIN_NAMES: Record<ChainId, string>;
+/**
+ * Short chain names for compact display. Keyed by `SelectableChainId` so the
+ * non-EVM Tron destination (base58) has a short name too -- the tx-link/name
+ * helpers in the trade result surfaces index this with a destination chain id
+ * that can be Tron.
+ */
+export declare const CHAIN_SHORT_NAMES: Record<SelectableChainId, string>;
+/**
+ * Block explorer origins by chain (no trailing path). Single source of truth --
+ * build tx/address URLs through the helpers below so links always target the
+ * right chain (the old per-component maps drifted and one hardcoded Arbiscan).
+ */
+export declare const CHAIN_EXPLORERS: Record<ChainId, string>;
+/**
+ * Native currency symbol per chain. Used for gas display (QuoteDetails) and
+ * balance labels (usePublicBalances). Most chains use ETH; Polygon uses POL,
+ * Arc uses USDC (native gas token on Circle's stablecoin L1).
+ * Derived from `CHAIN_REGISTRY.nativeCurrency`, defaulting to "ETH".
+ */
+export declare const CHAIN_NATIVE_CURRENCY: Record<ChainId, string>;
+/**
+ * Tronscan uses a `#/` hash route (not the `/tx/` path shape of the EVM
+ * explorers), so Tron links are built separately from `CHAIN_EXPLORERS`.
+ */
+export declare const TRON_EXPLORER = "https://tronscan.org";
+/**
+ * Build a transaction URL on the given chain's explorer (empty if unknown).
+ * Accepts a `SelectableChainId` so a Tron destination fill can be linked; Tron
+ * routes to tronscan's hash-route form.
+ */
+export declare function getExplorerTxUrl(chainId: SelectableChainId, txHash: string): string;
+/** Build an address URL on the given chain's explorer (empty if unknown). */
+export declare function getExplorerAddressUrl(chainId: SelectableChainId, address: string): string;
+/**
+ * Extended chain names including the Aztec source + non-EVM destinations. The
+ * Aztec virtual chain is branded "Xochi" in the UI, which is why its display
+ * name is not simply a chain name.
+ */
+export declare const EXTENDED_CHAIN_NAMES: Record<ExtendedChainId, string>;
+/** Supported chain IDs as array */
+export declare const SUPPORTED_CHAIN_IDS: readonly ChainId[];
+/** Type guard for ChainId */
+export declare function isChainId(value: unknown): value is ChainId;
+/**
+ * A chain id the solver can settle; equals `ChainId` (Robinhood is a first-class chain). The
+ * name is kept for the intent-API call sites (schema validation) that document the settleable
+ * surface explicitly, mirroring xochi's `@xochi/shared`.
+ */
+export type SettleableChainId = ChainId | RobinhoodChainId;
+/**
+ * Chain ids the solver can settle to or from; exactly `SUPPORTED_CHAIN_IDS`. The intent API
+ * (`/api/intent/quote` and `/api/intent/execute`) validates request chain ids against this set.
+ * Token addresses ride in the request body, so the API needs no per-chain token config to
+ * accept a corridor; the solver decides feasibility.
+ */
+export declare const SETTLEABLE_CHAIN_IDS: readonly SettleableChainId[];
+/** Type guard for a settleable chain id (any supported chain, including Robinhood). */
+export declare function isSettleableChainId(value: unknown): value is SettleableChainId;
+/** Type guard for ExtendedChainId (EVM chains + Aztec source + Tron destination). */
+export declare function isExtendedChainId(value: unknown): value is ExtendedChainId;
+/** Check if route between chains is supported */
+export declare function isRouteSupported(from: ChainId, to: ChainId): boolean;
+export {};