@sage-protocol/sdk 0.0.6 → 0.0.8

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
 ----------------------
 
@@ -174,6 +212,36 @@ const tx = await sdk.governance.buildDelegateSelfTx({ provider, governor, accoun
 // send via userOp (CDP) or EOA
 ```
 
+Votes token resolution and gates
+```js
+// Resolve the IVotes token used for proposals
+const votesToken = await sdk.governance.resolveVotesToken({ provider, governor });
+
+// Build preferred self-delegate using resolved token
+const del = await sdk.governance.buildDelegateSelfPreferred({ provider, governor, account: user });
+
+// Delegate and verify votes (no throw)
+const res = await sdk.governance.delegateSelfAndVerify({ provider, governor, account: user, signer, minVotes: 1n });
+// → { txHash, ok, votes, payload }
+
+// Readiness to propose (preflight)
+const gates = await sdk.governance.ensureProposeGates({ provider, governor, proposer: user });
+// Optionally include execution check (registry update as timelock)
+const ready = await sdk.governance.readinessToPropose({
+  provider,
+  governor,
+  proposer: user,
+  execution: { registry, timelock, subdao, libraryId: 'main', manifestCID, promptCount: 12 },
+});
+```
+
+Subgraph normalization
+```js
+// listProposalsFiltered now returns both state (string) and stateNum (0–7)
+const items = await sdk.subgraph.listProposalsFiltered({ url: SUBGRAPH_URL, governor });
+// item.state → 'PENDING' | 'ACTIVE' | ... ; item.stateNum → 0..7 or null when unknown
+```
+
 Proposal timeline (subgraph)
 ```js
 const t = await sdk.subgraph.getProposalTimeline({ url: SUBGRAPH_URL, id: idHexOrDecimal });