@morpho-org/midnight-sdk 1.0.0 → 1.2.0

package/lib/esm/api/MidnightApi.js

@@ -1,5 +1,8 @@
+import { MathLib } from "@morpho-org/morpho-ts";
+import { InvalidMidnightApiResponseError } from "../errors.js";
+import { TickLib } from "../math/index.js";
 import { Payload } from "../signatures/Payload.js";
-import { buildBookPath, mapBookMarket, mapPriceLevel, mapTakeableOffer, parseValidationResponse, requestMidnightApi, } from "./helpers.js";
+import { buildBookPath, mapBookMarket, mapBoundTakeableOffers, mapPriceLevel, parseValidationResponse, requestMidnightApi, } from "./helpers.js";
 /**
  * Midnight API client and stateless helper surface for books and mempool data.
  *
@@ -217,7 +220,10 @@ export class MidnightApi {
             }),
         });
         return {
-            data: response.data.map(mapTakeableOffer),
+            data: mapBoundTakeableOffers(response.data, {
+                marketId: input.marketId,
+                side: input.side,
+            }),
         };
     }
     /**
@@ -267,7 +273,61 @@ export class MidnightApi {
                 assets: input.assets,
             },
         });
-        const takeableOffers = response.data.takeable_offers.map(mapTakeableOffer);
+        const takeableOffers = mapBoundTakeableOffers(response.data.takeable_offers, {
+            marketId: input.marketId,
+            side: input.side,
+        });
+        const averageWorstPrice = "averageWorstPrice" in input && input.averageWorstPrice != null
+            ? input.averageWorstPrice
+            : "slippage" in input && input.slippage != null
+                ? response.data.average_worst_price
+                : undefined;
+        if (averageWorstPrice != null) {
+            const guard = BigInt(averageWorstPrice);
+            let filledUnits = 0n;
+            let weightedPrice = 0n;
+            if ("units" in input && input.units != null) {
+                let remainingUnits = BigInt(input.units);
+                for (const take of takeableOffers) {
+                    if (remainingUnits === 0n)
+                        break;
+                    const price = TickLib.tickToPrice(take.offer.tick);
+                    const filled = take.units < remainingUnits ? take.units : remainingUnits;
+                    filledUnits += filled;
+                    weightedPrice += filled * price;
+                    remainingUnits -= filled;
+                }
+            }
+            else {
+                let remainingAssets = BigInt(input.assets);
+                for (const take of takeableOffers) {
+                    if (remainingAssets === 0n)
+                        break;
+                    const price = TickLib.tickToPrice(take.offer.tick);
+                    const takeAssets = input.side === "asks"
+                        ? MathLib.mulDivUp(take.units, price, MathLib.WAD)
+                        : MathLib.mulDivDown(take.units, price, MathLib.WAD);
+                    if (takeAssets === 0n)
+                        continue;
+                    const fillsEntireTake = takeAssets <= remainingAssets;
+                    const filled = fillsEntireTake
+                        ? take.units
+                        : MathLib.mulDiv(remainingAssets, MathLib.WAD, price, input.side === "asks" ? "Down" : "Up");
+                    if (filled === 0n)
+                        continue;
+                    filledUnits += filled;
+                    weightedPrice += filled * price;
+                    remainingAssets = fillsEntireTake ? remainingAssets - takeAssets : 0n;
+                }
+            }
+            if (filledUnits > 0n) {
+                const averagePrice = MathLib.mulDivDown(weightedPrice, 1n, filledUnits);
+                const violatesGuard = input.side === "asks" ? averagePrice > guard : averagePrice < guard;
+                if (violatesGuard) {
+                    throw new InvalidMidnightApiResponseError(`Midnight API quote takeable offers imply average price "${averagePrice}" outside average_worst_price guard "${guard}".`);
+                }
+            }
+        }
         return {
             data: {
                 averageBestPrice: response.data.average_best_price,
@@ -320,7 +380,11 @@ export class MidnightApi {
         });
         return {
             cursor: response.cursor,
-            data: response.data.map(mapTakeableOffer),
+            data: mapBoundTakeableOffers(response.data, {
+                maker: input.maker,
+                marketIds: input.marketIds,
+                groups: input.groups,
+            }),
         };
     }
     /**

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

@@ -1,4 +1,4 @@
-import type { Hash } from "viem";
+import { type Address, type Hash } from "viem";
 import type { ApiBookMarketResponse, ApiCollateralResponse, ApiPriceLevelResponse, ApiRequestParams, ApiTakeableOfferResponse, MempoolPayloadValidationResult, MidnightApiBookMarket, MidnightApiBookSide, MidnightApiCollateral, MidnightApiPriceLevel, MidnightApiTake } from "./types.js";
 /** @internal Sends one Midnight API request and maps non-2xx responses to SDK errors. */
 export declare function requestMidnightApi<Response = unknown>(params: ApiRequestParams): Promise<Response>;
@@ -16,5 +16,15 @@ export declare function mapCollateral(collateral: ApiCollateralResponse): Midnig
 export declare function mapPriceLevel(level: ApiPriceLevelResponse): 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. */
+export interface TakeableOfferContext {
+    readonly marketId?: Hash;
+    readonly side?: MidnightApiBookSide;
+    readonly maker?: Address;
+    readonly marketIds?: readonly Hash[];
+    readonly groups?: readonly Hash[];
+}
+/** @internal Maps, validates, and best-price-sorts API takeable offers. */
+export declare function mapBoundTakeableOffers(takeableOffers: readonly ApiTakeableOfferResponse[], context: TakeableOfferContext): MidnightApiTake[];
 /** @internal Parses the mempool validation response envelope. */
 export declare function parseValidationResponse(response: unknown): MempoolPayloadValidationResult;

package/lib/esm/api/helpers.js

@@ -1,9 +1,11 @@
-import { BLUE_API_BASE_URL } from "@morpho-org/morpho-ts";
+import { BLUE_API_BASE_URL, isHexEqual } from "@morpho-org/morpho-ts";
+import { isAddressEqual } from "viem";
 import { InvalidMidnightApiResponseError, MidnightApiError, } from "../errors.js";
+import { MarketUtils } from "../market/index.js";
 const DEFAULT_MIDNIGHT_API_URL = new URL("/v0/midnight", BLUE_API_BASE_URL);
 // Keep this literal in source so the browser ESM build does not import package.json
 // through Node-only createRequire/module shims.
-const MIDNIGHT_SDK_VERSION = "0.1.0";
+const MIDNIGHT_SDK_VERSION = "1.0.1";
 /** @internal Sends one Midnight API request and maps non-2xx responses to SDK errors. */
 export async function requestMidnightApi(params) {
     const baseUrl = new URL(params.baseUrl ?? DEFAULT_MIDNIGHT_API_URL);
@@ -153,6 +155,50 @@ export function mapTakeableOffer(takeableOffer) {
         ratifierData: takeableOffer.ratifier_data,
     };
 }
+/** @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)) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer market_id "${take.marketId}" does not match embedded offer market "${embeddedMarketId}".`);
+        }
+        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}".`);
+        }
+        if (context.marketIds != null &&
+            context.marketIds.length > 0 &&
+            !context.marketIds.some((marketId) => isHexEqual(marketId, take.marketId))) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer market_id "${take.marketId}" is outside the requested market_ids filter.`);
+        }
+        if (context.side != null) {
+            const expectedBuy = context.side === "bids";
+            if (take.offer.buy !== expectedBuy) {
+                throw new InvalidMidnightApiResponseError(`Midnight API ${context.side} takeable offer returned offer.buy "${take.offer.buy}".`);
+            }
+        }
+        if (context.maker != null &&
+            !isAddressEqual(take.offer.maker, context.maker)) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer maker "${take.offer.maker}" does not match requested maker "${context.maker}".`);
+        }
+        if (context.groups != null &&
+            context.groups.length > 0 &&
+            !context.groups.some((group) => isHexEqual(group, take.offer.group))) {
+            throw new InvalidMidnightApiResponseError(`Midnight API takeable offer group "${take.offer.group}" is outside the requested groups filter.`);
+        }
+        return take;
+    });
+    if (context.side == null)
+        return mapped;
+    return [...mapped].sort((a, b) => {
+        if (a.offer.tick === b.offer.tick)
+            return 0;
+        if (context.side === "asks")
+            return a.offer.tick < b.offer.tick ? -1 : 1;
+        return a.offer.tick > b.offer.tick ? -1 : 1;
+    });
+}
 /** @internal Parses the mempool validation response envelope. */
 export function parseValidationResponse(response) {
     const parsedResponse = requireRecord(response, "validation response");

package/lib/esm/errors.d.ts

@@ -277,6 +277,21 @@ export declare class InvalidTypedDataSignatureError extends Error {
     readonly signer: Address;
     constructor(signer: Address, cause?: unknown);
 }
+/**
+ * Thrown when decoded Ecrecover ratifier data contains a non-canonical signature `v` value.
+ *
+ * @example
+ * ```ts
+ * import { InvalidEcrecoverSignatureVError } from "@morpho-org/midnight-sdk";
+ *
+ * throw new InvalidEcrecoverSignatureVError(29);
+ * ```
+ */
+export declare class InvalidEcrecoverSignatureVError extends Error {
+    /** Invalid ECDSA recovery id. */
+    readonly v: number;
+    constructor(v: number);
+}
 /**
  * Thrown when the Midnight API returns a non-2xx response.
  *

package/lib/esm/errors.js

@@ -325,6 +325,25 @@ export class InvalidTypedDataSignatureError extends Error {
         this.signer = signer;
     }
 }
+/**
+ * Thrown when decoded Ecrecover ratifier data contains a non-canonical signature `v` value.
+ *
+ * @example
+ * ```ts
+ * import { InvalidEcrecoverSignatureVError } from "@morpho-org/midnight-sdk";
+ *
+ * throw new InvalidEcrecoverSignatureVError(29);
+ * ```
+ */
+export class InvalidEcrecoverSignatureVError extends Error {
+    /** Invalid ECDSA recovery id. */
+    v;
+    constructor(v) {
+        super(`Ecrecover signature v "${v}" is invalid. Use canonical Ethereum v 27 or 28.`);
+        this.name = "InvalidEcrecoverSignatureVError";
+        this.v = v;
+    }
+}
 /**
  * Thrown when the Midnight API returns a non-2xx response.
  *

package/lib/esm/fetch/Market.js

@@ -1,7 +1,8 @@
 import { getChainAddress } from "@morpho-org/morpho-ts";
 import { readContract } from "viem/actions";
 import { midnightAbi } from "../abis.js";
-import { Market, MarketParams } from "../market/index.js";
+import { InvalidMarketParameterError } from "../errors.js";
+import { Market, MarketParams, MarketUtils } from "../market/index.js";
 import { callParameters, resolveChainId } from "./utils.js";
 /**
  * Fetches immutable market params by id.
@@ -41,7 +42,11 @@ export async function fetchMarketParams(client, params) {
         functionName: "toMarket",
         args: [params.marketId],
     });
-    return new MarketParams(market);
+    return normalizeFetchedMarketParams(market, {
+        marketId: params.marketId,
+        chainId,
+        midnight,
+    });
 }
 /**
  * Fetches a hydrated market by id.
@@ -92,7 +97,11 @@ export async function fetchMarket(client, params) {
     ]);
     const [totalUnits, lossFactor, withdrawable, continuousFeeCredit, settlementFeeCbps0, settlementFeeCbps1, settlementFeeCbps2, settlementFeeCbps3, settlementFeeCbps4, settlementFeeCbps5, settlementFeeCbps6, continuousFee, tickSpacing,] = state;
     return new Market({
-        params: new MarketParams(market),
+        params: normalizeFetchedMarketParams(market, {
+            marketId: params.marketId,
+            chainId,
+            midnight,
+        }),
         totalUnits,
         lossFactor,
         withdrawable,
@@ -110,3 +119,29 @@ export async function fetchMarket(client, params) {
         tickSpacing,
     });
 }
+function normalizeFetchedMarketParams(market, expected) {
+    const marketParams = new MarketParams(market);
+    if (marketParams.chainId !== BigInt(expected.chainId)) {
+        throw new InvalidMarketParameterError({
+            parameter: "chainId",
+            value: marketParams.chainId,
+            instruction: `Fetched market must use client chain id "${expected.chainId}".`,
+        });
+    }
+    if (marketParams.midnight.toLowerCase() !== expected.midnight.toLowerCase()) {
+        throw new InvalidMarketParameterError({
+            parameter: "midnight",
+            value: marketParams.midnight,
+            instruction: `Fetched market must use Midnight contract "${expected.midnight}".`,
+        });
+    }
+    const actualMarketId = MarketUtils.toId(marketParams);
+    if (actualMarketId.toLowerCase() !== expected.marketId.toLowerCase()) {
+        throw new InvalidMarketParameterError({
+            parameter: "marketId",
+            value: actualMarketId,
+            instruction: `Fetched market must match requested market id "${expected.marketId}".`,
+        });
+    }
+    return marketParams;
+}

package/lib/esm/fetch/Position.d.ts

@@ -1,5 +1,5 @@
 import type { Address, Client, Hash } from "viem";
-import { AccrualPosition, Position } from "../market/index.js";
+import { AccrualPosition, Position } from "../position/index.js";
 import type { MidnightFetchParams } from "./types.js";
 /**
  * Fetches a Midnight position by id and user.

package/lib/esm/fetch/Position.js

@@ -2,7 +2,7 @@ import { getChainAddress } from "@morpho-org/morpho-ts";
 import { readContract } from "viem/actions";
 import { midnightAbi } from "../abis.js";
 import { MAX_COLLATERALS } from "../constants.js";
-import { AccrualPosition, Position } from "../market/index.js";
+import { AccrualPosition, Position } from "../position/index.js";
 import { abi as getPositionAbi, code as getPositionCode, } from "../queries/GetPosition.js";
 import { fetchMarket } from "./Market.js";
 import { callParameters, resolveChainId, shouldUseDeployless, } from "./utils.js";
@@ -60,6 +60,8 @@ export async function fetchPosition(client, params) {
             });
             const collateral = position.collateral;
             return new Position({
+                user: params.user,
+                marketId: params.marketId,
                 credit: position.credit,
                 pendingFee: position.pendingFee,
                 lastLossFactor: position.lastLossFactor,
@@ -92,6 +94,8 @@ export async function fetchPosition(client, params) {
         });
     }));
     return new Position({
+        user: params.user,
+        marketId: params.marketId,
         credit: position[0],
         pendingFee: position[1],
         lastLossFactor: position[2],

package/lib/esm/fetch/utils.d.ts

@@ -4,5 +4,5 @@ import type { DeploylessFetchParameters, MidnightCallParameters } from "./types.
 export declare const callParameters: (params: MidnightCallParameters) => MidnightCallParameters;
 /** @internal Returns the configured deployless mode, defaulting to enabled. */
 export declare const shouldUseDeployless: (params: DeploylessFetchParameters) => boolean | "force";
-/** @internal Returns the configured viem client chain id or fetches it from RPC. */
+/** @internal Returns the RPC chain id and rejects configured-chain drift. */
 export declare const resolveChainId: (client: Client) => Promise<number>;

package/lib/esm/fetch/utils.js

@@ -1,4 +1,5 @@
 import { getChainId } from "viem/actions";
+import { ChainIdMismatchError } from "../errors.js";
 /** @internal Extracts viem call parameters from Midnight fetch inputs. */
 export const callParameters = (params) => ({
     account: params.account,
@@ -8,5 +9,11 @@ export const callParameters = (params) => ({
 });
 /** @internal Returns the configured deployless mode, defaulting to enabled. */
 export const shouldUseDeployless = (params) => params.deployless ?? true;
-/** @internal Returns the configured viem client chain id or fetches it from RPC. */
-export const resolveChainId = async (client) => client.chain?.id ?? (await getChainId(client));
+/** @internal Returns the RPC chain id and rejects configured-chain drift. */
+export const resolveChainId = async (client) => {
+    const rpcChainId = await getChainId(client);
+    if (client.chain?.id != null && client.chain.id !== rpcChainId) {
+        throw new ChainIdMismatchError(client.chain.id, BigInt(rpcChainId));
+    }
+    return rpcChainId;
+};

package/lib/esm/index.d.ts

@@ -5,6 +5,7 @@ export * from "./fetch/index.js";
 export * from "./market/index.js";
 export * from "./math/index.js";
 export * from "./offers/index.js";
+export * from "./position/index.js";
 export * from "./signatures/index.js";
 /**
  * Namespace for Midnight mempool payload utilities.

package/lib/esm/index.js

@@ -5,6 +5,7 @@ export * from "./fetch/index.js";
 export * from "./market/index.js";
 export * from "./math/index.js";
 export * from "./offers/index.js";
+export * from "./position/index.js";
 export * from "./signatures/index.js";
 /**
  * Namespace for Midnight mempool payload utilities.

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

@@ -1,4 +1,2 @@
 export * from "./Market.js";
 export * from "./MarketUtils.js";
-export * from "./Position.js";
-export * from "./PositionUtils.js";

package/lib/esm/market/index.js

@@ -1,4 +1,2 @@
 export * from "./Market.js";
 export * from "./MarketUtils.js";
-export * from "./Position.js";
-export * from "./PositionUtils.js";

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

@@ -721,7 +721,7 @@ export interface BuildOfferParams {
     readonly maxUnits?: BigIntish;
     /** Maximum buyer or seller assets; defaults to zero. Exactly one of `maxUnits` and `maxAssets` must be non-zero. */
     readonly maxAssets?: BigIntish;
-    /** Maximum market continuous fee accepted by this offer; defaults to the protocol maximum. */
+    /** Maximum market continuous fee accepted by this offer; defaults to zero. */
     readonly continuousFeeCap?: BigIntish;
     /** Offer start timestamp; defaults to zero. */
     readonly start?: BigIntish;

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

@@ -0,0 +1,179 @@
+import { type BigIntish } from "@morpho-org/morpho-ts";
+/** One time-bounded offer leg to convert into a Midnight `Offer.create` input. */
+export interface FixedRateOfferChainLeg {
+    /** Spacing-aligned Midnight tick for this offer. */
+    readonly tick: bigint;
+    /** First timestamp at which the offer leg is active. */
+    readonly startTimestamp: bigint;
+    /** Last timestamp at which the offer leg is active. */
+    readonly expiryTimestamp: bigint;
+}
+/** Parameters shared by lend-only and borrow-only fixed-rate offer-chain builders. */
+export interface BuildFixedRateOfferChainParams {
+    /** Target yearly fixed rate as a decimal number, for example `0.05` for 5%. */
+    readonly targetRate: number;
+    /** Tick spacing enforced by the market. */
+    readonly tickSpacing: BigIntish;
+    /** Market maturity timestamp in seconds. */
+    readonly maturityTimestamp: BigIntish;
+    /** First timestamp the chain should cover. */
+    readonly chainStartTimestamp: BigIntish;
+    /** Latest timestamp the chain may cover. */
+    readonly chainEndTimestamp: BigIntish;
+}
+/**
+ * Utilities for building time-bounded Midnight offer chains.
+ *
+ * A Midnight offer has one fixed price, so its displayed yearly rate changes
+ * as maturity approaches. The markets app uses these helpers when a maker wants
+ * to post, for example, a 5% order for several months: the app builds several
+ * adjacent offers sharing the same reserve, each with a different tick and time
+ * window, so the order reviews and renders as a stable 5% order across the
+ * selected window instead of drifting upward as time passes.
+ *
+ * @example
+ * ```ts
+ * import { OfferChainUtils } from "@morpho-org/midnight-sdk";
+ *
+ * const legs = OfferChainUtils.buildLendFixedRateOfferChain({
+ *   targetRate: 0.05,
+ *   tickSpacing: 4n,
+ *   maturityTimestamp: 1_798_761_600n,
+ *   chainStartTimestamp: 1_767_225_600n,
+ *   chainEndTimestamp: 1_791_153_600n,
+ * });
+ * console.log(legs[0]?.tick);
+ * ```
+ */
+export declare namespace OfferChainUtils {
+    /**
+     * Maximum fraction of the initial time-to-maturity covered by a fixed-rate offer chain.
+     *
+     * Use this cap before displaying an expiry picker for a fixed-rate maker
+     * order. The last part of the maturity window is intentionally excluded
+     * because tiny time changes cause large displayed-rate drift.
+     *
+     * @example
+     * ```ts
+     * import { OfferChainUtils } from "@morpho-org/midnight-sdk";
+     *
+     * console.log(OfferChainUtils.MAX_EXPIRY_TTM_FRACTION);
+     * ```
+     */
+    const MAX_EXPIRY_TTM_FRACTION = 0.75;
+    /**
+     * Builds borrow-side sell-offer legs that approximate one fixed maker rate over time.
+     *
+     * Use before a make-borrow or supply-collateral-and-make-borrow flow when a
+     * borrower wants one displayed fixed borrow rate across a longer window. Map
+     * the returned legs to `Offer.create({ buy: false, ... })`, then group and
+     * submit them through the maker flow.
+     *
+     * Borrow chains read their target rate at each leg's expiry edge. If a leg
+     * would need to extend past `chainEndTimestamp`, it is dropped rather than
+     * clamped so the expiry edge remains the recoverable target-rate edge.
+     *
+     * @param params - Fixed-rate offer-chain parameters without a side field.
+     * @param params.targetRate - Target yearly fixed rate expressed as a decimal number.
+     * @param params.tickSpacing - Tick spacing enforced by the market.
+     * @param params.maturityTimestamp - Market maturity timestamp in seconds.
+     * @param params.chainStartTimestamp - First timestamp the chain should cover.
+     * @param params.chainEndTimestamp - Latest timestamp the chain may cover.
+     * @returns Borrow-side offer legs that can be mapped to `Offer.create({ buy: false, ... })`.
+     * @throws {InvalidOfferParameterError} when an input is invalid or the end timestamp exceeds the supported horizon.
+     * @example
+     * ```ts
+     * import { Offer, OfferChainUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const legs = OfferChainUtils.buildBorrowFixedRateOfferChain({
+     *   targetRate: 0.08,
+     *   tickSpacing: market.tickSpacing,
+     *   maturityTimestamp: market.params.maturity,
+     *   chainStartTimestamp: now,
+     *   chainEndTimestamp: expiry,
+     * });
+     * const offers = legs.map((leg) =>
+     *   Offer.create({
+     *     ...baseOffer,
+     *     buy: false,
+     *     tick: leg.tick,
+     *     start: leg.startTimestamp,
+     *     expiry: leg.expiryTimestamp,
+     *   }),
+     * );
+     * ```
+     */
+    function buildBorrowFixedRateOfferChain(params: BuildFixedRateOfferChainParams): readonly FixedRateOfferChainLeg[];
+    /**
+     * Builds lend-side buy-offer legs that approximate one fixed maker rate over time.
+     *
+     * Use before a make-lend flow when a lender wants one displayed fixed lend
+     * rate across a longer window. Map the returned legs to
+     * `Offer.create({ buy: true, ... })`, then group and submit them through the
+     * maker flow.
+     *
+     * Lend chains read their target rate at each leg's start edge. The first leg
+     * may start before `chainStartTimestamp`; clamping that edge would move the
+     * recoverable display rate below the maker's target.
+     *
+     * @param params - Fixed-rate offer-chain parameters without a side field.
+     * @param params.targetRate - Target yearly fixed rate expressed as a decimal number.
+     * @param params.tickSpacing - Tick spacing enforced by the market.
+     * @param params.maturityTimestamp - Market maturity timestamp in seconds.
+     * @param params.chainStartTimestamp - First timestamp the chain should cover.
+     * @param params.chainEndTimestamp - Latest timestamp the chain may cover.
+     * @returns Lend-side offer legs that can be mapped to `Offer.create({ buy: true, ... })`.
+     * @throws {InvalidOfferParameterError} when an input is invalid or the end timestamp exceeds the supported horizon.
+     * @example
+     * ```ts
+     * import { Offer, OfferChainUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const legs = OfferChainUtils.buildLendFixedRateOfferChain({
+     *   targetRate: 0.05,
+     *   tickSpacing: market.tickSpacing,
+     *   maturityTimestamp: market.params.maturity,
+     *   chainStartTimestamp: now,
+     *   chainEndTimestamp: expiry,
+     * });
+     * const offers = legs.map((leg) =>
+     *   Offer.create({
+     *     ...baseOffer,
+     *     buy: true,
+     *     tick: leg.tick,
+     *     start: leg.startTimestamp,
+     *     expiry: leg.expiryTimestamp,
+     *   }),
+     * );
+     * ```
+     */
+    function buildLendFixedRateOfferChain(params: BuildFixedRateOfferChainParams): readonly FixedRateOfferChainLeg[];
+    /**
+     * Returns the latest supported end timestamp for a fixed-rate offer chain.
+     *
+     * Chains intentionally stop before the final part of the maturity window
+     * because rate sensitivity accelerates near maturity and would require too
+     * many short-lived offers for a stable maker quote.
+     * Call this when constraining a make-offer expiry selector, then pass the
+     * selected timestamp to the lend-only or borrow-only chain builder.
+     *
+     * @param params - Maturity and chain-start timestamps.
+     * @param params.maturityTimestamp - Market maturity timestamp in seconds.
+     * @param params.chainStartTimestamp - First timestamp the chain should cover.
+     * @returns Latest accepted chain end timestamp.
+     * @throws {InvalidOfferParameterError} when a timestamp is invalid.
+     * @example
+     * ```ts
+     * import { OfferChainUtils } from "@morpho-org/midnight-sdk";
+     *
+     * const maxExpiry = OfferChainUtils.getMaxFixedRateOfferChainEndTimestamp({
+     *   maturityTimestamp: market.params.maturity,
+     *   chainStartTimestamp: now,
+     * });
+     * console.log(maxExpiry);
+     * ```
+     */
+    function getMaxFixedRateOfferChainEndTimestamp(params: {
+        readonly maturityTimestamp: BigIntish;
+        readonly chainStartTimestamp: BigIntish;
+    }): bigint;
+}