@seedprotocol/eas

@seedprotocol/eas reads attestations from an EAS indexer's GraphQL API, by default https://optimism-sepolia.easscan.org/graphql. It returns raw attestations: Seeds, their Versions and their property attestations, with values still encoded in decodedDataJson. The SDK and @seedprotocol/query are built on it. Most apps should use @seedprotocol/query, which turns the same data into JSON items; reach for this package when you want the attestations themselves, for example to list one account's Seeds, check revocation or read history.

import { getSeedsBySchemaName, getItemVersionsFromEas } from '@seedprotocol/eas'
import { registerNodeEasPlatform } from '@seedprotocol/eas/node'

It only reads. Writing attestations is done by @seedprotocol/publish.

Install

npm install @seedprotocol/eas

It has no Seed dependencies and no peer dependencies, and on Node it needs 20.18.1 or later. Its undici dependency is loaded only by @seedprotocol/eas/node. @seedprotocol/query and the SDK install it for you, pinned to their own exact version, so in an app that has them, install it at their version (npm install @seedprotocol/eas@<that version>); a second copy makes @seedprotocol/query throw DuplicateEasModuleError (one version for every package).

Entry points

There is no /react entry. When client.init runs, the SDK registers DefaultEasClient and DefaultQueryClient from this package (on Node, NodeEasClient instead of DefaultEasClient), and the functions on this page then work against them. Without the SDK, call ensureEasPlatform() (below), which works in browsers and Node.

registerNodeEasPlatform

Registers the Node GraphQL client and request cache that every query function uses.

function registerNodeEasPlatform(options?: { easClient?: NodeEasClientOptions }): void

Importing @seedprotocol/eas/node already registers them as a side effect, so calling the function is optional but makes the dependency explicit. Pass easClient options (NodeEasClientOptions, below) to change the client's connection settings. Each call registers a new client, replacing the one before. Without any registration, query functions throw EasClient not configured. Import from @seedprotocol/eas/node ….

The Node request cache shares one request between concurrent identical calls and keeps nothing once a request settles, so every call reads fresh data. A request the indexer doesn't answer within 30 seconds (EAS_REQUEST_TIMEOUT_MS) rejects with TimeoutError: EAS indexer request timed out after 30000 ms. Requests aren't retried.

NodeEasClient sends its requests through its own undici Agent, made on the first request, which offers only the X25519:P-256 TLS key exchange groups (EAS_NODE_ECDH_CURVE) and keeps idle connections open for 30 seconds (EAS_NODE_KEEP_ALIVE_TIMEOUT_MS). Node's own fetch closes idle connections after 4 seconds, and from Node 24.21 it also offers a post-quantum group that easscan doesn't support, which slows every new connection's handshake. The process's TLS defaults and fetch's global dispatcher aren't changed. No Agent is made under Bun or Deno, or when the host has replaced fetch's global dispatcher with something other than an Agent (a proxy agent, NODE_USE_ENV_PROXY, a MockAgent); requests then go through fetch's default. @seedprotocol/eas/node needs Node 20.18.1 or later on Node 20, and 22.3 or later on Node 22.

import { registerNodeEasPlatform } from '@seedprotocol/eas/node'
import { getSeedsBySchemaName } from '@seedprotocol/eas'

registerNodeEasPlatform()

const seeds = await getSeedsBySchemaName('post', 5)
for (const seed of seeds) console.log(seed.id, seed.attester, new Date(seed.timeCreated * 1000).toISOString())

NodeEasClientOptions:

createEasNodeDispatcher(options?: { ecdhCurve?, keepAliveTimeoutMs? }) returns a promise that resolves to that Agent, or to undefined where none is made, so await it. It was synchronous before 0.7.13. It loads undici's Agent with a dynamic import from @seedprotocol/eas itself, so a bundler resolves undici from this package rather than from your app. NodeEasClient makes its dispatcher once, on the first request, and every request waits for it. To hold the Agent yourself, for example to close it on shutdown, make it and pass it in:

import { createEasNodeDispatcher, registerNodeEasPlatform } from '@seedprotocol/eas/node'

const agent = await createEasNodeDispatcher({ keepAliveTimeoutMs: 60_000 })
registerNodeEasPlatform({ easClient: { dispatcher: agent ?? false } })

export async function shutdown() {
  await agent?.close()
}

import { registerNodeEasPlatform } from '@seedprotocol/eas/node'

// Send EAS requests through fetch's global dispatcher, e.g. a proxy agent you installed
registerNodeEasPlatform({ easClient: { dispatcher: false } })

ensureEasPlatform

Registers the default fetch-based clients, DefaultEasClient and DefaultQueryClient, for whichever of the two slots has nothing registered yet. Clients already registered, such as the SDK's, are left in place. DefaultEasClient's requests have the same 30-second limit as the Node client's and use fetch's default connection handling. @seedprotocol/query calls it before its first read; on Node, query first registers a NodeEasClient when no EAS client is registered.

function ensureEasPlatform(): void

Use it instead of registerNodeEasPlatform when code may run next to the SDK or in a browser: registerNodeEasPlatform always replaces whatever is registered.

import { ensureEasPlatform, getSeedsBySchemaName } from '@seedprotocol/eas'

ensureEasPlatform()
const seeds = await getSeedsBySchemaName('post', 5)
console.log(seeds.length)

Chain and endpoint

Reads go to one chain's indexer, which defaults to OP Sepolia (chain ID 11155420), the testnet Seed Protocol runs on. Other chains have no Seed data, because Seed's contracts aren't deployed anywhere else.

const DEFAULT_EAS_CHAIN_ID = 11155420

function getEasReadChainId(): number
function getEasEndpoint(): string

getEasReadChainId returns the first of these that's set:

1. The SDK's config.eas.chainId
2. @seedprotocol/publish's chain
3. The chain the SDK's local database already holds data from
4. The EAS_CHAIN_ID or NEXT_PUBLIC_EAS_CHAIN_ID environment variable
5. 11155420

The SDK and publish must agree: configuring different chains throws Seed Protocol chain mismatch.

getEasEndpoint returns, in order: the SDK's config.eas.indexerUrl; the EAS_ENDPOINT or NEXT_PUBLIC_EAS_ENDPOINT environment variable (also read from window.env in a browser); the chosen chain's known easscan indexer. It throws when the environment URL is a known indexer for a different chain, and when the chain has no known indexer and none is configured. The endpoint is read on every request, so configuration applied after import takes effect.

In a script without the SDK, set the environment variables:

# Read Base Sepolia's indexer instead
EAS_CHAIN_ID=84532 node read.mjs

# Use your own indexer for the default chain
EAS_ENDPOINT=https://eas-indexer.example.com/graphql node read.mjs

Known deployments

EAS_CHAIN_DEPLOYMENTS lists the chains with a known EAS deployment, keyed by chain ID. Each entry is an EasChainDeployment:

interface EasChainDeployment {
  chainId: number
  name: string
  easContractAddress: `0x${string}`
  schemaRegistryAddress: `0x${string}`
  indexerUrl?: string
  explorerUrl?: string
  testnet?: boolean
}

OP Stack chains use the EAS predeploys, exported as OP_STACK_EAS_CONTRACT_ADDRESS (0x4200…0021) and OP_STACK_SCHEMA_REGISTRY_ADDRESS (0x4200…0020).

configureEasReadChain, expectEasReadChain, isEasReadChainSettled, isEasReadChainConfigured, whenEasReadChainSettled and resetEasReadChain are how the SDK and publish package set the chain. Don't call them from app code; use SeedConfig.eas or the environment variables.

Schema lookups

Every Seed model has its own EAS schema, bytes32 <name>, where <name> is the model's EAS name (post, blog_post, html_page), and each property has a schema such as string title. Most queries need the schema's UID.

getEasSchemaUidForExactDefinition

The UID of the schema whose definition is exactly the string you pass, such as a property schema (string title) or a model's Seed schema (bytes32 post).

function getEasSchemaUidForExactDefinition(schemaDefinition: string): Promise<string | undefined>

It returns undefined when there's no such schema. Found UIDs are cached for the process, per EAS endpoint, and misses for five minutes (SCHEMA_LOOKUP_MISS_TTL_MS). A UID recorded with setSchemaUidForSchemaDefinition, as publish does for each schema it registers, answers without a request, before the indexer has the schema. It throws when the request fails.

import '@seedprotocol/eas/node'
import { getEasSchemaUidForExactDefinition } from '@seedprotocol/eas'

const postSchemaUid = await getEasSchemaUidForExactDefinition('bytes32 post')

Model schemas

A model's Seed schema can be published under more than one EAS name: SDKs before 0.7.4 wrote HTMLPage as htmlpage, and a model's nameMatch level decides which names it accepts. These functions find every Seed schema a model can match in one request.

type ModelSchemaLookup = { name: string; level?: NameMatchLevel }
type EasModelSchemaMatch = { schema: EASSchema; modelName: string; tier: NameMatchTier }

function getEasModelSchemasForNames(models: readonly ModelSchemaLookup[]): Promise<EasModelSchemaMatch[]>
function fetchEasModelSchemas(models: readonly ModelSchemaLookup[]): Promise<EASSchema[]>
function matchEasModelSchemas(schemas: readonly EASSchema[], models: readonly ModelSchemaLookup[]): EasModelSchemaMatch[]
function modelSchemaDefinition(modelName: string): string

fetchEasModelSchemas asks for every bytes32 <name> schema whose name is in easNamesToFetch for each model at its level ('fuzzy' by default; at 'exact' only bytes32 <easName>). matchEasModelSchemas says which model each schema is for and at which tier: the tightest tier wins, a tie between models matches nothing, and schemas no model matches are left out. A match at tier 'exact' is the schema new Seeds are published under; looser matches are schemas older SDKs published under. getEasModelSchemasForNames does both. They return [] when the clients aren't configured and throw when the request fails. modelSchemaDefinition(name) is bytes32 <easName(name)>.

import '@seedprotocol/eas/node'
import { getEasModelSchemasForNames } from '@seedprotocol/eas'

const matches = await getEasModelSchemasForNames([{ name: 'BlogPost' }, { name: 'HTMLPage', level: 'exact' }])
for (const m of matches) console.log(m.modelName, m.schema.schema, m.schema.id, m.tier)

EAS names

easName is the function the SDK and @seedprotocol/publish use to turn a model or property name into the name written to EAS (ADR 0008). It splits words where a lowercase letter or digit meets a capital and before the last capital of an acronym, turns any other run of non-alphanumeric characters into _, trims and lowercases.

function easName(name: string): string

easName('BlogPost')  // 'blog_post'
easName('HTMLPage')  // 'html_page'
easName('ID3Tag')    // 'id3_tag'
easName('New model') // 'new_model'

SDKs before 0.7.4 published acronyms without the split (HTMLPage as htmlpage). To read names written by any version, match instead of converting back:

Types: NameMatchLevel and NameMatchTier ('exact' | 'normalized' | 'fuzzy'), NameMatchCandidate<T>, NameMatchResult<T>. A schema file sets the level per model or property with nameMatch.

getSchemaNamesBySchemaUids

The registered names of schemas, by UID.

function getSchemaNamesBySchemaUids(schemaUids: string[]): Promise<Map<string, string[]>>

Schemas without a name are left out. Found names are cached for the process; resetSchemaNamesCache() clears the cache.

Reading Seeds

A Seed attestation is an item's permanent identity. Its id is the item's Seed UID, its schemaId is the model's schema, and its attester is the publisher.

getSeedsBySchemaName

Seeds of one model, newest first, with revoked Seeds left out.

function getSeedsBySchemaName(
  schemaName: string,
  limit?: number,
  skip?: number,
  options?: { uidPrefix?: string; attesters?: readonly string[] },
): Promise<Attestation[]>

This matches the schema's name, not its definition, so 'post' finds the Seed schema. The name belongs to the model, not to an app, so it returns every publisher's Seeds. Each result has schema.schemaNames set to the name you passed. getSeedUidsBySchemaName(schemaName, limit?) returns just the UIDs.

getSeedsFromSchemaUids

Seeds of the given schemas published by the given accounts, newest first.

function getSeedsFromSchemaUids(args: {
  schemaUids: string[]
  addresses: string[]
  excludeRevoked?: boolean // default true
}): Promise<Attestation[]>

Addresses are checksummed for you, and values that aren't 20-byte hex addresses are dropped, so a list of only such values matches nothing. The same goes for the address lists of getPublishedByFromEas, getDomainOwnershipFromEas and getPublishAuthorizationFromEas. There's no limit: it returns every match.

import '@seedprotocol/eas/node'
import { getEasSchemaUidForExactDefinition, getSeedsFromSchemaUids } from '@seedprotocol/eas'

const postSchemaUid = await getEasSchemaUidForExactDefinition('bytes32 post')
if (!postSchemaUid) throw new Error('No Post schema on this chain')

const seeds = await getSeedsFromSchemaUids({
  schemaUids: [postSchemaUid],
  addresses: ['0x1234567890abcdef1234567890abcdef12345678'],
})
console.log(seeds.length, 'posts from this publisher')

getSeedsByUidsFromEas

Seeds by UID, newest first, with schema.schemaNames filled in.

function getSeedsByUidsFromEas(args: { uids: string[]; excludeRevoked?: boolean }): Promise<Attestation[]>

excludeRevoked defaults to true. An empty list returns [] without a request.

Reading Versions and properties

A Version attestation references its Seed (refUID is the Seed UID), and each property attestation references its Version. Property values are in decodedDataJson, a JSON string of { name, type, signature, value } entries. Values that live on Arweave (Html bodies, files) are stored there as references, not inline; @seedprotocol/query resolves them for you.

The indexer gives an integer value as a JSON number or numeric string when it's small, and as { type: 'BigNumber', hex } when it's wide (uint256). Seed publishes a Number property as a decimal string and a Date as uint256 Unix seconds. These functions read them:

getItemVersionsFromEas and getItemPropertiesFromEas

excludeRevoked defaults to true. Edits published as patches add more property attestations to the same Version, so several can share a Version and schema.

getCanonicalItemPropertiesFromEas

One property attestation per Version and property schema: the newest non-revoked one from the right account.

function getCanonicalItemPropertiesFromEas(args: {
  versionUids: string[]
  excludeRevoked?: boolean // default true
  checkAttesters?: boolean // default true
}): Promise<Attestation[]>

With checkAttesters, a Version counts only if its Seed's attester made it, and a property only if its Version's attester did. That costs two more requests, for the Versions and their Seeds. A property whose Version or Seed the indexer doesn't return is dropped, since there's nothing to check it against. checkAttesters: false skips the check and the two requests, and keeps the newest attestation whoever made it, so another account's property on a trusted Version can still win.

pickLatestPropertyAttestationsByRefAndSchema(attestations, options?) makes the same newest-per-schema pick on a list you already have, without checking attesters. It skips revoked attestations; pass { ifAllRevoked: 'newestRevoked' } to keep the newest revoked one where every attestation for a schema is revoked.

An item's current values, from its publisher only:

import '@seedprotocol/eas/node'
import { getItemVersionsFromEas, getCanonicalItemPropertiesFromEas } from '@seedprotocol/eas'

const seedUid = process.argv[2]!
const versions = await getItemVersionsFromEas({ seedUids: [seedUid] })
const properties = await getCanonicalItemPropertiesFromEas({ versionUids: versions.map((v) => v.id) })

for (const p of properties) {
  const [field] = JSON.parse(p.decodedDataJson) as { name: string; value: { value: unknown } }[]
  if (field) console.log(field.name, field.value.value)
}

getAttestationChangesSince

Attestations created or revoked after a time, for checking whether cached data is still current.

function getAttestationChangesSince(args: {
  refUIDs: string[]
  ids: string[]
  since: number // Unix seconds
}): Promise<AttestationChange[]>

type AttestationChange = { id: string; refUID: string; timeCreated: number; revocationTime: number }

It returns attestations that reference one of refUIDs (new or revoked Versions of a Seed, properties of a Version) or are one of ids (a revoked Seed), created or revoked after since. Long lists are split into requests of 400 UIDs. revocationTime is 0 when not revoked.

Attestation type

Query functions return the indexer's Attestation type (generated from the easscan schema). The fields Seed's queries select:

EASSchema (the indexer's Schema type) and SchemaWhereInput are exported too.

GraphQL documents

The queries are exported as typed GraphQL documents, for your own requests through BaseEasClient.getEasClient().request(...): GET_SCHEMAS, GET_SCHEMA_BY_NAME, GET_SEEDS, GET_SEEDS_LEAN (without the slow schema join), GET_SEED_IDS, GET_VERSIONS, GET_PROPERTIES, GET_ALL_PROPERTIES_FOR_ALL_VERSIONS, GET_FILES_METADATA, GET_IMAGE_SEEDS, GET_IMAGE_VERSIONS, GET_STORAGE_TRANSACTION_ID, GET_ATTESTATION_CHANGES, GET_DOMAIN_OWNERSHIPS (DomainOwnership attestations, with expirationTime) and GET_PUBLISH_AUTHORIZATIONS (PublishAuthorization attestations, with expirationTime and revoked). Each takes a where: AttestationWhereInput (or SchemaWhereInput); withExcludeRevokedFilter(where) adds revoked: false to one.

import '@seedprotocol/eas/node'
import { BaseEasClient, GET_SCHEMAS } from '@seedprotocol/eas'

const { schemas } = await BaseEasClient.getEasClient().request(GET_SCHEMAS, {
  where: { schema: { equals: 'string title' } },
})
console.log(schemas.map((s) => s.id))

Client classes

To run these functions somewhere the SDK doesn't, implement IEasClient (getEasClient(): GraphQLClient) and IQueryClientFactory and pass them to configure. Build the GraphQLClient with createEasGraphQLClient(url) to keep the 30-second limit; a plain new GraphQLClient(url) has none. BaseEasClient.getSeedsBySchemaName is deprecated and always throws; use the getSeedsBySchemaName function.

Timing log

Set DEBUG=seedEas:timing (in a browser, localStorage.debug = 'seedEas:timing') to log every indexer request. It's off by default. Each request through createEasGraphQLClient logs request <operation> <filters> rows=<n> bytes=<n> <ms>ms, where <filters> gives the length of each id.in or refUID.in list, or (failed: <error name>) in place of the counts. Each lookup through the query functions' request cache logs fetchQuery <key> network|deduped|cache <ms>ms: network when it sent the request, deduped when it waited on the same request already in flight, cache when the cache answered.

seedEas:timing request GetSchemas rows=1 bytes=122 12ms
seedEas:timing request GetSchemas 504ms (failed: TimeoutError)

One copy of the package

The registered clients live in module state, and assertSingleEasModule() throws DuplicateEasModuleError when they were registered through another copy of this package; @seedprotocol/query calls it before every read. When two copies happen and how to fix it is in query's troubleshooting.

UID and address helpers

Constants: ZERO_ADDRESS, ZERO_BYTES ('0x') and ZERO_BYTES32, and the Version schema, VERSION_SCHEMA_DEF ('bytes32 version') and its UID VERSION_SCHEMA_UID (0x13c0fd59d69dbce40501a41f8b37768d26dd2e2bb0cad64615334d84f7b9bdf6, the same on every chain).

The schema UID cache the SDK uses (getEasSchemaUidForSchemaDefinition, getSchemaUidForSchemaDefinitionFromCache, setSchemaUidForSchemaDefinition, setSchemaUidForModel, getSchemaUidForModelFromCache, cachedSchemaLookup, clearSchemaLookupMisses, resetSchemaUidCaches) is exported but is SDK plumbing; app code doesn't need it. getEasSchemaUidForSchemaDefinition is getEasSchemaUidForExactDefinition returning undefined when the request fails, and getSchemaUidForSchemaDefinitionFromCache reads the same cache without a request. All three take the exact definition (string title).

Tool attestations

Tools that publish for users can add tool attestations next to the Seed: who published it (seedprotocol.publishedBy), a domain ownership claim (seedprotocol.domainOwnership), and a publish authorization grant (seedprotocol.publishAuthorization). This package has the read and verify side; @seedprotocol/publish writes them.

Domain ownership covers the flow.

Related

• Read published Seed data: reading with @seedprotocol/query, and raw attestations with this package
• @seedprotocol/query: published items as JSON
• EAS indexing: how the indexer fits in
• The data model: Seeds, Versions and properties
• Client and configuration: SeedConfig.eas
• @seedprotocol/arweave: the content side