@morpho-org/midnight-sdk 1.5.1-next.0 → 1.7.0-next.0

package/lib/esm/api/MidnightApi.d.ts

@@ -65,9 +65,9 @@ export declare class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Paginated books mapped to SDK camelCase fields.
+     * @returns Paginated books mapped to SDK camelCase fields, with each book's price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds` filter.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds`, `chainIds`, `loanTokens`, `collateralTokens`, or `maturities` filters.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -90,7 +90,7 @@ export declare class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Book snapshot mapped to SDK camelCase fields.
+     * @returns Book snapshot mapped to SDK camelCase fields, with price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when the returned book's `market_id` does not match, or cannot be derived from, its own market params, or when it differs from the requested `marketId`.
      * @example
@@ -115,7 +115,7 @@ export declare class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Price levels mapped to SDK camelCase fields.
+     * @returns Price levels mapped to SDK camelCase fields, sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
      * @example
@@ -142,7 +142,7 @@ export declare class MidnightApi {
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -171,9 +171,10 @@ export declare class MidnightApi {
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns Quote and signed ABI-ready take caps mapped from the API response.
+     * @throws {InvalidMidnightApiQuoteTargetError} when the runtime input does not set exactly one of `units` or `assets`.
      * @throws {NegativeValueError} when `settlementFee` is negative.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API returns a malformed success response or the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, when its caps or buy-side receiver are not executable, or when the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
      * @throws {SettlementFeeExceedsPriceError} when a bid's settlement fee exceeds its offer price.
      * @example
      * ```ts
@@ -204,7 +205,7 @@ export declare class MidnightApi {
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns Paginated ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -321,9 +322,9 @@ export declare class MidnightApi {
      * @param params.marketIds - Optional market id filters.
      * @param params.limit - Optional maximum number of books to return.
      * @param params.cursor - Optional opaque pagination cursor from a previous response.
-     * @returns Paginated books mapped to SDK camelCase fields.
+     * @returns Paginated books mapped to SDK camelCase fields, with each book's price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds` filter.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds`, `chainIds`, `loanTokens`, `collateralTokens`, or `maturities` filters.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -341,7 +342,7 @@ export declare class MidnightApi {
      *
      * @param params.marketId - Market id whose book to read.
      * @param params.depth - Optional maximum levels returned per side.
-     * @returns Book snapshot mapped to SDK camelCase fields.
+     * @returns Book snapshot mapped to SDK camelCase fields, with price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when the returned book's `market_id` does not match, or cannot be derived from, its own market params, or when it differs from the requested `marketId`.
      * @example
@@ -364,7 +365,7 @@ export declare class MidnightApi {
      * @param params.marketId - Market id whose book side to read.
      * @param params.side - Book side to query.
      * @param params.depth - Optional maximum levels returned.
-     * @returns Price levels mapped to SDK camelCase fields.
+     * @returns Price levels mapped to SDK camelCase fields, sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
      * @example
@@ -389,7 +390,7 @@ export declare class MidnightApi {
      * @param params.side - Book side to query.
      * @returns ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -416,9 +417,10 @@ export declare class MidnightApi {
      * @param params.slippage - Optional slippage percentage used to derive the guard. Mutually exclusive with `params.averageWorstPrice`.
      * @param params.settlementFee - Optional current WAD-scaled settlement fee used for local guard validation. Defaults to zero.
      * @returns Quote and signed ABI-ready take caps mapped from the API response.
+     * @throws {InvalidMidnightApiQuoteTargetError} when the runtime input does not set exactly one of `units` or `assets`.
      * @throws {NegativeValueError} when `settlementFee` is negative.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API returns a malformed success response or the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, when its caps or buy-side receiver are not executable, or when the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
      * @throws {SettlementFeeExceedsPriceError} when a bid's settlement fee exceeds its offer price.
      * @example
      * ```ts
@@ -446,7 +448,7 @@ export declare class MidnightApi {
      * @param params.cursor - Optional opaque pagination cursor from a previous response.
      * @returns Paginated ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";

package/lib/esm/api/MidnightApi.js

@@ -1,8 +1,8 @@
 import { assertNonNegative, MathLib } from "@morpho-org/morpho-ts";
-import { InvalidMidnightApiResponseError } from "../errors.js";
+import { InvalidMidnightApiQuoteTargetError, InvalidMidnightApiResponseError, } from "../errors.js";
 import { TakeAmountsLib } from "../math/index.js";
 import { Payload } from "../signatures/Payload.js";
-import { buildBookPath, mapBoundBookMarket, mapBoundBooks, mapBoundTakeableOffers, mapPriceLevel, parseValidationResponse, requestMidnightApi, } from "./helpers.js";
+import { buildBookPath, mapBoundBookMarket, mapBoundBooks, mapBoundTakeableOffers, mapPriceLevels, parseValidationResponse, requestMidnightApi, } from "./helpers.js";
 export { MempoolPayloadValidationRule } from "./types.js";
 /**
  * Midnight API client and stateless helper surface for books and mempool data.
@@ -73,9 +73,9 @@ export class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Paginated books mapped to SDK camelCase fields.
+     * @returns Paginated books mapped to SDK camelCase fields, with each book's price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds` filter.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds`, `chainIds`, `loanTokens`, `collateralTokens`, or `maturities` filters.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -106,7 +106,13 @@ export class MidnightApi {
         });
         return {
             cursor: response.cursor,
-            data: mapBoundBooks(response.data, input.marketIds),
+            data: mapBoundBooks(response.data, {
+                marketIds: input.marketIds,
+                chainIds: input.chainIds,
+                loanTokens: input.loanTokens,
+                collateralTokens: input.collateralTokens,
+                maturities: input.maturities,
+            }),
         };
     }
     /**
@@ -119,7 +125,7 @@ export class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Book snapshot mapped to SDK camelCase fields.
+     * @returns Book snapshot mapped to SDK camelCase fields, with price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when the returned book's `market_id` does not match, or cannot be derived from, its own market params, or when it differs from the requested `marketId`.
      * @example
@@ -157,7 +163,7 @@ export class MidnightApi {
      * @param params.baseUrl - Optional Midnight API base URL override.
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
-     * @returns Price levels mapped to SDK camelCase fields.
+     * @returns Price levels mapped to SDK camelCase fields, sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
      * @example
@@ -182,7 +188,7 @@ export class MidnightApi {
             },
         });
         return {
-            data: response.data.map(mapPriceLevel),
+            data: mapPriceLevels(response.data, input.side),
         };
     }
     /**
@@ -197,7 +203,7 @@ export class MidnightApi {
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -243,9 +249,10 @@ export class MidnightApi {
      * @param params.fetch - Optional fetch implementation override.
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns Quote and signed ABI-ready take caps mapped from the API response.
+     * @throws {InvalidMidnightApiQuoteTargetError} when the runtime input does not set exactly one of `units` or `assets`.
      * @throws {NegativeValueError} when `settlementFee` is negative.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API returns a malformed success response or the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, when its caps or buy-side receiver are not executable, or when the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
      * @throws {SettlementFeeExceedsPriceError} when a bid's settlement fee exceeds its offer price.
      * @example
      * ```ts
@@ -262,6 +269,8 @@ export class MidnightApi {
      */
     static async fetchBookQuote(params) {
         const input = params;
+        if ((input.units == null) === (input.assets == null))
+            throw new InvalidMidnightApiQuoteTargetError();
         const settlementFee = BigInt(input.settlementFee ?? 0n);
         assertNonNegative("settlementFee", settlementFee);
         const response = await requestMidnightApi({
@@ -368,7 +377,7 @@ export class MidnightApi {
      * @param params.request - Optional fetch options forwarded to this request.
      * @returns Paginated ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -533,9 +542,9 @@ export class MidnightApi {
      * @param params.marketIds - Optional market id filters.
      * @param params.limit - Optional maximum number of books to return.
      * @param params.cursor - Optional opaque pagination cursor from a previous response.
-     * @returns Paginated books mapped to SDK camelCase fields.
+     * @returns Paginated books mapped to SDK camelCase fields, with each book's price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds` filter.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned book's `market_id` does not match, or cannot be derived from, its own market params, or when a returned book falls outside the supplied `marketIds`, `chainIds`, `loanTokens`, `collateralTokens`, or `maturities` filters.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -558,7 +567,7 @@ export class MidnightApi {
      *
      * @param params.marketId - Market id whose book to read.
      * @param params.depth - Optional maximum levels returned per side.
-     * @returns Book snapshot mapped to SDK camelCase fields.
+     * @returns Book snapshot mapped to SDK camelCase fields, with price levels sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when the returned book's `market_id` does not match, or cannot be derived from, its own market params, or when it differs from the requested `marketId`.
      * @example
@@ -586,7 +595,7 @@ export class MidnightApi {
      * @param params.marketId - Market id whose book side to read.
      * @param params.side - Book side to query.
      * @param params.depth - Optional maximum levels returned.
-     * @returns Price levels mapped to SDK camelCase fields.
+     * @returns Price levels mapped to SDK camelCase fields, sorted best first (asks ascending tick, bids descending tick).
      * @throws {MidnightApiError} when the API returns a non-2xx response.
      * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
      * @example
@@ -616,7 +625,7 @@ export class MidnightApi {
      * @param params.side - Book side to query.
      * @returns ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";
@@ -648,9 +657,10 @@ export class MidnightApi {
      * @param params.slippage - Optional slippage percentage used to derive the guard. Mutually exclusive with `params.averageWorstPrice`.
      * @param params.settlementFee - Optional current WAD-scaled settlement fee used for local guard validation. Defaults to zero.
      * @returns Quote and signed ABI-ready take caps mapped from the API response.
+     * @throws {InvalidMidnightApiQuoteTargetError} when the runtime input does not set exactly one of `units` or `assets`.
      * @throws {NegativeValueError} when `settlementFee` is negative.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API returns a malformed success response or the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, when its caps or buy-side receiver are not executable, or when the returned offers imply a rounded aggregate settlement price outside the effective average-worst-price guard.
      * @throws {SettlementFeeExceedsPriceError} when a bid's settlement fee exceeds its offer price.
      * @example
      * ```ts
@@ -683,7 +693,7 @@ export class MidnightApi {
      * @param params.cursor - Optional opaque pagination cursor from a previous response.
      * @returns Paginated ABI-ready take objects mapped from the API response.
      * @throws {MidnightApiError} when the API returns a non-2xx response.
-     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON.
+     * @throws {InvalidMidnightApiResponseError} when the API success response is not JSON, when a returned offer cannot be mapped (malformed numeric or hex fields), when its `market_id` does not match, or cannot be derived from, its embedded market, when it falls outside the requested filters, when its `receiverIfMakerIsSeller` is not a well-formed address, or when its caps or buy-side receiver are not executable.
      * @example
      * ```ts
      * import { MidnightApi } from "@morpho-org/midnight-sdk/api";

package/lib/esm/api/helpers.d.ts

@@ -14,16 +14,28 @@ export declare function buildBookPath(params: {
  * its own market params. Recomputing the id with `MarketUtils.toId` (mirroring the
  * takeable-offers path) stops a hostile API from pairing a trusted id with foreign
  * metadata; every book flows through here, so both bound paths reject the same substitution.
+ * Collaterals are returned in the protocol's canonical order so their array index matches
+ * the onchain `collateralIndex`.
  */
 export declare function mapBookMarket(book: ApiBookMarketResponse): MidnightApiBookMarket;
 /** @internal Maps a book market, binding its verified id to the requested market. */
 export declare function mapBoundBookMarket(book: ApiBookMarketResponse, requestedMarketId: Hash): MidnightApiBookMarket;
-/** @internal Maps listed book markets, binding each verified id to the requested market_ids filter when present. */
-export declare function mapBoundBooks(books: readonly ApiBookMarketResponse[], marketIds?: readonly Hash[]): MidnightApiBookMarket[];
+/** @internal Requested `fetchBooks` filters that every returned book must satisfy. */
+export interface BookFilterContext {
+    readonly marketIds?: readonly Hash[];
+    readonly chainIds?: readonly number[];
+    readonly loanTokens?: readonly Address[];
+    readonly collateralTokens?: readonly Address[];
+    readonly maturities?: readonly number[];
+}
+/** @internal Maps listed book markets, binding each verified id to requested filters when present. */
+export declare function mapBoundBooks(books: readonly ApiBookMarketResponse[], context?: BookFilterContext): MidnightApiBookMarket[];
 /** @internal Maps a collateral API payload to the SDK response shape. */
 export declare function mapCollateral(collateral: ApiCollateralResponse): MidnightApiCollateral;
 /** @internal Maps a price-level API payload to the SDK response shape. */
 export declare function mapPriceLevel(level: ApiPriceLevelResponse): MidnightApiPriceLevel;
+/** @internal Maps API price levels and sorts them best first: asks by ascending tick, bids by descending tick. */
+export declare function mapPriceLevels(levels: readonly ApiPriceLevelResponse[], side: MidnightApiBookSide): MidnightApiPriceLevel[];
 /** @internal Maps a takeable-offer API payload to the SDK response shape. */
 export declare function mapTakeableOffer(takeableOffer: ApiTakeableOfferResponse): MidnightApiTake;
 /** @internal API response context required for a takeable offer to be executable for the caller's request. */

package/lib/esm/api/helpers.js

@@ -1,7 +1,8 @@
 import { BLUE_API_BASE_URL, isHexEqual } from "@morpho-org/morpho-ts";
 import { isAddress, isAddressEqual, maxUint256, } from "viem";
-import { InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
+import { InvalidMidnightApiResponseError, InvalidOfferParameterError, MidnightApiError, } from "../errors.js";
 import { MarketUtils } from "../market/index.js";
+import { OfferUtils } from "../offers/index.js";
 import { MempoolPayloadValidationRule, } from "./types.js";
 import { MIDNIGHT_SDK_VERSION } from "./version.generated.js";
 const DEFAULT_MIDNIGHT_API_URL = new URL("/v0/midnight", BLUE_API_BASE_URL);
@@ -86,6 +87,8 @@ export function buildBookPath(params) {
  * its own market params. Recomputing the id with `MarketUtils.toId` (mirroring the
  * takeable-offers path) stops a hostile API from pairing a trusted id with foreign
  * metadata; every book flows through here, so both bound paths reject the same substitution.
+ * Collaterals are returned in the protocol's canonical order so their array index matches
+ * the onchain `collateralIndex`.
  */
 export function mapBookMarket(book) {
     let derivedMarketId;
@@ -121,13 +124,15 @@ export function mapBookMarket(book) {
         chainId: book.chain_id,
         midnight: book.midnight,
         loanToken: book.loan_token,
-        collaterals: book.collaterals.map(mapCollateral),
+        collaterals: [...book.collaterals]
+            .sort(MarketUtils.compareCollateralTokens)
+            .map(mapCollateral),
         maturity: book.maturity,
         rcfThreshold: book.rcf_threshold,
         enterGate: book.enter_gate,
         liquidatorGate: book.liquidator_gate,
-        asks: book.asks.map(mapPriceLevel),
-        bids: book.bids.map(mapPriceLevel),
+        asks: mapPriceLevels(book.asks, "asks"),
+        bids: mapPriceLevels(book.bids, "bids"),
     };
 }
 /** @internal Maps a book market, binding its verified id to the requested market. */
@@ -138,15 +143,36 @@ export function mapBoundBookMarket(book, requestedMarketId) {
     }
     return market;
 }
-/** @internal Maps listed book markets, binding each verified id to the requested market_ids filter when present. */
-export function mapBoundBooks(books, marketIds) {
+/** @internal Maps listed book markets, binding each verified id to requested filters when present. */
+export function mapBoundBooks(books, context = {}) {
     return books.map((book) => {
         const market = mapBookMarket(book);
-        if (marketIds != null &&
-            marketIds.length > 0 &&
-            !marketIds.some((marketId) => isHexEqual(marketId, market.marketId))) {
+        if (context.marketIds != null &&
+            context.marketIds.length > 0 &&
+            !context.marketIds.some((marketId) => isHexEqual(marketId, market.marketId))) {
             throw new InvalidMidnightApiResponseError(`Midnight API book market_id "${market.marketId}" is outside the requested market_ids filter.`);
         }
+        if (context.chainIds != null &&
+            context.chainIds.length > 0 &&
+            !context.chainIds.includes(market.chainId)) {
+            throw new InvalidMidnightApiResponseError(`Midnight API book market_id "${market.marketId}" is outside the requested chain_ids filter.`);
+        }
+        if (context.loanTokens != null &&
+            context.loanTokens.length > 0 &&
+            !context.loanTokens.some((token) => isAddressEqual(token, market.loanToken))) {
+            throw new InvalidMidnightApiResponseError(`Midnight API book market_id "${market.marketId}" is outside the requested loan_tokens filter.`);
+        }
+        const { collateralTokens } = context;
+        if (collateralTokens != null &&
+            collateralTokens.length > 0 &&
+            !market.collaterals.some((collateral) => collateralTokens.some((token) => isAddressEqual(token, collateral.token)))) {
+            throw new InvalidMidnightApiResponseError(`Midnight API book market_id "${market.marketId}" is outside the requested collateral_tokens filter.`);
+        }
+        if (context.maturities != null &&
+            context.maturities.length > 0 &&
+            !context.maturities.includes(market.maturity)) {
+            throw new InvalidMidnightApiResponseError(`Midnight API book market_id "${market.marketId}" is outside the requested maturities filter.`);
+        }
         return market;
     });
 }
@@ -169,6 +195,12 @@ export function mapPriceLevel(level) {
         count: level.count,
     };
 }
+/** @internal Maps API price levels and sorts them best first: asks by ascending tick, bids by descending tick. */
+export function mapPriceLevels(levels, side) {
+    return levels
+        .map(mapPriceLevel)
+        .sort((a, b) => (side === "asks" ? a.tick - b.tick : b.tick - a.tick));
+}
 /** @internal Maps a takeable-offer API payload to the SDK response shape. */
 export function mapTakeableOffer(takeableOffer) {
     const offer = takeableOffer.offer;
@@ -212,11 +244,38 @@ export function mapTakeableOffer(takeableOffer) {
 /** @internal Maps, validates, and best-price-sorts API takeable offers. */
 export function mapBoundTakeableOffers(takeableOffers, context) {
     const mapped = takeableOffers.map((takeableOffer) => {
-        const take = mapTakeableOffer(takeableOffer);
-        const embeddedMarketId = MarketUtils.toId(take.offer.market);
-        if (!isHexEqual(embeddedMarketId, take.marketId)) {
+        let take;
+        let matchesAdvertisedId;
+        let embeddedMarketId;
+        try {
+            take = mapTakeableOffer(takeableOffer);
+            embeddedMarketId = MarketUtils.toId(take.offer.market);
+            matchesAdvertisedId = isHexEqual(embeddedMarketId, take.marketId);
+        }
+        catch (cause) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer market_id "${takeableOffer.market_id}" could not be mapped or validated against its embedded offer market.`, { cause });
+        }
+        if (!matchesAdvertisedId) {
             throw new InvalidMidnightApiResponseError(`Midnight API takeable offer market_id "${take.marketId}" does not match embedded offer market "${embeddedMarketId}".`);
         }
+        const { maxUnits, maxAssets, buy, maker, receiverIfMakerIsSeller } = take.offer;
+        if (!isAddress(receiverIfMakerIsSeller)) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer receiverIfMakerIsSeller "${receiverIfMakerIsSeller}" is not an address.`);
+        }
+        try {
+            // Return values unused: called only to enforce the cap-shape and buy-receiver invariants.
+            OfferUtils.validateOfferCaps({ maxUnits, maxAssets });
+            OfferUtils.resolveReceiverIfMakerIsSeller({
+                buy,
+                maker,
+                receiverIfMakerIsSeller,
+            });
+        }
+        catch (cause) {
+            if (!(cause instanceof InvalidOfferParameterError))
+                throw cause;
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer for market_id "${take.marketId}" is not executable: ${cause.message}`, { cause });
+        }
         if (context.marketId != null &&
             !isHexEqual(take.marketId, context.marketId)) {
             throw new InvalidMidnightApiResponseError(`Midnight API takeable offer market_id "${take.marketId}" does not match requested market "${context.marketId}".`);

package/lib/esm/api/index.d.ts

@@ -1,2 +1,2 @@
-export { InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
+export { InvalidMidnightApiQuoteTargetError, InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
 export * from "./MidnightApi.js";

package/lib/esm/api/index.js

@@ -1,2 +1,2 @@
-export { InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
+export { InvalidMidnightApiQuoteTargetError, InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
 export * from "./MidnightApi.js";

package/lib/esm/api/types.d.ts

@@ -341,7 +341,7 @@ export interface MidnightApiBookMarket {
     readonly midnight: Address;
     /** Loan token address. */
     readonly loanToken: Address;
-    /** Collateral definitions for the market. */
+    /** Collateral definitions for the market, in canonical `collateralIndex` order. */
     readonly collaterals: readonly MidnightApiCollateral[];
     /** Market maturity timestamp in unix seconds. */
     readonly maturity: number;

package/lib/esm/api/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** @internal Installed Midnight SDK package version. */
-export declare const MIDNIGHT_SDK_VERSION = "1.5.1-next.0";
+export declare const MIDNIGHT_SDK_VERSION = "1.7.0-next.0";

package/lib/esm/api/version.generated.js

@@ -1,3 +1,3 @@
 // Generated by scripts/release/generate-midnight-package-version.mjs. Do not edit.
 /** @internal Installed Midnight SDK package version. */
-export const MIDNIGHT_SDK_VERSION = "1.5.1-next.0";
+export const MIDNIGHT_SDK_VERSION = "1.7.0-next.0";

package/lib/esm/errors.d.ts

@@ -339,3 +339,16 @@ export declare class MidnightApiError extends Error {
 export declare class InvalidMidnightApiResponseError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Thrown when a Midnight API quote request does not target exactly one of `units` or `assets`.
+ *
+ * @example
+ * ```ts
+ * import { InvalidMidnightApiQuoteTargetError } from "@morpho-org/midnight-sdk/api";
+ *
+ * throw new InvalidMidnightApiQuoteTargetError();
+ * ```
+ */
+export declare class InvalidMidnightApiQuoteTargetError extends Error {
+    constructor(options?: ErrorOptions);
+}

package/lib/esm/errors.js

@@ -395,3 +395,19 @@ export class InvalidMidnightApiResponseError extends Error {
         this.name = "InvalidMidnightApiResponseError";
     }
 }
+/**
+ * Thrown when a Midnight API quote request does not target exactly one of `units` or `assets`.
+ *
+ * @example
+ * ```ts
+ * import { InvalidMidnightApiQuoteTargetError } from "@morpho-org/midnight-sdk/api";
+ *
+ * throw new InvalidMidnightApiQuoteTargetError();
+ * ```
+ */
+export class InvalidMidnightApiQuoteTargetError extends Error {
+    constructor(options) {
+        super("Midnight API quote requires exactly one of `units` or `assets`. Provide a single target amount.", options);
+        this.name = "InvalidMidnightApiQuoteTargetError";
+    }
+}

package/lib/esm/market/Market.js

@@ -132,7 +132,7 @@ export class MarketParams {
             }
             seenCollateralTokens.add(token);
         }
-        this.collateralParams = collateralParams.sort((a, b) => a.token.toLowerCase() < b.token.toLowerCase() ? -1 : 1);
+        this.collateralParams = collateralParams.sort(MarketUtils.compareCollateralTokens);
         this.maturity = BigInt(params.maturity);
         this.rcfThreshold = BigInt(params.rcfThreshold);
         this.enterGate = params.enterGate;

package/lib/esm/market/MarketUtils.d.ts

@@ -1,4 +1,5 @@
 import { type BigIntish } from "@morpho-org/morpho-ts";
+import { type Address } from "viem";
 import { type CollateralParams, type ICollateralParams, type MarketInput, MarketParams, type SettlementFeeCbps } from "./Market.js";
 type CollateralParamsInput = ICollateralParams | CollateralParams;
 /**
@@ -12,6 +13,19 @@ type CollateralParamsInput = ICollateralParams | CollateralParams;
  * ```
  */
 export declare namespace MarketUtils {
+    /**
+     * @internal Orders collaterals by token address, case-insensitively, matching the protocol's
+     * canonical `collateralIndex` order used by `MarketParams` and `MarketUtils.hash`.
+     *
+     * @param a - First collateral.
+     * @param b - Second collateral.
+     * @returns Negative when `a` sorts before `b`, positive when after, `0` when tokens are equal.
+     */
+    function compareCollateralTokens(a: {
+        readonly token: Address;
+    }, b: {
+        readonly token: Address;
+    }): -1 | 0 | 1;
     /**
      * Converts collateral params from a plain input or ABI tuple.
      *

package/lib/esm/market/MarketUtils.js

@@ -1,5 +1,5 @@
 import { assertNonNegative, MathLib, } from "@morpho-org/morpho-ts";
-import { concat, encodeAbiParameters, encodePacked, keccak256 } from "viem";
+import { concat, encodeAbiParameters, encodePacked, keccak256, } from "viem";
 import { CBP, COLLATERAL_PARAMS_TYPEHASH, MARKET_TYPEHASH, SETTLEMENT_FEE_BREAKPOINTS, } from "../constants.js";
 import { InvalidMarketParameterError, UnknownCollateralIndexError, } from "../errors.js";
 import { MarketParams, } from "./Market.js";
@@ -56,6 +56,22 @@ const marketParamsAbiParameter = {
  */
 export var MarketUtils;
 (function (MarketUtils) {
+    /**
+     * @internal Orders collaterals by token address, case-insensitively, matching the protocol's
+     * canonical `collateralIndex` order used by `MarketParams` and `MarketUtils.hash`.
+     *
+     * @param a - First collateral.
+     * @param b - Second collateral.
+     * @returns Negative when `a` sorts before `b`, positive when after, `0` when tokens are equal.
+     */
+    function compareCollateralTokens(a, b) {
+        const tokenA = a.token.toLowerCase();
+        const tokenB = b.token.toLowerCase();
+        if (tokenA === tokenB)
+            return 0;
+        return tokenA < tokenB ? -1 : 1;
+    }
+    MarketUtils.compareCollateralTokens = compareCollateralTokens;
     /**
      * Converts collateral params from a plain input or ABI tuple.
      *
@@ -299,7 +315,7 @@ export var MarketUtils;
         const marketParams = "params" in market ? market.params : market;
         const collateralParams = marketParams.collateralParams.length === 0
             ? marketParams.collateralParams
-            : [...marketParams.collateralParams].sort((a, b) => a.token.toLowerCase() < b.token.toLowerCase() ? -1 : 1);
+            : [...marketParams.collateralParams].sort(compareCollateralTokens);
         const collateralParamHashes = collateralParams.map((params) => keccak256(encodeAbiParameters(collateralParamsHashParams, [
             COLLATERAL_PARAMS_TYPEHASH,
             params.token,

package/lib/esm/offers/Offer.d.ts

@@ -526,7 +526,7 @@ export declare class Offer {
      * @param params.tickSpacing - Optional market tick spacing; defaults to `DEFAULT_TICK_SPACING`.
      * @param params.maxUnits - Optional unit cap; defaults to zero.
      * @param params.maxAssets - Optional buyer or seller asset cap; defaults to zero.
-     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to `MAX_CONTINUOUS_FEE`.
+     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to `0n` (fail-closed: no market continuous fee accepted unless set explicitly).
      * @param params.start - Optional offer start timestamp; defaults to zero.
      * @param params.expiry - Offer expiry timestamp.
      * @param params.callback - Optional callback address; defaults to the zero address.

package/lib/esm/offers/Offer.js

@@ -476,7 +476,7 @@ export class Offer {
      * @param params.tickSpacing - Optional market tick spacing; defaults to `DEFAULT_TICK_SPACING`.
      * @param params.maxUnits - Optional unit cap; defaults to zero.
      * @param params.maxAssets - Optional buyer or seller asset cap; defaults to zero.
-     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to `MAX_CONTINUOUS_FEE`.
+     * @param params.continuousFeeCap - Optional maximum market continuous fee accepted by this offer; defaults to `0n` (fail-closed: no market continuous fee accepted unless set explicitly).
      * @param params.start - Optional offer start timestamp; defaults to zero.
      * @param params.expiry - Offer expiry timestamp.
      * @param params.callback - Optional callback address; defaults to the zero address.