@totalis/hip4-client 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 `@totalis/hip4-client` follows [semantic versioning](https://semver.org).
 The contract version the generated types come from is `sdkVersion` in `./version`.
 
+## 0.81.0
+
+### Added
+
+- `totalis.readComboCash()`: what one Combo can stake now, from one
+  `GET /v1/me/balances` read and the signer's HyperCore cash read from
+  Hyperliquid (TT-2572). It answers `vault`, `wallet`, `core` (spot USDC less
+  its hold), `coreMode`, `setupFee`, `offeredCore` and `allowance`, each `null`
+  when unknown. Pass it as `cash` and `offeredCore` as `core` to `openPosition`,
+  `signEntry` or `prepareEntryFunding`; `allowance` is the largest stake they
+  plan from it. A Portfolio Margin account offers no Core, as in the Totalis app.
+- `offeredCore(spendable, setupFee)` and `comboAllowance({ vault, wallet, core })`,
+  the same rule as plain functions.
+- `readCoreCash(network, account, info?)`, `hyperliquidInfo(fetch?)`,
+  `coreSetupFee` and `infoUrl` on `hyperliquidNetwork`, for reading HyperCore
+  cash yourself.
+
 ## 0.80.0
 
 ### Added

package/dist/client.d.ts

@@ -5,12 +5,12 @@ export type { components, operations, paths } from "./generated/client.js";
 export type { AccessToken, ApiClientOptions, PublicEnvironment } from "./base.js";
 /** The typed HTTP client for the `client` audience. `createTotalis` adds the flows. */
 export declare function createClient(environment: PublicEnvironment, options?: ApiClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;
-export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, type Acceptance, type AcceptanceResult, type Amount, type BridgeState, type CashoutBid, type Chooser, type Deployment, type DepositAccepted, type EntryCash, type EntryFailure, type EntryQuote, type CoreExit, type LegacySignedEntry, type Leg, type PreparedEntryFunding, type NotAdmitted, type RecordListener, type Operation, type Quote, type ResponseOf, type SellBackQuote, type SignedAcceptance, type SignedCashout, type SignedCoreExit, type SignedDeposit, type SignedEntry, type SignedReturnToCore, type Totalis, type TotalisOptions, type TransferQuote, type WalletCall, type Withdrawal, } from "./totalis.js";
-export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, type BridgedCash, type HypercoreAnswer, type HypercoreSignature, type HypercoreTransport, type HyperliquidNetwork, type SendAssetAction, type SignedSendAsset, } from "./hypercore.js";
+export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, type Acceptance, type AcceptanceResult, type Amount, type BridgeState, type ComboCash, type CashoutBid, type Chooser, type Deployment, type DepositAccepted, type EntryCash, type EntryFailure, type EntryQuote, type CoreExit, type LegacySignedEntry, type Leg, type PreparedEntryFunding, type NotAdmitted, type RecordListener, type Operation, type Quote, type ResponseOf, type SellBackQuote, type SignedAcceptance, type SignedCashout, type SignedCoreExit, type SignedDeposit, type SignedEntry, type SignedReturnToCore, type Totalis, type TotalisOptions, type TransferQuote, type WalletCall, type Withdrawal, } from "./totalis.js";
+export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, coreSetupFee, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidInfo, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, readCoreCash, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, type BridgedCash, type CoreAccountMode, type CoreCash, type HypercoreAnswer, type HyperliquidInfo, type HypercoreSignature, type HypercoreTransport, type HyperliquidNetwork, type SendAssetAction, type SignedSendAsset, } from "./hypercore.js";
 export { ApiError, envelope, NetworkError, randomBytes32, retryingFetch, sendOnce, unwrap, uuidv7, type Fetch, type Repaired, type RetryPolicy } from "./request.js";
 export { items, pages, type Page, type PageQuery } from "./pagination.js";
 export { toTotalisSigner, type SignerInput, type TotalisSigner } from "./signer.js";
 export { BalanceUnknownError, ExitUnavailableError, normalizeError, type NormalizedError } from "./flow-errors.js";
-export { netCashout, netOfProfitFee, netPayout, netStake, spendableCash } from "./money.js";
+export { comboAllowance, netCashout, netOfProfitFee, netPayout, netStake, offeredCore, spendableCash } from "./money.js";
 export { createUiAdapter, type AccountResource, type QuoteView, type UiAdapter, type UiAdapterOptions } from "./ui.js";
 export { StreamClosedError, TotalisStream, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscription } from "./stream.js";

package/dist/client.js

@@ -5,11 +5,11 @@ export function createClient(environment, options) {
     return audienceClient(environment, options);
 }
 export { bestBid, bestQuote, createTotalis, EntryError, entryFailure, follow, } from "./totalis.js";
-export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, } from "./hypercore.js";
+export { bridgeAction, bridgeGasBuffer, classifyHypercoreAnswer, coreSetupFee, hyperevmUsdcBridge, hyperliquidExchange, hyperliquidInfo, hyperliquidNetwork, hypercoreNonce, hypercoreSignature, readCoreCash, sendAssetTypedData, settleHypercore, signSendAsset, submitHypercore, usdcText, } from "./hypercore.js";
 export { ApiError, envelope, NetworkError, randomBytes32, retryingFetch, sendOnce, unwrap, uuidv7 } from "./request.js";
 export { items, pages } from "./pagination.js";
 export { toTotalisSigner } from "./signer.js";
 export { BalanceUnknownError, ExitUnavailableError, normalizeError } from "./flow-errors.js";
-export { netCashout, netOfProfitFee, netPayout, netStake, spendableCash } from "./money.js";
+export { comboAllowance, netCashout, netOfProfitFee, netPayout, netStake, offeredCore, spendableCash } from "./money.js";
 export { createUiAdapter } from "./ui.js";
 export { StreamClosedError, TotalisStream } from "./stream.js";

package/dist/hypercore.d.ts

@@ -5,6 +5,7 @@ export type HyperliquidNetwork = {
     /** The signing domain chain the HyperEVM bridge names: the deployment's own chain. */
     readonly signatureChainId: Hex;
     readonly exchangeUrl: string;
+    readonly infoUrl: string;
     readonly usdcToken: string;
 };
 export declare function hyperliquidNetwork(chainId: string | number): HyperliquidNetwork;
@@ -109,3 +110,27 @@ export declare function settleHypercore(signed: SignedSendAsset, options?: {
     readonly now?: () => number;
     readonly retryDelayMs?: number;
 }): Promise<HypercoreAnswer>;
+/** A read of Hyperliquid's `/info` on one network: the request body in, the answer's JSON out. */
+export type HyperliquidInfo = (network: HyperliquidNetwork, body: Readonly<Record<string, unknown>>, signal?: AbortSignal) => Promise<unknown>;
+/** POST to the network's `/info`. A non-2xx answer or a body that is not JSON throws. */
+export declare function hyperliquidInfo(fetchImpl?: typeof fetch): HyperliquidInfo;
+/** Hyperliquid's one-time account setup fee, in USDC base units, taken on top of an account's first send out when it was funded without paying it. */
+export declare const coreSetupFee = 1000000n;
+/** The account mode Hyperliquid's `userAbstraction` names; `null` for one this SDK does not know. */
+export type CoreAccountMode = "STANDARD" | "UNIFIED" | "PORTFOLIO_MARGIN";
+/**
+ * The account's HyperCore USDC as a Combo can bridge it, read from
+ * Hyperliquid. `spendable` is spot USDC `total` less `hold`, then floored
+ * to USDC base units (6 decimals); `hold` already carries order holds and
+ * position margin. A Portfolio Margin account offers none, as in the Totalis
+ * app. `setupFee` says whether a bridge from it also pays `coreSetupFee`; it is
+ * read only when there is something to bridge. Each is `null` when unread or
+ * unreadable, never 0.
+ */
+export type CoreCash = {
+    readonly mode: CoreAccountMode | null;
+    readonly spendable: bigint | null;
+    readonly setupFee: boolean | null;
+};
+/** Read `account`'s `CoreCash` on `network`. A failed or malformed read leaves its fields `null`; it never throws. */
+export declare function readCoreCash(network: HyperliquidNetwork, account: string, info?: HyperliquidInfo, signal?: AbortSignal): Promise<CoreCash>;

package/dist/hypercore.js

@@ -1,8 +1,8 @@
 import { sleep } from "./request.js";
 import { canonicalSignature } from "./typed-data.js";
 const networks = {
-    "999": { chain: "Mainnet", signatureChainId: "0x3e7", exchangeUrl: "https://api.hyperliquid.xyz/exchange", usdcToken: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054" },
-    "998": { chain: "Testnet", signatureChainId: "0x3e6", exchangeUrl: "https://api.hyperliquid-testnet.xyz/exchange", usdcToken: "USDC:0xeb62eee3685fc4c43992febcd9e75443" },
+    "999": { chain: "Mainnet", signatureChainId: "0x3e7", exchangeUrl: "https://api.hyperliquid.xyz/exchange", infoUrl: "https://api.hyperliquid.xyz/info", usdcToken: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054" },
+    "998": { chain: "Testnet", signatureChainId: "0x3e6", exchangeUrl: "https://api.hyperliquid-testnet.xyz/exchange", infoUrl: "https://api.hyperliquid-testnet.xyz/info", usdcToken: "USDC:0xeb62eee3685fc4c43992febcd9e75443" },
 };
 export function hyperliquidNetwork(chainId) {
     const key = String(chainId);
@@ -130,3 +130,77 @@ export async function settleHypercore(signed, options = {}) {
             return { kind: "unknown" };
     }
 }
+/** POST to the network's `/info`. A non-2xx answer or a body that is not JSON throws. */
+export function hyperliquidInfo(fetchImpl = (input, init) => globalThis.fetch(input, init)) {
+    return async (network, body, signal) => {
+        const response = await fetchImpl(network.infoUrl, {
+            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (!response.ok)
+            throw new Error(`Hyperliquid info answered ${response.status}`);
+        const answer = JSON.parse(await response.text());
+        return answer;
+    };
+}
+/** Hyperliquid's one-time account setup fee, in USDC base units, taken on top of an account's first send out when it was funded without paying it. */
+export const coreSetupFee = 1000000n;
+const decimalText = /^\d+(\.\d+)?$/;
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function coreMode(answer) {
+    if (answer === "default" || answer === "disabled")
+        return "STANDARD";
+    if (answer === "unifiedAccount")
+        return "UNIFIED";
+    if (answer === "portfolioMargin")
+        return "PORTFOLIO_MARGIN";
+    return null;
+}
+/** Spot decimal text (8 decimals) as integer units, or `null` past 8 decimals. */
+function spotUnits(text) {
+    const [whole = "0", fraction = ""] = text.split(".");
+    return fraction.length > 8 ? null : BigInt(whole) * 100000000n + BigInt(fraction.padEnd(8, "0"));
+}
+/**
+ * Spot USDC `total` less `hold`, exact in spot's 8 decimals and only then
+ * floored to USDC base units, so the sub-unit parts never round it up.
+ * `null` when the answer is malformed: two USDC entries, or a hold above the
+ * total. An account with no USDC entry holds none.
+ */
+function spotUsdc(answer) {
+    if (!record(answer) || !Array.isArray(answer.balances))
+        return null;
+    const entries = answer.balances.filter((entry) => record(entry) && entry.coin === "USDC");
+    if (entries.length === 0)
+        return 0n;
+    const [usdc] = entries;
+    if (entries.length > 1 || !record(usdc) || typeof usdc.total !== "string" || typeof usdc.hold !== "string" || !decimalText.test(usdc.total) || !decimalText.test(usdc.hold))
+        return null;
+    const total = spotUnits(usdc.total);
+    const hold = spotUnits(usdc.hold);
+    if (total === null || hold === null || hold > total)
+        return null;
+    return (total - hold) / 100n;
+}
+/** Whether `preTransferCheck` charges the setup fee: its `fee` is exactly 0 or exactly `coreSetupFee`; anything else is `null`. */
+function setupFeeCharged(answer) {
+    if (!record(answer) || typeof answer.fee !== "string" || !decimalText.test(answer.fee))
+        return null;
+    const fee = spotUnits(answer.fee);
+    return fee === 0n ? false : fee === coreSetupFee * 100n ? true : null;
+}
+const settledValue = (result) => (result.status === "fulfilled" ? result.value : undefined);
+/** Read `account`'s `CoreCash` on `network`. A failed or malformed read leaves its fields `null`; it never throws. */
+export async function readCoreCash(network, account, info = hyperliquidInfo(), signal) {
+    const [modeRead, spotRead] = await Promise.allSettled([
+        info(network, { type: "userAbstraction", user: account }, signal),
+        info(network, { type: "spotClearinghouseState", user: account }, signal),
+    ]);
+    const mode = coreMode(settledValue(modeRead));
+    const spot = spotUsdc(settledValue(spotRead));
+    const spendable = mode === null || spot === null ? null : mode === "PORTFOLIO_MARGIN" ? 0n : spot;
+    if (spendable === null || spendable === 0n)
+        return { mode, spendable, setupFee: null };
+    const check = await info(network, { type: "preTransferCheck", user: hyperevmUsdcBridge, source: account }, signal).then(setupFeeCharged, () => null);
+    return { mode, spendable, setupFee: check };
+}

package/dist/money.d.ts

@@ -26,6 +26,24 @@ export declare function spendableCash(balance: Pick<Balance, "amount" | "state"
     readonly wallet: bigint | null;
     readonly total: bigint | null;
 };
+/**
+ * The HyperCore USDC a Combo offers its bridge (`core` for `openPosition`,
+ * `signEntry` and `prepareEntryFunding`): all of `spendable`, less
+ * `coreSetupFee` when the bridge also pays it. `null` while either is unknown
+ * and there is Core to bridge.
+ */
+export declare function offeredCore(spendable: bigint | null, setupFee: boolean | null): bigint | null;
+/**
+ * The largest stake one Combo can take now, in USDC base units, as an entry
+ * plans its funding: free vault cash, then available wallet USDC, then a
+ * bridge of the offered Core less `bridgeGasBuffer`. `null` when any part is
+ * unknown, never a partial sum.
+ */
+export declare function comboAllowance(cash: {
+    readonly vault: bigint | null;
+    readonly wallet: bigint | null;
+    readonly core: bigint | null;
+}): bigint | null;
 /**
  * What the owner receives from a gross close amount (a settlement payout or a
  * sell-back price), as the vault pays it: the profit fee is

package/dist/money.js

@@ -1,3 +1,4 @@
+import { bridgeGasBuffer, coreSetupFee } from "./hypercore.js";
 const bps = 10000n;
 /**
  * Spendable Totalis cash from `GET /v1/me/balances`, in USDC base units, as
@@ -25,6 +26,31 @@ export function spendableCash(balance) {
         total: balance.state === "CURRENT" && balance.amount !== null ? BigInt(balance.amount) : null,
     };
 }
+/**
+ * The HyperCore USDC a Combo offers its bridge (`core` for `openPosition`,
+ * `signEntry` and `prepareEntryFunding`): all of `spendable`, less
+ * `coreSetupFee` when the bridge also pays it. `null` while either is unknown
+ * and there is Core to bridge.
+ */
+export function offeredCore(spendable, setupFee) {
+    if (spendable === null || spendable === 0n || setupFee === false)
+        return spendable;
+    if (setupFee === null)
+        return null;
+    return spendable > coreSetupFee ? spendable - coreSetupFee : 0n;
+}
+/**
+ * The largest stake one Combo can take now, in USDC base units, as an entry
+ * plans its funding: free vault cash, then available wallet USDC, then a
+ * bridge of the offered Core less `bridgeGasBuffer`. `null` when any part is
+ * unknown, never a partial sum.
+ */
+export function comboAllowance(cash) {
+    const { vault, wallet, core } = cash;
+    if (vault === null || wallet === null || core === null)
+        return null;
+    return vault + wallet + (core > bridgeGasBuffer ? core - bridgeGasBuffer : 0n);
+}
 /**
  * What the owner receives from a gross close amount (a settlement payout or a
  * sell-back price), as the vault pays it: the profit fee is

package/dist/totalis.d.ts

@@ -1,7 +1,7 @@
 import { issueApiKey, rotateApiKey } from "./api-keys.js";
 import { type AccessToken, type ApiClientOptions, type PublicEnvironment } from "./base.js";
 import type { paths } from "./generated/client.js";
-import { type BridgedCash, type HypercoreAnswer, type HypercoreTransport, type SignedSendAsset } from "./hypercore.js";
+import { type BridgedCash, type CoreAccountMode, type HypercoreAnswer, type HypercoreTransport, type HyperliquidInfo, type SignedSendAsset } from "./hypercore.js";
 import { BalanceUnknownError, EntryError, ExitUnavailableError } from "./flow-errors.js";
 import { ApiError, NetworkError, type RetryPolicy } from "./request.js";
 import { type SignerInput } from "./signer.js";
@@ -69,6 +69,23 @@ export type EntryCash = {
     readonly wallet: Amount | null;
 };
 export type DepositAccepted = Ok<"/v1/me/deposits", "post", 202>;
+/**
+ * What one Combo can stake, from the venue balances and the account's
+ * HyperCore cash, in USDC base units (`readComboCash`). `vault` and `wallet`
+ * are `spendableCash`'s; `core` is HyperCore spot USDC less its hold;
+ * `setupFee` whether a bridge from it pays Hyperliquid's one-time setup fee;
+ * `offeredCore` what an entry may bridge (`offeredCore`); `allowance` the
+ * largest stake (`comboAllowance`). Each is `null` when unknown, never 0.
+ */
+export type ComboCash = {
+    readonly vault: bigint | null;
+    readonly wallet: bigint | null;
+    readonly coreMode: CoreAccountMode | null;
+    readonly core: bigint | null;
+    readonly setupFee: boolean | null;
+    readonly offeredCore: bigint | null;
+    readonly allowance: bigint | null;
+};
 /** Who signed an acceptance record, and for which vault; a record is only sent or recovered by the same account on the same deployment. */
 type RecordScope = {
     readonly acceptanceId: string;
@@ -263,6 +280,10 @@ export declare function createTotalis(options: TotalisOptions): {
         readonly wallet: bigint | null;
         readonly total: bigint | null;
     }>;
+    readComboCash: (options?: {
+        readonly info?: HyperliquidInfo;
+        readonly signal?: AbortSignal;
+    }) => Promise<ComboCash>;
     openPosition: (request: {
         readonly legs: readonly Leg[];
         readonly stake: Amount;

package/dist/totalis.js

@@ -1,9 +1,9 @@
 import { keccak_256 } from "@noble/hashes/sha3";
 import { createApiKeyClient, issueApiKey, rotateApiKey } from "./api-keys.js";
 import { audienceClient, headerRecord } from "./base.js";
-import { bridgeAction, bridgeGasBuffer, hyperliquidExchange, hyperliquidNetwork, settleHypercore, signSendAsset, usdcUnits, } from "./hypercore.js";
+import { bridgeAction, bridgeGasBuffer, hyperliquidExchange, hyperliquidNetwork, readCoreCash, settleHypercore, signSendAsset, usdcUnits, } from "./hypercore.js";
 import { BalanceUnknownError, EntryError, ExitUnavailableError, normalizeError } from "./flow-errors.js";
-import { spendableCash } from "./money.js";
+import { comboAllowance, offeredCore, spendableCash } from "./money.js";
 import { ApiError, backoffDelay, envelope, NetworkError, randomBytes32, resendable, retryingFetch, sendOnce, singleFetch, sleep, unwrap, uuidv7 } from "./request.js";
 import { toTotalisSigner } from "./signer.js";
 import { TotalisStream } from "./stream.js";
@@ -433,6 +433,26 @@ export function createTotalis(options) {
     async function readSpendableCash(signal) {
         return spendableCash(unwrap(await client.GET("/v1/me/balances", signal === undefined ? {} : { signal })));
     }
+    /**
+     * The account's Combo cash now (`ComboCash`): one venue balances read and
+     * the signer's HyperCore cash read from Hyperliquid, together. Pass `cash`
+     * and `offeredCore` straight to `openPosition` (`cash`, `core`) so the entry
+     * plans from what was shown. A failed HyperCore read leaves its fields
+     * `null`; a failed balances read throws, as `spendableCash` does. `info`
+     * replaces the Hyperliquid read, for tests or a proxy.
+     */
+    async function readComboCash(options = {}) {
+        const [account, chain] = await Promise.all([(async () => (await requireSigner()).address())(), deployment()]);
+        const [venue, core] = await Promise.all([
+            readSpendableCash(options.signal),
+            readCoreCash(hyperliquidNetwork(chain.chain_id), account, options.info, options.signal),
+        ]);
+        const offered = offeredCore(core.spendable, core.setupFee);
+        return {
+            vault: venue.vault, wallet: venue.wallet, coreMode: core.mode, core: core.spendable, setupFee: core.setupFee,
+            offeredCore: offered, allowance: comboAllowance({ vault: venue.vault, wallet: venue.wallet, core: offered }),
+        };
+    }
     /** The wallet's USDC authorization of `value` into the vault; the venue fills `account` and `from` with the same wallet. */
     async function depositAuthorization(chain, account, value) {
         const authorization = { value: value.toString(), valid_after: String(now() - 60), valid_before: String(now() + 600), salt: randomBytes32() };
@@ -1360,6 +1380,7 @@ export function createTotalis(options) {
         deployment,
         /** Spendable Totalis cash from a fresh balances read (`spendableCash`): `{ vault, wallet, total }`, each `null` while unknown, never 0. */
         spendableCash: readSpendableCash,
+        readComboCash,
         openPosition,
         cashOut,
         prepareEntryFunding,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalis/hip4-client",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "description": "Totalis HIP-4 SDK: typed HTTP clients, signer-agnostic typed data, a retrying request layer, pagination, a realtime stream and taker/maker flows",
   "type": "module",
   "files": [