aftermath-ts-sdk 1.3.27 → 1.3.28

package/dist/packages/perpetuals/perpetualsMarket.js

@@ -12,77 +12,155 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PerpetualsMarket = void 0;
 const __1 = require("../..");
 const caller_1 = require("../../general/utils/caller");
-const iFixedUtils_1 = require("../../general/utils/iFixedUtils");
 const perpetuals_1 = require("./perpetuals");
-const utils_1 = require("./utils");
+/**
+ * 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 order 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 market = markets[0];
+ *
+ * const { orderbook } = await market.getOrderbook();
+ * const stats = await market.get24hrStats();
+ * const { basePrice, collateralPrice } = await market.getPrices();
+ * ```
+ */
 class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
-    constructor(marketData, config) {
-        super(config, `perpetuals/${marketData.collateralCoinType}/markets/${marketData.objectId}`);
+    /**
+     * 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.).
+     * @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");
         this.marketData = marketData;
-        this.getMaxOrderSizeUsd = (inputs) => __awaiter(this, void 0, void 0, function* () {
-            const { side, price, account, indexPrice, leverage } = inputs;
-            const maxSize = yield this.fetchApi("max-order-size", {
-                accountId: account.accountCap.accountId,
-                collateral: account.collateralBalance(),
-                side,
-                price,
-                leverage,
-            });
-            return Number(maxSize) * this.lotSize() * indexPrice;
+        this.Provider = Provider;
+        /**
+         * Compute the maximum order size that can be placed by a given account
+         * in this market, under optional leverage and price assumptions.
+         *
+         * This is a common frontend helper for:
+         * - "max size" buttons
+         * - input validation against risk limits
+         *
+         * **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 assumed leverage.
+         * @param inputs.price - Optional assumed price (e.g. for limit orders).
+         *
+         * @returns `{ maxOrderSize }` in base units (scaled integer as `bigint`).
+         *
+         * @example
+         * ```ts
+         * const { maxOrderSize } = await market.getMaxOrderSize({
+         *   accountId: 123n,
+         *   side: PerpetualsOrderSide.Bid,
+         *   leverage: 5,
+         * });
+         * ```
+         */
+        // TODO: move/add to account ?
+        this.getMaxOrderSize = (inputs) => __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("account/max-order-size", Object.assign(Object.assign({}, inputs), { marketId: this.marketId }));
         });
         // =========================================================================
-        //  Calculations
+        //  Funding / Timing
         // =========================================================================
+        /**
+         * Compute the remaining time until the next funding event, in milliseconds.
+         *
+         * @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();
         };
+        /**
+         * Get the scheduled timestamp for the next funding event, in milliseconds.
+         *
+         * 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`.
+         */
         this.nextFundingTimeMs = () => {
-            const fundingFrequencyMs = Number(this.marketParams.fundingFrequencyMs);
-            const lastFundingIntervalNumber = Math.floor(this.marketState.fundingLastUpdateMs / fundingFrequencyMs);
-            return (lastFundingIntervalNumber + 1) * fundingFrequencyMs;
-        };
-        // 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)
-        //
-        // To get the rate as a percentage, multiply the output by 100.
-        this.estimatedFundingRate = (inputs) => {
-            const { indexPrice } = inputs;
-            const premiumTwap = iFixedUtils_1.IFixedUtils.numberFromIFixed(this.marketState.premiumTwap);
-            const relativePremium = premiumTwap / indexPrice;
-            const periodAdjustment = Number(this.marketParams.fundingFrequencyMs) /
-                Number(this.marketParams.fundingPeriodMs);
-            return relativePremium * periodAdjustment;
+            return this.marketData.nextFundingTimestampMs >
+                BigInt(Number.MAX_SAFE_INTEGER)
+                ? Number.MAX_SAFE_INTEGER
+                : Number(this.marketData.nextFundingTimestampMs);
         };
-        this.priceToOrderPrice = (inputs) => {
-            const { price } = inputs;
-            const lotSize = this.marketParams.lotSize;
-            const tickSize = this.marketParams.tickSize;
-            return perpetuals_1.Perpetuals.priceToOrderPrice({
-                price,
-                lotSize,
-                tickSize,
-            });
-        };
-        this.orderPriceToPrice = (inputs) => {
-            const { orderPrice } = inputs;
-            const lotSize = this.marketParams.lotSize;
-            const tickSize = this.marketParams.tickSize;
-            return perpetuals_1.Perpetuals.orderPriceToPrice({
-                orderPrice,
-                lotSize,
-                tickSize,
-            });
+        /**
+         * Estimated funding rate per period for this market.
+         *
+         * This is read directly from `marketData.estimatedFundingRate`.
+         *
+         * @returns Estimated funding rate as a fraction (e.g. `0.01` = 1%).
+         */
+        this.estimatedFundingRate = () => {
+            return this.marketData.estimatedFundingRate;
         };
+        // =========================================================================
+        //  Margin / Collateral Calculations
+        // =========================================================================
+        /**
+         * Calculate the collateral required to support an order given leverage and prices.
+         *
+         * The computed collateral is based on the *remaining* unfilled size:
+         * `remaining = initialSize - filledSize`.
+         *
+         * USD requirement:
+         * ```text
+         * remainingBase * indexPrice * initialMarginRatio
+         * ```
+         * where `initialMarginRatio = 1 / leverage` (or 1 if leverage is falsy).
+         *
+         * @param inputs.leverage - Target leverage for the order (>= 1).
+         * @param inputs.orderData - Order data containing `initialSize` and `filledSize`.
+         * @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 coin units
+         */
         this.calcCollateralUsedForOrder = (inputs) => {
             const { leverage, orderData, indexPrice, collateralPrice } = inputs;
-            const imr = 1 / leverage;
-            // const imr = this.initialMarginRatio();
-            const collateralUsd = Number(orderData.initialSize - orderData.filledSize) *
-                this.lotSize() *
+            const imr = 1 / (leverage || 1);
+            const collateralUsd = (Number(orderData.currentSize) / __1.Casting.Fixed.fixedOneN9) *
                 indexPrice *
                 imr;
             const collateral = collateralUsd / collateralPrice;
@@ -91,9 +169,64 @@ class PerpetualsMarket extends caller_1.Caller {
                 collateral,
             };
         };
+        // =========================================================================
+        //  Helpers
+        // =========================================================================
+        /**
+         * Round a price to the nearest valid tick for this market.
+         *
+         * Rounding mode:
+         * - `floor: true` => round down
+         * - `ceil: true`  => round up
+         * - neither       => nearest tick (`Math.round`)
+         *
+         * @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) => {
-            return Math.round(inputs.price / this.tickSize()) * this.tickSize();
+            const ticks = inputs.price / this.tickSize();
+            return ((inputs.floor
+                ? Math.floor(ticks)
+                : inputs.ceil
+                    ? Math.ceil(ticks)
+                    : Math.round(ticks)) * this.tickSize());
+        };
+        /**
+         * Round a price to the nearest valid tick as a fixed-point `bigint` (1e9 precision).
+         *
+         * 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 - 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);
+            return ((BigInt(inputs.floor
+                ? Math.floor(scaledPrice)
+                : inputs.ceil
+                    ? Math.ceil(scaledPrice)
+                    : Math.round(scaledPrice)) /
+                this.marketParams.tickSize) *
+                this.marketParams.tickSize);
         };
+        /**
+         * Round a base-asset size to the nearest valid lot size for this market.
+         *
+         * Rounding mode:
+         * - `floor: true` => round down
+         * - `ceil: true`  => round up
+         * - neither       => nearest lot (`Math.round`)
+         *
+         * @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();
             return ((inputs.floor
@@ -102,7 +235,59 @@ class PerpetualsMarket extends caller_1.Caller {
                     ? Math.ceil(lots)
                     : Math.round(lots)) * this.lotSize());
         };
+        /**
+         * Round a base-asset size to the nearest valid lot as a fixed-point `bigint` (1e9 precision).
+         *
+         * @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);
+            return ((BigInt(inputs.floor
+                ? Math.floor(scaledSize)
+                : inputs.ceil
+                    ? Math.ceil(scaledSize)
+                    : Math.round(scaledSize)) /
+                this.marketParams.lotSize) *
+                this.marketParams.lotSize);
+        };
+        /**
+         * Construct an "empty" position object for this market.
+         *
+         * 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,
+                collateral: 0,
+                collateralUsd: 0,
+                baseAssetAmount: 0,
+                quoteAssetNotionalAmount: 0,
+                cumFundingRateLong: this.marketData.marketState.cumFundingRateLong,
+                cumFundingRateShort: this.marketData.marketState.cumFundingRateShort,
+                asksQuantity: 0,
+                bidsQuantity: 0,
+                pendingOrders: [],
+                makerFee: 1, // 100% (placeholder default)
+                takerFee: 1, // 100% (placeholder default)
+                leverage: 1,
+                entryPrice: 0,
+                freeCollateral: 0,
+                freeMarginUsd: 0,
+                liquidationPrice: 0,
+                marginRatio: 1,
+                unrealizedFundingsUsd: 0,
+                unrealizedPnlUsd: 0,
+            };
+        };
         this.marketId = marketData.objectId;
+        this.indexPrice = marketData.indexPrice;
+        this.collateralPrice = marketData.collateralPrice;
         this.collateralCoinType = marketData.collateralCoinType;
         this.marketParams = marketData.marketParams;
         this.marketState = marketData.marketState;
@@ -110,53 +295,181 @@ class PerpetualsMarket extends caller_1.Caller {
     // =========================================================================
     //  Inspections
     // =========================================================================
-    // NOTE: should this be entirely removed since data already in orderbook function ?
-    getOrderbookPrice() {
-        return this.fetchApi("orderbook-price");
+    /**
+     * Fetch the 24-hour volume and price change statistics for this market.
+     *
+     * Under the hood, this calls {@link Perpetuals.getMarkets24hrStats} and
+     * returns the first (and only) entry.
+     *
+     * @returns {@link PerpetualsMarket24hrStats}.
+     *
+     * @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* () {
+            const res = yield new perpetuals_1.Perpetuals(this.config).getMarkets24hrStats({
+                marketIds: [this.marketId],
+            });
+            return res.marketsStats[0];
+        });
     }
-    get24hrVolume() {
-        return this.fetchApi("24hr-volume");
+    /**
+     * Fetch the full orderbook snapshot for this market.
+     *
+     * @returns Object containing `orderbook`.
+     *
+     * @example
+     * ```ts
+     * const { orderbook } = await market.getOrderbook();
+     * console.log(orderbook.bids[0], orderbook.asks[0]);
+     * ```
+     */
+    // TODO: move to `Perpetuals` class ?
+    getOrderbook() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { orderbooks } = yield this.fetchApi("markets/orderbooks", {
+                marketIds: [this.marketId],
+            });
+            return {
+                orderbook: orderbooks[0].orderbook,
+            };
+        });
     }
-    getPrice24hrsAgo() {
-        return this.fetchApi("price-24hrs-ago");
+    /**
+     * Market-level preview of placing a market order.
+     *
+     * 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* () {
+            return this.fetchApi("account/previews/place-market-order", Object.assign(Object.assign({}, inputs), { accountId: undefined }), abortSignal);
+        });
     }
-    getOrderbook() {
-        return this.fetchApi("orderbook");
+    /**
+     * Market-level preview of placing a limit order.
+     *
+     * Similar to {@link getPlaceMarketOrderPreview}, this uses:
+     * - `account/previews/place-limit-order`
+     * - `accountId: undefined`
+     *
+     * @param inputs - {@link SdkPerpetualsPlaceLimitOrderPreviewInputs}.
+     * @param abortSignal - Optional abort signal to cancel the request.
+     *
+     * @returns Either `{ error }` or a preview describing the simulated post-order state.
+     */
+    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);
+        });
+    }
+    // =========================================================================
+    //  Order History
+    // =========================================================================
+    /**
+     * Fetch paginated order history for this market.
+     *
+     * This is market-wide (public) history, not scoped to any account.
+     *
+     * @param inputs.beforeTimestampCursor - Optional pagination cursor.
+     * @param inputs.limit - Optional page size.
+     *
+     * @returns {@link ApiPerpetualsMarketOrderHistoryResponse} containing:
+     * - `orders`
+     * - `nextBeforeTimestampCursor`
+     */
+    getOrderHistory(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("market/order-history", Object.assign(Object.assign({}, inputs), { marketId: this.marketId }));
+        });
     }
     // =========================================================================
-    //  Trade History
+    //  Prices
     // =========================================================================
-    getTradeHistory(inputs) {
+    /**
+     * Fetch the current prices for this market.
+     *
+     * Internally calls {@link Perpetuals.getPrices} and returns the first result.
+     *
+     * @returns `{ marketId, basePrice, collateralPrice, midPrice, markPrice }`.
+     *
+     * @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 this.fetchApi(`trade-history`, inputs);
+            return (yield new perpetuals_1.Perpetuals(this.config).getPrices({
+                marketIds: [this.marketId],
+            })).marketsPrices[0];
         });
     }
     // =========================================================================
     //  Value Conversions
     // =========================================================================
+    /**
+     * Get the base-asset lot size for this market as a `number`.
+     *
+     * Order sizes must be multiples 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 size for this market as a `number`.
+     *
+     * Limit prices must be multiples 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.
+     */
     maxLeverage() {
-        return (1 /
-            __1.Casting.IFixed.numberFromIFixed(this.marketParams.marginRatioInitial));
+        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 __1.Casting.IFixed.numberFromIFixed(this.marketParams.marginRatioInitial);
+        return this.marketParams.marginRatioInitial;
     }
+    /**
+     * Get the maintenance margin ratio for this market.
+     *
+     * Falling below this ratio may trigger liquidation.
+     *
+     * @returns Maintenance margin ratio as a fraction.
+     */
     maintenanceMarginRatio() {
-        return __1.Casting.IFixed.numberFromIFixed(this.marketParams.marginRatioMaintenance);
-    }
-    // =========================================================================
-    //  Helpers
-    // =========================================================================
-    orderPrice(inputs) {
-        const { orderId } = inputs;
-        const orderPrice = utils_1.PerpetualsOrderUtils.price(orderId);
-        return this.orderPriceToPrice({ orderPrice });
+        return this.marketParams.marginRatioMaintenance;
     }
 }
 exports.PerpetualsMarket = PerpetualsMarket;