aftermath-ts-sdk 1.3.23-perps.35 → 1.3.23-perps.37

package/dist/packages/perpetuals/perpetualsVault.js

@@ -24,10 +24,52 @@ exports.PerpetualsVault = void 0;
 const transactions_1 = require("@mysten/sui/transactions");
 const caller_1 = require("../../general/utils/caller");
 const perpetuals_1 = require("./perpetuals");
+/**
+ * High-level wrapper around a single Perpetuals vault.
+ *
+ * A vault is a managed perpetuals account that accepts user deposits (LP),
+ * trades across up to a bounded set of markets, and supports withdrawals via
+ * a request flow.
+ *
+ * This class provides:
+ *
+ * - Transaction builders for:
+ *   - User actions (deposit, create/cancel withdraw request, update slippage)
+ *   - Force-withdraw processing (close positions and settle a request)
+ *   - Owner admin actions (update params, process requests, withdraw fees/collateral)
+ * - Read helpers for:
+ *   - Vault withdraw requests
+ *   - LP token pricing
+ *   - Accessing the vault’s underlying perpetuals account
+ * - Static validation helpers for LP coin metadata (name/symbol constraints)
+ * - A small calculation helper for withdraw-request slippage
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const perps = afSdk.Perpetuals();
+ * const { vaults } = await perps.getAllVaults();
+ * const vault = vaults[0];
+ *
+ * const { tx } = await vault.getDepositTx({
+ *   walletAddress: "0x...",
+ *   depositAmount: BigInt("1000000000"),
+ *   minLpAmountOut: 0n,
+ * });
+ * ```
+ */
 class PerpetualsVault extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
+    /**
+     * Create a new {@link PerpetualsVault} wrapper.
+     *
+     * @param vaultObject - Raw on-chain vault object snapshot.
+     * @param config - Optional {@link CallerConfig} (network, auth, base URL).
+     * @param Provider - Optional shared {@link AftermathApi} provider. When provided,
+     *   transaction builders will serialize {@link Transaction}s into `txKind`.
+     */
     constructor(vaultObject, config, Provider) {
         super(config, "perpetuals");
         this.vaultObject = vaultObject;
@@ -39,129 +81,233 @@ class PerpetualsVault extends caller_1.Caller {
     // =========================================================================
     //  Withdraw Request Txs
     // =========================================================================
+    /**
+     * Build a `process-force-withdraw-request` transaction.
+     *
+     * Force-withdraw is a mechanism that closes required positions and processes
+     * a withdraw request after a delay window (see vault params).
+     *
+     * @param inputs.walletAddress - User wallet that owns the withdraw request.
+     * @param inputs.sizesToClose - Mapping of marketId -> size (base units) to close.
+     * @param inputs.recipientAddress - Optional recipient of the withdrawn collateral.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx` (and any additional outputs
+     *   provided by the backend response type).
+     */
     getProcessForceWithdrawRequestTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
-            return this.fetchApiTxObject("vault/transactions/process-force-withdraw-request", Object.assign(Object.assign({}, otherInputs), { 
-                // NOTE: should this be `vaultIds` ?
-                vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
+            return this.fetchApiTxObject("vault/transactions/process-force-withdraw-request", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build an `update-withdraw-request-slippage` transaction.
+     *
+     * This updates the user's minimum acceptable collateral output amount
+     * for an existing withdraw request.
+     *
+     * @param inputs.minCollateralAmountOut - New minimum collateral amount out.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getUpdateWithdrawRequestSlippageTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/update-withdraw-request-slippage", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
     // =========================================================================
     //  Owner Settings Txs
     // =========================================================================
+    /**
+     * Build an owner transaction to update the vault's force withdraw delay.
+     *
+     * @param inputs.forceWithdrawDelayMs - New delay (ms). Should be <= {@link constants.maxForceWithdrawDelayMs}.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getOwnerUpdateForceWithdrawDelayTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/owner/update-force-withdraw-delay", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build an owner transaction to update the vault's lock period.
+     *
+     * @param inputs.lockPeriodMs - New lock period (ms). Should be <= {@link constants.maxLockPeriodMs}.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getOwnerUpdateLockPeriodTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/owner/update-lock-period", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build an owner transaction to update the vault performance fee.
+     *
+     * @param inputs.performanceFeePercentage - New fee as a fraction (e.g. `0.2` = 20%).
+     *   Should be <= {@link constants.maxPerformanceFeePercentage}.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getOwnerUpdatePerformanceFeeTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/owner/update-performance-fee", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
     // =========================================================================
     //  Owner Interactions Txs
     // =========================================================================
+    /**
+     * Build an owner transaction to process one or more users' withdraw requests.
+     *
+     * This is the normal (non-force) processing path for withdrawals. The owner
+     * batches users and settles their requests in a single transaction.
+     *
+     * @param inputs.userAddresses - Users whose requests should be processed.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getOwnerProcessWithdrawRequestsTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
-            return this.fetchApiTxObject("vault/transactions/owner/process-withdraw-requests", Object.assign(Object.assign({}, otherInputs), { 
-                // NOTE: should this be `vaultIds` ?
-                vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
+            return this.fetchApiTxObject("vault/transactions/owner/process-withdraw-requests", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build an owner transaction to withdraw accrued performance fees.
+     *
+     * @param inputs.withdrawAmount - Amount of collateral to withdraw as fees.
+     * @param inputs.recipientAddress - Optional recipient address for the withdrawn fees.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Response containing `tx` and any extra outputs described by
+     * {@link ApiPerpetualsVaultOwnerWithdrawPerformanceFeesTxResponse}.
+     */
     getOwnerWithdrawPerformanceFeesTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx: txFromInputs } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/owner/withdraw-performance-fees", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: txFromInputs !== null && txFromInputs !== void 0 ? txFromInputs : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build an owner transaction to withdraw vault collateral by redeeming LP.
+     *
+     * @param inputs.lpWithdrawAmount - Amount of LP to redeem.
+     * @param inputs.minCollateralAmountOut - Minimum collateral out to protect from slippage.
+     * @param inputs.recipientAddress - Optional recipient address for withdrawn collateral.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Response containing `tx` and any extra outputs described by
+     * {@link ApiPerpetualsVaultOwnerWithdrawCollateralTxResponse}.
+     */
     getOwnerWithdrawCollateralTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/owner/withdraw-collateral", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
     // =========================================================================
     //  User Interactions Txs
     // =========================================================================
+    /**
+     * Build a user transaction to create a vault withdraw request.
+     *
+     * Withdrawals are request-based: the user specifies how much LP to redeem
+     * and a minimum collateral output amount.
+     *
+     * @param inputs.walletAddress - Wallet creating the request.
+     * @param inputs.lpWithdrawAmount - Amount of LP to withdraw.
+     * @param inputs.minCollateralAmountOut - Minimum collateral out (slippage guard).
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getCreateWithdrawRequestTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/create-withdraw-request", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build a user transaction to cancel an existing vault withdraw request.
+     *
+     * @param inputs.walletAddress - Wallet canceling the request.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     */
     getCancelWithdrawRequestTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
             return this.fetchApiTxObject("vault/transactions/cancel-withdraw-request", Object.assign(Object.assign({}, otherInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
+    /**
+     * Build a user transaction to deposit collateral into the vault in exchange for LP.
+     *
+     * You can specify the deposit as:
+     * - `depositAmount` (wallet pays directly), OR
+     * - `depositCoinArg` (use an existing transaction argument)
+     *
+     * @param inputs.walletAddress - Depositor wallet.
+     * @param inputs.minLpAmountOut - Minimum LP out (slippage guard).
+     * @param inputs.isSponsoredTx - Whether the tx is sponsored (gas paid by another party).
+     * @param inputs.depositAmount - Amount of collateral to deposit (mutually exclusive with `depositCoinArg`).
+     * @param inputs.depositCoinArg - Transaction argument referencing collateral coin.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing `tx`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await vault.getDepositTx({
+     *   walletAddress: "0x...",
+     *   depositAmount: 1_000_000_000n,
+     *   minLpAmountOut: 0n,
+     * });
+     * ```
+     */
     // TODO: make return lp coin out ?
     getDepositTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -172,45 +318,50 @@ class PerpetualsVault extends caller_1.Caller {
                     depositAmount: otherInputs.depositAmount,
                     collateralCoinType: this.vaultObject.collateralCoinType,
                 }
-                : {
-                    depositCoinArg: otherInputs.depositCoinArg,
-                };
+                : { depositCoinArg: otherInputs.depositCoinArg };
             return this.fetchApiTxObject("vault/transactions/deposit", Object.assign(Object.assign(Object.assign({}, otherInputs), depositInputs), { vaultId: this.vaultObject.objectId, txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
                     tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
-                })) }), undefined, {
-                txKind: true,
-            });
+                })) }), undefined, { txKind: true });
         });
     }
     // =========================================================================
     //  Objects
     // =========================================================================
+    /**
+     * Fetch all withdraw requests for this vault.
+     *
+     * @returns {@link ApiPerpetualsVaultsWithdrawRequestsResponse} containing requests
+     * scoped to `this.vaultObject.objectId`.
+     *
+     * @remarks
+     * This currently calls the `vaults/withdraw-requests` endpoint with a single vault ID.
+     * This may be moved to {@link Perpetuals} as a shared helper.
+     */
     // TODO: move to `Perpetuals` (as well) ?
     getAllWithdrawRequests() {
         return this.fetchApi("vaults/withdraw-requests", {
             vaultIds: [this.vaultObject.objectId],
         });
     }
-    // // TODO: add to perps account as well ?
-    // public async getWithdrawRequestsForUser(inputs: {
-    // 	walletAddress: SuiAddress;
-    // }) {
-    // 	return this.fetchApi<
-    // 		PerpetualsVaultWithdrawRequest[],
-    // 		ApiPerpetualsVaultWithdrawRequestsBody
-    // 	>("owned-withdraw-requests", {
-    // 		...inputs,
-    // 		vaultIds: [this.vaultObject.objectId],
-    // 	});
-    // }
     // =========================================================================
     //  Owner Previews
     // =========================================================================
+    /**
+     * Preview the results of an owner processing one or more withdraw requests.
+     *
+     * @param inputs.userAddresses - Users to process.
+     * @returns Preview response with expected effects.
+     */
     getPreviewOwnerProcessWithdrawRequests(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/owner/process-withdraw-requests", Object.assign(Object.assign({}, inputs), { vaultId: this.vaultObject.objectId }));
         });
     }
+    /**
+     * Preview the amount available for the owner to withdraw as performance fees.
+     *
+     * @returns Preview response including withdrawable fees and related metadata.
+     */
     getPreviewOwnerWithdrawPerformanceFees() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/owner/withdraw-performance-fees", {
@@ -218,6 +369,12 @@ class PerpetualsVault extends caller_1.Caller {
             });
         });
     }
+    /**
+     * Preview an owner collateral withdrawal (LP redemption).
+     *
+     * @param inputs.lpWithdrawAmount - LP amount to redeem.
+     * @returns Preview response including estimated collateral out.
+     */
     getPreviewOwnerWithdrawCollateral(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/owner/withdraw-collateral", Object.assign(Object.assign({}, inputs), { vaultId: this.vaultObject.objectId }));
@@ -226,16 +383,38 @@ class PerpetualsVault extends caller_1.Caller {
     // =========================================================================
     //  User Previews
     // =========================================================================
+    /**
+     * Preview creating a withdraw request.
+     *
+     * @param inputs.walletAddress - Requesting wallet.
+     * @param inputs.lpWithdrawAmount - LP amount to withdraw.
+     * @returns Preview response including estimated collateral out and constraints.
+     */
     getPreviewCreateWithdrawRequest(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/create-withdraw-request", Object.assign(Object.assign({}, inputs), { vaultId: this.vaultObject.objectId }));
         });
     }
+    /**
+     * Preview depositing into the vault.
+     *
+     * @param inputs.depositAmount - Deposit amount in collateral coin units.
+     * @returns Preview response including estimated LP out.
+     */
     getPreviewDeposit(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/deposit", Object.assign(Object.assign({}, inputs), { vaultId: this.vaultObject.objectId }));
         });
     }
+    /**
+     * Preview processing a force withdraw request for a user.
+     *
+     * This is useful to determine what positions/sizes must be closed or what
+     * the expected outputs are prior to building the actual transaction.
+     *
+     * @param inputs.walletAddress - User wallet with a pending force-withdraw.
+     * @returns Preview response describing expected processing effects.
+     */
     getPreviewProcessForceWithdrawRequest(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("vault/previews/process-force-withdraw-request", Object.assign(Object.assign({}, inputs), { vaultId: this.vaultObject.objectId }));
@@ -244,6 +423,13 @@ class PerpetualsVault extends caller_1.Caller {
     // =========================================================================
     //  Inspections
     // =========================================================================
+    /**
+     * Fetch the current LP coin price for this vault (in collateral units).
+     *
+     * Internally calls {@link Perpetuals.getLpCoinPrices} and returns the first price.
+     *
+     * @returns LP coin price as a `number`.
+     */
     getLpCoinPrice() {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield new perpetuals_1.Perpetuals(this.config, this.Provider).getLpCoinPrices({
@@ -254,6 +440,12 @@ class PerpetualsVault extends caller_1.Caller {
     // =========================================================================
     //  Account
     // =========================================================================
+    /**
+     * Build a lightweight “cap-like” object for the vault’s underlying account.
+     *
+     * @returns {@link PerpetualsPartialVaultCap} suitable for account fetch helpers
+     * such as {@link Perpetuals.getAccount}.
+     */
     partialVaultCap() {
         return {
             vaultId: this.vaultObject.objectId,
@@ -263,6 +455,11 @@ class PerpetualsVault extends caller_1.Caller {
             collateralCoinType: this.vaultObject.collateralCoinType,
         };
     }
+    /**
+     * Fetch the underlying perpetuals account object for this vault.
+     *
+     * @returns `{ account }` where `account` is the on-chain {@link PerpetualsAccountObject}.
+     */
     getAccountObject() {
         return __awaiter(this, void 0, void 0, function* () {
             return {
@@ -272,6 +469,11 @@ class PerpetualsVault extends caller_1.Caller {
             };
         });
     }
+    /**
+     * Fetch a {@link PerpetualsAccount} wrapper for the vault’s underlying account.
+     *
+     * @returns `{ account }` where `account` is a high-level {@link PerpetualsAccount}.
+     */
     getAccount() {
         return __awaiter(this, void 0, void 0, function* () {
             return new perpetuals_1.Perpetuals(this.config, this.Provider).getAccount({
@@ -284,10 +486,14 @@ exports.PerpetualsVault = PerpetualsVault;
 // =========================================================================
 //  Public Constants
 // =========================================================================
+/**
+ * Vault-level protocol limits and UI-friendly constraints.
+ *
+ * @remarks
+ * These are SDK constants (not fetched from chain). They should match the
+ * on-chain / backend limits enforced by the vault module.
+ */
 PerpetualsVault.constants = {
-    // NOTE: what is this ?
-    // /// Time necessary for the next vault's params update
-    // vaultParamsUpdateFrequency: 28800000, // 8hrs
     /**
      * Maximum lock period in milliseconds.
      */
@@ -297,11 +503,11 @@ PerpetualsVault.constants = {
      */
     maxForceWithdrawDelayMs: 86400000, // 1 day
     /**
-     * Maximum vault fee.
+     * Maximum vault fee (performance fee).
      */
     maxPerformanceFeePercentage: 0.2, // 20%
     /**
-     * Minimum USD value required for users deposits.
+     * Minimum USD value required for user deposits.
      */
     minDepositUsd: 1,
     /**
@@ -309,11 +515,11 @@ PerpetualsVault.constants = {
      */
     minOwnerLockUsd: 1,
     /**
-     * The maximum number of distinct `ClearingHouse`.
+     * The maximum number of distinct markets (`ClearingHouse`s) the vault can trade.
      */
     maxMarketsInVault: 12,
     /**
-     * The maximum number of pending orders allowed for a single position in the `Vault`.
+     * The maximum number of pending orders allowed for a single position in the vault.
      */
     maxPendingOrdersPerPosition: 70,
 };
@@ -324,16 +530,22 @@ PerpetualsVault.constants = {
  * Checks if a string is a valid LP coin name.
  *
  * @param value - The string to check.
- * @returns `true` if `value` is can be used as a valid LP coin name, otherwise `false`.
+ * @returns `true` if `value` can be used as a valid LP coin name, otherwise `false`.
+ *
+ * @remarks
+ * Current rule: ASCII-only. This aligns with many on-chain metadata constraints.
  */
 PerpetualsVault.isValidLpCoinName = (value) => {
     return /^[\x00-\x7F]+$/.test(value);
 };
 /**
- * Checks if a string is a valid LP coin type.
+ * Checks if a string is a valid LP coin type symbol.
  *
  * @param value - The string to check.
- * @returns `true` if `value` is can be used as a valid LP coin type, otherwise `false`.
+ * @returns `true` if `value` can be used as a valid LP coin type symbol, otherwise `false`.
+ *
+ * @remarks
+ * Current rule: uppercase A–Z plus underscore.
  */
 PerpetualsVault.isValidLpCoinTypeSymbol = (value) => {
     return /^[A-Z_]+$/.test(value);
@@ -341,6 +553,17 @@ PerpetualsVault.isValidLpCoinTypeSymbol = (value) => {
 // =========================================================================
 //  Calculations
 // =========================================================================
+/**
+ * Compute the implied slippage tolerance for a withdraw request.
+ *
+ * Defined as:
+ * ```text
+ * (lpAmountInUsd - minCollateralAmountOutUsd) / lpAmountInUsd
+ * ```
+ *
+ * @param inputs.withdrawRequest - Withdraw request to analyze.
+ * @returns Slippage fraction (0..1). Returns `0` if `lpAmountInUsd` is missing/zero.
+ */
 PerpetualsVault.calcWithdrawRequestSlippage = (inputs) => {
     const { withdrawRequest } = inputs;
     return withdrawRequest.lpAmountInUsd

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "aftermath-ts-sdk",
-	"version": "1.3.23-perps.35",
+	"version": "1.3.23-perps.37",
 	"description": "Aftermath TypeScript SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",