aftermath-ts-sdk 1.3.23-perps.34 → 1.3.23-perps.36

package/dist/packages/perpetuals/perpetualsAccount.js

@@ -25,7 +25,20 @@ const caller_1 = require("../../general/utils/caller");
 const utils_1 = require("../../general/utils");
 const perpetuals_1 = require("./perpetuals");
 const transactions_1 = require("@mysten/sui/transactions");
-// TODO: create refresh account positions function ?
+/**
+ * Note on “refreshing” account state:
+ *
+ * This class is a thin wrapper around a snapshot of {@link PerpetualsAccountObject}
+ * that is typically fetched via {@link Perpetuals.getAccount}. The transaction builders
+ * use the current snapshot to derive fields like `hasPosition` and to construct
+ * SL/TP helpers that depend on the position side.
+ *
+ * If your app is long-lived, you may want to periodically re-fetch the account
+ * (and recreate this wrapper) to avoid stale local position/order state. For example:
+ * - After placing/canceling orders
+ * - After fills/liquidations/funding settlements
+ * - After switching markets or wallets
+ */
 /**
  * High-level wrapper around a single Perpetuals account or vault account.
  *
@@ -110,11 +123,11 @@ class PerpetualsAccount extends caller_1.Caller {
      * @param inputs.depositCoinArg - Transaction object argument referencing a
      *   coin to deposit (mutually exclusive with `depositAmount`).
      *
-     * @returns Transaction response containing a serialized `txKind`.
+     * @returns Transaction response containing a `tx`.
      *
      * @example
      * ```ts
-     * const { txKind } = await account.getDepositCollateralTx({
+     * const { tx } = await account.getDepositCollateralTx({
      *   depositAmount: BigInt("1000000000"),
      * });
      * ```
@@ -147,12 +160,12 @@ class PerpetualsAccount extends caller_1.Caller {
      *   coins directly.
      * @param inputs.tx - Optional transaction to extend (defaults to new `Transaction()`).
      *
-     * @returns A response containing `txKind` and the `coinOutArg` where the
+     * @returns A response containing `tx` and the `coinOutArg` where the
      *   withdrawn coins end up if `recipientAddress` is not used.
      *
      * @example
      * ```ts
-     * const { txKind, coinOutArg } = await account.getWithdrawCollateralTx({
+     * const { tx, coinOutArg } = await account.getWithdrawCollateralTx({
      *   withdrawAmount: BigInt("1000000000"),
      * });
      * ```
@@ -186,7 +199,7 @@ class PerpetualsAccount extends caller_1.Caller {
      * @param inputs.allocateAmount - Amount of collateral to allocate.
      * @param inputs.tx - Optional transaction to extend.
      *
-     * @returns Transaction response containing a serialized `txKind`.
+     * @returns Transaction response containing a `tx`.
      */
     getAllocateCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -217,7 +230,7 @@ class PerpetualsAccount extends caller_1.Caller {
      * @param inputs.deallocateAmount - Amount of collateral to deallocate.
      * @param inputs.tx - Optional transaction to extend.
      *
-     * @returns Transaction response containing a serialized `txKind`.
+     * @returns Transaction response containing a `tx`.
      */
     getDeallocateCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -247,7 +260,7 @@ class PerpetualsAccount extends caller_1.Caller {
      * @param inputs.toAccountId - Destination account ID.
      * @param inputs.tx - Optional transaction to extend.
      *
-     * @returns Transaction response containing a serialized `txKind`.
+     * @returns Transaction response containing a `tx`.
      */
     getTransferCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -279,6 +292,12 @@ class PerpetualsAccount extends caller_1.Caller {
      * - Derives `hasPosition` based on the current account state for the given market.
      * - Optionally attaches SL/TP stop orders via the `slTp` input.
      *
+     * Important behavioral notes:
+     * - `hasPosition` is derived from the local {@link PerpetualsAccountObject} snapshot.
+     *   If the snapshot is stale, consider re-fetching the account first.
+     * - For vault-backed accounts, the API routes to `/perpetuals/vault/...` and uses
+     *   `vaultId` as the identity discriminator. For direct accounts, it uses `accountId`.
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceMarketOrderInputs} for details.
      *   Notably:
      *   - `marketId`, `side`, `size`, `collateralChange`, `reduceOnly`
@@ -286,11 +305,11 @@ class PerpetualsAccount extends caller_1.Caller {
      *   - Optional `slTp` params
      *   - Optional `tx` to extend
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      *
      * @example
      * ```ts
-     * const { txKind } = await account.getPlaceMarketOrderTx({
+     * const { tx } = await account.getPlaceMarketOrderTx({
      *   marketId: "0x...",
      *   side: PerpetualsOrderSide.Bid,
      *   size: BigInt("1000000000"),
@@ -327,9 +346,14 @@ class PerpetualsAccount extends caller_1.Caller {
      * - Requires `price` and `orderType`.
      * - Supports reduce-only flags, expiry, optional leverage, and SL/TP stop orders.
      *
+     * Notes:
+     * - `hasPosition` is derived from local account state; refresh the account if needed.
+     * - This method does not validate tick/lot sizing locally; the API/on-chain
+     *   will enforce market constraints.
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderInputs}.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getPlaceLimitOrderTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -355,13 +379,21 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Build a `cancel-orders` transaction for this account.
      *
+     * Each market in `marketIdsToData` supplies:
+     * - `orderIds`: the orders to cancel in that market
+     * - `collateralChange`: collateral adjustment to apply alongside cancellation
+     * - `leverage`: leverage context used for estimating/validating constraints server-side
+     *
+     * Notes:
+     * - Cancels are applied per market; some markets may succeed while others fail
+     *   depending on API/on-chain validation (returned as a transaction failure at execution).
+     * - If you need to understand the effect prior to building a tx, use
+     *   {@link getCancelOrdersPreview}.
+     *
      * @param inputs.tx - Optional transaction to extend.
-     * @param inputs.marketIdsToData - Mapping from market IDs to:
-     *   - `orderIds`: order IDs to cancel
-     *   - `collateralChange`: net collateral impact (if any)
-     *   - `leverage`: current leverage used for estimating effects
+     * @param inputs.marketIdsToData - Mapping from market IDs to cancel payloads.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getCancelOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -384,10 +416,13 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Build a `cancel-stop-orders` transaction for this account.
      *
+     * This cancels stop-order *objects/tickets* by their object IDs. These IDs are
+     * returned by stop-order query endpoints (see {@link getStopOrderDatas}).
+     *
      * @param inputs.tx - Optional transaction to extend.
      * @param inputs.stopOrderIds - Array of stop-order ticket IDs to cancel.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getCancelStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -413,9 +448,14 @@ class PerpetualsAccount extends caller_1.Caller {
      * This allows placing one or more stop orders in a single transaction,
      * optionally with a dedicated gas coin and a sponsored gas flag.
      *
+     * Typical usage:
+     * - Construct stop order payload(s) client-side
+     * - Call this method to build a transaction kind
+     * - Sign/execute the transaction via Sui
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceStopOrdersInputs}.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getPlaceStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -446,9 +486,14 @@ class PerpetualsAccount extends caller_1.Caller {
      * in a given market. If the account has no position for `marketId`, this
      * throws an error.
      *
+     * Implementation details:
+     * - Determines the current position side from the account snapshot.
+     * - Sets `positionSide` for the API so SL/TP orders are bound to closing logic
+     *   (i.e. they should trigger on the opposite side of the open position).
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceSlTpOrdersInputs}.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getPlaceSlTpOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -480,10 +525,15 @@ class PerpetualsAccount extends caller_1.Caller {
      *
      * This endpoint lets you update existing stop orders in batch.
      *
+     * Notes:
+     * - You must provide the full updated stop-order objects (including object IDs).
+     * - This is typically used to adjust trigger prices, sizes, expiries, or the
+     *   embedded limit-order parameters.
+     *
      * @param inputs.stopOrders - Full updated stop-order payloads to apply.
      * @param inputs.tx - Optional transaction to extend.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getEditStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -548,13 +598,18 @@ class PerpetualsAccount extends caller_1.Caller {
      * This updates the effective leverage for the position (or potential position)
      * in `marketId`, and optionally adjusts collateral in tandem.
      *
+     * Notes:
+     * - Leverage changes may be constrained by protocol risk limits and current
+     *   position state.
+     * - If you want to understand the effect first, use {@link getSetLeveragePreview}.
+     *
      * @param inputs.tx - Optional transaction to extend.
      * @param inputs.leverage - Target leverage value.
      * @param inputs.collateralChange - Net collateral change to apply alongside
      *   the leverage update.
      * @param inputs.marketId - Market whose leverage to adjust.
      *
-     * @returns Transaction response containing `txKind`.
+     * @returns Transaction response containing `tx`.
      */
     getSetLeverageTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -601,6 +656,12 @@ class PerpetualsAccount extends caller_1.Caller {
      * This payload is intended to be signed off-chain and then submitted to
      * `getStopOrderDatas` as a proof of account ownership.
      *
+     * Important:
+     * - The returned payload is *not* a Sui transaction; it is an off-chain
+     *   “authentication” message.
+     * - The backend expects `account_id` to be a decimal string. This code
+     *   normalizes the bigint `accountId` by stripping the trailing `n`.
+     *
      * @param inputs.marketIds - Optional list of market IDs to scope the query.
      *
      * @returns An object describing the action and account/market IDs, suitable
@@ -659,6 +720,9 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Preview the effects of placing a market order (without building a tx).
      *
+     * This is a read-only API call that runs the protocol’s pricing / margin /
+     * slippage logic against the current market state and your account/vault context.
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceMarketOrderPreviewInputs}.
      * @param abortSignal - Optional `AbortSignal` to cancel the request.
      *
@@ -687,6 +751,11 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Preview the effects of placing a limit order (without building a tx).
      *
+     * The preview simulates:
+     * - How much size would execute immediately vs post to the book
+     * - Expected slippage and execution price
+     * - Resulting position and margin impact
+     *
      * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
      * @param abortSignal - Optional `AbortSignal` to cancel the request.
      *
@@ -710,15 +779,19 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Preview the effects of canceling orders across one or more markets.
      *
+     * This is commonly used to:
+     * - Validate that cancels are allowed under current margin constraints
+     * - Estimate how collateral/margin would change after canceling (and applying
+     *   the associated `collateralChange` values)
+     *
      * If `marketIdsToData` is empty, this returns a trivial preview with:
-     * - `collateralChange: 0`
-     * - `updatedPositions: []`
+     * - `marketIdsToData: {}`
      *
      * @param inputs - See {@link SdkPerpetualsCancelOrdersPreviewInputs}.
      * @param abortSignal - Optional `AbortSignal` to cancel the request.
      *
      * @returns Either:
-     * - `{ updatedPositions, collateralChange }`, or
+     * - `{ marketIdsToData }`, or
      * - `{ error }`.
      */
     getCancelOrdersPreview(inputs, abortSignal) {
@@ -779,6 +852,10 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Preview the effects of setting leverage for a given market.
      *
+     * The preview returns:
+     * - The position after the leverage change (`updatedPosition`)
+     * - The collateral delta required/produced (`collateralChange`)
+     *
      * @param inputs.marketId - Market whose leverage you want to adjust.
      * @param inputs.leverage - Target leverage value.
      * @param abortSignal - Optional `AbortSignal` to cancel the request.
@@ -806,6 +883,10 @@ class PerpetualsAccount extends caller_1.Caller {
      * Preview the effects of allocating/deallocating collateral for the position in
      * a given market.
      *
+     * Semantics:
+     * - Positive `collateralChange` previews allocation (moving collateral into the market).
+     * - Negative `collateralChange` previews deallocation (moving collateral out of the market).
+     *
      * @param inputs.marketId - Market of whose position you want to allocate/deallocate
      * collateral to/from.
      * @param inputs.collateralChange - The target collateral change (a positive number
@@ -874,8 +955,12 @@ class PerpetualsAccount extends caller_1.Caller {
      * This is especially useful after a long-running session where on-chain
      * pending orders may have changed relative to the local `account` state.
      *
-     * @returns Array of {@link PerpetualsOrderData} describing each pending order.
-     *   Returns `[]` if there are no pending orders.
+     * The request payload is derived from this instance’s current snapshot:
+     * - It enumerates `account.positions[].pendingOrders`
+     * - Sends each `{ orderId, currentSize }` to the API to resolve canonical order data
+     *
+     * @returns {@link ApiPerpetualsAccountOrderDatasResponse} containing an `orderDatas`
+     * array. Returns `{ orderDatas: [] }` if there are no pending orders.
      */
     getOrderDatas() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -900,12 +985,16 @@ class PerpetualsAccount extends caller_1.Caller {
      * Fetch stop-order ticket data for this account, using an off-chain signed
      * payload.
      *
-     * @param inputs.bytes - Serialized message that was signed (e.g. from
-     *   {@link getStopOrdersMessageToSign}).
+     * Typical flow:
+     * 1) Call {@link getStopOrdersMessageToSign} to construct a deterministic payload
+     * 2) Sign the payload with the wallet
+     * 3) Provide the signed payload to this method to fetch stop order data
+     *
+     * @param inputs.bytes - Serialized message that was signed (e.g. JSON string).
      * @param inputs.signature - Signature over `bytes`.
      * @param inputs.marketIds - Optional subset of markets to filter results by.
      *
-     * @returns Array of {@link PerpetualsStopOrderData}.
+     * @returns {@link ApiPerpetualsStopOrderDatasResponse} containing `stopOrderDatas`.
      */
     getStopOrderDatas(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -926,11 +1015,15 @@ class PerpetualsAccount extends caller_1.Caller {
      * Fetch paginated collateral-change history for this account, including
      * deposits, withdrawals, funding settlements, liquidations, etc.
      *
+     * Pagination:
+     * - Use `beforeTimestampCursor` to fetch older entries.
+     * - The API returns a `nextBeforeTimestampCursor` to continue pagination.
+     *
      * @param inputs.beforeTimestampCursor - Optional cursor for pagination.
      * @param inputs.limit - Optional limit per page.
      *
      * @returns {@link ApiPerpetualsAccountCollateralHistoryResponse} containing
-     *   an array of changes and a `nextBeforeTimestampCursor`.
+     * an array of changes and a `nextBeforeTimestampCursor`.
      */
     getCollateralHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -940,18 +1033,39 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Fetch paginated order history for this account.
      *
+     * This endpoint is distinct from {@link getOrderDatas}:
+     * - `getOrderDatas` resolves current/pending orders based on the snapshot.
+     * - `getOrderHistory` returns historical order events (fills, cancels, etc.)
+     *   over time with cursor-based pagination.
+     *
      * @param inputs.beforeTimestampCursor - Optional cursor for pagination.
      * @param inputs.limit - Optional limit per page.
      *
      * @returns {@link ApiPerpetualsAccountOrderHistoryResponse} containing a list of
-     *   orders and a `nextBeforeTimestampCursor`.
+     * orders and a `nextBeforeTimestampCursor`.
      */
     getOrderHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/order-history", Object.assign(Object.assign({}, inputs), { accountId: this.accountCap.accountId }));
         });
     }
-    // TODO: docs
+    /**
+     * Fetch historical margin snapshots for this account over a time range.
+     *
+     * This endpoint returns time-series margin data suitable for charting UI
+     * such as equity and available collateral over time.
+     *
+     * Inputs:
+     * - `fromTimestamp` / `toTimestamp` are Unix timestamps in **milliseconds**.
+     * - `intervalMs` controls the resolution (e.g. 60_000 for 1-minute points).
+     *
+     * Notes:
+     * - Returned points are typically aligned to the requested interval.
+     * - This is an account-level view (aggregated across markets).
+     *
+     * @param inputs - {@link ApiPerpetualsAccountMarginHistoryBody} without `accountId`.
+     * @returns {@link ApiPerpetualsAccountMarginHistoryResponse} containing `marginHistoryDatas`.
+     */
     getMarginHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/margin-history", Object.assign(Object.assign({}, inputs), { accountId: this.accountCap.accountId }));
@@ -988,6 +1102,10 @@ class PerpetualsAccount extends caller_1.Caller {
      * A stop order is considered SL/TP if it appears in the combined set of
      * SL/TP orders across **all** markets (see {@link slTpStopOrderDatas}).
      *
+     * Note:
+     * - This implementation uses JSON string equality to compare objects.
+     *   This is pragmatic but assumes stable field ordering and identical shapes.
+     *
      * @param inputs.stopOrderDatas - Full array of stop-order ticket data.
      * @returns An array of non-SL/TP stop orders, or `undefined` if none exist.
      */
@@ -1011,6 +1129,9 @@ class PerpetualsAccount extends caller_1.Caller {
      * - "Full" SL/TP orders (size >= `i64MaxBigInt`)
      * - "Partial" SL/TP orders (size < `i64MaxBigInt`)
      *
+     * The "full vs partial" distinction is a protocol convention: some systems
+     * encode “close entire position” using a sentinel max size.
+     *
      * @param inputs.stopOrderDatas - Full list of stop-order tickets.
      * @returns Array of SL/TP stop orders, or `undefined` if none exist.
      */
@@ -1064,6 +1185,10 @@ class PerpetualsAccount extends caller_1.Caller {
      * - Order side is opposite of the position side.
      * - At least a `stopLossIndexPrice` or `takeProfitIndexPrice` is set.
      *
+     * Notes on matching:
+     * - The side comparison uses the current position side derived from the account snapshot.
+     * - If `baseAssetAmount === 0` (no effective position), the method returns no SL/TP orders.
+     *
      * @param inputs.marketId - Market to categorize stop orders for.
      * @param inputs.stopOrderDatas - Full list of stop orders.
      *
@@ -1081,7 +1206,14 @@ class PerpetualsAccount extends caller_1.Caller {
             };
         }
         const side = !position ? undefined : perpetuals_1.Perpetuals.positionSide(position);
-        // TODO: clean this up
+        /**
+         * Implementation note:
+         *
+         * This method uses a pair of predicates that differ only by the `size` threshold
+         * to split “full close” SL/TP from “partial close” SL/TP. The sentinel threshold
+         * is {@link Casting.i64MaxBigInt}. Keeping the logic explicit (rather than
+         * abstracting into helpers) makes it easier to reason about protocol conventions.
+         */
         const fullSlTpOrder = stopOrderDatas.find((order) => order.marketId === marketId &&
             order.slTp &&
             order.side !== side &&
@@ -1102,6 +1234,9 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Convenience accessor for the account's available collateral (in coin units).
      *
+     * This is the amount of collateral not currently locked/allocated across markets,
+     * as represented by the backend response.
+     *
      * @returns Available collateral as a `number`.
      */
     collateral() {
@@ -1127,20 +1262,26 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Resolve the owner wallet address of this account or vault.
      *
-     * - For direct accounts, returns the `walletAddress` field.
-     * - For vault-backed accounts, returns `ownerAddress`.
+     * - For direct accounts, returns the cap's `walletAddress` field.
+     * - For vault-backed accounts, returns the vault cap's `ownerAddress`.
+     *
+     * Naming note:
+     * - Some types use `walletAddress` for direct ownership. For vault-backed accounts
+     *   the analogous field is `ownerAddress`.
      *
      * @returns Owner wallet {@link SuiAddress}.
      */
     ownerAddress() {
         return "walletAddress" in this.accountCap
-            ? // TODO: change to ownerAddress ?
+            ? // NOTE: direct accounts expose `walletAddress`; vault accounts expose `ownerAddress`.
                 this.accountCap.walletAddress
             : this.accountCap.ownerAddress;
     }
     /**
      * Get the underlying account object ID.
      *
+     * This is the on-chain object that holds the account's state and positions.
+     *
      * @returns {@link ObjectId} of the account object.
      */
     accountObjectId() {
@@ -1149,6 +1290,8 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Get the numeric perpetuals account ID.
      *
+     * This is the protocol-level identifier (bigint-derived) used across API calls.
+     *
      * @returns {@link PerpetualsAccountId} for this account.
      */
     accountId() {
@@ -1157,12 +1300,13 @@ class PerpetualsAccount extends caller_1.Caller {
     /**
      * Get the account cap object ID, if this is a direct account.
      *
-     * **Note:** This is **not** available for vault-backed accounts and will
-     * throw an error if called on one.
+     * Direct accounts are controlled via an on-chain “cap” object. Vault-backed
+     * accounts are controlled via vault caps and do not expose a direct account-cap ID.
+     *
+     * @throws If called for a vault-backed account.
      *
      * @returns {@link ObjectId} of the account cap.
      */
-    // TODO: make this work with vaults
     accountCapId() {
         if ("vaultId" in this.accountCap)
             throw new Error("not account cap id present on vault owned account");