perp-cli 0.14.2 → 0.15.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

@@ -420,7 +420,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 +802,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 +846,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 +982,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.js

@@ -20,7 +20,7 @@ import { loadArbState, addPosition as persistAddPosition, removePosition as pers
 import { handleRates, handleBasisScan, handleDexScan, handleCompare, handleFundingHistory, handleFundingPositions, fetchAllPrices, printGapTable, printTrackSummary, formatGapPrice, } from "./arb.js";
 // ── Fee-Adjusted Net Spread Calculation ──
 import { getTakerFee } from "../constants.js";
-import { assertFundingArbVenue, getVenue, listVenuesWithRole, networkConfig, resolveVenueId, tryResolveVenueId } from "../exchanges/venue.js";
+import { assertFundingArbVenue, getVenue, listVenuesWithRole, networkConfig, resolveVenueId, roleUnsupported, tryResolveVenueId } from "../exchanges/venue.js";
 import { sharedApiNetwork } from "../api/public/urls.js";
 import { findSpotQuoteBalance, readSpotQuoteAvailableFresh, requireBotSpotVenue, requireSpotAdapter, spotNetworkOf, spotPairSymbol, spotSharesPerpMargin, sweepSpotQuoteToPerp, transferQuoteToPerp, transferQuoteToSpot } from "../exchanges/spot-factory.js";
 import { fillSizeString, readSpotBalancesFresh, sizeDecimalsOf, spotLotStepOf, spotMarketFill } from "../exchanges/spot-result.js";
@@ -821,7 +821,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                     if (stop.requested())
                         break; // stopping: no new close sequence
                     const pos = openPositions[i];
-                    // Quarantined (design §12.3): hands off until a human clears it.
+                    // Quarantined: hands off until a human clears it.
                     if (isQuarantined(pos.symbol, (m) => console.log(chalk.red(m))))
                         continue;
                     // Per-position isolation: one position's failing exit check (e.g. an
@@ -877,7 +877,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                                 try {
                                     const longAdapter = await getAdapterForExchange(pos.longExchange);
                                     const shortAdapter = await getAdapterForExchange(pos.shortExchange);
-                                    // Sequential, reduce-only, verified (design §12.3): long first, then
+                                    // Sequential, reduce-only, verified: long first, then
                                     // short. A definite long-close failure changes nothing → retried next
                                     // cycle, quarantined after MAX_PAIR_CLOSE_FAILURES in a row. An unknown
                                     // outcome, a partial close or an unhedged leg quarantines (no retry).
@@ -1114,7 +1114,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             skip(snap.symbol, "already open");
                             continue;
                         }
-                        // Global quarantine (design §12.3): unknown / unhedged outcome on this symbol somewhere.
+                        // Global quarantine: unknown / unhedged outcome on this symbol somewhere.
                         if (isQuarantined(snap.symbol, (m) => console.log(chalk.red(m)))) {
                             skip(snap.symbol, "quarantined");
                             continue;
@@ -1234,7 +1234,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             try {
                                 const longAdapter = await getAdapterForExchange(longExchange);
                                 const shortAdapter = await getAdapterForExchange(shortExchange);
-                                // Sequential verified legs (design §12.3): long, then short sized to the
+                                // Sequential verified legs: long, then short sized to the
                                 // long's verified fill; reduce-only rollback / trim; unknown → quarantine.
                                 legsStarted = true;
                                 const res = await openPerpPairVerified({
@@ -1445,7 +1445,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         .option("--duration <minutes>", "Track duration in minutes (with --track)", "10")
         .option("--beep", "Beep on large gaps (with --gaps)")
         .option("--check-liquidity", "Check orderbook depth in live mode (slower)")
-        .option("--include-unverified", "With --rates / --compare: also show venues whose funding rate is unverified (qfex) — display only, never ranked for trading")
+        .option("--include-unverified", "With --rates / --compare: also show venues whose funding rate is unverified (qfex; txflow — unofficial API; variational; grvt — indicative rate; extended) — display only, never ranked for trading")
         .action(async (opts) => {
         // ── Price gap modes ──
         if (opts.gaps || opts.track || opts.alert) {
@@ -1857,6 +1857,8 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         for (const ex of [longExch, shortExch]) {
             const venue = getVenue(ex);
             if (!venue.roles.includes("trading")) {
+                if (venue.gatedRoles !== null)
+                    throw roleUnsupported(venue, "trading");
                 throw unsupported(venue.displayName, "trading", "no trading API — it cannot be an arb leg", `Use a trading venue: ${listVenuesWithRole("trading").map(v => v.id).join(", ")}`);
             }
         }
@@ -1867,7 +1869,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
             console.log(chalk.red("  Long and short exchange must be different."));
             return;
         }
-        // Global quarantine (design §12.3): an unknown / unhedged outcome on this symbol
+        // Global quarantine: an unknown / unhedged outcome on this symbol
         // anywhere blocks new trades until a human clears it.
         const quarantined = quarantineEntryFor(sym, (m) => console.error(m));
         if (quarantined !== null) {
@@ -1875,7 +1877,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 remediation: `${quarantined.remediation} — then: perp strategy quarantine-clear ${sym}`,
             });
         }
-        // A venue whose funding rate is unverified is never a funding-arb leg (design §14.12 #6).
+        // A venue whose funding rate is unverified is never a funding-arb leg.
         assertFundingArbVenue(longExch);
         assertFundingArbVenue(shortExch);
         const longAdapter = await getAdapterForExchange(longExch);
@@ -1991,7 +1993,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         }
         if (!isJson())
             console.log(chalk.gray(`    Executing legs sequentially (long, then short sized to the verified long fill)...\n`));
-        // 5. Sequential verified legs (design §12.3). The second leg is sized to the
+        // 5. Sequential verified legs. The second leg is sized to the
         //    first leg's VERIFIED fill, any shortfall is trimmed off the long
         //    (reduce-only, verified — always, --reconcile is implied), a definite short
         //    failure rolls the long back reduce-only, and an unknown outcome (incl. a
@@ -2070,12 +2072,14 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // Resolve exchange aliases
         spotExch = resolveVenueId(spotExch);
         perpExch = resolveVenueId(perpExch);
-        // Validate spot exchange: bot/arb spot scope (§12.4 #3) — throws CAPABILITY_UNSUPPORTED
+        // Validate spot exchange: bot/arb spot scope — throws CAPABILITY_UNSUPPORTED
         // for venues without spot or outside the scope (pacifica shared margin, arcus swaps).
         const spotDef = requireBotSpotVenue(spotExch.replace(/-spot$/, ""));
         spotExch = spotDef.id;
         perpExch = tryResolveVenueId(perpExch) ?? perpExch;
         if (!getVenue(perpExch).roles.includes("trading")) {
+            if (getVenue(perpExch).gatedRoles !== null)
+                throw roleUnsupported(getVenue(perpExch), "trading");
             throw unsupported(perpExch, "trading", "no trading API — it cannot be the perp leg", `Use a trading venue: ${listVenuesWithRole("trading").map(v => v.id).join(", ")}`);
         }
         assertFundingArbVenue(perpExch);
@@ -2093,7 +2097,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 return;
             console.log(chalk.red(`  ${msg}`));
         };
-        // Global quarantine (design §12.3): checked before anything is read or moved.
+        // Global quarantine: checked before anything is read or moved.
         const quarantined = quarantineEntryFor(sym, (m) => console.error(m));
         if (quarantined !== null) {
             throw new PerpError("RISK_VIOLATION", `${sym} is quarantined (${quarantined.strategy}: ${quarantined.reason})`, {
@@ -2273,7 +2277,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // 7. Execute both legs. Same exchange shares a nonce → sequential; else parallel.
         if (!isJson())
             console.log(chalk.gray(`    Executing ${sameVenue ? "sequentially" : "both legs simultaneously"}...\n`));
-        // The perp leg goes through placePerpVerified (design §12.3): a fill is the measured
+        // The perp leg goes through placePerpVerified: a fill is the measured
         // position delta; an unknown outcome is ORDER_PENDING (quarantine, never roll back).
         let spotResult;
         let perpResult;
@@ -2523,7 +2527,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                 remediation: `Pass both: perp arb close ${sym} --spot-exch <spot venue> --perp-exch <perp venue>`,
             });
         }
-        // Load adapters (bot/arb spot scope — §12.4 #3)
+        // Load adapters (bot/arb spot scope)
         const spotDef = requireBotSpotVenue(spotExch.replace(/-spot$/, ""));
         const spotAdapter = await requireSpotAdapter(spotDef.id, await getAdapter(spotDef.id));
         const perpAdapter = await getAdapter(perpExch);
@@ -2551,12 +2555,12 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
         // Read before anything moves — a failure aborts the close.
         const preCloseQuote = await readSpotQuoteAvailableFresh(spotAdapter);
         // Same exchange → sequential (nonce collision), different → parallel.
-        // The spot leg's REAL fill decides the outcome (§12.4 #5): only a confirmed spot sale
+        // The spot leg's REAL fill decides the outcome: only a confirmed spot sale
         // counts as closed; legs are re-matched so no naked short / unhedged spot is left.
         const sameVenue = spotDef.id === (tryResolveVenueId(perpExch) ?? perpExch);
         const closeDec = sizeDecimalsOf(closeSize);
-        // The perp buy-back and every re-match order go through placePerpVerified (design
-        // §12.3): only a measured position change counts; an unknown outcome stops the close.
+        // The perp buy-back and every re-match order go through placePerpVerified:
+        // only a measured position change counts; an unknown outcome stops the close.
         let spotResult;
         let perpResult;
         if (sameVenue) {
@@ -3073,7 +3077,7 @@ export function registerArbAutoCommands(program, getAdapterForExchange, isJson,
                             (p.long.dex === pos.shortDex && p.short.dex === pos.longDex)));
                     const currentSpread = current?.annualSpread ?? 0;
                     if (currentSpread <= closeSpread || !current) {
-                        // Quarantined (design §12.3): hands off until a human clears it.
+                        // Quarantined: hands off until a human clears it.
                         if (isQuarantined(pos.underlying, (m) => console.error(chalk.red(m))))
                             continue;
                         const reason = !current ? "pair disappeared" : `spread ${currentSpread.toFixed(1)}% <= ${closeSpread}%`;

package/dist/commands/arb.d.ts

@@ -29,6 +29,18 @@ export declare function handleRates(isJson: () => boolean, opts: {
     top?: string;
     includeUnverified?: boolean;
 }): Promise<void>;
+/**
+ * Cross-venue price basis — a PRICE comparison, independent of funding.
+ *
+ * Venue scope: every venue with the "trading" role (both legs must be executable), whether or not
+ * its funding rate is verified; market-data-only venues (TxFlow, unofficial API) are out. Prices
+ * come from each venue's market directory and are grouped by `canonical` symbol with the funding
+ * scan's guards (fetchCanonicalPriceGroups): unclassified / ambiguous tickers have no canonical and
+ * never pair, and a venue whose mark deviates more than MAX_PRICE_DEVIATION_PCT from the group
+ * median is dropped. The chosen cheap / rich pair must itself agree within MAX_PRICE_DEVIATION_PCT:
+ * a wider gap is a different asset under the same ticker (BB on Lighter 8.50 vs Aster 0.0091).
+ * A venue that fails is reported on stderr and is absent from the scan, never silently empty.
+ */
 export declare function handleBasisScan(isJson: () => boolean, opts: {
     minBasis: string;
     symbol?: string;