Sage Protocol SDK

Backend-agnostic helpers for interacting with Sage Protocol contracts, IPFS, and governance systems.

npm i @sage-protocol/sdk

Quick Start

import sdk from '@sage-protocol/sdk';

const provider = sdk.getProvider({ rpcUrl: 'https://base-sepolia.publicnode.com' });

// Discover SubDAOs
const subdaos = await sdk.subdao.discoverSubDAOs({
  provider,
  factoryAddress: '0x89Fd9FfD04503A62c52E6769401AB928abbeD5cA',
  fromBlock: 0,
});

// Fetch SubDAO info
const info = await sdk.subdao.getSubDAOInfo({ provider, subdao: subdaos[0].subdao });

CommonJS

const sdk = require('@sage-protocol/sdk');

Module Overview

| Module | Description | |--------|-------------| | getProvider() | Minimal ethers v6 RPC helper | | governance | Governor metadata, proposals, voting | | timelock | Queue operations, scheduling | | factory | SubDAO creation and forking | | library | Manifest listings, ownership | | lineage | Fork ancestry, per-library fees | | prompt | Prompt metadata, usage counters | | ipfs | Upload, discovery, worker APIs | | 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 | | adapters | Normalized governance adapters | | errors | SageSDKError codes |

Services

SubgraphService

import { services } from '@sage-protocol/sdk';

const subgraphService = new services.SubgraphService({
  url: 'https://api.studio.thegraph.com/query/your-subgraph',
  timeout: 10000,
  retries: 3,
  cache: { enabled: true, ttl: 30000 },
});

const subdaos = await subgraphService.getSubDAOs({ limit: 50 });
const proposals = await subgraphService.getProposals({
  governor: '0xGovernor',
  states: ['ACTIVE', 'PENDING'],
});

IPFSService

import { services } from '@sage-protocol/sdk';

const ipfsService = new services.IPFSService({
  workerBaseUrl: 'https://api.sageprotocol.io',
  gateway: 'https://ipfs.io',
  signer: yourSigner, // Optional for uploads
});

// Fetch (parallel gateway race)
const content = await ipfsService.fetchByCID('QmTest123...');

// Upload
const cid = await ipfsService.upload(
  { title: 'My Prompt', content: '...' },
  { name: 'prompt.json', warm: true }
);

Common Operations

Governance

// Compute proposal ID
const idHex = sdk.governance.computeProposalIdHex({ targets, values, calldatas, description });

// Preflight simulation
const pre = await sdk.governance.simulatePropose({ provider, governor, targets, values, calldatas, description, sender });

// Get votes
const votes = await sdk.governance.getVotesLatestMinusOne({ provider, governor, account: user });

// Self-delegate
const tx = await sdk.governance.buildDelegateSelfTx({ provider, governor, account: user });

SubDAO Creation

// Create operator SubDAO (team-controlled)
const res = await sdk.subdao.createOperatorSubDAO({
  signer,
  factoryAddress: FACTORY,
  operator: '0xSafeOrEOA',
  name: 'My SubDAO',
  description: 'Team controlled',
  burnAmount: 1500n * 10n**18n,
  sxxx: SXXX,
});

Note: if you call the factory's operator-creation functions directly (e.g., createSubDAOOperator*), you must pass a non-zero operatorAdmin (it may be the same as operatorExecutor).

Library Fork Fees

// Get fork fee for a library
const fee = await sdk.lineage.getLibraryForkFee({ provider, registry, subdao });

// Get full library info
const info = await sdk.lineage.getLibraryInfo({ provider, registry, subdao });

React Hooks

Requires react and swr peer dependencies:

import { services, hooks } from '@sage-protocol/sdk';

function SubDAOList() {
  const { data, error, isLoading } = hooks.useSubDAOs(subgraphService, { limit: 50 });

  if (isLoading) return <div>Loading...</div>;
  return <ul>{data.map(s => <li key={s.id}>{s.name}</li>)}</ul>;
}

function PromptViewer({ cid }) {
  const { data } = hooks.useFetchCID(ipfsService, cid);
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

| Hook | Description | |------|-------------| | useSubDAOs | Fetch SubDAOs from subgraph | | useProposals | Fetch proposals from subgraph | | useFetchCID | Fetch IPFS content by CID | | useUpload | Upload content to IPFS |

Error Handling

import { serviceErrors } from '@sage-protocol/sdk';

try {
  const data = await subgraphService.getSubDAOs({ limit: 50 });
} catch (error) {
  if (error instanceof serviceErrors.SubgraphError) {
    console.error(`[${error.code}]:`, error.message);
  }
}

Environment Variables

# Private transaction relay
SAGE_PRIVATE_RPC=https://builder.your-relay.example/rpc

# Explorer API (for ABI resolution)
NEXT_PUBLIC_ETHERSCAN_API_KEY=YourKey

Design Principles

• Pure data in/out; no console prompts or environment coupling
• Minimal ABI fragments maintained alongside contracts
• Composable modules - import only what you need
• Edge runtime compatible (uses fetch())

Documentation

• Full Docs

License

Apache 2.0