@morpho-org/midnight-sdk 0.1.0

package/lib/esm/offers/Offer.js

@@ -0,0 +1,339 @@
+import { zeroAddress } from "viem";
+import { MarketParams, } from "../market/index.js";
+import { OfferUtils } from "./OfferUtils.js";
+/**
+ * Maker-side Midnight offer.
+ *
+ * Build new maker offers with {@link Offer.create}, then pass them to
+ * `Group.create` for shared-consumption ladders or directly to `Tree.create`
+ * for standalone offers. API/take-side code can convert a plain `IOffer`
+ * into this class before ABI encoding. The class resolves the onchain `group`
+ * field lazily. Standalone offers derive their group id from the offer hash
+ * with the zero group id; `Group.create` copies offers and overrides the group
+ * on those copies when several offers share one consumption bucket. Offers
+ * hydrated from API or decoded data may also carry a known group id.
+ *
+ * @example
+ * ```ts
+ * import { Offer } from "@morpho-org/midnight-sdk";
+ *
+ * const offer = Offer.create({
+ *   market: {
+ *     loanToken: "0x0000000000000000000000000000000000000001",
+ *     collateralParams: [
+ *       {
+ *         token: "0x0000000000000000000000000000000000007000",
+ *         lltv: 770000000000000000n,
+ *         maxLif: 1061007957559681697n,
+ *         oracle: "0x0000000000000000000000000000000000008000",
+ *       },
+ *     ],
+ *     maturity: 1n,
+ *     rcfThreshold: 0n,
+ *     enterGate: "0x0000000000000000000000000000000000000000",
+ *     liquidatorGate: "0x0000000000000000000000000000000000000000",
+ *   },
+ *   buy: false,
+ *   maker: "0x0000000000000000000000000000000000000002",
+ *   start: 0n,
+ *   expiry: 2n,
+ *   tick: 100n,
+ *   callback: "0x0000000000000000000000000000000000000000",
+ *   callbackData: "0x",
+ *   receiverIfMakerIsSeller: "0x0000000000000000000000000000000000000002",
+ *   ratifier: "0x0000000000000000000000000000000000000003",
+ *   reduceOnly: false,
+ *   maxUnits: 100n,
+ *   maxAssets: 0n,
+ *   continuousFeeCap: 317097919n,
+ * });
+ * console.log(offer.buy);
+ * ```
+ */
+export class Offer {
+    /** Market this offer trades. */
+    market;
+    /** Whether the maker buys units. */
+    buy;
+    /** Offer maker. */
+    maker;
+    /** Start timestamp. */
+    start;
+    /** Expiry timestamp. */
+    expiry;
+    /** Midnight tick. */
+    tick;
+    cachedGroup;
+    cachedHash;
+    /** Optional maker callback. */
+    callback;
+    /** Callback payload. */
+    callbackData;
+    /** Receiver used when maker is seller. */
+    receiverIfMakerIsSeller;
+    /** Ratifier contract. */
+    ratifier;
+    /** Whether the offer can only reduce maker exposure. */
+    reduceOnly;
+    /** Maximum units; zero means max assets controls consumption. */
+    maxUnits;
+    /** Maximum buyer or seller assets, depending on side. */
+    maxAssets;
+    /** Maximum market continuous fee accepted by this offer. */
+    continuousFeeCap;
+    constructor(offer) {
+        this.market = MarketParams.from(offer.market);
+        this.buy = offer.buy;
+        this.maker = offer.maker;
+        this.start = BigInt(offer.start);
+        this.expiry = BigInt(offer.expiry);
+        this.tick = BigInt(offer.tick);
+        this.cachedGroup = offer.group;
+        this.callback = offer.callback;
+        this.callbackData = offer.callbackData;
+        this.receiverIfMakerIsSeller = offer.receiverIfMakerIsSeller;
+        this.ratifier = offer.ratifier;
+        this.reduceOnly = offer.reduceOnly;
+        this.maxUnits = BigInt(offer.maxUnits);
+        this.maxAssets = BigInt(offer.maxAssets);
+        this.continuousFeeCap = BigInt(offer.continuousFeeCap);
+    }
+    /**
+     * Returns an offer instance from class or plain input.
+     *
+     * Use at boundaries that accept either maker-created `Offer` instances or
+     * decoded `IOffer` objects from an API response. For brand-new maker input,
+     * prefer {@link Offer.create} so deterministic parameters are validated first.
+     *
+     * @param offer - Offer class or plain input.
+     * @returns Offer instance.
+     * @example
+     * ```ts
+     * import { Offer } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const offer = Offer.from({
+     *   market: {
+     *     loanToken: "0x0000000000000000000000000000000000006000",
+     *     collateralParams: [
+     *       {
+     *         token: "0x0000000000000000000000000000000000007000",
+     *         lltv: 770000000000000000n,
+     *         maxLif: 1061007957559681697n,
+     *         oracle: "0x0000000000000000000000000000000000008000",
+     *       },
+     *     ],
+     *     maturity: 54_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: zeroAddress,
+     *     liquidatorGate: zeroAddress,
+     *   },
+     *   buy: true,
+     *   maker: "0x0000000000000000000000000000000000009000",
+     *   start: 0n,
+     *   expiry: 3_600n,
+     *   tick: 5_000n,
+     *   callback: zeroAddress,
+     *   callbackData: "0x",
+     *   receiverIfMakerIsSeller: zeroAddress,
+     *   ratifier: "0x0000000000000000000000000000000000004000",
+     *   reduceOnly: false,
+     *   maxUnits: 100n,
+     *   maxAssets: 0n,
+     *   continuousFeeCap: 317097919n,
+     * });
+     * console.log(offer.buy);
+     * ```
+     */
+    static from(offer) {
+        return offer instanceof Offer ? offer : new Offer(offer);
+    }
+    /**
+     * Consumption group id encoded into this offer.
+     *
+     * When no group id was provided, the value is computed on first access by
+     * hashing this offer with the protocol zero group id. The computed value is
+     * cached because offer hashing is resource-intensive.
+     *
+     * @returns Consumption group id.
+     * @example
+     * ```ts
+     * import { Offer } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const loanToken = "0x0000000000000000000000000000000000006000";
+     * const collateralToken = "0x0000000000000000000000000000000000007000";
+     * const oracle = "0x0000000000000000000000000000000000008000";
+     * const maker = "0x0000000000000000000000000000000000009000";
+     * const ratifier = "0x0000000000000000000000000000000000004000";
+     *
+     * const offer = Offer.create({
+     *   market: {
+     *     loanToken,
+     *     collateralParams: [
+     *       {
+     *         token: collateralToken,
+     *         lltv: 770000000000000000n,
+     *         maxLif: 1061007957559681697n,
+     *         oracle,
+     *       },
+     *     ],
+     *     maturity: 2_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: zeroAddress,
+     *     liquidatorGate: zeroAddress,
+     *   },
+     *   buy: true,
+     *   maker,
+     *   tick: 5_000n,
+     *   expiry: 2_100n,
+     *   ratifier,
+     *   maxAssets: 100n,
+     * });
+     *
+     * const group = offer.group;
+     * // group satisfies Hash
+     * ```
+     */
+    get group() {
+        this.cachedGroup ??= OfferUtils.groupHash(this);
+        return this.cachedGroup;
+    }
+    /**
+     * Canonical protocol offer hash for this offer.
+     *
+     * The hash includes {@link Offer.group}. It is computed lazily and cached
+     * because hashing includes market hashing and ABI encoding.
+     *
+     * @returns Offer hash.
+     * @example
+     * ```ts
+     * import { Offer } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const loanToken = "0x0000000000000000000000000000000000006000";
+     * const collateralToken = "0x0000000000000000000000000000000000007000";
+     * const oracle = "0x0000000000000000000000000000000000008000";
+     * const maker = "0x0000000000000000000000000000000000009000";
+     * const ratifier = "0x0000000000000000000000000000000000004000";
+     *
+     * const offer = Offer.create({
+     *   market: {
+     *     loanToken,
+     *     collateralParams: [
+     *       {
+     *         token: collateralToken,
+     *         lltv: 770000000000000000n,
+     *         maxLif: 1061007957559681697n,
+     *         oracle,
+     *       },
+     *     ],
+     *     maturity: 2_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: zeroAddress,
+     *     liquidatorGate: zeroAddress,
+     *   },
+     *   buy: true,
+     *   maker,
+     *   tick: 5_000n,
+     *   expiry: 2_100n,
+     *   ratifier,
+     *   maxAssets: 100n,
+     * });
+     *
+     * const hash = offer.hash;
+     * // hash satisfies Hash
+     * ```
+     */
+    get hash() {
+        this.cachedHash ??= OfferUtils.hash(this);
+        return this.cachedHash;
+    }
+    /**
+     * Creates a validated maker-side Midnight offer.
+     *
+     * This is the first step of the make-side flow. After creation, pass related
+     * offers to `Group.create` when they share consumption, or pass standalone
+     * offers directly to `Tree.create`. Omit `group` for brand-new maker offers;
+     * provide it when hydrating an offer that already has a protocol group, such
+     * as an offer decoded from the API.
+     *
+     * @param params.market - Market params or hydrated market this offer trades.
+     * @param params.buy - Whether the maker buys loan assets.
+     * @param params.maker - Maker address.
+     * @param params.tick - Offer tick.
+     * @param params.group - Optional consumption group id for already-grouped offers.
+     * @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.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.
+     * @param params.callbackData - Optional callback payload; defaults to `0x`.
+     * @param params.receiverIfMakerIsSeller - Optional receiver used when maker is seller.
+     * @param params.ratifier - Ratifier contract address.
+     * @param params.reduceOnly - Optional flag restricting the offer to exposure-reducing execution.
+     * @returns Offer instance.
+     * @throws {InvalidOfferParameterError} when the offer cannot satisfy protocol parameter rules.
+     * @example
+     * ```ts
+     * import { Offer } from "@morpho-org/midnight-sdk";
+     * import { zeroAddress } from "viem";
+     *
+     * const loanToken = "0x0000000000000000000000000000000000006000";
+     * const collateralToken = "0x0000000000000000000000000000000000007000";
+     * const oracle = "0x0000000000000000000000000000000000008000";
+     * const maker = "0x0000000000000000000000000000000000009000";
+     * const ratifier = "0x0000000000000000000000000000000000004000";
+     * const apiGroup =
+     *   "0x1111111111111111111111111111111111111111111111111111111111111111";
+     *
+     * const offer = Offer.create({
+     *   market: {
+     *     loanToken,
+     *     collateralParams: [
+     *       {
+     *         token: collateralToken,
+     *         lltv: 770000000000000000n,
+     *         maxLif: 1061007957559681697n,
+     *         oracle,
+     *       },
+     *     ],
+     *     maturity: 2_000n,
+     *     rcfThreshold: 0n,
+     *     enterGate: zeroAddress,
+     *     liquidatorGate: zeroAddress,
+     *   },
+     *   buy: true,
+     *   maker,
+     *   tick: 5_000n,
+     *   group: apiGroup,
+     *   expiry: 2_100n,
+     *   ratifier,
+     *   maxAssets: 100n,
+     * });
+     * // offer satisfies Offer
+     * ```
+     */
+    static create(params) {
+        const validated = OfferUtils.validateOfferParams(params);
+        return new Offer({
+            market: params.market,
+            buy: params.buy,
+            maker: params.maker,
+            start: validated.start,
+            expiry: validated.expiry,
+            tick: validated.tick,
+            group: params.group,
+            callback: params.callback ?? zeroAddress,
+            callbackData: params.callbackData ?? "0x",
+            receiverIfMakerIsSeller: validated.receiverIfMakerIsSeller,
+            ratifier: params.ratifier,
+            reduceOnly: params.reduceOnly ?? false,
+            maxUnits: validated.maxUnits,
+            maxAssets: validated.maxAssets,
+            continuousFeeCap: validated.continuousFeeCap,
+        });
+    }
+}