feat(doc): Update type doc to avoid warnings (#1730)

.github/workflows/ci.yml

@@ -60,6 +60,10 @@ jobs:
       - name: Mgv cli Tests
         run: yarn mgv help
 
+      # == verify docs can be generated ==
+      - name: Generate Docs
+        run: yarn doc
+
         # == Send coverage report to Coveralls ==
         # Coverallsapp by default uses GITHUB_SHA but that does not necessarily correspond
         # to HEAD because a branch is checked out. We here find the actual SHA for HEAD.

examples/tutorials/deploy-kandel.js

@@ -85,8 +85,8 @@ const seed = {
 };
 
 // Deploy a Kandel instance with the specified seed data (the offers are later populated based on the above distribution)
-const { result: kandelPromise } = await kandelStrategies.seeder.sow(seed);
-const kandelInstance = await kandelPromise;
+const { result } = await kandelStrategies.seeder.sow(seed);
+const kandelInstance = await result;
 
 // Approve Kandel instance to use our funds
 const approvalTxs = await kandelInstance.approveIfHigher();

package.json

@@ -123,7 +123,8 @@
     "ts-mockito": "^2.0.0",
     "ts-node": "^10.9.1",
     "typechain": "^8.1.0",
-    "typedoc": "^0.25.2",
+    "typedoc": "^0.25.7",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.2.2"
   },
   "packageManager": "[email protected]"

src/configuration.ts

@@ -13,7 +13,8 @@ import {
   ReliableHttpProvider,
   ReliableWebsocketProvider,
 } from "@mangrovedao/reliable-event-subscriber";
-import { Bigish, Provider, typechain } from "./types";
+import { Provider, typechain } from "./types";
+import { Bigish } from "./util";
 import * as mgvDeployments from "@mangrovedao/mangrove-deployments";
 import * as contextAddresses from "@mangrovedao/context-addresses";
 import * as eth from "./eth";
@@ -783,7 +784,7 @@ function readContextAaveAddresses() {
  *
  * Example for adding configuration for a new token with symbol "SYM":
  *
- *    updateConfiguration({tokens: { SYM: { decimals: 18}}})
+ *    `updateConfiguration({tokens: { SYM: { decimals: 18}}})`
  */
 export function updateConfiguration(defaults: PartialConfiguration): void {
   config = deepmerge(config, defaults) as Configuration;

src/eth.ts

@@ -8,7 +8,7 @@ import { Provider, Signer } from "./types";
 import { logger, logdataLimiter } from "./util/logger";
 import { readJsonWallet } from "./util/readJsonWallet";
 
-interface JsonWalletOptions {
+export interface JsonWalletOptions {
   // local path to json wallet file
   path: string;
   // json wallet password

src/index.ts

@@ -11,50 +11,177 @@ import Mangrove from "./mangrove";
 import Market from "./market";
 import Semibook from "./semibook";
 import OfferLogic from "./offerLogic";
-import Token from "./token";
+import Token, {
+  AmountAndOverrides,
+  ApproveArgs,
+  TokenCalculations,
+} from "./token";
 import LiquidityProvider from "./liquidityProvider";
 import KandelStrategies from "./kandelStrategies";
 import * as mgvTestUtil from "./util/test/mgvIntegrationTestUtil";
 import { typechain } from "./types";
-import KandelDistribution from "./kandel/kandelDistribution";
+import { Bigish } from "./util";
+import KandelDistribution, {
+  OfferDistribution,
+  OfferList,
+} from "./kandel/kandelDistribution";
 import GeometricKandelDistributionGenerator from "./kandel/geometricKandel/geometricKandelDistributionGenerator";
 import KandelFarm from "./kandel/kandelFarm";
-import KandelSeeder from "./kandel/kandelSeeder";
-import CoreKandelInstance from "./kandel/coreKandelInstance";
+import KandelSeeder, { KandelSeed } from "./kandel/kandelSeeder";
+import CoreKandelInstance, {
+  KandelParameterOverrides,
+  KandelParameters,
+  MarketOrMarketFactory,
+} from "./kandel/coreKandelInstance";
 import OfferMaker from "./offerMaker";
 import { enableLogging } from "./util/logger";
-import configuration from "./configuration";
-import TickPriceHelper from "./util/tickPriceHelper";
+import configuration, {
+  AddressesConfig,
+  Configuration,
+  KandelAllConfigurationFields,
+  KandelMarketConfiguration,
+  KandelNetworkConfiguration,
+  KandelRawMarketConfiguration,
+  MangroveOrderNetworkConfiguration,
+  NamedAddresses,
+  PartialConfiguration,
+  PartialKandelAllConfigurationFields,
+  PartialKandelConfiguration,
+  PartialMangroveOrderConfiguration,
+  PartialMarketConfig,
+  PartialNetworkConfig,
+  RecursivePartial,
+  ReliableEventSubscriberConfig,
+  TokenConfig,
+  TokenDefaults,
+  address,
+  network,
+  tokenId,
+  tokenSymbol,
+} from "./configuration";
+import TickPriceHelper, { RoundingMode } from "./util/tickPriceHelper";
 import GeometricKandelDistribution from "./kandel/geometricKandel/geometricKandelDistribution";
 import GeneralKandelDistribution from "./kandel/generalKandelDistribution";
-import GeometricKandelInstance from "./kandel/geometricKandel/geometricKandelInstance";
+import GeometricKandelInstance, {
+  GeometricKandelParameterOverrides,
+} from "./kandel/geometricKandel/geometricKandelInstance";
+import KandelDistributionHelper, {
+  OffersWithGives,
+} from "./kandel/kandelDistributionHelper";
+import GeneralKandelDistributionGenerator from "./kandel/generalKandelDistributionGenerator";
+import GeometricKandelDistributionHelper, {
+  DistributionParams,
+  PriceDistributionParams,
+  TickDistributionParams,
+} from "./kandel/geometricKandel/geometricKandelDistributionHelper";
+import GeneralKandelDistributionHelper from "./kandel/generalKandelDistributionHelper";
+import GeometricKandelLib from "./kandel/geometricKandel/geometricKandelLib";
+import GeometricKandelStatus, {
+  OfferStatus,
+  OffersWithLiveness,
+  Statuses,
+} from "./kandel/geometricKandel/geometricKandelStatus";
+import TradeEventManagement, {
+  Optional,
+  OrderResultWithOptionalSummary,
+} from "./util/tradeEventManagement";
+import Trade, { CleanUnitParams } from "./util/trade";
+import KandelConfiguration from "./kandel/kandelConfiguration";
+import { JsonWalletOptions } from "./eth";
+import MangroveEventSubscriber from "./mangroveEventSubscriber";
+import { prettyPrintFilter } from "./util/prettyPrint";
+import { Density } from "./util/Density";
 
 // Turn off Ethers.js warnings
 // ethers.utils.Logger.setLogLevel(ethers.utils.Logger.levels.ERROR);
 
 export default Mangrove;
+
+// Mangrove
+export { Mangrove, Market, Semibook, OfferLogic, LiquidityProvider };
+
+// Utils
+export type { prettyPrintFilter };
+export type { Bigish };
+export type { Optional };
+export type { JsonWalletOptions };
+export type { MangroveEventSubscriber };
+export { Density, eth, typechain, ethers, OfferMaker, enableLogging };
+
+// Test utils
+export { mgvTestUtil };
+
+// Tick price helper
+export { TickPriceHelper };
+export type { RoundingMode };
+
+// Trade
+export { Trade, TradeEventManagement };
+export type { CleanUnitParams, OrderResultWithOptionalSummary };
+
+// Kandel
 export {
-  eth,
-  typechain,
-  ethers,
-  Mangrove,
-  Market,
-  Semibook,
-  Token,
-  OfferLogic,
-  LiquidityProvider,
-  mgvTestUtil,
   KandelStrategies,
   KandelDistribution,
   GeneralKandelDistribution,
   GeometricKandelDistributionGenerator,
   GeometricKandelDistribution,
   KandelFarm,
-  KandelSeeder,
   CoreKandelInstance,
   GeometricKandelInstance,
-  OfferMaker,
-  TickPriceHelper,
-  enableLogging,
-  configuration,
+  KandelDistributionHelper,
+  GeneralKandelDistributionGenerator,
+  KandelConfiguration,
+  GeometricKandelDistributionHelper,
+  GeneralKandelDistributionHelper,
+  GeometricKandelLib,
+  GeometricKandelStatus,
+  KandelSeeder,
+};
+export type {
+  OfferDistribution,
+  DistributionParams,
+  PriceDistributionParams,
+  TickDistributionParams,
+  OfferStatus,
+  KandelParameterOverrides,
+  GeometricKandelParameterOverrides,
+  KandelSeed,
+  MarketOrMarketFactory,
+  OffersWithGives,
+  OffersWithLiveness,
+  KandelParameters,
+  Statuses,
+  OfferList,
+};
+
+// Token
+export { Token, TokenCalculations };
+export type { ApproveArgs, AmountAndOverrides };
+
+// Configuration
+export { configuration };
+export type {
+  KandelMarketConfiguration,
+  PartialKandelAllConfigurationFields,
+  RecursivePartial,
+  network,
+  PartialNetworkConfig,
+  address,
+  AddressesConfig,
+  KandelRawMarketConfiguration,
+  PartialConfiguration,
+  NamedAddresses,
+  KandelAllConfigurationFields,
+  MangroveOrderNetworkConfiguration,
+  PartialMarketConfig,
+  tokenSymbol,
+  PartialMangroveOrderConfiguration,
+  tokenId,
+  TokenDefaults,
+  TokenConfig,
+  ReliableEventSubscriberConfig,
+  PartialKandelConfiguration,
+  KandelNetworkConfiguration,
+  Configuration,
 };

src/kandel/coreKandelInstance.ts

@@ -1,6 +1,6 @@
 import * as ethers from "ethers";
-import { Bigish, typechain } from "../types";
-
+import { typechain } from "../types";
+import { Bigish } from "../util";
 import * as KandelTypes from "../types/typechain/GeometricKandel";
 
 import Big from "big.js";
@@ -16,6 +16,7 @@ import KandelSeeder from "./kandelSeeder";
 import GeneralKandelDistribution from "./generalKandelDistribution";
 import GeneralKandelDistributionGenerator from "./generalKandelDistributionGenerator";
 import GeneralKandelDistributionHelper from "./generalKandelDistributionHelper";
+import Mangrove from "../mangrove";
 
 // The market used by the Kandel instance or a factory function to create the market.
 export type MarketOrMarketFactory =
@@ -350,8 +351,6 @@ class CoreKandelInstance {
   /** Creates a distribution based on an explicit set of offers based on the Kandel parameters.
    * @param params The parameters for the distribution.
    * @param params.explicitOffers The explicit offers to use.
-   * @param params.explicitOffers.bids The explicit bids to use.
-   * @param params.explicitOffers.asks The explicit asks to use.
    * @returns The new distribution.
    */
   public async createDistributionWithOffers(params: {
@@ -405,9 +404,7 @@ class CoreKandelInstance {
 
   /** Calculates a new distribution based on the provided offers and deltas.
    * @param params The parameters for the new distribution.
-   * @param params.explicitOffers The offers to use.
-   * @param params.explicitOffers.bids The explicit bids to use.
-   * @param params.explicitOffers.asks The explicit asks to use.
+   * @param params.explicitOffers The explicit offers to use.
    * @param params.baseDelta The delta to apply to the base token volume. If not provided, then the base token volume is unchanged.
    * @param params.quoteDelta The delta to apply to the quote token volume. If not provided, then the quote token volume is unchanged.
    * @param params.minimumBasePerOffer The minimum base token volume per offer. If not provided, then the minimum base token volume is used.
@@ -569,17 +566,11 @@ class CoreKandelInstance {
 
   /** Calculates the provision locked for a set of offers based on the given parameters
    * @param existingOffers the offers to calculate provision for.
-   * @param existingOffers.bids[].gasprice the gas price for the offer in Mwei. Should be 0 for deprovisioned offers.
-   * @param existingOffers.bids[].gasreq the gas requirement for the offer.
-   * @param existingOffers.bids[].gasbase the offer list's offer_gasbase.
-   * @param existingOffers.asks[].gasprice the gas price for the offer in Mwei. Should be 0 for deprovisioned offers.
-   * @param existingOffers.asks[].gasreq the gas requirement for the offer.
-   * @param existingOffers.asks[].gasbase the offer list's offer_gasbase.
    * @returns the locked provision, in ethers.
    */
   public getLockedProvisionFromOffers(existingOffers: {
-    bids: { gasprice: number; gasreq: number; gasbase: number }[];
-    asks: { gasprice: number; gasreq: number; gasbase: number }[];
+    bids: Mangrove.OfferProvisionParams[];
+    asks: Mangrove.OfferProvisionParams[];
   }) {
     return this.market.mgv.calculateOffersProvision(
       existingOffers.bids.concat(existingOffers.asks),
@@ -614,10 +605,7 @@ class CoreKandelInstance {
    * @param params.distribution The distribution to calculate the provision for. Optional.
    * @param params.bidCount The number of bids to calculate the provision for. Optional.
    * @param params.askCount The number of asks to calculate the provision for. Optional.
-   * @param existingOffers[] the offers with potential locked provision.
-   * @param existingOffers[].gasprice the gas price for the offer in Mwei. Should be 0 for deprovisioned offers.
-   * @param existingOffers[].gasreq the gas requirement for the offer.
-   * @param existingOffers[].gasbase the offer list's offer_gasbase.
+   * @param existingOffers the offers with potential locked provision.
    * @returns the additional required provision, in ethers.
    * @remarks If neither distribution nor askCount or bidCount is provided, then the current number of price points less the stepSize is used.
    */
@@ -630,8 +618,8 @@ class CoreKandelInstance {
       askCount?: number;
     },
     existingOffers: {
-      bids: { gasprice: number; gasreq: number; gasbase: number }[];
-      asks: { gasprice: number; gasreq: number; gasbase: number }[];
+      bids: Mangrove.OfferProvisionParams[];
+      asks: Mangrove.OfferProvisionParams[];
     },
   ) {
     const lockedProvision = this.getLockedProvisionFromOffers(existingOffers);
@@ -938,11 +926,7 @@ class CoreKandelInstance {
 
   /** Retracts offers
    * @param params The parameters.
-   * @param params.retractParams The parameters for retracting offers.
-   * @param params.retractParams.startIndex The start Kandel index of offers to retract. If not provided, then 0 is used.
-   * @param params.retractParams.endIndex The end index of offers to retract. This is exclusive of the offer the index 'endIndex'. If not provided, then the number of price points is used.
-   * @param params.retractParams.maxOffersInChunk The maximum number of offers to include in a single retract transaction. If not provided, then KandelConfiguration is used.
-   * @param params.retractParams.firstAskIndex The index of the first ask in the distribution. It is used to determine the order in which to retract offers if multiple chunks are needed; if not provided, the midpoint between start and end is used.
+   * @param params.retractParams The parameters for retracting offers. See {@link retractOffers}
    * @param params.skipLast Whether to skip the last chunk. This is used to allow the last chunk to be retracted while withdrawing funds.
    * @param overrides The ethers overrides to use when calling the retractOffers function.
    * @returns The transaction(s) used to retract the offers.

src/kandel/generalKandelDistribution.ts

@@ -7,12 +7,10 @@ import KandelDistribution, {
 /** @title A general distribution of bids and ask for Kandel fully specified as bids and asks with tick and volumes and no other parameters. */
 class GeneralKandelDistribution extends KandelDistribution {
   /** Constructor
-   * @param params.offers The distribution of bids and asks.
-   * @param params.baseQuoteTickOffset The number of ticks to jump between two price points - this gives the geometric progression. Should be >=1.
    * @param params.pricePoints The number of price points in the distribution.
    * @param params.stepSize The step size used when transporting funds from an offer to its dual. Should be >=1.
+   * @param params.offers The distribution of bids and asks.
    * @param params.market The key data about the market.
-   *
    */
   public constructor(params: {
     pricePoints: number;

src/kandel/generalKandelDistributionGenerator.ts

@@ -1,5 +1,5 @@
 import Big from "big.js";
-import { Bigish } from "../types";
+import { Bigish } from "../util";
 import KandelDistribution from "./kandelDistribution";
 import { OffersWithGives } from "./kandelDistributionHelper";
 import GeneralKandelDistributionHelper from "./generalKandelDistributionHelper";
@@ -50,8 +50,6 @@ class GeneralKandelDistributionGenerator {
   /** Creates a distribution based on an explicit set of offers. Either based on an original distribution or parameters for one.
    * @param params The parameters for the distribution.
    * @param params.explicitOffers The explicit offers to use.
-   * @param params.explicitOffers.bids The explicit bids to use.
-   * @param params.explicitOffers.asks The explicit asks to use.
    * @param params.distribution The original distribution or parameters for one. If pricePoints is not provided, then the number of offers is used.
    * @returns The new distribution.
    */

src/kandel/generalKandelDistributionHelper.ts

@@ -17,7 +17,6 @@ class GeneralKandelDistributionHelper {
    * @param explicitOffers The explicit offers to use.
    * @param explicitOffers.bids The explicit bids to use.
    * @param explicitOffers.asks The explicit asks to use.
-   * @param explicitAsks The explicit asks to use.
    * @param distribution The original distribution. If pricePoints is not provided, then the number of offers is used.
    * @returns The new distribution.
    */