@gearbox-protocol/sdk 13.7.0-kyc.3 → 14.0.0-next.10

package/dist/esm/sdk/OnchainSDK.js

@@ -0,0 +1,472 @@
+import {
+  createPublicClient,
+  fallback,
+  http,
+  parseEventLogs
+} from "viem";
+import { ChainContractsRegister } from "./base/index.js";
+import { getChain } from "./chain/index.js";
+import {
+  ADDRESS_PROVIDER_V310,
+  AP_GEAR_TOKEN,
+  AP_ROUTER,
+  isV310,
+  NO_VERSION,
+  VERSION_RANGE_310
+} from "./constants/index.js";
+import {
+  createAddressProvider,
+  hydrateAddressProvider,
+  SdkAlreadyAttachedError,
+  SdkChainMismatchError,
+  SdkNotAttachedError,
+  SdkStateVersionMismatchError
+} from "./core/index.js";
+import { MarketRegister } from "./market/MarketRegister.js";
+import { PriceFeedRegister } from "./market/pricefeeds/index.js";
+import { PluginStateVersionError } from "./plugins/index.js";
+import { createRouter } from "./router/index.js";
+import { formatTimestamp, TypedObjectUtils, toAddress } from "./utils/index.js";
+import { getLogsSafe } from "./utils/viem/index.js";
+const STATE_VERSION = 1;
+function createViemClient(opts, chain) {
+  if ("client" in opts) {
+    return opts.client;
+  }
+  let transport;
+  if ("transport" in opts) {
+    transport = opts.transport;
+  } else {
+    const rpcs = opts.rpcURLs.map(
+      (url) => http(url, {
+        ...opts.httpTransportOptions,
+        timeout: opts.timeout,
+        retryCount: opts.retryCount
+      })
+    );
+    transport = rpcs.length > 1 ? fallback(rpcs) : rpcs[0];
+  }
+  return createPublicClient({ transport, chain });
+}
+class OnchainSDK extends ChainContractsRegister {
+  /** Registered plugin instances, keyed by plugin name. */
+  plugins;
+  #currentBlock;
+  #timestamp;
+  #syncing = false;
+  #attached = false;
+  #addressProvider;
+  #marketRegister;
+  #priceFeeds;
+  /**
+   * Gas limit applied to read-only `eth_call` requests.
+   **/
+  gasLimit;
+  /**
+   * When `true`, the SDK throws on unrecognised contract types.
+   **/
+  strictContractTypes;
+  /**
+   * @param network - Gearbox network type (e.g. `"Mainnet"`, `"Monad"`).
+   * @param clientOptions - Connection options (RPC URLs, transport, or client).
+   * @param options - SDK configuration options.
+   */
+  constructor(network, clientOptions, options) {
+    const gearboxChain = getChain(network);
+    if ("client" in clientOptions) {
+      const clientChainId = clientOptions.client.chain?.id;
+      if (clientChainId !== void 0 && clientChainId !== gearboxChain.id) {
+        throw new SdkChainMismatchError(gearboxChain.id, clientChainId);
+      }
+    }
+    const client = createViemClient(clientOptions, gearboxChain);
+    super(client, options?.logger);
+    this.strictContractTypes = options?.strictContractTypes ?? false;
+    this.plugins = options?.plugins ?? {};
+    for (const plugin of Object.values(this.plugins)) {
+      plugin.sdk = this;
+    }
+    if (options?.gasLimit !== null) {
+      this.gasLimit = options?.gasLimit ?? getChain(this.networkType).gasLimit;
+    }
+  }
+  /**
+   * Initialises the SDK by reading live on-chain state.
+   *
+   * @param options - Attach configuration.
+   * @throws {@link SdkAlreadyAttachedError} if already attached.
+   */
+  async attach(options) {
+    if (this.#attached) {
+      throw new SdkAlreadyAttachedError();
+    }
+    const {
+      addressProvider = ADDRESS_PROVIDER_V310,
+      blockNumber,
+      ignoreUpdateablePrices,
+      ignoreMarkets,
+      marketConfigurators: mcs,
+      redstone,
+      pyth
+    } = options ?? {};
+    const marketConfigurators = mcs ?? TypedObjectUtils.keys(
+      this.client.chain.defaultMarketConfigurators
+    );
+    this.logger?.info(
+      {
+        networkType: this.networkType,
+        chainId: this.chainId,
+        addressProvider,
+        marketConfigurators,
+        blockNumber,
+        ignoreMarkets
+      },
+      "attaching sdk"
+    );
+    const time = Date.now();
+    const block = await this.client.getBlock(
+      blockNumber ? { blockNumber: BigInt(blockNumber) } : { blockTag: "latest" }
+    );
+    this.#currentBlock = block.number;
+    this.#timestamp = block.timestamp;
+    if (!!blockNumber && !redstone?.historicTimestamp && time - Number(block.timestamp) * 1e3 > 60 * 1e3) {
+      this.logger?.warn(
+        "attaching to fixed block number, but redstone historicTimestamp is not set. price updates might fail"
+      );
+    }
+    if (!!blockNumber && !pyth?.historicTimestamp && time - Number(block.timestamp) * 1e3 > 60 * 1e3) {
+      this.logger?.warn(
+        "attaching to fixed block number, but pyth historicTimestamp is not set. price updates might fail"
+      );
+    }
+    this.#priceFeeds = new PriceFeedRegister(this, { redstone, pyth });
+    this.logger?.debug(
+      `attach block number ${this.currentBlock} timestamp ${this.timestamp}`
+    );
+    this.#addressProvider = await createAddressProvider(this, addressProvider);
+    this.logger?.debug(
+      `address provider version: ${this.#addressProvider.version}`
+    );
+    await this.#addressProvider.syncState(this.currentBlock);
+    this.#marketRegister = new MarketRegister(this, ignoreMarkets);
+    await this.#marketRegister.loadMarkets(
+      marketConfigurators,
+      ignoreUpdateablePrices
+    );
+    const pluginsList = TypedObjectUtils.entries(this.plugins);
+    const pluginResponse = await Promise.allSettled(
+      pluginsList.map(([name, plugin]) => {
+        if (plugin.attach) {
+          this.logger?.debug(`attaching plugin ${name}`);
+          return plugin.attach();
+        }
+        return void 0;
+      })
+    );
+    pluginResponse.forEach((r, i) => {
+      const [name, plugin] = pluginsList[i];
+      if (plugin.attach && r.status === "fulfilled") {
+        this.logger?.debug(`attached plugin ${name}`);
+      } else if (plugin.attach && r.status === "rejected") {
+        this.logger?.error(r.reason, `failed to attach plugin ${name}`);
+      }
+    });
+    this.logger?.info(`attach time: ${Date.now() - time} ms`);
+    this.#attached = true;
+  }
+  /**
+   * Restores SDK state from a previously serialised {@link GearboxState}
+   * snapshot, without making any on-chain calls.
+   *
+   * @param state - Serialised state obtained from {@link OnchainSDK.state}.
+   * @param options - Hydrate configuration.
+   * @throws {@link SdkAlreadyAttachedError} if already attached.
+   * @throws {@link SdkStateVersionMismatchError} if snapshot version doesn't match.
+   * @throws {@link SdkChainMismatchError} if snapshot network doesn't match.
+   */
+  hydrate(state, options) {
+    if (this.#attached) {
+      throw new SdkAlreadyAttachedError();
+    }
+    if (state.version !== STATE_VERSION) {
+      throw new SdkStateVersionMismatchError(STATE_VERSION, state.version);
+    }
+    if (state.network !== this.networkType) {
+      throw new SdkChainMismatchError(this.networkType, state.network);
+    }
+    const { ignoreMarkets, redstone, pyth } = options ?? {};
+    this.logger?.info({ networkType: this.networkType }, "hydrating sdk state");
+    this.#currentBlock = state.currentBlock;
+    this.#timestamp = state.timestamp;
+    this.#priceFeeds = new PriceFeedRegister(this, { redstone, pyth });
+    this.#addressProvider = hydrateAddressProvider(this, state.addressProvider);
+    this.logger?.debug(
+      `address provider version: ${this.#addressProvider.version}`
+    );
+    this.#marketRegister = new MarketRegister(this, ignoreMarkets);
+    this.#marketRegister.hydrate(state.markets);
+    for (const [name, plugin] of TypedObjectUtils.entries(this.plugins)) {
+      const pluginState = state.plugins[name];
+      if (plugin.hydrate && pluginState) {
+        if (!pluginState.loaded) {
+          this.logger?.debug(
+            `skipping hydrating plugin ${name} state: not loaded`
+          );
+          continue;
+        }
+        if (pluginState.version !== plugin.version) {
+          throw new PluginStateVersionError(plugin, pluginState);
+        }
+        plugin.hydrate(pluginState);
+      }
+    }
+    this.logger?.info("hydrated sdk state");
+    this.#attached = true;
+  }
+  /**
+   * Gearbox network type the SDK is connected to (e.g. `"Mainnet"`, `"Arbitrum"`).
+   **/
+  get networkType() {
+    return this.client.chain.network;
+  }
+  /**
+   * Whether the SDK has been initialised via {@link attach} or {@link hydrate}.
+   **/
+  get attached() {
+    return this.#attached;
+  }
+  /**
+   * Returns a human-readable snapshot of the entire SDK state.
+   * @param raw - When `true`, include raw numeric values alongside formatted ones.
+   */
+  stateHuman(raw = true) {
+    return {
+      network: this.networkType,
+      block: Number(this.currentBlock),
+      timestamp: formatTimestamp(Number(this.timestamp), raw),
+      core: {
+        addressProviderV3: this.addressProvider.stateHuman(raw)
+      },
+      tokens: this.tokensMeta.values(),
+      plugins: Object.fromEntries(
+        TypedObjectUtils.entries(this.plugins).map(([name, plugin]) => [
+          name,
+          plugin.loaded ? plugin.stateHuman?.(raw) : void 0
+        ])
+      ),
+      ...this.marketRegister.stateHuman(raw)
+    };
+  }
+  /** Serialisable snapshot of the current SDK state. */
+  get state() {
+    return {
+      version: STATE_VERSION,
+      network: this.networkType,
+      chainId: this.chainId,
+      currentBlock: this.currentBlock,
+      timestamp: this.timestamp,
+      addressProvider: this.addressProvider.state,
+      markets: this.marketRegister.state,
+      plugins: Object.fromEntries(
+        TypedObjectUtils.entries(this.plugins).map(([name, plugin]) => [
+          name,
+          plugin.loaded ? { version: plugin.version, loaded: true, ...plugin.state } : { version: plugin.version, loaded: false }
+        ])
+      )
+    };
+  }
+  /**
+   * Incrementally updates SDK state by replaying on-chain events.
+   *
+   * @param opts - Target block and sync behaviour.
+   * @returns `true` if the sync completed successfully.
+   */
+  async syncState(opts) {
+    let { blockNumber, timestamp, ignoreUpdateablePrices } = opts ?? {};
+    if (this.priceFeeds.historical && !ignoreUpdateablePrices) {
+      this.logger?.warn(
+        "syncState is not supported with redstone or pyth historicTimestamp"
+      );
+    }
+    if (!blockNumber || !timestamp) {
+      const block = await this.client.getBlock({
+        blockTag: "latest"
+      });
+      blockNumber = block.number;
+      timestamp = block.timestamp;
+    }
+    if (blockNumber <= this.currentBlock) {
+      return false;
+    }
+    if (this.#syncing) {
+      this.logger?.warn(
+        `cannot sync to ${blockNumber}, already syncing at ${this.currentBlock}`
+      );
+      return false;
+    }
+    this.#syncing = true;
+    const prevBlock = this.currentBlock;
+    const prevTimestamp = this.timestamp;
+    let success = false;
+    try {
+      let delta = Math.floor(Date.now() / 1e3) - Number(timestamp);
+      this.logger?.debug(
+        `syncing state to block ${blockNumber} (delta ${delta}s )...`
+      );
+      const watchAddresses = [
+        ...Array.from(this.marketRegister.watchAddresses),
+        this.addressProvider.address
+      ];
+      const fromBlock = this.currentBlock + 1n;
+      this.logger?.debug(
+        `getting logs from ${watchAddresses.length} addresses in [${fromBlock}:${blockNumber}]`
+      );
+      const logs = await getLogsSafe(this.client, {
+        fromBlock,
+        toBlock: blockNumber,
+        address: watchAddresses
+      });
+      for (const log of logs) {
+        const contract = this.getContract(log.address);
+        if (contract) {
+          const event = parseEventLogs({
+            abi: contract.abi,
+            logs: [log]
+          })[0];
+          contract.processLog(event);
+        }
+      }
+      this.#currentBlock = blockNumber;
+      this.#timestamp = timestamp;
+      await this.marketRegister.syncState(ignoreUpdateablePrices);
+      const pluginsList = TypedObjectUtils.entries(this.plugins);
+      const pluginResponse = await Promise.allSettled(
+        pluginsList.map(([name, plugin]) => {
+          if (plugin.syncState) {
+            this.logger?.debug(`syncing plugin ${name}`);
+            return plugin.syncState();
+          }
+          return void 0;
+        })
+      );
+      pluginResponse.forEach((r, i) => {
+        const [name, plugin] = pluginsList[i];
+        if (plugin.syncState && r.status === "fulfilled") {
+          this.logger?.debug(`synced plugin ${name}`);
+        } else if (plugin.syncState && r.status === "rejected") {
+          this.logger?.error(r.reason, `failed to sync plugin ${name}`);
+        }
+      });
+      delta = Math.floor(Date.now() / 1e3) - Number(timestamp);
+      this.logger?.debug(
+        `synced state to block ${blockNumber} (delta ${delta}s)`
+      );
+      success = true;
+    } catch (e) {
+      this.logger?.error(
+        `sync state to block ${blockNumber} with ts ${timestamp} failed, reverting to old block ${prevBlock} with ts ${prevTimestamp}: ${e}`
+      );
+      this.#currentBlock = prevBlock;
+      this.#timestamp = prevTimestamp;
+    } finally {
+      this.#syncing = false;
+    }
+    return success;
+  }
+  /**
+   * Block number that the SDK state corresponds to.
+   * @throws {@link SdkNotAttachedError} if not attached.
+   */
+  get currentBlock() {
+    if (this.#currentBlock === void 0) {
+      throw new SdkNotAttachedError();
+    }
+    return this.#currentBlock;
+  }
+  /**
+   * Block timestamp (Unix epoch seconds) corresponding to {@link currentBlock}.
+   * @throws {@link SdkNotAttachedError} if not attached.
+   */
+  get timestamp() {
+    if (this.#timestamp === void 0) {
+      throw new SdkNotAttachedError();
+    }
+    return this.#timestamp;
+  }
+  /**
+   * Global registry of all price feeds known to the SDK.
+   * @throws {@link SdkNotAttachedError} if not attached.
+   */
+  get priceFeeds() {
+    if (this.#priceFeeds === void 0) {
+      throw new SdkNotAttachedError();
+    }
+    return this.#priceFeeds;
+  }
+  /** GEAR governance token address, or `undefined` if not listed. */
+  get gear() {
+    try {
+      const g = this.addressProvider.getAddress(AP_GEAR_TOKEN, NO_VERSION);
+      return g;
+    } catch (e) {
+      this.logger?.warn(e);
+      return void 0;
+    }
+  }
+  /**
+   * The chain's address provider contract.
+   * @throws {@link SdkNotAttachedError} if not attached.
+   */
+  get addressProvider() {
+    if (this.#addressProvider === void 0) {
+      throw new SdkNotAttachedError();
+    }
+    return this.#addressProvider;
+  }
+  /**
+   * Registry of all loaded markets.
+   * @throws {@link SdkNotAttachedError} if not attached.
+   */
+  get marketRegister() {
+    if (this.#marketRegister === void 0) {
+      throw new SdkNotAttachedError();
+    }
+    return this.#marketRegister;
+  }
+  /**
+   * Resolves the appropriate router contract for a given credit manager,
+   * credit facade, or explicit version range.
+   */
+  routerFor(params) {
+    let routerRange;
+    if (Array.isArray(params)) {
+      routerRange = params;
+    } else {
+      let facadeAddr;
+      if ("creditFacade" in params) {
+        facadeAddr = toAddress(params.creditFacade);
+      } else {
+        const cm = this.marketRegister.findCreditManager(
+          toAddress(params.creditManager)
+        );
+        facadeAddr = cm.creditFacade.address;
+      }
+      const facadeV = this.mustGetContract(facadeAddr).version;
+      if (isV310(facadeV)) {
+        routerRange = VERSION_RANGE_310;
+      } else {
+        throw new Error(`Unsupported credit facade version ${facadeV}`);
+      }
+    }
+    const routerEntry = this.addressProvider.getLatest(AP_ROUTER, routerRange);
+    if (!routerEntry) {
+      throw new Error(`router not found in version range ${routerRange}`);
+    }
+    const [routerAddr, routerV] = routerEntry;
+    return createRouter(this, routerAddr, routerV);
+  }
+}
+export {
+  OnchainSDK,
+  STATE_VERSION
+};