@xochi/client 0.0.0-stage → 0.1.2

package/dist/cjs/shared/shieldedPreview.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldedPreviewResponseSchema = exports.ShieldedPreviewSchema = exports.ShieldedFeeBreakdownSchema = exports.ShieldedCorridorSchema = exports.ShieldedNetworkIdentitySchema = exports.aztecValue = void 0;
+exports.decodeShieldedPreview = decodeShieldedPreview;
+const zod_1 = require("zod");
+const schemas_js_1 = require("./schemas.js");
+/** 32-byte hex (`0x` + 64). */
+const bytes32 = zod_1.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.
+ */
+exports.aztecValue = bytes32;
+/** Canonical unsigned decimal string (uint256 members). */
+const uintString = zod_1.z.string().regex(/^(0|[1-9][0-9]*)$/);
+/** Canonical positive base-unit amount. */
+const baseUnits = zod_1.z.string().regex(/^[1-9][0-9]*$/);
+exports.ShieldedNetworkIdentitySchema = zod_1.z.object({
+    aztec_chain_id: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    protocol_version: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    rollup_address: schemas_js_1.ethAddress,
+    l1_chain_id: zod_1.z.string().regex(/^[1-9][0-9]*$/),
+    genesis_or_network_digest: bytes32,
+});
+exports.ShieldedCorridorSchema = zod_1.z.object({
+    corridor_id: bytes32,
+    revision: zod_1.z.number().int().min(1).max(4294967295),
+    manifest_digest: bytes32,
+});
+exports.ShieldedFeeBreakdownSchema = zod_1.z.object({
+    gas_floor: uintString,
+    solver_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    solver_fee: uintString,
+    price_impact_bps: zod_1.z.number().int().min(0).max(10000),
+    price_impact: uintString,
+    venue_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    venue_fee: uintString,
+    routing_fee_bps: zod_1.z.number().int().min(0).max(10000),
+    routing_fee: uintString,
+    total_bps: zod_1.z.number().int().min(0).max(40000),
+    total_fee: uintString,
+});
+/** `ShieldedPreviewV1` in snake_case: the terms minus the per-execution members. */
+exports.ShieldedPreviewSchema = zod_1.z.object({
+    protocol_version: zod_1.z.literal("xochi.shielded.preview.v1"),
+    environment: zod_1.z.string().min(1),
+    source: zod_1.z.object({
+        chain_id: zod_1.z.number().int().positive(),
+        token_address: schemas_js_1.ethAddress,
+        wallet: schemas_js_1.ethAddress,
+        collector: schemas_js_1.ethAddress,
+        amount: baseUnits,
+    }),
+    destination: zod_1.z.object({
+        settlement_type: zod_1.z.literal("shielded"),
+        privacy_level: zod_1.z.literal("private"),
+        disclosure_profile: zod_1.z.literal("recipient-private-public-amount-v1"),
+        rail: zod_1.z.literal("a_tracer"),
+        network: exports.ShieldedNetworkIdentitySchema,
+        corridor: exports.ShieldedCorridorSchema,
+        asset_id: zod_1.z.string().min(1),
+        token_address: exports.aztecValue,
+        recipient_binding_id: zod_1.z.string().min(1),
+        recipient_descriptor_digest: bytes32,
+        recipient_address: exports.aztecValue,
+        amount: baseUnits,
+        fee_payer: exports.aztecValue,
+    }),
+    fee_breakdown: exports.ShieldedFeeBreakdownSchema,
+    refund_address: schemas_js_1.ethAddress,
+    refund_amount: baseUnits,
+    collect_before: zod_1.z.number().int().nonnegative(),
+    settlement_service_deadline: zod_1.z.number().int().nonnegative(),
+    recipient_binding_digest: bytes32,
+    policy_revision: zod_1.z.number().int().nonnegative(),
+});
+exports.ShieldedPreviewResponseSchema = zod_1.z.object({
+    executable: zod_1.z.literal(false),
+    preview_version: zod_1.z.literal("xochi.shielded.preview.v1"),
+    preview_digest: bytes32,
+    recipient_binding_digest: bytes32,
+    domain: zod_1.z.object({
+        name: zod_1.z.literal("Xochi Shielded Preview"),
+        version: zod_1.z.literal("1"),
+        chain_id: zod_1.z.number().int().positive(),
+        salt: bytes32,
+    }),
+    preview: exports.ShieldedPreviewSchema,
+    manifest: zod_1.z.object({
+        manifest_digest: bytes32,
+        aztec_sdk_version: zod_1.z.string().min(1),
+        recipient_account_class_id: exports.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.
+ */
+function decodeShieldedPreview(body) {
+    const decoded = exports.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/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);
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Trading Constants
+ *
+ * Shared trading configuration for slippage, quotes, and limits.
+ */
+/** Default slippage in basis points (0.5%) */
+export declare const DEFAULT_SLIPPAGE_BPS = 50;
+/** Available slippage options in basis points */
+export declare const SLIPPAGE_OPTIONS: readonly [10, 50, 100, 200];
+export type SlippageOption = (typeof SLIPPAGE_OPTIONS)[number];
+/** Slippage presets with labels */
+export declare const SLIPPAGE_PRESETS: {
+    readonly low: 10;
+    readonly medium: 50;
+    readonly high: 100;
+};
+/** Quote expiry in seconds */
+export declare const QUOTE_EXPIRY_SEC = 30;
+/** Maximum retries for failed quotes */
+export declare const MAX_QUOTE_RETRIES = 3;
+/** Maximum decimal places for token amounts */
+export declare const MAX_TOKEN_DECIMALS = 18;
+/** Minimum trade amount in USD */
+export declare const MIN_TRADE_USD = 1;
+/** Maximum slippage percentage */
+export declare const MAX_SLIPPAGE_PERCENT = 50;
+/** Minimum slippage percentage */
+export declare const MIN_SLIPPAGE_PERCENT = 0.01;
+/**
+ * Hard ceiling on how far below market a fill may be before execution is
+ * refused. This is all-in value loss (fees + fixed network minimum + market
+ * slippage) versus the live market rate, not the user's configurable slippage
+ * tolerance. Protects users from executing trades -- typically dust orders --
+ * where costs eat more than half the notional.
+ */
+export declare const MAX_PRICE_IMPACT_PERCENT = 50;
+/**
+ * Minimum trust score for Aztec L2 shielded settlement (the Private privacy
+ * level). L1 stealth (ERC-5564) is NOT trust-gated: privacy is free by default,
+ * so any wallet can settle to a one-time stealth address and simply pays its own
+ * trust-tier fee. Only the deeper Aztec-shielded tiers -- Private (50+) and
+ * Sovereign (75+), both reached via pxe-bridge -- require trust.
+ */
+export declare const SHIELDED_MIN_SCORE = 50;
+/** Trust score thresholds by tier */
+export declare const TRUST_THRESHOLDS: {
+    readonly trusted: 25;
+    readonly verified: 50;
+    readonly premium: 75;
+    readonly institutional: 100;
+};
+/** Basis points denominator (1 bps = 0.01%) */
+export declare const BPS_DENOMINATOR = 10000;
+/** Maximum deadline offset in seconds (1 hour) */
+export declare const MAX_DEADLINE_OFFSET_SEC = 3600;
+/**
+ * Server-side ceiling on a quote request's `deadline`, in seconds from now.
+ *
+ * Deliberately looser than MAX_DEADLINE_OFFSET_SEC, which is the CLIENT's rule
+ * (src/utils/validators.ts) and the value the frontend actually sends. This is
+ * the outer bound the API will accept from anyone, sized so an agent or a device
+ * with a skewed clock is not rejected for asking a reasonable question.
+ *
+ * The reason there is a ceiling at all: `deadline` is what the user signs into
+ * the intent EIP-712, so an unbounded value is an authorization with no
+ * expiry -- and `decideReconcile` treats "past the signed deadline" as the point
+ * where an in-doubt intent can no longer move funds.
+ */
+export declare const MAX_QUOTE_DEADLINE_FUTURE_SEC: number;
+/**
+ * How far in the PAST a quote `deadline` may be and still be accepted, in
+ * seconds. Pure clock-skew tolerance: no correct client asks for a deadline that
+ * has already passed, but one whose clock is behind might.
+ *
+ * A past-dated deadline is not inert data: the abandoned-deposit sweep reads
+ * `deadline` to decide when a deposit route has died, so `deadline: 1` would
+ * mean "terminalise this live route on the next cron tick". The sweep gates on
+ * the server-set `created_at` too; this is the other half: the value never
+ * gets stored in the first place.
+ */
+export declare const MAX_QUOTE_DEADLINE_PAST_SEC = 3600;
+/**
+ * Sanity bound on the SOLVER-supplied `deposit_deadline`, in seconds from the
+ * quote, applied only when Xochi persists it.
+ *
+ * The client treats this field as untrusted: `POLL_CEILING_MAX_MS` exists
+ * because a malformed or hostile `deposit_deadline` far in the future must not
+ * turn the poll into a permanent background request loop. Persisting it makes
+ * the server trust it more than the browser does, and it is the PRIMARY gate
+ * on the abandoned-deposit sweep (`COALESCE(deposit_deadline, deadline)`), so
+ * one bad value -- a misparsed `XOCHI_DEPOSIT_DEADLINE_SECONDS`, a solver bug
+ * -- would make every deposit row permanently and silently unsweepable.
+ *
+ * Riddler's default is 1800s, so this is two orders of magnitude of headroom: it
+ * rejects nothing a correctly configured solver can mint. A value outside it is
+ * stored as NULL, which degrades the sweep to the quote `deadline` rather than
+ * to no gate at all. The value SERVED to the client is never altered -- it is
+ * covered by the deposit attestation signature, so changing it would break
+ * client-side verification.
+ */
+export declare const MAX_DEPOSIT_WINDOW_SEC: number;
+/** Maximum proof age in seconds (1 hour) -- proofs older than this are rejected server-side */
+export declare const MAX_PROOF_AGE_SEC = 3600;
+/** Grace period for rotated provider sets in seconds (24 hours) */
+export declare const PROVIDER_SET_GRACE_PERIOD_SEC = 86400;
+/** Ethereum address length including 0x prefix */
+export declare const ETH_ADDRESS_LENGTH = 42;
+/** Max slippage in basis points */
+export declare const MAX_SLIPPAGE_BPS: number;
+/** Multipliers for attestation scoring within a category */
+export declare const ATTESTATION_MULTIPLIERS: {
+    readonly first: 1;
+    readonly second: 0.25;
+    readonly subsequent: 0.1;
+};
+/** Default query limit for paginated API responses */
+export declare const DEFAULT_QUERY_LIMIT = 50;
+/** Maximum query limit for announcement scanning */
+export declare const MAX_ANNOUNCEMENT_LIMIT = 1000;
+/** Default announcement query limit */
+export declare const DEFAULT_ANNOUNCEMENT_LIMIT = 100;
+/** Rate limit window in milliseconds (15 minutes) */
+export declare const RATE_LIMIT_WINDOW_MS: number;
+/** Maximum rate-limited attempts per window */
+export declare const RATE_LIMIT_MAX_ATTEMPTS = 5;
+/** JWT token expiry in hours */
+export declare const JWT_EXPIRY_HOURS = 4;
+/** Tier proof expiry in milliseconds (7 days) */
+export declare const TIER_PROOF_EXPIRY_MS: number;
+/** Max rate limit store size before cleanup */
+export declare const RATE_LIMIT_STORE_MAX = 10000;
+/** Base delay for failed auth in milliseconds */
+export declare const AUTH_FAILURE_BASE_DELAY_MS = 500;
+/** Max delay for failed auth in milliseconds */
+export declare const AUTH_FAILURE_MAX_DELAY_MS = 5000;
+/** Max demo code length */
+export declare const MAX_DEMO_CODE_LENGTH = 100;
+/** Mock spread factor (1% spread = 99/100) */
+export declare const MOCK_SPREAD_NUMERATOR = 99n;
+export declare const MOCK_SPREAD_DENOMINATOR = 100n;
+/** All trading constants in one object */
+export declare const TRADING: {
+    readonly defaultSlippageBps: 50;
+    readonly slippageOptions: readonly [10, 50, 100, 200];
+    readonly quoteExpirySec: 30;
+    readonly maxQuoteRetries: 3;
+    readonly maxTokenDecimals: 18;
+    readonly minTradeUsd: 1;
+    readonly maxSlippagePercent: 50;
+    readonly minSlippagePercent: 0.01;
+    readonly maxPriceImpactPercent: 50;
+    readonly shieldedMinScore: 50;
+};

package/dist/cjs/shared/trading.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Trading Constants
+ *
+ * Shared trading configuration for slippage, quotes, and limits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRADING = exports.MOCK_SPREAD_DENOMINATOR = exports.MOCK_SPREAD_NUMERATOR = exports.MAX_DEMO_CODE_LENGTH = exports.AUTH_FAILURE_MAX_DELAY_MS = exports.AUTH_FAILURE_BASE_DELAY_MS = exports.RATE_LIMIT_STORE_MAX = exports.TIER_PROOF_EXPIRY_MS = exports.JWT_EXPIRY_HOURS = exports.RATE_LIMIT_MAX_ATTEMPTS = exports.RATE_LIMIT_WINDOW_MS = exports.DEFAULT_ANNOUNCEMENT_LIMIT = exports.MAX_ANNOUNCEMENT_LIMIT = exports.DEFAULT_QUERY_LIMIT = exports.ATTESTATION_MULTIPLIERS = exports.MAX_SLIPPAGE_BPS = exports.ETH_ADDRESS_LENGTH = exports.PROVIDER_SET_GRACE_PERIOD_SEC = exports.MAX_PROOF_AGE_SEC = exports.MAX_DEPOSIT_WINDOW_SEC = exports.MAX_QUOTE_DEADLINE_PAST_SEC = exports.MAX_QUOTE_DEADLINE_FUTURE_SEC = exports.MAX_DEADLINE_OFFSET_SEC = exports.BPS_DENOMINATOR = exports.TRUST_THRESHOLDS = exports.SHIELDED_MIN_SCORE = exports.MAX_PRICE_IMPACT_PERCENT = exports.MIN_SLIPPAGE_PERCENT = exports.MAX_SLIPPAGE_PERCENT = exports.MIN_TRADE_USD = exports.MAX_TOKEN_DECIMALS = exports.MAX_QUOTE_RETRIES = exports.QUOTE_EXPIRY_SEC = exports.SLIPPAGE_PRESETS = exports.SLIPPAGE_OPTIONS = exports.DEFAULT_SLIPPAGE_BPS = void 0;
+// ============================================================
+// Slippage Configuration
+// ============================================================
+/** Default slippage in basis points (0.5%) */
+exports.DEFAULT_SLIPPAGE_BPS = 50;
+/** Available slippage options in basis points */
+exports.SLIPPAGE_OPTIONS = [10, 50, 100, 200];
+/** Slippage presets with labels */
+exports.SLIPPAGE_PRESETS = {
+    low: 10, // 0.1%
+    medium: 50, // 0.5%
+    high: 100, // 1%
+};
+// ============================================================
+// Quote Configuration
+// ============================================================
+/** Quote expiry in seconds */
+exports.QUOTE_EXPIRY_SEC = 30;
+/** Maximum retries for failed quotes */
+exports.MAX_QUOTE_RETRIES = 3;
+// ============================================================
+// Trading Limits
+// ============================================================
+/** Maximum decimal places for token amounts */
+exports.MAX_TOKEN_DECIMALS = 18;
+/** Minimum trade amount in USD */
+exports.MIN_TRADE_USD = 1;
+/** Maximum slippage percentage */
+exports.MAX_SLIPPAGE_PERCENT = 50;
+/** Minimum slippage percentage */
+exports.MIN_SLIPPAGE_PERCENT = 0.01;
+/**
+ * Hard ceiling on how far below market a fill may be before execution is
+ * refused. This is all-in value loss (fees + fixed network minimum + market
+ * slippage) versus the live market rate, not the user's configurable slippage
+ * tolerance. Protects users from executing trades -- typically dust orders --
+ * where costs eat more than half the notional.
+ */
+exports.MAX_PRICE_IMPACT_PERCENT = 50;
+// ============================================================
+// Trust Thresholds
+// ============================================================
+/**
+ * Minimum trust score for Aztec L2 shielded settlement (the Private privacy
+ * level). L1 stealth (ERC-5564) is NOT trust-gated: privacy is free by default,
+ * so any wallet can settle to a one-time stealth address and simply pays its own
+ * trust-tier fee. Only the deeper Aztec-shielded tiers -- Private (50+) and
+ * Sovereign (75+), both reached via pxe-bridge -- require trust.
+ */
+exports.SHIELDED_MIN_SCORE = 50;
+/** Trust score thresholds by tier */
+exports.TRUST_THRESHOLDS = {
+    trusted: 25,
+    verified: 50,
+    premium: 75,
+    institutional: 100,
+};
+// ============================================================
+// Numeric Constants
+// ============================================================
+/** Basis points denominator (1 bps = 0.01%) */
+exports.BPS_DENOMINATOR = 10_000;
+/** Maximum deadline offset in seconds (1 hour) */
+exports.MAX_DEADLINE_OFFSET_SEC = 3600;
+/**
+ * Server-side ceiling on a quote request's `deadline`, in seconds from now.
+ *
+ * Deliberately looser than MAX_DEADLINE_OFFSET_SEC, which is the CLIENT's rule
+ * (src/utils/validators.ts) and the value the frontend actually sends. This is
+ * the outer bound the API will accept from anyone, sized so an agent or a device
+ * with a skewed clock is not rejected for asking a reasonable question.
+ *
+ * The reason there is a ceiling at all: `deadline` is what the user signs into
+ * the intent EIP-712, so an unbounded value is an authorization with no
+ * expiry -- and `decideReconcile` treats "past the signed deadline" as the point
+ * where an in-doubt intent can no longer move funds.
+ */
+exports.MAX_QUOTE_DEADLINE_FUTURE_SEC = 24 * 3600;
+/**
+ * How far in the PAST a quote `deadline` may be and still be accepted, in
+ * seconds. Pure clock-skew tolerance: no correct client asks for a deadline that
+ * has already passed, but one whose clock is behind might.
+ *
+ * A past-dated deadline is not inert data: the abandoned-deposit sweep reads
+ * `deadline` to decide when a deposit route has died, so `deadline: 1` would
+ * mean "terminalise this live route on the next cron tick". The sweep gates on
+ * the server-set `created_at` too; this is the other half: the value never
+ * gets stored in the first place.
+ */
+exports.MAX_QUOTE_DEADLINE_PAST_SEC = 3600;
+/**
+ * Sanity bound on the SOLVER-supplied `deposit_deadline`, in seconds from the
+ * quote, applied only when Xochi persists it.
+ *
+ * The client treats this field as untrusted: `POLL_CEILING_MAX_MS` exists
+ * because a malformed or hostile `deposit_deadline` far in the future must not
+ * turn the poll into a permanent background request loop. Persisting it makes
+ * the server trust it more than the browser does, and it is the PRIMARY gate
+ * on the abandoned-deposit sweep (`COALESCE(deposit_deadline, deadline)`), so
+ * one bad value -- a misparsed `XOCHI_DEPOSIT_DEADLINE_SECONDS`, a solver bug
+ * -- would make every deposit row permanently and silently unsweepable.
+ *
+ * Riddler's default is 1800s, so this is two orders of magnitude of headroom: it
+ * rejects nothing a correctly configured solver can mint. A value outside it is
+ * stored as NULL, which degrades the sweep to the quote `deadline` rather than
+ * to no gate at all. The value SERVED to the client is never altered -- it is
+ * covered by the deposit attestation signature, so changing it would break
+ * client-side verification.
+ */
+exports.MAX_DEPOSIT_WINDOW_SEC = 24 * 3600;
+/** Maximum proof age in seconds (1 hour) -- proofs older than this are rejected server-side */
+exports.MAX_PROOF_AGE_SEC = 3600;
+/** Grace period for rotated provider sets in seconds (24 hours) */
+exports.PROVIDER_SET_GRACE_PERIOD_SEC = 86400;
+/** Ethereum address length including 0x prefix */
+exports.ETH_ADDRESS_LENGTH = 42;
+/** Max slippage in basis points */
+exports.MAX_SLIPPAGE_BPS = exports.MAX_SLIPPAGE_PERCENT * 100;
+// ============================================================
+// Attestation Diminishing Returns
+// ============================================================
+/** Multipliers for attestation scoring within a category */
+exports.ATTESTATION_MULTIPLIERS = {
+    first: 1.0,
+    second: 0.25,
+    subsequent: 0.1,
+};
+// ============================================================
+// Query Limits
+// ============================================================
+/** Default query limit for paginated API responses */
+exports.DEFAULT_QUERY_LIMIT = 50;
+/** Maximum query limit for announcement scanning */
+exports.MAX_ANNOUNCEMENT_LIMIT = 1000;
+/** Default announcement query limit */
+exports.DEFAULT_ANNOUNCEMENT_LIMIT = 100;
+// ============================================================
+// Auth & Rate Limiting
+// ============================================================
+/** Rate limit window in milliseconds (15 minutes) */
+exports.RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+/** Maximum rate-limited attempts per window */
+exports.RATE_LIMIT_MAX_ATTEMPTS = 5;
+/** JWT token expiry in hours */
+exports.JWT_EXPIRY_HOURS = 4;
+/** Tier proof expiry in milliseconds (7 days) */
+exports.TIER_PROOF_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+/** Max rate limit store size before cleanup */
+exports.RATE_LIMIT_STORE_MAX = 10_000;
+/** Base delay for failed auth in milliseconds */
+exports.AUTH_FAILURE_BASE_DELAY_MS = 500;
+/** Max delay for failed auth in milliseconds */
+exports.AUTH_FAILURE_MAX_DELAY_MS = 5000;
+/** Max demo code length */
+exports.MAX_DEMO_CODE_LENGTH = 100;
+// ============================================================
+// Mock Spread
+// ============================================================
+/** Mock spread factor (1% spread = 99/100) */
+exports.MOCK_SPREAD_NUMERATOR = 99n;
+exports.MOCK_SPREAD_DENOMINATOR = 100n;
+// ============================================================
+// Bundled Trading Config
+// ============================================================
+/** All trading constants in one object */
+exports.TRADING = {
+    defaultSlippageBps: exports.DEFAULT_SLIPPAGE_BPS,
+    slippageOptions: exports.SLIPPAGE_OPTIONS,
+    quoteExpirySec: exports.QUOTE_EXPIRY_SEC,
+    maxQuoteRetries: exports.MAX_QUOTE_RETRIES,
+    maxTokenDecimals: exports.MAX_TOKEN_DECIMALS,
+    minTradeUsd: exports.MIN_TRADE_USD,
+    maxSlippagePercent: exports.MAX_SLIPPAGE_PERCENT,
+    minSlippagePercent: exports.MIN_SLIPPAGE_PERCENT,
+    maxPriceImpactPercent: exports.MAX_PRICE_IMPACT_PERCENT,
+    shieldedMinScore: exports.SHIELDED_MIN_SCORE,
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Shared Types
+ *
+ * Type definitions used across frontend and backend.
+ */
+/** Lowercase tier id used on the wire + in the fee breakdown. */
+export type Tier = "standard" | "trusted" | "verified" | "premium" | "institutional";
+/**
+ * Itemized fee breakdown for a quote (economics.md Part 1, "Frontend display spec").
+ * Three additive layers on a never-discounted cost floor: solver spread + gas
+ * floor (Riddler), venue fee (Xochi), routing fee (Raxol -> buyback). Amounts are
+ * destination-token smallest units (strings); rates are bps. Discounts carve
+ * venue + routing only, never the solver floor.
+ */
+export interface FeeBreakdown {
+    tier: Tier;
+    assetClass: "stable" | "volatile";
+    /** Guaranteed minimum, never discounted (Riddler). */
+    gasFloor: {
+        amount: string;
+        usd: string;
+    };
+    solverFeeBps: number;
+    solverFee: string;
+    /** > 0 only on large-vs-depth fills; render as a warning, not a fee. */
+    priceImpactBps: number;
+    priceImpact: string;
+    venueFeeBps: number;
+    venueFee: string;
+    routingFeeBps: number;
+    routingFee: string;
+    totalBps: number;
+    totalFee: string;
+    totalUsd: string;
+    /** 15 -- solver upside on positive slippage; the user keeps the other 85%. */
+    surplusSharePct: number;
+}

package/dist/cjs/shared/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Shared Types
+ *
+ * Type definitions used across frontend and backend.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,30 @@
+/**
+ * Validators
+ *
+ * Address validators: EVM hex20 and checksummed Tron base58.
+ */
+/** Ethereum address regex pattern */
+export declare const ETH_ADDRESS_REGEX: RegExp;
+/** Zero address constant */
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** Check if string is a valid Ethereum address */
+export declare function isValidAddress(address: string): boolean;
+/**
+ * Tron mainnet address shape: 34 chars, leading "T", base58 alphabet (no
+ * 0/O/I/l). Shape alone is NOT sufficient to accept an address -- see
+ * `isValidTronAddress`, which also verifies the base58check checksum.
+ */
+export declare const TRON_ADDRESS_REGEX: RegExp;
+/**
+ * Validate a Tron address, checksum included.
+ *
+ * The shape regex alone accepts any typo that keeps the length and alphabet,
+ * which is nearly all of them. Base58check carries a 4-byte checksum, so a
+ * mistyped address survives it with probability about 1 in 4 billion. That
+ * matters here specifically because a Tron payout recipient is typed by hand on
+ * an EVM-origin swap: there is no Tron wallet in the flow to catch it later, and
+ * a TRC-20 transfer to a well-formed but unowned address is irrecoverable.
+ *
+ * Checksum = first 4 bytes of sha256(sha256(0x41 || address_bytes)).
+ */
+export declare function isValidTronAddress(address: string): boolean;