@moonwell-fi/moonwell-sdk 0.21.0 → 0.22.0

package/actions/governance/getDelegates.ts

@@ -1,5 +1,5 @@
 import { isAddress } from "viem";
-import { base, mainnet, moonbeam, optimism } from "viem/chains";
+import { base, mainnet, optimism } from "viem/chains";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
 import {
   type Environment,
@@ -23,17 +23,17 @@ export async function getDelegates(
 ): GetDelegatesReturnType {
   const logId = logger.start("getDelegates", "Starting to get delegates...");
 
-  const governanceEnvironment = publicEnvironments.moonbeam;
+  // Any environment resolves the same `governanceIndexerUrl`; the Ethereum hub
+  // replaces Moonbeam here now that the sunset chain is gone (MOO-551).
+  const governanceEnvironment = publicEnvironments.ethereum;
 
   const apiVoters = await fetchAllVoters(governanceEnvironment);
   const forumProfiles = await getForumProfiles();
 
-  const targetChainIds = [
-    moonbeam.id,
-    base.id,
-    optimism.id,
-    mainnet.id,
-  ] as const;
+  // Moonbeam dropped with the sunset: the chain is halted, so it can no longer
+  // serve `getUserVotingPower`. Delegate totals therefore no longer include any
+  // WELL that remained on Moonbeam.
+  const targetChainIds = [base.id, optimism.id, mainnet.id] as const;
   const envs = Object.values(client.environments as Environment[]).filter(
     (env) =>
       env.contracts.views !== undefined &&

package/actions/governance/getGovernanceTokenInfo.ts

@@ -19,6 +19,8 @@ export type GetGovernanceTokenInfoReturnType = Promise<
 
 export async function getGovernanceTokenInfo(
   _client: MoonwellClient,
+  // Retained for API compatibility, but WELL is the only governance token left
+  // now that MFAM went with Moonriver (MOO-551), so there is nothing to branch on.
   args: GetGovernanceTokenInfoParameters,
 ): GetGovernanceTokenInfoReturnType {
   const logId = logger.start(
@@ -26,22 +28,28 @@ export async function getGovernanceTokenInfo(
     "Starting to get governance token info...",
   );
 
-  if (args.governanceToken === "WELL") {
-    const totalSupply =
-      await publicEnvironments.moonbeam.contracts.governanceToken.read.totalSupply();
-
+  // TypeScript already narrows `GovernanceToken` to "WELL", but a JS consumer
+  // still passing "MFAM" would otherwise receive WELL's supply as a normal
+  // success — silently wrong data where TS consumers get a compile error.
+  // Reject it rather than let the removed token look like it still resolves.
+  if (args.governanceToken !== undefined && args.governanceToken !== "WELL") {
     logger.end(logId);
+    throw new Error(
+      `Unsupported governance token "${args.governanceToken}". MFAM was removed with the Moonriver sunset (MOO-551); WELL is the only governance token.`,
+    );
+  }
 
-    return {
-      totalSupply: new Amount(totalSupply || 0n, 18),
-    };
-  } else {
-    const totalSupply =
-      await publicEnvironments.moonriver.contracts.governanceToken.read.totalSupply();
+  // WELL supply used to be read from Moonbeam, the original mint. That chain is
+  // halted (MOO-551), so the read now targets the Ethereum multigov hub — the
+  // home of live governance. Note this reports the hub's xWELL supply rather
+  // than Moonbeam's historical total, so the number can differ from pre-sunset
+  // releases. MFAM is gone entirely: Apollo governance ended with Moonriver.
+  const totalSupply =
+    await publicEnvironments.ethereum.contracts.governanceToken.read.totalSupply();
 
-    logger.end(logId);
-    return {
-      totalSupply: new Amount(totalSupply || 0n, 18),
-    };
-  }
+  logger.end(logId);
+
+  return {
+    totalSupply: new Amount(totalSupply || 0n, 18),
+  };
 }

package/actions/governance/getUserVoteReceipt.ts

@@ -1,7 +1,8 @@
 import type { Address, Chain } from "viem";
 import type { MoonwellClient } from "../../client/createMoonwellClient.js";
-import { Amount, getEnvironmentFromArgs } from "../../common/index.js";
+import { Amount } from "../../common/index.js";
 import type { NetworkParameterType } from "../../common/types.js";
+import type { Environment } from "../../environments/index.js";
 import type { VoteReceipt } from "../../types/voteReceipt.js";
 import {
   type ApiVoteReceipt,
@@ -10,6 +11,7 @@ import {
   fetchUserVoteReceipt,
   isNotFoundError,
 } from "./governor-api-client.js";
+import { resolveGovernanceEnvironment } from "./proposals/common.js";
 
 export type GetUserVoteReceiptParameters<
   environments,
@@ -50,8 +52,17 @@ export async function getUserVoteReceipt<
 ): GetUserVoteReceiptReturnType {
   const { proposalId, userAddress, chainId } = args;
 
-  const environment = getEnvironmentFromArgs(client, args);
-  if (!environment) {
+  // `args.chainId` identifies the chain the PROPOSAL lives on, not the
+  // environment we read through — the same distinction `getProposal` draws
+  // (MOO-551). Resolving the environment from it meant an archive lookup
+  // (1284/1285) matched no registered environment post-sunset and returned `[]`,
+  // a third shape callers don't handle: every historical vote read as "didn't
+  // vote". Resolve the indexer source independently and pass `chainId` through
+  // untouched.
+  const governanceEnvironment = resolveGovernanceEnvironment(
+    Object.values(client.environments as Record<string, Environment>),
+  );
+  if (!governanceEnvironment) {
     return [];
   }
 
@@ -64,7 +75,7 @@ export async function getUserVoteReceipt<
   for (const cid of tryChains) {
     try {
       const apiVoteReceipts = await fetchUserVoteReceipt(
-        environment,
+        governanceEnvironment,
         cid,
         proposalId,
         userAddress,
@@ -87,7 +98,10 @@ export async function getUserVoteReceipt<
   if (collected.length === 0) {
     return [
       {
-        chainId: environment.chainId,
+        // An explicit request names the chain the stub is about; a bare lookup
+        // queried every supported chain, so the source we read through is the
+        // only chain it can honestly claim.
+        chainId: chainId ?? governanceEnvironment.chainId,
         proposalId,
         account: userAddress,
         voted: false,

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

@@ -15,11 +15,20 @@ const getGovernorApiUrl = (environment: Environment): string => {
  * active multigov contract lives; Moonbeam follows for the historical archive,
  * then Moonriver (legacy standalone governor).
  *
- * This is the fan-out set for `getUserVoteReceipt` — a bare proposalId is
- * queried on every chain and non-empty receipts are concatenated. Do NOT use it
- * as the single-proposal fallback in `getProposal`: Moonriver has its own
- * explicit route there, and reaching a 1285 proposal through a Moonbeam env
- * would surface a degraded result (see `MULTIGOV_PROPOSAL_FALLBACK_CHAIN_IDS`).
+ * The fan-out set for two consumers: `getUserVoteReceipt` (a bare proposalId is
+ * queried on every chain and non-empty receipts are concatenated) and
+ * `getProposals` (every chain's list is fetched and merged, so the archive stays
+ * listable after the sunset).
+ *
+ * Since MOO-551 no Moonbeam/Moonriver environment exists, so 1284 and 1285 are
+ * served through whichever governance environment resolved — reporting
+ * `quorum: 0` and no `eta` because nothing on-chain can be read for a halted
+ * chain. That degradation is the accepted post-sunset design here, not a bug.
+ *
+ * Still do NOT use this set as the *single-proposal* fallback in `getProposal`:
+ * a bare lookup must not silently resolve to a 1285 proposal it wasn't asked
+ * for — that stays an explicit `chainId` route (see
+ * `MULTIGOV_PROPOSAL_FALLBACK_CHAIN_IDS`).
  */
 export const SUPPORTED_GOVERNOR_CHAIN_IDS = [1, 1284, 1285] as const;
 

package/actions/governance/proposals/common.ts

@@ -1,10 +1,12 @@
 import axios from "axios";
+import { mainnet } from "viem/chains";
 import { Amount } from "../../../common/index.js";
 import type { Environment } from "../../../environments/index.js";
 import { publicEnvironments } from "../../../environments/index.js";
 import {
   MultichainProposalState,
   MultichainProposalStateMapping,
+  type Proposal,
   ProposalState,
 } from "../../../types/proposal.js";
 import type { ApiProposal } from "../governor-api-client.js";
@@ -176,14 +178,24 @@ export type ApiProposalFormatted = {
 /**
  * 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.
+ * Used for proposals whose chainId has no resolvable environment, or whose
+ * on-chain state read failed. Since the sunset (MOO-551) this is the permanent
+ * — not transient — route for every Moonbeam (1284) and Moonriver (1285)
+ * proposal, because no environment exists for those chains any more.
  *
- * Precedence (highest wins): Executed → Canceled → Queued → Active → Pending.
+ * Precedence (highest wins):
+ * Executed → Canceled → Queued → Active → Succeeded/Defeated → Pending.
  * Executed wins over Canceled because the SDK treats EXECUTED state changes as
  * the terminal truth even when an earlier CANCELED event is present.
+ *
+ * Once voting has closed with no terminal state change, the outcome is decided
+ * from the tallies. Without that branch every defeated archive proposal fell
+ * through to `Pending` and listed as perpetually pending — the pre-sunset
+ * Moonbeam governor read used to report the real `Defeated`. The tallies are
+ * the only signal available here: quorum needs an RPC and reports 0 for the
+ * archive, so a for-majority that missed quorum reads as Succeeded rather than
+ * Defeated. That is the same degradation quorum already carries, and it is
+ * strictly closer to the truth than Pending.
  */
 export const deriveProposalStateFromApi = (
   formatted: ApiProposalFormatted,
@@ -199,6 +211,11 @@ export const deriveProposalStateFromApi = (
   if (now >= apiProposal.votingStartTime && now <= apiProposal.votingEndTime) {
     return ProposalState.Active;
   }
+  if (now > apiProposal.votingEndTime) {
+    return formatted.forVotes.exponential > formatted.againstVotes.exponential
+      ? ProposalState.Succeeded
+      : ProposalState.Defeated;
+  }
   return ProposalState.Pending;
 };
 
@@ -332,6 +349,26 @@ export const getEnvironmentByChainId = (
     (e) => e.chainId === chainId,
   );
 
+/**
+ * The environment that drives Governor-API reads for the whole proposal surface.
+ *
+ * Before the sunset this was the caller's Moonbeam/Moonriver environment, and
+ * both `getProposals` and `getProposal` gated on one of those being registered.
+ * Those chains are gone (MOO-551), so governance is now homed on the Ethereum
+ * multigov hub. Every environment resolves the same `governanceIndexerUrl`, so
+ * any registered chain can serve the indexer — Ethereum is merely preferred
+ * because its `multichainGovernor` also answers the live quorum/state reads.
+ *
+ * Consequence for the historical archive: Moonbeam (1284) and Moonriver (1285)
+ * proposals still list, because the indexer keeps serving them, but nothing
+ * on-chain can be read for them any more. They surface with indexer-derived
+ * state and no quorum or eta — see `getProposalsOnChainData`'s `!homeEnv` path.
+ */
+export const resolveGovernanceEnvironment = (
+  environments: Environment[],
+): Environment | undefined =>
+  environments.find((e) => e.chainId === mainnet.id) ?? environments[0];
+
 export const readCrossChainQuorums = async (
   apiProposals: ApiProposal[],
   governanceEnvironment: Environment,
@@ -376,12 +413,18 @@ export const getProposalsOnChainData = async (
 ): Promise<ProposalOnChainData[]> => {
   let quorum = 0n;
 
-  if (governanceEnvironment.contracts.governor) {
+  // The governance environment is now the Ethereum multigov hub (MOO-551), which
+  // has a `multichainGovernor` and no legacy `governor`. Read whichever the env
+  // actually wires, otherwise a hub-local proposal would report quorum 0.
+  const localQuorumRead = governanceEnvironment.contracts.governor
+    ? () => governanceEnvironment.contracts.governor?.read.getQuorum()
+    : governanceEnvironment.contracts.multichainGovernor
+      ? () => governanceEnvironment.contracts.multichainGovernor?.read.quorum()
+      : undefined;
+
+  if (localQuorumRead) {
     try {
-      quorum =
-        governanceEnvironment.chainId === 1284
-          ? await governanceEnvironment.contracts.governor.read.quorumVotes()
-          : await governanceEnvironment.contracts.governor.read.getQuorum();
+      quorum = (await localQuorumRead()) ?? 0n;
     } catch (error) {
       console.warn("Failed to fetch quorum:", error);
       // Report so a swallowed quorum failure (which leaves quorum at 0n) is
@@ -571,3 +614,93 @@ export const getProposalsOnChainData = async (
 
   return onChainDataList;
 };
+
+/**
+ * Map an indexer proposal plus its on-chain data onto the public `Proposal`.
+ *
+ * `getProposal` and `getProposals` both used to carry their own copy of this
+ * block, and both carried a comment warning the other not to drift from it —
+ * jscpd measured 69 duplicated lines between them. One implementation removes
+ * the drift risk those comments were describing.
+ */
+export const mapApiProposalToProposal = (
+  apiProposal: ApiProposal,
+  onChainData: ProposalOnChainData,
+  governanceEnvironment: Environment,
+): Proposal => {
+  const formattedData = formatApiProposalData(apiProposal);
+  // getProposalsOnChainData already classified this proposal and routed its
+  // reads accordingly; re-classifying here would drift and drop `multichain`.
+  const isMultichain = onChainData.isMultichain;
+
+  const now = Math.floor(Date.now() / 1000);
+  let proposalState = onChainData.state;
+
+  if (
+    proposalState === ProposalState.Pending &&
+    now >= apiProposal.votingStartTime &&
+    now <= apiProposal.votingEndTime
+  ) {
+    proposalState = ProposalState.Active;
+  }
+
+  if (formattedData.executed) {
+    proposalState = ProposalState.Executed;
+  } else if (
+    isMultichain &&
+    onChainData.votesCollected &&
+    now > apiProposal.votingEndTime &&
+    proposalState === ProposalState.Succeeded
+  ) {
+    // Succeeded with collection done means "awaiting execution" — surface as
+    // Queued so the frontend renders the "Ready to Execute" timeline step.
+    // Defeated/Canceled/Executed must NOT be promoted: under the
+    // state-machine-based votesCollected those terminal states also satisfy
+    // `votesCollected: true`, so a `< Queued` gate would mislabel them.
+    proposalState = ProposalState.Queued;
+  }
+
+  const proposal: Proposal = {
+    id: apiProposal.proposalId,
+    chainId: apiProposal.chainId,
+    proposalId: apiProposal.proposalId,
+    proposer: apiProposal.proposer as `0x${string}`,
+    eta: onChainData.eta,
+    startTimestamp: apiProposal.votingStartTime,
+    endTimestamp: apiProposal.votingEndTime,
+    startBlock: Number(apiProposal.blockNumber),
+    forVotes: formattedData.forVotes,
+    againstVotes: formattedData.againstVotes,
+    abstainVotes: formattedData.abstainVotes,
+    totalVotes: formattedData.totalVotes,
+    canceled: formattedData.canceled,
+    executed: formattedData.executed,
+    quorum: new Amount(onChainData.quorum, 18),
+    state: proposalState,
+    // Extended data
+    title: formattedData.title,
+    subtitle: formattedData.subtitle,
+    description: apiProposal.description,
+    targets: apiProposal.targets,
+    calldatas: apiProposal.calldatas,
+    // Legacy-governor proposals (Moonriver, early Moonbeam) carry the function
+    // signature separately from the selector-less calldata; pass it through so
+    // consumers can decode the call. Empty for multichain-governor proposals.
+    signatures: apiProposal.signatures ?? [],
+    stateChanges: formattedData.stateChanges,
+    environment: governanceEnvironment,
+  };
+
+  if (apiProposal.snapshotBlocks) {
+    proposal.snapshotBlocks = apiProposal.snapshotBlocks;
+  }
+
+  if (isMultichain) {
+    proposal.multichain = {
+      id: apiProposal.proposalId,
+      votesCollected: onChainData.votesCollected,
+    };
+  }
+
+  return proposal;
+};

package/actions/governance/proposals/getProposal.ts

@@ -1,9 +1,7 @@
-import { mainnet, moonbeam, moonriver } from "viem/chains";
 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, ProposalState } from "../../../types/proposal.js";
+import type { Proposal } from "../../../types/proposal.js";
 import {
   type ApiProposal,
   MULTIGOV_PROPOSAL_FALLBACK_CHAIN_IDS,
@@ -12,9 +10,10 @@ import {
 } from "../governor-api-client.js";
 import { resolveIpfsDescriptions } from "../ipfs.js";
 import {
-  formatApiProposalData,
   getProposalsOnChainData,
+  mapApiProposalToProposal,
   readCrossChainQuorums,
+  resolveGovernanceEnvironment,
 } from "./common.js";
 
 export type GetProposalParameters<
@@ -41,42 +40,24 @@ export async function getProposal<
 ): GetProposalReturnType {
   const { proposalId } = args;
 
-  const environment = getEnvironmentFromArgs(client, args);
-  if (!environment) {
-    return undefined;
-  }
-
-  // Ethereum-home multigov proposals are served by the same Governor API as
-  // historical Moonbeam ones (the lunar indexer fans out both chainIds), so
-  // route them through `getGovernorApiProposal` using the Moonbeam env as the
-  // indexer source. Without this, a caller resolving the env by `chainId: 1`
-  // would bail out on the `!moonbeam && !moonriver` check below and the page
-  // reload path returns undefined.
-  if (environment.chainId === mainnet.id) {
-    const moonbeamEnv = Object.values(
-      client.environments as Record<string, Environment>,
-    ).find((e) => e.chainId === moonbeam.id);
-    if (!moonbeamEnv) {
-      return undefined;
-    }
-    return getGovernorApiProposal(
-      moonbeamEnv,
-      proposalId,
-      args.chainId ?? mainnet.id,
-    );
-  }
-
-  if (
-    environment.chainId !== moonbeam.id &&
-    environment.chainId !== moonriver.id
-  ) {
+  // `args.chainId` identifies the chain the PROPOSAL lives on, which is no longer
+  // the same thing as the environment we read through. Before the sunset it was
+  // both, and the action resolved a Moonbeam/Moonriver environment from it —
+  // which now means a `chainId: 1284` lookup would resolve nothing and the whole
+  // historical archive would 404 (MOO-551). Resolve the indexer source
+  // independently and pass `chainId` through untouched.
+  const governanceEnvironment = resolveGovernanceEnvironment(
+    Object.values(client.environments as Record<string, Environment>),
+  );
+  if (!governanceEnvironment) {
     return undefined;
   }
 
-  if (environment.chainId === moonbeam.id) {
-    return getGovernorApiProposal(environment, proposalId, args.chainId);
-  }
-  return getGovernorApiProposal(environment, proposalId, moonriver.id);
+  return getGovernorApiProposal(
+    governanceEnvironment,
+    proposalId,
+    args.chainId,
+  );
 }
 
 /**
@@ -118,87 +99,23 @@ async function getGovernorApiProposal(
     readCrossChainQuorums([apiProposal], governanceEnvironment),
   ]);
 
-  const formattedData = formatApiProposalData(apiProposal);
   const onChainDataList = await getProposalsOnChainData(
     [apiProposal],
     governanceEnvironment,
     { crossChainQuorums },
   );
-  const onChainData = onChainDataList[0]!;
-  // Single source of truth: getProposalsOnChainData already classified this
-  // proposal with the caller env's Artemis cutoff and used it to route the
-  // on-chain reads. Reusing it avoids the drift that left Moonbeam-homed
-  // local-target proposals (and hub-local Ethereum ones) without `multichain`.
-  const isMultichain = onChainData.isMultichain;
-
-  const now = Math.floor(Date.now() / 1000);
-  let proposalState = onChainData.state;
 
-  if (
-    proposalState === ProposalState.Pending &&
-    now >= apiProposal.votingStartTime &&
-    now <= apiProposal.votingEndTime
-  ) {
-    proposalState = ProposalState.Active;
-  }
-
-  if (formattedData.executed) {
-    proposalState = ProposalState.Executed;
-  } else if (
-    isMultichain &&
-    onChainData.votesCollected &&
-    now > apiProposal.votingEndTime &&
-    proposalState === ProposalState.Succeeded
-  ) {
-    // Succeeded with collection done means "awaiting execution" — surface as
-    // Queued so the frontend renders the "Ready to Execute" timeline step.
-    // Defeated/Canceled/Executed must NOT be promoted: under the new
-    // state-machine-based votesCollected, those terminal states also satisfy
-    // `votesCollected: true`, so a `< Queued` gate would mislabel them.
-    proposalState = ProposalState.Queued;
-  }
-
-  const proposal: Proposal = {
-    id: apiProposal.proposalId,
-    chainId: apiProposal.chainId,
-    proposalId: apiProposal.proposalId,
-    proposer: apiProposal.proposer as `0x${string}`,
-    eta: onChainData.eta,
-    startTimestamp: apiProposal.votingStartTime,
-    endTimestamp: apiProposal.votingEndTime,
-    startBlock: Number(apiProposal.blockNumber),
-    forVotes: formattedData.forVotes,
-    againstVotes: formattedData.againstVotes,
-    abstainVotes: formattedData.abstainVotes,
-    totalVotes: formattedData.totalVotes,
-    canceled: formattedData.canceled,
-    executed: formattedData.executed,
-    quorum: new Amount(onChainData.quorum, 18),
-    state: proposalState,
-    // Extended data
-    title: formattedData.title,
-    subtitle: formattedData.subtitle,
-    description: apiProposal.description,
-    targets: apiProposal.targets,
-    calldatas: apiProposal.calldatas,
-    // Legacy-governor proposals (Moonriver, early Moonbeam) carry the function
-    // signature separately from the selector-less calldata; pass it through so
-    // consumers can decode the call. Empty for multichain-governor proposals.
-    signatures: apiProposal.signatures ?? [],
-    stateChanges: formattedData.stateChanges,
-    environment: governanceEnvironment,
-  };
-
-  if (apiProposal.snapshotBlocks) {
-    proposal.snapshotBlocks = apiProposal.snapshotBlocks;
-  }
-
-  if (isMultichain) {
-    proposal.multichain = {
-      id: apiProposal.proposalId,
-      votesCollected: onChainData.votesCollected,
-    };
+  // `getProposalsOnChainData` maps 1:1 over its input, so the single entry is
+  // always present — guard rather than assert, so the invariant is enforced
+  // instead of asserted away if that ever stops holding.
+  const onChainData = onChainDataList[0];
+  if (!onChainData) {
+    return undefined;
   }
 
-  return proposal;
+  return mapApiProposalToProposal(
+    apiProposal,
+    onChainData,
+    governanceEnvironment,
+  );
 }