@moonwell-fi/moonwell-sdk 0.13.0 → 0.14.0

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/getUserVoteReceipt.ts

@@ -3,7 +3,13 @@ import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import { Amount, getEnvironmentFromArgs } from "../../common/index.js";
 import type { NetworkParameterType } from "../../common/types.js";
 import type { VoteReceipt } from "../../types/voteReceipt.js";
-import { fetchUserVoteReceipt } from "./governor-api-client.js";
+import {
+  type ApiVoteReceipt,
+  GovernorNotFoundError,
+  SUPPORTED_GOVERNOR_CHAIN_IDS,
+  fetchUserVoteReceipt,
+  isNotFoundError,
+} from "./governor-api-client.js";
 
 export type GetUserVoteReceiptParameters<
   environments,
@@ -14,10 +20,27 @@ export type GetUserVoteReceiptParameters<
 
   /** User address*/
   userAddress: Address;
+
+  /**
+   * The chain the proposal lives on (1 = Ethereum multigov,
+   * 1284 = Moonbeam historical). When omitted, every supported chain is queried
+   * and non-empty receipts are concatenated — proposalIds may collide across
+   * chains (they represent different proposals), so a single bare proposalId
+   * can have votes on both Ethereum and Moonbeam.
+   */
+  chainId?: number;
 };
 
 export type GetUserVoteReceiptReturnType = Promise<VoteReceipt[]>;
 
+/**
+ * Fetch a user's vote receipts for a proposal.
+ *
+ * Returns the "didn't vote" stub when the proposal exists on at least one
+ * queried chain but the user hasn't voted there. Throws `GovernorNotFoundError`
+ * when the proposal doesn't exist on any queried chain — callers can use that
+ * to distinguish "the user didn't vote" from "this proposal isn't visible".
+ */
 export async function getUserVoteReceipt<
   environments,
   Network extends Chain | undefined,
@@ -25,44 +48,61 @@ export async function getUserVoteReceipt<
   client: MoonwellClient,
   args: GetUserVoteReceiptParameters<environments, Network>,
 ): GetUserVoteReceiptReturnType {
-  const { proposalId, userAddress } = args;
+  const { proposalId, userAddress, chainId } = args;
 
   const environment = getEnvironmentFromArgs(client, args);
-
   if (!environment) {
     return [];
   }
 
-  try {
-    const apiVoteReceipts = await fetchUserVoteReceipt(
-      environment,
-      `${proposalId}`,
-      userAddress,
-    );
+  const tryChains = chainId ? [chainId] : SUPPORTED_GOVERNOR_CHAIN_IDS;
 
-    if (apiVoteReceipts.length === 0) {
-      return [
-        {
-          chainId: environment.chainId,
-          proposalId,
-          account: userAddress,
-          voted: false,
-          option: 0,
-          votes: new Amount(0, 18),
-        },
-      ];
+  const collected: ApiVoteReceipt[] = [];
+  let anyChainAcknowledged = false;
+  const notFoundChainIds: number[] = [];
+
+  for (const cid of tryChains) {
+    try {
+      const apiVoteReceipts = await fetchUserVoteReceipt(
+        environment,
+        cid,
+        proposalId,
+        userAddress,
+      );
+      anyChainAcknowledged = true;
+      collected.push(...apiVoteReceipts);
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        notFoundChainIds.push(cid);
+        continue;
+      }
+      throw error;
     }
+  }
 
-    return apiVoteReceipts.map((apiReceipt) => ({
-      chainId: apiReceipt.chainId,
-      proposalId,
-      account: userAddress as Address,
-      voted: true,
-      option: apiReceipt.voteValue,
-      votes: new Amount(BigInt(apiReceipt.votes), 18),
-    }));
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to fetch user vote receipt: ${message}`);
+  if (!anyChainAcknowledged) {
+    throw new GovernorNotFoundError(notFoundChainIds[0] ?? 0, proposalId);
   }
+
+  if (collected.length === 0) {
+    return [
+      {
+        chainId: environment.chainId,
+        proposalId,
+        account: userAddress,
+        voted: false,
+        option: 0,
+        votes: new Amount(0, 18),
+      },
+    ];
+  }
+
+  return collected.map((apiReceipt) => ({
+    chainId: apiReceipt.chainId,
+    proposalId,
+    account: userAddress,
+    voted: true,
+    option: apiReceipt.voteValue,
+    votes: new Amount(BigInt(apiReceipt.votes), 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;
+}