@moonwell-fi/moonwell-sdk 0.13.0 → 0.14.0

package/actions/governance/governor-api-client.ts

@@ -1,14 +1,81 @@
+import axios from "axios";
 import type { Environment } from "../../environments/index.js";
 import { getWithRetry } from "../axiosWithRetry.js";
 
 /**
  * Base configuration for Governor API requests
- * The Governor API is the new governance indexer, accessed via governanceIndexerUrl
+ * The Governor API is the multigov governance indexer, accessed via governanceIndexerUrl
  */
 const getGovernorApiUrl = (environment: Environment): string => {
   return environment.governanceIndexerUrl;
 };
 
+/**
+ * Chains the governor indexer serves. Ethereum first because that's where the
+ * active multigov contract lives; Moonbeam follows for the historical archive.
+ */
+export const SUPPORTED_GOVERNOR_CHAIN_IDS = [1, 1284] as const;
+
+/**
+ * Build the chain-prefixed proposal key the indexer requires
+ * (e.g. chainId=1, proposalId=7 → "1-0000000007").
+ */
+export const buildProposalKey = (
+  chainId: number,
+  proposalId: number | string,
+): string => `${chainId}-${String(proposalId).padStart(10, "0")}`;
+
+/**
+ * Thrown by proposal-scoped fetchers when the indexer reports the proposal
+ * doesn't exist (HTTP 404). Callers use `isNotFoundError` to drive chainId
+ * fallback without misclassifying a real 5xx outage as "not found".
+ */
+export class GovernorNotFoundError extends Error {
+  public readonly chainId: number;
+  public readonly proposalId: number | string;
+  constructor(chainId: number, proposalId: number | string) {
+    super(
+      `Governor resource not found for chainId=${chainId}, proposalId=${proposalId}`,
+    );
+    this.name = "GovernorNotFoundError";
+    this.chainId = chainId;
+    this.proposalId = proposalId;
+  }
+}
+
+export const isNotFoundError = (error: unknown): boolean => {
+  if (error instanceof GovernorNotFoundError) return true;
+  return axios.isAxiosError(error) && error.response?.status === 404;
+};
+
+/**
+ * Wraps a proposal-scoped fetch: if the underlying axios call surfaces a 404,
+ * throws a typed `GovernorNotFoundError` so callers can distinguish missing
+ * resources from real outages. Other failures (5xx, non-200, network) propagate
+ * as-is.
+ */
+async function fetchProposalScoped<T>(
+  url: string,
+  chainId: number,
+  proposalId: number | string,
+  resourceLabel: string,
+): Promise<T> {
+  try {
+    const response = await getWithRetry<T>(url);
+    if (response.status !== 200 || !response.data) {
+      throw new Error(
+        `Failed to fetch ${resourceLabel}: ${response.statusText}`,
+      );
+    }
+    return response.data;
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.status === 404) {
+      throw new GovernorNotFoundError(chainId, proposalId);
+    }
+    throw error;
+  }
+}
+
 /**
  * Paginated response type
  */
@@ -94,19 +161,26 @@ export type ApiVoteReceipt = {
   timestamp: number;
 };
 
+export type FetchProposalsOptions = PaginationOptions & {
+  chainId: number;
+};
+
 /**
  * Fetch proposals from Governor API
+ *
+ * `chainId` is required by the indexer — 1 (Ethereum multigov) or
+ * 1284 (Moonbeam historical). Missing/unsupported chainId returns 400.
  */
 export async function fetchProposals(
   environment: Environment,
-  options?: PaginationOptions & { chainId?: number },
+  options: FetchProposalsOptions,
 ): Promise<PaginatedResponse<ApiProposal>> {
   const baseUrl = getGovernorApiUrl(environment);
   const params = new URLSearchParams();
 
-  if (options?.limit) params.append("limit", options.limit.toString());
-  if (options?.cursor) params.append("cursor", options.cursor);
-  if (options?.chainId) params.append("chainId", options.chainId.toString());
+  params.append("chainId", options.chainId.toString());
+  if (options.limit) params.append("limit", options.limit.toString());
+  if (options.cursor) params.append("cursor", options.cursor);
 
   const response = await getWithRetry<PaginatedResponse<ApiProposal>>(
     `${baseUrl}/api/v1/governor/proposals?${params.toString()}`,
@@ -120,20 +194,20 @@ export async function fetchProposals(
 }
 
 /**
- * Fetch all proposals (handles pagination internally)
+ * Fetch all proposals for a given chainId (handles pagination internally)
  */
 export async function fetchAllProposals(
   environment: Environment,
-  options?: { chainId?: number },
+  options: { chainId: number },
 ): Promise<ApiProposal[]> {
   const allProposals: ApiProposal[] = [];
   let cursor: string | undefined = undefined;
 
   do {
     const response = await fetchProposals(environment, {
+      chainId: options.chainId,
       limit: 1000,
       ...(cursor && { cursor }),
-      ...(options?.chainId && { chainId: options.chainId }),
     });
 
     allProposals.push(...response.results);
@@ -148,19 +222,17 @@ export async function fetchAllProposals(
  */
 export async function fetchProposal(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
 ): Promise<ApiProposal> {
   const baseUrl = getGovernorApiUrl(environment);
-
-  const response = await getWithRetry<ApiProposal>(
-    `${baseUrl}/api/v1/governor/proposals/${proposalId}`,
+  const key = buildProposalKey(chainId, proposalId);
+  return fetchProposalScoped<ApiProposal>(
+    `${baseUrl}/api/v1/governor/proposals/${key}`,
+    chainId,
+    proposalId,
+    "proposal",
   );
-
-  if (response.status !== 200 || !response.data) {
-    throw new Error(`Failed to fetch proposal: ${response.statusText}`);
-  }
-
-  return response.data;
 }
 
 /**
@@ -168,24 +240,23 @@ export async function fetchProposal(
  */
 export async function fetchProposalVotes(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
   options?: PaginationOptions,
 ): Promise<PaginatedResponse<ApiVote>> {
   const baseUrl = getGovernorApiUrl(environment);
+  const key = buildProposalKey(chainId, proposalId);
   const params = new URLSearchParams();
 
   if (options?.limit) params.append("limit", options.limit.toString());
   if (options?.cursor) params.append("cursor", options.cursor);
 
-  const response = await getWithRetry<PaginatedResponse<ApiVote>>(
-    `${baseUrl}/api/v1/governor/proposals/${proposalId}/votes?${params.toString()}`,
+  return fetchProposalScoped<PaginatedResponse<ApiVote>>(
+    `${baseUrl}/api/v1/governor/proposals/${key}/votes?${params.toString()}`,
+    chainId,
+    proposalId,
+    "proposal votes",
   );
-
-  if (response.status !== 200 || !response.data) {
-    throw new Error(`Failed to fetch proposal votes: ${response.statusText}`);
-  }
-
-  return response.data;
 }
 
 /**
@@ -193,16 +264,22 @@ export async function fetchProposalVotes(
  */
 export async function fetchAllProposalVotes(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
 ): Promise<ApiVote[]> {
   const allVotes: ApiVote[] = [];
   let cursor: string | undefined = undefined;
 
   do {
-    const response = await fetchProposalVotes(environment, proposalId, {
-      limit: 1000,
-      ...(cursor && { cursor }),
-    });
+    const response = await fetchProposalVotes(
+      environment,
+      chainId,
+      proposalId,
+      {
+        limit: 1000,
+        ...(cursor && { cursor }),
+      },
+    );
 
     allVotes.push(...response.results);
     cursor = response.nextCursor;
@@ -216,28 +293,23 @@ export async function fetchAllProposalVotes(
  */
 export async function fetchProposalStateChanges(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
   options?: PaginationOptions,
 ): Promise<PaginatedResponse<ApiProposalStateChange>> {
   const baseUrl = getGovernorApiUrl(environment);
+  const key = buildProposalKey(chainId, proposalId);
   const params = new URLSearchParams();
 
   if (options?.limit) params.append("limit", options.limit.toString());
   if (options?.cursor) params.append("cursor", options.cursor);
 
-  const response = await getWithRetry<
-    PaginatedResponse<ApiProposalStateChange>
-  >(
-    `${baseUrl}/api/v1/governor/proposals/${proposalId}/state-changes?${params.toString()}`,
+  return fetchProposalScoped<PaginatedResponse<ApiProposalStateChange>>(
+    `${baseUrl}/api/v1/governor/proposals/${key}/state-changes?${params.toString()}`,
+    chainId,
+    proposalId,
+    "proposal state changes",
   );
-
-  if (response.status !== 200 || !response.data) {
-    throw new Error(
-      `Failed to fetch proposal state changes: ${response.statusText}`,
-    );
-  }
-
-  return response.data;
 }
 
 /**
@@ -245,16 +317,22 @@ export async function fetchProposalStateChanges(
  */
 export async function fetchAllProposalStateChanges(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
 ): Promise<ApiProposalStateChange[]> {
   const allStateChanges: ApiProposalStateChange[] = [];
   let cursor: string | undefined = undefined;
 
   do {
-    const response = await fetchProposalStateChanges(environment, proposalId, {
-      limit: 1000,
-      ...(cursor && { cursor }),
-    });
+    const response = await fetchProposalStateChanges(
+      environment,
+      chainId,
+      proposalId,
+      {
+        limit: 1000,
+        ...(cursor && { cursor }),
+      },
+    );
 
     allStateChanges.push(...response.results);
     cursor = response.nextCursor;
@@ -447,20 +525,16 @@ export async function fetchAllVoterVotes(
  */
 export async function fetchUserVoteReceipt(
   environment: Environment,
-  proposalId: string,
+  chainId: number,
+  proposalId: number | string,
   voterAddress: string,
 ): Promise<ApiVoteReceipt[]> {
   const baseUrl = getGovernorApiUrl(environment);
-
-  const response = await getWithRetry<ApiVoteReceipt[]>(
-    `${baseUrl}/api/v1/governor/proposals/${proposalId}/vote/${voterAddress}`,
+  const key = buildProposalKey(chainId, proposalId);
+  return fetchProposalScoped<ApiVoteReceipt[]>(
+    `${baseUrl}/api/v1/governor/proposals/${key}/vote/${voterAddress}`,
+    chainId,
+    proposalId,
+    "user vote receipt",
   );
-
-  if (response.status !== 200 || !response.data) {
-    throw new Error(
-      `Failed to fetch user vote receipt: ${response.statusText}`,
-    );
-  }
-
-  return response.data;
 }

package/actions/governance/proposals/common.ts

@@ -7,7 +7,7 @@ import { publicEnvironments } from "../../../environments/index.js";
 import {
   MultichainProposalStateMapping,
   type Proposal,
-  type ProposalState,
+  ProposalState,
 } from "../../../types/proposal.js";
 import { postWithRetry } from "../../axiosWithRetry.js";
 import type { ApiProposal } from "../governor-api-client.js";
@@ -134,6 +134,35 @@ export type ApiProposalFormatted = {
   subtitle: string;
 };
 
+/**
+ * Derive a ProposalState value from API data alone (no on-chain read).
+ *
+ * Used for proposals whose chainId doesn't match the governance environment's
+ * chainId — e.g. chainId=1 (Ethereum multigov) proposals reached through the
+ * Moonbeam governance environment, where on-chain reads against Moonbeam's
+ * governor would be meaningless.
+ *
+ * Precedence (highest wins): Executed → Canceled → Queued → Active → Pending.
+ * Executed wins over Canceled because the SDK treats EXECUTED state changes as
+ * the terminal truth even when an earlier CANCELED event is present.
+ */
+export const deriveProposalStateFromApi = (
+  formatted: ApiProposalFormatted,
+  apiProposal: ApiProposal,
+  now: number,
+): ProposalState => {
+  if (formatted.executed) return ProposalState.Executed;
+  if (formatted.canceled) return ProposalState.Canceled;
+  const hasQueued = apiProposal.stateChanges?.some(
+    (sc) => sc.state === "QUEUED",
+  );
+  if (hasQueued) return ProposalState.Queued;
+  if (now >= apiProposal.votingStartTime && now <= apiProposal.votingEndTime) {
+    return ProposalState.Active;
+  }
+  return ProposalState.Pending;
+};
+
 /**
  * Parses and formats API proposal data
  */
@@ -255,8 +284,25 @@ export const getProposalsOnChainData = async (
 
   const legacyArtemisMaxId = await getLegacyArtemisMaxId(governanceEnvironment);
 
+  const nowSeconds = Math.floor(Date.now() / 1000);
+
   const onChainDataList = await Promise.all(
     apiProposals.map(async (p) => {
+      // Proposals from a different chain than the governance env (e.g. chainId=1
+      // Ethereum proposals fetched through the Moonbeam env) can't be read from
+      // this env's contracts — derive state from API events here so callers
+      // never see a misleading `state: 0` default for finalized proposals.
+      if (p.chainId !== governanceEnvironment.chainId) {
+        const formatted = formatApiProposalData(p);
+        return {
+          state: deriveProposalStateFromApi(formatted, p, nowSeconds),
+          proposalData: null,
+          eta: 0,
+          votesCollected: false,
+          quorum: 0n,
+        };
+      }
+
       const isMultichain = isMultichainAware(p, legacyArtemisMaxId);
 
       const governorContract = isMultichain
@@ -296,6 +342,10 @@ export const getProposalsOnChainData = async (
 
   const votesCollectedList = await Promise.all(
     apiProposals.map(async (apiProposal) => {
+      if (apiProposal.chainId !== governanceEnvironment.chainId) {
+        return false;
+      }
+
       const isMultichain = isMultichainAware(apiProposal, legacyArtemisMaxId);
 
       if (

package/actions/governance/proposals/getProposal.ts

@@ -3,8 +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 { Chain, Environment } from "../../../environments/index.js";
-import type { Proposal } from "../../../types/proposal.js";
-import { fetchProposal } from "../governor-api-client.js";
+import { type Proposal, ProposalState } from "../../../types/proposal.js";
+import {
+  type ApiProposal,
+  SUPPORTED_GOVERNOR_CHAIN_IDS,
+  fetchProposal,
+  isNotFoundError,
+} from "../governor-api-client.js";
 import {
   appendProposalExtendedData,
   formatApiProposalData,
@@ -20,6 +25,11 @@ export type GetProposalParameters<
   network extends Chain | undefined,
 > = NetworkParameterType<environments, network> & {
   proposalId: number;
+  /**
+   * The chain the proposal lives on (1 = Ethereum multigov,
+   * 1284 = Moonbeam historical). When omitted, both are tried in turn.
+   */
+  chainId?: number;
 };
 
 export type GetProposalReturnType = Promise<Proposal | undefined>;
@@ -45,33 +55,41 @@ export async function getProposal<
     return undefined;
   }
 
-  try {
-    if (environment.chainId === moonbeam.id) {
-      // Moonbeam: Use new Governor API
-      return await getMoonbeamProposal(environment, proposalId);
-    } else {
-      // Moonriver: Use old Ponder approach
-      return await getMoonriverProposal(environment, proposalId);
-    }
-  } catch (error) {
-    console.error(
-      `[getProposal] Error fetching proposal ${proposalId}:`,
-      error,
-    );
-    return undefined;
+  if (environment.chainId === moonbeam.id) {
+    return getMoonbeamProposal(environment, proposalId, args.chainId);
   }
+  return getMoonriverProposal(environment, proposalId);
 }
 
 /**
- * Fetch a single proposal for Moonbeam using the new Governor API
+ * Fetch a single proposal for Moonbeam using the Governor API.
+ *
+ * When `chainId` is provided we hit only that chain. When omitted we try the
+ * supported chains in order (Ethereum first since that's where active multigov
+ * proposals live) and fall back on `NotFoundError`. Real outages (5xx, network
+ * errors) propagate so callers can distinguish "missing" from "broken".
  */
 async function getMoonbeamProposal(
   governanceEnvironment: Environment,
   proposalId: number,
+  chainId?: number,
 ): Promise<Proposal | undefined> {
-  const apiProposalId = `${proposalId}`;
+  const tryChains = chainId ? [chainId] : SUPPORTED_GOVERNOR_CHAIN_IDS;
+
+  let apiProposal: ApiProposal | undefined;
+  for (const cid of tryChains) {
+    try {
+      apiProposal = await fetchProposal(governanceEnvironment, cid, proposalId);
+      break;
+    } catch (error) {
+      if (isNotFoundError(error)) continue;
+      throw error;
+    }
+  }
 
-  const apiProposal = await fetchProposal(governanceEnvironment, apiProposalId);
+  if (!apiProposal) {
+    return undefined;
+  }
 
   const formattedData = formatApiProposalData(apiProposal);
   const onChainDataList = await getProposalsOnChainData(
@@ -79,29 +97,31 @@ async function getMoonbeamProposal(
     governanceEnvironment,
   );
   const onChainData = onChainDataList[0]!;
-
   const isMultichain = isMultichainProposal(apiProposal.targets);
 
-  let proposalState = onChainData.state;
+  // For cross-chain proposals, onChainData.state is already API-derived inside
+  // getProposalsOnChainData, so the post-processing below acts as a no-op
+  // (votesCollected is false and the derived state is already terminal).
   const now = Math.floor(Date.now() / 1000);
+  let proposalState = onChainData.state;
 
   if (
-    proposalState === 0 &&
+    proposalState === ProposalState.Pending &&
     now >= apiProposal.votingStartTime &&
     now <= apiProposal.votingEndTime
   ) {
-    proposalState = 1; // Active
+    proposalState = ProposalState.Active;
   }
 
   if (formattedData.executed) {
-    proposalState = 7; // ProposalState.Executed
+    proposalState = ProposalState.Executed;
   } else if (
     isMultichain &&
     onChainData.votesCollected &&
     now > apiProposal.votingEndTime &&
-    proposalState < 5
+    proposalState < ProposalState.Queued
   ) {
-    proposalState = 5; // ProposalState.Queued
+    proposalState = ProposalState.Queued;
   }
 
   const proposal: Proposal = {

package/actions/governance/proposals/getProposals.ts

@@ -4,8 +4,8 @@ import { Amount, getEnvironmentsFromArgs } from "../../../common/index.js";
 import type { OptionalNetworkParameterType } from "../../../common/types.js";
 import type { Chain, Environment } from "../../../environments/index.js";
 import * as logger from "../../../logger/console.js";
-import type { Proposal } from "../../../types/proposal.js";
-import { fetchAllProposals } from "../governor-api-client.js";
+import { type Proposal, ProposalState } from "../../../types/proposal.js";
+import { type ApiProposal, fetchAllProposals } from "../governor-api-client.js";
 import {
   appendProposalExtendedData,
   formatApiProposalData,
@@ -58,7 +58,14 @@ export async function getProposals<
   );
 
   const proposals = allProposals.flat();
-  const sortedProposals = proposals.sort((a, b) => b.proposalId - a.proposalId);
+  // Newer multigov-ethereum proposals (chainId=1) and historical Moonbeam
+  // proposals (chainId=1284) restart their proposalId counters from 1, so IDs
+  // may collide across chains. Sort by proposalId desc with chainId as a
+  // stable tiebreaker (smaller chainId — Ethereum — wins).
+  const sortedProposals = proposals.sort((a, b) => {
+    if (b.proposalId !== a.proposalId) return b.proposalId - a.proposalId;
+    return a.chainId - b.chainId;
+  });
 
   logger.end(logId);
 
@@ -66,12 +73,36 @@ export async function getProposals<
 }
 
 /**
- * Fetch proposals for Moonbeam using the new Governor API
+ * Fetch proposals for Moonbeam using the Governor API.
+ *
+ * The same indexer DO serves two chains:
+ *   - chainId=1 (Ethereum) — the active multigov contract
+ *   - chainId=1284 (Moonbeam) — historical proposals
+ *
+ * Uses `Promise.allSettled` so a transient outage on one chain doesn't take
+ * down the other — partial results are preferred over a hard failure.
  */
 async function getMoonbeamProposals(
   governanceEnvironment: Environment,
 ): Promise<Proposal[]> {
-  const apiProposals = await fetchAllProposals(governanceEnvironment);
+  const results = await Promise.allSettled([
+    fetchAllProposals(governanceEnvironment, { chainId: 1 }),
+    fetchAllProposals(governanceEnvironment, { chainId: 1284 }),
+  ]);
+
+  const chainsAttempted: ReadonlyArray<1 | 1284> = [1, 1284];
+  const apiProposals: ApiProposal[] = [];
+  results.forEach((result, index) => {
+    if (result.status === "fulfilled") {
+      apiProposals.push(...result.value);
+    } else {
+      console.warn(
+        `[getProposals] Failed to fetch proposals for chainId=${chainsAttempted[index]}; continuing with remaining chains.`,
+        result.reason,
+      );
+    }
+  });
+
   const onChainDataList = await getProposalsOnChainData(
     apiProposals,
     governanceEnvironment,
@@ -79,31 +110,34 @@ async function getMoonbeamProposals(
 
   const proposals: Proposal[] = apiProposals.map((apiProposal, index) => {
     const onChainData = onChainDataList[index]!;
-
     const formattedData = formatApiProposalData(apiProposal);
+    const isMultichain = isMultichainProposal(apiProposal.targets);
 
-    let proposalState = onChainData.state;
+    // `onChainData.state` is already API-derived for cross-chain proposals
+    // (handled inside getProposalsOnChainData), so the post-processing below
+    // is a no-op for them — derived states already reflect executed/canceled/
+    // queued/active/pending, and votesCollected is false so the Queued branch
+    // never fires.
     const now = Math.floor(Date.now() / 1000);
+    let proposalState = onChainData.state;
 
     if (
-      proposalState === 0 &&
+      proposalState === ProposalState.Pending &&
       now >= apiProposal.votingStartTime &&
       now <= apiProposal.votingEndTime
     ) {
-      proposalState = 1; // Active
+      proposalState = ProposalState.Active;
     }
 
-    const isMultichain = isMultichainProposal(apiProposal.targets);
-
     if (formattedData.executed) {
-      proposalState = 7; // ProposalState.Executed
+      proposalState = ProposalState.Executed;
     } else if (
       isMultichain &&
       onChainData.votesCollected &&
       now > apiProposal.votingEndTime &&
-      proposalState < 5
+      proposalState < ProposalState.Queued
     ) {
-      proposalState = 5; // ProposalState.Queued
+      proposalState = ProposalState.Queued;
     }
 
     const proposal: Proposal = {

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

@@ -12,6 +12,7 @@ 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
@@ -164,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