@raintree-technology/perps 0.1.0

package/dist/lib/onboarding.js

@@ -0,0 +1,1459 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Ed25519Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";
+import { KeyPair } from "near-api-js";
+import { ec, shortString, typedData as starkTypedData } from "starknet";
+import { hashTypedData, hexToBytes } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { ONBOARDING_STATE_DIR } from "./paths.js";
+import { ensurePrivateDir, hardenPrivateFile, PRIVATE_FILE_MODE } from "./fs-security.js";
+import { recordTelemetryMetric } from "./telemetry.js";
+export const ALL_SETUP_CHAINS = ["evm", "aptos", "starknet"];
+export const ALL_SETUP_EXCHANGES = [
+    "hyperliquid",
+    "decibel",
+    "aevo",
+    "orderly",
+    "paradex",
+];
+export const SETUP_MODES = ["mainnet-data", "testnet-execution", "both"];
+const CHAIN_EXCHANGES = {
+    evm: ["hyperliquid", "aevo", "orderly"],
+    aptos: ["decibel"],
+    starknet: ["paradex"],
+};
+const EXCHANGE_CHAINS = {
+    hyperliquid: "evm",
+    decibel: "aptos",
+    aevo: "evm",
+    orderly: "evm",
+    paradex: "starknet",
+};
+const ORDERLY_TESTNET_API = "https://testnet-api.orderly.org/v1";
+const ORDERLY_MAINNET_API = "https://api-evm.orderly.org/v1";
+const ORDERLY_EIP712_VERIFYING_CONTRACT = "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC";
+const ORDERLY_FALLBACK_BROKER_IDS = ["woofi_pro", "woofi_dex", "orderly"];
+const AEVO_TESTNET_API = "https://api-testnet.aevo.xyz";
+const AEVO_MAINNET_CHAIN_ID = 1;
+const AEVO_TESTNET_CHAIN_ID = 11155111;
+const PARADEX_TESTNET_API = "https://api.testnet.paradex.trade/v1";
+const SECONDS_PER_DAY = 86_400;
+const MILLISECONDS_PER_DAY = 86_400_000;
+function dedupe(values, order) {
+    const set = new Set(values);
+    return order.filter((item) => set.has(item));
+}
+function randomHex(bytes) {
+    return `0x${randomBytes(bytes).toString("hex")}`;
+}
+function normalizeText(input) {
+    if (!input)
+        return undefined;
+    const value = input.trim();
+    return value.length > 0 ? value : undefined;
+}
+function parsePositiveInt(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        return Math.floor(value);
+    }
+    if (typeof value !== "string")
+        return fallback;
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function readNested(input, path) {
+    let cursor = input;
+    for (const key of path) {
+        if (!isRecord(cursor) || !(key in cursor)) {
+            return undefined;
+        }
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+function readStringAt(input, path) {
+    const value = readNested(input, path);
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+async function parseBody(response) {
+    const raw = (await response.text()).trim();
+    if (!raw)
+        return { raw };
+    try {
+        return { raw, json: JSON.parse(raw) };
+    }
+    catch {
+        return { raw };
+    }
+}
+function describeHttpError(prefix, status, payload) {
+    const message = readStringAt(payload.json, ["message"]) ??
+        readStringAt(payload.json, ["error"]) ??
+        payload.raw;
+    return `${prefix} HTTP ${status}${message ? `: ${message}` : ""}`;
+}
+function toParadexChainIdFelt(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("0x"))
+        return trimmed;
+    return shortString.encodeShortString(trimmed);
+}
+async function fetchParadexChainId(restUrl) {
+    const response = await fetch(`${restUrl.replace(/\/$/, "")}/system/config`, {
+        method: "GET",
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok) {
+        const body = (await response.text()).trim();
+        throw new Error(`paradex system config HTTP ${response.status}${body ? `: ${body}` : ""}`);
+    }
+    const payload = (await response.json());
+    if (!payload.starknet_chain_id) {
+        throw new Error("paradex system config missing starknet_chain_id");
+    }
+    return toParadexChainIdFelt(payload.starknet_chain_id);
+}
+async function requestParadexJwtToken(args) {
+    const chainId = await fetchParadexChainId(args.restUrl);
+    const signedPost = async (typedPath, endpointPath, extraHeaders = {}) => {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const expiration = timestamp + 7 * 24 * 60 * 60;
+        const typed = {
+            domain: {
+                name: "Paradex",
+                chainId,
+                version: "1",
+            },
+            primaryType: "Request",
+            types: {
+                StarkNetDomain: [
+                    { name: "name", type: "felt" },
+                    { name: "chainId", type: "felt" },
+                    { name: "version", type: "felt" },
+                ],
+                Request: [
+                    { name: "method", type: "felt" },
+                    { name: "path", type: "felt" },
+                    { name: "body", type: "felt" },
+                    { name: "timestamp", type: "felt" },
+                    { name: "expiration", type: "felt" },
+                ],
+            },
+            message: {
+                method: "POST",
+                path: typedPath,
+                body: "",
+                timestamp,
+                expiration,
+            },
+        };
+        const messageHash = starkTypedData.getMessageHash(typed, args.accountAddress);
+        const signature = ec.starkCurve.sign(messageHash, args.privateKey);
+        const signatureValue = JSON.stringify([signature.r.toString(), signature.s.toString()]);
+        return fetch(`${args.restUrl.replace(/\/$/, "")}${endpointPath}`, {
+            method: "POST",
+            headers: {
+                accept: "application/json",
+                "content-type": "application/json",
+                "PARADEX-STARKNET-ACCOUNT": args.accountAddress,
+                "PARADEX-STARKNET-SIGNATURE": signatureValue,
+                "PARADEX-TIMESTAMP": String(timestamp),
+                "PARADEX-SIGNATURE-EXPIRATION": String(expiration),
+                ...extraHeaders,
+            },
+            body: JSON.stringify({}),
+        });
+    };
+    const parseAuthBody = async (response) => {
+        const raw = (await response.text()).trim();
+        if (!raw) {
+            return { raw };
+        }
+        try {
+            return { ...JSON.parse(raw), raw };
+        }
+        catch {
+            return { raw };
+        }
+    };
+    let response = await signedPost("/v1/auth", "/auth");
+    let parsed = await parseAuthBody(response);
+    if (!response.ok && parsed.raw.includes("NOT_ONBOARDED")) {
+        const onboardingHeaders = {};
+        if (args.ethereumAccount) {
+            onboardingHeaders["PARADEX-ETHEREUM-ACCOUNT"] = args.ethereumAccount;
+        }
+        const onboardingResponse = await signedPost("/v1/onboarding", "/onboarding", onboardingHeaders);
+        const onboardingBody = await parseBody(onboardingResponse);
+        if (!onboardingResponse.ok) {
+            throw new Error(describeHttpError("paradex onboarding", onboardingResponse.status, onboardingBody));
+        }
+        response = await signedPost("/v1/auth", "/auth");
+        parsed = await parseAuthBody(response);
+    }
+    if (!response.ok) {
+        throw new Error(`paradex auth HTTP ${response.status}${parsed.raw ? `: ${parsed.raw}` : ""}`);
+    }
+    if (!parsed.jwt_token) {
+        throw new Error("paradex auth response missing jwt_token");
+    }
+    return parsed.jwt_token;
+}
+function parseJsonArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => isRecord(item));
+}
+function extractOrderlyAccountId(payload) {
+    return (readStringAt(payload, ["data", "account_id"]) ??
+        readStringAt(payload, ["data", "accountId"]) ??
+        readStringAt(payload, ["account_id"]) ??
+        readStringAt(payload, ["accountId"]));
+}
+async function resolveOrderlyBrokerId(args) {
+    const provided = normalizeText(args.providedBrokerId);
+    if (provided)
+        return provided;
+    const response = await fetch(`${args.restUrl.replace(/\/$/, "")}/public/broker/name`, {
+        method: "GET",
+        headers: { accept: "application/json" },
+    });
+    if (!response.ok)
+        return undefined;
+    const payload = await parseBody(response);
+    const rows = parseJsonArray(readNested(payload.json, ["data", "rows"]));
+    const brokerIds = rows
+        .map((row) => readStringAt(row, ["broker_id"]) ?? readStringAt(row, ["brokerId"]))
+        .filter((value) => !!value);
+    for (const candidate of ORDERLY_FALLBACK_BROKER_IDS) {
+        if (brokerIds.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return brokerIds[0];
+}
+async function bootstrapOrderlyCredentials(args) {
+    const walletPrivateKey = args.profile.credentials.orderly?.tradingSecret;
+    if (!walletPrivateKey) {
+        throw new Error("missing ORDERLY_TRADING_SECRET (wallet signer) for bootstrap");
+    }
+    const restUrl = normalizeText(args.options.orderlyRestUrl) ??
+        normalizeText(process.env.ORDERLY_REST_URL) ??
+        ORDERLY_TESTNET_API;
+    const chainId = parsePositiveInt(args.options.orderlyChainId, 421614);
+    const wallet = privateKeyToAccount(walletPrivateKey);
+    const brokerId = await resolveOrderlyBrokerId({
+        restUrl,
+        providedBrokerId: args.options.orderlyBrokerId,
+    });
+    if (!brokerId) {
+        throw new Error("unable to resolve Orderly broker id; set ORDERLY_BROKER_ID or ORDERLY_TESTNET_FAUCET_BROKER_ID");
+    }
+    const baseUrl = restUrl.replace(/\/$/, "");
+    const query = new URLSearchParams({
+        address: wallet.address.toLowerCase(),
+        broker_id: brokerId,
+        chain_type: "evm",
+    });
+    let accountId;
+    const accountLookup = await fetch(`${baseUrl}/get_account?${query.toString()}`, {
+        method: "GET",
+        headers: { accept: "application/json" },
+    });
+    if (accountLookup.ok) {
+        const payload = await parseBody(accountLookup);
+        accountId = extractOrderlyAccountId(payload.json);
+    }
+    const domain = {
+        name: "Orderly",
+        version: "1",
+        chainId,
+        verifyingContract: ORDERLY_EIP712_VERIFYING_CONTRACT,
+    };
+    if (!accountId) {
+        const nonceQuery = new URLSearchParams({
+            broker_id: brokerId,
+            chain_id: String(chainId),
+            user_address: wallet.address.toLowerCase(),
+        });
+        const nonceResponse = await fetch(`${baseUrl}/registration_nonce?${nonceQuery.toString()}`, {
+            method: "GET",
+            headers: { accept: "application/json" },
+        });
+        const nonceBody = await parseBody(nonceResponse);
+        if (!nonceResponse.ok) {
+            throw new Error(describeHttpError("orderly registration nonce", nonceResponse.status, nonceBody));
+        }
+        const registrationNonce = readStringAt(nonceBody.json, ["data", "registration_nonce"]) ??
+            readStringAt(nonceBody.json, ["registration_nonce"]);
+        if (!registrationNonce) {
+            throw new Error("orderly registration nonce missing registration_nonce");
+        }
+        const timestamp = Date.now();
+        const registrationSignature = await wallet.signTypedData({
+            domain,
+            primaryType: "Registration",
+            types: {
+                Registration: [
+                    { name: "brokerId", type: "string" },
+                    { name: "chainId", type: "uint256" },
+                    { name: "timestamp", type: "uint64" },
+                    { name: "registrationNonce", type: "uint256" },
+                ],
+            },
+            message: {
+                brokerId,
+                chainId: BigInt(chainId),
+                timestamp: BigInt(timestamp),
+                registrationNonce: BigInt(registrationNonce),
+            },
+        });
+        const registerResponse = await fetch(`${baseUrl}/register_account`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                message: {
+                    brokerId,
+                    chainId,
+                    chainType: "EVM",
+                    timestamp,
+                    registrationNonce,
+                },
+                signature: registrationSignature,
+                userAddress: wallet.address.toLowerCase(),
+            }),
+        });
+        const registerBody = await parseBody(registerResponse);
+        if (!registerResponse.ok) {
+            throw new Error(describeHttpError("orderly register account", registerResponse.status, registerBody));
+        }
+        accountId = extractOrderlyAccountId(registerBody.json) ?? wallet.address;
+    }
+    const keyPair = KeyPair.fromRandom("ed25519");
+    const orderlySecret = keyPair.toString();
+    const orderlyKey = keyPair.getPublicKey().toString();
+    const timestamp = Date.now();
+    const expiration = timestamp + 365 * MILLISECONDS_PER_DAY;
+    const scope = "read,trading";
+    const currentKeySignature = await wallet.signTypedData({
+        domain,
+        primaryType: "AddOrderlyKey",
+        types: {
+            AddOrderlyKey: [
+                { name: "brokerId", type: "string" },
+                { name: "chainId", type: "uint256" },
+                { name: "orderlyKey", type: "string" },
+                { name: "scope", type: "string" },
+                { name: "timestamp", type: "uint64" },
+                { name: "expiration", type: "uint64" },
+            ],
+        },
+        message: {
+            brokerId,
+            chainId: BigInt(chainId),
+            orderlyKey,
+            scope,
+            timestamp: BigInt(timestamp),
+            expiration: BigInt(expiration),
+        },
+    });
+    const keyBody = {
+        message: {
+            brokerId,
+            chainId,
+            chainType: "EVM",
+            orderlyKey,
+            scope,
+            timestamp,
+            expiration,
+        },
+        signature: currentKeySignature,
+        userAddress: wallet.address.toLowerCase(),
+    };
+    const orderlyKeyResponse = await fetch(`${baseUrl}/orderly_key`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(keyBody),
+    });
+    if (!orderlyKeyResponse.ok) {
+        const legacySignature = await wallet.signTypedData({
+            domain,
+            primaryType: "AddOrderlyKey",
+            types: {
+                AddOrderlyKey: [
+                    { name: "brokerId", type: "string" },
+                    { name: "chainId", type: "uint256" },
+                    { name: "key", type: "string" },
+                    { name: "timestamp", type: "uint64" },
+                ],
+            },
+            message: {
+                brokerId,
+                chainId: BigInt(chainId),
+                key: orderlyKey,
+                timestamp: BigInt(timestamp),
+            },
+        });
+        const legacyResponse = await fetch(`${baseUrl}/add_orderly_key`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                message: {
+                    brokerId,
+                    chainId,
+                    timestamp,
+                    key: orderlyKey,
+                },
+                signature: legacySignature,
+                userAddress: wallet.address.toLowerCase(),
+            }),
+        });
+        const legacyBody = await parseBody(legacyResponse);
+        if (!legacyResponse.ok) {
+            const modernBody = await parseBody(orderlyKeyResponse);
+            const modernError = describeHttpError("orderly add key", orderlyKeyResponse.status, modernBody);
+            const legacyError = describeHttpError("orderly add key (legacy)", legacyResponse.status, legacyBody);
+            throw new Error(`${modernError}; ${legacyError}`);
+        }
+    }
+    return {
+        accountId: accountId ?? wallet.address,
+        key: orderlyKey,
+        secret: orderlySecret,
+        brokerId,
+        chainId,
+    };
+}
+function extractAevoApiCredentials(payload) {
+    const apiKey = readStringAt(payload, ["api_key"]) ??
+        readStringAt(payload, ["apiKey"]) ??
+        readStringAt(payload, ["data", "api_key"]) ??
+        readStringAt(payload, ["data", "apiKey"]) ??
+        readStringAt(payload, ["result", "api_key"]) ??
+        readStringAt(payload, ["result", "apiKey"]);
+    const apiSecret = readStringAt(payload, ["api_secret"]) ??
+        readStringAt(payload, ["apiSecret"]) ??
+        readStringAt(payload, ["data", "api_secret"]) ??
+        readStringAt(payload, ["data", "apiSecret"]) ??
+        readStringAt(payload, ["result", "api_secret"]) ??
+        readStringAt(payload, ["result", "apiSecret"]);
+    return {
+        apiKey,
+        apiSecret,
+    };
+}
+function resolveAevoDomain(restUrl) {
+    const normalized = restUrl.toLowerCase();
+    if (normalized.includes("testnet")) {
+        return { name: "Aevo Testnet", chainId: AEVO_TESTNET_CHAIN_ID };
+    }
+    return { name: "Aevo Mainnet", chainId: AEVO_MAINNET_CHAIN_ID };
+}
+async function bootstrapAevoCredentials(args) {
+    const signingKey = args.profile.credentials.aevo?.signingKey;
+    if (!signingKey) {
+        throw new Error("missing AEVO_SIGNING_KEY for bootstrap");
+    }
+    const accountPrivateKeyRaw = normalizeText(args.options.aevoAccountPrivateKey) ?? signingKey;
+    if (!/^0x[a-fA-F0-9]{64}$/.test(accountPrivateKeyRaw)) {
+        throw new Error("AEVO_ACCOUNT_PRIVATE_KEY must be a 0x-prefixed 32-byte hex private key");
+    }
+    const restUrl = normalizeText(args.options.aevoRestUrl) ??
+        normalizeText(process.env.AEVO_REST_URL) ??
+        AEVO_TESTNET_API;
+    const baseUrl = restUrl.replace(/\/$/, "");
+    const account = privateKeyToAccount(accountPrivateKeyRaw);
+    const signingWallet = privateKeyToAccount(signingKey);
+    const domainConfig = resolveAevoDomain(baseUrl);
+    const expiry = Math.floor(Date.now() / 1000) + 365 * SECONDS_PER_DAY;
+    const expiryText = String(expiry);
+    const accountRegisterHash = hashTypedData({
+        domain: {
+            name: domainConfig.name,
+            version: "1",
+            chainId: domainConfig.chainId,
+        },
+        primaryType: "Register",
+        types: {
+            Register: [
+                { name: "key", type: "address" },
+                { name: "expiry", type: "string" },
+            ],
+        },
+        message: {
+            key: account.address,
+            expiry: expiryText,
+        },
+    });
+    const accountSignature = await account.signMessage({
+        message: {
+            raw: hexToBytes(accountRegisterHash),
+        },
+    });
+    const signingKeySignature = await signingWallet.signTypedData({
+        domain: {
+            name: domainConfig.name,
+            version: "1",
+            chainId: domainConfig.chainId,
+        },
+        primaryType: "SignKey",
+        types: {
+            SignKey: [
+                { name: "account", type: "address" },
+                { name: "expiry", type: "string" },
+            ],
+        },
+        message: {
+            account: account.address,
+            expiry: expiryText,
+        },
+    });
+    const registerPayload = {
+        account: account.address,
+        signing_key: signingWallet.address,
+        expiry: expiryText,
+        account_signature: accountSignature,
+        signing_key_signature: signingKeySignature,
+    };
+    const registerResponse = await fetch(`${baseUrl}/register`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            accept: "application/json",
+        },
+        body: JSON.stringify(registerPayload),
+    });
+    const registerBody = await parseBody(registerResponse);
+    if (!registerResponse.ok) {
+        throw new Error(describeHttpError("aevo register", registerResponse.status, registerBody));
+    }
+    let credentials = extractAevoApiCredentials(registerBody.json);
+    if (!credentials.apiKey || !credentials.apiSecret) {
+        const apiKeyResponse = await fetch(`${baseUrl}/api-key`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(registerPayload),
+        });
+        const apiKeyBody = await parseBody(apiKeyResponse);
+        if (!apiKeyResponse.ok) {
+            throw new Error(describeHttpError("aevo api-key", apiKeyResponse.status, apiKeyBody));
+        }
+        credentials = extractAevoApiCredentials(apiKeyBody.json);
+    }
+    if (!credentials.apiKey || !credentials.apiSecret) {
+        throw new Error("aevo bootstrap did not return api_key/api_secret");
+    }
+    return {
+        apiKey: credentials.apiKey,
+        apiSecret: credentials.apiSecret,
+        accountAddress: account.address,
+        signingAddress: signingWallet.address,
+    };
+}
+function applyAuthOptions(profile, options = {}) {
+    const decibelBearer = normalizeText(options.decibelBearerToken);
+    if (decibelBearer && profile.credentials.decibel) {
+        profile.credentials.decibel.apiBearerToken = decibelBearer;
+    }
+    const aevoApiKey = normalizeText(options.aevoApiKey);
+    const aevoApiSecret = normalizeText(options.aevoApiSecret);
+    if (profile.credentials.aevo) {
+        if (aevoApiKey)
+            profile.credentials.aevo.apiKey = aevoApiKey;
+        if (aevoApiSecret)
+            profile.credentials.aevo.apiSecret = aevoApiSecret;
+    }
+    if (profile.credentials.orderly) {
+        const accountId = normalizeText(options.orderlyAccountId) ?? profile.wallets.evmAddress;
+        const key = normalizeText(options.orderlyKey);
+        const secret = normalizeText(options.orderlySecret);
+        if (accountId)
+            profile.credentials.orderly.accountId = accountId;
+        if (key)
+            profile.credentials.orderly.key = key;
+        if (secret)
+            profile.credentials.orderly.secret = secret;
+    }
+    if (profile.credentials.paradex) {
+        const bearer = normalizeText(options.paradexApiBearerToken);
+        const accountAddress = normalizeText(options.paradexAccountAddress);
+        const ethereumAccount = normalizeText(options.paradexEthereumAccount);
+        if (bearer)
+            profile.credentials.paradex.apiBearerToken = bearer;
+        if (accountAddress)
+            profile.credentials.paradex.accountAddress = accountAddress;
+        if (ethereumAccount)
+            profile.credentials.paradex.ethereumAccount = ethereumAccount;
+    }
+    refreshManualFollowUps(profile);
+}
+export async function bootstrapOnboardingAuth(profile, options = {}) {
+    applyAuthOptions(profile, options);
+    const results = [];
+    if (profile.exchanges.includes("decibel")) {
+        if (profile.credentials.decibel?.apiBearerToken) {
+            results.push({
+                exchange: "decibel",
+                service: "decibel auth",
+                status: "ok",
+                detail: "using DECIBEL_API_BEARER_TOKEN",
+            });
+        }
+        else {
+            results.push({
+                exchange: "decibel",
+                service: "decibel auth",
+                status: "manual",
+                detail: "still requires DECIBEL_API_BEARER_TOKEN",
+            });
+        }
+    }
+    if (profile.exchanges.includes("aevo")) {
+        const hasApiKey = !!normalizeText(profile.credentials.aevo?.apiKey);
+        const hasApiSecret = !!normalizeText(profile.credentials.aevo?.apiSecret);
+        if (hasApiKey && hasApiSecret) {
+            results.push({
+                exchange: "aevo",
+                service: "aevo auth",
+                status: "ok",
+                detail: "using AEVO_API_KEY and AEVO_API_SECRET",
+            });
+        }
+        else {
+            try {
+                const bootstrap = await bootstrapAevoCredentials({ profile, options });
+                if (profile.credentials.aevo) {
+                    profile.credentials.aevo.apiKey = bootstrap.apiKey;
+                    profile.credentials.aevo.apiSecret = bootstrap.apiSecret;
+                }
+                results.push({
+                    exchange: "aevo",
+                    service: "aevo auth",
+                    status: "ok",
+                    detail: `generated AEVO_API_KEY/AEVO_API_SECRET for ${bootstrap.accountAddress} via /register`,
+                });
+            }
+            catch (err) {
+                results.push({
+                    exchange: "aevo",
+                    service: "aevo auth",
+                    status: "manual",
+                    detail: err instanceof Error ? err.message : "still requires AEVO_API_KEY and AEVO_API_SECRET",
+                });
+            }
+        }
+    }
+    if (profile.exchanges.includes("orderly")) {
+        const hasAccountId = !!normalizeText(profile.credentials.orderly?.accountId);
+        const hasKey = !!normalizeText(profile.credentials.orderly?.key);
+        const hasSecret = !!normalizeText(profile.credentials.orderly?.secret);
+        if (hasAccountId && hasKey && hasSecret) {
+            results.push({
+                exchange: "orderly",
+                service: "orderly auth",
+                status: "ok",
+                detail: "using ORDERLY_ACCOUNT_ID, ORDERLY_KEY, ORDERLY_SECRET",
+            });
+        }
+        else {
+            try {
+                const defaultRestUrl = profile.mode === "mainnet-data" ? ORDERLY_MAINNET_API : ORDERLY_TESTNET_API;
+                const bootstrap = await bootstrapOrderlyCredentials({
+                    profile,
+                    options: {
+                        ...options,
+                        orderlyRestUrl: normalizeText(options.orderlyRestUrl) ??
+                            normalizeText(process.env.ORDERLY_REST_URL) ??
+                            defaultRestUrl,
+                    },
+                });
+                if (profile.credentials.orderly) {
+                    profile.credentials.orderly.accountId = bootstrap.accountId;
+                    profile.credentials.orderly.key = bootstrap.key;
+                    profile.credentials.orderly.secret = bootstrap.secret;
+                }
+                results.push({
+                    exchange: "orderly",
+                    service: "orderly auth",
+                    status: "ok",
+                    detail: `registered account + API key (broker=${bootstrap.brokerId}, chain=${bootstrap.chainId})`,
+                });
+            }
+            catch (err) {
+                results.push({
+                    exchange: "orderly",
+                    service: "orderly auth",
+                    status: "manual",
+                    detail: err instanceof Error
+                        ? err.message
+                        : "still requires ORDERLY_ACCOUNT_ID, ORDERLY_KEY, ORDERLY_SECRET",
+                });
+            }
+        }
+    }
+    if (profile.exchanges.includes("paradex")) {
+        const paradex = profile.credentials.paradex;
+        if (!paradex) {
+            results.push({
+                exchange: "paradex",
+                service: "paradex auth",
+                status: "error",
+                detail: "missing generated Paradex credential bundle",
+            });
+        }
+        else if (normalizeText(paradex.apiBearerToken)) {
+            results.push({
+                exchange: "paradex",
+                service: "paradex auth",
+                status: "ok",
+                detail: "using PARADEX_API_BEARER_TOKEN",
+            });
+        }
+        else {
+            const accountAddress = normalizeText(paradex.accountAddress) ??
+                normalizeText(process.env.PARADEX_ACCOUNT_ADDRESS) ??
+                normalizeText(paradex.starkPublicKey);
+            const privateKey = normalizeText(paradex.privateKey);
+            const ethereumAccount = normalizeText(paradex.ethereumAccount) ??
+                normalizeText(options.paradexEthereumAccount) ??
+                normalizeText(process.env.PARADEX_ETHEREUM_ACCOUNT) ??
+                normalizeText(profile.wallets.evmAddress);
+            if (!accountAddress || !privateKey) {
+                results.push({
+                    exchange: "paradex",
+                    service: "paradex auth",
+                    status: "manual",
+                    detail: "requires PARADEX_ACCOUNT_ADDRESS (or bearer token) paired with PARADEX_PRIVATE_KEY",
+                });
+            }
+            else {
+                const restUrl = normalizeText(options.paradexRestUrl) ?? PARADEX_TESTNET_API;
+                try {
+                    const token = await requestParadexJwtToken({
+                        restUrl,
+                        accountAddress,
+                        privateKey,
+                        ethereumAccount,
+                    });
+                    paradex.apiBearerToken = token;
+                    paradex.accountAddress = accountAddress;
+                    if (ethereumAccount) {
+                        paradex.ethereumAccount = ethereumAccount;
+                    }
+                    results.push({
+                        exchange: "paradex",
+                        service: "paradex auth",
+                        status: "ok",
+                        detail: "minted PARADEX_API_BEARER_TOKEN from Stark signature",
+                    });
+                }
+                catch (err) {
+                    results.push({
+                        exchange: "paradex",
+                        service: "paradex auth",
+                        status: "manual",
+                        detail: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+    refreshManualFollowUps(profile);
+    return results;
+}
+export function parseSetupMode(value) {
+    const normalized = value.trim().toLowerCase();
+    if (SETUP_MODES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Invalid setup mode: ${value}. Expected one of: ${SETUP_MODES.join(", ")}`);
+}
+export function parseSetupChains(value) {
+    const normalized = value
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+    if (normalized.length === 0) {
+        throw new Error("At least one chain is required");
+    }
+    for (const item of normalized) {
+        if (!ALL_SETUP_CHAINS.includes(item)) {
+            throw new Error(`Invalid chain: ${item}. Expected one of: ${ALL_SETUP_CHAINS.join(", ")}`);
+        }
+    }
+    return dedupe(normalized, ALL_SETUP_CHAINS);
+}
+export function parseSetupExchanges(value) {
+    const normalized = value
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean);
+    if (normalized.length === 0) {
+        throw new Error("At least one exchange is required");
+    }
+    for (const item of normalized) {
+        if (!ALL_SETUP_EXCHANGES.includes(item)) {
+            throw new Error(`Invalid exchange: ${item}. Expected one of: ${ALL_SETUP_EXCHANGES.join(", ")}`);
+        }
+    }
+    return dedupe(normalized, ALL_SETUP_EXCHANGES);
+}
+export function resolveExchangesFromChains(chains) {
+    const collected = [];
+    for (const chain of chains) {
+        collected.push(...CHAIN_EXCHANGES[chain]);
+    }
+    return dedupe(collected, ALL_SETUP_EXCHANGES);
+}
+export function inferChainsFromExchanges(exchanges) {
+    const chains = exchanges.map((exchange) => EXCHANGE_CHAINS[exchange]);
+    return dedupe(chains, ALL_SETUP_CHAINS);
+}
+const ONBOARDING_PROVIDERS = {
+    hyperliquid: {
+        exchange: "hyperliquid",
+        chain: "evm",
+        manualFundingHint: "complete wallet funding in the Hyperliquid testnet web app",
+    },
+    decibel: {
+        exchange: "decibel",
+        chain: "aptos",
+        manualAuthFollowUp: {
+            exchange: "decibel",
+            env: ["DECIBEL_API_BEARER_TOKEN"],
+            detail: "Set a Decibel bearer token for authenticated reads/trading after wallet generation.",
+        },
+        fundingTask: ({ profile, options }) => requestAptosFaucet({
+            aptosAddress: profile.wallets.aptosAddress,
+            options,
+        }),
+    },
+    aevo: {
+        exchange: "aevo",
+        chain: "evm",
+        manualAuthFollowUp: {
+            exchange: "aevo",
+            env: ["AEVO_API_KEY", "AEVO_API_SECRET", "AEVO_ACCOUNT_PRIVATE_KEY"],
+            detail: "If auto-bootstrap fails, set AEVO_API_KEY + AEVO_API_SECRET (or provide AEVO_ACCOUNT_PRIVATE_KEY for setup bootstrap).",
+        },
+        manualFundingHint: "complete wallet funding in the Aevo testnet web app",
+    },
+    orderly: {
+        exchange: "orderly",
+        chain: "evm",
+        manualAuthFollowUp: {
+            exchange: "orderly",
+            env: ["ORDERLY_ACCOUNT_ID", "ORDERLY_KEY", "ORDERLY_SECRET", "ORDERLY_BROKER_ID"],
+            detail: "If auto-bootstrap fails, set ORDERLY_* credentials directly or provide ORDERLY_BROKER_ID so setup can register/generate keys.",
+        },
+        fundingTask: ({ profile, options }) => requestOrderlyFaucet({
+            walletAddress: profile.wallets.evmAddress,
+            options,
+        }),
+    },
+    paradex: {
+        exchange: "paradex",
+        chain: "starknet",
+        manualAuthFollowUp: {
+            exchange: "paradex",
+            env: [
+                "PARADEX_API_BEARER_TOKEN",
+                "PARADEX_ACCOUNT_ADDRESS",
+                "PARADEX_ETHEREUM_ACCOUNT",
+            ],
+            detail: "Provide a Paradex bearer token (or set PARADEX_ACCOUNT_ADDRESS + PARADEX_PRIVATE_KEY, plus PARADEX_ETHEREUM_ACCOUNT when onboarding is required).",
+        },
+        manualFundingHint: "complete faucet funding in Paradex developer mode",
+    },
+};
+function buildManualFollowUps(profile) {
+    const followUps = [];
+    for (const exchange of profile.exchanges) {
+        const provider = ONBOARDING_PROVIDERS[exchange];
+        if (!provider.manualAuthFollowUp) {
+            continue;
+        }
+        if (exchange === "decibel") {
+            const hasBearer = !!normalizeText(profile.credentials.decibel?.apiBearerToken);
+            if (!hasBearer) {
+                followUps.push(provider.manualAuthFollowUp);
+            }
+            continue;
+        }
+        if (exchange === "aevo") {
+            const hasApiKey = !!normalizeText(profile.credentials.aevo?.apiKey);
+            const hasApiSecret = !!normalizeText(profile.credentials.aevo?.apiSecret);
+            if (!hasApiKey || !hasApiSecret) {
+                followUps.push(provider.manualAuthFollowUp);
+            }
+            continue;
+        }
+        if (exchange === "orderly") {
+            const hasAccountId = !!normalizeText(profile.credentials.orderly?.accountId);
+            const hasKey = !!normalizeText(profile.credentials.orderly?.key);
+            const hasSecret = !!normalizeText(profile.credentials.orderly?.secret);
+            if (!hasAccountId || !hasKey || !hasSecret) {
+                followUps.push(provider.manualAuthFollowUp);
+            }
+            continue;
+        }
+        if (exchange === "paradex") {
+            const hasBearer = !!normalizeText(profile.credentials.paradex?.apiBearerToken);
+            const hasAccount = !!normalizeText(profile.credentials.paradex?.accountAddress) &&
+                !!normalizeText(profile.credentials.paradex?.privateKey);
+            if (!hasBearer && !hasAccount) {
+                followUps.push(provider.manualAuthFollowUp);
+            }
+            continue;
+        }
+    }
+    return followUps;
+}
+function refreshManualFollowUps(profile) {
+    profile.manualFollowUps = buildManualFollowUps(profile);
+}
+export function createOnboardingProfile(args) {
+    const exchanges = dedupe(args.exchanges, ALL_SETUP_EXCHANGES);
+    const chains = inferChainsFromExchanges(exchanges);
+    const generatedAt = new Date().toISOString();
+    const profile = {
+        mode: args.mode,
+        chains,
+        exchanges,
+        generatedAt,
+        credentials: {},
+        wallets: {},
+        manualFollowUps: [],
+    };
+    const needsEvmWallet = exchanges.some((exchange) => CHAIN_EXCHANGES.evm.includes(exchange));
+    if (needsEvmWallet) {
+        const evmPrivateKey = randomHex(32);
+        const evmAddress = privateKeyToAccount(evmPrivateKey).address;
+        profile.wallets.evmAddress = evmAddress;
+        if (exchanges.includes("hyperliquid")) {
+            profile.credentials.hyperliquid = {
+                privateKey: evmPrivateKey,
+                walletAddress: evmAddress,
+            };
+        }
+        if (exchanges.includes("aevo")) {
+            profile.credentials.aevo = {
+                signingKey: evmPrivateKey,
+            };
+        }
+        if (exchanges.includes("orderly")) {
+            profile.credentials.orderly = {
+                tradingSecret: evmPrivateKey,
+            };
+        }
+    }
+    if (exchanges.includes("decibel")) {
+        const aptosPrivateKeyObj = Ed25519PrivateKey.generate();
+        const aptosPrivateKey = aptosPrivateKeyObj.toString();
+        const aptosAddress = new Ed25519Account({ privateKey: aptosPrivateKeyObj })
+            .accountAddress
+            .toString();
+        profile.credentials.decibel = {
+            apiWalletPrivateKey: aptosPrivateKey,
+            apiWalletAddress: aptosAddress,
+        };
+        profile.wallets.aptosAddress = aptosAddress;
+    }
+    if (exchanges.includes("paradex")) {
+        const starkPrivateKeyBytes = ec.starkCurve.utils.randomPrivateKey();
+        const starkPrivateKey = `0x${Buffer.from(starkPrivateKeyBytes).toString("hex")}`;
+        const starkPublicKey = ec.starkCurve.getStarkKey(starkPrivateKey);
+        profile.credentials.paradex = {
+            privateKey: starkPrivateKey,
+            starkPublicKey,
+            ethereumAccount: profile.wallets.evmAddress,
+        };
+        profile.wallets.starkPublicKey = starkPublicKey;
+    }
+    refreshManualFollowUps(profile);
+    return profile;
+}
+function shouldForceTestnetEverywhere(mode) {
+    return mode === "testnet-execution";
+}
+function pushTestnetNetworkLine(lines, key, forceTestnetEverywhere) {
+    if (forceTestnetEverywhere) {
+        lines.push(`${key}=testnet`);
+    }
+    else {
+        lines.push(`# ${key}=testnet`);
+    }
+}
+function pushTestnetRestLine(lines, key, value, forceTestnetEverywhere) {
+    if (forceTestnetEverywhere) {
+        lines.push(`${key}=${value}`);
+    }
+    else {
+        lines.push(`# ${key}=${value}`);
+    }
+}
+export function buildOnboardingEnvFile(profile) {
+    const forceTestnetEverywhere = shouldForceTestnetEverywhere(profile.mode);
+    const lines = [
+        "# Auto-generated by perps setup wizard",
+        `# Generated: ${profile.generatedAt}`,
+        "# SECURITY: keep this local and never commit it.",
+        "",
+    ];
+    if (profile.mode === "both") {
+        lines.push("# Mode: mainnet-data + testnet-execution");
+        lines.push("# Data commands default to mainnet; execution defaults to testnet.");
+        lines.push("# Exchange network/url overrides are intentionally commented to preserve command-intent defaults.");
+        lines.push("");
+    }
+    else if (profile.mode === "testnet-execution") {
+        lines.push("# Mode: force testnet for selected exchanges");
+        lines.push("# Exchange network/url overrides are active below.");
+        lines.push("");
+    }
+    else {
+        lines.push("# Mode: mainnet data only");
+        lines.push("# No private credentials generated in this profile.");
+        lines.push("");
+    }
+    if (profile.exchanges.includes("hyperliquid") && profile.credentials.hyperliquid) {
+        lines.push("# Hyperliquid");
+        pushTestnetNetworkLine(lines, "HYPERLIQUID_NETWORK", forceTestnetEverywhere);
+        lines.push(`HYPERLIQUID_PRIVATE_KEY=${profile.credentials.hyperliquid.privateKey}`);
+        lines.push(`HYPERLIQUID_WALLET_ADDRESS=${profile.credentials.hyperliquid.walletAddress}`);
+        lines.push("");
+    }
+    if (profile.exchanges.includes("decibel") && profile.credentials.decibel) {
+        lines.push("# Decibel (Aptos)");
+        pushTestnetNetworkLine(lines, "DECIBEL_NETWORK", forceTestnetEverywhere);
+        lines.push(`DECIBEL_API_WALLET_PRIVATE_KEY=${profile.credentials.decibel.apiWalletPrivateKey}`);
+        lines.push(`DECIBEL_API_WALLET_ADDRESS=${profile.credentials.decibel.apiWalletAddress}`);
+        const decibelBearer = normalizeText(profile.credentials.decibel.apiBearerToken);
+        if (decibelBearer) {
+            lines.push(`DECIBEL_API_BEARER_TOKEN=${decibelBearer}`);
+        }
+        else {
+            lines.push("# DECIBEL_API_BEARER_TOKEN=...");
+        }
+        lines.push("");
+    }
+    if (profile.exchanges.includes("aevo") && profile.credentials.aevo) {
+        lines.push("# Aevo");
+        pushTestnetNetworkLine(lines, "AEVO_NETWORK", forceTestnetEverywhere);
+        pushTestnetRestLine(lines, "AEVO_REST_URL", AEVO_TESTNET_API, forceTestnetEverywhere);
+        lines.push(`AEVO_SIGNING_KEY=${profile.credentials.aevo.signingKey}`);
+        const aevoApiKey = normalizeText(profile.credentials.aevo.apiKey);
+        const aevoApiSecret = normalizeText(profile.credentials.aevo.apiSecret);
+        if (aevoApiKey) {
+            lines.push(`AEVO_API_KEY=${aevoApiKey}`);
+        }
+        else {
+            lines.push("# AEVO_API_KEY=...");
+        }
+        if (aevoApiSecret) {
+            lines.push(`AEVO_API_SECRET=${aevoApiSecret}`);
+        }
+        else {
+            lines.push("# AEVO_API_SECRET=...");
+        }
+        lines.push("# AEVO_ACCOUNT_PRIVATE_KEY=... # optional: used only for setup bootstrap if AEVO_API_* absent");
+        lines.push("");
+    }
+    if (profile.exchanges.includes("orderly") && profile.credentials.orderly) {
+        lines.push("# Orderly");
+        pushTestnetNetworkLine(lines, "ORDERLY_NETWORK", forceTestnetEverywhere);
+        pushTestnetRestLine(lines, "ORDERLY_REST_URL", ORDERLY_TESTNET_API, forceTestnetEverywhere);
+        lines.push(`ORDERLY_TRADING_SECRET=${profile.credentials.orderly.tradingSecret}`);
+        const orderlyAccountId = normalizeText(profile.credentials.orderly.accountId);
+        const orderlyKey = normalizeText(profile.credentials.orderly.key);
+        const orderlySecret = normalizeText(profile.credentials.orderly.secret);
+        if (orderlyAccountId) {
+            lines.push(`ORDERLY_ACCOUNT_ID=${orderlyAccountId}`);
+        }
+        else {
+            lines.push("# ORDERLY_ACCOUNT_ID=0x...");
+        }
+        if (orderlyKey) {
+            lines.push(`ORDERLY_KEY=${orderlyKey}`);
+        }
+        else {
+            lines.push("# ORDERLY_KEY=...");
+        }
+        if (orderlySecret) {
+            lines.push(`ORDERLY_SECRET=${orderlySecret}`);
+        }
+        else {
+            lines.push("# ORDERLY_SECRET=...");
+        }
+        lines.push("");
+    }
+    if (profile.exchanges.includes("paradex")) {
+        lines.push("# Paradex (Starknet)");
+        pushTestnetNetworkLine(lines, "PARADEX_NETWORK", forceTestnetEverywhere);
+        pushTestnetRestLine(lines, "PARADEX_REST_URL", PARADEX_TESTNET_API, forceTestnetEverywhere);
+        if (profile.mode === "testnet-execution") {
+            lines.push("PARADEX_CHAIN_ID=SN_SEPOLIA");
+        }
+        else {
+            lines.push("# PARADEX_CHAIN_ID=SN_SEPOLIA");
+        }
+        if (profile.credentials.paradex) {
+            lines.push(`PARADEX_PRIVATE_KEY=${profile.credentials.paradex.privateKey}`);
+            lines.push(`PARADEX_STARK_PUBLIC_KEY=${profile.credentials.paradex.starkPublicKey}`);
+            const paradexAccountAddress = normalizeText(profile.credentials.paradex.accountAddress);
+            if (paradexAccountAddress) {
+                lines.push(`PARADEX_ACCOUNT_ADDRESS=${paradexAccountAddress}`);
+            }
+            else {
+                lines.push("# PARADEX_ACCOUNT_ADDRESS=0x...");
+            }
+            const paradexEthereumAccount = normalizeText(profile.credentials.paradex.ethereumAccount);
+            if (paradexEthereumAccount) {
+                lines.push(`PARADEX_ETHEREUM_ACCOUNT=${paradexEthereumAccount}`);
+            }
+            else {
+                lines.push("# PARADEX_ETHEREUM_ACCOUNT=0x...");
+            }
+            const paradexBearer = normalizeText(profile.credentials.paradex.apiBearerToken);
+            if (paradexBearer) {
+                lines.push(`PARADEX_API_BEARER_TOKEN=${paradexBearer}`);
+            }
+            else {
+                lines.push("# PARADEX_API_BEARER_TOKEN=...");
+            }
+        }
+        else {
+            lines.push("# PARADEX_ACCOUNT_ADDRESS=0x...");
+            lines.push("# PARADEX_ETHEREUM_ACCOUNT=0x...");
+            lines.push("# PARADEX_API_BEARER_TOKEN=...");
+        }
+        lines.push("");
+    }
+    if (profile.exchanges.includes("orderly")) {
+        lines.push("# Optional Orderly setup + faucet automation");
+        lines.push("# ORDERLY_BROKER_ID=...");
+        lines.push("# ORDERLY_TESTNET_FAUCET_BROKER_ID=...");
+        lines.push("# ORDERLY_TESTNET_FAUCET_CHAIN_ID=421614");
+        lines.push("");
+    }
+    if (profile.exchanges.includes("decibel")) {
+        lines.push("# Optional Aptos faucet automation");
+        lines.push("# APTOS_TESTNET_FAUCET_JWT=...");
+        lines.push("# APTOS_TESTNET_FAUCET_AMOUNT=100000000");
+        lines.push("");
+    }
+    if (profile.mode !== "mainnet-data") {
+        lines.push("# Conservative risk defaults for early testnet dry-runs");
+        lines.push("RISK_MAX_POSITION_SIZE_USD=100");
+        lines.push("RISK_MAX_TOTAL_EXPOSURE_USD=200");
+        lines.push("RISK_MAX_LEVERAGE=2");
+        lines.push("");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+async function requestOrderlyFaucet(args) {
+    const brokerId = normalizeText(args.options.orderlyBrokerId);
+    if (!brokerId) {
+        return {
+            exchange: "orderly",
+            service: "orderly faucet",
+            status: "skipped",
+            detail: "missing ORDERLY_TESTNET_FAUCET_BROKER_ID",
+        };
+    }
+    if (!args.walletAddress) {
+        return {
+            exchange: "orderly",
+            service: "orderly faucet",
+            status: "skipped",
+            detail: "no EVM wallet address generated",
+        };
+    }
+    const chainId = parsePositiveInt(args.options.orderlyChainId, 421614);
+    const endpoint = "https://testnet-operator-evm.orderly.org/v1/faucet/usdc";
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            chain_id: chainId,
+            broker_id: brokerId,
+            user_address: args.walletAddress,
+        }),
+    });
+    if (!response.ok) {
+        const body = (await response.text()).trim();
+        throw new Error(`orderly faucet HTTP ${response.status}${body ? `: ${body}` : ""}`);
+    }
+    return {
+        exchange: "orderly",
+        service: "orderly faucet",
+        status: "ok",
+        detail: `requested USDC for ${args.walletAddress} on chain ${chainId}`,
+    };
+}
+async function requestAptosFaucet(args) {
+    const jwt = normalizeText(args.options.aptosFaucetJwt);
+    if (!jwt) {
+        return {
+            exchange: "decibel",
+            service: "aptos faucet",
+            status: "skipped",
+            detail: "missing APTOS_TESTNET_FAUCET_JWT",
+        };
+    }
+    if (!args.aptosAddress) {
+        return {
+            exchange: "decibel",
+            service: "aptos faucet",
+            status: "skipped",
+            detail: "no Aptos wallet address generated",
+        };
+    }
+    const amount = parsePositiveInt(args.options.aptosFaucetAmount, 100000000);
+    const endpoint = new URL("https://faucet.testnet.aptoslabs.com/mint");
+    endpoint.searchParams.set("address", args.aptosAddress);
+    endpoint.searchParams.set("amount", String(amount));
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${jwt}`,
+            "x-is-jwt": "true",
+        },
+    });
+    if (!response.ok) {
+        const body = (await response.text()).trim();
+        throw new Error(`aptos faucet HTTP ${response.status}${body ? `: ${body}` : ""}`);
+    }
+    return {
+        exchange: "decibel",
+        service: "aptos faucet",
+        status: "ok",
+        detail: `requested ${amount} Octas for ${args.aptosAddress}`,
+    };
+}
+export async function fundOnboardingWallets(profile, options = {}) {
+    const results = [];
+    const tasks = profile.exchanges
+        .map((exchange) => ONBOARDING_PROVIDERS[exchange])
+        .filter((provider) => typeof provider.fundingTask === "function")
+        .map((provider) => provider.fundingTask({ profile, options }));
+    const settled = await Promise.allSettled(tasks);
+    for (const item of settled) {
+        if (item.status === "fulfilled") {
+            results.push(item.value);
+            recordTelemetryMetric({
+                metric: `funding.${item.value.exchange}`,
+                status: item.value.status === "ok"
+                    ? "success"
+                    : item.value.status === "error"
+                        ? "failed"
+                        : item.value.status,
+            });
+            continue;
+        }
+        const message = item.reason instanceof Error ? item.reason.message : String(item.reason);
+        if (message.startsWith("orderly faucet")) {
+            results.push({
+                exchange: "orderly",
+                service: "orderly faucet",
+                status: "error",
+                detail: message,
+            });
+            recordTelemetryMetric({ metric: "funding.orderly", status: "failed" });
+            continue;
+        }
+        if (message.startsWith("aptos faucet")) {
+            results.push({
+                exchange: "decibel",
+                service: "aptos faucet",
+                status: "error",
+                detail: message,
+            });
+            recordTelemetryMetric({ metric: "funding.decibel", status: "failed" });
+            continue;
+        }
+        results.push({
+            exchange: "orderly",
+            service: "faucet",
+            status: "error",
+            detail: message,
+        });
+        recordTelemetryMetric({ metric: "funding.orderly", status: "failed" });
+    }
+    for (const exchange of profile.exchanges) {
+        const provider = ONBOARDING_PROVIDERS[exchange];
+        if (!provider.manualFundingHint) {
+            continue;
+        }
+        results.push({
+            exchange,
+            service: `${exchange} faucet`,
+            status: "manual",
+            detail: provider.manualFundingHint,
+        });
+        recordTelemetryMetric({ metric: `funding.${exchange}`, status: "manual" });
+    }
+    return results;
+}
+function makeOnboardingStatePath(idempotencyKey) {
+    return resolve(ONBOARDING_STATE_DIR, `${idempotencyKey}.json`);
+}
+function computeIdempotencyKey(mode, exchanges) {
+    const payload = `${mode}:${[...exchanges].sort().join(",")}`;
+    const digest = Buffer.from(payload, "utf-8").toString("base64url").slice(0, 24);
+    return `onboarding-${digest}`;
+}
+function createRunState(mode, exchanges) {
+    const idempotencyKey = computeIdempotencyKey(mode, exchanges);
+    const now = new Date().toISOString();
+    return {
+        id: `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        idempotencyKey,
+        mode,
+        exchanges: [...exchanges],
+        updatedAt: now,
+        statusByStep: {
+            plan: "pending",
+            generate: "pending",
+            fund: "pending",
+            verify: "pending",
+            report: "pending",
+        },
+        notes: [],
+    };
+}
+function readRunState(path) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeRunState(path, state) {
+    ensurePrivateDir(ONBOARDING_STATE_DIR);
+    state.updatedAt = new Date().toISOString();
+    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { mode: PRIVATE_FILE_MODE });
+    hardenPrivateFile(path);
+}
+function markStep(state, step, status, note) {
+    state.statusByStep[step] = status;
+    if (note) {
+        state.notes.push(note);
+    }
+    state.updatedAt = new Date().toISOString();
+    return state;
+}
+function verifyOnboardingProfile(profile) {
+    const notes = [];
+    if (profile.exchanges.some((exchange) => EXCHANGE_CHAINS[exchange] === "evm") && !profile.wallets.evmAddress) {
+        notes.push("Missing generated EVM wallet for selected EVM exchanges");
+    }
+    if (profile.exchanges.includes("decibel") && !profile.wallets.aptosAddress) {
+        notes.push("Missing generated Aptos wallet for Decibel");
+    }
+    if (profile.exchanges.includes("paradex") && !profile.wallets.starkPublicKey) {
+        notes.push("Missing generated Stark public key for Paradex");
+    }
+    return notes;
+}
+export async function runOnboardingStateMachine(args) {
+    const idempotencyKey = computeIdempotencyKey(args.mode, args.exchanges);
+    const statePath = args.statePath ? resolve(args.statePath) : makeOnboardingStatePath(idempotencyKey);
+    let state = args.resume ? readRunState(statePath) : null;
+    if (!state) {
+        state = createRunState(args.mode, args.exchanges);
+        state.idempotencyKey = idempotencyKey;
+        writeRunState(statePath, state);
+    }
+    markStep(state, "plan", "running");
+    writeRunState(statePath, state);
+    markStep(state, "plan", "done", `mode=${args.mode}; exchanges=${args.exchanges.join(",")}`);
+    writeRunState(statePath, state);
+    if (!state.profile) {
+        markStep(state, "generate", "running");
+        writeRunState(statePath, state);
+        state.profile = createOnboardingProfile({
+            mode: args.mode,
+            exchanges: args.exchanges,
+        });
+    }
+    if (args.shouldBootstrapAuth ?? true) {
+        state.authResults = await bootstrapOnboardingAuth(state.profile, args.authOptions ?? {});
+        const autoReady = state.authResults.filter((result) => result.status === "ok").length;
+        state.notes.push(`auth bootstrap completed (${autoReady}/${state.authResults.length} ready)`);
+    }
+    else {
+        state.authResults = [];
+        state.notes.push("auth bootstrap skipped");
+    }
+    markStep(state, "generate", "done");
+    writeRunState(statePath, state);
+    if (args.shouldFund) {
+        const retries = Math.max(0, args.fundingRetries ?? 1);
+        markStep(state, "fund", "running");
+        writeRunState(statePath, state);
+        let attempt = 0;
+        let fundingResults = [];
+        while (attempt <= retries) {
+            attempt += 1;
+            fundingResults = await fundOnboardingWallets(state.profile, args.fundingOptions ?? {});
+            const failed = fundingResults.filter((result) => result.status === "error");
+            if (failed.length === 0) {
+                break;
+            }
+            if (attempt <= retries) {
+                state.notes.push(`fund attempt ${attempt} had ${failed.length} errors; retrying`);
+            }
+        }
+        state.fundingResults = fundingResults;
+        markStep(state, "fund", "done");
+        writeRunState(statePath, state);
+    }
+    else {
+        state.fundingResults = [];
+        markStep(state, "fund", "done", "funding skipped");
+        writeRunState(statePath, state);
+    }
+    markStep(state, "verify", "running");
+    writeRunState(statePath, state);
+    const verificationNotes = verifyOnboardingProfile(state.profile);
+    if (verificationNotes.length > 0) {
+        for (const note of verificationNotes) {
+            state.notes.push(note);
+        }
+        markStep(state, "verify", "error");
+    }
+    else {
+        markStep(state, "verify", "done");
+    }
+    writeRunState(statePath, state);
+    markStep(state, "report", "done");
+    writeRunState(statePath, state);
+    return {
+        profile: state.profile,
+        authResults: state.authResults ?? [],
+        fundingResults: state.fundingResults ?? [],
+        statePath,
+        state,
+    };
+}