@sage-protocol/sdk 0.1.18 → 0.1.23

package/package.json

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

package/types/index.d.ts

@@ -131,8 +131,204 @@ export interface GovernanceOperationsModule {
   }): Promise<TimelockRoleCheck[]>;
 }
 
+export interface VotesTokenDescription {
+  votingToken: AddressLike;
+  baseToken: AddressLike;
+  isWrapper: boolean;
+  multiplierNFT: AddressLike | null;
+  basis: bigint | null;
+  description: string;
+}
+
+// ============ Governance Profile Types (3-Axis Model) ============
+
+export type GovernanceKind = 'operator' | 'token';
+export type ProposalAccess = 'council-only' | 'community-threshold';
+export type ExecutionAccess = 'council-only' | 'anyone';
+export type GovernancePlaybook = 'council-closed' | 'council-drafts' | 'community' | 'legacy' | 'custom';
+
+export interface GovernanceProfile {
+  /** Profile version: 1=legacy (detected via heuristics), 2=explicit 3-axis profile */
+  version: 1 | 2;
+  /** OPERATOR (council/EOA decides) or TOKEN (ERC20Votes snapshot) */
+  governanceKind: GovernanceKind | null;
+  /** COUNCIL_ONLY (only COUNCIL_ROLE) or COMMUNITY_THRESHOLD (token holders >= threshold) */
+  proposalAccess: ProposalAccess | null;
+  /** COUNCIL_ONLY (only council can execute) or ANYONE (public execution) */
+  executionAccess: ExecutionAccess | null;
+  /** Derived playbook name for UX */
+  playbook: GovernancePlaybook;
+  /** True if proposals require COUNCIL_ROLE */
+  isCouncil: boolean;
+  /** True if SXXX stake is required to propose (TOKEN + COMMUNITY_THRESHOLD only) */
+  requiresStake: boolean;
+}
+
+export interface GovernanceModeDetectionResult extends GovernanceProfile {
+  /** Legacy operator flag */
+  operator: boolean;
+  /** Legacy governance mode label */
+  governance: string;
+  governor: AddressLike | null;
+  timelock: AddressLike | null;
+  subdao: AddressLike | null;
+  stakeRequired: bigint | null;
+  depositWei: bigint | null;
+}
+
+export interface VotingStatus {
+  subdao: AddressLike | null;
+  governor: AddressLike;
+  stakeToken: AddressLike | null;
+  votingToken: AddressLike;
+  baseToken: AddressLike;
+  isWrapper: boolean;
+  multiplierNFT: AddressLike | null;
+  basis: bigint | null;
+  threshold: bigint | null;
+  votingPower: bigint | null;
+  tokenBalance: bigint | null;
+  delegate: AddressLike | null;
+  canPropose: boolean | null;
+  tokenMismatch: boolean;
+  stakeTokenVotes: bigint | null;
+  stakeTokenDelegate: AddressLike | null;
+  stakeTokenBalance: bigint | null;
+  description: string;
+}
+
+export interface ProposeGatesSummary {
+  threshold: bigint | null;
+  cooldown: bigint | null;
+  stake: bigint | null;
+  allowanceOk: boolean | null;
+  votesOk: boolean | null;
+  details: {
+    sxxxToken: AddressLike | null;
+    proposer: AddressLike;
+    governor: AddressLike;
+  };
+}
+
+export interface ProposeReadiness extends ProposeGatesSummary {
+  executionReady: boolean | null;
+  executionError: string | null;
+}
+
 export interface GovernanceModule {
   operations: GovernanceOperationsModule;
+  getGovernorInfo(args: { provider: ProviderLike; governor: AddressLike }): Promise<{
+    address: AddressLike;
+    name: string | null;
+    votingDelay: bigint | null;
+    votingPeriod: bigint | null;
+    proposalThreshold: bigint | null;
+    timelock: AddressLike | null;
+    sxxxToken: AddressLike | null;
+    quorumNumerator: bigint | null;
+    stakeAmount: bigint | null;
+  }>;
+  getProposal(args: { provider: ProviderLike; governor: AddressLike; id: bigint | number | string }): Promise<{
+    governor: AddressLike;
+    id: bigint;
+    state: any;
+    snapshot: bigint;
+    deadline: bigint;
+    votes: { against: bigint; for: bigint; abstain: bigint };
+  }>;
+  listProposals(args: { provider: ProviderLike; governor: AddressLike; fromBlock?: number | bigint | string; toBlock?: number | bigint | string }): Promise<ProposalTuple[]>;
+  getProposalMetadata(args: { provider: ProviderLike; governor: AddressLike; id: bigint | number | string; fromBlock?: number | bigint | string; toBlock?: number | bigint | string }): Promise<ProposalTuple & {
+    proposer: AddressLike;
+    blockNumber: number | bigint | null;
+    transactionHash: HashLike | null;
+  }>;
+  hashDescription(description: string): HashLike;
+  buildProposeTx(args: {
+    governor: AddressLike;
+    targets?: AddressLike[];
+    values?: bigint[] | BigNumberish[];
+    calldatas?: string[];
+    descriptionOrHash?: string;
+  }): TransactionPayload;
+  buildCastVoteTx(args: { governor: AddressLike; proposalId: bigint | number | string; support: number | string; reason?: string }): TransactionPayload;
+  buildQueueTx(args: {
+    governor: AddressLike;
+    targets?: AddressLike[];
+    values?: bigint[] | BigNumberish[];
+    calldatas?: string[];
+    descriptionOrHash?: string;
+  }): TransactionPayload;
+  buildExecuteTx(args: {
+    governor: AddressLike;
+    targets?: AddressLike[];
+    values?: bigint[] | BigNumberish[];
+    calldatas?: string[];
+    descriptionOrHash?: string;
+  }): TransactionPayload;
+  buildQueueByIdTx(args: { governor: AddressLike; proposalId: bigint | number | string }): TransactionPayload;
+  buildExecuteByIdTx(args: { governor: AddressLike; proposalId: bigint | number | string }): TransactionPayload;
+  decodeProposalEffects(args: {
+    provider: ProviderLike;
+    governor: AddressLike;
+    proposalId: bigint | number | string;
+    fromBlock?: number | bigint | string;
+    toBlock?: number | bigint | string;
+  }): Promise<any>;
+  getQuorumAt(args: { provider: ProviderLike; governor: AddressLike; blockTag?: bigint | number | string }): Promise<bigint | null>;
+  getQuorumLatestMinusOne(args: { provider: ProviderLike; governor: AddressLike }): Promise<bigint | null>;
+  getVotesLatestMinusOne(args: { provider: ProviderLike; token?: AddressLike; governor?: AddressLike; account: AddressLike }): Promise<bigint>;
+  simulatePropose(args: {
+    provider: ProviderLike;
+    governor: AddressLike;
+    targets?: AddressLike[];
+    values?: bigint[] | BigNumberish[];
+    calldatas?: string[];
+    description?: string;
+    sender?: AddressLike;
+  }): Promise<{ ok: boolean; error?: { type: string; message: string } }>;
+  resolveVotesToken(args: { provider: ProviderLike; subdao?: AddressLike; governor?: AddressLike }): Promise<AddressLike>;
+  resolveVotesTokenChain(args: { provider: ProviderLike; subdao?: AddressLike; governor?: AddressLike }): Promise<{
+    votingToken: AddressLike;
+    baseToken: AddressLike;
+    isWrapper: boolean;
+  }>;
+  describeVotesToken(args: { provider: ProviderLike; subdao?: AddressLike; governor?: AddressLike }): Promise<VotesTokenDescription>;
+  getVotingStatus(args: { provider: ProviderLike; subdao?: AddressLike; governor?: AddressLike; account: AddressLike }): Promise<VotingStatus>;
+  buildDelegateTx(args: { token: AddressLike; delegatee: AddressLike }): TransactionPayload;
+  buildDelegateSelfTx(args: { provider: ProviderLike; governor: AddressLike; account: AddressLike }): Promise<TransactionPayload>;
+  buildDelegateSelfPreferred(args: { provider: ProviderLike; subdao?: AddressLike; governor?: AddressLike; account: AddressLike }): Promise<TransactionPayload>;
+  delegateSelfAndVerify(args: {
+    provider: ProviderLike;
+    subdao?: AddressLike;
+    governor?: AddressLike;
+    account: AddressLike;
+    signer?: any;
+    minVotes?: bigint | number | string | null;
+  }): Promise<{ txHash: string | null; ok: boolean; votes: bigint; payload: TransactionPayload }>;
+  ensureProposeGates(args: { provider: ProviderLike; governor: AddressLike; proposer: AddressLike }): Promise<ProposeGatesSummary>;
+  readinessToPropose(args: {
+    provider: ProviderLike;
+    governor: AddressLike;
+    proposer: AddressLike;
+    execution?: {
+      provider: ProviderLike;
+      registry: AddressLike;
+      timelock: AddressLike;
+      subdao: AddressLike;
+      libraryId?: string;
+      manifestCID?: string;
+      promptCount?: bigint | number | string;
+    } | null;
+  }): Promise<ProposeReadiness>;
+  listActiveProposals(args: { url: string; governor: AddressLike; first?: number; skip?: number }): Promise<any>;
+  buildProposeTxByHash(args: {
+    governor: AddressLike;
+    targets?: AddressLike[];
+    values?: bigint[] | BigNumberish[];
+    calldatas?: string[];
+    descriptionHash: string;
+  }): TransactionPayload;
+  detectMode(args: { provider: ProviderLike; governor?: AddressLike; timelock?: AddressLike | null; subdao?: AddressLike | null }): Promise<GovernanceModeDetectionResult>;
   [key: string]: any;
 }
 
@@ -331,13 +527,13 @@ export interface LibrarySearchResponse {
 }
 
 export interface LibraryModule {
-  listManifests(args: { provider: ProviderLike; registry: AddressLike; offset?: number; limit?: number }): Promise<{ total: bigint; manifests: Array<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; }> }>;
-  getManifestInfo(args: { provider: ProviderLike; registry: AddressLike; manifestCID: string }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; }>;
-  getLatestLibrary(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike; libraryId?: string }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; } | null>;
+  listManifests(args: { provider: ProviderLike; registry: AddressLike; factoryAddress: AddressLike; offset?: number; limit?: number }): Promise<{ total: bigint; manifests: Array<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; version: string; }> }>;
+  getManifestInfo(args: { provider: ProviderLike; registry: AddressLike; manifestCID: string }): Promise<never>;
+  getLatestLibrary(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; version: string; } | null>;
   hasScopedOwnership(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike; manifestCID: string }): Promise<boolean>;
-  buildUpdateLibraryForSubDAOTx(args: { registry: AddressLike; subdao: AddressLike; manifestCID: string; promptCount?: bigint | number | string; libraryId?: string }): TransactionPayload;
+  buildUpdateLibraryTx(args: { registry: AddressLike; subdao: AddressLike; manifestCID: string; version?: string }): TransactionPayload;
   buildAuthorizeTimelockTx(args: { registry: AddressLike; timelock: AddressLike; subdao: AddressLike }): TransactionPayload;
-  executionReadiness(args: { provider: ProviderLike; registry: AddressLike; timelock: AddressLike; subdao: AddressLike; libraryId?: string; manifestCID?: string; promptCount?: bigint | number | string }): Promise<{ ok: boolean; error: string | null; missingRole: string | null }>;
+  executionReadiness(args: { provider: ProviderLike; registry: AddressLike; timelock: AddressLike; subdao: AddressLike; manifestCID?: string; version?: string }): Promise<{ ok: boolean; error: string | null; missingRole: string | null }>;
   searchRegistry(args: { provider: ProviderLike; registry: AddressLike; query: string; limit?: number; ipfsClient?: any; ipfsOptions?: Record<string, any>; libraryAdapter?: any; manifestFetcher?: (cid: string) => Promise<any>; }): Promise<LibrarySearchResponse>;
   validation: { createManifestValidator(options?: Record<string, any>): ManifestValidator };
 }
@@ -690,6 +886,122 @@ export interface BountySubmission {
   exists: boolean;
 }
 
+// ---- Contributions Module ----
+
+export type GovernanceModel = 'TOKEN_VOTING' | 'COUNCIL' | 'OPERATOR' | 'DIRECT';
+
+export interface PromptContribution {
+  id: string;
+  dao: AddressLike;
+  daoName: string | null;
+  promptKey: string;
+  contributor: AddressLike;
+  cid: string;
+  timestamp: number;
+  createdAt: number;
+  updatedAt: number;
+  transactionHash: string | null;
+  governanceModel: GovernanceModel;
+  proposalId: bigint | null;
+  forVotes: bigint | null;
+  againstVotes: bigint | null;
+  abstainVotes: bigint | null;
+  uniqueVoters: number | null;
+  quorum: bigint | null;
+  fromBounty: boolean;
+  bountyId: bigint | null;
+  badgeId: bigint | null;
+  badgeEvidenceURI: string | null;
+}
+
+export interface ContributionAggregates {
+  totalContributions: number;
+  uniqueContributors: number;
+  bountyOriginated: number;
+  governanceOriginated: number;
+  totalForVotes: bigint;
+  totalAgainstVotes: bigint;
+  averageVoterCount: number;
+  badgeCount: number;
+}
+
+export interface GovernanceQuality {
+  model: GovernanceModel;
+  decentralization: number;
+  consensus: number;
+  raw: Record<string, any>;
+}
+
+export interface SoulboundBadge {
+  id: string;
+  contract: AddressLike;
+  badgeId: bigint;
+  recipient: AddressLike;
+  evidenceURI: string | null;
+  blockNumber: number;
+  blockTimestamp: number;
+  transactionHash: string | null;
+}
+
+export interface ContributionsModule {
+  GovernanceModel: {
+    TOKEN_VOTING: 'TOKEN_VOTING';
+    COUNCIL: 'COUNCIL';
+    OPERATOR: 'OPERATOR';
+    DIRECT: 'DIRECT';
+  };
+
+  listContributions(args: {
+    url: string;
+    subdao?: AddressLike;
+    promptKey?: string;
+    contributor?: AddressLike;
+    fromBounty?: boolean;
+    first?: number;
+    skip?: number;
+    orderBy?: 'updatedAt' | 'createdAt';
+    orderDirection?: 'asc' | 'desc';
+  }): Promise<PromptContribution[]>;
+
+  getByPrompt(args: {
+    url: string;
+    subdao: AddressLike;
+    promptKey: string;
+  }): Promise<{ contributions: PromptContribution[]; aggregates: ContributionAggregates }>;
+
+  getById(args: {
+    url: string;
+    id: string;
+  }): Promise<PromptContribution | null>;
+
+  getByContributor(args: {
+    url: string;
+    contributor: AddressLike;
+    first?: number;
+    skip?: number;
+  }): Promise<PromptContribution[]>;
+
+  getBadgesByRecipient(args: {
+    url: string;
+    recipient: AddressLike;
+    first?: number;
+  }): Promise<SoulboundBadge[]>;
+
+  getGovernanceQuality(
+    contribution: PromptContribution,
+    context?: { totalHolders?: number; totalCouncilMembers?: number }
+  ): GovernanceQuality;
+
+  enrichWithGovernanceModel(
+    contribution: PromptContribution,
+    subdaoInfo: any
+  ): PromptContribution;
+
+  detectGovernanceModel(subdaoInfo: any): GovernanceModel;
+
+  computeAggregates(contributions: PromptContribution[]): ContributionAggregates;
+}
+
 export interface BountyModule {
   // Constants
   getMaxSubmissionsPerBounty(args: { provider: ProviderLike; bountySystem: AddressLike }): Promise<bigint>;
@@ -758,11 +1070,225 @@ export interface BountyModule {
   buildRemoveFromWhitelistTx(args: { bountySystem: AddressLike; bountyId: BigNumberish; addresses: AddressLike[] }): TransactionPayload;
 }
 
+// ============ Git Storage Client Types ============
+
+export type GitObjectType = 'blob' | 'tree' | 'commit';
+
+export interface GitObject {
+  /** Object ID (SHA-1 hash) */
+  oid: string;
+  /** Object type */
+  type: GitObjectType;
+  /** Object size in bytes */
+  size: number;
+  /** Base64 encoded object data */
+  data: string;
+}
+
+export interface GitRef {
+  /** Reference name (e.g., 'refs/heads/main') */
+  name: string;
+  /** Object ID the ref points to */
+  oid: string;
+  /** Last update timestamp */
+  updatedAt: number;
+  /** Wallet address of last updater */
+  updatedBy?: string;
+}
+
+export interface GitCommit {
+  /** Commit hash */
+  oid: string;
+  /** Tree object hash */
+  treeOid: string;
+  /** Parent commit hash */
+  parentOid?: string;
+  /** Commit message */
+  message: string;
+  /** Author name */
+  authorName?: string;
+  /** Author email */
+  authorEmail?: string;
+  /** Author wallet address */
+  authorAddress?: string;
+  /** Commit timestamp */
+  timestamp: number;
+}
+
+export interface LibraryMetadata {
+  /** SubDAO address */
+  subdao: string;
+  /** Library name */
+  name: string;
+  /** Library description */
+  description?: string;
+  /** Library visibility */
+  visibility: 'public' | 'private';
+  /** Creation timestamp */
+  createdAt: number;
+  /** Last update timestamp */
+  updatedAt: number;
+  /** Fork information */
+  forkOf?: {
+    subdao: string;
+    commit: string;
+  };
+}
+
+export interface Collaborator {
+  /** Wallet address */
+  address: string;
+  /** Permission level */
+  permission: 'read' | 'write' | 'admin';
+  /** When collaborator was added */
+  addedAt: number;
+  /** Who added the collaborator */
+  addedBy?: string;
+}
+
+export interface PushResult {
+  /** Whether push succeeded */
+  success: boolean;
+  /** New commit hash */
+  commitHash?: string;
+  /** Error message if failed */
+  error?: string;
+}
+
+export interface PushPayload {
+  /** Objects to push */
+  objects: GitObject[];
+  /** Ref updates (name -> oid) */
+  refs: Record<string, string>;
+  /** Commit message */
+  message: string;
+}
+
+export interface CloneResult {
+  /** All objects in the library */
+  objects: GitObject[];
+  /** All refs (name -> oid) */
+  refs: Record<string, string>;
+  /** Library metadata */
+  metadata: LibraryMetadata;
+}
+
+export interface FetchResult {
+  /** Objects since the given commit */
+  objects: GitObject[];
+  /** Current refs (name -> oid) */
+  refs: Record<string, string>;
+}
+
+export interface CollaboratorPermissions {
+  canRead: boolean;
+  canWrite: boolean;
+  isAdmin: boolean;
+  permission?: string;
+}
+
+export interface GitAuthProvider {
+  /** Get wallet address */
+  getAddress(): Promise<string>;
+  /** Sign a message */
+  signMessage(message: string): Promise<string>;
+}
+
+export interface GitStorageClientOptions {
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Custom headers */
+  headers?: Record<string, string>;
+  /** Ethers signer for authenticated requests */
+  signer?: GitAuthProvider | (() => Promise<GitAuthProvider>);
+  /** Custom auth provider */
+  getAuth?: () => Promise<{ address: string; signature: string; nonce: string }>;
+  /** Bearer token for authentication */
+  token?: string;
+}
+
+export interface GitStorageClient {
+  readonly baseUrl: string;
+  readonly timeout: number;
+  readonly headers: Record<string, string>;
+
+  // Library Management
+  createLibrary(subdao: string, name: string, options?: {
+    description?: string;
+    visibility?: 'public' | 'private';
+  }): Promise<LibraryMetadata>;
+
+  getLibrary(subdao: string): Promise<LibraryMetadata>;
+
+  listLibraries(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{ libraries: LibraryMetadata[]; cursor?: string }>;
+
+  deleteLibrary(subdao: string): Promise<{ ok: boolean }>;
+
+  // Git Object Operations
+  putObjects(subdao: string, objects: GitObject[]): Promise<{ stored: number }>;
+  getObject(subdao: string, oid: string): Promise<GitObject>;
+  getObjects(subdao: string, oids: string[]): Promise<{ objects: GitObject[] }>;
+
+  // Reference Operations
+  listRefs(subdao: string): Promise<{ refs: GitRef[] }>;
+  getRef(subdao: string, refName: string): Promise<GitRef>;
+  updateRef(subdao: string, refName: string, oid: string, options?: {
+    oldOid?: string;
+  }): Promise<{ ok: boolean }>;
+
+  // Sync Operations
+  push(subdao: string, payload: PushPayload): Promise<PushResult>;
+  clone(subdao: string): Promise<CloneResult>;
+  fetch(subdao: string, since?: string): Promise<FetchResult>;
+
+  // File Access
+  getHistory(subdao: string, options?: {
+    ref?: string;
+    limit?: number;
+  }): Promise<{ commits: GitCommit[] }>;
+
+  getTree(subdao: string, ref: string, path: string): Promise<{ entries: Array<{
+    name: string;
+    type: 'blob' | 'tree';
+    oid: string;
+  }> }>;
+
+  getBlob(subdao: string, ref: string, path: string): Promise<{ content: string }>;
+  getFile(subdao: string, ref: string, path: string): Promise<string>;
+
+  // Fork Operations
+  fork(sourceSubdao: string, targetSubdao: string): Promise<{ success: boolean; commitHash?: string }>;
+  getForks(subdao: string): Promise<{ forks: Array<{ subdao: string; forkedAt: number }> }>;
+  getUpstream(subdao: string): Promise<{ upstreamSubdao: string; upstreamCommit: string; forkedAt: number }>;
+
+  // Collaborator Operations
+  listCollaborators(subdao: string): Promise<{ collaborators: Collaborator[] }>;
+  addCollaborator(subdao: string, address: string, permission: 'read' | 'write' | 'admin'): Promise<{ ok: boolean }>;
+  removeCollaborator(subdao: string, address: string): Promise<{ ok: boolean }>;
+  getPermissions(subdao: string, address: string): Promise<CollaboratorPermissions>;
+
+  // High-Level Convenience Methods
+  pushManifest(subdao: string, manifest: object, message: string): Promise<PushResult>;
+  getManifest(subdao: string, ref?: string): Promise<object>;
+
+  // Cache Management
+  clearAuthCache(): void;
+}
+
+export interface GitStorageClientConstructor {
+  new (baseUrl: string, options?: GitStorageClientOptions): GitStorageClient;
+}
+
+export declare const GitStorageClient: GitStorageClientConstructor;
+
 export interface SageSDK {
   version: string;
   getProvider: (rpcUrl: string) => any;
   abi: Record<string, any>;
-  governance: Record<string, any>;
+  governance: GovernanceModule;
   subdao: Record<string, any>;
   timelock: Record<string, any>;
   factory: Record<string, any>;
@@ -791,9 +1317,17 @@ export interface SageSDK {
   votingMultiplier: VotingMultiplierModule;
   auction: AuctionModule;
   bounty: BountyModule;
+  contributions: ContributionsModule;
   subgraph: Record<string, any>;
   errors: Record<string, any>;
   resolveGovernanceContext: (args: any) => Promise<any>;
+  // Client exports
+  clients: {
+    DiscoveryClient: any;
+    GitStorageClient: GitStorageClientConstructor;
+  };
+  DiscoveryClient: any;
+  GitStorageClient: GitStorageClientConstructor;
 }
 
 declare const sdk: SageSDK;