perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/arcus/spot.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Arcus spot = Stock Token swaps through the Arcus Spot Router (design §12,
+ * §12.4 #5 #7). Not an exchange account: balances are the master wallet's
+ * ERC-20 balances on Robinhood Chain, and every trade is an exact-input swap
+ * settled on-chain (Permit2 `PermitWitnessTransferFrom` + `TakerIntent`).
+ *
+ * - Markets: every `/tokens` entry vs USDG ("BASE/USDG"); wire = token address.
+ * - Orderbook / limit / cancel: CAPABILITY_UNSUPPORTED (router has no book, nothing rests).
+ * - Signer: master EVM key (OWS --wallet or pk) from ArcusAdapter; absent → NO_SIGNER_AVAILABLE.
+ * - allowWrapped=false is requested and verified in the signed intent.
+ * - Permit2 allowance: EIP-2612 permit when the token supports it, else an
+ *   on-chain approve tx that requires `confirmOnchainApprove` and RH ETH for gas.
+ *
+ * Signing/submit flow ported from @arcus-xyz/arcus-spot-sdk@1.0.2
+ * (src/signing.ts) — Copyright Arcus, Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ */
+import type { ResolvedSlippage } from "../slippage.js";
+import type { SpotAdapter, SpotBalance, SpotMarketInfo, SpotOrderResult, SpotPricesCapable } from "../spot-interface.js";
+import type { ArcusAdapter } from "./adapter.js";
+/** /status polling: total wait before returning finality "pending". */
+export declare const ARCUS_SPOT_STATUS_TIMEOUT_MS = 90000;
+export interface ArcusSpotOptions {
+    /** Allow sending the one-time on-chain `approve(Permit2)` tx (CLI: --yes). */
+    confirmOnchainApprove: boolean;
+}
+export declare class ArcusSpotAdapter implements SpotAdapter, SpotPricesCapable {
+    readonly name = "arcus";
+    private readonly perp;
+    private opts;
+    private readonly router;
+    private readonly chain;
+    /** upper-case symbol → token (native ETH sentinel excluded) */
+    private tokens;
+    private usdg;
+    /** opts default refuses the approve tx; the CLI enables it per invocation (--yes) via setConfirmOnchainApprove. */
+    constructor(perp: ArcusAdapter, opts?: ArcusSpotOptions);
+    /** CLI --yes: allow the one-time on-chain approve(Permit2) tx. */
+    setConfirmOnchainApprove(confirm: boolean): void;
+    /** Loads the router's live token list (the canonical market universe). */
+    init(): Promise<void>;
+    private quoteToken;
+    /** bare base or "BASE/USDG" → router token. */
+    private resolve;
+    private bestEntry;
+    /**
+     * markPrice = all-in indicative price of a MARK_PROBE_USDG buy (/price,
+     * USDG sellAmount ÷ net buyAmount, fees included) — the router has no mark.
+     * volume24h = null: the router publishes no volume. Tokens the router
+     * cannot route at the probe size (422 NO_QUOTES / below-minimum codes) are
+     * omitted and listed on stderr; any other error propagates.
+     */
+    getSpotMarkets(): Promise<SpotMarketInfo[]>;
+    /**
+     * SpotPricesCapable: markets (same pricing as getSpotMarkets) for the given base
+     * tokens only — one /price call per token, for valuing wallet holdings without
+     * pricing the whole universe. Tokens the router does not list (native ETH, wrapped
+     * placeholders) are not returned; the caller reports them as unpriced.
+     */
+    getSpotPrices(tokens: readonly string[]): Promise<SpotMarketInfo[]>;
+    private priceMarkets;
+    getSpotOrderbook(_symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    /**
+     * Wallet balances on Robinhood Chain: native ETH, USDG, and every /tokens
+     * token (plus its wrapped placeholder) with a non-zero balance. Wrapped
+     * placeholders are reported as "<SYMBOL>(wrapped)" — awaiting maker
+     * settlement, non-transferable. shared:false (not perp collateral).
+     */
+    getSpotBalances(): Promise<SpotBalance[]>;
+    /**
+     * Market swap. `size` is in BASE units for both sides.
+     * - sell: exact-input `size` BASE → USDG.
+     * - buy: the router is exact-input only, so `size` BASE is converted to a
+     *   USDG sellAmount: V = USDG out for selling `size` (/price), B = BASE out
+     *   for selling V USDG (/price), sellAmount = ceil(size × V / B) — the
+     *   all-in buy price at that notional. The signed intent must then carry
+     *   minBuyAmount ≥ size × (1 − slippageBps), else nothing is signed.
+     * Both sides also require minBuyAmount ≥ quote.buyAmount × (1 − slippageBps).
+     * slippageBps = the caller's resolveSlippage() value (design §13.2); the router
+     * takes an integer bound.
+     */
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        slippage: ResolvedSlippage;
+    }): Promise<SpotOrderResult>;
+    private swap;
+    /** Submitted-but-unconfirmed result: never a throw, always "do NOT resubmit". */
+    private pendingResult;
+    private verifyIntent;
+    /**
+     * Ensure the taker's sellToken→Permit2 allowance covers `amount`
+     * (SDK buildArcusSellTokenPermitIfNeeded): none needed → []; EIP-2612 token →
+     * one signed permit; otherwise an approve tx, only when confirmOnchainApprove.
+     */
+    private ensurePermit2Allowance;
+    private submitError;
+    /**
+     * Poll /status until confirmed/failed or ARCUS_SPOT_STATUS_TIMEOUT_MS; fills come from the
+     * receipt's Transfer logs. Any inconsistency returns "pending" (never throws for a bad
+     * outcome — the caller also converts thrown poll/RPC errors into "pending").
+     */
+    private awaitFinal;
+    spotLimitOrder(_symbol: string, _side: "buy" | "sell", _price: string, _size: string, _opts?: {
+        tif?: string;
+    }): Promise<unknown>;
+    spotCancelOrder(_symbol: string, _orderId: string): Promise<unknown>;
+}