perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/rate-limiter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-process token-bucket rate limiter keyed by venue (design §3 L4, §10.9).
+ *
+ * Limitation (documented): this only coordinates requests inside one process.
+ * CLI + MCP server + bots running at once can still exceed a venue's limit.
+ */
+import { PerpError } from "../errors.js";
+import type { RateLimitPolicy } from "./venue.js";
+/** Acquire capacity for one request. `endpoint` is looked up in policy.weights (unlisted = 1). */
+export declare function acquireRate(key: string, policy: RateLimitPolicy, endpoint: string): Promise<void>;
+/** Map an HTTP 429 into a structured RATE_LIMITED error. */
+export declare function rateLimitedError(venue: string, retryAfterHeader: string | null, body: string): PerpError;

package/dist/exchanges/rate-limiter.js

@@ -0,0 +1,64 @@
+/**
+ * Per-process token-bucket rate limiter keyed by venue (design §3 L4, §10.9).
+ *
+ * Limitation (documented): this only coordinates requests inside one process.
+ * CLI + MCP server + bots running at once can still exceed a venue's limit.
+ */
+import { PerpError } from "../errors.js";
+class TokenBucket {
+    policy;
+    tokens;
+    last = Date.now();
+    queue = Promise.resolve();
+    constructor(policy) {
+        this.policy = policy;
+        if (!(policy.capacity > 0) || !(policy.refillPerSec > 0)) {
+            throw new Error(`invalid rate limit policy: ${JSON.stringify(policy)}`);
+        }
+        this.tokens = policy.capacity;
+    }
+    refill() {
+        const now = Date.now();
+        this.tokens = Math.min(this.policy.capacity, this.tokens + ((now - this.last) / 1000) * this.policy.refillPerSec);
+        this.last = now;
+    }
+    acquire(weight) {
+        if (weight > this.policy.capacity) {
+            throw new PerpError("RATE_LIMITED", `request weight ${weight} exceeds bucket capacity ${this.policy.capacity}`);
+        }
+        const run = async () => {
+            for (;;) {
+                this.refill();
+                if (this.tokens >= weight) {
+                    this.tokens -= weight;
+                    return;
+                }
+                const waitMs = Math.ceil(((weight - this.tokens) / this.policy.refillPerSec) * 1000);
+                await new Promise(r => setTimeout(r, waitMs));
+            }
+        };
+        const p = this.queue.then(run);
+        this.queue = p.catch(() => undefined);
+        return p;
+    }
+}
+const buckets = new Map();
+/** Acquire capacity for one request. `endpoint` is looked up in policy.weights (unlisted = 1). */
+export async function acquireRate(key, policy, endpoint) {
+    let b = buckets.get(key);
+    if (!b) {
+        b = new TokenBucket(policy);
+        buckets.set(key, b);
+    }
+    const weight = policy.weights?.[endpoint] ?? 1; // unlisted endpoints cost 1 by the policy's definition
+    await b.acquire(weight);
+}
+/** Map an HTTP 429 into a structured RATE_LIMITED error. */
+export function rateLimitedError(venue, retryAfterHeader, body) {
+    const retryAfterSec = retryAfterHeader !== null ? Number(retryAfterHeader) : NaN;
+    return new PerpError("RATE_LIMITED", `${venue}: rate limited (HTTP 429)`, {
+        ...(Number.isFinite(retryAfterSec) ? { retryAfterMs: retryAfterSec * 1000 } : {}),
+        body: body.slice(0, 500),
+        remediation: `Reduce request frequency for ${venue} or request a higher API limit from the venue`,
+    });
+}

package/dist/exchanges/registry.d.ts

@@ -1,13 +1,25 @@
 /**
- * Adapter registry for plugin-style exchange discovery.
- * New exchanges register here — commands use registry to resolve names/aliases.
+ * Adapter registry — legacy name/alias API, now derived from the venue
+ * definitions (src/exchanges/venues/, design §10.10). New venues are added by
+ * registering a VenueDefinition, not here.
  */
+import "./venues/index.js";
 export interface AdapterRegistration {
     name: string;
     aliases: string[];
+    /**
+     * Legacy field = the adapter's `chain` value (pacifica "solana", hyperliquid "evm",
+     * lighter "ethereum", aster "bnb"). For key-kind decisions use the venue's
+     * masterKeyKind; for where funds live use networks.<net>.settlementChain.
+     */
     chain: string;
 }
+/**
+ * @deprecated Registration happens through VenueDefinition (registerVenue in ./venue.ts).
+ * Kept for API compatibility; throws so a stray call cannot create an adapter-less entry.
+ */
 export declare function registerAdapter(reg: AdapterRegistration): void;
 export declare function getAdapterRegistration(nameOrAlias: string): AdapterRegistration | undefined;
 export declare function listExchanges(): string[];
+/** Resolve an alias to its canonical venue id. Throws UNKNOWN_VENUE for unknown names. */
 export declare function resolveExchangeName(nameOrAlias: string): string;

package/dist/exchanges/registry.js

@@ -1,42 +1,30 @@
 /**
- * Adapter registry for plugin-style exchange discovery.
- * New exchanges register here — commands use registry to resolve names/aliases.
+ * Adapter registry — legacy name/alias API, now derived from the venue
+ * definitions (src/exchanges/venues/, design §10.10). New venues are added by
+ * registering a VenueDefinition, not here.
+ */
+import { getVenue, listVenues, tryResolveVenueId } from "./venue.js";
+import "./venues/index.js";
+function toRegistration(def) {
+    // HyperliquidAdapter.chain is "evm"; every other adapter's chain is its mainnet settlement chain.
+    const chain = def.family === "hyperliquid" ? "evm" : def.networks.mainnet.settlementChain;
+    return { name: def.id, aliases: [...def.aliases], chain };
+}
+/**
+ * @deprecated Registration happens through VenueDefinition (registerVenue in ./venue.ts).
+ * Kept for API compatibility; throws so a stray call cannot create an adapter-less entry.
  */
-const registry = new Map();
 export function registerAdapter(reg) {
-    registry.set(reg.name, reg);
-    for (const alias of reg.aliases) {
-        registry.set(alias, reg);
-    }
+    throw new Error(`registerAdapter("${reg.name}") is no longer supported — add a VenueDefinition under src/exchanges/venues/`);
 }
 export function getAdapterRegistration(nameOrAlias) {
-    return registry.get(nameOrAlias.toLowerCase());
+    const id = tryResolveVenueId(nameOrAlias);
+    return id === null ? undefined : toRegistration(getVenue(id));
 }
 export function listExchanges() {
-    return [...new Set([...registry.values()].map(r => r.name))];
+    return listVenues().map(v => v.id);
 }
+/** Resolve an alias to its canonical venue id. Throws UNKNOWN_VENUE for unknown names. */
 export function resolveExchangeName(nameOrAlias) {
-    const reg = registry.get(nameOrAlias.toLowerCase());
-    return reg?.name ?? nameOrAlias.toLowerCase();
+    return getVenue(nameOrAlias).id;
 }
-// ── Built-in adapter registrations ──
-registerAdapter({
-    name: "pacifica",
-    aliases: ["pac"],
-    chain: "solana",
-});
-registerAdapter({
-    name: "hyperliquid",
-    aliases: ["hl"],
-    chain: "evm",
-});
-registerAdapter({
-    name: "lighter",
-    aliases: ["lt"],
-    chain: "ethereum",
-});
-registerAdapter({
-    name: "aster",
-    aliases: ["ast"],
-    chain: "bnb",
-});

package/dist/exchanges/slippage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Single slippage resolver for every market-type order (design §13.2, §13.10 #1).
+ *
+ * Precedence (all explicit configuration, no hidden constants):
+ *   --slippage-bps flag → settings.slippageBps[venue] → settings.defaultSlippageBps.
+ * Adapters never read settings; they receive the resolved value as an argument.
+ */
+import type { VenueId } from "./venue-types.js";
+import "./venues/index.js";
+export type SlippageSource = "flag" | "venue" | "default";
+export interface ResolvedSlippage {
+    bps: number;
+    source: SlippageSource;
+}
+/** Largest slippage bound (bps) the venue accepts (VenueDefinition.maxSlippageBps). */
+export declare function venueMaxSlippageBps(venue: VenueId): number;
+/** defaultSlippageBps applies to every trading venue, so it must fit the tightest venue maximum. */
+export declare function maxDefaultSlippageBps(): number;
+/**
+ * Parse a bps value for a settings key (`defaultSlippageBps` / `slippageBps.<venue>`):
+ * a number ≥ 1 and ≤ `max`. Out of range → INVALID_PARAMS; never clamps.
+ * Shared by `perp settings set` and `perp setup` so both accept exactly what resolveSlippage() accepts.
+ */
+export declare function parseSlippageSettingBps(key: string, value: string, max: number): number;
+/**
+ * Resolve the slippage bound for a market-type order on `venue`.
+ * `flagBps` = caller's explicit per-call value (CLI --slippage-bps), null when absent.
+ * Out of range (bps < 1 or > venue max) → INVALID_PARAMS before anything is sent; never clamps.
+ */
+export declare function resolveSlippage(venue: VenueId, flagBps: number | null): ResolvedSlippage;
+/**
+ * resolveSlippage() for an adapter (its `name` is a venue id). Bot/arb paths pass
+ * flagBps = null, so the bound comes from settings (slippageBps[venue] → defaultSlippageBps).
+ */
+export declare function resolveAdapterSlippage(adapter: {
+    readonly name: string;
+}, flagBps: number | null): ResolvedSlippage;

package/dist/exchanges/slippage.js

@@ -0,0 +1,70 @@
+/**
+ * Single slippage resolver for every market-type order (design §13.2, §13.10 #1).
+ *
+ * Precedence (all explicit configuration, no hidden constants):
+ *   --slippage-bps flag → settings.slippageBps[venue] → settings.defaultSlippageBps.
+ * Adapters never read settings; they receive the resolved value as an argument.
+ */
+import { PerpError } from "../errors.js";
+import { loadSettings, isValidSlippageBps } from "../settings.js";
+import { getVenue, listVenuesWithRole, resolveVenueId } from "./venue.js";
+import "./venues/index.js";
+/** Largest slippage bound (bps) the venue accepts (VenueDefinition.maxSlippageBps). */
+export function venueMaxSlippageBps(venue) {
+    return getVenue(venue).maxSlippageBps;
+}
+/** defaultSlippageBps applies to every trading venue, so it must fit the tightest venue maximum. */
+export function maxDefaultSlippageBps() {
+    return Math.min(...listVenuesWithRole("trading").map(v => v.maxSlippageBps));
+}
+/**
+ * Parse a bps value for a settings key (`defaultSlippageBps` / `slippageBps.<venue>`):
+ * a number ≥ 1 and ≤ `max`. Out of range → INVALID_PARAMS; never clamps.
+ * Shared by `perp settings set` and `perp setup` so both accept exactly what resolveSlippage() accepts.
+ */
+export function parseSlippageSettingBps(key, value, max) {
+    const bps = Number(value);
+    if (!isValidSlippageBps(bps) || bps > max) {
+        throw new PerpError("INVALID_PARAMS", `${key} must be a number of basis points in 1..${max} (got "${value}")`);
+    }
+    return bps;
+}
+/**
+ * Resolve the slippage bound for a market-type order on `venue`.
+ * `flagBps` = caller's explicit per-call value (CLI --slippage-bps), null when absent.
+ * Out of range (bps < 1 or > venue max) → INVALID_PARAMS before anything is sent; never clamps.
+ */
+export function resolveSlippage(venue, flagBps) {
+    let resolved;
+    if (flagBps !== null) {
+        resolved = { bps: flagBps, source: "flag" };
+    }
+    else {
+        const s = loadSettings();
+        const perVenue = s.slippageBps[venue];
+        resolved = perVenue !== undefined
+            ? { bps: perVenue, source: "venue" }
+            : { bps: s.defaultSlippageBps, source: "default" };
+    }
+    const max = venueMaxSlippageBps(venue);
+    if (!Number.isFinite(resolved.bps) || resolved.bps < 1 || resolved.bps > max) {
+        const where = resolved.source === "flag" ? "--slippage-bps"
+            : resolved.source === "venue" ? `settings slippageBps.${venue}` : "settings defaultSlippageBps";
+        throw new PerpError("INVALID_PARAMS", `Slippage bound ${resolved.bps} bps (from ${where}) is outside 1..${max} bps for ${venue}`, {
+            exchange: venue,
+            remediation: resolved.source === "flag"
+                ? `Pass --slippage-bps between 1 and ${max}`
+                : resolved.source === "venue"
+                    ? `Run: perp settings set slippageBps.${venue} <1..${max}> (or perp settings unset slippageBps.${venue})`
+                    : `Run: perp settings set defaultSlippageBps <1..${max}> (or perp settings set slippageBps.${venue} <n>)`,
+        });
+    }
+    return resolved;
+}
+/**
+ * resolveSlippage() for an adapter (its `name` is a venue id). Bot/arb paths pass
+ * flagBps = null, so the bound comes from settings (slippageBps[venue] → defaultSlippageBps).
+ */
+export function resolveAdapterSlippage(adapter, flagBps) {
+    return resolveSlippage(resolveVenueId(adapter.name), flagBps);
+}

package/dist/exchanges/spot-factory.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Spot adapter factory — the only place spot adapters are created (design §12.4 #1).
+ *
+ * - `getSpotAdapter` returns null iff the venue has no spot (`def.spot === null`).
+ *   Creation / init / network errors propagate (SSOT Rule #2 — no catch).
+ * - `createSpot` (venue definition) constructs and init()s the adapter.
+ * - Cached per perp adapter instance (each instance is bound to one venue + network,
+ *   so the key is the adapter's own network, not the process-wide one) and per
+ *   on-chain-approve option. Read-only and signed perp adapters keep separate entries.
+ *
+ * Bot scope (§12.4 #3): bots only trade spot on venues where `isBotSpotVenue(def)`.
+ * Quote/base detection (§12.4 #6) goes through `def.spot.quoteAssets`.
+ */
+import type { AssetClass, Network, VenueMarket } from "./venue-types.js";
+import type { ExchangeAdapter } from "./interface.js";
+import { type SpotAdapter, type SpotBalance, type SpotMarketInfo } from "./spot-interface.js";
+import { type SpotCreateOptions, type VenueDefinition, type VenueSpotDefinition } from "./venue.js";
+import "./venues/index.js";
+/** Options for every non-CLI caller: on-chain approve txs are never sent implicitly. */
+export declare const NO_ONCHAIN_APPROVE: SpotCreateOptions;
+/** Venues with spot support, for remediation text. */
+export declare function listSpotVenues(): VenueDefinition[];
+/**
+ * Get (or create + init) the spot adapter for a venue. null iff the venue has no spot.
+ * `opts` defaults to NO_ONCHAIN_APPROVE (the safe deny); only the CLI passes --yes.
+ */
+export declare function getSpotAdapter(venue: string, perp: ExchangeAdapter, opts?: SpotCreateOptions): Promise<SpotAdapter | null>;
+/** The venue's spot definition, or CAPABILITY_UNSUPPORTED. */
+export declare function requireSpotDefinition(def: VenueDefinition): VenueSpotDefinition;
+/** CLI form: throws CAPABILITY_UNSUPPORTED when the venue has no spot. */
+export declare function requireSpotAdapter(venue: string, perp: ExchangeAdapter, opts?: SpotCreateOptions): Promise<SpotAdapter>;
+/**
+ * Bots (funding-arb*, spot-perp-*, arb-auto, arb/index) only use spot venues with a
+ * separate (or runtime-decided) spot balance and a spot↔perp transfer. Pacifica
+ * (shared margin) and Arcus (on-chain swap) are excluded.
+ */
+export declare function isBotSpotVenue(def: VenueDefinition): boolean;
+export declare function listBotSpotVenues(): VenueDefinition[];
+/** Bot form: throws CAPABILITY_UNSUPPORTED for venues outside the bot spot scope. */
+export declare function requireBotSpotVenue(venue: string): VenueDefinition & {
+    spot: VenueSpotDefinition;
+};
+/**
+ * Bot spot adapter for an adapter-map name. null when the name is not a venue, or the
+ * venue is outside the bot spot scope. Creation errors propagate.
+ */
+export declare function getBotSpotAdapter(name: string, perp: ExchangeAdapter): Promise<SpotAdapter | null>;
+/** Upper-cased token with venue balance suffixes removed ("USDC_SPOT" / "PURR-SPOT" → base). */
+export declare function spotTokenBase(token: string): string;
+/** The venue's spot quote assets on `net` (network-keyed: Lighter RH quotes USDG on mainnet, USDC on testnet). */
+export declare function spotQuoteAssets(def: VenueDefinition, net: Network): readonly string[];
+/** Default quote on `net` (bare-base symbols, transfers). */
+export declare function defaultSpotQuote(def: VenueDefinition, net: Network): string;
+/** The network a spot adapter was created for (getSpotAdapter). */
+export declare function spotNetworkOf(spot: SpotAdapter): Network;
+export declare function isSpotQuoteAsset(def: VenueDefinition, net: Network, token: string): boolean;
+/** "BASE/QUOTE" for a bare base on this venue (quoteAssets[net][0]). */
+export declare function spotPairSymbol(def: VenueDefinition, net: Network, base: string): string;
+/** The balance row of the venue's default quote asset (transfer asset), or null. */
+export declare function findSpotQuoteBalance(def: VenueDefinition, net: Network, balances: readonly SpotBalance[]): SpotBalance | null;
+/** Non-quote balances with a positive total (the "holdings" side of spot-perp hedges). */
+export declare function nonQuoteSpotBalances(def: VenueDefinition, net: Network, balances: readonly SpotBalance[]): SpotBalance[];
+/**
+ * true when spot quote balance is the same money as perp margin for this perp
+ * adapter: accountModel "unified", or "runtime" with a unified perp account (HL).
+ */
+export declare function spotSharesPerpMargin(def: VenueDefinition, perp: ExchangeAdapter): boolean;
+export interface ValuedSpotBalance extends SpotBalance {
+    valueUsd: number;
+}
+/**
+ * USD value of positive spot balances. Quote assets (stablecoins) are 1:1; other
+ * tokens use the venue's spot mark price. Tokens without a usable price are
+ * EXCLUDED and reported via `warn` — never valued at 0 (SSOT Rule #2).
+ * `shared` is carried through so aggregators can skip money already in perp equity.
+ */
+export declare function valueSpotBalances(def: VenueDefinition, net: Network, balances: readonly SpotBalance[], markets: readonly SpotValuationPrice[], warn: (msg: string) => void): ValuedSpotBalance[];
+/** Timeout for one venue's spot valuation (balances + prices) in aggregate views (portfolio, landing). */
+export declare const SPOT_VALUATION_TIMEOUT_MS = 5000;
+/** The price fields valuation reads (a spot market, or a held token's price — SpotHoldingPrice). */
+export type SpotValuationPrice = Pick<SpotMarketInfo, "baseToken" | "markPrice">;
+/**
+ * Prices used to value `balances`. Wallet-model venues (Arcus) price only the held
+ * non-quote tokens (`getSpotPrices`); exchange venues use `getSpotMarkets()`, plus — when the
+ * adapter is SpotHoldingPricesCapable — `getHoldingPrices()` for held tokens that are not a spot
+ * market (Hyperliquid HIP-4 outcome tokens). A holding price counts only when it is quoted in one of
+ * the venue's spot quote assets (valued 1:1 like the quote balance); any other quote (or an unknown
+ * one) → markPrice null → the token stays unpriced (never 0).
+ */
+export declare function spotMarketsForValuation(def: VenueDefinition, spot: SpotAdapter, balances: readonly SpotBalance[], net: Network): Promise<SpotValuationPrice[]>;
+/**
+ * Balances + valuation for aggregate views, bounded by `timeoutMs` (rejects with a
+ * TIMEOUT error; the caller reports it — never a partial or zero value).
+ */
+export declare function fetchValuedSpotBalances(def: VenueDefinition, spot: SpotAdapter, warn: (msg: string) => void, timeoutMs?: number): Promise<ValuedSpotBalance[]>;
+/** Reject with TIMEOUT after `timeoutMs` (the timer is cleared either way). */
+export declare function withSpotTimeout<T>(p: Promise<T>, what: string, timeoutMs?: number): Promise<T>;
+/**
+ * Fixed-point decimal string for a transfer amount, floored to TRANSFER_STEP — never
+ * `String(n)` (exponent "1e-7" or float artefacts "0.30000000000000004").
+ */
+export declare function transferAmountString(amount: number): string;
+/**
+ * Move the venue's quote asset (quoteAssets[0]) perp → spot.
+ * Returns false (no-op, nothing moved) when spot and perp share margin; throws
+ * CAPABILITY_UNSUPPORTED when the venue has no transfer. Callers log "Transferred" only on true.
+ */
+export declare function transferQuoteToSpot(spot: SpotAdapter, amount: number): Promise<boolean>;
+/**
+ * A spot↔perp transfer the venue refused for lack of funds (classifyError → INSUFFICIENT_BALANCE,
+ * e.g. HL "Insufficient balance for withdrawal.") → INSUFFICIENT_BALANCE that says how much the
+ * SOURCE side can move OF THE TRANSFER ASSET (`readAvailable`: perp withdrawable for to-spot, spot
+ * quote available for to-perp) — never an account-wide equity figure: a multi-asset margin
+ * account can hold margin and none of the asset. A failed read is reported as such (never a
+ * guessed figure). Any other error → unchanged.
+ */
+export declare function transferShortfallError(e: unknown, opts: {
+    venue: string;
+    direction: "to-spot" | "to-perp";
+    amount: string;
+    asset: string;
+    readAvailable: () => Promise<number>;
+}): Promise<unknown>;
+/** Spot → perp counterpart of transferQuoteToSpot. */
+export declare function transferQuoteToPerp(spot: SpotAdapter, amount: number): Promise<boolean>;
+/**
+ * Spot quote (quoteAssets[0]) `available` read UNCACHED; 0 when the venue holds no
+ * quote row. Errors propagate. Used as the baseline for sweepSpotQuoteToPerp().
+ */
+export declare function readSpotQuoteAvailableFresh(spot: SpotAdapter): Promise<number>;
+/**
+ * Sweep back to perp ONLY the spot quote this trade produced / left over: the part of
+ * the (uncached) available balance above `keep` (the quote that was there before the
+ * trade — never touched), capped at `max` (e.g. what this trade transferred in; null =
+ * no cap). Returns the amount moved; 0 when the balance is shared with perp or the
+ * amount is ≤ minAmount. Errors propagate — callers surface them (funds remain in spot).
+ */
+export declare function sweepSpotQuoteToPerp(spot: SpotAdapter, minAmount: number, opts: {
+    keep: number;
+    max: number | null;
+}): Promise<number>;
+export interface SpotPerpMatch {
+    /** Spot base as the spot adapter names it (bare base → quoteAssets[0]). */
+    spotBase: string;
+    /** Perp market symbol on the perp venue (VenueMarket.symbol). */
+    perpSymbol: string;
+    canonical: string;
+    assetClass: AssetClass;
+    spotPrice: number;
+    perpPrice: number;
+    /** |spot − perp| / perp × 100 */
+    deviationPct: number;
+}
+/**
+ * Match a spot venue's markets (default quote only) to a perp venue's markets by
+ * canonical symbol — `canonicalFor(spotVenue, base, perp.assetClass)` must equal the
+ * perp market's canonical (`null` never matches, NEVER_MATCH pairs excluded) — plus a
+ * price guard: |spot − perp mark| ≤ MAX_PRICE_DEVIATION_PCT. Spot markets without a
+ * price cannot be validated and are not matched. Bare-ticker equality is never enough.
+ *
+ * `perpMarkets` = the perp venue's public markets (`fetchPerpMarketsForMatching`).
+ * Returns spot base (upper-case) → match.
+ */
+export declare function matchSpotPerp(spotVenue: string, spotMarkets: readonly SpotMarketInfo[], perpVenue: string, perpMarkets: readonly VenueMarket[], warn: (msg: string) => void, net: Network): Map<string, SpotPerpMatch>;
+/** The perp venue's public markets (canonical + asset class + mark) on `net` (default: process network). */
+export declare function fetchPerpMarketsForMatching(perpVenue: string, net?: Network): Promise<VenueMarket[]>;