@0xmonaco/core 1.1.7 → 1.1.8

package/dist/api/sweeper/hypercore.js

@@ -0,0 +1,357 @@
+/**
+ * USDC withdrawals from Hyperliquid (HyperCore) to a Sei deposit address.
+ *
+ * Circle's CCTP integration on HyperCore withdraws USDC to any CCTP domain
+ * through one user-signed HyperCore action, `sendToEvmWithData`
+ * (developers.circle.com/cctp/howtos/withdraw-usdc-from-hypercore-to-evm).
+ * Hyperliquid executes the signed action itself, so the user pays no gas: its
+ * system call into Circle's CoreDepositWallet on HyperEVM burns the USDC with
+ * Sei as the destination domain and the deposit address as the mint
+ * recipient. Empty `data` selects Circle's default forwarding hook, so Circle
+ * mints on Sei and keeps its fee out of the mint. The hub then sweeps the
+ * deposit address like any deposit made straight to it.
+ */
+import { concat, createPublicClient, hashDomain, hashStruct, http, keccak256, parseAbi, parseSignature, serializeTypedData, } from "viem";
+import { hyperEvm, hyperliquidEvmTestnet, sei, seiTestnet } from "viem/chains";
+import { APIError } from "../../errors";
+/** Sei's CCTP domain: where the withdrawal mints. Not its EVM chain id. */
+export const SEI_CCTP_DOMAIN = 16;
+/** Gas for Hyperliquid's call into the CoreDepositWallet on HyperEVM, as in Circle's guide. */
+const HYPEREVM_GAS_LIMIT = 200_000;
+/** USDC's decimals on HyperEVM and Sei. */
+export const USDC_DECIMALS = 6;
+/**
+ * The Hyperliquid network that pairs with the SDK's Sei chain: mainnet with
+ * Sei mainnet, testnet with Sei testnet (where every non-mainnet Monaco
+ * network settles). `undefined` for any other chain.
+ */
+export function hypercoreNetworkFor(chainId) {
+    if (chainId === sei.id) {
+        return {
+            hyperliquidChain: "Mainnet",
+            exchangeUrl: "https://api.hyperliquid.xyz/exchange",
+            infoUrl: "https://api.hyperliquid.xyz/info",
+            hyperEvm,
+            coreDepositWallet: "0x6B9E773128f453f5c2C60935Ee2DE2CBc5390A24",
+            seiUsdc: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392",
+            hyperEvmUsdc: "0xb88339CB7199b77E23DB6E890353E22632Ba630f",
+            tokenMessenger: "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d",
+            irisUrl: "https://iris-api.circle.com",
+        };
+    }
+    if (chainId === seiTestnet.id) {
+        return {
+            hyperliquidChain: "Testnet",
+            exchangeUrl: "https://api.hyperliquid-testnet.xyz/exchange",
+            infoUrl: "https://api.hyperliquid-testnet.xyz/info",
+            hyperEvm: hyperliquidEvmTestnet,
+            coreDepositWallet: "0x0B80659a4076E9E93C7DbE0f10675A16a3e5C206",
+            seiUsdc: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED",
+            hyperEvmUsdc: "0x2B3370eE501B4a559b57D449569354196457D8Ab",
+            tokenMessenger: "0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA",
+            irisUrl: "https://iris-api-sandbox.circle.com",
+        };
+    }
+    return undefined;
+}
+const CORE_DEPOSIT_WALLET_ABI = parseAbi(["function calculateCrossChainWithdrawalFee(bool shouldForward, uint32 destinationChainId) view returns (uint256)"]);
+/**
+ * The most Circle deducts from a forwarded withdrawal to Sei: the CCTP
+ * `maxFee` its CoreDepositWallet burns with (its forwarding fee for the
+ * domain plus CCTP's own cap). Owner-configurable per domain, so it is read
+ * rather than assumed. The wallet also reverts a withdrawal that does not
+ * exceed it.
+ */
+export async function readMaxFee(network) {
+    const client = createPublicClient({ chain: network.hyperEvm, transport: http() });
+    return client.readContract({
+        address: network.coreDepositWallet,
+        abi: CORE_DEPOSIT_WALLET_ABI,
+        functionName: "calculateCrossChainWithdrawalFee",
+        args: [true, SEI_CCTP_DOMAIN],
+    });
+}
+/** USDC's token index on HyperCore, on mainnet and testnet alike (`spotMeta`). */
+const HYPERCORE_USDC_TOKEN = 0;
+/**
+ * Account modes that keep one balance per asset. Hyperliquid reports such an
+ * account's whole balance in its spot state, and its perp state "is not
+ * meaningful" (hyperliquid-docs: trading/account-abstraction-modes).
+ */
+function isUnified(mode) {
+    return mode === "unifiedAccount" || mode === "portfolioMargin";
+}
+/** Read the account's mode and USDC balances from Hyperliquid's public info endpoint. */
+export async function readHypercoreAccount(network, user) {
+    const query = (type) => postToInfo(network, { type, user: user.toLowerCase() });
+    const [mode, perpState, spotState] = await Promise.all([
+        query("userAbstraction"),
+        query("clearinghouseState"),
+        query("spotClearinghouseState"),
+    ]);
+    const usdc = spotState.balances?.find((balance) => balance.token === HYPERCORE_USDC_TOKEN);
+    // Subtract at Hyperliquid's own precision and truncate only the result:
+    // truncating total and hold separately can overstate the unheld balance.
+    const spot = usdc ? toExact(usdc.total, network) - toExact(usdc.hold, network) : 0n;
+    return {
+        mode,
+        perp: isUnified(mode) ? 0n : toRawUsdc(toExact(perpState.withdrawable, network)),
+        spot: spot > 0n ? toRawUsdc(spot) : 0n,
+    };
+}
+/**
+ * Raw USDC kept back for Hyperliquid's own fee on a withdrawal to HyperEVM,
+ * which it charges on top of the amount. Hyperliquid documents the fee as
+ * 200k gas at the next HyperEVM block's base fee but does not publish the
+ * USDC rate it charges. Derived, not quoted: on 2026-11-05 a mainnet
+ * withdrawal was charged 0.012948 USDC and testnet withdrawals 0.07122 to
+ * 0.072664, and 0.1 covers both with room.
+ */
+const HYPERLIQUID_FEE_RESERVE = 100000n;
+/**
+ * The most a perp draw can take. Hyperliquid charges its fee to spot when
+ * spot covers it, and to the balance withdrawn otherwise (both measured on
+ * testnet, the second with 0.01 USDC in spot), so perp keeps the reserve back
+ * only when spot holds less than it.
+ */
+function perpDrawable(account) {
+    if (account.spot >= HYPERLIQUID_FEE_RESERVE) {
+        return account.perp;
+    }
+    return account.perp > HYPERLIQUID_FEE_RESERVE ? account.perp - HYPERLIQUID_FEE_RESERVE : 0n;
+}
+/** The most a spot draw can take: spot pays Hyperliquid's fee on top of it. */
+function spotDrawable(account) {
+    return account.spot > HYPERLIQUID_FEE_RESERVE ? account.spot - HYPERLIQUID_FEE_RESERVE : 0n;
+}
+/**
+ * The balance one withdrawal of `amount` draws on, or `undefined` when none
+ * covers it with room for Hyperliquid's fee. A unified or portfolio-margin
+ * account draws on spot: Hyperliquid refuses any other source for it
+ * ("Unified account only supports sending assets through spot"). Otherwise
+ * perp comes first, where a deposit to Hyperliquid lands by default.
+ */
+export function chooseSource(account, amount) {
+    if (!isUnified(account.mode) && amount <= perpDrawable(account)) {
+        return "perp";
+    }
+    return amount <= spotDrawable(account) ? "spot" : undefined;
+}
+/** The most one withdrawal can draw: it draws on a single balance and leaves room for Hyperliquid's fee. */
+export function availableToDraw(account) {
+    const spot = spotDrawable(account);
+    if (isUnified(account.mode)) {
+        return spot;
+    }
+    // Not Math.max: it does not take bigints.
+    const perp = perpDrawable(account);
+    if (perp > spot) {
+        return perp;
+    }
+    return spot;
+}
+/** POST one query to Hyperliquid's info endpoint; any failure is an `APIError`. */
+async function postToInfo(network, body) {
+    const endpoint = network.infoUrl;
+    let response;
+    try {
+        response = await fetch(endpoint, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    }
+    catch (error) {
+        throw new APIError("Network request to Hyperliquid failed", { endpoint, cause: error instanceof Error ? error : new Error(String(error)) });
+    }
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+        throw new APIError(`Hyperliquid's ${body.type} query answered ${response.status}`, {
+            endpoint,
+            statusCode: response.status,
+            responseBody: text.slice(0, 500),
+        });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new APIError(`Hyperliquid's ${body.type} reply was not readable`, { endpoint, statusCode: response.status, responseBody: text.slice(0, 500) });
+    }
+}
+/**
+ * Fixed-point scale for Hyperliquid's decimal strings: above any precision it
+ * reports (USDC carries 8 `weiDecimals`), so arithmetic on it is exact.
+ */
+const EXACT_DECIMALS = 18;
+/** Hyperliquid's decimal-string amount at {@link EXACT_DECIMALS}. */
+function toExact(value, network) {
+    const match = typeof value === "string" ? /^(\d+)(?:\.(\d+))?$/.exec(value) : null;
+    if (!match) {
+        throw new APIError(`Hyperliquid reported an unreadable USDC amount: ${JSON.stringify(value)}`, { endpoint: network.infoUrl });
+    }
+    const [, whole = "0", fraction = ""] = match;
+    return BigInt(whole) * 10n ** BigInt(EXACT_DECIMALS) + BigInt(fraction.slice(0, EXACT_DECIMALS).padEnd(EXACT_DECIMALS, "0"));
+}
+/** A non-negative exact amount in raw 6-decimal USDC, truncated so the SDK never offers more than the account holds. */
+function toRawUsdc(exact) {
+    return exact / 10n ** BigInt(EXACT_DECIMALS - USDC_DECIMALS);
+}
+const PRIMARY_TYPE = "HyperliquidTransaction:SendToEvmWithData";
+/** The action's EIP-712 type, as Circle documents it; field order is part of the hash. */
+const SEND_TO_EVM_WITH_DATA_TYPES = {
+    [PRIMARY_TYPE]: [
+        { name: "hyperliquidChain", type: "string" },
+        { name: "token", type: "string" },
+        { name: "amount", type: "string" },
+        { name: "sourceDex", type: "string" },
+        { name: "destinationRecipient", type: "string" },
+        { name: "addressEncoding", type: "string" },
+        { name: "destinationChainId", type: "uint32" },
+        { name: "gasLimit", type: "uint64" },
+        { name: "data", type: "bytes" },
+        { name: "nonce", type: "uint64" },
+    ],
+};
+/** The signature domain's type: every field `HyperliquidSignTransaction` sets. */
+const EIP712_DOMAIN_TYPE = [
+    { name: "name", type: "string" },
+    { name: "version", type: "string" },
+    { name: "chainId", type: "uint256" },
+    { name: "verifyingContract", type: "address" },
+];
+/**
+ * Sign a USDC withdrawal from Hyperliquid to `recipient` on Sei.
+ *
+ * The signature's domain uses the wallet's own chain (Sei), which Hyperliquid
+ * accepts from any chain and wallets that hold the domain to the active
+ * network sign without switching.
+ */
+export async function signWithdrawalToSei(params) {
+    const { walletClient, network, amount, sourceDex, recipient, nonce } = params;
+    const chainId = walletClient.chain?.id;
+    const account = walletClient.account;
+    if (chainId === undefined || account === undefined) {
+        throw new Error("signWithdrawalToSei needs a wallet client with a chain and an account");
+    }
+    const message = {
+        hyperliquidChain: network.hyperliquidChain,
+        token: "USDC",
+        amount,
+        sourceDex,
+        destinationRecipient: recipient,
+        addressEncoding: "hex",
+        destinationChainId: SEI_CCTP_DOMAIN,
+        gasLimit: BigInt(HYPEREVM_GAS_LIMIT),
+        data: "0x",
+        nonce: BigInt(nonce),
+    };
+    const domain = {
+        name: "HyperliquidSignTransaction",
+        version: "1",
+        chainId,
+        verifyingContract: "0x0000000000000000000000000000000000000000",
+    };
+    const signature = await signHyperliquidTypedData(walletClient, account, domain, message);
+    const { r, s, yParity } = parseSignature(signature);
+    return {
+        action: {
+            type: "sendToEvmWithData",
+            signatureChainId: `0x${chainId.toString(16)}`,
+            ...message,
+            gasLimit: HYPEREVM_GAS_LIMIT,
+            nonce,
+        },
+        nonce,
+        signature: { r, s, v: 27 + yParity },
+    };
+}
+/**
+ * Sign Hyperliquid typed data with the wallet's account.
+ *
+ * viem's `signTypedData` refuses this type from 2.57.12 (wevm/viem#5308 lets
+ * a struct name hold only letters, digits, `_` and `$`; wevm/viem#5403 allows
+ * `:` again in a later release), and Hyperliquid names every user-signed
+ * action `HyperliquidTransaction:<Action>` — the colon is part of the hashed
+ * type, so it cannot be dropped. The SDK runs on whatever viem the app
+ * resolves, so it does not rely on the fix being installed. A local account therefore
+ * signs the EIP-712 digest built from viem's unvalidated `hashDomain` and
+ * `hashStruct`; any other account (a browser or embedded wallet) is sent the
+ * typed data as `eth_signTypedData_v4`, exactly as viem would send it.
+ */
+async function signHyperliquidTypedData(walletClient, account, domain, message) {
+    const types = { EIP712Domain: EIP712_DOMAIN_TYPE, ...SEND_TO_EVM_WITH_DATA_TYPES };
+    if (account.type === "local") {
+        const sign = account.sign;
+        if (!sign) {
+            throw new Error("The wallet's local account cannot sign a raw digest");
+        }
+        const digest = keccak256(concat([
+            "0x1901",
+            hashDomain({ domain: { ...domain, chainId: BigInt(domain.chainId) }, types: { EIP712Domain: EIP712_DOMAIN_TYPE } }),
+            hashStruct({ data: message, primaryType: PRIMARY_TYPE, types }),
+        ]));
+        return sign({ hash: digest });
+    }
+    return walletClient.request({
+        method: "eth_signTypedData_v4",
+        params: [account.address, serializeTypedData({ domain, message, primaryType: PRIMARY_TYPE, types })],
+    });
+}
+/**
+ * The suggestion every unknown outcome carries. Calling the method again signs
+ * a fresh nonce, so a retry after an executed withdrawal moves the funds twice.
+ */
+const UNKNOWN_OUTCOME_SUGGESTION = "Hyperliquid may have executed the withdrawal. Do not call depositFromHypercore again, which signs a second one: check sdk.sweeper.listDeposits (the deposit lists once it is minted on Sei) or the Hyperliquid balance first.";
+/** Clear `retryable` on an error whose outcome is unknown (see {@link UNKNOWN_OUTCOME_SUGGESTION}). */
+function unknownOutcome(error) {
+    error.retryable = false;
+    error.suggestion = UNKNOWN_OUTCOME_SUGGESTION;
+    return error;
+}
+/**
+ * Post a signed withdrawal to Hyperliquid's exchange endpoint.
+ *
+ * Hyperliquid answers a decided rejection with HTTP 200 and
+ * `{"status":"err","response":"<reason>"}`, so the status alone does not tell
+ * success from refusal. A refusal is a decided outcome (nothing moved); a
+ * dropped connection, a 5xx, or a reply that is neither `ok` nor `err` leaves
+ * the outcome unknown. The signed body is never attached to an error.
+ */
+export async function postToExchange(network, withdrawal) {
+    const endpoint = network.exchangeUrl;
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(withdrawal),
+        });
+    }
+    catch (error) {
+        throw unknownOutcome(new APIError(`Network request to Hyperliquid failed`, { endpoint, cause: error instanceof Error ? error : new Error(String(error)) }));
+    }
+    const text = await response.text().catch(() => "");
+    if (response.status >= 500) {
+        throw unknownOutcome(new APIError(`Hyperliquid answered ${response.status}`, { endpoint, statusCode: response.status, responseBody: text.slice(0, 500) }));
+    }
+    if (!response.ok) {
+        throw new APIError(`Hyperliquid refused the withdrawal: ${response.status}`, { endpoint, statusCode: response.status, responseBody: text.slice(0, 500) });
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    const status = body !== null && typeof body === "object" ? body.status : undefined;
+    if (status === "ok") {
+        return;
+    }
+    if (status === "err") {
+        const reason = body.response;
+        throw new APIError(`Hyperliquid rejected the withdrawal: ${typeof reason === "string" ? reason : JSON.stringify(reason)}`, {
+            endpoint,
+            statusCode: response.status,
+            responseBody: body,
+        });
+    }
+    throw unknownOutcome(new APIError("Hyperliquid's reply was not readable", { endpoint, statusCode: response.status, responseBody: text.slice(0, 500) }));
+}

package/dist/api/sweeper/hyperevm.d.ts

@@ -0,0 +1,50 @@
+/**
+ * USDC deposits from HyperEVM to a Sei deposit address.
+ *
+ * The wallet burns its Circle USDC on HyperEVM through Circle's
+ * TokenMessengerV2, naming the Sei deposit address as the mint recipient and
+ * attaching Circle's forwarding hook, so Circle mints on Sei
+ * (developers.circle.com/cctp/concepts/forwarding-service). The hub sweeps the
+ * mint like any deposit made straight to the address, so nothing of Monaco's
+ * runs on HyperEVM. The wallet pays HYPE for the approval and burn.
+ */
+import { type Address, type Hash, type WalletClient } from "viem";
+import { type HypercoreNetwork } from "./hypercore";
+/**
+ * Circle's forwarding fee for a HyperEVM-to-Sei transfer on the standard lane,
+ * at Circle's "high" level. Every forwarded transfer we sent was charged its
+ * whole `maxFee`, so the quote is used as is rather than padded; and a
+ * `maxFee` below the forwarding fee would leave the mint unforwarded, so the
+ * top of Circle's range is the safe choice.
+ */
+export declare function quoteForwardFee(network: HypercoreNetwork): Promise<bigint>;
+/** The wallet's Circle USDC, its allowance to TokenMessengerV2, and its HYPE, on HyperEVM. */
+export interface HyperEvmAccount {
+    usdc: bigint;
+    allowance: bigint;
+    gas: bigint;
+}
+export declare function readHyperEvmAccount(network: HypercoreNetwork, address: Address): Promise<HyperEvmAccount>;
+/**
+ * Approve (when the allowance is short) and burn `amount` of the wallet's
+ * HyperEVM USDC to `recipient` on Sei, with Circle forwarding the mint.
+ *
+ * Decided failures — nothing was burned — throw as they are: a wallet's
+ * refusal, a failure before the burn was broadcast, and a `ContractError` for
+ * a reverted, cancelled or replaced approval or burn. A burn that may have
+ * been broadcast but whose outcome cannot be read is an unknown outcome: the
+ * `APIError` carries `retryable: false` and, when known, the burn's hash,
+ * because calling again burns a second time. An approval in that state stays
+ * retryable, since the next call re-reads the allowance.
+ */
+export declare function burnToSei(params: {
+    walletClient: WalletClient;
+    network: HypercoreNetwork;
+    amount: bigint;
+    recipient: string;
+    maxFee: bigint;
+    allowance: bigint;
+}): Promise<{
+    approveTxHash?: Hash;
+    burnTxHash: Hash;
+}>;