@xochi/client 0.0.0-stage → 0.1.2

package/dist/esm/claim.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pre-sign check for a stealth claim's UserOperation.
+ *
+ * `POST /api/stealth/claim/prepare` returns a sponsored ERC-4337 operation and
+ * the `userOpHash` the stealth key is asked to sign. The hash alone is valid over
+ * any preimage that hashes to it, so signing it unverified authorises whatever
+ * the server chose to build -- including a sweep to somebody else's address.
+ *
+ * `@xochi/signer`'s `assertPreparedClaimMatchesRequest` recomputes the hash
+ * from the served op under the pinned v0.8 EntryPoint, then checks `sender`,
+ * the settlement chain, `callData` (`execute(token, 0, transfer(recipient,
+ * amount))`), a zero native value and a paymaster. It runs here with
+ * `requireVerified` forced on: an absent op, EntryPoint or settlement chain is a
+ * refusal, never a warning, because the signature is the entire authorisation
+ * and nothing after it can catch a wrong one.
+ */
+import { type ClaimExpectation, type PreparedClaim } from "@xochi/signer";
+/** What the client independently knows the claim should do. */
+export type PreparedClaimExpectation = Omit<ClaimExpectation, "requireVerified">;
+/**
+ * `claim_op_unverified` is the category the widget already reports for a
+ * refused claim op, so a host branching on it keeps working.
+ */
+export type PreparedClaimCheck = {
+    ok: true;
+    token: string;
+    amount: string;
+} | {
+    ok: false;
+    errorCategory: "claim_op_unverified";
+    reason: string;
+};
+export declare function checkPreparedClaim(prepared: PreparedClaim, expected: PreparedClaimExpectation): PreparedClaimCheck;

package/dist/esm/claim.js

@@ -0,0 +1,41 @@
+/**
+ * Pre-sign check for a stealth claim's UserOperation.
+ *
+ * `POST /api/stealth/claim/prepare` returns a sponsored ERC-4337 operation and
+ * the `userOpHash` the stealth key is asked to sign. The hash alone is valid over
+ * any preimage that hashes to it, so signing it unverified authorises whatever
+ * the server chose to build -- including a sweep to somebody else's address.
+ *
+ * `@xochi/signer`'s `assertPreparedClaimMatchesRequest` recomputes the hash
+ * from the served op under the pinned v0.8 EntryPoint, then checks `sender`,
+ * the settlement chain, `callData` (`execute(token, 0, transfer(recipient,
+ * amount))`), a zero native value and a paymaster. It runs here with
+ * `requireVerified` forced on: an absent op, EntryPoint or settlement chain is a
+ * refusal, never a warning, because the signature is the entire authorisation
+ * and nothing after it can catch a wrong one.
+ */
+import { XochiClaimMismatchError, assertPreparedClaimMatchesRequest, } from "@xochi/signer";
+export function checkPreparedClaim(prepared, expected) {
+    try {
+        const verification = assertPreparedClaimMatchesRequest(prepared, {
+            ...expected,
+            requireVerified: true,
+        });
+        // With requireVerified every gap throws, so an unverified result here is a
+        // contract break in the signer: refuse it rather than sign on it.
+        if (!verification.verified || !verification.token || !verification.amount) {
+            return {
+                ok: false,
+                errorCategory: "claim_op_unverified",
+                reason: verification.reason ?? "the claim operation could not be verified",
+            };
+        }
+        return { ok: true, token: verification.token, amount: verification.amount };
+    }
+    catch (err) {
+        const reason = err instanceof XochiClaimMismatchError
+            ? err.message
+            : `claim verification failed unexpectedly: ${err instanceof Error ? err.message : String(err)}`;
+        return { ok: false, errorCategory: "claim_op_unverified", reason };
+    }
+}

package/dist/esm/fee.d.ts

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import type { FeeBreakdown } from "./shared/types.js";
+export type FeeTier = "standard" | "trusted" | "verified" | "premium" | "institutional";
+export type AssetClass = "stable" | "volatile";
+export type AttestationType = "compliance" | "non_membership";
+export declare const FEE_SCHEDULE: {
+    readonly surplus_share_pct: 15;
+    readonly tier_boundaries: readonly [{
+        readonly min_trust_score: 100;
+        readonly tier: "institutional";
+    }, {
+        readonly min_trust_score: 75;
+        readonly tier: "premium";
+    }, {
+        readonly min_trust_score: 50;
+        readonly tier: "verified";
+    }, {
+        readonly min_trust_score: 25;
+        readonly tier: "trusted";
+    }, {
+        readonly min_trust_score: 0;
+        readonly tier: "standard";
+    }];
+    readonly solver_base_bps: {
+        readonly stable: 8;
+        readonly volatile: 18;
+    };
+    readonly venue_bps: {
+        readonly standard: {
+            readonly stable: 6;
+            readonly volatile: 10;
+        };
+        readonly trusted: {
+            readonly stable: 5;
+            readonly volatile: 8;
+        };
+        readonly verified: {
+            readonly stable: 3;
+            readonly volatile: 5;
+        };
+        readonly premium: {
+            readonly stable: 2;
+            readonly volatile: 3;
+        };
+        readonly institutional: {
+            readonly stable: 1;
+            readonly volatile: 2;
+        };
+    };
+    readonly routing_bps: {
+        readonly standard: {
+            readonly stable: 8;
+            readonly volatile: 12;
+        };
+        readonly trusted: {
+            readonly stable: 6;
+            readonly volatile: 9;
+        };
+        readonly verified: {
+            readonly stable: 4;
+            readonly volatile: 6;
+        };
+        readonly premium: {
+            readonly stable: 2;
+            readonly volatile: 4;
+        };
+        readonly institutional: {
+            readonly stable: 1;
+            readonly volatile: 2;
+        };
+    };
+    readonly price_impact: {
+        readonly k: 50;
+        readonly cap_bps: 150;
+        readonly max_fill_fraction: 0.25;
+    };
+    readonly tier_attestation_requirements: {
+        readonly standard: AttestationType[];
+        readonly trusted: AttestationType[];
+        readonly verified: AttestationType[];
+        readonly premium: AttestationType[];
+        readonly institutional: AttestationType[];
+    };
+};
+export declare function scoreToTier(score: number): FeeTier;
+export declare function gateTier(rawTier: FeeTier, provided: AttestationType[]): FeeTier;
+export declare function priceImpactBps(fillUsd: number, liquidityUsd: number | null | undefined): number;
+export interface FeeComputeParams {
+    input_amount: string | bigint;
+    asset_class?: AssetClass;
+    trust_score?: number;
+    tier?: FeeTier;
+    attestations?: AttestationType[];
+    acp_origin?: boolean;
+    fill_usd?: number;
+    available_liquidity_usd?: number | null;
+}
+export interface FeeBreakdownCore {
+    tier: FeeTier;
+    asset_class: AssetClass;
+    solver_fee_bps: number;
+    solver_fee: string;
+    price_impact_bps: number;
+    price_impact: string;
+    venue_fee_bps: number;
+    venue_fee: string;
+    routing_fee_bps: number;
+    routing_fee: string;
+    total_bps: number;
+    total_fee: string;
+    surplus_share_pct: number;
+}
+export declare function computeFeeBreakdown(params: FeeComputeParams): FeeBreakdownCore;
+export declare const LayeredFeeBreakdownSchema: z.ZodObject<{
+    tier: z.ZodString;
+    asset_class: z.ZodEnum<["stable", "volatile"]>;
+    gas_floor: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        usd: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        usd: string;
+    }, {
+        amount: string;
+        usd: string;
+    }>>;
+    solver_fee_bps: z.ZodNumber;
+    solver_fee: z.ZodString;
+    price_impact_bps: z.ZodNumber;
+    price_impact: z.ZodString;
+    venue_fee_bps: z.ZodNumber;
+    venue_fee: z.ZodString;
+    routing_fee_bps: z.ZodNumber;
+    routing_fee: z.ZodString;
+    total_bps: z.ZodNumber;
+    total_fee: z.ZodString;
+    total_usd: z.ZodOptional<z.ZodString>;
+    surplus_share_pct: z.ZodNumber;
+    discount: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<["tier", "promo"]>;
+        bps: z.ZodNumber;
+        amount: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    tier: z.ZodString;
+    asset_class: z.ZodEnum<["stable", "volatile"]>;
+    gas_floor: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        usd: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        usd: string;
+    }, {
+        amount: string;
+        usd: string;
+    }>>;
+    solver_fee_bps: z.ZodNumber;
+    solver_fee: z.ZodString;
+    price_impact_bps: z.ZodNumber;
+    price_impact: z.ZodString;
+    venue_fee_bps: z.ZodNumber;
+    venue_fee: z.ZodString;
+    routing_fee_bps: z.ZodNumber;
+    routing_fee: z.ZodString;
+    total_bps: z.ZodNumber;
+    total_fee: z.ZodString;
+    total_usd: z.ZodOptional<z.ZodString>;
+    surplus_share_pct: z.ZodNumber;
+    discount: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<["tier", "promo"]>;
+        bps: z.ZodNumber;
+        amount: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    tier: z.ZodString;
+    asset_class: z.ZodEnum<["stable", "volatile"]>;
+    gas_floor: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        usd: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        usd: string;
+    }, {
+        amount: string;
+        usd: string;
+    }>>;
+    solver_fee_bps: z.ZodNumber;
+    solver_fee: z.ZodString;
+    price_impact_bps: z.ZodNumber;
+    price_impact: z.ZodString;
+    venue_fee_bps: z.ZodNumber;
+    venue_fee: z.ZodString;
+    routing_fee_bps: z.ZodNumber;
+    routing_fee: z.ZodString;
+    total_bps: z.ZodNumber;
+    total_fee: z.ZodString;
+    total_usd: z.ZodOptional<z.ZodString>;
+    surplus_share_pct: z.ZodNumber;
+    discount: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<["tier", "promo"]>;
+        bps: z.ZodNumber;
+        amount: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }, {
+        amount: string;
+        source: "tier" | "promo";
+        bps: number;
+    }>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type LayeredFeeBreakdownWire = z.infer<typeof LayeredFeeBreakdownSchema>;
+export declare function parseFeeBreakdown(raw: unknown): LayeredFeeBreakdownWire;
+export interface FeeInvariantOptions {
+    input_amount?: string | bigint;
+}
+export interface FeeReconcilable {
+    solver_fee_bps: number;
+    price_impact_bps: number;
+    venue_fee_bps: number;
+    routing_fee_bps: number;
+    total_bps: number;
+    solver_fee: string;
+    price_impact: string;
+    venue_fee: string;
+    routing_fee: string;
+    total_fee: string;
+}
+export declare function feeBreakdownReconcilable(fb: FeeBreakdown): FeeReconcilable;
+export declare function assertFeeBreakdownInvariants(fb: FeeReconcilable, opts?: FeeInvariantOptions): void;

package/dist/esm/fee.js

@@ -0,0 +1,285 @@
+// Layered fee model -- the network-free reference for the Xochi `fee_breakdown`
+// (SPEC.md Section 4). Byte/amount-parity with the server's authoritative
+// `Riddler.Integrations.Xochi.FeePolicy.calculate_layered_fee/1`; the fee
+// vectors in `@xochi/spec/fee/vectors.json` are generated from this module
+// (`packages/spec/fee/generate.ts`) and re-checked by
+// `packages/reference/test/fee.test.ts`, making Section 4 conformance-tested
+// the same way the signing layer is.
+//
+// Two roles:
+//   - `computeFeeBreakdown(params)` -- predict the deterministic core of a
+//     breakdown (bps + token-unit amounts) from the published schedule, so a
+//     taker can cross-check a server quote instead of trusting it blindly.
+//   - `assertFeeBreakdownInvariants(fb)` -- structurally verify a server-returned
+//     breakdown reconciles (layers sum to the total, bps sum to `total_bps`, no
+//     discount crosses the solver floor). This moves real funds; a misreported
+//     split MUST fail loud, not settle.
+//
+// The `gas_floor` / `*_usd` fields are price-oracle-derived and added by the
+// server's quote adapter -- they are outside this deterministic core and are
+// validated only for shape (see `LayeredFeeBreakdownSchema`), never recomputed
+// here.
+import { z } from "zod";
+// Canonical fee schedule. Single source of truth: mirrors the module attributes
+// of `Riddler.Integrations.Xochi.FeePolicy`. `@xochi/spec/fee/schedule.json`
+// is a generated projection of this object (see `packages/spec/fee/generate.ts`).
+// Headline total per tier = solver + venue + routing (no impact, non-ACP):
+// stable 22/19/15/12/10, volatile 40/35/29/25/22.
+export const FEE_SCHEDULE = {
+    // Percentage of positive fill slippage (surplus) captured; the rest returns
+    // to the taker. Reported, not part of the fee-bps sum.
+    surplus_share_pct: 15,
+    // Trust score -> tier, highest boundary first (a score matches the first
+    // boundary it meets or exceeds).
+    tier_boundaries: [
+        { min_trust_score: 100, tier: "institutional" },
+        { min_trust_score: 75, tier: "premium" },
+        { min_trust_score: 50, tier: "verified" },
+        { min_trust_score: 25, tier: "trusted" },
+        { min_trust_score: 0, tier: "standard" },
+    ],
+    // Solver spread -- the never-discounted cost floor, identical at every tier.
+    solver_base_bps: { stable: 8, volatile: 18 },
+    // Venue (Xochi) cut -- tier-discounted.
+    venue_bps: {
+        standard: { stable: 6, volatile: 10 },
+        trusted: { stable: 5, volatile: 8 },
+        verified: { stable: 3, volatile: 5 },
+        premium: { stable: 2, volatile: 3 },
+        institutional: { stable: 1, volatile: 2 },
+    },
+    // Routing (Raxol) cut -- tier-discounted; waived entirely when the intent
+    // originates from ACP (the routing cut is already paid via the ACP job budget).
+    routing_bps: {
+        standard: { stable: 8, volatile: 12 },
+        trusted: { stable: 6, volatile: 9 },
+        verified: { stable: 4, volatile: 6 },
+        premium: { stable: 2, volatile: 4 },
+        institutional: { stable: 1, volatile: 2 },
+    },
+    // Price impact is a solver cost, not a fee: impact_bps = clamp(round(k *
+    // fill/liq), 0, cap). Zero on unknown/zero depth.
+    price_impact: { k: 50, cap_bps: 150, max_fill_fraction: 0.25 },
+    // Attestation proofs a tier requires; without them the tier is gated down to
+    // the highest qualifying one.
+    tier_attestation_requirements: {
+        standard: [],
+        trusted: [],
+        verified: ["compliance"],
+        premium: ["compliance", "non_membership"],
+        institutional: ["compliance", "non_membership"],
+    },
+};
+const BPS_DENOMINATOR = 10000n;
+// Highest-privilege-first, for gating a tier down to the best one whose proof
+// requirements are satisfied. Mirrors FeePolicy's @tier_gate_order.
+const TIER_GATE_ORDER = ["institutional", "premium", "verified", "trusted", "standard"];
+// Maps a trust score to its fee tier. Non-integer or negative scores fall back
+// to `standard`, matching the server.
+export function scoreToTier(score) {
+    if (!Number.isInteger(score) || score < 0)
+        return "standard";
+    for (const { min_trust_score, tier } of FEE_SCHEDULE.tier_boundaries) {
+        if (score >= min_trust_score)
+            return tier;
+    }
+    return "standard";
+}
+function isSubset(required, provided) {
+    return required.every((r) => provided.has(r));
+}
+// Gates a raw tier down to the highest tier whose attestation requirements are
+// met by `provided`. A tier with no requirements is returned unchanged.
+export function gateTier(rawTier, provided) {
+    const providedSet = new Set(provided);
+    const required = FEE_SCHEDULE.tier_attestation_requirements[rawTier];
+    if (isSubset(required, providedSet))
+        return rawTier;
+    for (const tier of TIER_GATE_ORDER) {
+        if (isSubset(FEE_SCHEDULE.tier_attestation_requirements[tier], providedSet))
+            return tier;
+    }
+    return "standard";
+}
+// Price-impact in bps for `fillUsd` filled against `liquidityUsd` of solver
+// inventory. Returns 0 when depth is unknown or non-positive (depth-blind => no
+// impact term). impact_bps = clamp(round(k * fill/liq), 0, cap).
+export function priceImpactBps(fillUsd, liquidityUsd) {
+    if (typeof fillUsd !== "number" ||
+        typeof liquidityUsd !== "number" ||
+        !Number.isFinite(fillUsd) ||
+        !Number.isFinite(liquidityUsd) ||
+        liquidityUsd <= 0) {
+        return 0;
+    }
+    const { k, cap_bps } = FEE_SCHEDULE.price_impact;
+    return Math.round(Math.min(cap_bps, Math.max(0, (k * fillUsd) / liquidityUsd)));
+}
+// Per-layer fee amount in token base units: floor(base * bps / 10000). Each
+// layer floors independently, so the sum of layers can be a hair below
+// floor(base * total_bps / 10000) -- that per-layer floor is the normative rule.
+function layerAmount(base, bps) {
+    if (base <= 0n || bps <= 0)
+        return 0n;
+    return (base * BigInt(bps)) / BPS_DENOMINATOR;
+}
+function parseBaseAmount(input) {
+    if (typeof input === "bigint") {
+        if (input < 0n)
+            throw new Error(`fee: input_amount must be non-negative, got ${input}`);
+        return input;
+    }
+    if (!/^\d+$/.test(input)) {
+        throw new Error(`fee: input_amount must be a non-negative integer string, got ${JSON.stringify(input)}`);
+    }
+    return BigInt(input);
+}
+// Reference layered-fee computation, byte-parity with the server. Produces the
+// deterministic core a taker can compare against a returned quote.
+export function computeFeeBreakdown(params) {
+    const assetClass = params.asset_class ?? "stable";
+    const tier = params.tier ?? gateTier(scoreToTier(params.trust_score ?? 0), params.attestations ?? []);
+    const solverBps = FEE_SCHEDULE.solver_base_bps[assetClass];
+    const venueBps = FEE_SCHEDULE.venue_bps[tier][assetClass];
+    const routingBps = params.acp_origin ? 0 : FEE_SCHEDULE.routing_bps[tier][assetClass];
+    const impactBps = priceImpactBps(params.fill_usd ?? 0, params.available_liquidity_usd ?? null);
+    // Non-negative layers => the sum already dominates the solver floor; the clamp
+    // is a defensive invariant, not arithmetic that fires in practice.
+    const totalBps = Math.max(solverBps + venueBps + routingBps + impactBps, solverBps);
+    const base = parseBaseAmount(params.input_amount);
+    const solverFee = layerAmount(base, solverBps);
+    const impactFee = layerAmount(base, impactBps);
+    const venueFee = layerAmount(base, venueBps);
+    const routingFee = layerAmount(base, routingBps);
+    const totalFee = solverFee + impactFee + venueFee + routingFee;
+    return {
+        tier,
+        asset_class: assetClass,
+        solver_fee_bps: solverBps,
+        solver_fee: solverFee.toString(),
+        price_impact_bps: impactBps,
+        price_impact: impactFee.toString(),
+        venue_fee_bps: venueBps,
+        venue_fee: venueFee.toString(),
+        routing_fee_bps: routingBps,
+        routing_fee: routingFee.toString(),
+        total_bps: totalBps,
+        total_fee: totalFee.toString(),
+        surplus_share_pct: FEE_SCHEDULE.surplus_share_pct,
+    };
+}
+// -- Wire validation (HTTP boundary) --
+const bpsField = z.number().int().nonnegative();
+const amountField = z
+    .string()
+    .regex(/^\d+$/, "must be a non-negative integer string (token base units)");
+// The solver's `fee_breakdown` object as `/xochi/quote` serves it (SPEC.md
+// Section 4; `LayeredFeeBreakdown` in `@xochi/spec/wire/openapi.json`).
+// `gas_floor`/`total_usd` are price-oracle-derived and optional here so a
+// pre-adapter core still parses; `.passthrough()` tolerates additive fields a
+// newer server may send.
+//
+// Deliberately NOT the Worker's `FeeBreakdownSchema` (`shared/schemas.ts`),
+// though both carry the same fifteen layer fields and the same optional
+// `discount`. They are two contracts on two surfaces and neither accepts a
+// superset of the other: the Worker's `/api/*` re-emission REQUIRES
+// `gas_floor`/`total_usd`, closes `tier` to the five-tier enum and strips
+// unknown keys, while this one validates the solver's own object (and the
+// network-free core, which has no oracle envelope), pins every bps to a
+// non-negative integer and `gas_floor.amount` to base units, and passes
+// unknown keys through. Merging them would either make every pre-adapter core
+// unparseable or relax the Worker contract the frontend renders against.
+export const LayeredFeeBreakdownSchema = z
+    .object({
+    tier: z.string(),
+    asset_class: z.enum(["stable", "volatile"]),
+    gas_floor: z.object({ amount: amountField, usd: z.string() }).optional(),
+    solver_fee_bps: bpsField,
+    solver_fee: amountField,
+    price_impact_bps: bpsField,
+    price_impact: amountField,
+    venue_fee_bps: bpsField,
+    venue_fee: amountField,
+    routing_fee_bps: bpsField,
+    routing_fee: amountField,
+    total_bps: bpsField,
+    total_fee: amountField,
+    total_usd: z.string().optional(),
+    surplus_share_pct: bpsField,
+    // Served only when the request carried `promo_discount_bps > 0` (xochi#584):
+    // which discount priced the quote and how much it took off the Standard
+    // venue + routing layers. Informational -- `venue_fee`/`routing_fee` are
+    // already net of it, so the reconciliation in `assertFeeBreakdownInvariants`
+    // neither reads nor subtracts it. Shape-only, like `gas_floor`: the promo
+    // input is worker-side and no fee vector carries it.
+    discount: z
+        .object({ source: z.enum(["tier", "promo"]), bps: bpsField, amount: amountField })
+        .optional(),
+})
+    .passthrough();
+// Parses + shape-validates a solver `fee_breakdown`. Throws (zod) on a
+// malformed object -- callers at the HTTP boundary should not swallow this.
+export function parseFeeBreakdown(raw) {
+    return LayeredFeeBreakdownSchema.parse(raw);
+}
+// The reconciliation fields of a decoded quote's `feeBreakdown` (the camelCase
+// `FeeBreakdown` that `getQuote` and the machine hand back), so the client's own
+// quote can go through `assertFeeBreakdownInvariants` without the wire object.
+export function feeBreakdownReconcilable(fb) {
+    return {
+        solver_fee_bps: fb.solverFeeBps,
+        price_impact_bps: fb.priceImpactBps,
+        venue_fee_bps: fb.venueFeeBps,
+        routing_fee_bps: fb.routingFeeBps,
+        total_bps: fb.totalBps,
+        solver_fee: fb.solverFee,
+        price_impact: fb.priceImpact,
+        venue_fee: fb.venueFee,
+        routing_fee: fb.routingFee,
+        total_fee: fb.totalFee,
+    };
+}
+// Structurally verifies a wire `fee_breakdown` reconciles. Throws with context
+// on any violation; a server that misreports the split MUST fail loud here
+// before funds move. Checks, in order:
+//   1. bps layers sum to total_bps (with the solver-floor clamp),
+//   2. total_bps >= solver_fee_bps (no discount crosses the floor),
+//   3. amount layers sum to total_fee,
+//   4. (optional) each layer amount == floor(base * bps / 10000).
+export function assertFeeBreakdownInvariants(fb, opts = {}) {
+    const bpsSum = fb.solver_fee_bps + fb.price_impact_bps + fb.venue_fee_bps + fb.routing_fee_bps;
+    const expectedTotalBps = Math.max(bpsSum, fb.solver_fee_bps);
+    if (fb.total_bps !== expectedTotalBps) {
+        throw new Error(`fee_breakdown: total_bps ${fb.total_bps} != clamped layer sum ${expectedTotalBps} ` +
+            `(solver ${fb.solver_fee_bps} + impact ${fb.price_impact_bps} + venue ${fb.venue_fee_bps} + routing ${fb.routing_fee_bps})`);
+    }
+    if (fb.total_bps < fb.solver_fee_bps) {
+        throw new Error(`fee_breakdown: total_bps ${fb.total_bps} below solver floor ${fb.solver_fee_bps}`);
+    }
+    const layers = {
+        solver: BigInt(fb.solver_fee),
+        price_impact: BigInt(fb.price_impact),
+        venue: BigInt(fb.venue_fee),
+        routing: BigInt(fb.routing_fee),
+    };
+    const feeSum = layers.solver + layers.price_impact + layers.venue + layers.routing;
+    const totalFee = BigInt(fb.total_fee);
+    if (feeSum !== totalFee) {
+        throw new Error(`fee_breakdown: layer amounts sum to ${feeSum} but total_fee is ${totalFee}`);
+    }
+    if (opts.input_amount !== undefined) {
+        const base = parseBaseAmount(opts.input_amount);
+        const checks = [
+            ["solver_fee", layers.solver, fb.solver_fee_bps],
+            ["price_impact", layers.price_impact, fb.price_impact_bps],
+            ["venue_fee", layers.venue, fb.venue_fee_bps],
+            ["routing_fee", layers.routing, fb.routing_fee_bps],
+        ];
+        for (const [name, amount, bps] of checks) {
+            const expected = layerAmount(base, bps);
+            if (amount !== expected) {
+                throw new Error(`fee_breakdown: ${name} ${amount} != floor(${base} * ${bps} / 10000) = ${expected}`);
+            }
+        }
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @xochi/client: a client for the Xochi trade API (`https://api.xochi.fi/api/*`).
+ *
+ * - The wire contract and shared vocabulary (chains, statuses, schemas).
+ * - The trade lifecycle as a pure state machine: `update(model, msg)`.
+ * - A transport over the Worker API: `createXochiClient`.
+ * - Pre-sign fund-safety checks, from `@xochi/signer`, run by the machine at
+ *   quote ingest and exported for hosts that drive their own flow.
+ * - The layered fee reference (SPEC.md Section 4): the published schedule, the
+ *   deterministic breakdown it implies, and the reconciliation check a served
+ *   `fee_breakdown` must pass.
+ */
+export * from "./shared/index.js";
+export * from "./machine/index.js";
+export * from "./transport/client.js";
+export * from "./claim.js";
+export * from "./fee.js";
+export type { MethodPin, PinnedPullRecipients, PreparedClaim } from "@xochi/signer";

package/dist/esm/index.js

@@ -0,0 +1,17 @@
+/**
+ * @xochi/client: a client for the Xochi trade API (`https://api.xochi.fi/api/*`).
+ *
+ * - The wire contract and shared vocabulary (chains, statuses, schemas).
+ * - The trade lifecycle as a pure state machine: `update(model, msg)`.
+ * - A transport over the Worker API: `createXochiClient`.
+ * - Pre-sign fund-safety checks, from `@xochi/signer`, run by the machine at
+ *   quote ingest and exported for hosts that drive their own flow.
+ * - The layered fee reference (SPEC.md Section 4): the published schedule, the
+ *   deterministic breakdown it implies, and the reconciliation check a served
+ *   `fee_breakdown` must pass.
+ */
+export * from "./shared/index.js";
+export * from "./machine/index.js";
+export * from "./transport/client.js";
+export * from "./claim.js";
+export * from "./fee.js";

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

@@ -0,0 +1,29 @@
+/**
+ * The stealth claim-info gate, applied at quote ingest.
+ */
+/**
+ * Why a served `claim_info` cannot be acted on, or null when it is fine.
+ *
+ * A stealth payout lands in a counterfactual SimpleAccount, and the FACTORY in
+ * `claim_info` is what decides who owns that account. The client follows the
+ * advertised factory on purpose (#302, so it and the solver derive the same
+ * address), which means an attacker who can influence the served value picks
+ * where the money goes and both sides agree on it.
+ *
+ * This is the last check before that value is trusted: the factory must be one
+ * this build ships, and the salt must be the documented 0. Note the client
+ * cannot verify the stealth ADDRESS itself at quote time (the solver picks the
+ * ephemeral key, so the address is only derivable once announced), which is
+ * exactly why the factory has to carry the weight.
+ */
+export type ClaimInfoRejection = {
+    code: "untrusted_factory";
+    message: string;
+} | {
+    code: "unexpected_salt";
+    message: string;
+};
+export declare function claimInfoError(claimInfo: {
+    factoryAddress?: string;
+    salt?: number;
+} | undefined | null, chainId: number | undefined | null): ClaimInfoRejection | null;