@moonwell-fi/moonwell-sdk 0.21.0 → 0.23.0

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

package/actions/governance/proposals/getProposals.ts

@@ -1,16 +1,20 @@
-import { moonbeam, moonriver } from "viem/chains";
 import type { MoonwellClient } from "../../../client/createMoonwellClient.js";
-import { Amount, getEnvironmentsFromArgs } from "../../../common/index.js";
+import { 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, ProposalState } from "../../../types/proposal.js";
-import { type ApiProposal, fetchAllProposals } from "../governor-api-client.js";
+import type { Proposal } from "../../../types/proposal.js";
+import {
+  type ApiProposal,
+  SUPPORTED_GOVERNOR_CHAIN_IDS,
+  fetchAllProposals,
+} from "../governor-api-client.js";
 import { resolveIpfsDescriptions } from "../ipfs.js";
 import {
-  formatApiProposalData,
   getProposalsOnChainData,
+  mapApiProposalToProposal,
   readCrossChainQuorums,
+  resolveGovernanceEnvironment,
 } from "./common.js";
 
 export type GetProposalsParameters<
@@ -31,30 +35,14 @@ export async function getProposals<
 
   const environments = getEnvironmentsFromArgs(client, args);
 
-  const governanceEnvironments = environments.filter(
-    (environment) =>
-      environment.chainId === moonbeam.id ||
-      environment.chainId === moonriver.id,
-  );
+  const governanceEnvironment = resolveGovernanceEnvironment(environments);
 
-  if (governanceEnvironments.length === 0) {
+  if (!governanceEnvironment) {
     logger.end(logId);
     return [];
   }
 
-  const allProposals = await Promise.all(
-    governanceEnvironments.map(async (governanceEnvironment) => {
-      if (governanceEnvironment.chainId === moonbeam.id) {
-        // Moonbeam + Ethereum: Governor API (chainIds 1 and 1284)
-        return getMoonbeamProposals(governanceEnvironment);
-      } else {
-        // Moonriver: Governor API, single legacy governor (chainId 1285)
-        return getMoonriverProposals(governanceEnvironment);
-      }
-    }),
-  );
-
-  const proposals = allProposals.flat();
+  const proposals = await fetchGovernorProposals(governanceEnvironment);
   // 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
@@ -70,27 +58,34 @@ export async function getProposals<
 }
 
 /**
- * Fetch proposals for Moonbeam using the Governor API.
+ * Fetch every proposal the Governor API serves, across all governance chains.
  *
- * The same indexer DO serves two chains:
- *   - chainId=1 (Ethereum) — the active multigov contract
- *   - chainId=1284 (Moonbeam) — historical proposals
+ * One indexer DO serves them all:
+ *   - chainId=1    (Ethereum)  — the active multigov contract
+ *   - chainId=1284 (Moonbeam)  — historical archive, chain halted
+ *   - chainId=1285 (Moonriver) — legacy Apollo governor, chain halted
  *
- * Uses `Promise.allSettled` so a transient outage on one chain doesn't take
- * down the other — partial results are preferred over a hard failure.
+ * The sunset chains keep appearing here on purpose: the indexer still has their
+ * proposals even though no RPC exists for them any more, so the governance
+ * record stays readable (MOO-551). What they lose is the on-chain half —
+ * `getProposalsOnChainData` finds no environment for 1284/1285 and derives their
+ * state from indexer events, leaving quorum and eta unset.
+ *
+ * `Promise.allSettled` so one chain's outage degrades to a missing slice rather
+ * than an empty list.
  */
-async function getMoonbeamProposals(
+async function fetchGovernorProposals(
   governanceEnvironment: Environment,
 ): Promise<Proposal[]> {
-  const results = await Promise.allSettled([
-    fetchAllProposals(governanceEnvironment, { chainId: 1 }),
-    fetchAllProposals(governanceEnvironment, { chainId: 1284 }),
-  ]);
+  const results = await Promise.allSettled(
+    SUPPORTED_GOVERNOR_CHAIN_IDS.map((chainId) =>
+      fetchAllProposals(governanceEnvironment, { chainId }),
+    ),
+  );
 
-  const chainsAttempted: ReadonlyArray<1 | 1284> = [1, 1284];
   const apiProposals: ApiProposal[] = [];
   results.forEach((result, index) => {
-    const chainId = chainsAttempted[index];
+    const chainId = SUPPORTED_GOVERNOR_CHAIN_IDS[index];
     if (result.status === "fulfilled") {
       apiProposals.push(...result.value);
     } else if (chainId !== undefined) {
@@ -109,44 +104,13 @@ async function getMoonbeamProposals(
 }
 
 /**
- * Fetch proposals for Moonriver using the Governor API.
+ * Governor-API pipeline: resolve IPFS descriptions + cross-chain quorums in
+ * parallel, read on-chain data, then map each ApiProposal to a Proposal.
  *
- * Moonriver runs a single legacy standalone governor (no multichain governor),
- * so we fetch only its chainId from the same lunar indexer and reuse the shared
- * pipeline. `getProposalsOnChainData` classifies these as non-multichain and
- * reads state/quorum from the legacy governor (via `getQuorum`).
- */
-async function getMoonriverProposals(
-  governanceEnvironment: Environment,
-): Promise<Proposal[]> {
-  // Moonriver is a single chain, so there's no other chain to "continue with"
-  // like the Moonbeam fan-out — but a bare throw would reject the whole
-  // `Promise.all` in getProposals and drop Moonbeam/Ethereum results too. Mirror
-  // the per-chain handling getMoonbeamProposals uses: report the outage via
-  // onError and degrade to an empty Moonriver list instead of rejecting.
-  let apiProposals: ApiProposal[] = [];
-  try {
-    apiProposals = await fetchAllProposals(governanceEnvironment, {
-      chainId: moonriver.id,
-    });
-  } catch (reason) {
-    console.warn(
-      `[getProposals] Failed to fetch proposals for chainId=${moonriver.id}; continuing with an empty Moonriver list.`,
-      reason,
-    );
-    governanceEnvironment.onError?.(reason, {
-      source: "governance-proposals",
-      chainId: moonriver.id,
-    });
-  }
-  return buildProposals(apiProposals, governanceEnvironment);
-}
-
-/**
- * Shared Governor-API pipeline: resolve IPFS descriptions + cross-chain quorums
- * in parallel, read on-chain data, then map each ApiProposal to a Proposal.
- * Used by both the Moonbeam/Ethereum and Moonriver paths so the mapping stays
- * in one place.
+ * Single caller (`fetchGovernorProposals`) since the sunset removed the separate
+ * `getMoonbeamProposals` / `getMoonriverProposals` entry points (MOO-551) —
+ * kept as its own function because it is the list-shaped counterpart to
+ * `getProposal`'s single-proposal pipeline, and the two are read together.
  */
 async function buildProposals(
   apiProposals: ApiProposal[],
@@ -164,85 +128,20 @@ async function buildProposals(
     { crossChainQuorums },
   );
 
-  const proposals: Proposal[] = apiProposals.map((apiProposal, index) => {
-    const onChainData = onChainDataList[index]!;
-    const formattedData = formatApiProposalData(apiProposal);
-    // Single source of truth — see getProposal.ts. getProposalsOnChainData
-    // classified with the Artemis cutoff and routed the reads accordingly;
-    // re-classifying here without the cutoff 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 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,
-      };
-    }
-
-    return proposal;
+  // `getProposalsOnChainData` maps 1:1 over its input, so every index resolves —
+  // guard rather than assert, so the invariant is enforced instead of asserted
+  // away if that ever stops holding.
+  const proposals: Proposal[] = apiProposals.flatMap((apiProposal, index) => {
+    const onChainData = onChainDataList[index];
+    return onChainData
+      ? [
+          mapApiProposalToProposal(
+            apiProposal,
+            onChainData,
+            governanceEnvironment,
+          ),
+        ]
+      : [];
   });
 
   return proposals;