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

package/dist/packages/perpetuals/perpetualsMarket.js

@@ -13,15 +13,78 @@ exports.PerpetualsMarket = void 0;
 const __1 = require("../..");
 const caller_1 = require("../../general/utils/caller");
 const perpetuals_1 = require("./perpetuals");
+/**
+ * High-level wrapper around a single perpetuals market.
+ *
+ * This class provides:
+ *
+ * - Lightweight accessors for immutable market properties:
+ *   - `marketId`, `indexPrice`, `collateralPrice`, `collateralCoinType`
+ *   - `marketParams`, `marketState`
+ * - Read endpoints for:
+ *   - Orderbook snapshots
+ *   - 24h stats and trade history
+ *   - Market prices and derived funding metrics
+ * - Helpers for:
+ *   - Order sizing (max size, lot/tick rounding)
+ *   - Margin and collateral calculations
+ *   - Constructing an “empty” position for a market
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const perps = new Perpetuals(config);
+ * const markets = await perps.getMarkets({ marketIds: ["0x..."] });
+ * const btcPerp = new PerpetualsMarket(markets[0], config);
+ *
+ * const ob = await btcPerp.getOrderbook();
+ * const stats = await btcPerp.get24hrStats();
+ * const prices = await btcPerp.getPrices();
+ * ```
+ */
 class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
+    /**
+     * Create a new {@link PerpetualsMarket} wrapper from raw market data.
+     *
+     * @param marketData - Snapshot of market configuration and state.
+     * @param config - Optional {@link CallerConfig} (network, base URL, etc.).
+     */
     constructor(marketData, config
     // public readonly Provider?: AftermathApi
     ) {
         super(config, "perpetuals");
         this.marketData = marketData;
+        /**
+         * 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.
+         *
+         * **Note:** This lives on the `account` namespace since it depends on
+         * account state.
+         *
+         * @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.
+         *
+         * @returns An object containing `maxOrderSize` (as `bigint` in base units).
+         *
+         * @example
+         * ```ts
+         * const { maxOrderSize } = await market.getMaxOrderSize({
+         *   accountId,
+         *   side: PerpetualsOrderSide.Bid,
+         *   leverage: 5,
+         * });
+         * ```
+         */
         // TODO: move/add to account ?
         this.getMaxOrderSize = (inputs) => __awaiter(this, void 0, void 0, function* () {
             const { side, price, accountId, leverage } = inputs;
@@ -35,22 +98,75 @@ class PerpetualsMarket extends caller_1.Caller {
         });
         // =========================================================================
         //  Calculations
-        // =========================================================================
+        // =========================================================================`
+        /**
+         * 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()`.
+         */
         this.timeUntilNextFundingMs = () => {
             return this.nextFundingTimeMs() - Date.now();
         };
+        /**
+         * 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.
+         *
+         * @returns Next funding timestamp (ms) as a JS `number`.
+         */
         this.nextFundingTimeMs = () => {
             return this.marketData.nextFundingTimestampMs >
                 BigInt(Number.MAX_SAFE_INTEGER)
                 ? Number.MAX_SAFE_INTEGER
                 : Number(this.marketData.nextFundingTimestampMs);
         };
+        /**
+         * Estimated funding rate per period for this market.
+         *
+         * Conceptually defined as:
+         *
+         * ```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%).
+         */
         // 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;
         };
+        /**
+         * Calculate the collateral required to support an order given leverage
+         * and prices.
+         *
+         * The formula is (in USD):
+         *
+         * ```text
+         * remainingSizeBase * indexPrice * initialMarginRatio
+         * ```
+         *
+         * where:
+         * - `remainingSizeBase` = `(initialSize - filledSize) / fixedOneN9`
+         * - `initialMarginRatio` = `1 / leverage` (or 1 if leverage is falsy).
+         *
+         * @param inputs.leverage - Target leverage for the order.
+         * @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.
+         *
+         * @returns Object with:
+         * - `collateralUsd`: required collateral in USD.
+         * - `collateral`: required collateral in collateral coins.
+         */
         this.calcCollateralUsedForOrder = (inputs) => {
             const { leverage, orderData, indexPrice, collateralPrice } = inputs;
             const imr = 1 / (leverage || 1);
@@ -70,6 +186,22 @@ class PerpetualsMarket extends caller_1.Caller {
         // =========================================================================
         //  Helpers
         // =========================================================================
+        /**
+         * 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.
+         *
+         * @example
+         * ```ts
+         * const validPrice = market.roundToValidPrice({ price: 27123.45 });
+         * ```
+         */
         this.roundToValidPrice = (inputs) => {
             const ticks = inputs.price / this.tickSize();
             return ((inputs.floor
@@ -78,6 +210,18 @@ class PerpetualsMarket extends caller_1.Caller {
                     ? Math.ceil(ticks)
                     : Math.round(ticks)) * this.tickSize());
         };
+        /**
+         * Round a price to the nearest valid tick for this market, expressed as
+         * a `bigint` scaled by `Fixed.fixedOneN9`.
+         *
+         * This is useful when you need the on-chain representation directly.
+         *
+         * @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`.
+         */
         this.roundToValidPriceBigInt = (inputs) => {
             const scaledPrice = Number(inputs.price * __1.Casting.Fixed.fixedOneN9);
             // TODO: make sure this calc is safe
@@ -89,6 +233,15 @@ class PerpetualsMarket extends caller_1.Caller {
                 this.marketParams.tickSize) *
                 this.marketParams.tickSize);
         };
+        /**
+         * 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.
+         *
+         * @returns Size snapped to a valid lot boundary.
+         */
         this.roundToValidSize = (inputs) => {
             const lots = inputs.size / this.lotSize();
             return ((inputs.floor
@@ -97,6 +250,16 @@ class PerpetualsMarket extends caller_1.Caller {
                     ? Math.ceil(lots)
                     : 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`).
+         *
+         * @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`.
+         */
         this.roundToValidSizeBigInt = (inputs) => {
             const scaledSize = Number(inputs.size * __1.Casting.Fixed.fixedOneN9);
             // TODO: make sure this calc is safe
@@ -108,6 +271,15 @@ class PerpetualsMarket extends caller_1.Caller {
                 this.marketParams.lotSize) *
                 this.marketParams.lotSize);
         };
+        /**
+         * 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.
+         *
+         * @returns A zeroed-out {@link PerpetualsPosition} for `this.marketId`.
+         */
         this.emptyPosition = () => {
             return {
                 marketId: this.marketId,
@@ -143,12 +315,41 @@ class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Inspections
     // =========================================================================
+    /**
+     * Fetch the mid price for this market’s orderbook.
+     *
+     * This is a convenience endpoint that returns only:
+     *
+     * - `midPrice`: The midpoint between best bid and best ask, or `undefined`
+     *   if the orderbook is empty or malformed.
+     *
+     * @returns A promise resolving to `{ midPrice }`.
+     *
+     * @example
+     * ```ts
+     * const { midPrice } = await market.getOrderbookMidPrice();
+     * ```
+     */
     // NOTE: should this be entirely removed since data already in orderbook function ?
     getOrderbookMidPrice() {
         return this.fetchApi("market/orderbook-price", {
             marketId: this.marketId,
         });
     }
+    /**
+     * 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 {@link PerpetualsMarket24hrStats} with volume, high/low, and other metrics.
+     *
+     * @example
+     * ```ts
+     * const stats = await market.get24hrStats();
+     * console.log(stats.volumeUsd, stats.priceChangePct);
+     * ```
+     */
     get24hrStats() {
         return __awaiter(this, void 0, void 0, function* () {
             const stats = yield new perpetuals_1.Perpetuals(this.config).getMarkets24hrStats({
@@ -157,6 +358,21 @@ class PerpetualsMarket extends caller_1.Caller {
             return stats[0];
         });
     }
+    /**
+     * Fetch the full orderbook snapshot for this market.
+     *
+     * Currently implemented via the generic `markets` endpoint with:
+     * - `marketIds: [this.marketId]`
+     * - `withOrderbook: true`
+     *
+     * @returns {@link PerpetualsOrderbook} for this market.
+     *
+     * @example
+     * ```ts
+     * const ob = await market.getOrderbook();
+     * console.log(ob.bids[0], ob.asks[0]);
+     * ```
+     */
     getOrderbook() {
         return __awaiter(this, void 0, void 0, function* () {
             // TODO: create own endpoint for just orderbook
@@ -168,11 +384,47 @@ class PerpetualsMarket extends caller_1.Caller {
             return marketDatas[0].orderbook;
         });
     }
+    /**
+     * 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`
+     */
     getPlaceMarketOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/previews/place-market-order", Object.assign(Object.assign({}, inputs), { accountId: undefined }), abortSignal);
         });
     }
+    /**
+     * Market-level preview of placing a limit order.
+     *
+     * Similar to {@link getPlaceMarketOrderPreview}, this uses:
+     * - `account/previews/place-limit-order`
+     * - `accountId: undefined`
+     *
+     * @param inputs - See {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
+     * @param abortSignal - Optional `AbortSignal` to cancel the request.
+     *
+     * @returns Either:
+     * - `{ error }`, or
+     * - A preview object with post-order position, slippage, and collateral changes.
+     */
     getPlaceLimitOrderPreview(inputs, abortSignal) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("account/previews/place-limit-order", Object.assign(Object.assign({}, inputs), { accountId: undefined }), abortSignal);
@@ -181,6 +433,24 @@ class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Trade History
     // =========================================================================
+    /**
+     * Fetch paginated trade history for this market.
+     *
+     * This returns *market-level* trade history (not account-specific), useful
+     * for charting, recent trades lists, etc.
+     *
+     * @param inputs.cursor - Optional pagination cursor.
+     * @param inputs.limit - Optional number of trades per page.
+     *
+     * @returns {@link PerpetualsTradeHistoryWithCursor} including a list of
+     *   trades and a `nextCursor`.
+     *
+     * @example
+     * ```ts
+     * const result = await market.getTradeHistory({ limit: 100 });
+     * console.log(result.trades.length, result.nextCursor);
+     * ```
+     */
     getTradeHistory(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.fetchApi("market/trade-history", Object.assign(Object.assign({}, inputs), { marketId: this.marketId }));
@@ -189,6 +459,19 @@ class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Prices
     // =========================================================================
+    /**
+     * Fetch the current base and collateral prices for this market.
+     *
+     * Internally calls {@link Perpetuals.getPrices} and returns the first
+     * element corresponding to `this.marketId`.
+     *
+     * @returns `{ basePrice, collateralPrice }` for this market.
+     *
+     * @example
+     * ```ts
+     * const { basePrice, collateralPrice } = await market.getPrices();
+     * ```
+     */
     getPrices() {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield new perpetuals_1.Perpetuals(this.config
@@ -201,18 +484,55 @@ class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Value Conversions
     // =========================================================================
+    /**
+     * Get the base asset lot size for this market as a `number`.
+     *
+     * Order sizes must be a multiple of this lot size.
+     *
+     * @returns Lot size in base asset units.
+     */
     lotSize() {
         return perpetuals_1.Perpetuals.lotOrTickSizeToNumber(this.marketParams.lotSize);
     }
+    /**
+     * Get the minimal price tick for this market as a `number`.
+     *
+     * Limit prices must be a multiple of this tick size.
+     *
+     * @returns Tick size in quote units (e.g. USD).
+     */
     tickSize() {
         return perpetuals_1.Perpetuals.lotOrTickSizeToNumber(this.marketParams.tickSize);
     }
+    /**
+     * Get the maximum theoretical leverage for this market, computed as:
+     *
+     * ```ts
+     * 1 / marginRatioInitial
+     * ```
+     *
+     * @returns Maximum leverage value for opening positions.
+     */
     maxLeverage() {
         return 1 / this.marketParams.marginRatioInitial;
     }
+    /**
+     * Get the initial margin ratio for this market.
+     *
+     * This is the minimum margin required when opening a position.
+     *
+     * @returns Initial margin ratio as a fraction (e.g. 0.05 = 20x).
+     */
     initialMarginRatio() {
         return this.marketParams.marginRatioInitial;
     }
+    /**
+     * Get the maintenance margin ratio for this market.
+     *
+     * Falling below this ratio may result in liquidation.
+     *
+     * @returns Maintenance margin ratio as a fraction.
+     */
     maintenanceMarginRatio() {
         return this.marketParams.marginRatioMaintenance;
     }