@gearbox-protocol/sdk 14.12.0-next.8 → 14.12.0-next.80

package/dist/esm/sdk/OnchainSDK.js

@@ -1,541 +1,476 @@
-import {
-  createPublicClient,
-  fallback,
-  http,
-  parseEventLogs
-} from "viem";
-import {
-  CreditAccountsServiceV310
-} from "./accounts/index.js";
-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 { RWARegistry } from "./market/index.js";
+import { TypedObjectUtils } from "./utils/mappers.js";
+import { getChain } from "./chain/chains.js";
+import "./chain/index.js";
+import { ADDRESS_PROVIDER_V310, AP_GEAR_TOKEN, AP_ROUTER } from "./constants/address-provider.js";
+import { VERSION_RANGE_310, isV310 } from "./constants/versions.js";
+import "./constants/index.js";
+import { formatTimestamp } from "./utils/formatter.js";
+import { toAddress } from "./utils/toAddress.js";
+import "./utils/index.js";
+import { ChainContractsRegister } from "./base/ChainContractsRegister.js";
+import { SdkAlreadyAttachedError, SdkChainMismatchError, SdkNotAttachedError, SdkStateVersionMismatchError } from "./core/errors.js";
+import "./base/index.js";
+import { executeDelegatedMulticalls } from "./utils/viem/executeDelegatedMulticalls.js";
+import "./utils/viem/index.js";
+import { PriceFeedRegister } from "./market/pricefeeds/PriceFeedsRegister.js";
+import "./market/pricefeeds/index.js";
 import { MarketRegister } from "./market/MarketRegister.js";
-import { PriceFeedRegister } from "./market/pricefeeds/index.js";
-import { PluginStateVersionError } from "./plugins/index.js";
-import { PoolService } from "./pools/index.js";
-import { createRouter } from "./router/index.js";
-import { formatTimestamp, TypedObjectUtils, toAddress } from "./utils/index.js";
-import {
-  executeDelegatedMulticalls
-} from "./utils/viem/index.js";
+import { RWARegistry } from "./market/rwa/RWARegistry.js";
+import "./market/index.js";
+import { CreditAccountsServiceV310 } from "./accounts/CreditAccountsServiceV310.js";
+import { LiquidationsService } from "./accounts/liquidations/LiquidationsService.js";
+import { createRedemptionLogger } from "./accounts/withdrawal-compressor/createRedemptionLogger.js";
+import { createWithdrawalCompressor } from "./accounts/withdrawal-compressor/createWithdrawalCompressor.js";
+import "./accounts/index.js";
+import { createAddressProvider, hydrateAddressProvider } from "./core/createAddressProvider.js";
+import "./core/index.js";
+import { OpportunitiesService } from "./opportunities/OpportunitiesService.js";
+import "./opportunities/index.js";
+import { PluginStateVersionError } from "./plugins/errors.js";
+import "./plugins/index.js";
+import { PoolService } from "./pools/PoolService.js";
+import "./pools/index.js";
+import { PositionsService } from "./positions/PositionsService.js";
+import "./positions/index.js";
+import { createRouter } from "./router/createRouter.js";
+import "./router/index.js";
+import { createPublicClient, fallback, http, parseEventLogs } from "viem";
+//#region src/sdk/OnchainSDK.ts
+/**
+* Serialised state format version, checked during hydration to detect
+* incompatible snapshots.
+**/
 const STATE_VERSION = 1;
+/**
+* @internal
+* Creates a viem `PublicClient` from the given connection options.
+*/
 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 });
+	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;
-  #rwa;
-  #marketRegister;
-  #priceFeeds;
-  /**
-   * Gas limit applied to read-only `eth_call` requests.
-   **/
-  gasLimit;
-  /**
-   * When `true`, the SDK throws on unrecognised contract types.
-   **/
-  strictContractTypes;
-  /**
-   * Namespace for credit accounts operations.
-   */
-  accounts;
-  /**
-   * Namespace for pool operations.
-   */
-  pools;
-  /**
-   * @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 ?? {};
-    this.#rwa = new RWARegistry(this);
-    for (const plugin of Object.values(this.plugins)) {
-      plugin.sdk = this;
-    }
-    if (options?.gasLimit !== null) {
-      this.gasLimit = options?.gasLimit ?? getChain(this.networkType).gasLimit;
-    }
-    this.accounts = new CreditAccountsServiceV310(this);
-    this.pools = new PoolService(this);
-  }
-  /**
-   * 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,
-      loadZappers
-    } = options ?? {};
-    const marketConfigurators = mcs ?? TypedObjectUtils.keys(
-      this.client.chain.defaultMarketConfigurators
-    );
-    const rwaFactories = options?.rwaFactories ?? this.client.chain.rwaFactories;
-    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);
-    if (!marketConfigurators.length) {
-      this.logger?.warn(
-        "no market configurators provided, skipping market loading"
-      );
-    } else {
-      const delegated = [
-        ...this.#marketRegister.getLoadMulticalls(marketConfigurators),
-        ...this.#rwa.getLoadMulticalls(marketConfigurators, rwaFactories)
-      ];
-      let txs = [];
-      if (!ignoreUpdateablePrices) {
-        const updatables = await this.#priceFeeds.getPartialUpdatablePriceFeeds(
-          marketConfigurators
-        );
-        const updates = await this.#priceFeeds.generatePriceFeedsUpdateTxs(updatables);
-        txs = updates.txs;
-      }
-      this.logger?.debug(
-        { configurators: marketConfigurators },
-        `calling getMarkets with ${txs.length} price updates in block ${this.currentBlock}`
-      );
-      await executeDelegatedMulticalls(this.client, delegated, {
-        priceUpdates: txs,
-        blockNumber: this.currentBlock,
-        gas: this.gasLimit
-      });
-      if (loadZappers) {
-        await this.#marketRegister.loadZappers();
-      }
-    }
-    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);
-    this.#rwa = new RWARegistry(this);
-    this.#rwa.setState(state.rwa);
-    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(),
-      rwa: this.#rwa.stateHuman(raw),
-      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,
-      ...this.marketRegister.state,
-      rwa: this.#rwa.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 this.client.getLogs({
-        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;
-  }
-  /**
-   * RWA register for RWA-wrapped underlying tokens and factories.
-   *
-   * @throws If the SDK has not been attached or hydrated yet.
-   **/
-  get rwa() {
-    if (this.#rwa === void 0) {
-      throw new SdkNotAttachedError();
-    }
-    return this.#rwa;
-  }
-  /**
-   * @internal
-   * Resolves the appropriate router contract for a given credit manager,
-   * credit facade, or explicit version range.
-   *
-   * @param params - Identifies the context: a credit manager address/state,
-   *   a credit facade address/state, or a {@link VersionRange}.
-   * @returns The matching router contract instance.
-   * @throws If the credit facade version is unsupported or no router is
-   *   registered for the resolved 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
+/**
+* Single-chain entry point for the Gearbox SDK.
+*
+* `OnchainSDK` aggregates on-chain state for the Gearbox protocol — markets,
+* credit managers, pools, price oracles, and price feeds — into a single
+* queryable object that can be kept up-to-date via {@link syncState} or
+* serialised/restored via {@link state}/{@link hydrate}.
+*
+* Create an instance with `new OnchainSDK(network, clientOptions, options)`,
+* then call {@link attach} (live chain data) or {@link hydrate} (saved snapshot).
+*
+* @typeParam Plugins - Map of plugin names to plugin instances that extend
+*   the SDK with additional domain-specific functionality.
+**/
+var OnchainSDK = class extends ChainContractsRegister {
+	/** Registered plugin instances, keyed by plugin name. */
+	plugins;
+	#currentBlock;
+	#timestamp;
+	#syncing = false;
+	#attached = false;
+	#addressProvider;
+	#rwa;
+	#marketRegister;
+	#priceFeeds;
+	#withdrawalCompressor;
+	#redemptionLogger;
+	/**
+	* Gas limit applied to read-only `eth_call` requests.
+	**/
+	gasLimit;
+	/**
+	* When `true`, the SDK throws on unrecognised contract types.
+	**/
+	strictContractTypes;
+	/**
+	* Namespace for credit accounts operations.
+	*/
+	accounts;
+	/**
+	* Namespace for pool operations.
+	*/
+	pools;
+	/**
+	* Namespace for liquidatable credit accounts discovery.
+	*/
+	liquidations;
+	/**
+	* Namespace for the pool and strategy opportunities of this chain.
+	*/
+	opportunities;
+	/**
+	* Namespace for the positions a wallet holds on this chain.
+	*/
+	positions;
+	/**
+	* @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 ?? {};
+		this.#rwa = new RWARegistry(this);
+		for (const plugin of Object.values(this.plugins)) plugin.sdk = this;
+		if (options?.gasLimit !== null) this.gasLimit = options?.gasLimit ?? getChain(this.networkType).gasLimit;
+		this.accounts = new CreditAccountsServiceV310(this);
+		this.pools = new PoolService(this);
+		this.liquidations = new LiquidationsService(this);
+		this.opportunities = new OpportunitiesService(this);
+		this.positions = new PositionsService(this);
+		this.#withdrawalCompressor = createWithdrawalCompressor(this);
+	}
+	/**
+	* 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, loadZappers } = options ?? {};
+		const marketConfigurators = mcs ?? TypedObjectUtils.keys(this.client.chain.defaultMarketConfigurators);
+		const rwaFactories = options?.rwaFactories ?? this.client.chain.rwaFactories;
+		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 > 6e4) 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 > 6e4) 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);
+		if (!marketConfigurators.length) this.logger?.warn("no market configurators provided, skipping market loading");
+		else {
+			const delegated = [...this.#marketRegister.getLoadMulticalls(marketConfigurators), ...this.#rwa.getLoadMulticalls(marketConfigurators, rwaFactories)];
+			let txs = [];
+			if (!ignoreUpdateablePrices) {
+				const updatables = await this.#priceFeeds.getPartialUpdatablePriceFeeds(marketConfigurators);
+				txs = (await this.#priceFeeds.generatePriceFeedsUpdateTxs(updatables)).txs;
+			}
+			this.logger?.debug({ configurators: marketConfigurators }, `calling getMarkets with ${txs.length} price updates in block ${this.currentBlock}`);
+			await executeDelegatedMulticalls(this.client, delegated, {
+				priceUpdates: txs,
+				blockNumber: this.currentBlock,
+				gas: this.gasLimit
+			});
+			if (loadZappers) await this.#marketRegister.loadZappers();
+		}
+		const pluginsList = TypedObjectUtils.entries(this.plugins);
+		(await Promise.allSettled(pluginsList.map(([name, plugin]) => {
+			if (plugin.attach) {
+				this.logger?.debug(`attaching plugin ${name}`);
+				return plugin.attach();
+			}
+		}))).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 !== 1) throw new SdkStateVersionMismatchError(1, 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);
+		this.#rwa = new RWARegistry(this);
+		this.#rwa.setState(state.rwa);
+		if (state.withdrawals) this.#withdrawalCompressor?.hydrate(state.withdrawals);
+		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(),
+			rwa: this.#rwa.stateHuman(raw),
+			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: 1,
+			network: this.networkType,
+			chainId: this.chainId,
+			currentBlock: this.currentBlock,
+			timestamp: this.timestamp,
+			addressProvider: this.addressProvider.state,
+			...this.marketRegister.state,
+			rwa: this.#rwa.state,
+			withdrawals: this.#withdrawalCompressor?.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 this.client.getLogs({
+				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);
+			(await Promise.allSettled(pluginsList.map(([name, plugin]) => {
+				if (plugin.syncState) {
+					this.logger?.debug(`syncing plugin ${name}`);
+					return plugin.syncState();
+				}
+			}))).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 {
+			return this.addressProvider.getAddress(AP_GEAR_TOKEN, 0);
+		} catch (e) {
+			this.logger?.warn(e);
+			return;
+		}
+	}
+	/**
+	* 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;
+	}
+	/**
+	* RWA register for RWA-wrapped underlying tokens and factories.
+	*
+	* @throws If the SDK has not been attached or hydrated yet.
+	**/
+	get rwa() {
+		if (this.#rwa === void 0) throw new SdkNotAttachedError();
+		return this.#rwa;
+	}
+	/**
+	* @internal
+	* Resolves the appropriate router contract for a given credit manager,
+	* credit facade, or explicit version range.
+	*
+	* @param params - Identifies the context: a credit manager address/state,
+	*   a credit facade address/state, or a {@link VersionRange}.
+	* @returns The matching router contract instance.
+	* @throws If the credit facade version is unsupported or no router is
+	*   registered for the resolved version range.
+	**/
+	routerFor(params) {
+		let routerRange;
+		if (Array.isArray(params)) routerRange = params;
+		else {
+			let facadeAddr;
+			if ("creditFacade" in params) facadeAddr = toAddress(params.creditFacade);
+			else facadeAddr = this.marketRegister.findCreditManager(toAddress(params.creditManager)).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);
+	}
+	/**
+	* Withdrawal compressor contract for the current chain, or `undefined`
+	* when no withdrawal compressor is supported on it.
+	**/
+	get withdrawalCompressor() {
+		return this.#withdrawalCompressor;
+	}
+	/**
+	* `RedemptionLogger` contract for the current chain, or `undefined` when
+	* it is not deployed on it. Created lazily on first access: the contract
+	* is resolved from the address provider, which is only available after
+	* the SDK is attached or hydrated.
+	**/
+	get redemptionLogger() {
+		this.#redemptionLogger ??= createRedemptionLogger(this);
+		return this.#redemptionLogger;
+	}
 };
+//#endregion
+export { OnchainSDK, STATE_VERSION };