perp-cli 0.14.3 → 0.16.0

package/dist/commands/agent.js

@@ -9,7 +9,8 @@ import chalk from "chalk";
 import bs58 from "bs58";
 import { loadSettings } from "../settings.js";
 import { getAgent, setAgent, deleteAgent, listAgents, acquireLock, releaseLock, getVenueAgent, getVenueAgentForNetwork, setVenueAgent, deleteVenueAgent, listVenueAgents, agentNetworkOf, recordedAgentNetworkOf, assertAgentNetwork, getAgentForNetwork, agentSourceOf, } from "../agent-wallet/store.js";
-import { getVenue, networkConfig, resolveVenueId } from "../exchanges/venue.js";
+import { getVenue, networkConfig, resolveVenueId, roleUnsupported } from "../exchanges/venue.js";
+import { RISEX_APP_URL } from "../exchanges/venues/risex.js";
 import { listConfiguredAccountVenues } from "../config.js";
 import "../exchanges/venues/index.js";
 import { LIGHTER_RH_RESERVED_KEY_INDEXES } from "../exchanges/venues/lighter-family.js";
@@ -114,7 +115,7 @@ function readPipedStdin() {
     });
 }
 /**
- * Ondo API key id + secret, from stdin only (design §10.4 — never flags).
+ * Ondo API key id + secret, from stdin only (never flags).
  * TTY: key id prompt, then hidden secret prompt. Piped: line 1 = key id, line 2 = secret.
  */
 /** Lighter ChangePubKey settlement window when confirming a slot (docs example: 30 s, 1 s apart; kept under the 60 req/min budget). */
@@ -445,7 +446,7 @@ async function verifyQfex(network, opts) {
     };
 }
 /**
- * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * Confirmation of the account a QFEX key was resolved to. In a terminal: a
  * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
  * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
  */
@@ -471,6 +472,40 @@ export function confirmImportAccount(explicitAccountId, json) {
         }
     };
 }
+/** RISEx: session-key status on the venue and the on-chain permission bitmap (read-only). */
+async function verifyRisex(network, opts) {
+    const meta = opts.agentName !== undefined ? getVenueAgent("risex", opts.agentName) : getVenueAgentForNetwork("risex", network);
+    // Read-only release (trading role gated): approve / revoke are refused, so point to the RISEx app.
+    const tradingGated = !getVenue("risex").roles.includes("trading");
+    if (!meta) {
+        throw new PerpError("AGENT_NOT_REGISTERED", `No RISEx signer registered for ${network}`, {
+            remediation: tradingGated
+                ? `RISEx is read-only in this perp-cli release (trading in a later release): manage signers in the RISEx app (${RISEX_APP_URL})`
+                : `perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --master <ows-wallet>`,
+        });
+    }
+    const { verifyRisexAgent } = await import("../exchanges/risex/agent.js");
+    const v = await verifyRisexAgent(meta);
+    const warnings = [];
+    if (!v.active)
+        warnings.push(`RISEx signer ${meta.signerAddress} status is ${String(v.status)} (1 = Active)`);
+    if (v.expired)
+        warnings.push(`RISEx signer ${meta.signerAddress} expired at ${meta.expiresAt}`);
+    if (v.active && (!v.tradingOnly || meta.permissions.tradingOnly !== true)) {
+        // An active signer that can do more than trade is a failure, never ok:true.
+        throw new PerpError("POLICY_DENIED", `RISEx signer ${meta.signerAddress} ("${meta.agentName}") is NOT restricted to trading-only (on-chain ${JSON.stringify(v.permissions)}, bitmap ${String(v.bitmap)}; recorded tradingOnly=${String(meta.permissions.tradingOnly)})${v.reason !== null ? ` — ${v.reason}` : ""}`, {
+            exchange: "risex", signer: meta.signerAddress, permissions: v.permissions, bitmap: v.bitmap,
+            remediation: tradingGated
+                ? `Revoke it in the RISEx app (${RISEX_APP_URL}); then remove the local record: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke risex ${meta.agentName} --force`
+                : `Revoke it: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke risex ${meta.agentName}, then approve a new one`,
+        });
+    }
+    return {
+        registered: v.active, count: 1,
+        items: [{ agentName: meta.agentName, signer: meta.signerAddress, account: meta.accountAddress, network: meta.network, status: v.status, permissions: v.permissions, tradingOnly: v.tradingOnly, expiresAt: meta.expiresAt }],
+        warnings: warnings.length > 0 ? warnings : undefined,
+    };
+}
 /** Dispatch a verify to the venue-specific implementation. */
 async function verifyVenue(ex, network, opts) {
     if (ex === "aster")
@@ -487,8 +522,10 @@ async function verifyVenue(ex, network, opts) {
         return verifyArcus(network, opts);
     if (ex === "qfex")
         return verifyQfex(network, opts);
+    if (ex === "risex")
+        return verifyRisex(network, opts);
     throw new PerpError("NOT_IMPLEMENTED", `${ex} has no agents to verify`, {
-        remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter|lighter-rh|ondo|arcus|qfex> [agentName]",
+        remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter|lighter-rh|ondo|arcus|qfex|risex> [agentName]",
     });
 }
 /**
@@ -509,6 +546,9 @@ export function agentApproveUnsupportedReason(venue, network, op) {
 }
 /** Throws the uniform CAPABILITY_UNSUPPORTED error when agentApproveUnsupportedReason() is non-null. */
 export function assertAgentApproveSupported(venue, network, op) {
+    const def = getVenue(venue);
+    if (!def.roles.includes("trading"))
+        throw roleUnsupported(def, `agent ${op}`);
     if (venue === "qfex") {
         // Programmatic key creation needs a website session (SIWE + MFA) — not a CLI path.
         throw unsupported("qfex", "agentApprove", "API keys are created (and revoked) on the QFEX website, behind 2FA", `Create the key in QFEX Developer Settings, then import it: perp${network === "testnet" ? " -n testnet" : ""} wallet agent import qfex`);
@@ -540,6 +580,11 @@ export function defaultAgentName(venue, network) {
         case "ondo": return `perp-cli-ondo${suffix}`;
         case "arcus": return `perp-cli-arcus${suffix}`;
         case "qfex": return `perp-cli-qfex${suffix}`;
+        case "risex": return `perp-cli-risex${suffix}`;
+        case "txflow": return `perp-cli-txflow${suffix}`;
+        case "variational": return `perp-cli-variational${suffix}`;
+        case "grvt": return `perp-cli-grvt${suffix}`;
+        case "extended": return `perp-cli-extended${suffix}`;
     }
 }
 /**
@@ -622,7 +667,7 @@ function requirePassphrase(passphrase) {
 export async function approveVenueAgent(p) {
     assertAgentApproveSupported(p.venue, p.network, "approve");
     const agentName = p.agentName ?? defaultAgentName(p.venue, p.network);
-    // Ondo: HMAC key entered on stdin only (design §10.4)
+    // Ondo: HMAC key entered on stdin only
     if (p.venue === "ondo") {
         assertVenueAgentNameFree("ondo", agentName, p.network);
         if (getVenueAgent("ondo", agentName) && !p.rotate) {
@@ -636,7 +681,7 @@ export async function approveVenueAgent(p) {
         setVenueAgent("ondo", meta);
         return { venue: "ondo", meta };
     }
-    // Arcus: OWS Ed25519 agent + EIP-712 createApiKey (design §10.4)
+    // Arcus: OWS Ed25519 agent + EIP-712 createApiKey
     if (p.venue === "arcus") {
         const masterName = requireMaster(p.master);
         assertVenueAgentNameFree("arcus", agentName, p.network);
@@ -660,6 +705,53 @@ export async function approveVenueAgent(p) {
             releaseLock("arcus");
         }
     }
+    // RISEx: master-signed RegisterSigner, then an on-chain restriction to trading-only.
+    if (p.venue === "risex") {
+        const masterName = requireMaster(p.master);
+        assertVenueAgentNameFree("risex", agentName, p.network);
+        if (p.canWithdraw || p.canSpot) {
+            throw new PerpError("INVALID_PARAMS", "RISEx signers registered by perp-cli are always restricted to trading only (no fund movement, no spot)", {
+                remediation: "Drop --can-withdraw / --can-spot",
+            });
+        }
+        const expiresAt = parseExpiresInParam(p.expiresIn);
+        const { approveRisexAgent, revokeRisexAgent, risexAgentWalletName, risexRotatePreflight, risexSignerStatus } = await import("../exchanges/risex/agent.js");
+        acquireLock("risex");
+        try {
+            const existing = getVenueAgent("risex", agentName);
+            if (existing !== null) {
+                if (!p.rotate) {
+                    throw new PerpError("INVALID_PARAMS", `RISEx signer "${agentName}" already exists`, {
+                        remediation: `Replace it (revoke the old signer, register a fresh one): perp${p.network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --rotate — or choose another --agent-name`,
+                    });
+                }
+                // Rotate: the new signer's checks (pins, maintenance, master gas) pass first, then a
+                // venue-confirmed revoke of the old signer, then drop its key, then approve.
+                await risexRotatePreflight(masterName, p.passphrase, p.network);
+                // A kept record whose signer never registered (or is already revoked) has nothing to
+                // revoke on the venue: it is only forgotten locally. An Active one is revoked first.
+                const status = await risexSignerStatus(existing);
+                if (status === 1)
+                    await revokeRisexAgent({ meta: existing, masterOwsWallet: masterName, passphrase: p.passphrase });
+                try {
+                    loadOws().deleteWallet(existing.agentWalletName);
+                }
+                catch { /* already gone */ }
+                deleteVenueAgent("risex", agentName);
+            }
+            else if (p.rotate && loadOws().listWallets().some((w) => w.name === risexAgentWalletName(masterName, p.network))) {
+                throw new PerpError("INVALID_PARAMS", `OWS wallet "${risexAgentWalletName(masterName, p.network)}" exists but no RISEx signer record uses it`, {
+                    remediation: `If no RISEx signer uses its key, delete it (ows wallet delete ${risexAgentWalletName(masterName, p.network)}) and re-run the approve`,
+                });
+            }
+            const meta = await approveRisexAgent({ agentName, masterOwsWallet: masterName, passphrase: p.passphrase, network: p.network, expiresAt });
+            setVenueAgent("risex", meta);
+            return { venue: "risex", meta };
+        }
+        finally {
+            releaseLock("risex");
+        }
+    }
     const expiresAt = parseExpiresInParam(p.expiresIn);
     const masterName = requireMaster(p.master);
     const expiresAtIso = expiresAt.toISOString();
@@ -993,6 +1085,16 @@ export function printApproveOutcome(outcome) {
             console.log(`  Valid Until:   ${chalk.cyan(outcome.meta.validUntil)}`);
             console.log();
             return;
+        case "risex":
+            console.log(chalk.green.bold("\n  RISEx signer registered and restricted to trading-only!\n"));
+            console.log(`  Name:        ${chalk.cyan(outcome.meta.agentName)}`);
+            console.log(`  Signer:      ${chalk.cyan(outcome.meta.signerAddress)}`);
+            console.log(`  Account:     ${chalk.cyan(outcome.meta.accountAddress)}`);
+            console.log(`  Expires:     ${chalk.cyan(outcome.meta.expiresAt)}`);
+            console.log(`  Permissions: ${chalk.cyan("trading only")} ${chalk.gray(`(on-chain; disabled ${outcome.meta.permissions.disabled.join(", ")}; verified ${outcome.meta.permissions.verifiedAt})`)}`);
+            console.log(chalk.gray("  Deposits / withdrawals: RISEx app only (perp-cli never moves RISEx funds)."));
+            console.log();
+            return;
         case "lighter":
         case "lighter-rh":
             console.log(chalk.green.bold(`\n  ${getVenue(outcome.venue).displayName} Agent approved successfully!\n`));
@@ -1043,7 +1145,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
     // ── agent approve <exchange> ── register an agent wallet ──────────────────
     agent
         .command("approve <exchange>")
-        .description("Register an agent wallet / API key for an exchange (aster, hyperliquid, pacifica, lighter, lighter-rh, ondo, arcus)")
+        .description("Register an agent wallet / API key for an exchange (aster, hyperliquid, pacifica, lighter, lighter-rh, ondo, arcus, risex — risex: a trading-only session signer, restricted on-chain)")
         .option("--master <name>", "Master OWS wallet name")
         .option("--agent-name <name>", "Agent name (default: perp-cli-aster)")
         .option("--expires-in <duration>", "Expiry: 30d, 90d, 180d, 1y, or ISO-8601 datetime (default: 90d)")
@@ -1087,7 +1189,8 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 assertAgentApproveSupported(venue, network, "approve");
             let master = opts.master ?? null;
             let agentName = opts.agentName ?? null;
-            let expiresIn = opts.expiresIn ?? "90d";
+            // RISEx signers default to 30 days (owner decision; the venue maximum is not documented).
+            let expiresIn = opts.expiresIn ?? (venue === "risex" ? "30d" : "90d");
             let canPerp = opts.canPerp ?? true;
             let canSpot = opts.canSpot ?? false;
             let canWithdraw = opts.canWithdraw ?? false;
@@ -1218,6 +1321,9 @@ Examples:
             }
             const network = networkOf(command);
             const venue = resolveVenueId(exchange);
+            // TxFlow (market data only) / RISEx (perp-cli-registered, restricted signers only): refused before any stdin read.
+            const { assertImportSupported } = await import("./agent-import.js");
+            assertImportSupported(venue, network);
             const int = (flag, raw) => {
                 if (raw === undefined)
                     return null;
@@ -1296,14 +1402,14 @@ Examples:
         for (const { exchange: ex, meta } of listVenueAgents()) {
             if (venueFilter !== null && venueFilter !== ex)
                 continue;
-            const expiresAt = meta.kind === "arcus" ? meta.validUntil : null;
+            const expiresAt = meta.kind === "arcus" ? meta.validUntil : meta.kind === "risex" ? meta.expiresAt : null;
             const status = expiresAt !== null && expiresAt !== "" && new Date(expiresAt).getTime() < now ? "expired" : "active";
             rows.push({
                 name: meta.agentName,
                 exchange: ex,
                 network: meta.network,
                 source: agentSourceOf(ex, meta),
-                evmAddress: meta.kind === "arcus" ? meta.ownerAddress : "",
+                evmAddress: meta.kind === "arcus" ? meta.ownerAddress : meta.kind === "risex" ? meta.signerAddress : "",
                 // Ondo keys carry no expiry; shown as "—".
                 expiresAt: expiresAt ?? "",
                 status,
@@ -1373,9 +1479,11 @@ Examples:
             network = networkOf(command);
             // An imported key is only ever removed locally, so it needs no venue support for revoke
             // (e.g. an imported Aster testnet key).
-            const rec = exchange === "ondo" || exchange === "arcus" || exchange === "qfex" ? getVenueAgent(exchange, agentName) : getAgent(exchange, agentName);
+            const rec = exchange === "ondo" || exchange === "arcus" || exchange === "qfex" || exchange === "risex" ? getVenueAgent(exchange, agentName) : getAgent(exchange, agentName);
             // QFEX keys only exist as imports: a missing record is "already removed", never an approve-capability error.
-            if (exchange !== "qfex" && (rec === null || agentSourceOf(exchange, rec) !== "imported"))
+            // A release-gated venue (RISEx in 0.15.0) still lets --force / --local-only clear local state: nothing is signed or sent.
+            const localCleanupOfGated = localOnly && getVenue(exchange).gatedRoles !== null;
+            if (exchange !== "qfex" && !localCleanupOfGated && (rec === null || agentSourceOf(exchange, rec) !== "imported"))
                 assertAgentApproveSupported(exchange, network, "revoke");
         }
         catch (e) {
@@ -1425,6 +1533,46 @@ Examples:
                     console.log(chalk.green(`Agent "${agentName}" on qfex removed locally.`) + chalk.yellow(`\n  ${note}`));
                 return;
             }
+            // ── RISEx: RevokeSigner signed by the master wallet (gasless REST); then the key is deleted ──
+            if (exchange === "risex") {
+                const risexMeta = getVenueAgent("risex", agentName);
+                if (!risexMeta) {
+                    if (useJson)
+                        printJson({ ok: true, data: { alreadyRevoked: true } });
+                    else
+                        console.log(`Agent "${agentName}" on risex not found locally — already revoked.`);
+                    return;
+                }
+                if (risexMeta.network !== network) {
+                    throw new PerpError("AGENT_NOT_REGISTERED", `RISEx signer "${agentName}" is registered on ${risexMeta.network}, not ${network}`, {
+                        remediation: risexMeta.network === "mainnet" ? "Run without -n testnet to revoke it" : "Run with -n testnet to revoke it",
+                    });
+                }
+                let txHash = null;
+                if (!localOnly) {
+                    const masterName = opts.master ?? loadSettings().owsActiveWallet;
+                    if (!masterName) {
+                        throw new PerpError("INVALID_PARAMS", "Master wallet name is required to revoke a RISEx signer", {
+                            remediation: "Use --master <name>, or --force to clear local state only (then revoke it in the RISEx app)",
+                        });
+                    }
+                    const passphrase = await resolvePassphrase({ flag: passphraseFlag });
+                    const { revokeRisexAgent } = await import("../exchanges/risex/agent.js");
+                    txHash = (await revokeRisexAgent({ meta: risexMeta, masterOwsWallet: masterName, passphrase })).txHash;
+                }
+                try {
+                    loadOws().deleteWallet(risexMeta.agentWalletName);
+                }
+                catch { /* already gone */ }
+                deleteVenueAgent("risex", agentName);
+                if (useJson)
+                    printJson(jsonOk({ revoked: !localOnly, local: localOnly, txHash }));
+                else
+                    console.log(localOnly
+                        ? chalk.yellow(`Agent "${agentName}" on risex removed locally only — revoke signer ${risexMeta.signerAddress} in the RISEx app.`)
+                        : chalk.green(`Agent "${agentName}" on risex revoked successfully.`));
+                return;
+            }
             // ── Arcus: EIP-712 RevokeApiKey signed by the master wallet ──
             if (exchange === "arcus") {
                 const arcusMeta = getVenueAgent("arcus", agentName);

package/dist/commands/arb/index.js

@@ -1,10 +1,11 @@
 import { isDryRun, networkOf, supportsDryRun } from "../../cli-flags.js";
 import chalk from "chalk";
-import { makeTable, formatUsd, formatPnl, printJson, jsonOk, logSettledRejections } from "../../utils.js";
+import { makeTable, formatUsd, formatPnl, printJson, jsonOk } from "../../utils.js";
 import { SPOT_PERP_TOKEN_MAP } from "../../exchanges/index.js";
 import { readExecutionLog, logExecution } from "../../execution-log.js";
 import { toHourlyRate } from "../../funding.js";
-import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../../shared-api.js";
+import { fetchVenuesRates } from "../../funding/rates.js";
+import { sharedApiNetwork } from "../../api/public/urls.js";
 import { computeBasisRisk } from "../../arb-utils.js";
 import { removePosition as persistRemovePosition, getPositions as getArbStatePositions, loadArbState } from "../../arb-state.js";
 import { fetchBalancesWithFailures, computeRebalancePlan } from "../../rebalance.js";
@@ -15,7 +16,7 @@ import { listConfiguredAccountVenues } from "../../config.js";
 import { closePerpPairVerified, handleSpotClose } from "../arb-auto.js";
 import { quarantineEntryFor } from "../../bot/quarantine.js";
 import { PerpError, classifyError, parsePositiveDecimal } from "../../errors.js";
-import { listVenuesWithRole, resolveVenueId } from "../../exchanges/venue.js";
+import { getVenue, listVenuesWithRole, resolveVenueId } from "../../exchanges/venue.js";
 // ── Helpers ──
 import { DEFAULT_TAKER_FEE as TAKER_FEE } from "../../constants.js";
 /**
@@ -108,81 +109,22 @@ function entryHourly(e) {
     return e.fundingHours !== null ? e.rate / e.fundingHours : toHourlyRate(e.rate, e.exchange);
 }
 async function fetchFundingRatesMap() {
+    // The SAME rate rows as `arb scan --rates` (fetchVenuesRates): canonical-keyed (unclassified /
+    // ambiguous tickers have no row), each with its own basis (fundingHours) and rateKind. A failed
+    // venue is reported on stderr (explicit, never silent).
+    const venues = ["pacifica", "hyperliquid", "lighter", "aster"].map(id => getVenue(id));
+    const { rates: fetched, exchangeErrors } = await fetchVenuesRates(venues, sharedApiNetwork(), false);
+    // Never a leg on an unverified rate (row label; the venue filter already drops them).
+    const rates = fetched.filter(r => r.fundingVerified);
+    for (const [ex, msg] of Object.entries(exchangeErrors))
+        process.stderr.write(`[arb] ${ex}: funding rates unavailable — ${msg}\n`);
     const rateMap = new Map();
-    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
-    // alive when one DEX errors out, while rejection reasons get logged to
-    // stderr (explicit failure, never silent .catch(() => [])).
-    const settled = await Promise.allSettled([
-        fetchPacificaPrices(),
-        fetchHyperliquidMeta(),
-        fetchLighterOrderBookDetails(),
-        fetchLighterFundingRates(),
-        fetch("https://fapi.asterdex.com/fapi/v1/premiumIndex").then(r => r.json()),
-        fetch("https://fapi.asterdex.com/fapi/v3/fundingInfo").then(r => r.json()),
-    ]);
-    logSettledRejections(settled, ["pacifica", "hyperliquid", "lighter:orderbook", "lighter:funding", "aster:premiumIndex", "aster:fundingInfo"], "arb");
-    const pacAssets = settled[0].status === "fulfilled" ? settled[0].value : [];
-    const hlAssets = settled[1].status === "fulfilled" ? settled[1].value : [];
-    const ltDetails = settled[2].status === "fulfilled" ? settled[2].value : [];
-    const ltFunding = settled[3].status === "fulfilled" ? settled[3].value : [];
-    // Aster funding basis is per symbol: a rate is usable only with its fundingInfo interval.
-    const asterPremiums = settled[4].status === "fulfilled" && settled[5].status === "fulfilled" ? settled[4].value : [];
-    const asterInfo = settled[5].status === "fulfilled" ? settled[5].value : [];
-    const asterHours = new Map();
-    for (const row of Array.isArray(asterInfo) ? asterInfo : []) {
-        const h = Number(row.fundingIntervalHours);
-        if (typeof row.symbol === "string" && Number.isFinite(h) && h > 0)
-            asterHours.set(row.symbol, h);
-    }
-    const addRate = (sym, exchange, rate, markPrice, fundingHours = null) => {
-        if (!sym)
-            return;
-        if (!rateMap.has(sym))
-            rateMap.set(sym, []);
-        rateMap.get(sym).push({ exchange, rate, markPrice, fundingHours });
-    };
-    for (const p of pacAssets)
-        addRate(p.symbol, "pacifica", p.funding, p.mark);
-    for (const h of hlAssets)
-        addRate(h.symbol, "hyperliquid", h.funding, h.markPx);
-    // Lighter: join details + funding by marketId
-    // SSOT rule #2: skip rows whose mark price cannot be resolved (no 0 fallback).
-    // Prefer fr.markPrice; fall back to orderBook last-trade as documented
-    // price-source preference (NOT error fallback).
-    const ltPriceMap = new Map(ltDetails.map(d => [d.marketId, d.lastTradePrice]));
-    const ltSymMap = new Map(ltDetails.map(d => [d.marketId, d.symbol]));
-    for (const fr of ltFunding) {
-        const sym = fr.symbol || ltSymMap.get(fr.marketId) || "";
-        if (!sym)
-            continue;
-        const directMark = fr.markPrice;
-        const fallbackMark = ltPriceMap.get(fr.marketId);
-        let mp;
-        if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
-            mp = directMark;
-        }
-        else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
-            mp = fallbackMark;
-        }
-        if (mp === undefined || !Number.isFinite(fr.rate))
-            continue;
-        addRate(sym, "lighter", fr.rate, mp);
-    }
-    // Aster: premiumIndex
-    // SSOT rule #2: skip rows missing markPrice / lastFundingRate instead of
-    // 0-coercing — a 0 markPrice would corrupt downstream sizing.
-    for (const p of asterPremiums) {
-        const rawSym = String(p.symbol ?? "");
-        if (!rawSym.endsWith("USDT"))
-            continue;
-        const fundingRate = Number(p.lastFundingRate);
-        const markPrice = Number(p.markPrice);
-        if (!Number.isFinite(fundingRate) || !Number.isFinite(markPrice) || markPrice <= 0)
-            continue;
-        const hours = asterHours.get(rawSym);
-        if (hours === undefined)
-            continue; // not in /fapi/v3/fundingInfo → cannot normalize
-        addRate(rawSym.replace(/USDT$/, ""), "aster", fundingRate, markPrice, hours);
+    for (const r of rates) {
+        if (r.basis.kind !== "perHours")
+            continue; // these four venues quote per hours
+        if (!rateMap.has(r.canonical))
+            rateMap.set(r.canonical, []);
+        rateMap.get(r.canonical).push({ exchange: r.exchange, rate: r.fundingRate, markPrice: r.markPrice, fundingHours: r.basis.hours });
     }
     return rateMap;
 }
@@ -420,7 +362,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         };
         // Collect spot balances per exchange
         const spotBalancesByExchange = new Map();
-        // Bot/arb spot scope (§12.4 #3): configured venues with a separate spot balance + transfer.
+        // Bot/arb spot scope: configured venues with a separate spot balance + transfer.
         const configuredVenues = new Set(await listConfiguredAccountVenues());
         for (const def of listBotSpotVenues()) {
             if (!configuredVenues.has(def.id))
@@ -802,7 +744,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             await dropStaleStateEntry(sym, opts.yes === true, dryRun);
             return;
         }
-        // Global quarantine (design §12.3): an unknown / unhedged outcome was recorded for
+        // Global quarantine: an unknown / unhedged outcome was recorded for
         // this symbol. A human may still close it, but only knowingly (--force).
         const quarantined = quarantineEntryFor(sym, (m) => console.error(chalk.red(m)));
         if (quarantined !== null) {
@@ -846,7 +788,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                 console.log(chalk.cyan(`  [DRY-RUN] Would close spot-perp ${sym}: sell spot on ${spotExch} + buy back the perp short on ${perpExch}`));
                 return;
             }
-            // One implementation for spot-perp close (fill-checked legs, §12.4 #5): arb-auto's handler.
+            // One implementation for spot-perp close (fill-checked legs): arb-auto's handler.
             if (handleSpotClose === undefined)
                 throw new Error("spot-perp close handler is not registered (registerArbAutoCommands not called)");
             await handleSpotClose(sym, { spotExch, perpExch }, getAdapterForExchange, isJson);
@@ -982,7 +924,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         // Close the legs sequentially (long, then short), reduce-only and verified, each
         // sized from the venue's own position size. No retries: a definite failure of the
         // long close changes nothing; an unknown outcome or a leg left open after the
-        // other closed quarantines the symbol (design §12.3).
+        // other closed quarantines the symbol.
         const results = [];
         const closeRes = await closePerpPairVerified({
             source: "arb-close", sym,

package/dist/commands/arb-auto.d.ts

@@ -1,6 +1,7 @@
 import type { Network } from "../exchanges/venue-types.js";
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
+import type { FundingRateKind } from "../exchanges/interface.js";
 interface FundingSnapshot {
     symbol: string;
     pacRate: number;
@@ -17,7 +18,24 @@ interface FundingSnapshot {
     astMarkPrice: number;
     /** Aster per-symbol funding interval (= basis and settlement interval) from /fapi/v3/fundingInfo; null when Aster has no rate. */
     astHours: number | null;
+    /** Which rate each paired venue's value is (arb scan rateKind): "lastSettled" | "accruing" | "predicted" | null. */
+    rateKinds?: Record<string, FundingRateKind | null>;
+    /**
+     * Each venue's OWN symbol for this canonical row (Hyperliquid kPEPE, Lighter 1000PEPE): orders,
+     * position matching and closes use it, never the canonical key. Absent = the venue trades `symbol`.
+     */
+    venueSymbols?: Record<string, string>;
 }
+/** The venue symbol a snapshot / position leg trades on `exchange` (the canonical key when the venue uses it). */
+export declare function legSymbol(row: {
+    symbol: string;
+    venueSymbols?: Record<string, string>;
+}, exchange: string): string;
+/** --symbols matches a row by its canonical key or any venue's own symbol (kPEPE or 1000PEPE). */
+export declare function matchesSymbolFilter(row: {
+    symbol: string;
+    venueSymbols?: Record<string, string>;
+}, filter: readonly string[]): boolean;
 export interface LegOrderMinimums {
     exchange: string;
     minSize: string | null;
@@ -216,10 +234,16 @@ export declare function dexCloseBlockedBy(pos: {
     longDex: string;
     shortDex: string;
 }, failedDexes: Record<string, string>): string | null;
+export declare function fetchFundingSpreads(): Promise<FundingSnapshot[]>;
 export declare let handleSpotClose: ((sym: string, opts: {
     spotExch?: string;
     perpExch?: string;
 }, getAdapterForExchange: (exchange: string) => Promise<import("../exchanges/interface.js").ExchangeAdapter>, isJson: () => boolean) => Promise<void>) | undefined;
+/**
+ * `arb auto` flag validation: every numeric flag must be a finite number in its range, `--size` a
+ * number or "auto", `--settle-strategy` one of block | aggressive | off. INVALID_PARAMS otherwise.
+ */
+export declare function assertArbAutoFlags(opts: Record<string, unknown>): void;
 export declare function registerArbAutoCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean, getHLAdapterForDex?: (dex: string) => Promise<import("../exchanges/hyperliquid.js").HyperliquidAdapter>): void;
 export declare let handleArbPnlRef: (() => Promise<void>) | undefined;
 /**