@moonwell-fi/moonwell-sdk 0.12.2 → 0.13.1

package/actions/governance/getWellPrice.ts

@@ -0,0 +1,66 @@
+import {
+  type Environment,
+  publicEnvironments,
+} from "../../environments/index.js";
+
+/**
+ * Reads WELL/USD from Base's lending oracle via getUnderlyingPrice(mWELL).
+ *
+ * The Base oracle is Chainlink-fed and shared by the lending markets, so it's
+ * the authoritative WELL/USD source. Used in place of the per-chain
+ * views.getGovernanceTokenPrice() which is unreliable on Moonbeam (returns
+ * stale data) and Base (returns 0).
+ *
+ * Returns a uint256 already scaled to 18 decimals.
+ *
+ * @param baseEnvironment Pass the caller's Base environment when available so
+ *   user-configured RPCs / onError handlers are honored. Falls back to the
+ *   SDK's default public Base environment otherwise.
+ */
+export async function getWellPriceFromBaseOracle(
+  baseEnvironment?: Environment,
+): Promise<bigint> {
+  const baseEnv = baseEnvironment ?? publicEnvironments.base;
+  const tokens = baseEnv.config.tokens as Record<
+    string,
+    { address: `0x${string}` } | undefined
+  >;
+  const mWELL = tokens.MOONWELL_WELL?.address;
+  const oracle = baseEnv.contracts.oracle;
+  if (!mWELL || !oracle) {
+    // A custom Base env without MOONWELL_WELL or an oracle would silently
+    // zero out every WELL-priced read across the SDK. Surface it instead.
+    baseEnv.onError?.(
+      new Error(
+        `getWellPriceFromBaseOracle: missing ${!mWELL ? "MOONWELL_WELL token" : "oracle contract"} on Base env`,
+      ),
+      { source: "well-price", chainId: baseEnv.chainId },
+    );
+    return 0n;
+  }
+  return await oracle.read.getUnderlyingPrice([mWELL]);
+}
+
+/**
+ * Returns the governance-token-in-USD price for an environment.
+ *
+ * - For WELL-governed chains (Base, Optimism, Moonbeam), reads from the Base
+ *   lending oracle's mWELL underlying price (authoritative, Chainlink-fed).
+ * - For non-WELL chains (currently only Moonriver / MFAM), reads from the
+ *   env's own views.getGovernanceTokenPrice() — Moonriver has its own MFAM
+ *   oracle and isn't priced from Base.
+ *
+ * Returns 0n if the lookup fails.
+ */
+export async function getGovernanceTokenPriceFor(
+  environment: Environment,
+  baseEnvironment?: Environment,
+): Promise<bigint> {
+  if (environment.custom?.governance?.token === "WELL") {
+    return getWellPriceFromBaseOracle(baseEnvironment);
+  }
+  // Non-WELL (e.g. Moonriver / MFAM): the env itself is the governance "home".
+  const views = environment.contracts.views;
+  if (!views) return 0n;
+  return (await views.read.getGovernanceTokenPrice()) ?? 0n;
+}

package/actions/morpho/user-rewards/common.ts

@@ -12,10 +12,46 @@ import {
 } from "../../../environments/utils/index.js";
 import type { MorphoUserReward } from "../../../types/morphoUserReward.js";
 import type { MorphoUserStakingReward } from "../../../types/morphoUserStakingReward.js";
+import { getGovernanceTokenPriceFor } from "../../governance/getWellPrice.js";
+
+/**
+ * Error thrown for any failure communicating with the Merkl API: non-ok HTTP
+ * responses, network rejections (fetch threw), and response-body parse errors.
+ *
+ * - HTTP failures populate `status` and `statusText`.
+ * - Network and parse failures leave `status`/`statusText` undefined and
+ *   carry the original error via `cause`.
+ */
+export class MerklApiError extends Error {
+  readonly status: number | undefined;
+  readonly statusText: string | undefined;
+  readonly url: string;
+  readonly chainId: number;
+
+  constructor(params: {
+    message: string;
+    url: string;
+    chainId: number;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    cause?: unknown;
+  }) {
+    super(
+      params.message,
+      params.cause !== undefined ? { cause: params.cause } : undefined,
+    );
+    this.name = "MerklApiError";
+    this.url = params.url;
+    this.chainId = params.chainId;
+    this.status = params.status;
+    this.statusText = params.statusText;
+  }
+}
 
 export async function getUserMorphoRewardsData(params: {
   environment: Environment;
   account: `0x${string}`;
+  throwOnExternalApiError?: boolean;
 }): Promise<MorphoUserReward[]> {
   // The Morpho URD distributions endpoint (rewards.morpho.org) was
   // deprecated and now 301-redirects to a SPA, so JSON parsing fails.
@@ -23,6 +59,7 @@ export async function getUserMorphoRewardsData(params: {
   const merklRewards = await getMerklRewardsData(
     params.environment,
     params.account,
+    { throwOnError: params.throwOnExternalApiError ?? false },
   );
 
   const isFullDeployment =
@@ -128,11 +165,17 @@ export async function getUserMorphoStakingRewardsData(params: {
     await Promise.all([
       viewsContract?.read.getAllMarketsInfo(),
       homeViewsContract?.read.getNativeTokenPrice(),
-      homeViewsContract?.read.getGovernanceTokenPrice(),
+      getGovernanceTokenPriceFor(params.environment).catch((err) => {
+        params.environment.onError?.(err, {
+          source: "governance-token-price",
+          chainId: params.environment.chainId,
+        });
+        return 0n;
+      }),
     ]);
 
-  const governanceTokenPrice = new Amount(governanceTokenPriceRaw || 0n, 18);
-  const nativeTokenPrice = new Amount(nativeTokenPriceRaw || 0n, 18);
+  const governanceTokenPrice = new Amount(governanceTokenPriceRaw, 18);
+  const nativeTokenPrice = new Amount(nativeTokenPriceRaw ?? 0n, 18);
 
   let tokenPrices =
     allMarkets
@@ -294,30 +337,64 @@ type MerklRewardsResponse = {
 async function getMerklRewardsData(
   environment: Environment,
   account: Address,
+  options: { throwOnError: boolean } = { throwOnError: false },
 ): Promise<MerklRewardsResponse[]> {
+  const url = `https://api.merkl.xyz/v4/users/${account}/rewards?chainId=${environment.chainId}&test=false&breakdownPage=0&reloadChainId=${environment.chainId}`;
+
+  let response: Response;
   try {
     // Merkl campaigns always distribute rewards on the same chain as the
     // opportunity, so environment.chainId is the only chain we need to query.
     // The previous two-phase approach (fetch opportunities per vault → extract
     // chain IDs → fetch rewards per chain) made N+1 HTTP calls to discover
     // a chain ID we already know.
-    const response = await fetch(
-      `https://api.merkl.xyz/v4/users/${account}/rewards?chainId=${environment.chainId}&test=false&breakdownPage=0&reloadChainId=${environment.chainId}`,
-      {
-        headers: MOONWELL_FETCH_JSON_HEADERS,
-      },
+    response = await fetch(url, { headers: MOONWELL_FETCH_JSON_HEADERS });
+  } catch (error) {
+    if (options.throwOnError) {
+      throw new MerklApiError({
+        message: `Merkl API network error for chain ${environment.chainId}`,
+        url,
+        chainId: environment.chainId,
+        cause: error,
+      });
+    }
+    console.error(
+      `[getMerklRewardsData:network] chain=${environment.chainId} url=${url}`,
+      error,
     );
+    return [];
+  }
 
-    if (!response.ok) {
-      console.warn(
-        `Merkl API request failed: ${response.status} ${response.statusText}`,
-      );
-      return [];
+  if (!response.ok) {
+    const message = `Merkl API request failed for chain ${environment.chainId}: ${response.status} ${response.statusText}`;
+    if (options.throwOnError) {
+      throw new MerklApiError({
+        message,
+        url,
+        chainId: environment.chainId,
+        status: response.status,
+        statusText: response.statusText,
+      });
     }
+    console.warn(`${message} (url=${url})`);
+    return [];
+  }
 
+  try {
     return (await response.json()) as MerklRewardsResponse[];
   } catch (error) {
-    console.error("Error in getMerklRewardsData:", error);
+    if (options.throwOnError) {
+      throw new MerklApiError({
+        message: `Merkl API response parse error for chain ${environment.chainId}`,
+        url,
+        chainId: environment.chainId,
+        cause: error,
+      });
+    }
+    console.error(
+      `[getMerklRewardsData:parse] chain=${environment.chainId} url=${url}`,
+      error,
+    );
     return [];
   }
 }

package/actions/morpho/user-rewards/getMorphoUserRewards.ts

@@ -4,13 +4,41 @@ import { getEnvironmentsFromArgs } from "../../../common/index.js";
 import type { OptionalNetworkParameterType } from "../../../common/types.js";
 import type { Chain } from "../../../environments/index.js";
 import type { MorphoUserReward } from "../../../types/morphoUserReward.js";
-import { getUserMorphoRewardsData } from "./common.js";
+import { MerklApiError, getUserMorphoRewardsData } from "./common.js";
+
+/**
+ * AggregateError thrown by `getMorphoUserRewards` when one or more chains
+ * fail and `throwOnExternalApiError` is `true`. The `rewards` property
+ * carries the rewards from any chains that succeeded so callers can still
+ * surface partial results alongside the per-chain failures in `errors`.
+ */
+export class MorphoUserRewardsAggregateError extends AggregateError {
+  readonly rewards: MorphoUserReward[];
+
+  constructor(errors: Error[], message: string, rewards: MorphoUserReward[]) {
+    super(errors, message);
+    this.name = "MorphoUserRewardsAggregateError";
+    this.rewards = rewards;
+  }
+}
 
 export type GetMorphoUserRewardsParameters<
   environments,
   network extends Chain | undefined,
 > = OptionalNetworkParameterType<environments, network> & {
   userAddress: Address;
+  /**
+   * When true, errors from the external Merkl API are propagated to the
+   * caller instead of being swallowed and returning `[]`. Default `false`
+   * preserves the historical behavior for existing consumers.
+   *
+   * If multiple environments are queried and at least one fails while others
+   * succeed, this throws a `MorphoUserRewardsAggregateError` whose `errors`
+   * array contains the per-chain failures and whose `rewards` property
+   * carries the successful chains' rewards so the caller can still display
+   * partial results.
+   */
+  throwOnExternalApiError?: boolean;
 };
 
 export type GetMorphoUserRewardsReturnType = Promise<MorphoUserReward[]>;
@@ -22,18 +50,55 @@ export async function getMorphoUserRewards<
   client: MoonwellClient,
   args: GetMorphoUserRewardsParameters<environments, Network>,
 ): GetMorphoUserRewardsReturnType {
-  const environments = getEnvironmentsFromArgs(client, args);
-
-  const environmentsUserRewards = await Promise.all(
-    environments
-      .filter((environment) => environment.contracts.morphoViews !== undefined)
-      .map((environment) => {
-        return getUserMorphoRewardsData({
-          environment,
-          account: args.userAddress,
-        });
+  const targetEnvironments = getEnvironmentsFromArgs(client, args).filter(
+    (environment) => environment.contracts.morphoViews !== undefined,
+  );
+
+  const settled = await Promise.allSettled(
+    targetEnvironments.map((environment) =>
+      getUserMorphoRewardsData({
+        environment,
+        account: args.userAddress,
+        ...(args.throwOnExternalApiError !== undefined && {
+          throwOnExternalApiError: args.throwOnExternalApiError,
+        }),
       }),
+    ),
   );
 
-  return environmentsUserRewards.flat();
+  const fulfilled: MorphoUserReward[] = [];
+  const failures: Error[] = [];
+  const failedChainIds: number[] = [];
+  for (const [i, result] of settled.entries()) {
+    const environment = targetEnvironments[i];
+    if (result.status === "fulfilled") {
+      fulfilled.push(...result.value);
+      continue;
+    }
+    const reason = result.reason;
+    if (reason instanceof MerklApiError) {
+      failures.push(reason);
+      failedChainIds.push(reason.chainId);
+      continue;
+    }
+    const baseError =
+      reason instanceof Error ? reason : new Error(String(reason));
+    failures.push(
+      new Error(
+        `getMorphoUserRewards failed for chain ${environment.chainId}: ${baseError.message}`,
+        { cause: baseError },
+      ),
+    );
+    failedChainIds.push(environment.chainId);
+  }
+
+  if (failures.length > 0 && args.throwOnExternalApiError === true) {
+    throw new MorphoUserRewardsAggregateError(
+      failures,
+      `getMorphoUserRewards failed for chains: ${failedChainIds.join(", ")}`,
+      fulfilled,
+    );
+  }
+
+  return fulfilled;
 }

package/actions/morpho/vaults/common.ts

@@ -19,6 +19,7 @@ import type {
   MorphoVault,
   MorphoVaultMarket,
 } from "../../../types/morphoVault.js";
+import { getGovernanceTokenPriceFor } from "../../governance/getWellPrice.js";
 import { getGraphQL, getVaultV2Apy } from "../utils/graphql.js";
 import {
   SECONDS_PER_YEAR,
@@ -321,16 +322,19 @@ async function getMorphoVaultsDataFromIndexer(params: {
         const data = await Promise.all([
           viewsContract?.read.getAllMarketsInfo(),
           homeViewsContract?.read.getNativeTokenPrice(),
-          homeViewsContract?.read.getGovernanceTokenPrice(),
+          getGovernanceTokenPriceFor(environment).catch((err) => {
+            environment.onError?.(err, {
+              source: "governance-token-price",
+              chainId: environment.chainId,
+            });
+            return 0n;
+          }),
         ]);
 
         const [allMarkets, nativeTokenPriceRaw, governanceTokenPriceRaw] = data;
 
-        const governanceTokenPrice = new Amount(
-          governanceTokenPriceRaw || 0n,
-          18,
-        );
-        const nativeTokenPrice = new Amount(nativeTokenPriceRaw || 0n, 18);
+        const governanceTokenPrice = new Amount(governanceTokenPriceRaw, 18);
+        const nativeTokenPrice = new Amount(nativeTokenPriceRaw ?? 0n, 18);
 
         let tokenPrices =
           allMarkets
@@ -1056,16 +1060,19 @@ async function getMorphoVaultsDataFromOnChain(params: {
       const data = await Promise.all([
         viewsContract?.read.getAllMarketsInfo(),
         homeViewsContract?.read.getNativeTokenPrice(),
-        homeViewsContract?.read.getGovernanceTokenPrice(),
+        getGovernanceTokenPriceFor(environment).catch((err) => {
+          environment.onError?.(err, {
+            source: "governance-token-price",
+            chainId: environment.chainId,
+          });
+          return 0n;
+        }),
       ]);
 
       const [allMarkets, nativeTokenPriceRaw, governanceTokenPriceRaw] = data;
 
-      const governanceTokenPrice = new Amount(
-        governanceTokenPriceRaw || 0n,
-        18,
-      );
-      const nativeTokenPrice = new Amount(nativeTokenPriceRaw || 0n, 18);
+      const governanceTokenPrice = new Amount(governanceTokenPriceRaw, 18);
+      const nativeTokenPrice = new Amount(nativeTokenPriceRaw ?? 0n, 18);
 
       let tokenPrices =
         allMarkets

package/environments/definitions/ethereum/contracts.ts

@@ -0,0 +1,10 @@
+import { createContractsConfig } from "../../types/config.js";
+import { tokens } from "./tokens.js";
+
+export const contracts = createContractsConfig({
+  tokens,
+  contracts: {
+    // `stakingToken` is intentionally omitted until Ethereum staking contracts ship.
+    governanceToken: "WELL",
+  },
+});

package/environments/definitions/ethereum/custom.ts

@@ -0,0 +1,15 @@
+import { createCustomConfig } from "../../types/config.js";
+
+export const custom = createCustomConfig({
+  governance: {
+    token: "WELL",
+    chainIds: [],
+  },
+  wormhole: {
+    chainId: 2,
+    tokenBridge: { address: "0x3ee18B2214AFF97000D974cf647E654bB5f1d8A8" },
+  },
+  xWELL: {
+    bridgeAdapter: { address: "0x734AbBCe07679C9A6B4Fe3bC16325e028fA6DbB7" },
+  },
+});

package/environments/definitions/ethereum/environment.ts

@@ -1,15 +1,22 @@
-import { http, fallback } from "viem";
-import { mainnet as ethereum } from "viem/chains";
+import { http, defineChain, fallback } from "viem";
+import { mainnet } from "viem/chains";
 import {
   type Environment,
   createEnvironmentConfig,
 } from "../../types/config.js";
+import { contracts } from "./contracts.js";
+import { custom } from "./custom.js";
 import { tokens } from "./tokens.js";
 
+// viem's `mainnet` chain leaves `testnet` undefined; consumers
+// (e.g. the bridge modal) check `env.chain.testnet === false` strictly.
+const ethereum = defineChain({ ...mainnet, testnet: false });
+
 const createEnvironment = (
   rpcUrls?: string[],
   governanceIndexerUrl?: string,
-): Environment<typeof tokens, {}, {}, {}, {}> =>
+  lunarIndexerUrl?: string,
+): Environment<typeof tokens, {}, {}, typeof contracts, typeof custom> =>
   createEnvironmentConfig({
     key: "ethereum",
     name: "Ethereum",
@@ -25,12 +32,14 @@ const createEnvironment = (
     governanceIndexerUrl:
       governanceIndexerUrl ||
       "https://lunar-services-worker.moonwell.workers.dev",
+    lunarIndexerUrl:
+      lunarIndexerUrl || "https://lunar-services-worker.moonwell.workers.dev",
     tokens,
     markets: {},
     vaults: {},
     morphoMarkets: {},
-    contracts: {},
-    custom: {},
-  }) as Environment<typeof tokens, {}, {}, {}, {}>;
+    contracts,
+    custom,
+  }) as Environment<typeof tokens, {}, {}, typeof contracts, typeof custom>;
 
 export { createEnvironment, ethereum, tokens };

package/environments/definitions/ethereum/tokens.ts

@@ -14,4 +14,16 @@ export const tokens = createTokenConfig({
     name: "USD Coin",
     symbol: "USDC",
   },
+  WELL: {
+    address: "0xA88594D404727625A9437C3f886C7643872296AE",
+    decimals: 18,
+    name: "Moonwell",
+    symbol: "WELL",
+  },
+  stkWELL: {
+    address: "0xb3a9E0DCf37658a48aa9f018C44f90378ddD4357",
+    decimals: 18,
+    name: "Moonwell Staked WELL",
+    symbol: "stkWELL",
+  },
 });

package/environments/definitions/governance.ts

@@ -1,4 +1,4 @@
-import { base, moonbeam, moonriver, optimism } from "viem/chains";
+import { base, mainnet, moonbeam, moonriver, optimism } from "viem/chains";
 
 export interface GovernanceTokenInfo {
   id: string;
@@ -30,7 +30,7 @@ export const GovernanceTokensConfig = createGovernanceTokensConfig({
     id: "WELL",
     symbol: "WELL",
     name: "WELL",
-    chainIds: [moonbeam.id, base.id, optimism.id] as number[],
+    chainIds: [moonbeam.id, base.id, optimism.id, mainnet.id] as number[],
     testnet: false,
   },
   MFAM: {

package/errors/version.ts

@@ -1 +1 @@
-export const version = '0.12.2'
+export const version = '0.13.1'

package/index.ts

@@ -3,6 +3,9 @@ export {
   type MoonwellClient,
 } from "./client/createMoonwellClient.js";
 
+export { MerklApiError } from "./actions/morpho/user-rewards/common.js";
+export { MorphoUserRewardsAggregateError } from "./actions/morpho/user-rewards/getMorphoUserRewards.js";
+
 export type {
   MarketConfig,
   MorphoMarketConfig,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonwell-fi/moonwell-sdk",
   "description": "TypeScript Interface for Moonwell",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",