@sage-protocol/sdk 0.0.5 → 0.0.7

package/README.md

@@ -77,6 +77,44 @@ Next Phases
 -----------
 Phase 6 focuses on integration polish and packaging. Track progress in the [SDK Improvement Specification](../../docs/SDK_Improvement_Specification.md).
 
+New governance/factory/library helpers (2025‑10)
+-----------------------------------------------
+
+Proposal ID and preflight
+```js
+import sdk from '@sage-protocol/sdk';
+const idHex = sdk.governance.computeProposalIdHex({ targets, values, calldatas, description });
+const pre = await sdk.governance.simulatePropose({ provider, governor, targets, values, calldatas, description, sender });
+if (!pre.ok) throw new Error(`preflight failed: ${pre.error?.message}`);
+```
+
+Votes at latest‑1 (ERC20Votes)
+```js
+// Token path
+const votes1 = await sdk.governance.getVotesLatestMinusOne({ provider, token: sxxxToken, account: user });
+// Governor path (auto‑resolves token)
+const votes2 = await sdk.governance.getVotesLatestMinusOne({ provider, governor, account: user });
+```
+
+Factory‑mapped registry
+```js
+const mapped = await sdk.factory.getSubDAORegistry({ provider, factory, subdao });
+```
+
+Registry preflight as timelock
+```js
+const { to, data } = sdk.library.buildUpdateLibraryForSubDAOTx({ registry, subdao, manifestCID, promptCount, libraryId: 'main' });
+const sim = await sdk.library.simulateAsTimelock({ provider, registry, to, data, timelock });
+if (!sim.ok) throw new Error(`registry preflight failed: ${sim.error?.message}`);
+```
+
+Propose by hash (arrays + bytes32)
+```js
+// For governors that prefer descriptionHash (or deterministic IDs)
+const dh = sdk.governance.hashDescription(description);
+const tx = sdk.governance.buildProposeTxByHash({ governor, targets, values, calldatas, descriptionHash: dh });
+```
+
 API Notes and Examples
 ----------------------
 

package/dist/index.cjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.0.5",
+      version: "0.0.7",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -107,6 +107,8 @@ var require_abi = __commonJS({
       "function simpleKeyStoreAddress() view returns (address)",
       "function governanceConfigAddress() view returns (address)",
       "function libraryRegistryAddress() view returns (address)",
+      // Canonical per‑SubDAO mapping
+      "function subdaoToRegistry(address) view returns (address)",
       "function templateModule() view returns (address)",
       "function stats() view returns (uint128 totalSubDAOsCreated, uint128 totalBurnedForCreation)",
       // On-chain enumeration fallback (naming follows FactoryCoreFacet)
@@ -194,6 +196,7 @@ var require_abi = __commonJS({
     var ERC20Votes = [
       "function balanceOf(address) view returns (uint256)",
       "function getVotes(address) view returns (uint256)",
+      "function getPastVotes(address,uint256) view returns (uint256)",
       "function allowance(address,address) view returns (uint256)",
       "function delegate(address)",
       "function delegates(address) view returns (address)",
@@ -377,7 +380,7 @@ var require_description = __commonJS({
 // src/governance/index.js
 var require_governance = __commonJS({
   "src/governance/index.js"(exports2, module2) {
-    var { Contract, Interface, getAddress, hexlify, keccak256, toUtf8Bytes } = require("ethers");
+    var { Contract, Interface, AbiCoder, getAddress, hexlify, keccak256, toUtf8Bytes } = require("ethers");
     var ABI = require_abi();
     var { BigIntZero } = require_types();
     var { SageSDKError, CODES } = require_errors();
@@ -518,6 +521,15 @@ var require_governance = __commonJS({
     function hashDescription(description) {
       return keccak256(toUtf8Bytes(String(description)));
     }
+    function computeProposalIdHex({ targets = [], values = [], calldatas = [], description = "" }) {
+      const coder = AbiCoder.defaultAbiCoder();
+      const t = targets.map((a) => getAddress(a));
+      const v = values.map((value) => BigInt(String(value)));
+      const c = calldatas.map((data) => hexlify(data));
+      const descHash = hashDescription(description);
+      const encoded = coder.encode(["address[]", "uint256[]", "bytes[]", "bytes32"], [t, v, c, descHash]);
+      return keccak256(encoded);
+    }
     function buildProposeTx({ governor, targets = [], values = [], calldatas = [], descriptionOrHash = "" }) {
       const addr = normaliseGovernor(governor);
       const iface = new Interface(ABI.Governor);
@@ -594,6 +606,73 @@ var require_governance = __commonJS({
       const tag = latest > 0 ? BigInt(latest - 1) : 0n;
       return getQuorumAt({ provider, governor, blockTag: tag });
     }
+    async function getVotesLatestMinusOne({ provider, token: token2, governor, account }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      if (!token2 && !governor) throw new SageSDKError(CODES.INVALID_ARGS, "token or governor required");
+      if (!account) throw new SageSDKError(CODES.INVALID_ARGS, "account required");
+      let addr;
+      if (token2) {
+        addr = getAddress(token2);
+      } else {
+        const govAddr = normaliseGovernor(governor);
+        try {
+          const iface = new Interface(["function sxxxToken() view returns (address)"]);
+          const data = iface.encodeFunctionData("sxxxToken", []);
+          const ret = await provider.call({ to: govAddr, data });
+          const [tok] = AbiCoder.defaultAbiCoder().decode(["address"], ret);
+          addr = getAddress(tok);
+        } catch (err) {
+          throw new SageSDKError(CODES.NOT_FOUND, "failed to resolve governance token from governor", { cause: err });
+        }
+      }
+      const user = getAddress(account);
+      const latest = await provider.getBlockNumber();
+      const snapshot = latest > 0 ? BigInt(latest - 1) : 0n;
+      try {
+        const iface = new Interface(["function getPastVotes(address,uint256) view returns (uint256)"]);
+        const data = iface.encodeFunctionData("getPastVotes", [user, snapshot]);
+        const ret = await provider.call({ to: addr, data });
+        if (ret && ret !== "0x") {
+          const [val] = AbiCoder.defaultAbiCoder().decode(["uint256"], ret);
+          return BigInt(val.toString());
+        }
+      } catch (_) {
+      }
+      try {
+        const iface2 = new Interface(["function getVotes(address) view returns (uint256)"]);
+        const d2 = iface2.encodeFunctionData("getVotes", [user]);
+        const ret2 = await provider.call({ to: addr, data: d2 });
+        if (ret2 && ret2 !== "0x") {
+          const [val2] = AbiCoder.defaultAbiCoder().decode(["uint256"], ret2);
+          return BigInt(val2.toString());
+        }
+      } catch (_) {
+      }
+      return 0n;
+    }
+    async function simulatePropose({ provider, governor, targets = [], values = [], calldatas = [], description = "", sender }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      const addr = normaliseGovernor(governor);
+      const iface = new Interface(ABI.Governor);
+      const salted = makeProposalDescription(String(description || ""));
+      const t = targets.map((a) => getAddress(a));
+      const v = values.map((value) => BigInt(String(value)));
+      const c = calldatas.map((data2) => hexlify(data2));
+      let data;
+      try {
+        data = iface.encodeFunctionData("propose(address[],uint256[],bytes[],string)", [t, v, c, salted]);
+      } catch (err) {
+        return { ok: false, error: { type: "EncodeError", message: String(err && err.message || err) } };
+      }
+      try {
+        await provider.call({ to: addr, data, from: sender ? getAddress(sender) : void 0 });
+        return { ok: true };
+      } catch (err) {
+        let message = "execution reverted";
+        if (err && err.message) message = err.message;
+        return { ok: false, error: { type: "Revert", message } };
+      }
+    }
     async function detectGovernorOverloads({ provider, governor }) {
       if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
       const addr = normaliseGovernor(governor);
@@ -643,6 +722,25 @@ var require_governance = __commonJS({
       detectGovernorOverloads,
       buildDelegateTx,
       buildDelegateSelfTx,
+      computeProposalIdHex,
+      getVotesLatestMinusOne,
+      simulatePropose,
+      /**
+       * Explicit arrays+bytes32 builder for propose-by-hash governors or deterministic descriptions.
+       */
+      buildProposeTxByHash: function buildProposeTxByHash({ governor, targets = [], values = [], calldatas = [], descriptionHash }) {
+        const addr = normaliseGovernor(governor);
+        const iface = new Interface(ABI.Governor);
+        const t = targets.map((a) => getAddress(a));
+        const v = values.map((value) => BigInt(String(value)));
+        const c = calldatas.map((data2) => hexlify(data2));
+        const dh = typeof descriptionHash === "string" && /^0x[0-9a-fA-F]{64}$/.test(descriptionHash) ? descriptionHash : hashDescription(String(descriptionHash || ""));
+        if (t.length !== v.length || t.length !== c.length) {
+          throw new SageSDKError(CODES.INVALID_ARGS, "targets, values, calldatas length mismatch");
+        }
+        const data = iface.encodeFunctionData("propose(address[],uint256[],bytes[],bytes32)", [t, v, c, dh]);
+        return { to: addr, data, value: BigIntZero };
+      },
       /**
        * Detect governance mode and operator status.
        * Heuristics mirror CLI detectGovMode.
@@ -2169,11 +2267,24 @@ var require_factory = __commonJS({
       }
       return out;
     }
+    async function getSubDAORegistry({ provider, factory: factory2, subdao: subdao2 }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      const addr = normalise(factory2, "factory");
+      const contract = new Contract(addr, ABI.FactoryRead, provider);
+      try {
+        const mapped = await contract.subdaoToRegistry(normalise(subdao2, "subdao"));
+        const zero = "0x0000000000000000000000000000000000000000";
+        return mapped && mapped !== zero ? getAddress(mapped) : null;
+      } catch (_) {
+        return null;
+      }
+    }
     module2.exports = {
       getFactoryConfig,
       getFactoryStats,
       listSubDAOs,
       listSubDAOsIndexed,
+      getSubDAORegistry,
       listTemplates,
       getTemplateDetails,
       buildCreateSubDAOTx,
@@ -3100,7 +3211,20 @@ var require_library = __commonJS({
       hasScopedOwnership,
       buildUpdateLibraryForSubDAOTx,
       searchRegistry,
-      validation
+      validation,
+      /** Simulate calling a registry function as the timelock to verify authority/roles */
+      simulateAsTimelock: async function simulateAsTimelock({ provider, registry, to, data, timelock: timelock2 }) {
+        if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+        const reg = normalise(registry, "registry");
+        const tgt = to ? normalise(to, "to") : reg;
+        const from = normalise(timelock2, "timelock");
+        try {
+          await provider.call({ to: tgt, data, from });
+          return { ok: true };
+        } catch (err) {
+          return { ok: false, error: { type: "Revert", message: String(err && err.message || err) } };
+        }
+      }
     };
   }
 });

package/dist/index.mjs

@@ -20,7 +20,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@sage-protocol/sdk",
-      version: "0.0.5",
+      version: "0.0.7",
       description: "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
       main: "dist/index.cjs",
       module: "dist/index.mjs",
@@ -113,6 +113,8 @@ var require_abi = __commonJS({
       "function simpleKeyStoreAddress() view returns (address)",
       "function governanceConfigAddress() view returns (address)",
       "function libraryRegistryAddress() view returns (address)",
+      // Canonical per‑SubDAO mapping
+      "function subdaoToRegistry(address) view returns (address)",
       "function templateModule() view returns (address)",
       "function stats() view returns (uint128 totalSubDAOsCreated, uint128 totalBurnedForCreation)",
       // On-chain enumeration fallback (naming follows FactoryCoreFacet)
@@ -200,6 +202,7 @@ var require_abi = __commonJS({
     var ERC20Votes = [
       "function balanceOf(address) view returns (uint256)",
       "function getVotes(address) view returns (uint256)",
+      "function getPastVotes(address,uint256) view returns (uint256)",
       "function allowance(address,address) view returns (uint256)",
       "function delegate(address)",
       "function delegates(address) view returns (address)",
@@ -383,7 +386,7 @@ var require_description = __commonJS({
 // src/governance/index.js
 var require_governance = __commonJS({
   "src/governance/index.js"(exports, module) {
-    var { Contract, Interface, getAddress, hexlify, keccak256, toUtf8Bytes } = __require("ethers");
+    var { Contract, Interface, AbiCoder, getAddress, hexlify, keccak256, toUtf8Bytes } = __require("ethers");
     var ABI = require_abi();
     var { BigIntZero } = require_types();
     var { SageSDKError, CODES } = require_errors();
@@ -524,6 +527,15 @@ var require_governance = __commonJS({
     function hashDescription(description) {
       return keccak256(toUtf8Bytes(String(description)));
     }
+    function computeProposalIdHex({ targets = [], values = [], calldatas = [], description = "" }) {
+      const coder = AbiCoder.defaultAbiCoder();
+      const t = targets.map((a) => getAddress(a));
+      const v = values.map((value) => BigInt(String(value)));
+      const c = calldatas.map((data) => hexlify(data));
+      const descHash = hashDescription(description);
+      const encoded = coder.encode(["address[]", "uint256[]", "bytes[]", "bytes32"], [t, v, c, descHash]);
+      return keccak256(encoded);
+    }
     function buildProposeTx({ governor, targets = [], values = [], calldatas = [], descriptionOrHash = "" }) {
       const addr = normaliseGovernor(governor);
       const iface = new Interface(ABI.Governor);
@@ -600,6 +612,73 @@ var require_governance = __commonJS({
       const tag = latest > 0 ? BigInt(latest - 1) : 0n;
       return getQuorumAt({ provider, governor, blockTag: tag });
     }
+    async function getVotesLatestMinusOne({ provider, token, governor, account }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      if (!token && !governor) throw new SageSDKError(CODES.INVALID_ARGS, "token or governor required");
+      if (!account) throw new SageSDKError(CODES.INVALID_ARGS, "account required");
+      let addr;
+      if (token) {
+        addr = getAddress(token);
+      } else {
+        const govAddr = normaliseGovernor(governor);
+        try {
+          const iface = new Interface(["function sxxxToken() view returns (address)"]);
+          const data = iface.encodeFunctionData("sxxxToken", []);
+          const ret = await provider.call({ to: govAddr, data });
+          const [tok] = AbiCoder.defaultAbiCoder().decode(["address"], ret);
+          addr = getAddress(tok);
+        } catch (err) {
+          throw new SageSDKError(CODES.NOT_FOUND, "failed to resolve governance token from governor", { cause: err });
+        }
+      }
+      const user = getAddress(account);
+      const latest = await provider.getBlockNumber();
+      const snapshot = latest > 0 ? BigInt(latest - 1) : 0n;
+      try {
+        const iface = new Interface(["function getPastVotes(address,uint256) view returns (uint256)"]);
+        const data = iface.encodeFunctionData("getPastVotes", [user, snapshot]);
+        const ret = await provider.call({ to: addr, data });
+        if (ret && ret !== "0x") {
+          const [val] = AbiCoder.defaultAbiCoder().decode(["uint256"], ret);
+          return BigInt(val.toString());
+        }
+      } catch (_) {
+      }
+      try {
+        const iface2 = new Interface(["function getVotes(address) view returns (uint256)"]);
+        const d2 = iface2.encodeFunctionData("getVotes", [user]);
+        const ret2 = await provider.call({ to: addr, data: d2 });
+        if (ret2 && ret2 !== "0x") {
+          const [val2] = AbiCoder.defaultAbiCoder().decode(["uint256"], ret2);
+          return BigInt(val2.toString());
+        }
+      } catch (_) {
+      }
+      return 0n;
+    }
+    async function simulatePropose({ provider, governor, targets = [], values = [], calldatas = [], description = "", sender }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      const addr = normaliseGovernor(governor);
+      const iface = new Interface(ABI.Governor);
+      const salted = makeProposalDescription(String(description || ""));
+      const t = targets.map((a) => getAddress(a));
+      const v = values.map((value) => BigInt(String(value)));
+      const c = calldatas.map((data2) => hexlify(data2));
+      let data;
+      try {
+        data = iface.encodeFunctionData("propose(address[],uint256[],bytes[],string)", [t, v, c, salted]);
+      } catch (err) {
+        return { ok: false, error: { type: "EncodeError", message: String(err && err.message || err) } };
+      }
+      try {
+        await provider.call({ to: addr, data, from: sender ? getAddress(sender) : void 0 });
+        return { ok: true };
+      } catch (err) {
+        let message = "execution reverted";
+        if (err && err.message) message = err.message;
+        return { ok: false, error: { type: "Revert", message } };
+      }
+    }
     async function detectGovernorOverloads({ provider, governor }) {
       if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
       const addr = normaliseGovernor(governor);
@@ -649,6 +728,25 @@ var require_governance = __commonJS({
       detectGovernorOverloads,
       buildDelegateTx,
       buildDelegateSelfTx,
+      computeProposalIdHex,
+      getVotesLatestMinusOne,
+      simulatePropose,
+      /**
+       * Explicit arrays+bytes32 builder for propose-by-hash governors or deterministic descriptions.
+       */
+      buildProposeTxByHash: function buildProposeTxByHash({ governor, targets = [], values = [], calldatas = [], descriptionHash }) {
+        const addr = normaliseGovernor(governor);
+        const iface = new Interface(ABI.Governor);
+        const t = targets.map((a) => getAddress(a));
+        const v = values.map((value) => BigInt(String(value)));
+        const c = calldatas.map((data2) => hexlify(data2));
+        const dh = typeof descriptionHash === "string" && /^0x[0-9a-fA-F]{64}$/.test(descriptionHash) ? descriptionHash : hashDescription(String(descriptionHash || ""));
+        if (t.length !== v.length || t.length !== c.length) {
+          throw new SageSDKError(CODES.INVALID_ARGS, "targets, values, calldatas length mismatch");
+        }
+        const data = iface.encodeFunctionData("propose(address[],uint256[],bytes[],bytes32)", [t, v, c, dh]);
+        return { to: addr, data, value: BigIntZero };
+      },
       /**
        * Detect governance mode and operator status.
        * Heuristics mirror CLI detectGovMode.
@@ -2175,11 +2273,24 @@ var require_factory = __commonJS({
       }
       return out;
     }
+    async function getSubDAORegistry({ provider, factory, subdao }) {
+      if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+      const addr = normalise(factory, "factory");
+      const contract = new Contract(addr, ABI.FactoryRead, provider);
+      try {
+        const mapped = await contract.subdaoToRegistry(normalise(subdao, "subdao"));
+        const zero = "0x0000000000000000000000000000000000000000";
+        return mapped && mapped !== zero ? getAddress(mapped) : null;
+      } catch (_) {
+        return null;
+      }
+    }
     module.exports = {
       getFactoryConfig,
       getFactoryStats,
       listSubDAOs,
       listSubDAOsIndexed,
+      getSubDAORegistry,
       listTemplates,
       getTemplateDetails,
       buildCreateSubDAOTx,
@@ -3106,7 +3217,20 @@ var require_library = __commonJS({
       hasScopedOwnership,
       buildUpdateLibraryForSubDAOTx,
       searchRegistry,
-      validation
+      validation,
+      /** Simulate calling a registry function as the timelock to verify authority/roles */
+      simulateAsTimelock: async function simulateAsTimelock({ provider, registry, to, data, timelock }) {
+        if (!provider) throw new SageSDKError(CODES.INVALID_ARGS, "provider required");
+        const reg = normalise(registry, "registry");
+        const tgt = to ? normalise(to, "to") : reg;
+        const from = normalise(timelock, "timelock");
+        try {
+          await provider.call({ to: tgt, data, from });
+          return { ok: true };
+        } catch (err) {
+          return { ok: false, error: { type: "Revert", message: String(err && err.message || err) } };
+        }
+      }
     };
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/sdk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",