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

package/dist/packages/perpetuals/perpetualsMarket.js

@@ -34,12 +34,12 @@ const perpetuals_1 = require("./perpetuals");
  *
  * ```ts
  * const perps = new Perpetuals(config);
- * const markets = await perps.getMarkets({ marketIds: ["0x..."] });
- * const btcPerp = new PerpetualsMarket(markets[0], config);
+ * const { markets } = await perps.getMarkets({ marketIds: ["0x..."] });
+ * const market = markets[0];
  *
- * const ob = await btcPerp.getOrderbook();
- * const stats = await btcPerp.get24hrStats();
- * const prices = await btcPerp.getPrices();
+ * const { orderbook } = await market.getOrderbook();
+ * const stats = await market.get24hrStats();
+ * const { basePrice, collateralPrice } = await market.getPrices();
  * ```
  */
 class PerpetualsMarket extends caller_1.Caller {
@@ -51,6 +51,11 @@ class PerpetualsMarket extends caller_1.Caller {
      *
      * @param marketData - Snapshot of market configuration and state.
      * @param config - Optional {@link CallerConfig} (network, base URL, etc.).
+     * @param Provider - Optional shared {@link AftermathApi} provider instance.
+     *
+     * @remarks
+     * This class extends {@link Caller} with the `"perpetuals"` route prefix, meaning
+     * all HTTP requests resolve under `/perpetuals/...`.
      */
     constructor(marketData, config, Provider) {
         super(config, "perpetuals");
@@ -60,25 +65,24 @@ class PerpetualsMarket extends caller_1.Caller {
          * Compute the maximum order size that can be placed by a given account
          * in this market, under optional leverage and price assumptions.
          *
-         * This is useful for frontends to:
-         * - Drive "max" buttons.
-         * - Validate order inputs against risk limits.
+         * This is a common frontend helper for:
+         * - "max size" buttons
+         * - input validation against risk limits
          *
-         * **Note:** This lives on the `account` namespace since it depends on
-         * account state.
+         * **Note:** This is routed through the `account` namespace because it depends on
+         * the account's collateral and positions.
          *
          * @param inputs.accountId - Perpetuals account ID.
          * @param inputs.side - Order side (Bid/Ask).
-         * @param inputs.leverage - Optional leverage to assume (defaults to account-level).
-         * @param inputs.price - Optional limit price; if omitted, a default or index-based
-         *   assumption may be used by the backend.
+         * @param inputs.leverage - Optional assumed leverage.
+         * @param inputs.price - Optional assumed price (e.g. for limit orders).
          *
-         * @returns An object containing `maxOrderSize` (as `bigint` in base units).
+         * @returns `{ maxOrderSize }` in base units (scaled integer as `bigint`).
          *
          * @example
          * ```ts
          * const { maxOrderSize } = await market.getMaxOrderSize({
-         *   accountId,
+         *   accountId: 123n,
          *   side: PerpetualsOrderSide.Bid,
          *   leverage: 5,
          * });
@@ -96,15 +100,17 @@ class PerpetualsMarket extends caller_1.Caller {
             });
         });
         // =========================================================================
-        //  Calculations
-        // =========================================================================`
+        //  Funding / Timing
+        // =========================================================================
         /**
          * Compute the remaining time until the next funding event, in milliseconds.
          *
-         * - If the on-chain `nextFundingTimestampMs` exceeds `Number.MAX_SAFE_INTEGER`,
-         *   this uses `Number.MAX_SAFE_INTEGER` as a cap via {@link nextFundingTimeMs}.
-         *
          * @returns `nextFundingTimeMs() - Date.now()`.
+         *
+         * @remarks
+         * If the next funding timestamp does not fit safely into a JS `number`,
+         * {@link nextFundingTimeMs} returns `Number.MAX_SAFE_INTEGER`, and the
+         * difference may be very large.
          */
         this.timeUntilNextFundingMs = () => {
             return this.nextFundingTimeMs() - Date.now();
@@ -112,9 +118,9 @@ class PerpetualsMarket extends caller_1.Caller {
         /**
          * Get the scheduled timestamp for the next funding event, in milliseconds.
          *
-         * - If `nextFundingTimestampMs` doesn't fit in JS `number` safely
-         *   (i.e. `> Number.MAX_SAFE_INTEGER`), this method returns
-         *   `Number.MAX_SAFE_INTEGER` as a safeguard.
+         * Safety behavior:
+         * - If `marketData.nextFundingTimestampMs` exceeds `Number.MAX_SAFE_INTEGER`,
+         *   this returns `Number.MAX_SAFE_INTEGER`.
          *
          * @returns Next funding timestamp (ms) as a JS `number`.
          */
@@ -127,52 +133,41 @@ class PerpetualsMarket extends caller_1.Caller {
         /**
          * Estimated funding rate per period for this market.
          *
-         * Conceptually defined as:
+         * This is read directly from `marketData.estimatedFundingRate`.
          *
-         * ```text
-         * (bookTwap - indexTwap) / indexPrice * (fundingFrequency / fundingPeriod)
-         * ```
-         *
-         * but here it's read directly from `marketData.estimatedFundingRate`.
-         *
-         * @returns Estimated funding rate as a fraction (e.g. 0.01 = 1%).
+         * @returns Estimated funding rate as a fraction (e.g. `0.01` = 1%).
          */
-        // The funding rate as the difference between book and index TWAPs relative to the index price,
-        // scaled by the funding period adjustment:
-        // (bookTwap - indexTwap) / indexPrice * (fundingFrequency / fundingPeriod)
         this.estimatedFundingRate = () => {
             return this.marketData.estimatedFundingRate;
         };
+        // =========================================================================
+        //  Margin / Collateral Calculations
+        // =========================================================================
         /**
-         * Calculate the collateral required to support an order given leverage
-         * and prices.
+         * Calculate the collateral required to support an order given leverage and prices.
          *
-         * The formula is (in USD):
+         * The computed collateral is based on the *remaining* unfilled size:
+         * `remaining = initialSize - filledSize`.
          *
+         * USD requirement:
          * ```text
-         * remainingSizeBase * indexPrice * initialMarginRatio
+         * remainingBase * indexPrice * initialMarginRatio
          * ```
+         * where `initialMarginRatio = 1 / leverage` (or 1 if leverage is falsy).
          *
-         * where:
-         * - `remainingSizeBase` = `(initialSize - filledSize) / fixedOneN9`
-         * - `initialMarginRatio` = `1 / leverage` (or 1 if leverage is falsy).
-         *
-         * @param inputs.leverage - Target leverage for the order.
+         * @param inputs.leverage - Target leverage for the order (>= 1).
          * @param inputs.orderData - Order data containing `initialSize` and `filledSize`.
-         * @param inputs.indexPrice - Current index price of the underlying.
-         * @param inputs.collateralPrice - Price of the collateral asset in USD.
+         * @param inputs.indexPrice - Index/oracle price of the base asset.
+         * @param inputs.collateralPrice - Price of the collateral asset.
          *
          * @returns Object with:
-         * - `collateralUsd`: required collateral in USD.
-         * - `collateral`: required collateral in collateral coins.
+         * - `collateralUsd`: required collateral in USD
+         * - `collateral`: required collateral in collateral coin units
          */
         this.calcCollateralUsedForOrder = (inputs) => {
             const { leverage, orderData, indexPrice, collateralPrice } = inputs;
             const imr = 1 / (leverage || 1);
-            // const imr = this.initialMarginRatio();
-            const collateralUsd = 
-            // NOTE: is this safe ?
-            (Number(orderData.initialSize - orderData.filledSize) /
+            const collateralUsd = (Number(orderData.initialSize - orderData.filledSize) /
                 __1.Casting.Fixed.fixedOneN9) *
                 indexPrice *
                 imr;
@@ -188,18 +183,15 @@ class PerpetualsMarket extends caller_1.Caller {
         /**
          * Round a price to the nearest valid tick for this market.
          *
-         * @param inputs.price - Raw price to round.
-         * @param inputs.floor - If `true`, always round down to the previous tick.
-         * @param inputs.ceil - If `true`, always round up to the next tick.
-         *
-         * If neither `floor` nor `ceil` are set, this uses `Math.round`.
-         *
-         * @returns Price snapped to a valid tick.
+         * Rounding mode:
+         * - `floor: true` => round down
+         * - `ceil: true`  => round up
+         * - neither       => nearest tick (`Math.round`)
          *
-         * @example
-         * ```ts
-         * const validPrice = market.roundToValidPrice({ price: 27123.45 });
-         * ```
+         * @param inputs.price - Raw price to round.
+         * @param inputs.floor - Force floor rounding.
+         * @param inputs.ceil - Force ceil rounding.
+         * @returns Price snapped to the market tick size.
          */
         this.roundToValidPrice = (inputs) => {
             const ticks = inputs.price / this.tickSize();
@@ -210,20 +202,18 @@ class PerpetualsMarket extends caller_1.Caller {
                     : Math.round(ticks)) * this.tickSize());
         };
         /**
-         * Round a price to the nearest valid tick for this market, expressed as
-         * a `bigint` scaled by `Fixed.fixedOneN9`.
+         * Round a price to the nearest valid tick as a fixed-point `bigint` (1e9 precision).
          *
-         * This is useful when you need the on-chain representation directly.
+         * This is helpful when you need the on-chain representation directly
+         * (e.g. order price fields stored in 9-decimal fixed).
          *
          * @param inputs.price - Raw price as a JS number.
-         * @param inputs.floor - If `true`, always round down.
-         * @param inputs.ceil - If `true`, always round up.
-         *
-         * @returns Price scaled by `1e9` and snapped to a valid tick as a `bigint`.
+         * @param inputs.floor - Force floor rounding.
+         * @param inputs.ceil - Force ceil rounding.
+         * @returns Tick-snapped price scaled by `1e9`.
          */
         this.roundToValidPriceBigInt = (inputs) => {
             const scaledPrice = Number(inputs.price * __1.Casting.Fixed.fixedOneN9);
-            // TODO: make sure this calc is safe
             return ((BigInt(inputs.floor
                 ? Math.floor(scaledPrice)
                 : inputs.ceil
@@ -235,11 +225,15 @@ class PerpetualsMarket extends caller_1.Caller {
         /**
          * Round a base-asset size to the nearest valid lot size for this market.
          *
-         * @param inputs.size - Raw size in base asset units.
-         * @param inputs.floor - If `true`, always round down.
-         * @param inputs.ceil - If `true`, always round up.
+         * Rounding mode:
+         * - `floor: true` => round down
+         * - `ceil: true`  => round up
+         * - neither       => nearest lot (`Math.round`)
          *
-         * @returns Size snapped to a valid lot boundary.
+         * @param inputs.size - Raw size in base asset units.
+         * @param inputs.floor - Force floor rounding.
+         * @param inputs.ceil - Force ceil rounding.
+         * @returns Size snapped to the market lot size.
          */
         this.roundToValidSize = (inputs) => {
             const lots = inputs.size / this.lotSize();
@@ -250,18 +244,15 @@ class PerpetualsMarket extends caller_1.Caller {
                     : Math.round(lots)) * this.lotSize());
         };
         /**
-         * Round a base-asset size to the nearest valid lot size for this market,
-         * as a scaled `bigint` (`Fixed.fixedOneN9`).
+         * Round a base-asset size to the nearest valid lot as a fixed-point `bigint` (1e9 precision).
          *
-         * @param inputs.size - Raw size in base units.
-         * @param inputs.floor - If `true`, always round down.
-         * @param inputs.ceil - If `true`, always round up.
-         *
-         * @returns Size scaled by `1e9` and snapped to valid lot as a `bigint`.
+         * @param inputs.size - Raw base size as a JS number.
+         * @param inputs.floor - Force floor rounding.
+         * @param inputs.ceil - Force ceil rounding.
+         * @returns Lot-snapped size scaled by `1e9`.
          */
         this.roundToValidSizeBigInt = (inputs) => {
             const scaledSize = Number(inputs.size * __1.Casting.Fixed.fixedOneN9);
-            // TODO: make sure this calc is safe
             return ((BigInt(inputs.floor
                 ? Math.floor(scaledSize)
                 : inputs.ceil
@@ -273,16 +264,14 @@ class PerpetualsMarket extends caller_1.Caller {
         /**
          * Construct an "empty" position object for this market.
          *
-         * This is useful for UI and calculations when an account has no open
-         * position but you still want a full {@link PerpetualsPosition}-shaped
-         * object with defaulted values.
+         * Useful when an account has no open position but downstream UI/calculations
+         * expect a {@link PerpetualsPosition}-shaped object.
          *
          * @returns A zeroed-out {@link PerpetualsPosition} for `this.marketId`.
          */
         this.emptyPosition = () => {
             return {
                 marketId: this.marketId,
-                // collateralCoinType: this.marketData.collateralCoinType,
                 collateral: 0,
                 collateralUsd: 0,
                 baseAssetAmount: 0,
@@ -292,8 +281,8 @@ class PerpetualsMarket extends caller_1.Caller {
                 asksQuantity: 0,
                 bidsQuantity: 0,
                 pendingOrders: [],
-                makerFee: 1, // 100%
-                takerFee: 1, // 100%
+                makerFee: 1, // 100% (placeholder default)
+                takerFee: 1, // 100% (placeholder default)
                 leverage: 1,
                 entryPrice: 0,
                 freeCollateral: 0,
@@ -318,11 +307,10 @@ class PerpetualsMarket extends caller_1.Caller {
      * Fetch the mid price for this market’s orderbook.
      *
      * This is a convenience endpoint that returns only:
+     * - `midPrice`: midpoint between best bid and best ask, or `undefined`
+     *   if the orderbook is empty or unavailable.
      *
-     * - `midPrice`: The midpoint between best bid and best ask, or `undefined`
-     *   if the orderbook is empty or malformed.
-     *
-     * @returns A promise resolving to `{ midPrice }`.
+     * @returns `{ midPrice }`.
      *
      * @example
      * ```ts
@@ -339,15 +327,14 @@ class PerpetualsMarket extends caller_1.Caller {
      * Fetch the 24-hour statistics for this specific market.
      *
      * Under the hood, this calls {@link Perpetuals.getMarkets24hrStats} and
-     * returns the first (and only) entry for this market.
+     * returns the first (and only) entry.
      *
-     * @returns {@link PerpetualsMarket24hrStats} with volume, high/low, and other metrics.
+     * @returns {@link PerpetualsMarket24hrStats}.
      *
-     * @example
-     * ```ts
-     * const stats = await market.get24hrStats();
-     * console.log(stats.volumeUsd, stats.priceChangePct);
-     * ```
+     * @remarks
+     * This method creates a new {@link Perpetuals} instance using `this.config`.
+     * If you need shared Provider behavior, prefer calling `perps.getMarkets24hrStats`
+     * directly with the same Provider you initialized.
      */
     get24hrStats() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -360,22 +347,20 @@ class PerpetualsMarket extends caller_1.Caller {
     /**
      * Fetch the full orderbook snapshot for this market.
      *
-     * Currently implemented via the generic `markets` endpoint with:
-     * - `marketIds: [this.marketId]`
-     * - `withOrderbook: true`
+     * Implementation note:
+     * - Currently implemented via the generic `markets` endpoint with `withOrderbook: true`
+     * - The backend returns `marketDatas[]` which include both `market` and `orderbook`
      *
-     * @returns {@link PerpetualsOrderbook} for this market.
+     * @returns Object containing `orderbook`.
      *
      * @example
      * ```ts
-     * const ob = await market.getOrderbook();
-     * console.log(ob.bids[0], ob.asks[0]);
+     * const { orderbook } = await market.getOrderbook();
+     * console.log(orderbook.bids[0], orderbook.asks[0]);
      * ```
      */
     getOrderbook() {
         return __awaiter(this, void 0, void 0, function* () {
-            // TODO: create own endpoint for just orderbook
-            // return this.fetchApi<PerpetualsOrderbook>("market/orderbook");
             const { marketDatas } = yield this.fetchApi("markets", {
                 marketIds: [this.marketId],
                 withOrderbook: true,
@@ -388,24 +373,16 @@ class PerpetualsMarket extends caller_1.Caller {
     /**
      * Market-level preview of placing a market order.
      *
-     * Unlike the account-specific preview on {@link PerpetualsAccount},
-     * this version:
-     * - Calls `account/previews/place-market-order`.
-     * - Explicitly sets `accountId: undefined`, allowing the backend to use
-     *   generic or hypothetical assumptions about account state.
-     *
-     * @param inputs - See {@link SdkPerpetualsPlaceMarketOrderPreviewInputs}.
-     * @param abortSignal - Optional `AbortSignal` to cancel the HTTP request.
-     *
-     * @returns Either:
-     * - `{ error }`, or
-     * - A preview with:
-     *   - `updatedPosition`
-     *   - `priceSlippage` / `percentSlippage`
-     *   - `filledSize` / `filledSizeUsd`
-     *   - `postedSize` / `postedSizeUsd`
-     *   - `collateralChange`
-     *   - `executionPrice`
+     * Unlike {@link PerpetualsAccount.getPlaceMarketOrderPreview}, this version:
+     * - Calls `account/previews/place-market-order`
+     * - Explicitly sets `accountId: undefined`, allowing a “generic” preview that
+     *   doesn’t rely on a specific account’s on-chain positions/collateral.
+     *
+     * @param inputs - {@link SdkPerpetualsPlaceMarketOrderPreviewInputs}.
+     * @param abortSignal - Optional abort signal to cancel the request.
+     *
+     * @returns Either `{ error }` or a preview containing the simulated updated position,
+     * slippage, filled/posted sizes, collateral change, and execution price.
      */
     getPlaceMarketOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -419,12 +396,10 @@ class PerpetualsMarket extends caller_1.Caller {
      * - `account/previews/place-limit-order`
      * - `accountId: undefined`
      *
-     * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
-     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     * @param inputs - {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
+     * @param abortSignal - Optional abort signal to cancel the request.
      *
-     * @returns Either:
-     * - `{ error }`, or
-     * - A preview object with post-order position, slippage, and collateral changes.
+     * @returns Either `{ error }` or a preview describing the simulated post-order state.
      */
     getPlaceLimitOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -437,20 +412,14 @@ class PerpetualsMarket extends caller_1.Caller {
     /**
      * Fetch paginated order history for this market.
      *
-     * This returns *market-level* order history (not account-specific), useful
-     * for charting, recent orders lists, etc.
-     *
-     * @param inputs.cursor - Optional pagination cursor.
-     * @param inputs.limit - Optional number of orders per page.
+     * This is market-wide (public) history, not scoped to any account.
      *
-     * @returns {@link ApiPerpetualsMarketOrderHistoryResponse} including a list of
-     *   orders and a `nextBeforeTimestampCursor`.
+     * @param inputs.beforeTimestampCursor - Optional pagination cursor.
+     * @param inputs.limit - Optional page size.
      *
-     * @example
-     * ```ts
-     * const result = await market.getOrderHistory({ limit: 100 });
-     * console.log(result.orders.length, result.nextBeforeTimestampCursor);
-     * ```
+     * @returns {@link ApiPerpetualsMarketOrderHistoryResponse} containing:
+     * - `orders`
+     * - `nextBeforeTimestampCursor`
      */
     getOrderHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -463,21 +432,17 @@ class PerpetualsMarket extends caller_1.Caller {
     /**
      * Fetch the current base and collateral prices for this market.
      *
-     * Internally calls {@link Perpetuals.getPrices} and returns the first
-     * element corresponding to `this.marketId`.
+     * Internally calls {@link Perpetuals.getPrices} and returns the first result.
      *
-     * @returns `{ basePrice, collateralPrice }` for this market.
+     * @returns `{ basePrice, collateralPrice }`.
      *
-     * @example
-     * ```ts
-     * const { basePrice, collateralPrice } = await market.getPrices();
-     * ```
+     * @remarks
+     * This method instantiates a new {@link Perpetuals} client using `this.config`.
+     * If you rely on a shared Provider, call `perps.getPrices(...)` directly instead.
      */
     getPrices() {
         return __awaiter(this, void 0, void 0, function* () {
-            return (yield new perpetuals_1.Perpetuals(this.config
-            // this.Provider
-            ).getPrices({
+            return (yield new perpetuals_1.Perpetuals(this.config).getPrices({
                 marketIds: [this.marketId],
             })).marketsPrices[0];
         });
@@ -486,9 +451,9 @@ class PerpetualsMarket extends caller_1.Caller {
     //  Value Conversions
     // =========================================================================
     /**
-     * Get the base asset lot size for this market as a `number`.
+     * Get the base-asset lot size for this market as a `number`.
      *
-     * Order sizes must be a multiple of this lot size.
+     * Order sizes must be multiples of this lot size.
      *
      * @returns Lot size in base asset units.
      */
@@ -496,9 +461,9 @@ class PerpetualsMarket extends caller_1.Caller {
         return perpetuals_1.Perpetuals.lotOrTickSizeToNumber(this.marketParams.lotSize);
     }
     /**
-     * Get the minimal price tick for this market as a `number`.
+     * Get the minimal price tick size for this market as a `number`.
      *
-     * Limit prices must be a multiple of this tick size.
+     * Limit prices must be multiples of this tick size.
      *
      * @returns Tick size in quote units (e.g. USD).
      */
@@ -506,13 +471,14 @@ class PerpetualsMarket extends caller_1.Caller {
         return perpetuals_1.Perpetuals.lotOrTickSizeToNumber(this.marketParams.tickSize);
     }
     /**
-     * Get the maximum theoretical leverage for this market, computed as:
+     * Get the maximum theoretical leverage for this market.
      *
+     * Computed as:
      * ```ts
      * 1 / marginRatioInitial
      * ```
      *
-     * @returns Maximum leverage value for opening positions.
+     * @returns Maximum leverage.
      */
     maxLeverage() {
         return 1 / this.marketParams.marginRatioInitial;
@@ -530,7 +496,7 @@ class PerpetualsMarket extends caller_1.Caller {
     /**
      * Get the maintenance margin ratio for this market.
      *
-     * Falling below this ratio may result in liquidation.
+     * Falling below this ratio may trigger liquidation.
      *
      * @returns Maintenance margin ratio as a fraction.
      */