@sage-protocol/sdk 0.2.3 → 0.2.5

package/README.md

@@ -44,6 +44,7 @@ const sdk = require('@sage-protocol/sdk');
 | `subdao` | Discovery, staking, user stats |
 | `token` | SXXX balances, allowances |
 | `treasury` | Reserve snapshots, withdrawals |
+| `reputation` | Author metrics, leaderboard, achievements |
 | `boost` | Merkle/Direct boost helpers |
 | `subgraph` | GraphQL queries |
 | `services` | High-level SubgraphService + IPFSService |

package/dist/browser/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.2.3",
+      version: "0.2.5",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -80,7 +80,7 @@ var require_package = __commonJS({
       },
       devDependencies: {
         proxyquire: "^2.1.3",
-        sinon: "^17.0.1",
+        sinon: "^21.0.0",
         tsup: "^8.1.0",
         typescript: "^5.4.0"
       },
@@ -180,15 +180,21 @@ var require_abi = __commonJS({
       "function libraryByDAO(address) view returns (string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce)",
       "function daoTimelock(address) view returns (address)",
       "function getLibrary(address) view returns (tuple(string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce))",
+      "function getLibraryIds(address dao) view returns (bytes32[] memory)",
+      "function getLibraryStream(address dao, string libraryId) view returns (tuple(string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce))",
       "function getLibraryForkFee(address dao) view returns (uint256)",
       "function setLibraryForkFee(address dao, uint256 fee)",
       "function updateLibrary(address dao, string manifestCID, string version)",
       "function updateLibraryCAS(address dao, string manifestCID, string version, uint256 expectedNonce)",
+      "function updateLibraryStream(address dao, string libraryId, string manifestCID, string version)",
+      "function updateLibraryStreamCAS(address dao, string libraryId, string manifestCID, string version, uint256 expectedNonce)",
       "function registerDAO(address dao, address timelock)",
       "function registerForkedDAO(address childDAO, address childTimelock, address parentDAO, string manifestCID, string version)",
       "function initializeLibraryFromFork(address sourceDao, address forkedDao)",
       "event LibraryUpdated(address indexed dao, string manifestCID, address indexed timelock, string version, uint256 nonce)",
-      "event DAORegistered(address indexed dao, address indexed timelock)",
+      "event DAORegistered(address indexed dao, address indexed timelock, address indexed creator)",
+      "event LibraryCreated(address indexed dao, bytes32 indexed libraryIdHash, string libraryId, address indexed creator)",
+      "event LibraryStreamUpdated(address indexed dao, bytes32 indexed libraryIdHash, string libraryId, string manifestCID, address indexed updater, string version, uint256 nonce)",
       "event LibraryForked(address indexed sourceDao, address indexed forkedDao, string manifestCID)",
       "event LibraryForkFeeUpdated(address indexed dao, uint256 fee)",
       "error NonceMismatch(uint256 expected, uint256 actual)"
@@ -798,7 +804,7 @@ var require_subgraph = __commonJS({
       const whereClause = hasFilter ? "where:{ subdao:$subdao }" : "";
       const doc = `
     query($subdao:Bytes,$first:Int!,$skip:Int!){
-      subDAOLibraryPointers(
+      libraryProjects(
         ${whereClause}
         first:$first,
         skip:$skip,
@@ -807,10 +813,9 @@ var require_subgraph = __commonJS({
       ){
         id
         subdao
-        libraryId
         manifestCID
-        previousCID
-        promptCount
+        version
+        nonce
         updatedAt
       }
     }
@@ -825,7 +830,7 @@ var require_subgraph = __commonJS({
         variables.subdao = addr.toLowerCase();
       }
       const data = await query(url, doc, variables);
-      return mapSafe(data?.subDAOLibraryPointers, (row) => {
+      return mapSafe(data?.libraryProjects, (row) => {
         const id = row?.id;
         const manifestCID = row?.manifestCID;
         const sub = safeGetAddress(row?.subdao);
@@ -833,10 +838,10 @@ var require_subgraph = __commonJS({
         return {
           id: String(id),
           subdao: sub,
-          libraryId: String(row.libraryId || "main"),
+          libraryId: String(id),
           manifestCID: String(manifestCID),
-          previousCID: row.previousCID || null,
-          promptCount: row.promptCount != null ? Number(row.promptCount) : null,
+          previousCID: null,
+          promptCount: null,
           updatedAt: row.updatedAt != null ? Number(row.updatedAt) : null
         };
       });

package/dist/index.cjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.2.3",
+      version: "0.2.5",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -80,7 +80,7 @@ var require_package = __commonJS({
       },
       devDependencies: {
         proxyquire: "^2.1.3",
-        sinon: "^17.0.1",
+        sinon: "^21.0.0",
         tsup: "^8.1.0",
         typescript: "^5.4.0"
       },
@@ -180,15 +180,21 @@ var require_abi = __commonJS({
       "function libraryByDAO(address) view returns (string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce)",
       "function daoTimelock(address) view returns (address)",
       "function getLibrary(address) view returns (tuple(string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce))",
+      "function getLibraryIds(address dao) view returns (bytes32[] memory)",
+      "function getLibraryStream(address dao, string libraryId) view returns (tuple(string manifestCID, address lastUpdater, uint256 lastUpdated, string version, address forkedFromDAO, uint256 sxxxForkFee, uint256 nonce))",
       "function getLibraryForkFee(address dao) view returns (uint256)",
       "function setLibraryForkFee(address dao, uint256 fee)",
       "function updateLibrary(address dao, string manifestCID, string version)",
       "function updateLibraryCAS(address dao, string manifestCID, string version, uint256 expectedNonce)",
+      "function updateLibraryStream(address dao, string libraryId, string manifestCID, string version)",
+      "function updateLibraryStreamCAS(address dao, string libraryId, string manifestCID, string version, uint256 expectedNonce)",
       "function registerDAO(address dao, address timelock)",
       "function registerForkedDAO(address childDAO, address childTimelock, address parentDAO, string manifestCID, string version)",
       "function initializeLibraryFromFork(address sourceDao, address forkedDao)",
       "event LibraryUpdated(address indexed dao, string manifestCID, address indexed timelock, string version, uint256 nonce)",
-      "event DAORegistered(address indexed dao, address indexed timelock)",
+      "event DAORegistered(address indexed dao, address indexed timelock, address indexed creator)",
+      "event LibraryCreated(address indexed dao, bytes32 indexed libraryIdHash, string libraryId, address indexed creator)",
+      "event LibraryStreamUpdated(address indexed dao, bytes32 indexed libraryIdHash, string libraryId, string manifestCID, address indexed updater, string version, uint256 nonce)",
       "event LibraryForked(address indexed sourceDao, address indexed forkedDao, string manifestCID)",
       "event LibraryForkFeeUpdated(address indexed dao, uint256 fee)",
       "error NonceMismatch(uint256 expected, uint256 actual)"
@@ -792,7 +798,7 @@ var require_subgraph = __commonJS({
       const whereClause = hasFilter ? "where:{ subdao:$subdao }" : "";
       const doc = `
     query($subdao:Bytes,$first:Int!,$skip:Int!){
-      subDAOLibraryPointers(
+      libraryProjects(
         ${whereClause}
         first:$first,
         skip:$skip,
@@ -801,14 +807,10 @@ var require_subgraph = __commonJS({
       ){
         id
         subdao
-        libraryId
         manifestCID
-        previousCID
-        promptCount
+        version
+        nonce
         updatedAt
-        createdAt
-        blockNumber
-        blockTimestamp
       }
     }
   `;
@@ -822,23 +824,24 @@ var require_subgraph = __commonJS({
         variables.subdao = addr.toLowerCase();
       }
       const data = await query(url, doc, variables);
-      return mapSafe(data?.subDAOLibraryPointers, (row) => {
+      return mapSafe(data?.libraryProjects, (row) => {
         const id2 = row?.id;
         const manifestCID = row?.manifestCID;
         const sub = safeGetAddress(row?.subdao);
         if (!id2 || !manifestCID || !sub) return null;
-        const timestamp = (row.updatedAt != null ? Number(row.updatedAt) : null) || (row.createdAt != null ? Number(row.createdAt) : null) || (row.blockTimestamp != null ? Number(row.blockTimestamp) : null);
         return {
           id: String(id2),
           subdao: sub,
-          libraryId: String(row.libraryId || "main"),
+          libraryId: String(id2),
           manifestCID: String(manifestCID),
-          previousCID: row.previousCID || null,
-          promptCount: row.promptCount != null ? Number(row.promptCount) : null,
-          updatedAt: timestamp,
-          createdAt: row.createdAt != null ? Number(row.createdAt) : null,
-          blockNumber: row.blockNumber != null ? Number(row.blockNumber) : null,
-          blockTimestamp: row.blockTimestamp != null ? Number(row.blockTimestamp) : null
+          previousCID: null,
+          // LibraryProject doesn't track previous CID
+          promptCount: null,
+          // LibraryProject doesn't track prompt count
+          updatedAt: row.updatedAt != null ? Number(row.updatedAt) : null,
+          createdAt: null,
+          blockNumber: null,
+          blockTimestamp: null
         };
       });
     }
@@ -2124,7 +2127,7 @@ var require_subgraph2 = __commonJS({
       const whereClause = hasFilter ? "where:{ subdao:$subdao }" : "";
       const doc = `
     query($subdao:Bytes,$first:Int!,$skip:Int!){
-      subDAOLibraryPointers(
+      libraryProjects(
         ${whereClause}
         first:$first,
         skip:$skip,
@@ -2133,10 +2136,9 @@ var require_subgraph2 = __commonJS({
       ){
         id
         subdao
-        libraryId
         manifestCID
-        previousCID
-        promptCount
+        version
+        nonce
         updatedAt
       }
     }
@@ -2151,7 +2153,7 @@ var require_subgraph2 = __commonJS({
         variables.subdao = addr.toLowerCase();
       }
       const data = await query(url, doc, variables);
-      return mapSafe(data?.subDAOLibraryPointers, (row) => {
+      return mapSafe(data?.libraryProjects, (row) => {
         const id2 = row?.id;
         const manifestCID = row?.manifestCID;
         const sub = safeGetAddress(row?.subdao);
@@ -2159,10 +2161,10 @@ var require_subgraph2 = __commonJS({
         return {
           id: String(id2),
           subdao: sub,
-          libraryId: String(row.libraryId || "main"),
+          libraryId: String(id2),
           manifestCID: String(manifestCID),
-          previousCID: row.previousCID || null,
-          promptCount: row.promptCount != null ? Number(row.promptCount) : null,
+          previousCID: null,
+          promptCount: null,
           updatedAt: row.updatedAt != null ? Number(row.updatedAt) : null
         };
       });
@@ -3825,6 +3827,16 @@ var require_library = __commonJS({
         throw new SageSDKError(CODES.INVALID_ARGS, `invalid ${label}`, { cause: err });
       }
     }
+    function normaliseLibraryId(libraryId) {
+      const raw = (libraryId == null ? "" : String(libraryId)).trim().toLowerCase();
+      if (!raw) return "default";
+      if (raw === "main") return "default";
+      const ok = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/.test(raw) && !raw.includes("--");
+      if (!ok) {
+        throw new SageSDKError(CODES.INVALID_ARGS, `invalid libraryId`, { libraryId });
+      }
+      return raw;
+    }
     async function listManifests({ provider, registry, factoryAddress, offset = 0, limit = 50 }) {
       if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
       if (!factoryAddress) throw new SageSDKError(CODES.INVALID_ARGS, "factoryAddress required for V4 listing");
@@ -3863,6 +3875,35 @@ var require_library = __commonJS({
         sxxxForkFee: BigInt(info.sxxxForkFee.toString())
       };
     }
+    async function getLibraryStreamInfo({ provider, registry, subdao: subdao2, libraryId = "default" }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      if (!subdao2) throw new SageSDKError(CODES.INVALID_ARGS, "subdao required");
+      const addr = normalise(registry, "registry");
+      const dao = normalise(subdao2, "subdao");
+      const libId = normaliseLibraryId(libraryId);
+      const contract = new Contract(addr, ABI.LibraryRegistry, provider);
+      const info = await contract.getLibraryStream(dao, libId);
+      return {
+        libraryId: libId,
+        manifestCID: info.manifestCID,
+        previousCID: "",
+        timestamp: BigInt(info.lastUpdated.toString()),
+        proposer: getAddress(info.lastUpdater),
+        promptCount: 0,
+        version: info.version,
+        nonce: BigInt(info.nonce.toString()),
+        forkedFromDAO: info.forkedFromDAO && info.forkedFromDAO !== "0x0000000000000000000000000000000000000000" ? getAddress(info.forkedFromDAO) : null,
+        sxxxForkFee: BigInt(info.sxxxForkFee.toString())
+      };
+    }
+    async function getLibraryIds({ provider, registry, subdao: subdao2 }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      if (!subdao2) throw new SageSDKError(CODES.INVALID_ARGS, "subdao required");
+      const addr = normalise(registry, "registry");
+      const dao = normalise(subdao2, "subdao");
+      const contract = new Contract(addr, ABI.LibraryRegistry, provider);
+      return await contract.getLibraryIds(dao);
+    }
     async function getManifestInfo({ provider, registry, manifestCID }) {
       throw new SageSDKError(CODES.UNSUPPORTED_OPERATION, "getManifestInfo(cid) is not supported in V4. Use getLibraryInfo(subdao).");
     }
@@ -3885,26 +3926,42 @@ var require_library = __commonJS({
       const info = await getLatestLibrary({ provider, registry, subdao: subdao2 });
       return info && info.manifestCID === manifestCID;
     }
-    function buildUpdateLibraryTx({ registry, subdao: subdao2, manifestCID, version = "1.0.0" }) {
+    function buildUpdateLibraryTx({ registry, subdao: subdao2, libraryId = "default", manifestCID, version = "1.0.0" }) {
       const to = normalise(registry, "registry");
       if (!manifestCID) throw new SageSDKError(CODES.INVALID_ARGS, "manifestCID required");
-      const iface = new Interface(["function updateLibrary(address,string,string)"]);
-      const data = iface.encodeFunctionData("updateLibrary", [
-        normalise(subdao2, "subdao"),
-        String(manifestCID),
-        String(version)
-      ]);
+      const dao = normalise(subdao2, "subdao");
+      const libId = normaliseLibraryId(libraryId);
+      if (libId === "default") {
+        const iface2 = new Interface(["function updateLibrary(address,string,string)"]);
+        const data2 = iface2.encodeFunctionData("updateLibrary", [dao, String(manifestCID), String(version)]);
+        return { to, data: data2, value: 0n };
+      }
+      const iface = new Interface(["function updateLibraryStream(address,string,string,string)"]);
+      const data = iface.encodeFunctionData("updateLibraryStream", [dao, libId, String(manifestCID), String(version)]);
       return { to, data, value: 0n };
     }
-    function buildUpdateLibraryCAS({ registry, subdao: subdao2, manifestCID, version = "1.0.0", expectedNonce }) {
+    function buildUpdateLibraryCAS({ registry, subdao: subdao2, libraryId = "default", manifestCID, version = "1.0.0", expectedNonce }) {
       const to = normalise(registry, "registry");
       if (!manifestCID) throw new SageSDKError(CODES.INVALID_ARGS, "manifestCID required");
       if (expectedNonce === void 0 || expectedNonce === null) {
         throw new SageSDKError(CODES.INVALID_ARGS, "expectedNonce required for CAS update");
       }
-      const iface = new Interface(["function updateLibraryCAS(address,string,string,uint256)"]);
-      const data = iface.encodeFunctionData("updateLibraryCAS", [
-        normalise(subdao2, "subdao"),
+      const dao = normalise(subdao2, "subdao");
+      const libId = normaliseLibraryId(libraryId);
+      if (libId === "default") {
+        const iface2 = new Interface(["function updateLibraryCAS(address,string,string,uint256)"]);
+        const data2 = iface2.encodeFunctionData("updateLibraryCAS", [
+          dao,
+          String(manifestCID),
+          String(version),
+          BigInt(expectedNonce)
+        ]);
+        return { to, data: data2, value: 0n };
+      }
+      const iface = new Interface(["function updateLibraryStreamCAS(address,string,string,string,uint256)"]);
+      const data = iface.encodeFunctionData("updateLibraryStreamCAS", [
+        dao,
+        libId,
         String(manifestCID),
         String(version),
         BigInt(expectedNonce)
@@ -3915,6 +3972,8 @@ var require_library = __commonJS({
       listManifests,
       getManifestInfo,
       getLibraryInfo,
+      getLibraryStreamInfo,
+      getLibraryIds,
       getLatestLibrary,
       hasScopedOwnership,
       buildUpdateLibraryTx,
@@ -4470,7 +4529,12 @@ var require_governance = __commonJS({
       if (!parsed) throw new Error("ProposalCreated event not found");
       const targets = parsed.args.targets.map(getAddress);
       const calldatas = parsed.args.calldatas.map((d) => typeof d === "string" ? d : "0x" + Buffer.from(d).toString("hex"));
-      const LibraryIface = new Interface(["function updateLibrary(address,string,string)"]);
+      const LibraryIface = new Interface([
+        "function updateLibrary(address dao, string manifestCID, string version)",
+        "function updateLibraryCAS(address dao, string manifestCID, string version, uint256 expectedNonce)",
+        "function updateLibraryStream(address dao, string libraryId, string manifestCID, string version)",
+        "function updateLibraryStreamCAS(address dao, string libraryId, string manifestCID, string version, uint256 expectedNonce)"
+      ]);
       const PromptIface = new Interface(["function updatePromptByGovernance(string,string)"]);
       const effects = [];
       for (let i = 0; i < calldatas.length; i++) {
@@ -4484,7 +4548,10 @@ var require_governance = __commonJS({
           try {
             const reg = new Contract(
               targets[i],
-              ["function libraryByDAO(address) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee))"],
+              [
+                "function libraryByDAO(address) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee))",
+                "function getLibraryStream(address,string) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee,uint256 nonce))"
+              ],
               provider
             );
             const info = await reg.libraryByDAO(dao).catch(() => null);
@@ -4495,10 +4562,130 @@ var require_governance = __commonJS({
           } catch (_) {
           }
           effects.push({
-            type: "libraryUpdateV4",
+            type: "libraryUpdate",
+            index: i,
+            target: targets[i],
+            dao: getAddress(dao),
+            libraryId: "default",
+            previousCid: previousCID,
+            previousVersion,
+            newCid: String(newCid),
+            newVersion: String(version)
+          });
+          continue;
+        } catch (_) {
+        }
+        try {
+          const decoded = LibraryIface.decodeFunctionData("updateLibraryCAS", data);
+          const [dao, newCid, version] = decoded;
+          let previousCID = null;
+          let previousVersion = null;
+          try {
+            const reg = new Contract(
+              targets[i],
+              [
+                "function libraryByDAO(address) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee))",
+                "function getLibraryStream(address,string) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee,uint256 nonce))"
+              ],
+              provider
+            );
+            const info = await reg.libraryByDAO(dao).catch(() => null);
+            if (info && typeof info.manifestCID === "string") {
+              previousCID = info.manifestCID || null;
+              previousVersion = info.version || null;
+            }
+          } catch (_) {
+          }
+          effects.push({
+            type: "libraryUpdate",
+            index: i,
+            target: targets[i],
+            dao: getAddress(dao),
+            libraryId: "default",
+            previousCid: previousCID,
+            previousVersion,
+            newCid: String(newCid),
+            newVersion: String(version)
+          });
+          continue;
+        } catch (_) {
+        }
+        try {
+          const decoded = LibraryIface.decodeFunctionData("updateLibraryStream", data);
+          const [dao, libraryId, newCid, version] = decoded;
+          let previousCID = null;
+          let previousVersion = null;
+          try {
+            const reg = new Contract(
+              targets[i],
+              [
+                "function getLibraryStream(address,string) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee,uint256 nonce))",
+                "function libraryByDAO(address) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee))"
+              ],
+              provider
+            );
+            let info = null;
+            try {
+              info = await reg.getLibraryStream(dao, String(libraryId));
+            } catch (_) {
+              if (String(libraryId) === "default") {
+                info = await reg.libraryByDAO(dao).catch(() => null);
+              }
+            }
+            if (info && typeof info.manifestCID === "string") {
+              previousCID = info.manifestCID || null;
+              previousVersion = info.version || null;
+            }
+          } catch (_) {
+          }
+          effects.push({
+            type: "libraryUpdate",
             index: i,
             target: targets[i],
             dao: getAddress(dao),
+            libraryId: String(libraryId),
+            previousCid: previousCID,
+            previousVersion,
+            newCid: String(newCid),
+            newVersion: String(version)
+          });
+          continue;
+        } catch (_) {
+        }
+        try {
+          const decoded = LibraryIface.decodeFunctionData("updateLibraryStreamCAS", data);
+          const [dao, libraryId, newCid, version] = decoded;
+          let previousCID = null;
+          let previousVersion = null;
+          try {
+            const reg = new Contract(
+              targets[i],
+              [
+                "function getLibraryStream(address,string) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee,uint256 nonce))",
+                "function libraryByDAO(address) view returns (tuple(string manifestCID,address lastUpdater,uint256 lastUpdated,string version,address forkedFromDAO,uint256 sxxxForkFee))"
+              ],
+              provider
+            );
+            let info = null;
+            try {
+              info = await reg.getLibraryStream(dao, String(libraryId));
+            } catch (_) {
+              if (String(libraryId) === "default") {
+                info = await reg.libraryByDAO(dao).catch(() => null);
+              }
+            }
+            if (info && typeof info.manifestCID === "string") {
+              previousCID = info.manifestCID || null;
+              previousVersion = info.version || null;
+            }
+          } catch (_) {
+          }
+          effects.push({
+            type: "libraryUpdate",
+            index: i,
+            target: targets[i],
+            dao: getAddress(dao),
+            libraryId: String(libraryId),
             previousCid: previousCID,
             previousVersion,
             newCid: String(newCid),
@@ -4835,9 +5022,127 @@ var require_governance = __commonJS({
         description: desc.description
       };
     }
+    async function getProposalVotingStatus({ provider, governor, proposalId }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      if (!proposalId) throw new SageSDKError(CODES.INVALID_ARGS, "proposalId required");
+      const addr = normaliseGovernor(governor);
+      const g = new Contract(addr, ABI.Governor, provider);
+      const pid = typeof proposalId === "bigint" ? proposalId : BigInt(String(proposalId));
+      const [
+        stateNum,
+        snapshot,
+        deadline,
+        votes,
+        votingDelay,
+        votingPeriod,
+        proposalThreshold,
+        govName
+      ] = await Promise.all([
+        g.state(pid).catch(() => null),
+        g.proposalSnapshot(pid).catch(() => null),
+        g.proposalDeadline(pid).catch(() => null),
+        g.proposalVotes(pid).catch(() => null),
+        g.votingDelay().catch(() => null),
+        g.votingPeriod().catch(() => null),
+        g.proposalThreshold().catch(() => null),
+        g.name().catch(() => null)
+      ]);
+      let quorum = null;
+      if (snapshot != null) {
+        try {
+          quorum = await g.quorum(snapshot);
+          quorum = BigInt(quorum.toString());
+        } catch {
+          try {
+            const qv = await g.quorumVotes();
+            quorum = BigInt(qv.toString());
+          } catch {
+          }
+        }
+      }
+      let forVotes = 0n;
+      let againstVotes = 0n;
+      let abstainVotes = 0n;
+      if (Array.isArray(votes)) {
+        againstVotes = BigInt(votes[0]);
+        forVotes = BigInt(votes[1]);
+        abstainVotes = BigInt(votes[2]);
+      } else if (votes && typeof votes === "object") {
+        if (votes.againstVotes != null) againstVotes = BigInt(votes.againstVotes);
+        if (votes.forVotes != null) forVotes = BigInt(votes.forVotes);
+        if (votes.abstainVotes != null) abstainVotes = BigInt(votes.abstainVotes);
+      }
+      const totalVotes = forVotes + againstVotes + abstainVotes;
+      const participatingVotes = forVotes + againstVotes;
+      const quorumMet = quorum != null ? forVotes >= quorum : null;
+      const quorumProgress = quorum != null && quorum > 0n ? Number(forVotes * 10000n / quorum) / 100 : null;
+      const stateMap = ["PENDING", "ACTIVE", "CANCELED", "DEFEATED", "SUCCEEDED", "QUEUED", "EXPIRED", "EXECUTED"];
+      const state = typeof stateNum === "number" && stateNum >= 0 && stateNum < stateMap.length ? stateMap[stateNum] : null;
+      const BLOCK_TIME_SECONDS = 2;
+      const votingDelaySeconds = votingDelay != null ? Number(votingDelay) * BLOCK_TIME_SECONDS : null;
+      const votingPeriodSeconds = votingPeriod != null ? Number(votingPeriod) * BLOCK_TIME_SECONDS : null;
+      const formatSXXX = (val) => {
+        if (val == null) return null;
+        const num = Number(val) / 1e18;
+        if (num >= 1e6) return `${(num / 1e6).toFixed(1)}M`;
+        if (num >= 1e3) return `${(num / 1e3).toFixed(1)}K`;
+        return num.toFixed(2);
+      };
+      const formatDuration = (seconds) => {
+        if (seconds == null) return null;
+        if (seconds < 60) return `${seconds} seconds`;
+        if (seconds < 3600) return `${Math.round(seconds / 60)} minutes`;
+        if (seconds < 86400) return `${(seconds / 3600).toFixed(1)} hours`;
+        return `${(seconds / 86400).toFixed(1)} days`;
+      };
+      return {
+        governor: addr,
+        governorName: govName,
+        proposalId: pid.toString(),
+        state,
+        stateNum: typeof stateNum === "number" ? stateNum : null,
+        // Raw values (bigint as string for JSON serialization)
+        votes: {
+          for: forVotes.toString(),
+          against: againstVotes.toString(),
+          abstain: abstainVotes.toString(),
+          total: totalVotes.toString()
+        },
+        quorum: quorum?.toString() || null,
+        proposalThreshold: proposalThreshold?.toString() || null,
+        snapshot: snapshot?.toString() || null,
+        deadline: deadline?.toString() || null,
+        votingDelay: votingDelay?.toString() || null,
+        votingPeriod: votingPeriod?.toString() || null,
+        // Computed status
+        quorumMet,
+        quorumProgress,
+        // percentage (0-100+)
+        passing: forVotes > againstVotes,
+        // Formatted for display
+        formatted: {
+          forVotes: formatSXXX(forVotes),
+          againstVotes: formatSXXX(againstVotes),
+          abstainVotes: formatSXXX(abstainVotes),
+          totalVotes: formatSXXX(totalVotes),
+          quorum: formatSXXX(quorum),
+          proposalThreshold: formatSXXX(proposalThreshold),
+          votingDelay: formatDuration(votingDelaySeconds),
+          votingPeriod: formatDuration(votingPeriodSeconds)
+        },
+        // Plain language summary
+        summary: {
+          quorumStatus: quorum != null ? quorumMet ? `Quorum reached (${formatSXXX(forVotes)} of ${formatSXXX(quorum)} SXXX required)` : `${formatSXXX(forVotes)} of ${formatSXXX(quorum)} SXXX needed for quorum (${quorumProgress?.toFixed(1)}%)` : "Quorum information unavailable",
+          voteStatus: `${formatSXXX(forVotes)} SXXX for, ${formatSXXX(againstVotes)} SXXX against`,
+          outcome: forVotes > againstVotes ? "Currently passing" : forVotes < againstVotes ? "Currently failing" : "Tied",
+          votingPeriod: votingPeriodSeconds ? `Voting period: ${formatDuration(votingPeriodSeconds)}` : null
+        }
+      };
+    }
     module2.exports = {
       getGovernorInfo,
       getProposal,
+      getProposalVotingStatus,
       listProposals,
       getProposalMetadata,
       hashDescription,