perp-cli 0.12.17 → 0.14.1

package/dist/funding/normalize.d.ts

@@ -1,26 +1,36 @@
 /**
- * Funding rate normalization.
+ * Funding rate normalization (design §10.1, §10.13 #1).
  *
- * Exchange funding rate periods:
- * - Hyperliquid: per 1 HOUR (settles every 1h)
- * - Pacifica: per 1 HOUR (settles every 1h)
- * - Lighter: per 8 HOURS (API returns 8h rate, settles every 1h)
+ * The number of hours one quoted rate covers (the funding BASIS) comes from the
+ * venue definition — `VenueDefinition.fundingRateBasis`, read through
+ * `fundingBasisOf(ref)`. Settlement timing is a separate concept (arb/utils.ts).
  *
- * HIP-3 deployed dexes on Hyperliquid use 8h funding periods.
- *
- * To compare rates across exchanges, we normalize everything to
- * a per-hour basis, then annualize from there.
+ * A venue ref is a venue id/alias, or "hl:<dex>" for Hyperliquid HIP-3 dexes
+ * (those resolve to the Hyperliquid core basis — current behavior preserved).
+ * Unknown refs throw UNKNOWN_VENUE; per-market venues
+ * have no single hours value — use the market's basis with the `*ByBasis`
+ * variants below.
+ */
+import { type FundingRateBasis } from "../exchanges/venue-types.js";
+/**
+ * Funding basis of a venue ref. Unknown refs (e.g. a stale value in persisted
+ * arb/bot state) surface as UNKNOWN_VENUE with remediation instead of an
+ * anonymous crash deep inside a strategy loop.
  */
+export declare function venueFundingBasis(ref: string): FundingRateBasis;
 /**
- * Get funding period in hours for an exchange.
- * HIP-3 deployed dexes (not in the map) default to 1h (API returns hourly).
- * HL and PAC are 1h, Lighter API returns 8h rates.
+ * Hours one quoted funding rate covers for a venue ref.
+ * Throws INVALID_PARAMS for per-market or annualized venues — use the market's basis.
  */
-export declare function getFundingHours(exchange: string): number;
-/** Convert a raw funding rate to per-hour rate */
-export declare function toHourlyRate(rate: number, exchange: string): number;
+export declare function getFundingHours(ref: string): number;
+/** Convert a raw quoted rate to a per-hour rate using an explicit (market) basis. */
+export declare function toHourlyRateByBasis(rate: number, basis: FundingRateBasis): number;
+/** Convert a raw funding rate to per-hour rate using the venue's basis. */
+export declare function toHourlyRate(rate: number, ref: string): number;
 /** Annualize a raw rate from a specific exchange */
 export declare function annualizeRate(rate: number, exchange: string): number;
+/** Annualize a raw rate quoted on an explicit (market) basis */
+export declare function annualizeRateByBasis(rate: number, basis: FundingRateBasis): number;
 /** Annualize an already-normalized hourly rate (no exchange conversion needed) */
 export declare function annualizeHourlyRate(hourlyRate: number): number;
 /**
@@ -39,9 +49,11 @@ export declare function computeSignedAnnualSpread(shortRate: number, shortExchan
 /**
  * Estimate hourly funding payment for a position.
  * @param rate - raw funding rate from the exchange
- * @param exchange - exchange name
+ * @param exchange - venue ref
  * @param positionUsd - position notional in USD
  * @param side - "long" or "short" (longs pay positive rate, shorts receive)
  * @returns hourly payment in USD (positive = you pay, negative = you receive)
  */
 export declare function estimateHourlyFunding(rate: number, exchange: string, positionUsd: number, side: "long" | "short"): number;
+/** Same as estimateHourlyFunding, from an already-normalized hourly rate. */
+export declare function estimateHourlyFundingFromHourly(hourlyRate: number, positionUsd: number, side: "long" | "short"): number;

package/dist/funding/normalize.js

@@ -1,42 +1,71 @@
 /**
- * Funding rate normalization.
+ * Funding rate normalization (design §10.1, §10.13 #1).
  *
- * Exchange funding rate periods:
- * - Hyperliquid: per 1 HOUR (settles every 1h)
- * - Pacifica: per 1 HOUR (settles every 1h)
- * - Lighter: per 8 HOURS (API returns 8h rate, settles every 1h)
+ * The number of hours one quoted rate covers (the funding BASIS) comes from the
+ * venue definition — `VenueDefinition.fundingRateBasis`, read through
+ * `fundingBasisOf(ref)`. Settlement timing is a separate concept (arb/utils.ts).
  *
- * HIP-3 deployed dexes on Hyperliquid use 8h funding periods.
- *
- * To compare rates across exchanges, we normalize everything to
- * a per-hour basis, then annualize from there.
+ * A venue ref is a venue id/alias, or "hl:<dex>" for Hyperliquid HIP-3 dexes
+ * (those resolve to the Hyperliquid core basis — current behavior preserved).
+ * Unknown refs throw UNKNOWN_VENUE; per-market venues
+ * have no single hours value — use the market's basis with the `*ByBasis`
+ * variants below.
  */
+import { PerpError } from "../errors.js";
+import { fundingBasisOf, parseVenueRef } from "../exchanges/venue.js";
+import { rateToHourly } from "../exchanges/venue-types.js";
+import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 /** Funding periods per year by convention */
 const HOURLY_PERIODS = 24 * 365; // 8760
-/** How many hours each exchange's rate covers */
-const EXCHANGE_FUNDING_HOURS = {
-    hyperliquid: 1,
-    pacifica: 1,
-    lighter: 8,
-    aster: 8,
-};
 /**
- * Get funding period in hours for an exchange.
- * HIP-3 deployed dexes (not in the map) default to 1h (API returns hourly).
- * HL and PAC are 1h, Lighter API returns 8h rates.
+ * Funding basis of a venue ref. Unknown refs (e.g. a stale value in persisted
+ * arb/bot state) surface as UNKNOWN_VENUE with remediation instead of an
+ * anonymous crash deep inside a strategy loop.
+ */
+export function venueFundingBasis(ref) {
+    ensureVenuesRegistered();
+    try {
+        parseVenueRef(ref);
+    }
+    catch (err) {
+        if (err instanceof PerpError && err.structured.code === "UNKNOWN_VENUE") {
+            throw new PerpError("UNKNOWN_VENUE", `Cannot normalize funding for unknown venue reference "${ref}"`, {
+                remediation: "Use a registered venue id (or hl:<dex> for HIP-3). If the value came from persisted state "
+                    + "(~/.perp/arb-state.json or a bot state file), fix or remove that entry.",
+            });
+        }
+        throw err;
+    }
+    return fundingBasisOf(ref);
+}
+/**
+ * Hours one quoted funding rate covers for a venue ref.
+ * Throws INVALID_PARAMS for per-market or annualized venues — use the market's basis.
  */
-export function getFundingHours(exchange) {
-    return EXCHANGE_FUNDING_HOURS[exchange.toLowerCase()] ?? 1;
+export function getFundingHours(ref) {
+    const basis = venueFundingBasis(ref);
+    if (basis.kind !== "perHours") {
+        throw new PerpError("INVALID_PARAMS", `Funding basis of "${ref}" is annualized, not a number of hours`, {
+            remediation: "Use the market's fundingRateBasis with toHourlyRateByBasis()",
+        });
+    }
+    return basis.hours;
 }
-/** Convert a raw funding rate to per-hour rate */
-export function toHourlyRate(rate, exchange) {
-    const hours = EXCHANGE_FUNDING_HOURS[exchange.toLowerCase()] ?? 1;
-    return rate / hours;
+/** Convert a raw quoted rate to a per-hour rate using an explicit (market) basis. */
+export function toHourlyRateByBasis(rate, basis) {
+    return rateToHourly(rate, basis);
+}
+/** Convert a raw funding rate to per-hour rate using the venue's basis. */
+export function toHourlyRate(rate, ref) {
+    return rateToHourly(rate, venueFundingBasis(ref));
 }
 /** Annualize a raw rate from a specific exchange */
 export function annualizeRate(rate, exchange) {
-    const hourlyRate = toHourlyRate(rate, exchange);
-    return hourlyRate * HOURLY_PERIODS * 100; // as percentage
+    return annualizeHourlyRate(toHourlyRate(rate, exchange));
+}
+/** Annualize a raw rate quoted on an explicit (market) basis */
+export function annualizeRateByBasis(rate, basis) {
+    return annualizeHourlyRate(toHourlyRateByBasis(rate, basis));
 }
 /** Annualize an already-normalized hourly rate (no exchange conversion needed) */
 export function annualizeHourlyRate(hourlyRate) {
@@ -66,13 +95,16 @@ export function computeSignedAnnualSpread(shortRate, shortExchange, longRate, lo
 /**
  * Estimate hourly funding payment for a position.
  * @param rate - raw funding rate from the exchange
- * @param exchange - exchange name
+ * @param exchange - venue ref
  * @param positionUsd - position notional in USD
  * @param side - "long" or "short" (longs pay positive rate, shorts receive)
  * @returns hourly payment in USD (positive = you pay, negative = you receive)
  */
 export function estimateHourlyFunding(rate, exchange, positionUsd, side) {
-    const hourlyRate = toHourlyRate(rate, exchange);
+    return estimateHourlyFundingFromHourly(toHourlyRate(rate, exchange), positionUsd, side);
+}
+/** Same as estimateHourlyFunding, from an already-normalized hourly rate. */
+export function estimateHourlyFundingFromHourly(hourlyRate, positionUsd, side) {
     // Long pays positive funding, short receives positive funding
     const multiplier = side === "long" ? 1 : -1;
     return hourlyRate * positionUsd * multiplier;

package/dist/funding/rates.d.ts

@@ -1,22 +1,36 @@
 /**
- * Real-time 3-DEX funding rate comparison.
+ * Real-time cross-venue funding rate comparison.
  *
- * Fetches funding rates from Pacifica, Hyperliquid, and Lighter in parallel,
- * normalizes them to comparable hourly rates, and identifies arbitrage
- * opportunities across exchanges.
+ * Fans out over every venue with the "marketData" role (design §10.6) using
+ * each venue's `publicData.fetchFundingRates(net)`, normalizes every row to a
+ * per-hour rate with the row's own basis (Lighter
+ * family 8h, Aster per-symbol), and matches markets across venues by
+ * `canonical` (null → excluded, §10.9).
+ *
+ * A venue that fails is reported in `exchangeStatus` ("error") and
+ * `exchangeErrors` (message) — its rows are absent, never silently empty.
  */
 import { type HistoricalAverages } from "./history.js";
+import { type VenueDefinition } from "../exchanges/venue.js";
+import { type FundingRateBasis, type Network, type VenueId } from "../exchanges/venue-types.js";
 export interface ExchangeFundingRate {
-    exchange: "pacifica" | "hyperliquid" | "lighter" | "aster";
+    exchange: VenueId;
+    /** Venue display symbol (e.g. "kPEPE", "BTC"). */
     symbol: string;
+    /** Cross-venue matching key (canonical-symbols.ts). */
+    canonical: string;
     fundingRate: number;
+    basis: FundingRateBasis;
     hourlyRate: number;
     annualizedPct: number;
     markPrice: number;
-    nextFundingTime?: number;
-    historicalAvg?: HistoricalAverages;
+    nextFundingTime: number | null;
+    historicalAvg: HistoricalAverages | null;
+    /** false = the venue's funding rate is unverified (VenueDefinition.fundingVerified) — shown only on explicit request. */
+    fundingVerified: boolean;
 }
 export interface SymbolFundingComparison {
+    /** Canonical symbol shared by every row. */
     symbol: string;
     rates: ExchangeFundingRate[];
     maxSpreadAnnual: number;
@@ -29,20 +43,38 @@ export interface FundingRateSnapshot {
     timestamp: string;
     symbols: SymbolFundingComparison[];
     exchangeStatus: Record<string, "ok" | "error">;
+    /** Error message per venue whose status is "error" (§10.13 #3). */
+    exchangeErrors: Record<string, string>;
 }
 export declare const TOP_SYMBOLS: string[];
 /**
- * Fetch funding rates from all 3 DEXs in parallel, normalize, and compare.
+ * Fetch every venue in `venues` concurrently; failures land in status/errors.
+ * Venues whose funding is unverified (VenueDefinition.fundingVerified false — QFEX until its
+ * rate unit is confirmed) are DROPPED unless `includeUnverified`: every consumer that ranks,
+ * alerts on or trades funding spreads (arb scan, MCP, alerts, dashboard, portfolio) leaves it
+ * false. Only explicit, labelled reads pass true (`arb scan --include-unverified`).
+ */
+export declare function fetchVenuesRates(venues: VenueDefinition[], net: Network, includeUnverified: boolean): Promise<{
+    rates: ExchangeFundingRate[];
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
+}>;
+/**
+ * Fetch funding rates from every market-data venue in parallel, normalize, and compare.
  * Returns rates sorted by max spread (descending).
+ * @param opts.network defaults to the network the CLI selected (setSharedApiNetwork)
  */
 export declare function fetchAllFundingRates(opts?: {
     symbols?: string[];
     minSpread?: number;
+    network?: Network;
+    /** Also fetch venues whose funding rate is unverified (default false — see fetchVenuesRates). */
+    includeUnverified?: boolean;
 }): Promise<FundingRateSnapshot>;
 /**
- * Fetch rates for a single symbol across all exchanges.
+ * Fetch rates for a single (canonical) symbol across all exchanges.
  */
-export declare function fetchSymbolFundingRates(symbol: string): Promise<SymbolFundingComparison | null>;
+export declare function fetchSymbolFundingRates(symbol: string, includeUnverified?: boolean): Promise<SymbolFundingComparison | null>;
 export interface SpotPerpSpread {
     symbol: string;
     /** Perp exchange with the highest absolute funding rate */
@@ -65,7 +97,7 @@ export interface SpotPerpSpread {
 /**
  * Fetch spot+perp funding rate spreads.
  * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
- * Only includes symbols available on at least one spot exchange (HL or LT).
+ * Only includes symbols available on at least one bot spot venue (def.spot, §12.4 #3).
  *
  * Key safety checks:
  * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
@@ -75,7 +107,10 @@ export interface SpotPerpSpread {
 export declare function fetchSpotPerpSpreads(opts?: {
     symbols?: string[];
     minSpread?: number;
+    network?: Network;
 }): Promise<{
     timestamp: string;
     spreads: SpotPerpSpread[];
+    exchangeStatus: Record<string, "ok" | "error">;
+    exchangeErrors: Record<string, string>;
 }>;