Skip to content

Subgraph and Discovery API

Use this guide when you need to read governance/library state for apps, scripts, or analytics.

Read Path Rule

Client read path is:

Contracts -> Subgraph -> Worker REST -> CLI / SDK / Web / Agents

Do not build new CLI/SDK integrations that query subgraph GraphQL directly.

Why This Exists

  • Subgraph indexes chain events into queryable entities.
  • Worker adds caching and stable REST surfaces.
  • Client tools stay consistent and avoid expensive direct chain/subgraph fan-out.

Endpoint Strategy

Use worker APIs exposed by your environment.

Examples of route families (environment dependent):

  • /governance/*
  • /subdaos/*
  • /proposals/*
  • /discover/*

For diagnostics and analytics

Use Goldsky GraphQL endpoints.

Pattern:

https://api.goldsky.com/api/public/<project>/subgraphs/sage-protocol/<version>/gn

Avoid hardcoding versions in production clients. Treat this as operational/analytics access.

Core Entities (Current Shape)

SubDAO

type SubDAO {
  id: ID!
  address: Bytes!
  name: String
  description: String
  profileCID: String
  governor: Bytes!
  timelock: Bytes!
  memberCount: BigInt!
  createdAt: BigInt!
  updatedAt: BigInt!
  governanceKind: Int
  proposalAccess: Int
  executionAccess: Int
  playbook: String
}

Proposal

type Proposal {
  id: ID!
  governor: Bytes!
  title: String
  description: String
  proposer: Bytes!
  state: String!
  forVotes: BigInt!
  againstVotes: BigInt!
  abstainVotes: BigInt!
  startBlock: BigInt!
  endBlock: BigInt!
  eta: BigInt
}

LibraryPrompt

type LibraryPrompt {
  id: ID!
  subdao: Bytes!
  key: String!
  cid: String
  name: String
  description: String
  manifestCID: String!
  updatedAt: BigInt!
}

Common Queries

List DAOs

query ListDAOs($first: Int!) {
  subDAOs(first: $first, orderBy: createdAt, orderDirection: desc) {
    id
    name
    description
    governor
    timelock
    memberCount
    playbook
    governanceKind
    proposalAccess
    executionAccess
  }
}

DAO Proposals

query GetProposals($governor: Bytes!, $first: Int!) {
  proposals(
    where: { governor: $governor }
    first: $first
    orderBy: createdAt
    orderDirection: desc
  ) {
    id
    title
    state
    proposer
    forVotes
    againstVotes
    abstainVotes
    startBlock
    endBlock
  }
}

Library Prompts for DAO

query LibraryPrompts($subdao: Bytes!, $first: Int!) {
  libraryPrompts(
    where: { subdao: $subdao }
    first: $first
    orderBy: updatedAt
    orderDirection: desc
  ) {
    key
    name
    cid
    manifestCID
    updatedAt
  }
}

Freshness Expectations

  • Subgraph and worker data can lag chain head.
  • A successful transaction may take time to appear in discovery surfaces.
  • Treat execution success as canonical, then wait for indexing propagation.