@sage-protocol/sdk 0.0.3

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sage-protocol/sdk",
+  "version": "0.0.3",
+  "description": "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "types/index.d.ts",
+  "type": "commonjs",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json",
+    "./types/*": "./types/*"
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sage-protocol/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sage-protocol/sdk/issues"
+  },
+  "homepage": "https://github.com/sage-protocol/sdk#readme",
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "clean": "rm -rf dist",
+    "test": "yarn build && node --test \"tests/**/*.test.js\"",
+    "release": "yarn build && npm publish --workspace @sage-protocol/sdk"
+  },
+  "dependencies": {
+    "@merit-systems/echo-typescript-sdk": "^1.0.17",
+    "@whetstone-research/doppler-sdk": "^0.0.1-alpha.40",
+    "ai": "^3.2.3",
+    "axios": "^1.11.0",
+    "ethers": "^6.15.0",
+    "viem": "^2.33.2"
+  },
+  "devDependencies": {
+    "proxyquire": "^2.1.3",
+    "sinon": "^17.0.1",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.0"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,418 @@
+import type { BigNumberish } from 'ethers';
+
+export type AddressLike = string;
+export type HashLike = string;
+
+export interface ProviderLike {
+  getNetwork?: (...args: any[]) => Promise<any> | any;
+}
+
+export interface TransactionPayload {
+  to: AddressLike;
+  data: string;
+  value: bigint;
+}
+
+export interface ProposalTuple {
+  id: bigint;
+  governor: AddressLike;
+  targets: AddressLike[];
+  values: bigint[];
+  calldatas: string[];
+  description: string;
+  descriptionHash: string;
+  createdBlock: number | bigint | null;
+}
+
+export interface ProposalCacheAdapter {
+  load(governor: AddressLike, proposalId: bigint): Promise<ProposalTuple | null> | ProposalTuple | null;
+  save(governor: AddressLike, proposalId: bigint, tuple: ProposalTuple): Promise<void> | void;
+}
+
+export interface ProposalQueueResult {
+  receipt: any;
+  tuple: ProposalTuple;
+  viaTimelock?: boolean;
+}
+
+export interface ProposalPreflightSummary {
+  governor: AddressLike;
+  proposer: AddressLike | null;
+  config: {
+    proposalThreshold: bigint | null;
+    votingDelay: bigint | null;
+    votingPeriod: bigint | null;
+    proposalCooldown: bigint | null;
+  };
+  cooldown: {
+    remainingSeconds: number | null;
+  };
+  subdao: AddressLike | null;
+  governanceMode: number | null;
+  eligibleMember: boolean | null;
+  stake: {
+    token: AddressLike | null;
+    requiredWei: bigint | null;
+    balanceWei: bigint | null;
+    allowanceWei: bigint | null;
+    governorAuthorizedBurner: boolean | null;
+  };
+  timelock: AddressLike | null;
+}
+
+export interface TimelockRoleCheck {
+  contract: AddressLike;
+  role?: string;
+  hasRole?: boolean;
+  error?: string;
+}
+
+export interface GovernanceOperationsModule {
+  resolveProposalTuple(args: {
+    provider: ProviderLike;
+    governor: AddressLike;
+    proposalId: bigint | number | string;
+    refresh?: boolean;
+    cache?: ProposalCacheAdapter | null;
+    fromBlock?: number | bigint | string;
+  }): Promise<ProposalTuple>;
+  queueProposal(args: {
+    provider: ProviderLike;
+    signer: any;
+    governor: AddressLike;
+    proposalId: bigint | number | string;
+    timelock?: AddressLike | null;
+    cache?: ProposalCacheAdapter | null;
+    refresh?: boolean;
+    waitMs?: number;
+  }): Promise<ProposalQueueResult>;
+  executeProposal(args: {
+    provider: ProviderLike;
+    signer: any;
+    governor: AddressLike;
+    proposalId: bigint | number | string;
+    timelock?: AddressLike | null;
+    cache?: ProposalCacheAdapter | null;
+    refresh?: boolean;
+    waitMs?: number;
+  }): Promise<ProposalQueueResult>;
+  preflightProposal(args: {
+    provider: ProviderLike;
+    signer?: any;
+    governor: AddressLike;
+    timelock?: AddressLike | null;
+    subdao?: AddressLike | null;
+    sxxxToken?: AddressLike | null;
+  }): Promise<ProposalPreflightSummary>;
+  getProposalDetails(args: {
+    provider: ProviderLike;
+    governor: AddressLike;
+    proposalId: bigint | number | string;
+    refresh?: boolean;
+    cache?: ProposalCacheAdapter | null;
+    includeTimeline?: boolean;
+  }): Promise<ProposalTuple & {
+    stateRaw: number | null;
+    state: string | number | null;
+    snapshot: string | null;
+    deadline: string | null;
+    votes: {
+      against: bigint;
+      for: bigint;
+      abstain: bigint;
+    };
+    quorum: string | null;
+    timeline: Array<Record<string, any>>;
+  }>;
+  ensureTimelockRoles(args: {
+    provider: ProviderLike;
+    timelock: AddressLike;
+    registries?: AddressLike[];
+  }): Promise<TimelockRoleCheck[]>;
+}
+
+export interface GovernanceModule {
+  operations: GovernanceOperationsModule;
+  [key: string]: any;
+}
+
+export interface IpfsUploadResult {
+  cid: string;
+  provider: string | null;
+  response?: any;
+}
+
+export interface IpfsClient {
+  config: Record<string, any>;
+  hasPinataCreds(): boolean;
+  shouldUseWorker(): boolean;
+  resolveProviderOrder(preference?: string | string[]): string[];
+  uploadPrompt(args: {
+    prompt: {
+      name?: string;
+      description?: string;
+      content: any;
+      timestamp?: number;
+      version?: string;
+      files?: string[];
+    };
+    providers?: string[] | string;
+    provider?: string;
+    warm?: boolean;
+    gateways?: string[] | string;
+  }): Promise<IpfsUploadResult>;
+  uploadJson(payload: any, name?: string, options?: {
+    providers?: string[] | string;
+    provider?: string;
+    warm?: boolean;
+    gateways?: string[] | string;
+  }): Promise<IpfsUploadResult>;
+  uploadText(text: string, name?: string, options?: {
+    providers?: string[] | string;
+    provider?: string;
+    warm?: boolean;
+    gateways?: string[] | string;
+  }): Promise<IpfsUploadResult>;
+  downloadJson(args: { cid: string; gateways?: string[] | string; headers?: Record<string, string> }): Promise<any>;
+  warmGateways(cid: string, options?: { gateways?: string[] | string; timeoutMs?: number; concurrency?: number }): Promise<{ warmed: string[] }>;
+  buildGatewayUrls(cid: string, extra?: string[] | string): string[];
+  pin(args: { cids: string | string[]; warm?: boolean; gateways?: string[] | string }): Promise<any>;
+  generateCid(payload: any): string;
+}
+
+export interface IpfsModule {
+  DEFAULT_GATEWAY: string;
+  createClient(options?: {
+    provider?: string;
+    gateway?: string;
+    timeoutMs?: number;
+    retries?: number;
+    shouldWarm?: boolean;
+    testMode?: boolean;
+    pinataApiUrl?: string;
+    pinataApiKey?: string;
+    pinataSecretKey?: string;
+    pinataJwt?: string;
+    workerUploadUrl?: string;
+    workerUploadToken?: string;
+    web3Token?: string;
+    env?: Record<string, string | undefined>;
+  } & Record<string, any>): IpfsClient;
+  buildGatewayUrls(cid: string, gatewayBase?: string, extraGateways?: string[] | string): string[];
+  normalizeCidV1Base32(cid: string): string;
+}
+
+export interface ManifestLintError {
+  keyword: string;
+  instancePath: string;
+  message: string;
+  schemaPath?: string;
+  params?: Record<string, any>;
+}
+
+export interface ManifestLintResult {
+  ok: boolean;
+  versionOk: boolean;
+  missingSchema: boolean;
+  schemaPath: string | null;
+  errors: ManifestLintError[];
+  hints: string[];
+  manifestPath?: string | null;
+  version?: string | number | null;
+}
+
+export interface ManifestValidator {
+  loadSchema(): { schema: any | null; schemaPath: string | null };
+  lintManifest(manifest: any, options?: { enforceVersion?: boolean; manifestPath?: string | null }): ManifestLintResult;
+  lintManifestFile(manifestPath: string, options?: { enforceVersion?: boolean }): ManifestLintResult;
+  bestPracticeCheck(manifest: any, options?: { manifestPath?: string | null }): Array<Record<string, any>>;
+  bestPracticeCheckFile(manifestPath: string): Array<Record<string, any>>;
+}
+
+export interface LibrarySearchResult {
+  type: 'library' | 'prompt';
+  name: string;
+  description: string;
+  cid: string;
+  promptCount?: number;
+  tags?: string[];
+  key?: string;
+}
+
+export interface LibrarySearchResponse {
+  results: LibrarySearchResult[];
+  warnings: string[];
+  stats: { candidates: number; manifests: number };
+}
+
+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>;
+  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;
+  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 };
+}
+
+export interface TokenModule {
+  getBalance(args: { provider: ProviderLike; token: AddressLike; account: AddressLike }): Promise<bigint>;
+  getVotes(args: { provider: ProviderLike; token: AddressLike; account: AddressLike }): Promise<bigint>;
+  getTotalSupply(args: { provider: ProviderLike; token: AddressLike }): Promise<bigint>;
+  getAllowance(args: { provider: ProviderLike; token: AddressLike; owner: AddressLike; spender: AddressLike }): Promise<bigint>;
+  getDelegates(args: { provider: ProviderLike; token: AddressLike; account: AddressLike }): Promise<AddressLike>;
+  canCreateProposal(args: { provider: ProviderLike; token: AddressLike; account: AddressLike }): Promise<boolean>;
+  getProposalBurnMin(args: { provider: ProviderLike; token: AddressLike }): Promise<bigint>;
+  getTotalBurned(args: { provider: ProviderLike; token: AddressLike }): Promise<bigint>;
+  buildApproveTx(args: { token: AddressLike; spender: AddressLike; amount: BigNumberish }): TransactionPayload;
+  buildDelegateTx(args: { token: AddressLike; delegatee: AddressLike }): TransactionPayload;
+  buildAuthorizeBurnerTx(args: { token: AddressLike; burner: AddressLike }): TransactionPayload;
+  getAuthorizedBurners(args: { provider: ProviderLike; token: AddressLike; fromBlock?: number | bigint | string; toBlock?: number | bigint | string }): Promise<{
+    token: AddressLike;
+    burners: AddressLike[];
+    events: Array<{
+      type: 'authorized' | 'revoked';
+      burner: AddressLike;
+      blockNumber: number;
+      transactionHash: HashLike;
+      logIndex: number;
+    }>;
+  }>;
+  getBurnConstants(): {
+    PROPOSAL_BURN_MIN: bigint;
+    PROPOSAL_BURN_MAX: bigint;
+    SUBDAO_BURN_MIN: bigint;
+    SUBDAO_BURN_MAX: bigint;
+    FORK_BURN_MIN: bigint;
+    FORK_BURN_MAX: bigint;
+  };
+}
+
+export interface TreasuryInfo {
+  treasury: AddressLike;
+  totalReserves: bigint;
+  totalPOL: bigint;
+  totalDebt: bigint;
+  canonicalPool: AddressLike | null;
+  routerOrVault: AddressLike | null;
+  maxWithdrawalRate: bigint | null;
+  emergencyWithdrawalLimit: bigint | null;
+}
+
+export interface TreasuryModule {
+  getTreasuryInfo(args: { provider: ProviderLike; treasury: AddressLike }): Promise<TreasuryInfo>;
+  getPendingWithdrawals(args: { provider: ProviderLike; treasury: AddressLike; ids?: number[]; limit?: number }): Promise<Array<{
+    id: number;
+    token: AddressLike | null;
+    recipient: AddressLike | null;
+    amount: bigint;
+    value: bigint;
+    requester: AddressLike | null;
+    balanceBefore: bigint;
+    recipientBalanceBefore: bigint;
+    depositSnapshot: bigint;
+    isLP: boolean;
+    isEmergency: boolean;
+  }>>;
+  getCanonicalLiquidityPlans(args: { provider: ProviderLike; treasury: AddressLike; fromBlock?: number | bigint | string; toBlock?: number | bigint | string }): Promise<{
+    updates: Array<{ pool: AddressLike; routerOrVault: AddressLike; blockNumber: number; transactionHash: HashLike }>;
+    adds: Array<{
+      subdao: AddressLike;
+      pool: AddressLike;
+      sxxxToken: AddressLike;
+      stableToken: AddressLike;
+      sxxxAmount: bigint;
+      stableAmount: bigint;
+      lpRecipient: AddressLike;
+      blockNumber: number;
+      transactionHash: HashLike;
+    }>;
+    removes: Array<{
+      subdao: AddressLike;
+      pool: AddressLike;
+      lpToken: AddressLike;
+      lpAmount: bigint;
+      recipient: AddressLike;
+      blockNumber: number;
+      transactionHash: HashLike;
+    }>;
+  }>;
+  getLPContribution(args: { provider: ProviderLike; treasury: AddressLike; subdao: AddressLike; token: AddressLike }): Promise<bigint>;
+}
+
+export interface BoostModule {
+  getMerkleConfig(args: { provider: ProviderLike; manager: AddressLike; proposalId: number | bigint }): Promise<{
+    manager: AddressLike;
+    proposalId: number;
+    token: AddressLike | null;
+    totalAmount: bigint;
+    startTime: number;
+    endTime: number;
+    merkleRoot: bigint;
+  } | null>;
+  buildMerkleFundTx(args: { manager: AddressLike; proposalId: number | bigint; amount: BigNumberish }): TransactionPayload;
+  buildMerkleSetRootTx(args: { manager: AddressLike; proposalId: number | bigint; merkleRoot: BigNumberish }): TransactionPayload;
+  getDirectConfig(args: { provider: ProviderLike; manager: AddressLike; proposalId: number | bigint }): Promise<{
+    manager: AddressLike;
+    proposalId: number;
+    token: AddressLike | null;
+    perVoter: bigint;
+    maxVoters: bigint;
+    startTime: number;
+    endTime: number;
+  } | null>;
+  buildDirectCreateTx(args: { manager: AddressLike; proposalId: number | bigint; token: AddressLike; perVoter: BigNumberish; maxVoters: BigNumberish }): TransactionPayload;
+  buildDirectFundTx(args: { manager: AddressLike; proposalId: number | bigint; amount: BigNumberish }): TransactionPayload;
+}
+
+export interface PersonalModule {
+  buildCreatePersonalRegistryTx(args: { factory: AddressLike; policy: number }): TransactionPayload;
+  buildSetPriceTx(args: { marketplace: AddressLike; key: string; price: BigNumberish }): TransactionPayload;
+  buildBuyTx(args: {
+    marketplace: AddressLike;
+    creator: AddressLike;
+    key: string;
+    expectedPrice: BigNumberish;
+    deadline: BigNumberish;
+  }): TransactionPayload;
+  computeReceiptId(creator: AddressLike, key: string): bigint;
+  getReceiptBalance(args: {
+    provider: ProviderLike;
+    receipt: AddressLike;
+    holder: AddressLike;
+    receiptId: bigint | number | string;
+  }): Promise<bigint>;
+}
+
+export interface SageSDK {
+  version: string;
+  getProvider: (rpcUrl: string) => any;
+  abi: Record<string, any>;
+  governance: Record<string, any>;
+  subdao: Record<string, any>;
+  timelock: Record<string, any>;
+  factory: Record<string, any>;
+  library: LibraryModule;
+  prompt: Record<string, any>;
+  wallet: {
+    session: {
+      DEFAULT_WALLET_TYPE: string;
+      resolveWalletType(args?: { config?: any; env?: Record<string, any> }): string;
+      shouldAllowInsecurePrivateKey(env?: Record<string, any>): boolean;
+      persistWalletContext(args: { config: any; account: string; type: string }): boolean;
+    };
+    [key: string]: any;
+  };
+  walletTyped: Record<string, any>;
+  ipfs: IpfsModule;
+  token: TokenModule;
+  treasury: TreasuryModule;
+  boost: BoostModule;
+  personal: PersonalModule;
+  subgraph: Record<string, any>;
+  errors: Record<string, any>;
+  resolveGovernanceContext: (args: any) => Promise<any>;
+}
+
+declare const sdk: SageSDK;
+export = sdk;