@xochi/client 0.0.0-stage → 0.1.1

package/dist/esm/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/esm/shared/trading.js

@@ -0,0 +1,182 @@
+/**
+ * Trading Constants
+ *
+ * Shared trading configuration for slippage, quotes, and limits.
+ */
+// ============================================================
+// Slippage Configuration
+// ============================================================
+/** Default slippage in basis points (0.5%) */
+export const DEFAULT_SLIPPAGE_BPS = 50;
+/** Available slippage options in basis points */
+export const SLIPPAGE_OPTIONS = [10, 50, 100, 200];
+/** Slippage presets with labels */
+export const SLIPPAGE_PRESETS = {
+    low: 10, // 0.1%
+    medium: 50, // 0.5%
+    high: 100, // 1%
+};
+// ============================================================
+// Quote Configuration
+// ============================================================
+/** Quote expiry in seconds */
+export const QUOTE_EXPIRY_SEC = 30;
+/** Maximum retries for failed quotes */
+export const MAX_QUOTE_RETRIES = 3;
+// ============================================================
+// Trading Limits
+// ============================================================
+/** Maximum decimal places for token amounts */
+export const MAX_TOKEN_DECIMALS = 18;
+/** Minimum trade amount in USD */
+export const MIN_TRADE_USD = 1;
+/** Maximum slippage percentage */
+export const MAX_SLIPPAGE_PERCENT = 50;
+/** Minimum slippage percentage */
+export 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 const 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.
+ */
+export const SHIELDED_MIN_SCORE = 50;
+/** Trust score thresholds by tier */
+export const TRUST_THRESHOLDS = {
+    trusted: 25,
+    verified: 50,
+    premium: 75,
+    institutional: 100,
+};
+// ============================================================
+// Numeric Constants
+// ============================================================
+/** Basis points denominator (1 bps = 0.01%) */
+export const BPS_DENOMINATOR = 10_000;
+/** Maximum deadline offset in seconds (1 hour) */
+export 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 const 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.
+ */
+export 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 const MAX_DEPOSIT_WINDOW_SEC = 24 * 3600;
+/** Maximum proof age in seconds (1 hour) -- proofs older than this are rejected server-side */
+export const MAX_PROOF_AGE_SEC = 3600;
+/** Grace period for rotated provider sets in seconds (24 hours) */
+export const PROVIDER_SET_GRACE_PERIOD_SEC = 86400;
+/** Ethereum address length including 0x prefix */
+export const ETH_ADDRESS_LENGTH = 42;
+/** Max slippage in basis points */
+export const MAX_SLIPPAGE_BPS = MAX_SLIPPAGE_PERCENT * 100;
+// ============================================================
+// Attestation Diminishing Returns
+// ============================================================
+/** Multipliers for attestation scoring within a category */
+export const ATTESTATION_MULTIPLIERS = {
+    first: 1.0,
+    second: 0.25,
+    subsequent: 0.1,
+};
+// ============================================================
+// Query Limits
+// ============================================================
+/** Default query limit for paginated API responses */
+export const DEFAULT_QUERY_LIMIT = 50;
+/** Maximum query limit for announcement scanning */
+export const MAX_ANNOUNCEMENT_LIMIT = 1000;
+/** Default announcement query limit */
+export const DEFAULT_ANNOUNCEMENT_LIMIT = 100;
+// ============================================================
+// Auth & Rate Limiting
+// ============================================================
+/** Rate limit window in milliseconds (15 minutes) */
+export const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+/** Maximum rate-limited attempts per window */
+export const RATE_LIMIT_MAX_ATTEMPTS = 5;
+/** JWT token expiry in hours */
+export const JWT_EXPIRY_HOURS = 4;
+/** Tier proof expiry in milliseconds (7 days) */
+export const TIER_PROOF_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+/** Max rate limit store size before cleanup */
+export const RATE_LIMIT_STORE_MAX = 10_000;
+/** Base delay for failed auth in milliseconds */
+export const AUTH_FAILURE_BASE_DELAY_MS = 500;
+/** Max delay for failed auth in milliseconds */
+export const AUTH_FAILURE_MAX_DELAY_MS = 5000;
+/** Max demo code length */
+export const MAX_DEMO_CODE_LENGTH = 100;
+// ============================================================
+// Mock Spread
+// ============================================================
+/** Mock spread factor (1% spread = 99/100) */
+export const MOCK_SPREAD_NUMERATOR = 99n;
+export const MOCK_SPREAD_DENOMINATOR = 100n;
+// ============================================================
+// Bundled Trading Config
+// ============================================================
+/** All trading constants in one object */
+export const TRADING = {
+    defaultSlippageBps: DEFAULT_SLIPPAGE_BPS,
+    slippageOptions: SLIPPAGE_OPTIONS,
+    quoteExpirySec: QUOTE_EXPIRY_SEC,
+    maxQuoteRetries: MAX_QUOTE_RETRIES,
+    maxTokenDecimals: MAX_TOKEN_DECIMALS,
+    minTradeUsd: MIN_TRADE_USD,
+    maxSlippagePercent: MAX_SLIPPAGE_PERCENT,
+    minSlippagePercent: MIN_SLIPPAGE_PERCENT,
+    maxPriceImpactPercent: MAX_PRICE_IMPACT_PERCENT,
+    shieldedMinScore: SHIELDED_MIN_SCORE,
+};

package/dist/esm/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/esm/shared/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared Types
+ *
+ * Type definitions used across frontend and backend.
+ */
+export {};

package/dist/esm/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;

package/dist/esm/shared/validators.js

@@ -0,0 +1,74 @@
+/**
+ * Validators
+ *
+ * Address validators: EVM hex20 and checksummed Tron base58.
+ */
+import { sha256 } from "viem";
+// ============================================================
+// Address Validation
+// ============================================================
+/** Ethereum address regex pattern */
+export const ETH_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+/** Zero address constant */
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** Check if string is a valid Ethereum address */
+export function isValidAddress(address) {
+    return ETH_ADDRESS_REGEX.test(address);
+}
+/**
+ * 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 const TRON_ADDRESS_REGEX = /^T[1-9A-HJ-NP-Za-km-z]{33}$/;
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/** Decoded Tron address: 0x41 prefix + 20 address bytes + 4 checksum bytes. */
+const TRON_DECODED_BYTES = 25;
+const TRON_ADDRESS_PREFIX = 0x41;
+/** Decode base58 into bytes. Returns null on any character outside the alphabet. */
+function base58Decode(input) {
+    let acc = 0n;
+    for (const char of input) {
+        const digit = BASE58_ALPHABET.indexOf(char);
+        if (digit < 0)
+            return null;
+        acc = acc * 58n + BigInt(digit);
+    }
+    const bytes = [];
+    while (acc > 0n) {
+        bytes.unshift(Number(acc % 256n));
+        acc /= 256n;
+    }
+    // Every leading '1' in base58 encodes one leading zero byte.
+    for (const char of input) {
+        if (char !== BASE58_ALPHABET[0])
+            break;
+        bytes.unshift(0);
+    }
+    return Uint8Array.from(bytes);
+}
+/**
+ * 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 function isValidTronAddress(address) {
+    if (!TRON_ADDRESS_REGEX.test(address))
+        return false;
+    const decoded = base58Decode(address);
+    if (!decoded || decoded.length !== TRON_DECODED_BYTES)
+        return false;
+    if (decoded[0] !== TRON_ADDRESS_PREFIX)
+        return false;
+    const payload = decoded.subarray(0, 21);
+    const checksum = decoded.subarray(21);
+    const digest = sha256(sha256(payload, "bytes"), "bytes");
+    return checksum.every((byte, i) => byte === digest[i]);
+}