aftermath-ts-sdk 1.3.23-perps.25 → 1.3.23-perps.27

package/dist/packages/perpetuals/perpetualsAccount.js

@@ -26,10 +26,58 @@ const utils_1 = require("../../general/utils");
 const perpetuals_1 = require("./perpetuals");
 const transactions_1 = require("@mysten/sui/transactions");
 // TODO: create refresh account positions function ?
+/**
+ * High-level wrapper around a single Perpetuals account or vault account.
+ *
+ * This class encapsulates:
+ *
+ * - Transaction builders for:
+ *   - Collateral actions (deposit, withdraw, allocate, deallocate, transfer)
+ *   - Orders (market/limit, cancel, stop orders, SL/TP, set leverage)
+ * - Read-only account helpers:
+ *   - Stop-order message signing
+ *   - Order & stop-order metadata
+ *   - Collateral & trade history
+ * - Convenience helpers to:
+ *   - Fetch and categorize SL/TP stop orders
+ *   - Resolve account/vault identifiers and owner addresses
+ *
+ * You typically do not construct `PerpetualsAccount` directly. Instead, use
+ * {@link Perpetuals.getAccount} or {@link Perpetuals.getAccounts}, which
+ * fetch all required on-chain data and wrap it for you:
+ *
+ * ```ts
+ * const afSdk = new Aftermath("MAINNET");
+ * await afSdk.init();
+ *
+ * const perps = afSdk.Perpetuals();
+ * const [accountCap] = await perps.getOwnedAccountCaps({
+ *   walletAddress: "0x...",
+ * });
+ *
+ * const account = await perps.getAccount({ accountCap });
+ *
+ * // Build a deposit transaction
+ * const depositTx = await account.getDepositCollateralTx({
+ *   depositAmount: BigInt("1000000000"),
+ * });
+ * ```
+ */
 class PerpetualsAccount extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
+    /**
+     * Create a new {@link PerpetualsAccount} wrapper.
+     *
+     * @param account - Raw account object with positions and equity data.
+     * @param accountCap - Account cap or vault-cap-extended object containing
+     *   ownership and collateral metadata.
+     * @param config - Optional {@link CallerConfig} (network, auth, etc.).
+     * @param Provider - Optional shared {@link AftermathApi} provider instance
+     *   used to derive serialized transaction kinds (`txKind`) from
+     *   {@link Transaction} objects.
+     */
     constructor(account, accountCap, config, Provider) {
         const vaultId = "vaultId" in accountCap ? accountCap.vaultId : undefined;
         super(config, "perpetuals");
@@ -44,6 +92,33 @@ class PerpetualsAccount extends caller_1.Caller {
     // =========================================================================
     //  Collateral Txs
     // =========================================================================
+    /**
+     * Build a `deposit-collateral` transaction for this account.
+     *
+     * For non-vault accounts, this endpoint constructs a transaction that:
+     * - Optionally extends an existing {@link Transaction}, and
+     * - Deposits collateral into the Perpetuals account.
+     *
+     * **Note:** Vault accounts are currently not supported and will throw.
+     *
+     * @param inputs.tx - Optional existing transaction to extend. If omitted,
+     *   a new {@link Transaction} is created under the hood.
+     * @param inputs.isSponsoredTx - Optional flag indicating whether the
+     *   transaction is gas-sponsored.
+     * @param inputs.depositAmount - Amount of collateral to deposit, if paying
+     *   directly from the wallet.
+     * @param inputs.depositCoinArg - Transaction object argument referencing a
+     *   coin to deposit (mutually exclusive with `depositAmount`).
+     *
+     * @returns Transaction response containing a serialized `txKind`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await account.getDepositCollateralTx({
+     *   depositAmount: BigInt("1000000000"),
+     * });
+     * ```
+     */
     getDepositCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -65,6 +140,31 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `withdraw-collateral` transaction for this account.
+     *
+     * For non-vault accounts, this endpoint constructs a transaction to:
+     * - Withdraw collateral from the Perpetuals account, and
+     * - Optionally transfer it to a `recipientAddress` (otherwise coin is left
+     *   as a transaction argument).
+     *
+     * **Note:** Vault accounts are currently not supported and will throw.
+     *
+     * @param inputs.withdrawAmount - Amount of collateral to withdraw.
+     * @param inputs.recipientAddress - Optional address to receive the withdrawn
+     *   coins directly.
+     * @param inputs.tx - Optional transaction to extend (defaults to new `Transaction()`).
+     *
+     * @returns A response containing `txKind` and the `coinOutArg` where the
+     *   withdrawn coins end up if `recipientAddress` is not used.
+     *
+     * @example
+     * ```ts
+     * const { txKind, coinOutArg } = await account.getWithdrawCollateralTx({
+     *   withdrawAmount: BigInt("1000000000"),
+     * });
+     * ```
+     */
     getWithdrawCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -87,6 +187,18 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build an `allocate-collateral` transaction, moving collateral from this
+     * account into a specific market (clearing house).
+     *
+     * Works for both account-backed and vault-backed accounts.
+     *
+     * @param inputs.marketId - Market to allocate collateral to.
+     * @param inputs.allocateAmount - Amount of collateral to allocate.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing a serialized `txKind`.
+     */
     getAllocateCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -104,6 +216,18 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `deallocate-collateral` transaction, moving collateral from a
+     * specific market back to this account.
+     *
+     * Works for both account-backed and vault-backed accounts.
+     *
+     * @param inputs.marketId - Market to deallocate collateral from.
+     * @param inputs.deallocateAmount - Amount of collateral to deallocate.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing a serialized `txKind`.
+     */
     getDeallocateCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -121,6 +245,17 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `transfer-collateral` transaction between two Perpetuals accounts.
+     *
+     * Only supported for direct accounts, **not** vault-backed accounts.
+     *
+     * @param inputs.transferAmount - Amount of collateral to transfer.
+     * @param inputs.toAccountId - Destination account ID.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing a serialized `txKind`.
+     */
     getTransferCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -143,6 +278,35 @@ class PerpetualsAccount extends caller_1.Caller {
     // =========================================================================
     //  Order Txs
     // =========================================================================
+    /**
+     * Build a `place-market-order` transaction for this account.
+     *
+     * This is the primary entrypoint for opening/closing positions via market orders.
+     * It automatically:
+     * - Injects the account/vault identity into the payload.
+     * - Derives `hasPosition` based on the current account state for the given market.
+     * - Optionally attaches SL/TP stop orders via the `slTp` input.
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceMarketOrderInputs} for details.
+     *   Notably:
+     *   - `marketId`, `side`, `size`, `collateralChange`, `reduceOnly`
+     *   - Optional `leverage`
+     *   - Optional `slTp` params
+     *   - Optional `tx` to extend
+     *
+     * @returns Transaction response containing `txKind`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await account.getPlaceMarketOrderTx({
+     *   marketId: "0x...",
+     *   side: PerpetualsOrderSide.Bid,
+     *   size: BigInt("1000000000"),
+     *   collateralChange: 10,
+     *   reduceOnly: false,
+     * });
+     * ```
+     */
     getPlaceMarketOrderTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -162,6 +326,17 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `place-limit-order` transaction for this account.
+     *
+     * Similar to {@link getPlaceMarketOrderTx}, but uses limit order semantics:
+     * - Requires `price` and `orderType`.
+     * - Supports reduce-only flags, expiry, optional leverage, and SL/TP stop orders.
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderInputs}.
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getPlaceLimitOrderTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -181,6 +356,17 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `cancel-orders` transaction for this account.
+     *
+     * @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
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getCancelOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -197,6 +383,14 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `cancel-stop-orders` transaction for this account.
+     *
+     * @param inputs.tx - Optional transaction to extend.
+     * @param inputs.stopOrderIds - Array of stop-order ticket IDs to cancel.
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getCancelStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -213,6 +407,16 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `place-stop-orders` transaction for this account.
+     *
+     * This allows placing one or more stop orders in a single transaction,
+     * optionally with a dedicated gas coin and a sponsored gas flag.
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceStopOrdersInputs}.
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getPlaceStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -233,6 +437,17 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build a `place-sl-tp-orders` transaction for this account.
+     *
+     * This helper constructs SL/TP stop orders for an **existing** position
+     * in a given market. If the account has no position for `marketId`, this
+     * throws an error.
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceSlTpOrdersInputs}.
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getPlaceSlTpOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -256,6 +471,16 @@ class PerpetualsAccount extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Build an `edit-stop-orders` transaction for this account.
+     *
+     * This endpoint lets you update existing stop orders in batch.
+     *
+     * @param inputs.stopOrders - Full updated stop-order payloads to apply.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `txKind`.
+     */
     getEditStopOrdersTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -309,6 +534,20 @@ class PerpetualsAccount extends caller_1.Caller {
     // 		}
     // 	);
     // }
+    /**
+     * Build a `set-leverage` transaction for a given market.
+     *
+     * This updates the effective leverage for the position (or potential position)
+     * in `marketId`, and optionally adjusts collateral in tandem.
+     *
+     * @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`.
+     */
     getSetLeverageTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -345,6 +584,26 @@ class PerpetualsAccount extends caller_1.Caller {
     // =========================================================================
     //  Interactions
     // =========================================================================
+    /**
+     * Build a deterministic message payload to sign when querying stop orders
+     * from the backend.
+     *
+     * This payload is intended to be signed off-chain and then submitted to
+     * `getStopOrderDatas` as a proof of account ownership.
+     *
+     * @param inputs.marketIds - Optional list of market IDs to scope the query.
+     *
+     * @returns An object describing the action and account/market IDs, suitable
+     *   for message signing.
+     *
+     * @example
+     * ```ts
+     * const message = account.getStopOrdersMessageToSign({ marketIds: ["0x..."] });
+     * const { signature } = await wallet.signMessage({
+     *   message: new TextEncoder().encode(JSON.stringify(message)),
+     * });
+     * ```
+     */
     getStopOrdersMessageToSign(inputs) {
         var _a;
         return {
@@ -363,7 +622,7 @@ class PerpetualsAccount extends caller_1.Caller {
     // 			error: string;
     // 	  }
     // 	| {
-    // 			positionAfterOrder: PerpetualsPosition;
+    // 			updatedPosition: PerpetualsPosition;
     // 			priceSlippage: number;
     // 			percentSlippage: Percentage;
     // 			filledSize: number;
@@ -387,6 +646,20 @@ class PerpetualsAccount extends caller_1.Caller {
     // 		abortSignal
     // 	);
     // }
+    /**
+     * Preview the effects of placing a market order (without building a tx).
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceMarketOrderPreviewInputs}.
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either an error message or a preview including:
+     * - `updatedPosition`
+     * - `priceSlippage`, `percentSlippage`
+     * - `filledSize`, `filledSizeUsd`
+     * - `postedSize`, `postedSizeUsd`
+     * - `collateralChange`
+     * - `executionPrice`
+     */
     getPlaceMarketOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi(`${this.vaultId ? "vault" : "account"}/` +
@@ -399,6 +672,15 @@ class PerpetualsAccount extends caller_1.Caller {
                 })), abortSignal);
         });
     }
+    /**
+     * Preview the effects of placing a limit order (without building a tx).
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either an error message or a preview object similar to
+     *   {@link getPlaceMarketOrderPreview}.
+     */
     getPlaceLimitOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi(`${this.vaultId ? "vault" : "account"}/` +
@@ -411,13 +693,27 @@ class PerpetualsAccount extends caller_1.Caller {
                 })), abortSignal);
         });
     }
+    /**
+     * Preview the effects of canceling orders across one or more markets.
+     *
+     * If `marketIdsToData` is empty, this returns a trivial preview with:
+     * - `collateralChange: 0`
+     * - `updatedPositions: []`
+     *
+     * @param inputs - See {@link SdkPerpetualsCancelOrdersPreviewInputs}.
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either:
+     * - `{ updatedPositions, collateralChange }`, or
+     * - `{ error }`.
+     */
     getCancelOrdersPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             // NOTE: should this case return an error instead ?
             if (Object.keys(inputs.marketIdsToData).length <= 0)
                 return {
                     collateralChange: 0,
-                    marketIdsToPositionAfterCancelOrders: {},
+                    updatedPositions: [],
                 };
             return this.fetchApi(`${this.vaultId ? "vault" : "account"}/` + "previews/cancel-orders", Object.assign(Object.assign({}, inputs), ("vaultId" in this.accountCap
                 ? {
@@ -463,6 +759,17 @@ class PerpetualsAccount extends caller_1.Caller {
     // 		abortSignal
     // 	);
     // }
+    /**
+     * Preview the effects of setting leverage for a given market.
+     *
+     * @param inputs.marketId - Market whose leverage you want to adjust.
+     * @param inputs.leverage - Target leverage value.
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either:
+     * - `{ updatedPosition, collateralChange }`, or
+     * - `{ error }`.
+     */
     getSetLeveragePreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             const { marketId, leverage } = inputs;
@@ -476,6 +783,34 @@ class PerpetualsAccount extends caller_1.Caller {
                 })), abortSignal);
         });
     }
+    /**
+     * Preview the effects of allocating/deallocating collateral for the position in
+     * a given 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
+     * for allocating collateral, negative for deallocating collateral).
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either:
+     * - `{ updatedPosition, collateralChange }`, or
+     * - `{ error }`.
+     */
+    getEditCollateralPreview(inputs, abortSignal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { marketId, collateralChange } = inputs;
+            return this.fetchApi(`${this.vaultId ? "vault" : "account"}/` +
+                "previews/edit-collateral", Object.assign({ marketId,
+                collateralChange }, ("vaultId" in this.accountCap
+                ? {
+                    vaultId: this.accountCap.vaultId,
+                }
+                : {
+                    accountId: this.accountCap.accountId,
+                })), abortSignal);
+        });
+    }
     // public getPlaceClosePositionOrderPreview = async (
     // 	inputs: {
     // 		size: bigint;
@@ -512,6 +847,15 @@ class PerpetualsAccount extends caller_1.Caller {
     // 		abortSignal
     // 	);
     // };
+    /**
+     * Fetch the latest order metadata (sizes, IDs) for this account.
+     *
+     * 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.
+     */
     getOrderDatas() {
         return __awaiter(this, void 0, void 0, function* () {
             const orderDatas = this.account.positions.reduce((acc, position) => [
@@ -529,37 +873,70 @@ 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}).
+     * @param inputs.signature - Signature over `bytes`.
+     * @param inputs.marketIds - Optional subset of markets to filter results by.
+     *
+     * @returns Array of {@link PerpetualsStopOrderData}.
+     */
     getStopOrderDatas(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             const { bytes, signature, marketIds } = inputs;
-            return this.fetchApi("account/stop-order-datas", {
-                bytes,
-                signature,
-                accountId: this.accountCap.accountId,
-                walletAddress: this.ownerAddress(),
-                marketIds: marketIds !== null && marketIds !== void 0 ? marketIds : [],
-            });
+            return this.fetchApi(`${this.vaultId ? "vault" : "account"}/` + "stop-order-datas", Object.assign({ bytes,
+                signature, walletAddress: this.ownerAddress(), marketIds: marketIds !== null && marketIds !== void 0 ? marketIds : [] }, ("vaultId" in this.accountCap
+                ? {
+                    vaultId: this.accountCap.vaultId,
+                }
+                : {
+                    accountId: this.accountCap.accountId,
+                })));
         });
     }
+    /**
+     * Fetch paginated collateral-change history for this account, including
+     * deposits, withdrawals, funding settlements, liquidations, etc.
+     *
+     * @param inputs.cursor - Optional cursor for pagination.
+     * @param inputs.limit - Optional limit per page.
+     *
+     * @returns {@link PerpetualsAccountCollateralChangesWithCursor} containing
+     *   an array of changes and a `nextCursor`.
+     */
     getCollateralHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/collateral-history", Object.assign(Object.assign({}, inputs), { accountId: this.accountCap.accountId, collateralCoinType: this.accountCap.collateralCoinType }));
         });
     }
+    /**
+     * Fetch paginated trade (order fill) history for this account.
+     *
+     * @param inputs.cursor - Optional cursor for pagination.
+     * @param inputs.limit - Optional limit per page.
+     *
+     * @returns {@link PerpetualsAccountTradesWithCursor} containing a list of
+     *   trades and a `nextCursor`.
+     */
     getOrderHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/trade-history", Object.assign(Object.assign({}, inputs), { accountId: this.accountCap.accountId }));
         });
     }
-    // public async getMarginHistory() {
-    // 	return this.fetchApi<
-    // 		PerpetualsAccountMarginData[],
-    // 		ApiPerpetualsAccountMarginHistoryBody
-    // 	>("account/margin-history", {
-    // 		accountId: this.accountCap.accountId,
-    // 		collateralCoinType: this.accountCap.collateralCoinType,
-    // 	});
-    // }
+    // TODO: docs
+    // public async getMarginHistory(inputs: ApiDataWithCursorBody<Timestamp>) {
+    getMarginHistory() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("account/margin-history", {
+                // ...inputs,
+                accountId: this.accountCap.accountId,
+                collateralCoinType: this.accountCap.collateralCoinType,
+            });
+        });
+    }
     // public async getOwnedWithdrawRequests() {
     // 	return new Perpetuals(
     // 		this.config,
@@ -571,6 +948,12 @@ class PerpetualsAccount extends caller_1.Caller {
     // =========================================================================
     //  Helpers
     // =========================================================================
+    /**
+     * Find the current position for a given market ID, if any.
+     *
+     * @param inputs.marketId - Market ID to search for.
+     * @returns {@link PerpetualsPosition} if found, otherwise `undefined`.
+     */
     positionForMarketId(inputs) {
         try {
             return this.account.positions.find((pos) => pos.marketId === inputs.marketId);
@@ -579,6 +962,15 @@ class PerpetualsAccount extends caller_1.Caller {
             return undefined;
         }
     }
+    /**
+     * Filter a list of stop orders to only include non-SL/TP orders.
+     *
+     * A stop order is considered SL/TP if it appears in the combined set of
+     * SL/TP orders across **all** markets (see {@link slTpStopOrderDatas}).
+     *
+     * @param inputs.stopOrderDatas - Full array of stop-order ticket data.
+     * @returns An array of non-SL/TP stop orders, or `undefined` if none exist.
+     */
     nonSlTpStopOrderDatas(inputs) {
         const { stopOrderDatas } = inputs;
         const slTpOrders = this.slTpStopOrderDatas(inputs);
@@ -587,6 +979,21 @@ class PerpetualsAccount extends caller_1.Caller {
             .includes(JSON.stringify(stopOrder)));
         return stopOrders.length <= 0 ? undefined : stopOrders;
     }
+    /**
+     * Extract all SL/TP-style stop orders across **all** markets for this
+     * account.
+     *
+     * SL/TP orders are stop orders which:
+     * - Have an `slTp` payload, and
+     * - Target the opposite side of the current position.
+     *
+     * This combines:
+     * - "Full" SL/TP orders (size >= `i64MaxBigInt`)
+     * - "Partial" SL/TP orders (size < `i64MaxBigInt`)
+     *
+     * @param inputs.stopOrderDatas - Full list of stop-order tickets.
+     * @returns Array of SL/TP stop orders, or `undefined` if none exist.
+     */
     slTpStopOrderDatas(inputs) {
         const { stopOrderDatas } = inputs;
         let slTpOrders = [];
@@ -603,6 +1010,15 @@ class PerpetualsAccount extends caller_1.Caller {
         }
         return slTpOrders.length <= 0 ? undefined : slTpOrders;
     }
+    /**
+     * Filter stop orders for a single market to only include non-SL/TP orders.
+     *
+     * Uses {@link slTpStopOrderDatasForMarketId} under the hood.
+     *
+     * @param inputs.marketId - Market ID to filter for.
+     * @param inputs.stopOrderDatas - Full list of stop orders.
+     * @returns Non-SL/TP stop orders for the given market, or `undefined` if none exist.
+     */
     nonSlTpStopOrderDatasForMarketId(inputs) {
         const { marketId, stopOrderDatas } = inputs;
         const position = this.positionForMarketId({ marketId });
@@ -617,6 +1033,24 @@ class PerpetualsAccount extends caller_1.Caller {
             .includes(JSON.stringify(stopOrder)));
         return stopOrders.length <= 0 ? undefined : stopOrders;
     }
+    /**
+     * Categorize stop orders for a specific market into:
+     * - A "full" SL/TP order (size >= `i64MaxBigInt`) if any.
+     * - A set of "partial" SL/TP orders (size < `i64MaxBigInt`).
+     *
+     * SL/TP stop orders are defined as:
+     * - Market ID matches the input market.
+     * - `slTp` field is present.
+     * - Order side is opposite of the position side.
+     * - At least a `stopLossIndexPrice` or `takeProfitIndexPrice` is set.
+     *
+     * @param inputs.marketId - Market to categorize stop orders for.
+     * @param inputs.stopOrderDatas - Full list of stop orders.
+     *
+     * @returns Object containing:
+     * - `fullSlTpOrder` (if any)
+     * - `partialSlTpOrders` (if any, otherwise `undefined`)
+     */
     slTpStopOrderDatasForMarketId(inputs) {
         const { marketId, stopOrderDatas } = inputs;
         const position = this.positionForMarketId({ marketId });
@@ -645,6 +1079,11 @@ class PerpetualsAccount extends caller_1.Caller {
             partialSlTpOrders: partialSlTpOrders.length <= 0 ? undefined : partialSlTpOrders,
         };
     }
+    /**
+     * Convenience accessor for the account's available collateral (in coin units).
+     *
+     * @returns Available collateral as a `number`.
+     */
     collateral() {
         return this.account.availableCollateral;
     }
@@ -657,21 +1096,52 @@ class PerpetualsAccount extends caller_1.Caller {
     // 		this.collateralDecimals()
     // 	);
     // }
+    /**
+     * Check whether this {@link PerpetualsAccount} is vault-backed.
+     *
+     * @returns `true` if the underlying `accountCap` is a vault cap; otherwise `false`.
+     */
     isVault() {
-        return this.isVault !== undefined;
+        return "vaultId" in this.accountCap;
     }
+    /**
+     * Resolve the owner wallet address of this account or vault.
+     *
+     * - For direct accounts, returns the `walletAddress` field.
+     * - For vault-backed accounts, returns `ownerAddress`.
+     *
+     * @returns Owner wallet {@link SuiAddress}.
+     */
     ownerAddress() {
         return "walletAddress" in this.accountCap
             ? // TODO: change to ownerAddress ?
                 this.accountCap.walletAddress
             : this.accountCap.ownerAddress;
     }
+    /**
+     * Get the underlying account object ID.
+     *
+     * @returns {@link ObjectId} of the account object.
+     */
     accountObjectId() {
         return this.accountCap.accountObjectId;
     }
+    /**
+     * Get the numeric perpetuals account ID.
+     *
+     * @returns {@link PerpetualsAccountId} for this account.
+     */
     accountId() {
         return this.accountCap.accountId;
     }
+    /**
+     * 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.
+     *
+     * @returns {@link ObjectId} of the account cap.
+     */
     // TODO: make this work with vaults
     accountCapId() {
         if ("vaultId" in this.accountCap)
@@ -680,9 +1150,3 @@ class PerpetualsAccount extends caller_1.Caller {
     }
 }
 exports.PerpetualsAccount = PerpetualsAccount;
-// =========================================================================
-//  Private Constants
-// =========================================================================
-PerpetualsAccount.constants = {
-    closePositionMarginOfError: 0.1, // 10%
-};