Adapters

Every read in @seedprotocol/query goes through a data source: an object that lists Seeds and fetches their Versions and property attestations. There are two slots, remote (EAS, always available) and local (empty until something registers a source), and the source option on each call picks between them.

import { registerLocalQuerySource, type QueryDataSource } from '@seedprotocol/query'

Choosing a source

Pass source to queryBySchema, getSeed, getSeeds or queryBySchemaForMonth:

import { queryBySchema, getSeed } from '@seedprotocol/query'

const local = await queryBySchema('post', { source: 'local' })
const post = await getSeed('0xfd8c50ca131b725c288be7f46e4abe0c7b06f1226e98f552642edde8280ad900', { source: 'auto' })

Fallback rules

'local' never falls back. With no local source registered it throws:

[query] source: "local" requires registerLocalQuerySource(...) (e.g. SDK DB ready)

'auto':

• No local source registered: behaves exactly like 'remote', cache and etag included.
• queryBySchema and queryBySchemaForMonth: reads the local source. If that returns no items at all, the whole call is repeated against EAS with the same limit, skip, uidPrefix and attesters. One local item is enough to stay local, so a partly synced collection isn't topped up from EAS.
• getSeed: reads the local source. If it doesn't have the Seed, or has it with no Version from its attester, reads EAS (using the item cache). If it has the Seed with a Version, EAS isn't asked: a Seed whose Versions were all revoked returns null.
• getSeeds: reads every Seed from the local source, then reads the ones it doesn't have, or has with no Version, from EAS in one batch (using the item cache). The others are never read from EAS, as with getSeed.
• Results read locally have no etag.

The local source from the SDK

The SDK registers its SQLite database as the local source when client.init finishes, and clears it on client.stop() and client.unload(). From then on source: 'local' and 'auto' read the published items its EAS sync brought in: those of the client's owned and watched addresses. To read another publisher's items locally, add their address as a watched address and let a sync run; see Sync a user's data to another device.

@seedprotocol/sdk also exports helpers around it:

The SDK's source takes revocation from the database's revoked_at columns, which unpublishing sets before EAS's indexer catches up, so a local read can leave out an item that a remote read still returns. It also leaves out Seeds marked for deletion and Seeds whose Versions were all revoked. See Read published data for a full example, and Querying for reading the local database directly.

registerLocalQuerySource

Puts a source in the local slot, replacing whatever was there.

function registerLocalQuerySource(source: QueryDataSource): void
function clearLocalQuerySource(): void
function getRegisteredLocalQuerySource(): QueryDataSource | null
function hasLocalQuerySource(): boolean

The source must have kind: 'local'; anything else throws [query] registerLocalQuerySource expects a source with kind: "local". There's one slot per process, and the remote slot can't be replaced. Reads with source: 'local' don't check for a second copy of @seedprotocol/eas or @seedprotocol/arweave; 'auto' reads do, and throw if there is one (see Troubleshooting). To read from a different indexer, set EAS_ENDPOINT instead (see environment variables).

QueryDataSource

The interface a source implements. Every method returns attestations in the shape EAS's GraphQL API uses.

type QueryDataSource = {
  readonly kind: 'remote' | 'local'

  getSeedByUid(seedUid: string): Promise<AttestationLike | null>
  listSeedsBySchemaName(schemaName: string, opts: { limit: number; skip: number } & SeedListFilter): Promise<AttestationLike[]>
  listSeedsBySchemaNameForMonth(schemaName: string, year: number, month: number): Promise<AttestationLike[]>
  getVersionsForSeed(seedUid: string): Promise<AttestationLike[]>
  getVersionsForSeeds(seedUids: string[], opts?: { includeRevoked?: boolean }): Promise<AttestationLike[]>
  getPropertiesForVersionUids(versionUids: string[]): Promise<AttestationLike[]>
  getSeedsByUids(uids: string[]): Promise<AttestationLike[]>

  listChangesSince?(opts: { refUIDs: string[]; ids: string[]; since: number }): Promise<AttestationChange[]>
  readStorageBody?(ref: { propertyName: string; value: unknown; localPathHint?: string }): Promise<string | null>
}

type SeedListFilter = {
  uidPrefix?: string             // '0x' plus lowercase hex
  attesters?: readonly string[]  // lowercase addresses, at least one
}

type AttestationLike = {
  id: string
  decodedDataJson: string
  refUID: string
  schemaId: string
  timeCreated: number
  attester?: string
  schema?: { schemaNames?: Array<{ name: string }> }
  revoked?: boolean
}

A source doesn't have to filter Versions and properties by attester: the query layer keeps only Versions attested by their Seed's attester, and properties attested by their Version's attester, so return each attestation's attester when you have it. Attestations without one are kept.

createRemoteQueryDataSource() returns a new instance of the built-in EAS source and getRemoteQueryDataSource() the shared one. Both are useful to wrap, as below.

Example: one publisher's items

To list one account's Seeds in one call, pass attesters to queryBySchema. To keep every listing to one account whatever the call passes, register a source that adds the account to the EAS request and reuses the remote source for everything else. It reads uidPrefix and attesters from opts, so those options still filter:

import { EasClient, GET_SEEDS_LEAN, withExcludeRevokedFilter } from '@seedprotocol/eas'
import {
  createRemoteQueryDataSource,
  registerLocalQuerySource,
  queryBySchema,
  type AttestationLike,
  type QueryDataSource,
} from '@seedprotocol/query'

const publisher = '0xE870B14fCfF4A408e6eCb65Bd40f64d08859Efb3' // as EAS stores it: checksummed
const remote = createRemoteQueryDataSource()

const onePublisher: QueryDataSource = {
  ...remote,
  kind: 'local',
  async listSeedsBySchemaName(schemaName, { limit, skip, uidPrefix, attesters }) {
    if (attesters && !attesters.includes(publisher.toLowerCase())) return []
    const where = withExcludeRevokedFilter({
      attester: { equals: publisher },
      ...(uidPrefix ? { id: { startsWith: uidPrefix } } : {}),
      schema: { is: { schemaNames: { some: { name: { equals: schemaName } } } } },
    })
    const { itemSeeds } = await EasClient.getEasClient().request(GET_SEEDS_LEAN, { where, take: limit, skip })
    return itemSeeds.map(
      (seed): AttestationLike => ({ ...seed, schema: { schemaNames: [{ name: schemaName }] } }),
    )
  },
}

registerLocalQuerySource(onePublisher)

const { items } = await queryBySchema('post', { source: 'local', limit: 20 })

The query layer registers the EAS client before it calls the source, so EasClient.getEasClient() is ready inside the method. Reads through this source aren't cached, because it's in the local slot. Month listings (queryBySchemaForMonth) still return every publisher's Seeds unless you override listSeedsBySchemaNameForMonth too.

resolveQuerySource

Returns the source a call would use, without reading anything.

function resolveQuerySource(mode?: QuerySourceMode): {
  mode: QuerySourceMode
  dataSource: QueryDataSource
  useQueryCache: boolean
}
function normalizeSourceMode(source?: QuerySourceMode): QuerySourceMode // undefined → 'remote'

mode defaults to 'remote'. For 'local' without a registered source it throws, as above. For 'auto' it returns the local source when one is registered, otherwise the remote one; the per-call fallback described above happens later.

Browser and Node

The data sources are the same in both builds. The differences are around them:

In a browser app that runs the SDK, prefer the local source (or getPublishedSeedRecord from @seedprotocol/sdk): it reads what the app has already synced and needs no network. Use 'remote' for items no one in the app watches.

Related

• @seedprotocol/query overview: queryBySchema, getSeed, getSeeds, the record shape and caching
• Read published data: remote and local reads in practice
• Sync a user's data to another device: what ends up in the local database
• @seedprotocol/eas: the attestation queries behind the remote source