@xochi/client 0.0.0-stage → 0.1.1

package/dist/cjs/shared/schemas.js

@@ -0,0 +1,524 @@
+"use strict";
+/**
+ * Zod Schemas
+ *
+ * The Worker's quote and execute RESPONSE wire contract (`/api/intent/quote`,
+ * `/api/intent/execute`), with the primitives it closes over. Types are derived
+ * from schemas via z.infer -- single source of truth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUOTED_EXPIRY_GRACE_SECS = exports.EXECUTE_RESEND_MARGIN_SECS = exports.MAX_EXECUTE_RESENDS = exports.ExecuteResponseSchema = exports.READ_TOKEN_HEADER = exports.READ_TOKEN_PATTERN = exports.READ_TOKEN_LENGTH = exports.QuoteResponseSchema = exports.FeeDenominationSchema = exports.FeeBreakdownSchema = exports.ClaimInfoSchema = exports.SettlementOptionSchema = exports.Eip712TypedDataSchema = exports.QuotePromoSchema = exports.PROMO_TIER_BETTER_NOTE = exports.PROMO_NOT_APPLIED_NOTE = exports.PROMO_CODE_REGEX = exports.QuoteReferralSchema = exports.REFERRAL_NEUTRAL_NOTE = exports.REFERRAL_NOT_APPLIED_NOTE = exports.REFERRAL_CODE_REGEX = exports.paymentMethod = exports.settlementType = exports.recipientAddress = exports.tronAddress = exports.ethAddress = void 0;
+const zod_1 = require("zod");
+const validators_js_1 = require("./validators.js");
+const intents_js_1 = require("./intents.js");
+// ============================================================
+// Primitives
+// ============================================================
+/** Ethereum address: 0x-prefixed, 42 hex chars. Single source: validators.ts. */
+exports.ethAddress = zod_1.z.string().regex(validators_js_1.ETH_ADDRESS_REGEX);
+/**
+ * Tron base58check address: leading `T`, 34 chars, base58 alphabet (no
+ * 0/O/I/l). Structural check mirroring `TRON_ADDRESS_REGEX` in validators.ts;
+ * kept inline here so the schema module stays free of the viem import chain.
+ */
+exports.tronAddress = zod_1.z
+    .string()
+    .regex(/^T[1-9A-HJ-NP-Za-km-z]{33}$/, "Must be a Tron base58 address");
+/**
+ * Recipient address for a non-EVM destination: the user's own address on the
+ * destination chain (EVM routes settle to the signing wallet, so it is
+ * optional). EVM hex20 or Tron base58.
+ */
+exports.recipientAddress = zod_1.z.union([exports.ethAddress, exports.tronAddress]);
+/** Settlement type */
+exports.settlementType = zod_1.z
+    .enum(["public", "shielded", "stealth"])
+    .describe("Where the payout lands. `public` settles to the wallet address. `stealth` settles to a one-time address on Ethereum L1 (ERC-5564). `shielded` (Aztec L2 notes) is planned and not yet live: it is gated by SHIELDED_SETTLEMENT_LIVE, served as unavailable in `settlement_options`, and refused as a `settlement_preference` while that is off. Read `settlement_options` for live availability rather than assuming this enum's members are all fillable.");
+/**
+ * Pull+gas payment method the quote's eip712 authorizes.
+ *
+ * `deposit` is the odd one out and is not a pull at all: on a non-EVM origin
+ * (Tron) the user sends the tokens themselves to a served `deposit_address`,
+ * at their own network cost, with no wallet signature anywhere in the flow.
+ * It is in this enum because it is what belongs in this FIELD, which answers
+ * "how does the origin leg get funded".
+ *
+ * Without it the wire lies: a Tron-origin quote reports `payment_method:
+ * "permit2"` next to `gasless: false` and a `deposit_address`, describing a
+ * Permit2 pull on a chain that has no Permit2. The browser papers over it
+ * (`resolvePaymentMethod` overrides to `deposit` whenever a deposit address is
+ * present), so a human never sees the wrong label; every non-browser consumer
+ * does: the MCP server, the OpenAPI contract, and any agent branching on this
+ * field to decide whether to prepare a signature.
+ */
+exports.paymentMethod = zod_1.z.enum([
+    "erc3009",
+    "permit2",
+    "pimlico",
+    "x402",
+    "mpp",
+    "approval",
+    "deposit",
+]);
+// ============================================================
+// Referral and promo outcomes (quote response siblings of fee_breakdown)
+// ============================================================
+/**
+ * A referral code as stored (xochi#583): 3-32 of `A-Z 0-9 _ -`, starting with a
+ * letter or digit. Stored and compared uppercase, so a link's `?ref=summer` and
+ * `SUMMER` are the same code. Migration 0019 enforces the same shape.
+ */
+exports.REFERRAL_CODE_REGEX = /^[A-Z0-9][A-Z0-9_-]{2,31}$/;
+/**
+ * The note served when a `ref` was sent and is not applied. ONE text for every
+ * reason (unknown, expired, revoked, scoped to another key, a key that does not
+ * accept referrals, self-referral): a per-reason note would let a caller
+ * enumerate which codes exist.
+ */
+exports.REFERRAL_NOT_APPLIED_NOTE = "Referral code not applied.";
+/**
+ * The neutral referral line (xochi#603): served on a quote whose `ref` was
+ * applied when the request is not signed in as the quoting wallet. One fixed
+ * text, identical whether or not the wallet has a referral binding.
+ */
+exports.REFERRAL_NEUTRAL_NOTE = "A referrer may earn part of the routing fee on this trade.";
+exports.QuoteReferralSchema = zod_1.z
+    .union([
+    zod_1.z
+        .object({
+        code: zod_1.z
+            .string()
+            .regex(exports.REFERRAL_CODE_REGEX)
+            .describe("The code this trade credits, normalized uppercase."),
+        name: zod_1.z
+            .string()
+            .describe("Affiliate display name, rendered as `Referral: {name}` on the routing line."),
+    })
+        .strict()
+        .describe("Served only when the request carries a wallet-bound session (SIWE JWT or Mandate) for the quoting wallet: the code the trade will credit if executed now. The wallet's open referral binding wins over `ref`; otherwise it is the applied `ref`."),
+    zod_1.z
+        .object({
+        neutral: zod_1.z.literal(true),
+        note: zod_1.z.literal(exports.REFERRAL_NEUTRAL_NOTE),
+    })
+        .strict()
+        .describe("Served when `ref` was applied but the request is not signed in as the quoting wallet: a referrer may be credited, and who is not said. Identical whether or not the wallet has a referral binding."),
+])
+    .describe("Who earns the routing fee layer (`fee_breakdown.routing_fee`) in place of the publishable key's routing recipient. Attribution only: no amount, rate or total differs from the same quote without `ref`.");
+/**
+ * A promo code as stored (xochi#584): 3-32 of `A-Z 0-9 _ -`, starting with a
+ * letter or digit. Stored and compared uppercase, so `launch10` and `LAUNCH10`
+ * are the same code. Migration 0020 enforces the same shape.
+ */
+exports.PROMO_CODE_REGEX = /^[A-Z0-9][A-Z0-9_-]{2,31}$/;
+/**
+ * The inline error served when a `promo` was sent and cannot be used. ONE text
+ * for every reason (unknown, malformed, expired, revoked, used up, used up by
+ * this wallet, not accepted under this publishable key, lookup ceiling, the
+ * feature off): a per-reason message would let a caller enumerate which codes
+ * exist.
+ */
+exports.PROMO_NOT_APPLIED_NOTE = "This code can't be applied.";
+/**
+ * The note served when a valid code was sent but the caller's trust tier
+ * already discounts at least as much (discount = max(tier, capped promo), never
+ * both; an Institutional wallet always lands here). The code is
+ * not consumed.
+ */
+exports.PROMO_TIER_BETTER_NOTE = "Your trust tier already gives you a fee at least as low as this code.";
+exports.QuotePromoSchema = zod_1.z
+    .object({
+    code: zod_1.z.string().regex(exports.PROMO_CODE_REGEX).describe("The applied code, normalized uppercase."),
+    discount_bps: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .describe("Discount this code bought, in bps off the Standard venue + routing layers for the route's asset class. Already reflected in every amount of this quote and itemized as `fee_breakdown.discount`."),
+})
+    .strict()
+    .describe("Present when the `promo` sent on the quote was applied: it beat the caller's trust-tier discount and priced this quote. One use of the code is counted when this quote is executed, not now; if the code is used up or withdrawn by then, execute refuses with `promo_unavailable` and the caller re-quotes.");
+// ============================================================
+// Response Schemas (worker -> client/agent wire contract)
+// ============================================================
+/**
+ * EIP-712 typed data the user signs. Internal keys follow the EIP-712
+ * standard (camelCase: domain.chainId, domain.verifyingContract, primaryType)
+ * and are part of the signed payload -- they are intentionally NOT snake_cased.
+ * Passed through verbatim from the solver. Mirrors the `Eip712TypedData`
+ * schema in public/openapi.yaml.
+ */
+exports.Eip712TypedDataSchema = zod_1.z.object({
+    // Two domain shapes coexist: legacy Xochi-owned structs and token-pull
+    // domains carry `verifyingContract`; the Riddler XochiIntent v3 domain carries
+    // `salt` (keccak256(version)) and NO verifyingContract. Both fields are
+    // optional so either shape validates and both survive the parse verbatim -- a
+    // stripped `salt` or an injected `verifyingContract` would change the domain
+    // separator and strand the signature.
+    domain: zod_1.z.object({
+        name: zod_1.z.string(),
+        version: zod_1.z.string(),
+        chainId: zod_1.z.number().int(),
+        verifyingContract: exports.ethAddress.optional(),
+        salt: zod_1.z.string().optional(),
+    }),
+    types: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.object({ name: zod_1.z.string(), type: zod_1.z.string() }))),
+    primaryType: zod_1.z.string(),
+    message: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+exports.SettlementOptionSchema = zod_1.z.object({
+    type: exports.settlementType,
+    available: zod_1.z.boolean(),
+    reason: zod_1.z.string().optional(),
+});
+exports.ClaimInfoSchema = zod_1.z.object({
+    factory_address: exports.ethAddress,
+    salt: zod_1.z.number().int(),
+});
+/**
+ * A fee layer AMOUNT in token base units: digits only, no sign, no decimal
+ * point, no exponent, no `0x`.
+ *
+ * A plain `z.string()` would admit `""`, `"0.5"`, `"1.2e3"` and `"-5"`. Every
+ * consumer immediately does `BigInt()` on these to reconcile the layers against
+ * `total_fee`, and `BigInt` throws on three of those four and silently returns
+ * `0n` on the empty string -- so the loose type turns an upstream formatting
+ * change into a 500 on every quote for the route (nothing wraps the
+ * reconciliation in a try/catch). The producer (Riddler `fee_policy.ex`,
+ * `calculate_layered_fee`) emits `Integer.to_string` of a non-negative integer
+ * for all five, so this narrowing describes what is actually served rather
+ * than restricting it.
+ *
+ * Deliberately NOT applied to `gas_floor.usd` or `total_usd`: those are dollar
+ * figures and are legitimately decimal ("0.022663").
+ */
+const feeLayerBaseUnits = zod_1.z
+    .string()
+    .regex(/^\d+$/)
+    .describe("Fee layer amount in token base units (integer, no decimal point). " +
+    "Denominated in the token named by the response's `fee_denomination`.");
+/**
+ * Itemized fee breakdown (economics.md Part 1). snake_case wire shape the worker
+ * emits and the frontend renders against. Layers are three additive bps lines on
+ * a never-discounted cost floor (solver + gas), plus venue and routing.
+ *
+ * The layer AMOUNTS carry no denomination of their own. The token they are
+ * measured in is named by `fee_denomination` on the enclosing quote response.
+ */
+exports.FeeBreakdownSchema = zod_1.z.object({
+    // The SOLVER's view of the caller's tier, under which IT computed the layer
+    // amounts below. NOT the authority on the caller's tier: Xochi resolves that
+    // from D1 (`user_tiers`) and the client-supplied `trust_score` is never
+    // trusted. The two can legitimately disagree for a quote or two after an
+    // upgrade, because the solver's copy of the score lags D1's. Render the
+    // caller's tier from the Xochi-side value; read this one only as the label
+    // that explains these particular numbers.
+    tier: zod_1.z
+        .enum(["standard", "trusted", "verified", "premium", "institutional"])
+        .describe("The SOLVER's view of the tier, and the schedule it priced these layer " +
+        "amounts under. Not the authority on the caller's tier -- Xochi resolves " +
+        "that from its own records, and the solver's copy of the trust score can " +
+        "lag a fresh upgrade by a quote or two. Use it to explain these numbers, " +
+        "never to display the user's tier."),
+    asset_class: zod_1.z.enum(["stable", "volatile"]),
+    gas_floor: zod_1.z.object({ amount: zod_1.z.string(), usd: zod_1.z.string() }),
+    solver_fee_bps: zod_1.z.number(),
+    solver_fee: feeLayerBaseUnits,
+    price_impact_bps: zod_1.z.number(),
+    price_impact: feeLayerBaseUnits,
+    venue_fee_bps: zod_1.z.number(),
+    venue_fee: feeLayerBaseUnits,
+    routing_fee_bps: zod_1.z.number(),
+    routing_fee: feeLayerBaseUnits,
+    total_bps: zod_1.z.number(),
+    total_fee: feeLayerBaseUnits,
+    total_usd: zod_1.z.string(),
+    surplus_share_pct: zod_1.z.number(),
+    // Present when a promo code was in play on the quote (xochi#584): which
+    // discount priced it and how much it took off the Standard venue + routing
+    // layers. Emitted by the solver, which priced it; the worker reads `source`
+    // to decide whether the code was applied rather than assuming it was.
+    discount: zod_1.z
+        .object({
+        source: zod_1.z
+            .enum(["tier", "promo"])
+            .describe("Which discount priced this quote: the trust tier's or the promo code's. They never stack: discount = max(tier, min(promo, Institutional discount))."),
+        bps: zod_1.z
+            .number()
+            .int()
+            .nonnegative()
+            .describe("Basis points taken off the Standard venue + routing layers for this asset class. Never off the solver spread or the gas floor."),
+        amount: feeLayerBaseUnits,
+    })
+        .strict()
+        .optional()
+        .describe("The applied discount as a labelled line INSIDE `total_fee`: `venue_fee` and `routing_fee` are already net of it, so it is never subtracted again. Render it as e.g. `Promo LAUNCH10 -0.05%`. Absent when no promo code was sent."),
+});
+/**
+ * Which token the `fee_breakdown` layer amounts are measured in. See the
+ * `fee_denomination` field on {@link QuoteResponseSchema}.
+ */
+exports.FeeDenominationSchema = zod_1.z.enum(["origin", "destination"]);
+/**
+ * Canonical quote response: the Xochi worker's `/api/intent/quote` output and
+ * the pinned agent contract. snake_case envelope; the `eip712` value is
+ * verbatim EIP-712 typed data. When `can_solve` is true, `to_amount`,
+ * `payment_method`, and `eip712` are present. Mirrors `QuoteResponse` in
+ * public/openapi.yaml -- keep all three in lockstep.
+ */
+exports.QuoteResponseSchema = zod_1.z
+    .object({
+    success: zod_1.z.boolean(),
+    intent_id: zod_1.z.string(),
+    quote_id: zod_1.z.string(),
+    can_solve: zod_1.z.boolean(),
+    /** Non-executable price exploration: never persisted and carries no signing material. */
+    preview: zod_1.z.boolean().optional(),
+    to_amount: zod_1.z.string().optional(),
+    min_to_amount: zod_1.z.string().optional(),
+    xochi_fee: zod_1.z.string().optional(),
+    xochi_fee_rate: zod_1.z.string().optional(),
+    cost_bps: zod_1.z
+        .number()
+        .nonnegative()
+        .optional()
+        .describe("All-in cost of this quote in basis points, from the same fixed-cost " +
+        "guard that refuses an uneconomical order, so the displayed price and " +
+        "the refusal threshold cannot disagree. Unlike xochi_fee_rate (a flat " +
+        "schedule rate) this moves with route and size: cost is " +
+        "max(gas floor of the destination chain, the fee rate), so it rises " +
+        "as the order shrinks. BOUNDED BY THE GUARD: an order whose cost " +
+        "exceeds the ceiling is declined with error_category " +
+        "'amount_too_small' and carries no cost_bps at all, so every served " +
+        "value sits at or below the ceiling (150 bps at MAX_COST_RATIO 0.015). " +
+        "Do not model a range above it. Omitted when the origin token has no " +
+        "dollar value on the worker and the guard could not run -- absent " +
+        "means unknown, never zero. Unrounded: below half a basis point the " +
+        "distinction between a free fill and a merely cheap one still matters, " +
+        "and rounding server-side destroys it."),
+    // Itemized layer split; optional until the worker/Riddler emit it.
+    fee_breakdown: exports.FeeBreakdownSchema.optional(),
+    // Which token `fee_breakdown`'s amounts are measured in. Carried on the wire
+    // rather than inferred from the MERE PRESENCE of fee_breakdown, which would
+    // rest on an undocumented convention in another repo (Riddler's
+    // fee_policy.ex computes every layer off `input_amount`): the xochi#410
+    // failure class, a cross-repo fact with no runtime evidence in this one.
+    fee_denomination: exports.FeeDenominationSchema.optional().describe("Which token the `fee_breakdown` layer AMOUNTS are denominated in. " +
+        "'origin' means `from_token` base units, 'destination' means `to_token` " +
+        "base units. Formatting a fee with the wrong token's decimals and symbol " +
+        "misstates it by the exchange rate, and on a USDC->USDC route (6 decimals " +
+        "both sides) the mistake is invisible -- which is why this is stated on " +
+        "the wire instead of inferred from the presence of `fee_breakdown`. " +
+        "PROVENANCE: the solver does not emit this field yet, so today Xochi " +
+        "asserts it from the solver's documented convention (every layer computed " +
+        "off the input amount, hence 'origin') rather than reporting a value the " +
+        "solver stated. It is forwarded verbatim once the solver does send one. " +
+        "Treat it as Xochi's best statement of the denomination, not as the fee " +
+        "computer's own declaration. ABSENT MEANS UNKNOWN, never a default: when " +
+        "there is no `fee_breakdown` the field is omitted entirely."),
+    // Referral attribution for the routing layer (xochi#583). Xochi-owned and
+    // a sibling of `fee_breakdown` rather than inside it: the breakdown is the
+    // solver's itemization and may be absent, while the routing line exists on
+    // every quote (the client derives one without a breakdown).
+    referral: exports.QuoteReferralSchema.optional(),
+    referral_note: zod_1.z
+        .literal(exports.REFERRAL_NOT_APPLIED_NOTE)
+        .optional()
+        .describe("Present when a `ref` was sent and not applied. Deliberately one fixed text for every reason (unknown, expired, revoked, not valid for this key, a key that does not accept referrals, self-referral), so the response does not reveal whether a code exists. The quote is otherwise identical to one sent without `ref`."),
+    // Promo code outcome (xochi#584). Xochi-owned siblings of `fee_breakdown`:
+    // the breakdown itemizes the discount (`fee_breakdown.discount`), these say
+    // whether the code the caller sent is the thing that priced it.
+    promo: exports.QuotePromoSchema.optional(),
+    promo_note: zod_1.z
+        .enum([exports.PROMO_NOT_APPLIED_NOTE, exports.PROMO_TIER_BETTER_NOTE])
+        .optional()
+        .describe("Inline message for a `promo` that did not price this quote. The quote is still served, priced as if no code had been sent. `" +
+        exports.PROMO_NOT_APPLIED_NOTE +
+        "` is deliberately one fixed text for every reason (unknown, expired, revoked, used up, this wallet's limit reached, not accepted under this publishable key), so the response does not reveal whether a code exists. `" +
+        exports.PROMO_TIER_BETTER_NOTE +
+        "` means the code is valid but the trust-tier discount is at least as large; it is not consumed."),
+    estimated_gas_cost: zod_1.z.string().optional(),
+    stream_topic: zod_1.z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{16,64}$/)
+        .optional()
+        .describe("Subscribe capability for this intent's live status and fill-race " +
+        "stream, at `GET /api/stream/<stream_topic>` (WebSocket upgrade). " +
+        "TREAT IT AS A BEARER TOKEN: possession is the whole authorization, " +
+        "there is no second check, and the relay replays its recent event " +
+        "buffer to every new subscriber. It is served exactly once, in this " +
+        "response, and is never returned by a read endpoint. Keep it out of " +
+        "logs and out of URLs you share. It is deliberately NOT the " +
+        "`intent_id` beside it: that value is public by construction (it " +
+        "appears in status paths and in server logs), so a stream keyed on it " +
+        "would be readable by anyone who has ever seen one. Absent on an " +
+        "intent quoted before this field existed, which means no stream is " +
+        "available; fall back to polling `GET /api/intent/:id/status`, which " +
+        "is the durable path in every case."),
+    expiry: zod_1.z.string(),
+    gasless: zod_1.z.boolean().optional(),
+    gasless_fee: zod_1.z.string().optional(),
+    payment_method: exports.paymentMethod.optional(),
+    route: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    eip712: exports.Eip712TypedDataSchema.optional(),
+    // Origin-pull authorization: a second EIP-712 the user signs so the solver
+    // can collect origin funds before settling. ReceiveWithAuthorization (USDC
+    // domain) for erc3009, PermitWitnessTransferFrom for permit2. Absent for
+    // non-pulling methods and the mock path.
+    pull_authorization: exports.Eip712TypedDataSchema.optional(),
+    // Non-EVM origin (Tron): the per-intent address the user manually sends TRC-20
+    // to. Mutually exclusive with pull_authorization (a deposit route has no
+    // typed-data pull). Base58check -- never lowercased.
+    deposit_address: zod_1.z.string().optional(),
+    // Solver attestation binding the deposit_address to this intent. The client
+    // verifies the signature against a pinned signer BEFORE displaying the address
+    // (fail-closed); an absent/invalid attestation makes the route unavailable.
+    deposit_attestation: zod_1.z.string().optional(),
+    // Deposit-acceptance deadline (unix seconds) for a deposit route -- decoupled
+    // from the shorter quote `expiry` so a manual TRC-20 transfer has time to land.
+    // Drives the deposit countdown.
+    deposit_deadline: zod_1.z.number().int().optional(),
+    // Echo of the requested destination recipient (non-EVM/Tron routes). These
+    // routes carry no wallet signature, so recipient integrity rides on this
+    // authenticated channel: the client asserts the solvable quote echoes exactly
+    // the address it asked for and fail-closes otherwise (#113). Base58 is
+    // case-sensitive -- passed through verbatim, never lowercased.
+    recipient_address: exports.recipientAddress.optional(),
+    settlement_options: zod_1.z.array(exports.SettlementOptionSchema).optional(),
+    claim_info: exports.ClaimInfoSchema.optional(),
+    // Execute replay-dedup nonce the GET alias injects (absent from the POST
+    // envelope) so a third-party ACP agent need not do the pull-nonce bit math
+    // itself. Derived from the pull-authorization nonce (see deriveReplayNonce).
+    // Optional: the POST omits it, and the GET omits it too on a pull-less route.
+    nonce: zod_1.z.number().int().min(0).optional(),
+    error: zod_1.z.string().optional(),
+    // Present on the unsolvable-200 branch: `error_category` is a stable machine
+    // key for the reject class, `detail` the solver's raw reason. Absent on
+    // solvable quotes.
+    //
+    // Enumerated so the generated spec documents the vocabulary agents branch on,
+    // and so adding a category without declaring it fails the contract tests.
+    // Four are worker-side fail-closed guards; the rest come from
+    // `classifyDecline` (decline.ts), whose returns are a closed set of literals
+    // with `unknown` as the catch-all.
+    // Documented, deliberately NOT enumerated. The worker owns four of these,
+    // but the rest come from `classifyDecline` (decline.ts) over solver reasons,
+    // and the contract test below asserts an unlisted value still parses -- this
+    // side of the vocabulary is intentionally open, so a new upstream reason must
+    // not start failing every client that validates.
+    error_category: zod_1.z
+        .string()
+        .optional()
+        .describe("Stable machine key for a declined quote. Branch on this rather than on `error`, whose prose may change. Known values: gas_floor_unpriced (transient, retry), origin_pull_amount_mismatch, served_payout_mismatch, settlement_type_unavailable, stealth_factory_untrusted, refund_address_invalid, amount_too_large, amount_too_small, no_liquidity, route_unsupported, invalid_request (the request shape was rejected, not the route -- see `detail` for the offending field), auth, unknown. Treat an unrecognized value as a non-retryable decline."),
+    detail: zod_1.z.string().optional(),
+    // Present when `error_category` is `amount_too_small` because the route's
+    // FIXED settlement cost consumed too much of the order: the smallest order
+    // (USD) that clears the threshold at the current cost. Lets a caller retry
+    // with a workable amount instead of bisecting for one. Not a protocol
+    // constant -- it moves with the corridor's cost, so read it per quote.
+    minimum_amount_usd: zod_1.z
+        .number()
+        .positive()
+        .optional()
+        .describe("Smallest order in USD you should send on this route. THIS is the number to retry with; it already accounts for both the solver's floor and the fixed-cost threshold, so it is >= `min_fillable_usd`. Present on an `amount_too_small` decline. Varies with the corridor's current cost, so do not cache it."),
+    // The solver's own live bounds, passed through on a bounds decline. Both
+    // are served, so an undeclared one makes the strict schema reject a
+    // legitimate decline and leaves it out of the generated spec (#754).
+    min_fillable_usd: zod_1.z
+        .number()
+        .positive()
+        .optional()
+        .describe("The solver's live per-corridor floor: the smallest order it will fill at all, which is its own cost to fill. Reported for transparency. Do NOT retry with this figure -- an order at exactly the solver's cost delivers almost nothing. Use `minimum_amount_usd`."),
+    max_order_usd: zod_1.z
+        .number()
+        .positive()
+        .optional()
+        .describe("The solver's live per-trade ceiling in USD. Present on an `amount_too_large` decline."),
+})
+    .strict();
+/**
+ * Length of an intent read capability (`read_token` on the execute response,
+ * xochi#563): 32 random bytes as unpadded base64url.
+ */
+exports.READ_TOKEN_LENGTH = 43;
+/** Shape of an intent read capability: exactly `READ_TOKEN_LENGTH` base64url characters. */
+exports.READ_TOKEN_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${exports.READ_TOKEN_LENGTH}}$`);
+/**
+ * The request header that carries a `read_token` on `GET /api/intent/:id` and
+ * `GET /api/intent/:id/status`. A header and never a query parameter: the token
+ * must not land in URLs, logs or referrers.
+ */
+exports.READ_TOKEN_HEADER = "X-Xochi-Read-Token";
+/** Mirrors `ExecuteResponse` in public/openapi.yaml. */
+exports.ExecuteResponseSchema = zod_1.z
+    .object({
+    success: zod_1.z.boolean(),
+    intent_id: zod_1.z.string(),
+    status: zod_1.z.string(),
+    tx_hash: zod_1.z.string().optional(),
+    // Per-leg hashes for cross-chain: the origin/deposit leg is `tx_hash`, the
+    // destination fill is `receiving_tx_hash` (arrives later via status/WS).
+    bridge_tx_hash: zod_1.z.string().optional(),
+    receiving_tx_hash: zod_1.z.string().optional(),
+    // Public destination fill receipt (Riddler #632) + its chain, when a same-chain
+    // or fast fill resolves inline; usually arrives later via the status poll.
+    settlement_tx_hash: zod_1.z.string().optional(),
+    settlement_chain_id: zod_1.z.number().int().optional(),
+    // In-doubt: the solver may have moved funds but did not confirm. The intent
+    // stays non-terminal; surface this so the client shows "still confirming"
+    // rather than a success or a failure.
+    reconciling: zod_1.z.boolean().optional(),
+    note_commitment: zod_1.z.string().optional(),
+    stealth_address: zod_1.z.string().optional(),
+    ephemeral_pub_key: zod_1.z.string().optional(),
+    view_tag: zod_1.z.number().int().optional(),
+    error: zod_1.z.string().optional(),
+    substatus: zod_1.z
+        .literal(intents_js_1.NOT_EXECUTED_SUBSTATUS)
+        .optional()
+        .describe("`not_executed` on a `failed` where nothing moved, served by the execute 502 of the worker's own finishes (the resend budget's, a not-accepted refusal whose un-claim's write failed, no solver configured, a solver refusal carrying `details.funds_moved: false`) and echoed from the row by the lost-race 502 and the in-doubt 200: safe to re-quote. Absent on any other failure. Every source: docs/contracts/xochi-intent-api.md, \"The worker's not_executed marker\"."),
+    // Per-intent read capability (xochi#563): 32 random bytes, base64url, no
+    // padding. Served once, by the execute that admits the intent; present it as
+    // `X-Xochi-Read-Token` on `GET /api/intent/:id[/status]` to read the owner's
+    // view of a stealth intent; a shielded intent's token read gets the
+    // status-only view (SPEC.md §5.1). Older servers omit it. The one declared
+    // field that never fails the body: a malformed token is dropped, because this
+    // body reports an execute that may already have moved funds, and failing it
+    // would turn a settled swap into an in-doubt one over a privacy-only field.
+    // The describe is xochi's (xochi#565, `0317e84`) verbatim.
+    read_token: zod_1.z
+        .string()
+        .regex(exports.READ_TOKEN_PATTERN)
+        .optional()
+        .catch(undefined)
+        .describe("Per-intent read capability (xochi#563): 32 random bytes, base64url without padding. Returned to the request that claimed the intent for execution, on every answer where funds may have moved: the 200, the 502 of an unmarked solver refusal or failure this request wrote, a 502 whose status another writer decided, and the outcome unknown after the claim. Never on a `not_executed` answer, an un-claim back to `quoted` (the not-accepted 503, the in-doubt 200 with `status: \"quoted\"`) or a retried execute. Store it with the intent id and send it as the `X-Xochi-Read-Token` header on `GET /api/intent/{id}` and `/status` to get the owner's full view of a stealth intent without a wallet session. On a shielded intent it reads only the status-only view (legs_withheld), like an anonymous read; only a SIWE session for the intent's wallet reads that full record. A bearer secret: never log it or put it in a URL. The server stores only its SHA-256, so it cannot be re-issued; signing in with the intent's wallet (SIWE) reads the same view."),
+})
+    .strict();
+/**
+ * Automatic resends of one execute after its not-accepted answer. Mirrors
+ * `MAX_EXECUTE_RESENDS` in xochi's `@xochi/shared` `schemas.ts`, the budget
+ * the Worker enforces too: the refusal that follows this many un-claims
+ * finishes the intent `failed` instead.
+ */
+exports.MAX_EXECUTE_RESENDS = 3;
+/**
+ * A resend must reach the Worker at least this many seconds before the
+ * earliest deadline the signed request carries. Mirrors
+ * `EXECUTE_RESEND_MARGIN_SECS` in xochi's `@xochi/shared` `schemas.ts`, the
+ * margin the Worker applies before it un-claims.
+ */
+exports.EXECUTE_RESEND_MARGIN_SECS = 5;
+/**
+ * Seconds past an unexecuted intent's signed deadline before the Worker ends
+ * it: a `quoted` market row (never claimed, or every claim undone) that an
+ * intent read (`GET /api/intent/:id` or the status poll, never the stream)
+ * finds this far past the `deadline` the user signed is finished `failed`
+ * with `NOT_EXECUTED_SUBSTATUS`, and the read serves that. Slack for clock
+ * skew between the Worker, the database (whose clock the claim's deadline
+ * check uses), the solver and the client. Measured from the signed deadline;
+ * the quote sweep's own 60 s is measured from the Worker's 30 s quote expiry
+ * and usually ends a touched row first (README "Fund safety"). Mirrors
+ * `QUOTED_EXPIRY_GRACE_SECS` in xochi's `@xochi/shared` `schemas.ts`. The
+ * machine polls an execute at least this long past the quote's deadline
+ * (`unexecutedFinishAt`).
+ */
+exports.QUOTED_EXPIRY_GRACE_SECS = 60;

package/dist/cjs/shared/stealth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Stealth settlement constants: the SimpleAccount factory + salt a stealth
+ * payout is derived against, and the per-chain allowlist that bounds which
+ * advertised factory may be followed.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-5564
+ * @see https://eips.ethereum.org/EIPS/eip-6538
+ */
+/**
+ * SimpleAccountFactory (v0.8) for the counterfactual stealth destination.
+ * Salt is 0: one account per stealth EOA.
+ *
+ * Canonical home for a security-critical address the client and the worker
+ * both need; never declare a second copy.
+ */
+export declare const SIMPLE_ACCOUNT_FACTORY = "0x13E9ed32155810FDbd067D4522C492D6f68E5944";
+/** CREATE2 salt for the stealth SimpleAccount. One account per stealth EOA. */
+export declare const STEALTH_ACCOUNT_SALT = 0;
+/**
+ * Factories a stealth payout may be derived against, PER DESTINATION CHAIN.
+ *
+ * The client deliberately FOLLOWS the solver-advertised factory rather than its
+ * own pin (#302): if the two disagree they derive different counterfactual
+ * addresses and the recipient cannot find their money. That is the right call
+ * for parity, and it is why this list exists rather than a hard pin.
+ *
+ * Nothing else constrains WHAT may be advertised. The factory decides who owns
+ * the account the payout lands in, so an advertised factory that deploys an
+ * account owned by someone else is theft, and both sides would have agreed on
+ * it. This is the trust anchor the advertised value is checked against: follow
+ * the solver, but only into a factory this build already knows.
+ *
+ * Keyed by chain rather than a flat list because the capability matrix is
+ * expected to go per-chain, and a flat list would then accept a factory
+ * legitimate on one chain as authorization for another. Stealth is pinned to
+ * Ethereum L1 today (STEALTH_SETTLEMENT_CHAIN_ID), so there is exactly one
+ * entry; an unlisted chain has no trusted factory and fails closed.
+ *
+ * ROTATION: ship a build listing both the old and new factory for that chain,
+ * let the solver flip, then drop the old one. Staging it that way keeps the
+ * allowlist fail-closed without a window where stealth is refused.
+ */
+export declare const TRUSTED_STEALTH_FACTORIES: Readonly<Record<number, readonly string[]>>;
+/**
+ * Whether a factory may be used to derive a stealth payout ON THIS CHAIN.
+ *
+ * Case-insensitive: EVM addresses compare case-insensitively and the capability
+ * matrix preserves whatever casing the solver sent. Absent address, absent
+ * chain, or a chain with no listed factory all return false, because "we have
+ * no entry for this" and "this is fine" must not be the same answer about who
+ * receives someone's money.
+ */
+export declare function isTrustedStealthFactory(address: string | undefined | null, chainId: number | undefined | null): boolean;

package/dist/cjs/shared/stealth.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Stealth settlement constants: the SimpleAccount factory + salt a stealth
+ * payout is derived against, and the per-chain allowlist that bounds which
+ * advertised factory may be followed.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-5564
+ * @see https://eips.ethereum.org/EIPS/eip-6538
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRUSTED_STEALTH_FACTORIES = exports.STEALTH_ACCOUNT_SALT = exports.SIMPLE_ACCOUNT_FACTORY = void 0;
+exports.isTrustedStealthFactory = isTrustedStealthFactory;
+const chains_js_1 = require("./chains.js");
+/**
+ * SimpleAccountFactory (v0.8) for the counterfactual stealth destination.
+ * Salt is 0: one account per stealth EOA.
+ *
+ * Canonical home for a security-critical address the client and the worker
+ * both need; never declare a second copy.
+ */
+exports.SIMPLE_ACCOUNT_FACTORY = "0x13E9ed32155810FDbd067D4522C492D6f68E5944";
+/** CREATE2 salt for the stealth SimpleAccount. One account per stealth EOA. */
+exports.STEALTH_ACCOUNT_SALT = 0;
+/**
+ * Factories a stealth payout may be derived against, PER DESTINATION CHAIN.
+ *
+ * The client deliberately FOLLOWS the solver-advertised factory rather than its
+ * own pin (#302): if the two disagree they derive different counterfactual
+ * addresses and the recipient cannot find their money. That is the right call
+ * for parity, and it is why this list exists rather than a hard pin.
+ *
+ * Nothing else constrains WHAT may be advertised. The factory decides who owns
+ * the account the payout lands in, so an advertised factory that deploys an
+ * account owned by someone else is theft, and both sides would have agreed on
+ * it. This is the trust anchor the advertised value is checked against: follow
+ * the solver, but only into a factory this build already knows.
+ *
+ * Keyed by chain rather than a flat list because the capability matrix is
+ * expected to go per-chain, and a flat list would then accept a factory
+ * legitimate on one chain as authorization for another. Stealth is pinned to
+ * Ethereum L1 today (STEALTH_SETTLEMENT_CHAIN_ID), so there is exactly one
+ * entry; an unlisted chain has no trusted factory and fails closed.
+ *
+ * ROTATION: ship a build listing both the old and new factory for that chain,
+ * let the solver flip, then drop the old one. Staging it that way keeps the
+ * allowlist fail-closed without a window where stealth is refused.
+ */
+exports.TRUSTED_STEALTH_FACTORIES = {
+    [chains_js_1.CHAIN_IDS.ethereum]: [exports.SIMPLE_ACCOUNT_FACTORY],
+};
+/**
+ * Whether a factory may be used to derive a stealth payout ON THIS CHAIN.
+ *
+ * Case-insensitive: EVM addresses compare case-insensitively and the capability
+ * matrix preserves whatever casing the solver sent. Absent address, absent
+ * chain, or a chain with no listed factory all return false, because "we have
+ * no entry for this" and "this is fine" must not be the same answer about who
+ * receives someone's money.
+ */
+function isTrustedStealthFactory(address, chainId) {
+    if (!address || chainId === undefined || chainId === null)
+        return false;
+    const allowed = exports.TRUSTED_STEALTH_FACTORIES[chainId];
+    if (!allowed)
+        return false;
+    const normalized = address.toLowerCase();
+    return allowed.some((f) => f.toLowerCase() === normalized);
+}