@moonwell-fi/moonwell-sdk 0.15.0 → 0.16.0

package/actions/governance/ipfs.ts

@@ -0,0 +1,82 @@
+import type { Environment } from "../../environments/index.js";
+import { getWithRetry } from "../axiosWithRetry.js";
+import type { ApiProposal } from "./governor-api-client.js";
+
+const PINATA_GATEWAY = "https://d4529a05.mypinata.cloud/ipfs";
+
+// IPFS content is content-addressed, so a per-hash result is immutable and the
+// cache lives for the process lifetime — no TTL needed. Repeated getProposals()
+// calls in the same Node/browser session reuse the resolved markdown.
+const ipfsContentCache = new Map<string, string>();
+
+/**
+ * Strip the `ipfs://` prefix from an indexer-supplied URI. Returns null for
+ * anything that isn't an IPFS URI (including empty strings and undefined),
+ * which lets callers skip the fetch with a single check.
+ */
+export const parseIpfsHash = (uri: string | undefined): string | null => {
+  if (!uri) return null;
+  return uri.match(/^ipfs:\/\/(.+)$/)?.[1] ?? null;
+};
+
+/**
+ * Fetch a single IPFS resource via the Pinata gateway. Cached by hash.
+ *
+ * `responseType: "text"` disables axios's default JSON auto-parse so we keep
+ * the markdown body verbatim. We additionally reject non-string responses so
+ * an HTML error page or JSON payload doesn't poison the cache as
+ * `"[object Object]"` — the caller's per-proposal catch keeps the `ipfs://`
+ * URI in place when that happens.
+ */
+export const fetchIpfsContent = async (hash: string): Promise<string> => {
+  const cached = ipfsContentCache.get(hash);
+  if (cached !== undefined) return cached;
+
+  const response = await getWithRetry<string>(`${PINATA_GATEWAY}/${hash}`, {
+    responseType: "text",
+  });
+  if (typeof response.data !== "string") {
+    throw new Error(
+      `[fetchIpfsContent] non-string body for hash=${hash} (typeof=${typeof response.data})`,
+    );
+  }
+  ipfsContentCache.set(hash, response.data);
+  return response.data;
+};
+
+/**
+ * For every proposal whose `description` is an `ipfs://` URI, fetch the
+ * underlying markdown from Pinata and replace `description` in place. All
+ * fetches run in parallel.
+ *
+ * Failures are logged via console.warn AND surfaced through
+ * `env.onError` (matching the convention used by `getProposalData` /
+ * `getExtendedProposalData`), then swallowed per-proposal: the `ipfs://` URI
+ * is left untouched so consumers can detect (e.g. via
+ * `description.startsWith("ipfs://")`) and render a fallback. The bulk call
+ * never rejects, so a single bad pin doesn't kill `getProposals()` for
+ * everyone.
+ */
+export const resolveIpfsDescriptions = async (
+  proposals: ApiProposal[],
+  env: Environment,
+): Promise<void> => {
+  await Promise.all(
+    proposals.map(async (proposal) => {
+      const hash = parseIpfsHash(proposal.description);
+      if (!hash) return;
+      try {
+        proposal.description = await fetchIpfsContent(hash);
+      } catch (error) {
+        console.warn(
+          `[resolveIpfsDescriptions] failed to fetch hash=${hash}:`,
+          error,
+        );
+        env.onError?.(error, {
+          source: "governance-ipfs-description",
+          chainId: proposal.chainId,
+        });
+      }
+    }),
+  );
+};

package/actions/governance/proposals/common.ts

@@ -262,12 +262,61 @@ const getLegacyArtemisMaxId = async (
   }
 };
 
+/**
+ * Reads the multichain governor's quorum on every chain that holds an active
+ * proposal but isn't the one we'd normally read through. Returns a chainId →
+ * quorum map; chains with no `multichainGovernor` wired are omitted, as are
+ * chains whose quorum read reverted. Callers substitute `0n` for misses via
+ * the `options.crossChainQuorums?.get(...) ?? 0n` pattern.
+ *
+ * Read failures are routed through `onError` so Sentry-wired consumers see
+ * them — matching `getProposalData` / `getCrossChainProposalData` /
+ * `getExtendedProposalData`. The caller's `governanceEnvironment` carries
+ * `onError` since we don't have one per foreign chain in scope.
+ */
+export const readCrossChainQuorums = async (
+  apiProposals: ApiProposal[],
+  governanceEnvironment: Environment,
+): Promise<Map<number, bigint>> => {
+  const otherChainIds = Array.from(
+    new Set(
+      apiProposals
+        .map((p) => p.chainId)
+        .filter((c) => c !== governanceEnvironment.chainId),
+    ),
+  );
+  const quorums = new Map<number, bigint>();
+  await Promise.all(
+    otherChainIds.map(async (chainId) => {
+      const env = (Object.values(publicEnvironments) as Environment[]).find(
+        (e) => e.chainId === chainId,
+      );
+      const mg = env?.contracts.multichainGovernor;
+      if (!mg) return;
+      try {
+        quorums.set(chainId, await mg.read.quorum());
+      } catch (error) {
+        console.warn(
+          `[readCrossChainQuorums] quorum read failed for chainId=${chainId}:`,
+          error,
+        );
+        governanceEnvironment.onError?.(error, {
+          source: "governance-cross-chain-quorum",
+          chainId,
+        });
+      }
+    }),
+  );
+  return quorums;
+};
+
 /**
  * Fetches on-chain data for multiple proposals
  */
 export const getProposalsOnChainData = async (
   apiProposals: ApiProposal[],
   governanceEnvironment: Environment,
+  options?: { crossChainQuorums?: Map<number, bigint> },
 ): Promise<ProposalOnChainData[]> => {
   let quorum = 0n;
 
@@ -289,9 +338,12 @@ export const getProposalsOnChainData = async (
   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.
+      // Ethereum proposals fetched through the Moonbeam env) can't have their
+      // state read from this env's contracts — derive state from API events here
+      // so callers never see a misleading `state: 0` default for finalized
+      // proposals. Quorum, however, comes from a per-chain map populated by the
+      // caller via `readCrossChainQuorums` (defaulting to 0n when the caller
+      // didn't pre-fetch, e.g. in unit tests).
       if (p.chainId !== governanceEnvironment.chainId) {
         const formatted = formatApiProposalData(p);
         return {
@@ -299,7 +351,7 @@ export const getProposalsOnChainData = async (
           proposalData: null,
           eta: 0,
           votesCollected: false,
-          quorum: 0n,
+          quorum: options?.crossChainQuorums?.get(p.chainId) ?? 0n,
         };
       }
 

package/actions/governance/proposals/getProposal.ts

@@ -10,6 +10,7 @@ import {
   fetchProposal,
   isNotFoundError,
 } from "../governor-api-client.js";
+import { resolveIpfsDescriptions } from "../ipfs.js";
 import {
   appendProposalExtendedData,
   formatApiProposalData,
@@ -18,6 +19,7 @@ import {
   getProposalData,
   getProposalsOnChainData,
   isMultichainProposal,
+  readCrossChainQuorums,
 } from "./common.js";
 
 export type GetProposalParameters<
@@ -91,10 +93,16 @@ async function getMoonbeamProposal(
     return undefined;
   }
 
+  const [, crossChainQuorums] = await Promise.all([
+    resolveIpfsDescriptions([apiProposal], governanceEnvironment),
+    readCrossChainQuorums([apiProposal], governanceEnvironment),
+  ]);
+
   const formattedData = formatApiProposalData(apiProposal);
   const onChainDataList = await getProposalsOnChainData(
     [apiProposal],
     governanceEnvironment,
+    { crossChainQuorums },
   );
   const onChainData = onChainDataList[0]!;
   const isMultichain = isMultichainProposal(apiProposal.targets);

package/actions/governance/proposals/getProposals.ts

@@ -6,6 +6,7 @@ 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 { resolveIpfsDescriptions } from "../ipfs.js";
 import {
   appendProposalExtendedData,
   formatApiProposalData,
@@ -14,6 +15,7 @@ import {
   getProposalData,
   getProposalsOnChainData,
   isMultichainProposal,
+  readCrossChainQuorums,
 } from "./common.js";
 
 export type GetProposalsParameters<
@@ -93,19 +95,31 @@ async function getMoonbeamProposals(
   const chainsAttempted: ReadonlyArray<1 | 1284> = [1, 1284];
   const apiProposals: ApiProposal[] = [];
   results.forEach((result, index) => {
+    const chainId = chainsAttempted[index];
     if (result.status === "fulfilled") {
       apiProposals.push(...result.value);
-    } else {
+    } else if (chainId !== undefined) {
       console.warn(
-        `[getProposals] Failed to fetch proposals for chainId=${chainsAttempted[index]}; continuing with remaining chains.`,
+        `[getProposals] Failed to fetch proposals for chainId=${chainId}; continuing with remaining chains.`,
         result.reason,
       );
+      governanceEnvironment.onError?.(result.reason, {
+        source: "governance-proposals",
+        chainId,
+      });
     }
   });
 
+  // IPFS resolution and cross-chain quorum reads are independent — run them in
+  // parallel to save one network round-trip on the proposal list path.
+  const [, crossChainQuorums] = await Promise.all([
+    resolveIpfsDescriptions(apiProposals, governanceEnvironment),
+    readCrossChainQuorums(apiProposals, governanceEnvironment),
+  ]);
   const onChainDataList = await getProposalsOnChainData(
     apiProposals,
     governanceEnvironment,
+    { crossChainQuorums },
   );
 
   const proposals: Proposal[] = apiProposals.map((apiProposal, index) => {

package/environments/definitions/ethereum/contracts.ts

@@ -6,6 +6,7 @@ export const contracts = createContractsConfig({
   contracts: {
     stakingToken: "stkWELL",
     governanceToken: "WELL",
-    views: "0xF5f2ae75d762B7e2B42D53f48018436f52Ce5401",
+    views: "0xA061Ed814bBd1b03e8df0B7AbEbc40f4A6feb895",
+    multichainGovernor: "0x8769B70ac7c93AF0e75de0D69877709B66d75838",
   },
 });

package/errors/version.ts

@@ -1 +1 @@
-export const version = '0.15.0'
+export const version = '0.16.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moonwell-fi/moonwell-sdk",
   "description": "TypeScript Interface for Moonwell",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",