perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/arcus/public.js

@@ -0,0 +1,138 @@
+/**
+ * Arcus public market data — GET /v1/markets (one call serves both markets
+ * and funding rates).
+ *
+ * Mapping notes:
+ * - symbol: `baseAsset` (plain ticker, e.g. "TSLA"); venueSymbol: display name
+ *   ("TSLA-USD") which is also the `market` key for l2OrderBook/trades/candles.
+ * - tickSize / stepSize: the top-level fields. `tickTiers` (per-price-band
+ *   placement grid) is NOT folded into VenueMarket — the signed integer price
+ *   always divides by the top-level tickSize; tiers only restrict which limit
+ *   prices are accepted. The adapter validates/aligns against the tier tick
+ *   (see tickForPrice) using the raw market.
+ * - maxLeverage: floor(1 / initialMarginFraction) (regular-hours IMF).
+ * - assetClass from `category`: CRYPTO → crypto, EQUITIES → equity,
+ *   FOREX → fx. COMMODITIES / INDICES listings on Arcus are ETFs (GLD, SLV,
+ *   USO, CPER, SPY, QQQ …) → "etf" when `fullAssetName` names an ETF/Trust/
+ *   Fund/Shares; otherwise commodity / index (canonical then comes only from the
+ *   explicit table).
+ * - session: only for markets with `regularTradingHours` (24/7 crypto → null).
+ *   underlyingOpen = !isOutsideRth; priceBand = off-hours trading bounds when
+ *   published; marginMultiplier = offHoursIMF / IMF.
+ * - funding: hourly (`fundingRate` is the per-hour fraction last charged);
+ *   `nextFundingAt` is Unix seconds.
+ * - tradable: status === "ONLINE".
+ */
+import { PerpError } from "../../errors.js";
+import { canonicalFor } from "../canonical-symbols.js";
+import { arcusVenue } from "../venues/arcus.js";
+import { ArcusClient } from "./client.js";
+const FUNDING_BASIS = { kind: "perHours", hours: 1 };
+export async function fetchArcusRawMarkets(client) {
+    const res = await client.get("/v1/markets", "markets");
+    if (!res || !Array.isArray(res.markets)) {
+        throw new PerpError("EXCHANGE_ERROR", "Arcus /v1/markets: missing markets array");
+    }
+    return res.markets;
+}
+/** Fund-style names seen on Arcus COMMODITIES/INDICES listings (GLD "SPDR Gold Shares", SLV "iShares Silver Trust", USO/CPER "… Fund", SPY "SPDR S&P 500 ETF Trust"). */
+const ETF_NAME = /\b(ETF|Trust|Fund|Shares|iShares|SPDR)\b/i;
+export function arcusAssetClass(m) {
+    switch (m.category) {
+        case "CRYPTO": return "crypto";
+        case "EQUITIES": return "equity";
+        case "FOREX": return "fx";
+        case "COMMODITIES": return m.fullAssetName && ETF_NAME.test(m.fullAssetName) ? "etf" : "commodity";
+        case "INDICES": return m.fullAssetName && ETF_NAME.test(m.fullAssetName) ? "etf" : "index";
+        default:
+            throw new PerpError("EXCHANGE_ERROR", `Arcus market ${m.marketDisplayName}: unknown category "${m.category}"`);
+    }
+}
+function numOrNull(s) {
+    return typeof s === "string" && s.length > 0 && Number.isFinite(Number(s)) ? s : null;
+}
+function maxLeverageOf(m) {
+    const imf = Number(m.initialMarginFraction);
+    if (!(imf > 0)) {
+        throw new PerpError("EXCHANGE_ERROR", `Arcus market ${m.marketDisplayName}: invalid initialMarginFraction "${m.initialMarginFraction}"`);
+    }
+    // 1/0.025 is exactly 40 in binary FP for current markets; epsilon guards 1/0.1-style drift.
+    return Math.floor(1 / imf + 1e-9);
+}
+function sessionOf(m) {
+    if (m.regularTradingHours === null || m.regularTradingHours === undefined)
+        return null;
+    const lower = numOrNull(m.lowerTradingBound);
+    const upper = numOrNull(m.upperTradingBound);
+    const imf = Number(m.initialMarginFraction);
+    const offImf = Number(m.offHoursInitialMarginFraction);
+    return {
+        underlyingOpen: !m.isOutsideRth,
+        priceBand: lower !== null && upper !== null ? { lower, upper } : null,
+        // Rounded to 6 dp to drop binary-FP noise (0.0375/0.025 → 1.4999999999999998).
+        marginMultiplier: imf > 0 && offImf > 0 ? Math.round((offImf / imf) * 1e6) / 1e6 : null,
+    };
+}
+export function toArcusVenueMarket(m) {
+    const assetClass = arcusAssetClass(m);
+    const mark = numOrNull(m.markPrice);
+    if (mark === null) {
+        throw new PerpError("EXCHANGE_ERROR", `Arcus market ${m.marketDisplayName}: missing markPrice`);
+    }
+    return {
+        venue: "arcus",
+        venueSymbol: m.marketDisplayName,
+        symbol: m.baseAsset,
+        canonical: canonicalFor("arcus", m.baseAsset, assetClass),
+        assetClass,
+        settle: arcusVenue.networks.mainnet.collateral[0],
+        quoteAsset: m.quoteAsset,
+        markPrice: mark,
+        indexPrice: numOrNull(m.oraclePrice),
+        fundingRate: numOrNull(m.fundingRate),
+        fundingRateBasis: FUNDING_BASIS,
+        settlementIntervalHours: 1,
+        openInterest: numOrNull(m.openInterest),
+        volume24h: numOrNull(m.volume24hNotional),
+        tickSize: m.tickSize,
+        stepSize: m.stepSize,
+        minSize: numOrNull(m.minOrderSize),
+        minNotional: numOrNull(m.minOrderNotional),
+        maxLeverage: maxLeverageOf(m),
+        marginTiers: null,
+        session: sessionOf(m),
+        tradable: m.status === "ONLINE",
+    };
+}
+async function fetchMarkets(net) {
+    const raw = await fetchArcusRawMarkets(new ArcusClient(net, null));
+    return raw.map(toArcusVenueMarket);
+}
+async function fetchFundingRates(net) {
+    const raw = await fetchArcusRawMarkets(new ArcusClient(net, null));
+    const out = [];
+    const missing = [];
+    for (const m of raw) {
+        const rate = numOrNull(m.fundingRate);
+        if (rate === null) {
+            missing.push(m.marketDisplayName);
+            continue;
+        }
+        const assetClass = arcusAssetClass(m);
+        out.push({
+            venue: "arcus",
+            venueSymbol: m.marketDisplayName,
+            symbol: m.baseAsset,
+            canonical: canonicalFor("arcus", m.baseAsset, assetClass),
+            rate,
+            basis: FUNDING_BASIS,
+            markPrice: numOrNull(m.markPrice),
+            nextFundingTime: typeof m.nextFundingAt === "number" ? m.nextFundingAt * 1000 : null,
+        });
+    }
+    if (missing.length > 0) {
+        console.warn(`[arcus] excluded ${missing.length} market(s) without a published funding rate: ${missing.join(", ")}`);
+    }
+    return out;
+}
+export const arcusPublicData = { fetchMarkets, fetchFundingRates };

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

@@ -0,0 +1,176 @@
+/**
+ * Arcus request signing (docs.arcus.xyz/api-reference/authentication).
+ *
+ * Two Ed25519 schemes, both signed by the agent API key:
+ * - Scheme 1 (typed payload): placeOrder / cancelOrder / modifyOrder and every
+ *   element of batchPlaceOrders / batchCancelOrders. The signed bytes are a
+ *   compact, key-sorted JSON object of engine-native integers:
+ *     place  (op 1, op 4 = untriggered TPSL leg):
+ *       {"ad","ai"[,"c"],"ct","g","m","op","p","q","r","s","t","v"}
+ *     cancel (op 2): {"ad","ai"[,"c"],"ct"[,"id"],"m","op","v"}  (exactly one of id / c)
+ *     modify (op 3): {"ad","ai"[,"c"],"ct","g"[,"id"],"m","op","p","q","r","s","t","v"}
+ *       identity per ARCUS_MODIFY_SIGNED_IDENTITY (UNVERIFIED — see below)
+ * - Scheme 2 (legacy message): cancelAllOrders, setLeverage (and, by the docs'
+ *   "everything else" rule, scheduleCancel — unverified):
+ *     ed25519(timestampNs + action + canonicalJson(body))
+ *
+ * Time units (design §10.10): `ct` and X-Timestamp are Unix NANOseconds;
+ * signed `g` is NANOseconds; the request body `goodTilTime` is a MICROsecond
+ * decimal string (g = goodTilTime × 1000).
+ *
+ * Master-wallet operations (createApiKey / revokeApiKey / withdraw / transfer)
+ * are secp256k1 EIP-712 typed data; builders for those live at the bottom.
+ */
+/** Raw Ed25519 detached signer (OWS agent wallet or tweetnacl). No prefixing. */
+export type Ed25519SignFn = (message: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Compact JSON with keys sorted (recursively), no whitespace. `bigint` values
+ * are emitted as unquoted integers (engine-native ticks / quantums / ns).
+ */
+export declare function canonicalJson(value: unknown): string;
+export declare const ARCUS_SIDE: {
+    readonly buy: 0;
+    readonly sell: 1;
+};
+/** Signed TIF codes: 0 GTT, 1 FOK, 2 IOC, 3 ALO. */
+export declare const ARCUS_TIF_CODE: {
+    readonly GTT: 0;
+    readonly FOK: 1;
+    readonly IOC: 2;
+    readonly ALO: 3;
+};
+export type ArcusTif = keyof typeof ARCUS_TIF_CODE;
+export declare const ARCUS_OP: {
+    readonly place: 1;
+    readonly cancel: 2;
+    readonly modify: 3;
+    readonly placeUntriggered: 4;
+    readonly withdraw: 5;
+};
+export declare function assertArcusClientId(c: string): void;
+export interface ArcusPlaceFields {
+    /** Master EVM address (lowercased when signing). */
+    address: string;
+    accountIndex: number;
+    clientId: string | null;
+    /** X-Timestamp, ns. */
+    ctNs: bigint;
+    /** goodTilTime, ns (= body µs × 1000). */
+    goodTilNs: bigint;
+    marketId: number;
+    /** price ÷ top-level market tickSize (exact). */
+    priceTicks: bigint;
+    /** size ÷ stepSize (exact). */
+    quantums: bigint;
+    reduceOnly: boolean;
+    side: "buy" | "sell";
+    tif: ArcusTif;
+}
+/** op 1 (plain order) or op 4 (TPSL / untriggered leg inside a batch grouping). */
+export declare function placePayload(f: ArcusPlaceFields, untriggered: boolean): string;
+/**
+ * Which order identity the signed modify payload (op 3) carries.
+ *
+ * UNVERIFIED — the Arcus docs contradict each other:
+ *  - openapi.yml (info.description) and the modify-order page: modifyOrder payload
+ *    `…"g":N,[,"id":"…"],"m":N…  (exactly one of id / c)` — the request body also takes
+ *    exactly one of orderId / clientId;
+ *  - authentication page: always `id`, plus `c` "only if the resting order was placed
+ *    with a client id … the engine rejects a mismatch".
+ * Default follows the openapi spec ("idOnly": sign `id`, never `c`; the body sends
+ * orderId only). "idAndClientId" is the authentication-page variant. Settled by the
+ * docs/TEST-PLAN.md step "Arcus modify signature identity" on testnet.
+ */
+export type ArcusModifyIdentity = "idOnly" | "idAndClientId";
+export declare const ARCUS_MODIFY_SIGNED_IDENTITY: ArcusModifyIdentity;
+/** op 3. Signs `id`; echoes the resting order's `c` only in the "idAndClientId" variant. */
+export declare function modifyPayload(f: ArcusPlaceFields, orderId: string, identity?: ArcusModifyIdentity): string;
+export interface ArcusCancelFields {
+    address: string;
+    accountIndex: number;
+    ctNs: bigint;
+    marketId: number;
+    ref: {
+        kind: "orderId";
+        value: string;
+    } | {
+        kind: "clientOrderId";
+        value: string;
+    };
+}
+/** op 2 — exactly one of `id` (server order id) or `c` (client id). */
+export declare function cancelPayload(f: ArcusCancelFields): string;
+/** op 5 — API-key withdraw (only for keys provisioned with the `withdraw` permission). */
+export declare function withdrawPayload(f: {
+    address: string;
+    accountIndex: number;
+    ctNs: bigint;
+    nonce: string;
+    amountQuantums: bigint;
+}): string;
+/** `ts + action + canonicalJson(body)`, no delimiters. The same canonical body string must be sent as the HTTP body. */
+export declare function scheme2Message(tsNs: bigint, action: string, canonicalBody: string): string;
+export declare function signUtf8Hex(sign: Ed25519SignFn, message: string): Promise<string>;
+/**
+ * Unix time in nanoseconds (ms × 1e6), strictly increasing within the process
+ * so two requests in the same millisecond never share a `ct` replay slot.
+ */
+export declare function nowNs(): bigint;
+export type Eip712Types = Record<string, Array<{
+    name: string;
+    type: string;
+}>>;
+export interface ArcusTypedData {
+    domain: Record<string, unknown>;
+    /** Contains ONLY the primary type (OwsEvmSigner takes the first key as primaryType). */
+    types: Eip712Types;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/** BridgeVault (withdraw / transfer verifyingContract) per signing chain id. */
+export declare const ARCUS_BRIDGE_VAULT: Readonly<Record<number, `0x${string}`>>;
+/**
+ * createApiKey typed data. Always uses the accountIndex-bearing type (valid for
+ * every index, mandatory for 1–9/255); with a nonce, the combined type.
+ */
+export declare function createApiKeyTypedData(p: {
+    chainId: number;
+    apiWalletName: string;
+    publicKeyHex: string;
+    validUntilMs: number;
+    accountIndex: number;
+    nonce: string | null;
+}): ArcusTypedData;
+/** revokeApiKey typed data (no validUntil). */
+export declare function revokeApiKeyTypedData(p: {
+    chainId: number;
+    apiWalletName: string;
+    publicKeyHex: string;
+    accountIndex: number;
+    nonce: string | null;
+}): ArcusTypedData;
+/** Withdraw-to-self typed data. `amountQuantums`: quote quantums (1e9 = $1), sent as a decimal string. */
+export declare function withdrawTypedData(p: {
+    chainId: number;
+    ethereumAddress: string;
+    accountIndex: number;
+    amountQuantums: bigint;
+    nonce: string;
+}): ArcusTypedData;
+/** Internal subaccount transfer typed data. */
+export declare function transferTypedData(p: {
+    chainId: number;
+    ethereumAddress: string;
+    fromAccountIndex: number;
+    toAccountIndex: number;
+    amountQuantums: bigint;
+    nonce: string;
+}): ArcusTypedData;
+/** Split a 65-byte 0x-hex signature into Arcus `{r, s, v}` with v ∈ {0x1b, 0x1c}. */
+export declare function splitEvmSignature(sig: string): {
+    r: string;
+    s: string;
+    v: string;
+};
+/** 1 quote quantum = 1e-9 USDG. */
+export declare const QUOTE_QUANTUM = "0.000000001";

package/dist/exchanges/arcus/signing.js

@@ -0,0 +1,288 @@
+/**
+ * Arcus request signing (docs.arcus.xyz/api-reference/authentication).
+ *
+ * Two Ed25519 schemes, both signed by the agent API key:
+ * - Scheme 1 (typed payload): placeOrder / cancelOrder / modifyOrder and every
+ *   element of batchPlaceOrders / batchCancelOrders. The signed bytes are a
+ *   compact, key-sorted JSON object of engine-native integers:
+ *     place  (op 1, op 4 = untriggered TPSL leg):
+ *       {"ad","ai"[,"c"],"ct","g","m","op","p","q","r","s","t","v"}
+ *     cancel (op 2): {"ad","ai"[,"c"],"ct"[,"id"],"m","op","v"}  (exactly one of id / c)
+ *     modify (op 3): {"ad","ai"[,"c"],"ct","g"[,"id"],"m","op","p","q","r","s","t","v"}
+ *       identity per ARCUS_MODIFY_SIGNED_IDENTITY (UNVERIFIED — see below)
+ * - Scheme 2 (legacy message): cancelAllOrders, setLeverage (and, by the docs'
+ *   "everything else" rule, scheduleCancel — unverified):
+ *     ed25519(timestampNs + action + canonicalJson(body))
+ *
+ * Time units (design §10.10): `ct` and X-Timestamp are Unix NANOseconds;
+ * signed `g` is NANOseconds; the request body `goodTilTime` is a MICROsecond
+ * decimal string (g = goodTilTime × 1000).
+ *
+ * Master-wallet operations (createApiKey / revokeApiKey / withdraw / transfer)
+ * are secp256k1 EIP-712 typed data; builders for those live at the bottom.
+ */
+import { PerpError } from "../../errors.js";
+// ── Canonical JSON ──
+/**
+ * Compact JSON with keys sorted (recursively), no whitespace. `bigint` values
+ * are emitted as unquoted integers (engine-native ticks / quantums / ns).
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "bigint":
+            return value.toString();
+        case "number":
+            if (!Number.isFinite(value))
+                throw new Error(`canonicalJson: non-finite number ${value}`);
+            return JSON.stringify(value);
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "object": {
+            if (Array.isArray(value))
+                return `[${value.map(canonicalJson).join(",")}]`;
+            const obj = value;
+            const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();
+            return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+        }
+        default:
+            throw new Error(`canonicalJson: unsupported type ${typeof value}`);
+    }
+}
+// ── Scheme 1 enums ──
+export const ARCUS_SIDE = { buy: 0, sell: 1 };
+/** Signed TIF codes: 0 GTT, 1 FOK, 2 IOC, 3 ALO. */
+export const ARCUS_TIF_CODE = { GTT: 0, FOK: 1, IOC: 2, ALO: 3 };
+export const ARCUS_OP = { place: 1, cancel: 2, modify: 3, placeUntriggered: 4, withdraw: 5 };
+/** Payload version (`v`). */
+const PAYLOAD_VERSION = 1;
+/** clientId charset per docs: [A-Za-z0-9_-], 1–36 chars. Signed verbatim. */
+const CLIENT_ID_RE = /^[A-Za-z0-9_-]{1,36}$/;
+export function assertArcusClientId(c) {
+    if (!CLIENT_ID_RE.test(c)) {
+        throw new PerpError("INVALID_PARAMS", `Arcus clientId "${c}" must match [A-Za-z0-9_-]{1,36}`);
+    }
+}
+function lowerAddress(ad) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(ad))
+        throw new PerpError("INVALID_PARAMS", `Invalid Arcus master address "${ad}"`);
+    return ad.toLowerCase();
+}
+function placeLikeObject(op, f, orderId) {
+    if (f.clientId !== null)
+        assertArcusClientId(f.clientId);
+    return {
+        ad: lowerAddress(f.address),
+        ai: f.accountIndex,
+        c: f.clientId ?? undefined, // omitted entirely when absent
+        ct: f.ctNs,
+        g: f.goodTilNs,
+        id: orderId ?? undefined,
+        m: f.marketId,
+        op,
+        p: f.priceTicks,
+        q: f.quantums,
+        r: f.reduceOnly ? 1 : 0,
+        s: ARCUS_SIDE[f.side],
+        t: ARCUS_TIF_CODE[f.tif],
+        v: PAYLOAD_VERSION,
+    };
+}
+/** op 1 (plain order) or op 4 (TPSL / untriggered leg inside a batch grouping). */
+export function placePayload(f, untriggered) {
+    return canonicalJson(placeLikeObject(untriggered ? ARCUS_OP.placeUntriggered : ARCUS_OP.place, f, null));
+}
+export const ARCUS_MODIFY_SIGNED_IDENTITY = "idOnly";
+/** op 3. Signs `id`; echoes the resting order's `c` only in the "idAndClientId" variant. */
+export function modifyPayload(f, orderId, identity = ARCUS_MODIFY_SIGNED_IDENTITY) {
+    if (orderId.length === 0)
+        throw new PerpError("INVALID_PARAMS", "Arcus modifyOrder requires the server orderId");
+    const fields = identity === "idOnly" ? { ...f, clientId: null } : f;
+    return canonicalJson(placeLikeObject(ARCUS_OP.modify, fields, orderId));
+}
+/** op 2 — exactly one of `id` (server order id) or `c` (client id). */
+export function cancelPayload(f) {
+    if (f.ref.kind === "clientOrderId")
+        assertArcusClientId(f.ref.value);
+    return canonicalJson({
+        ad: lowerAddress(f.address),
+        ai: f.accountIndex,
+        c: f.ref.kind === "clientOrderId" ? f.ref.value : undefined,
+        ct: f.ctNs,
+        id: f.ref.kind === "orderId" ? f.ref.value : undefined,
+        m: f.marketId,
+        op: ARCUS_OP.cancel,
+        v: PAYLOAD_VERSION,
+    });
+}
+/** op 5 — API-key withdraw (only for keys provisioned with the `withdraw` permission). */
+export function withdrawPayload(f) {
+    return canonicalJson({
+        ad: lowerAddress(f.address),
+        ai: f.accountIndex,
+        ct: f.ctNs,
+        n: f.nonce,
+        op: ARCUS_OP.withdraw,
+        q: f.amountQuantums,
+        v: PAYLOAD_VERSION,
+    });
+}
+// ── Scheme 2 ──
+/** `ts + action + canonicalJson(body)`, no delimiters. The same canonical body string must be sent as the HTTP body. */
+export function scheme2Message(tsNs, action, canonicalBody) {
+    return `${tsNs.toString()}${action}${canonicalBody}`;
+}
+// ── Ed25519 helpers ──
+export async function signUtf8Hex(sign, message) {
+    const sig = await sign(new TextEncoder().encode(message));
+    if (sig.length !== 64) {
+        throw new PerpError("SIGNATURE_FAILED", `Arcus: Ed25519 signature must be 64 bytes (got ${sig.length})`);
+    }
+    return Buffer.from(sig).toString("hex");
+}
+let lastNs = 0n;
+/**
+ * Unix time in nanoseconds (ms × 1e6), strictly increasing within the process
+ * so two requests in the same millisecond never share a `ct` replay slot.
+ */
+export function nowNs() {
+    let t = BigInt(Date.now()) * 1000000n;
+    if (t <= lastNs)
+        t = lastNs + 1n;
+    lastNs = t;
+    return t;
+}
+/** BridgeVault (withdraw / transfer verifyingContract) per signing chain id. */
+export const ARCUS_BRIDGE_VAULT = {
+    4663: "0x14b107cf534239c59571b066cb6497a321da897c",
+    46630: "0x9a6d3499149fea853efe775a3577701539054eaf",
+};
+function bridgeVault(chainId) {
+    const v = ARCUS_BRIDGE_VAULT[chainId];
+    if (!v)
+        throw new PerpError("INVALID_PARAMS", `No Arcus BridgeVault known for chainId ${chainId}`);
+    return v;
+}
+function apiKeyDomain(chainId) {
+    // No verifyingContract (docs: API keys are pure off-chain auth).
+    return { name: "Arcus API Key", version: "1", chainId };
+}
+function assertApiKeyAccountIndex(i) {
+    if (!(Number.isInteger(i) && ((i >= 0 && i <= 9) || i === 255))) {
+        throw new PerpError("INVALID_PARAMS", `Arcus API key accountIndex must be 0–9 or 255 (got ${i})`);
+    }
+}
+function assertPubHex(h) {
+    if (!/^[0-9a-f]{64}$/.test(h))
+        throw new PerpError("INVALID_PARAMS", `Arcus API key must be 64 lowercase hex chars`);
+}
+/**
+ * createApiKey typed data. Always uses the accountIndex-bearing type (valid for
+ * every index, mandatory for 1–9/255); with a nonce, the combined type.
+ */
+export function createApiKeyTypedData(p) {
+    assertApiKeyAccountIndex(p.accountIndex);
+    assertPubHex(p.publicKeyHex);
+    const fields = [
+        { name: "apiWalletName", type: "string" },
+        { name: "apiWalletPublicKey", type: "string" },
+        { name: "validUntil", type: "uint256" },
+        ...(p.nonce !== null ? [{ name: "nonce", type: "string" }] : []),
+        { name: "accountIndex", type: "uint8" },
+    ];
+    return {
+        domain: apiKeyDomain(p.chainId),
+        types: { CreateApiKey: fields },
+        primaryType: "CreateApiKey",
+        message: {
+            apiWalletName: p.apiWalletName,
+            apiWalletPublicKey: p.publicKeyHex,
+            validUntil: p.validUntilMs,
+            ...(p.nonce !== null ? { nonce: p.nonce } : {}),
+            accountIndex: p.accountIndex,
+        },
+    };
+}
+/** revokeApiKey typed data (no validUntil). */
+export function revokeApiKeyTypedData(p) {
+    assertApiKeyAccountIndex(p.accountIndex);
+    assertPubHex(p.publicKeyHex);
+    const fields = [
+        { name: "apiWalletName", type: "string" },
+        { name: "apiWalletPublicKey", type: "string" },
+        ...(p.nonce !== null ? [{ name: "nonce", type: "string" }] : []),
+        { name: "accountIndex", type: "uint8" },
+    ];
+    return {
+        domain: apiKeyDomain(p.chainId),
+        types: { RevokeApiKey: fields },
+        primaryType: "RevokeApiKey",
+        message: {
+            apiWalletName: p.apiWalletName,
+            apiWalletPublicKey: p.publicKeyHex,
+            ...(p.nonce !== null ? { nonce: p.nonce } : {}),
+            accountIndex: p.accountIndex,
+        },
+    };
+}
+/** Withdraw-to-self typed data. `amountQuantums`: quote quantums (1e9 = $1), sent as a decimal string. */
+export function withdrawTypedData(p) {
+    return {
+        domain: { name: "Arcus Withdraw", version: "1", chainId: p.chainId, verifyingContract: bridgeVault(p.chainId) },
+        types: {
+            Withdraw: [
+                { name: "ethereumAddress", type: "address" },
+                { name: "accountIndex", type: "uint8" },
+                { name: "amount", type: "uint256" },
+                { name: "nonce", type: "string" },
+            ],
+        },
+        primaryType: "Withdraw",
+        message: {
+            ethereumAddress: p.ethereumAddress,
+            accountIndex: p.accountIndex,
+            amount: p.amountQuantums.toString(),
+            nonce: p.nonce,
+        },
+    };
+}
+/** Internal subaccount transfer typed data. */
+export function transferTypedData(p) {
+    return {
+        domain: { name: "Arcus Transfer", version: "1", chainId: p.chainId, verifyingContract: bridgeVault(p.chainId) },
+        types: {
+            Transfer: [
+                { name: "ethereumAddress", type: "address" },
+                { name: "fromAccountIndex", type: "uint8" },
+                { name: "toAccountIndex", type: "uint8" },
+                { name: "amount", type: "uint256" },
+                { name: "nonce", type: "string" },
+            ],
+        },
+        primaryType: "Transfer",
+        message: {
+            ethereumAddress: p.ethereumAddress,
+            fromAccountIndex: p.fromAccountIndex,
+            toAccountIndex: p.toAccountIndex,
+            amount: p.amountQuantums.toString(),
+            nonce: p.nonce,
+        },
+    };
+}
+/** Split a 65-byte 0x-hex signature into Arcus `{r, s, v}` with v ∈ {0x1b, 0x1c}. */
+export function splitEvmSignature(sig) {
+    const hex = sig.startsWith("0x") ? sig.slice(2) : sig;
+    if (hex.length !== 130) {
+        throw new PerpError("SIGNATURE_FAILED", `Arcus: expected a 65-byte EVM signature (got ${hex.length / 2} bytes)`);
+    }
+    let v = parseInt(hex.slice(128, 130), 16);
+    if (v === 0 || v === 1)
+        v += 27;
+    if (v !== 27 && v !== 28)
+        throw new PerpError("SIGNATURE_FAILED", `Arcus: unexpected signature v=${v}`);
+    return { r: `0x${hex.slice(0, 64)}`, s: `0x${hex.slice(64, 128)}`, v: `0x${v.toString(16)}` };
+}
+/** 1 quote quantum = 1e-9 USDG. */
+export const QUOTE_QUANTUM = "0.000000001";

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

@@ -0,0 +1,60 @@
+/**
+ * Robinhood Chain reads/txs for Arcus spot (design §12.4 #7), over
+ * `VenueNetworkConfig.rpcUrl` with ethers.
+ *
+ * Permit2 allowance logic ported from @arcus-xyz/arcus-spot-sdk@1.0.2
+ * (src/permits.ts) — Copyright Arcus, Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0). Changes: viem → ethers; the
+ * SDK's last-resort EIP-2612 domain guess (`version() ?? "1"` without a
+ * DOMAIN_SEPARATOR match) is replaced by an error (SSOT Rule #2).
+ */
+import { JsonRpcProvider, Transaction } from "ethers";
+/** Approve receipt wait. */
+export declare const ARCUS_APPROVE_RECEIPT_TIMEOUT_MS = 120000;
+export declare const MAX_UINT256: bigint;
+export interface TokenTransfer {
+    token: string;
+    from: string;
+    to: string;
+    amount: bigint;
+}
+export declare class ArcusSpotChain {
+    readonly rpcUrl: string;
+    readonly chainId: number;
+    readonly provider: JsonRpcProvider;
+    private chainChecked;
+    constructor(rpcUrl: string, chainId: number);
+    /** Fails if the RPC serves a different chain than the venue's signing chain. */
+    ready(): Promise<void>;
+    private call;
+    nativeBalance(owner: string): Promise<bigint>;
+    /**
+     * balanceOf(owner) for each token via Multicall3. Returns null for a target
+     * that answered with no data (no contract deployed — e.g. a wrapped token the
+     * factory has not created yet); a reverted call throws.
+     */
+    erc20Balances(owner: string, tokens: string[]): Promise<Array<bigint | null>>;
+    permit2Allowance(token: string, owner: string): Promise<bigint>;
+    /** EIP-2612 nonce, or null when the token has no `nonces()` (not EIP-2612 → approve tx needed). */
+    eip2612Nonce(token: string, owner: string): Promise<bigint | null>;
+    /**
+     * EIP-712 domain the token verifies permits with: EIP-5267 `eip712Domain()`,
+     * else a `version()` / "1" / "2" candidate that reproduces DOMAIN_SEPARATOR().
+     * Nothing verifiable → throws (no guessing).
+     */
+    eip2612Domain(token: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Send `approve(Permit2, MAX_UINT256)` from `owner`, signed via `signTx`
+     * (master key), after checking the native ETH balance covers
+     * gasLimit × maxFeePerGas. Waits for a successful receipt.
+     */
+    approvePermit2(token: string, owner: string, signTx: (tx: Transaction) => Promise<string>): Promise<string>;
+    /** ERC-20 Transfer logs in a mined tx (null when the RPC has no receipt for it). */
+    transfersIn(txHash: string): Promise<{
+        status: number | null;
+        transfers: TokenTransfer[];
+    } | null>;
+}