@xochi/client 0.1.1 → 0.1.3

package/dist/esm/shared/shieldedPreview.js

@@ -0,0 +1,124 @@
+/**
+ * Riddler's shielded terms preview wire (`POST /xochi/shielded/preview`,
+ * Riddler#1296): the typed request and response shapes and a decoder.
+ *
+ * There is NO transport method: the preview needs a `quote`-scoped Riddler
+ * credential, so only the Xochi Worker calls it, and the Worker proxy route is
+ * a follow-up owned by xochi#635. These shapes exist so that proxy and its
+ * consumers decode the solver's answer with the same schema the solver
+ * publishes (`packages/spec/wire/openapi.json`, `ShieldedPreviewResponse`).
+ *
+ * The preview is NOT a signing payload: `preview_digest` is the EIP-712 digest
+ * of `ShieldedPreviewV1` under the `Xochi Shielded Preview` domain, which no
+ * `ShieldedTermsV1` signature verifies against (`@xochi/spec`
+ * `conformance/shielded-terms.json`, PROPOSED). `executable` is always false.
+ */
+import { z } from "zod";
+import { ethAddress } from "./schemas.js";
+/** 32-byte hex (`0x` + 64). */
+const bytes32 = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+/**
+ * A 32-byte Aztec address or field element. The decoder checks the shape only;
+ * the solver has already refused zero and values at or above the BN254 modulus.
+ * A 20-byte EVM address never fits.
+ */
+export const aztecValue = bytes32;
+/** Canonical unsigned decimal string (uint256 members). */
+const uintString = z.string().regex(/^(0|[1-9][0-9]*)$/);
+/** Canonical positive base-unit amount. */
+const baseUnits = z.string().regex(/^[1-9][0-9]*$/);
+export const ShieldedNetworkIdentitySchema = z.object({
+    aztec_chain_id: z.string().regex(/^[1-9][0-9]*$/),
+    protocol_version: z.string().regex(/^[1-9][0-9]*$/),
+    rollup_address: ethAddress,
+    l1_chain_id: z.string().regex(/^[1-9][0-9]*$/),
+    genesis_or_network_digest: bytes32,
+});
+export const ShieldedCorridorSchema = z.object({
+    corridor_id: bytes32,
+    revision: z.number().int().min(1).max(4294967295),
+    manifest_digest: bytes32,
+});
+export const ShieldedFeeBreakdownSchema = z.object({
+    gas_floor: uintString,
+    solver_fee_bps: z.number().int().min(0).max(10000),
+    solver_fee: uintString,
+    price_impact_bps: z.number().int().min(0).max(10000),
+    price_impact: uintString,
+    venue_fee_bps: z.number().int().min(0).max(10000),
+    venue_fee: uintString,
+    routing_fee_bps: z.number().int().min(0).max(10000),
+    routing_fee: uintString,
+    total_bps: z.number().int().min(0).max(40000),
+    total_fee: uintString,
+});
+/** `ShieldedPreviewV1` in snake_case: the terms minus the per-execution members. */
+export const ShieldedPreviewSchema = z.object({
+    protocol_version: z.literal("xochi.shielded.preview.v1"),
+    environment: z.string().min(1),
+    source: z.object({
+        chain_id: z.number().int().positive(),
+        token_address: ethAddress,
+        wallet: ethAddress,
+        collector: ethAddress,
+        amount: baseUnits,
+    }),
+    destination: z.object({
+        settlement_type: z.literal("shielded"),
+        privacy_level: z.literal("private"),
+        disclosure_profile: z.literal("recipient-private-public-amount-v1"),
+        rail: z.literal("a_tracer"),
+        network: ShieldedNetworkIdentitySchema,
+        corridor: ShieldedCorridorSchema,
+        asset_id: z.string().min(1),
+        token_address: aztecValue,
+        recipient_binding_id: z.string().min(1),
+        recipient_descriptor_digest: bytes32,
+        recipient_address: aztecValue,
+        amount: baseUnits,
+        fee_payer: aztecValue,
+    }),
+    fee_breakdown: ShieldedFeeBreakdownSchema,
+    refund_address: ethAddress,
+    refund_amount: baseUnits,
+    collect_before: z.number().int().nonnegative(),
+    settlement_service_deadline: z.number().int().nonnegative(),
+    recipient_binding_digest: bytes32,
+    policy_revision: z.number().int().nonnegative(),
+});
+export const ShieldedPreviewResponseSchema = z.object({
+    executable: z.literal(false),
+    preview_version: z.literal("xochi.shielded.preview.v1"),
+    preview_digest: bytes32,
+    recipient_binding_digest: bytes32,
+    domain: z.object({
+        name: z.literal("Xochi Shielded Preview"),
+        version: z.literal("1"),
+        chain_id: z.number().int().positive(),
+        salt: bytes32,
+    }),
+    preview: ShieldedPreviewSchema,
+    manifest: z.object({
+        manifest_digest: bytes32,
+        aztec_sdk_version: z.string().min(1),
+        recipient_account_class_id: aztecValue,
+    }),
+});
+/**
+ * Decode a preview response. Throws (zod) on any shape the solver does not
+ * publish, including an executable or terms-shaped answer, and on a fee
+ * breakdown whose totals disagree: `total_fee` must be `max(gas_floor, layers)` (the gas
+ * floor is a minimum fee, as in FeePolicy) and `total_bps` the four rates.
+ */
+export function decodeShieldedPreview(body) {
+    const decoded = ShieldedPreviewResponseSchema.parse(body);
+    const f = decoded.preview.fee_breakdown;
+    const layers = BigInt(f.solver_fee) + BigInt(f.price_impact) + BigInt(f.venue_fee) + BigInt(f.routing_fee);
+    const gasFloor = BigInt(f.gas_floor);
+    const totalFee = layers > gasFloor ? layers : gasFloor;
+    const totalBps = f.solver_fee_bps + f.price_impact_bps + f.venue_fee_bps + f.routing_fee_bps;
+    if (BigInt(f.total_fee) !== totalFee || f.total_bps !== totalBps) {
+        throw new Error("shielded preview fee_breakdown totals disagree with max(gas_floor, layers)");
+    }
+    return decoded;
+}

package/dist/esm/transport/client.d.ts

@@ -38,7 +38,7 @@ export interface RetryPolicy {
     maxAttempts: number;
     /** First exponential backoff step. */
     baseDelayMs: number;
-    /** Clamp on a server-supplied `Retry-After` used for internal pacing. */
+    /** Clamp on client-generated exponential backoff delays. */
     maxDelayMs: number;
 }
 export declare const DEFAULT_TIMEOUTS: TransportTimeouts;
@@ -119,8 +119,9 @@ export declare function takeApiErrorReadToken(error: unknown): string | undefine
 /**
  * Parse a Retry-After header (our API sends integer seconds) into milliseconds,
  * clamped to [0, maxDelayMs] so a malformed or hostile value can't stall the
- * client. Returns null when absent/unparseable so the caller falls back to its
- * own exponential backoff.
+ * client. The default safety ceiling preserves server-directed waits up to
+ * MAX_RETRY_WAIT_SEC; a custom ceiling can narrow them. Returns null when
+ * absent/unparseable so the caller falls back to its own exponential backoff.
  */
 export declare function parseRetryAfterMs(headerValue: string | null, maxDelayMs?: number): number | null;
 /**

package/dist/esm/transport/client.js

@@ -130,11 +130,19 @@ function isNotAcceptedExecuteBody(status, body, intentId) {
  * MAX_RETRY_WAIT_SEC.
  */
 function notAcceptedRetryAt(headers, retryAfter) {
-    const header = headers.get("Retry-After");
-    const headerDelta = header === null || header.trim() === "" ? NaN : Number(header);
-    const wait = Number.isFinite(headerDelta) && headerDelta > retryAfter ? headerDelta : retryAfter;
+    const headerDelta = retryAfterDeltaSeconds(headers.get("Retry-After"));
+    const wait = headerDelta !== null && headerDelta > retryAfter ? headerDelta : retryAfter;
     return Math.ceil((Date.now() + Math.min(wait, MAX_RETRY_WAIT_SEC) * 1000) / 1000);
 }
+/** Retry-After's delta-seconds grammar: optional HTTP whitespace around 1*DIGIT. */
+function retryAfterDeltaSeconds(headerValue) {
+    const value = headerValue?.trim();
+    if (!value || !/^\d+$/.test(value))
+        return null;
+    const seconds = Number(value);
+    // Syntactically valid integers beyond Number's range still take the 600 s cap.
+    return Number.isFinite(seconds) ? seconds : Number.MAX_SAFE_INTEGER;
+}
 /**
  * Read tokens held for the errors `execute` rejected with, keyed by the error
  * so the token is never reachable from the error itself (a crash reporter or a
@@ -639,14 +647,13 @@ function readTokenFromPrefix(prefix, intentId) {
 /**
  * Parse a Retry-After header (our API sends integer seconds) into milliseconds,
  * clamped to [0, maxDelayMs] so a malformed or hostile value can't stall the
- * client. Returns null when absent/unparseable so the caller falls back to its
- * own exponential backoff.
+ * client. The default safety ceiling preserves server-directed waits up to
+ * MAX_RETRY_WAIT_SEC; a custom ceiling can narrow them. Returns null when
+ * absent/unparseable so the caller falls back to its own exponential backoff.
  */
-export function parseRetryAfterMs(headerValue, maxDelayMs = DEFAULT_RETRY.maxDelayMs) {
-    if (!headerValue)
-        return null;
-    const seconds = Number(headerValue);
-    if (!Number.isFinite(seconds) || seconds < 0)
+export function parseRetryAfterMs(headerValue, maxDelayMs = MAX_RETRY_WAIT_SEC * 1000) {
+    const seconds = retryAfterDeltaSeconds(headerValue);
+    if (seconds === null)
         return null;
     return Math.min(seconds * 1000, maxDelayMs);
 }
@@ -694,12 +701,9 @@ export function resolveRetryAfterSeconds(headers, body) {
     return Math.min(target, nowSec + MAX_RETRY_WAIT_SEC);
 }
 function deriveRetryTarget(headers, body, nowSec) {
-    const retryAfterHeader = headers.get("Retry-After");
-    if (retryAfterHeader !== null) {
-        const delta = Number(retryAfterHeader);
-        if (Number.isFinite(delta) && delta >= 0)
-            return nowSec + delta;
-    }
+    const delta = retryAfterDeltaSeconds(headers.get("Retry-After"));
+    if (delta !== null)
+        return nowSec + delta;
     const reset = headers.get("X-RateLimit-Reset");
     if (reset !== null) {
         const abs = Number(reset);
@@ -1006,7 +1010,7 @@ export function createXochiClient(options) {
                         // A 503 is a transient solver blip (saturation / gas-oracle
                         // unavailable); pace the retry off the server's Retry-After.
                         if (response.status === 503) {
-                            retryAfterMs = parseRetryAfterMs(response.headers.get("Retry-After"), retry.maxDelayMs);
+                            retryAfterMs = parseRetryAfterMs(response.headers.get("Retry-After"));
                         }
                         // A cut body does not parse, so it never carries the marker.
                         const record = truncated ? undefined : parseJsonObject(errorBody);
@@ -1062,7 +1066,7 @@ export function createXochiClient(options) {
                 if (lastError.name === "AbortError")
                     break;
                 if (attempt < maxAttempts - 1) {
-                    const delay = retryAfterMs ?? retry.baseDelayMs * Math.pow(2, attempt);
+                    const delay = retryAfterMs ?? Math.min(retry.baseDelayMs * Math.pow(2, attempt), retry.maxDelayMs);
                     // A retry means the request already failed once: that is the context
                     // for the error below if the retries run out.
                     log("warn", `[xochi-client] Retry ${attempt + 1}/${maxAttempts} in ${delay}ms`);
@@ -1163,12 +1167,12 @@ export function createXochiClient(options) {
                 return cached.quote;
             }
             const pending = pendingQuotes.get(requestHash);
-            if (pending && Date.now() - pending.timestamp < timeouts.requestTimeoutMs) {
+            if (pending) {
                 log("debug", "[xochi-client] Deduplicating quote request");
-                return pending.promise;
+                return pending;
             }
             const promise = fetchQuote(request);
-            pendingQuotes.set(requestHash, { promise, timestamp: Date.now() });
+            pendingQuotes.set(requestHash, promise);
             try {
                 const quote = await promise;
                 // Cache successful quotes -- EXCEPT pull-bearing ones. A quote carrying a
@@ -1181,7 +1185,8 @@ export function createXochiClient(options) {
                 return quote;
             }
             finally {
-                pendingQuotes.delete(requestHash);
+                if (pendingQuotes.get(requestHash) === promise)
+                    pendingQuotes.delete(requestHash);
             }
         },
         invalidateQuote(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xochi/client",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Xochi trade API client: transport, trade state machine, pre-sign fund-safety checks.",
   "keywords": [
     "xochi",