@moonwell-fi/moonwell-sdk 0.13.0 → 0.13.1

package/actions/governance/getStakingInfo.ts

@@ -7,14 +7,10 @@ import {
   getEnvironmentsFromArgs,
 } from "../../common/index.js";
 import type { NetworkParameterType } from "../../common/types.js";
-import {
-  type Chain,
-  type Environment,
-  type TokensType,
-  publicEnvironments,
-} from "../../environments/index.js";
+import type { Chain, Environment } from "../../environments/index.js";
 import type { StakingInfo } from "../../types/staking.js";
 import { getMerklStakingApr } from "./common.js";
+import { getGovernanceTokenPriceFor } from "./getWellPrice.js";
 
 export type GetStakingInfoParameters<
   environments,
@@ -23,6 +19,108 @@ export type GetStakingInfoParameters<
 
 export type GetStakingInfoReturnType = Promise<StakingInfo[]>;
 
+type StakingInfoStruct = {
+  cooldown: bigint;
+  distributionEnd: bigint;
+  emissionPerSecond: bigint;
+  totalSupply: bigint;
+  unstakeWindow: bigint;
+};
+
+const isStakingInfoStruct = (value: unknown): value is StakingInfoStruct => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.cooldown === "bigint" &&
+    typeof v.distributionEnd === "bigint" &&
+    typeof v.emissionPerSecond === "bigint" &&
+    typeof v.totalSupply === "bigint" &&
+    typeof v.unstakeWindow === "bigint"
+  );
+};
+
+/**
+ * Reads the staking fields directly from the stkWELL token contract when the
+ * core views' getStakingInfo() is unavailable or returns zeroed data
+ * (e.g. reverts on Moonbeam). Reads each field independently so a single
+ * transient RPC failure doesn't erase the whole fallback.
+ *
+ * The `assets` mapping is keyed by the stkWELL contract's own address — that's
+ * the Aave-fork convention (`address(this)` in StakedAave._initialize), not
+ * the underlying staked token. Verified on Moonbeam: assets(stkWELL) returns
+ * non-zero emissionPerSecond; assets(WELL) returns zero.
+ */
+async function getStakingInfoFromStkWell(
+  environment: Environment,
+): Promise<StakingInfoStruct | undefined> {
+  const stakingToken = environment.contracts.stakingToken;
+  const stakingTokenKey = environment.config.contracts.stakingToken;
+  const tokens = environment.config.tokens as Record<
+    string,
+    { address: `0x${string}` } | undefined
+  >;
+  const stakingTokenAddress = stakingTokenKey
+    ? tokens[stakingTokenKey]?.address
+    : undefined;
+  if (!stakingToken || !stakingTokenAddress) {
+    environment.onError?.(
+      new Error("getStakingInfoFromStkWell: missing stkWELL config"),
+      { source: "staking-fallback", chainId: environment.chainId },
+    );
+    return undefined;
+  }
+
+  const [
+    cooldownR,
+    unstakeWindowR,
+    distributionEndR,
+    totalSupplyR,
+    assetDataR,
+  ] = await Promise.allSettled([
+    stakingToken.read.COOLDOWN_SECONDS(),
+    stakingToken.read.UNSTAKE_WINDOW(),
+    stakingToken.read.DISTRIBUTION_END(),
+    stakingToken.read.totalSupply(),
+    stakingToken.read.assets([stakingTokenAddress]),
+  ]);
+
+  // Surface every rejection so operators don't have to guess which read failed.
+  for (const r of [
+    cooldownR,
+    unstakeWindowR,
+    distributionEndR,
+    totalSupplyR,
+    assetDataR,
+  ]) {
+    if (r.status === "rejected") {
+      environment.onError?.(r.reason, {
+        source: "staking-fallback",
+        chainId: environment.chainId,
+      });
+    }
+  }
+
+  // totalSupply is load-bearing for APR; if its read failed (vs. legitimately
+  // returning 0n on an empty new chain) we can't produce a sensible struct.
+  if (totalSupplyR.status === "rejected") return undefined;
+
+  const assetData =
+    assetDataR.status === "fulfilled" ? assetDataR.value : undefined;
+  // viem returns multi-output reads as a tuple (Readonly<[bigint, bigint, bigint]>)
+  // even when the ABI names the outputs.
+  const emissionPerSecond = assetData ? assetData[0] : 0n;
+
+  return {
+    cooldown: cooldownR.status === "fulfilled" ? cooldownR.value : 0n,
+    unstakeWindow:
+      unstakeWindowR.status === "fulfilled" ? unstakeWindowR.value : 0n,
+    distributionEnd:
+      distributionEndR.status === "fulfilled" ? distributionEndR.value : 0n,
+    totalSupply: totalSupplyR.value,
+    emissionPerSecond,
+  };
+}
+
 export async function getStakingInfo<
   environments,
   Network extends Chain | undefined,
@@ -36,85 +134,104 @@ export async function getStakingInfo<
     (env) => env.config.contracts.stakingToken,
   );
 
+  const baseEnvironment = (
+    client.environments as { base?: Environment } | undefined
+  )?.base;
+
   const envStakingInfoSettlements = await Promise.allSettled(
     envsWithStaking.map(async (environment) => {
-      const homeEnvironment =
-        (Object.values(publicEnvironments) as Environment[]).find((e) =>
-          e.custom?.governance?.chainIds?.includes(environment.chainId),
-        ) || environment;
-
       const isBase = environment.chainId === base.id;
 
-      const settlements = await Promise.allSettled([
-        environment.contracts.views?.read.getStakingInfo(),
-        homeEnvironment.contracts.views?.read.getGovernanceTokenPrice(),
-        ...(isBase
-          ? [
-              environment.contracts.views?.read.getStakingInfo({
+      const [viewsStakingResult, historicalStakingResult, priceResult] =
+        await Promise.allSettled([
+          environment.contracts.views?.read.getStakingInfo(),
+          isBase
+            ? environment.contracts.views?.read.getStakingInfo({
                 blockNumber: BigInt(34149943),
-              }),
-            ]
-          : []),
-      ]);
-
-      return settlements.map((s) =>
-        s.status === "fulfilled" ? s.value : undefined,
-      );
+              })
+            : Promise.resolve(undefined),
+          getGovernanceTokenPriceFor(environment, baseEnvironment),
+        ]);
+
+      const viewsStaking =
+        viewsStakingResult.status === "fulfilled"
+          ? viewsStakingResult.value
+          : undefined;
+
+      // Fall back to direct stkWELL reads when the views call rejected (the
+      // known Moonbeam failure mode) or returned a fully-zeroed struct
+      // (suspicious — a real deployment always has cooldown and unstake
+      // window configured > 0). A new chain with zero stakers but real
+      // schedule constants still goes through views.
+      const allZeroed =
+        isStakingInfoStruct(viewsStaking) &&
+        viewsStaking.cooldown === 0n &&
+        viewsStaking.unstakeWindow === 0n &&
+        viewsStaking.totalSupply === 0n &&
+        viewsStaking.emissionPerSecond === 0n;
+      const viewsValid = isStakingInfoStruct(viewsStaking) && !allZeroed;
+      const stakingInfo: StakingInfoStruct | undefined = viewsValid
+        ? viewsStaking
+        : await getStakingInfoFromStkWell(environment);
+
+      const historicalStaking =
+        historicalStakingResult.status === "fulfilled"
+          ? historicalStakingResult.value
+          : undefined;
+
+      const price = priceResult.status === "fulfilled" ? priceResult.value : 0n;
+
+      if (priceResult.status === "rejected") {
+        environment.onError?.(priceResult.reason, {
+          source: "governance-token-price",
+          chainId: environment.chainId,
+        });
+      }
+
+      return { stakingInfo, historicalStaking, price };
     }),
   );
 
-  const envStakingInfo = envStakingInfoSettlements
-    .filter((s) => s.status === "fulfilled")
-    .map(
-      (s) =>
-        (
-          s as PromiseFulfilledResult<
-            (
-              | bigint
-              | {
-                  cooldown: bigint;
-                  unstakeWindow: bigint;
-                  distributionEnd: bigint;
-                  totalSupply: bigint;
-                  emissionPerSecond: bigint;
-                  lastUpdateTimestamp: bigint;
-                  index: bigint;
-                }
-              | undefined
-            )[]
-          >
-        ).value,
-    )
-    .filter((val) => val !== undefined);
+  const envStakingInfo = envStakingInfoSettlements.map((s) =>
+    s.status === "fulfilled"
+      ? s.value
+      : { stakingInfo: undefined, historicalStaking: undefined, price: 0n },
+  );
 
   const baseEnv = envsWithStaking.find((env) => env.chainId === base.id);
-  const stakingTokenKey = baseEnv?.config.contracts.stakingToken;
-  const baseStkToken =
-    baseEnv != null && stakingTokenKey != null
-      ? baseEnv.config.tokens[stakingTokenKey]
-      : undefined;
-  const baseStakingApr =
-    baseStkToken != null ? await getMerklStakingApr(baseStkToken.address) : 0;
+  const baseStakingTokenKey = baseEnv?.config.contracts.stakingToken;
+  const baseTokens = baseEnv?.config.tokens as
+    | Record<string, { address: `0x${string}` } | undefined>
+    | undefined;
+  const baseStkTokenAddress = baseStakingTokenKey
+    ? baseTokens?.[baseStakingTokenKey]?.address
+    : undefined;
+  const baseStakingApr = baseStkTokenAddress
+    ? await getMerklStakingApr(baseStkTokenAddress)
+    : 0;
 
   const result = envsWithStaking.flatMap((curr, index) => {
-    const token =
-      curr.config.tokens[
-        curr.config.contracts.governanceToken as keyof TokensType<typeof curr>
-      ]!;
-    const stakingToken =
-      curr.config.tokens[
-        curr.config.contracts.stakingToken as keyof TokensType<typeof curr>
-      ]!;
-
-    const envStakingInfoData = envStakingInfo[index]![0]!;
-    const envGovernanceTokenPriceData = envStakingInfo[index]![1];
-    const envStakingInfoDataAfterX28Proposal = envStakingInfo[index]![2]!;
+    const govKey = curr.config.contracts.governanceToken;
+    const stkKey = curr.config.contracts.stakingToken;
+    const currTokens = curr.config.tokens as Record<
+      string,
+      { address: `0x${string}`; decimals: number; name: string; symbol: string }
+    >;
+    if (!govKey || !stkKey) return [];
+    const token = currTokens[govKey];
+    const stakingToken = currTokens[stkKey];
+    if (!token || !stakingToken) return [];
+
+    // envStakingInfo is built via Promise.allSettled with an explicit
+    // fallback object at the .map below, so entries are always defined here.
+    const {
+      stakingInfo: envStakingInfoData,
+      historicalStaking,
+      price,
+    } = envStakingInfo[index];
     const isBase = curr.chainId === base.id;
 
-    if (
-      !envStakingInfoData ||
-      (isBase && !envStakingInfoDataAfterX28Proposal)
-    ) {
+    if (!envStakingInfoData || (isBase && !historicalStaking)) {
       return [];
     }
 
@@ -124,20 +241,9 @@ export async function getStakingInfo<
       emissionPerSecond: emissionPerSecondRaw,
       totalSupply: totalSupplyRaw,
       unstakeWindow,
-    } = envStakingInfoData as {
-      cooldown: bigint;
-      distributionEnd: bigint;
-      emissionPerSecond: bigint;
-      totalSupply: bigint;
-      unstakeWindow: bigint;
-    };
-
-    //Quick workaround to get governance token price from some other environment
-    const governanceTokenPrice = new Amount(
-      (envGovernanceTokenPriceData ?? 0n) as bigint,
-      18,
-    );
+    } = envStakingInfoData;
 
+    const tokenPrice = new Amount(price, 18);
     const totalSupply = new Amount(totalSupplyRaw, 18);
     const emissionPerSecond = new Amount(emissionPerSecondRaw, 18);
 
@@ -145,7 +251,9 @@ export async function getStakingInfo<
       emissionPerSecond.value * SECONDS_PER_DAY * DAYS_PER_YEAR;
 
     const apr =
-      ((emissionPerYear + totalSupply.value) / totalSupply.value - 1) * 100;
+      totalSupply.value > 0
+        ? ((emissionPerYear + totalSupply.value) / totalSupply.value - 1) * 100
+        : 0;
 
     const stakingInfo: StakingInfo = {
       apr: isBase ? baseStakingApr : apr,
@@ -153,10 +261,10 @@ export async function getStakingInfo<
       cooldown: Number(cooldown),
       distributionEnd: Number(distributionEnd),
       token,
-      tokenPrice: governanceTokenPrice.value,
+      tokenPrice: tokenPrice.value,
       stakingToken,
       totalSupply,
-      totalSupplyUSD: totalSupply.value * governanceTokenPrice.value,
+      totalSupplyUSD: totalSupply.value * tokenPrice.value,
       unstakeWindow: Number(unstakeWindow),
     };
 

package/actions/governance/getUserStakingInfo.ts

@@ -3,13 +3,10 @@ import { base } from "viem/chains";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import { Amount, getEnvironmentsFromArgs } from "../../common/index.js";
 import type { OptionalNetworkParameterType } from "../../common/types.js";
-import {
-  type Environment,
-  type TokensType,
-  publicEnvironments,
-} from "../../environments/index.js";
+import type { Environment } from "../../environments/index.js";
 import type { UserStakingInfo } from "../../types/staking.js";
 import { getMerklCampaignIds, getMerklRewardsData } from "./common.js";
+import { getGovernanceTokenPriceFor } from "./getWellPrice.js";
 
 export type GetUserStakingInfoParameters<
   environments,
@@ -21,6 +18,113 @@ export type GetUserStakingInfoParameters<
 
 export type GetUserStakingInfoReturnType = Promise<UserStakingInfo[]>;
 
+type UserStakingFields = {
+  cooldown: bigint;
+  pendingRewards: bigint;
+  totalStaked: bigint;
+};
+
+type StakingScheduleFields = {
+  cooldown: bigint;
+  unstakeWindow: bigint;
+};
+
+/**
+ * Reads per-user staking fields directly from stkWELL when views.getUserStakingInfo()
+ * is unavailable (e.g. reverts on Moonbeam).
+ */
+async function readUserStakingFromStkWell(
+  environment: Environment,
+  userAddress: Address,
+): Promise<UserStakingFields | undefined> {
+  const stakingToken = environment.contracts.stakingToken;
+  if (!stakingToken) return undefined;
+
+  const [cooldownR, rewardsR, balanceR] = await Promise.allSettled([
+    stakingToken.read.stakersCooldowns([userAddress]),
+    stakingToken.read.getTotalRewardsBalance([userAddress]),
+    stakingToken.read.balanceOf([userAddress]),
+  ]);
+
+  // Surface every rejection so a single failed read (e.g. balanceOf throttled)
+  // doesn't silently zero a field that the UI would then display as "no stake".
+  for (const r of [cooldownR, rewardsR, balanceR]) {
+    if (r.status === "rejected") {
+      environment.onError?.(r.reason, {
+        source: "user-staking-fallback",
+        chainId: environment.chainId,
+      });
+    }
+  }
+
+  if (
+    cooldownR.status === "rejected" &&
+    rewardsR.status === "rejected" &&
+    balanceR.status === "rejected"
+  ) {
+    return undefined;
+  }
+
+  return {
+    cooldown: cooldownR.status === "fulfilled" ? cooldownR.value : 0n,
+    pendingRewards: rewardsR.status === "fulfilled" ? rewardsR.value : 0n,
+    totalStaked: balanceR.status === "fulfilled" ? balanceR.value : 0n,
+  };
+}
+
+/**
+ * Reads global cooldown/unstakeWindow constants from stkWELL when
+ * views.getStakingInfo() is unavailable.
+ */
+async function readScheduleFromStkWell(
+  environment: Environment,
+): Promise<StakingScheduleFields | undefined> {
+  const stakingToken = environment.contracts.stakingToken;
+  if (!stakingToken) return undefined;
+
+  const [cooldownR, unstakeWindowR] = await Promise.allSettled([
+    stakingToken.read.COOLDOWN_SECONDS(),
+    stakingToken.read.UNSTAKE_WINDOW(),
+  ]);
+
+  // Surface every rejection. A silent cooldown=0n would corrupt downstream
+  // cooldownEnding math even if the unstakeWindow read succeeded.
+  for (const r of [cooldownR, unstakeWindowR]) {
+    if (r.status === "rejected") {
+      environment.onError?.(r.reason, {
+        source: "user-staking-schedule-fallback",
+        chainId: environment.chainId,
+      });
+    }
+  }
+
+  if (cooldownR.status === "rejected" && unstakeWindowR.status === "rejected") {
+    return undefined;
+  }
+
+  return {
+    cooldown: cooldownR.status === "fulfilled" ? cooldownR.value : 0n,
+    unstakeWindow:
+      unstakeWindowR.status === "fulfilled" ? unstakeWindowR.value : 0n,
+  };
+}
+
+const isUserStakingShape = (value: unknown): value is UserStakingFields => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.cooldown === "bigint" &&
+    typeof v.pendingRewards === "bigint" &&
+    typeof v.totalStaked === "bigint"
+  );
+};
+
+const isScheduleShape = (value: unknown): value is StakingScheduleFields => {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.cooldown === "bigint" && typeof v.unstakeWindow === "bigint";
+};
+
 export async function getUserStakingInfo<
   environments,
   Network extends Chain | undefined,
@@ -35,23 +139,50 @@ export async function getUserStakingInfo<
   const envsWithStaking = environments.filter(
     (env) => env.contracts.stakingToken,
   );
+
+  const baseEnvironment = (
+    client.environments as { base?: Environment } | undefined
+  )?.base;
+
   const envStakingInfo = await Promise.all(
     envsWithStaking.map(async (environment) => {
-      const homeEnvironment =
-        (Object.values(publicEnvironments) as Environment[]).find((e) =>
-          e.custom?.governance?.chainIds?.includes(environment.chainId),
-        ) || environment;
-
       const settled = await Promise.allSettled([
         environment.contracts.views?.read.getUserStakingInfo([userAddress]),
         environment.contracts.governanceToken?.read.balanceOf([userAddress]),
-        homeEnvironment.contracts.views?.read.getGovernanceTokenPrice(),
         environment.contracts.views?.read.getStakingInfo(),
+        getGovernanceTokenPriceFor(environment, baseEnvironment),
       ]);
 
-      return settled.map((s) =>
-        s.status === "fulfilled" ? s.value : undefined,
-      );
+      const [userStakingR, balanceR, stakingScheduleR, priceR] = settled;
+
+      const viewsUserStaking =
+        userStakingR.status === "fulfilled" ? userStakingR.value : undefined;
+      const userStaking = isUserStakingShape(viewsUserStaking)
+        ? viewsUserStaking
+        : await readUserStakingFromStkWell(environment, userAddress);
+
+      const viewsSchedule =
+        stakingScheduleR.status === "fulfilled"
+          ? stakingScheduleR.value
+          : undefined;
+      const schedule = isScheduleShape(viewsSchedule)
+        ? viewsSchedule
+        : await readScheduleFromStkWell(environment);
+
+      const tokenBalance =
+        balanceR.status === "fulfilled" && balanceR.value !== undefined
+          ? balanceR.value
+          : 0n;
+
+      const price = priceR.status === "fulfilled" ? priceR.value : 0n;
+      if (priceR.status === "rejected") {
+        environment.onError?.(priceR.reason, {
+          source: "governance-token-price",
+          chainId: environment.chainId,
+        });
+      }
+
+      return { userStaking, schedule, tokenBalance, price };
     }),
   );
 
@@ -63,28 +194,27 @@ export async function getUserStakingInfo<
   );
 
   const result = envsWithStaking.flatMap((curr, index) => {
-    const token =
-      curr.config.tokens[
-        curr.config.contracts.governanceToken as keyof TokensType<typeof curr>
-      ]!;
-    const stakingToken =
-      curr.config.tokens[
-        curr.config.contracts.stakingToken as keyof TokensType<typeof curr>
-      ]!;
-
-    const userStakingInfoData = envStakingInfo[index]?.[0] as
-      | {
-          cooldown: bigint;
-          pendingRewards: bigint;
-          totalStaked: bigint;
-        }
-      | undefined;
-
-    if (!userStakingInfoData) return [];
-
-    const { cooldown, pendingRewards, totalStaked } = userStakingInfoData;
-
-    // merkl rewards (only for base)
+    const govKey = curr.config.contracts.governanceToken;
+    const stkKey = curr.config.contracts.stakingToken;
+    const currTokens = curr.config.tokens as Record<
+      string,
+      { address: `0x${string}`; decimals: number; name: string; symbol: string }
+    >;
+    if (!govKey || !stkKey) return [];
+    const token = currTokens[govKey];
+    const stakingToken = currTokens[stkKey];
+    if (!token || !stakingToken) return [];
+
+    // envStakingInfo is built via Promise.all over the same envsWithStaking
+    // array, so index access is always defined.
+    const { userStaking, schedule, tokenBalance, price } =
+      envStakingInfo[index];
+
+    if (!userStaking || !schedule) return [];
+
+    const { cooldown, pendingRewards, totalStaked } = userStaking;
+    const { cooldown: cooldownSeconds, unstakeWindow } = schedule;
+
     const isBase = curr.chainId === base.id;
     const merklReward = merklRewards.reduce((acc, r) => {
       if (r.chain === curr.chainId) {
@@ -94,27 +224,11 @@ export async function getUserStakingInfo<
     }, 0n);
     const merklPendingRewards = isBase ? merklReward : 0n;
 
-    const tokenBalance = (envStakingInfo[index]?.[1] ?? 0n) as bigint;
-
-    const governanceTokenPriceRaw = (envStakingInfo[index]?.[2] ??
-      0n) as bigint;
-
-    const stakingInfoData = envStakingInfo[index]?.[3] as
-      | {
-          cooldown: bigint;
-          unstakeWindow: bigint;
-        }
-      | undefined;
-
-    if (!stakingInfoData) return [];
-
-    const { cooldown: cooldownSeconds, unstakeWindow } = stakingInfoData;
-
     const cooldownEnding = cooldown > 0n ? cooldown + cooldownSeconds : 0n;
     const unstakingEnding =
       cooldown > 0n ? cooldown + cooldownSeconds + unstakeWindow : 0n;
 
-    const governanceTokenPrice = new Amount(governanceTokenPriceRaw, 18);
+    const tokenPrice = new Amount(price, 18);
 
     const userStakingInfo: UserStakingInfo = {
       chainId: curr.chainId,
@@ -128,7 +242,7 @@ export async function getUserStakingInfo<
         : new Amount(pendingRewards, 18),
       token,
       tokenBalance: new Amount(tokenBalance, 18),
-      tokenPrice: governanceTokenPrice.value,
+      tokenPrice: tokenPrice.value,
       stakingToken,
       stakingTokenBalance: new Amount(totalStaked, 18),
     };

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;
+}