Upgrading

This page takes an app from @seedprotocol/* 0.4.x or later to 0.8.0, newest release first.

Before you start

Upgrade every @seedprotocol/* package in one step, to the same version:

npm install @seedprotocol/sdk@0.8.0 @seedprotocol/react@0.8.0 @seedprotocol/publish@0.8.0
npm install --save-dev @seedprotocol/vite@0.8.0

Add the other @seedprotocol/* packages your app uses (query, feed, mapping, eas, arweave, gateway-hyper) at the same version. A Next.js app installs @seedprotocol/next as a dev dependency in place of @seedprotocol/vite (see Next.js apps use @seedprotocol/next). @seedprotocol/react and @seedprotocol/publish declare the exact SDK version as a peer, so npm refuses a mismatched set with ERESOLVE, and no overrides block is needed. The SDK installs XState, Drizzle and ZenFS as its own dependencies, and React Query comes with @seedprotocol/react as a peer, which npm, pnpm and bun install. Add Seed to your app has the full install step.

Then read the section for each release after the one you're on. The Changelog lists the additions and fixes that need no work.

Upgrading from 0.7.13 to 0.8.0

Released: 2026-10-30. The contracts and session-key parts come first, then the SDK and the packages around it. The Changelog lists everything else in 0.8.0.

Publishing through a ManagedAccount needs 0.8.0

Affects: every app on 0.7.13 or earlier that publishes through a ManagedAccount on OP Sepolia. Changed in: the OP Sepolia contracts, 2026-10-30, and @seedprotocol/publish 0.8.0.

On 0.7.13 such a publish reverts in the Router with Router: function does not exist., reported as PUBLISH_PREFLIGHT_FAILED, or as AUTOMATION_PREFLIGHT_FAILED for a session key. The failure comes at the attestation step, after the publish's uploads have run, so a publish can spend its uploads and still fail. Direct EAS from an EOA, reads and item.unpublish() don't touch the changed contracts and work on both releases.

0.8.0 needs those contracts too. Against contracts from before them, on a chain that wasn't redeployed or an older local twin, a publish fails with MULTI_PUBLISH_NOT_ROUTED before anything is sent, naming both selectors. It goes with contracts fb7ba92; Deployments has the addresses, and assertMultiPublishRouted makes the same check in a deploy script (Other exports).

Point the config at the new executor, reinstall and grant keys again

Affects: apps that set modularAccountModuleContract, and every session key. Changed in: the OP Sepolia contracts, 2026-10-30.

The executor is now 0xa4799d6D6AF110D5d69437488aBC31A5ef8ACA5f. With the old address in the config, an executor install and enrollPublishAutomation fail with EXECUTOR_MODULE_NOT_INSTALLED, naming both addresses, and a session-key publish fails with MULTI_PUBLISH_NOT_ROUTED.

import { initPublish } from '@seedprotocol/publish'

initPublish({
  thirdwebClientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID,
  uploadApiBaseUrl: import.meta.env.VITE_SEED_UPLOAD_API_URL,
  useModularExecutor: true,
  modularAccountModuleContract: '0x80562aeEe4F16473779b1474D8D32d114D302e94',
})

import { initPublish } from '@seedprotocol/publish'

initPublish({
  thirdwebClientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID,
  uploadApiBaseUrl: import.meta.env.VITE_SEED_UPLOAD_API_URL,
  useModularExecutor: true,
  modularAccountModuleContract: '0xa4799d6D6AF110D5d69437488aBC31A5ef8ACA5f',
})

An account that installed the old executor reads as not installed, so its admin installs again, with no uninstall step. A key is approved for one executor's address, so each key is granted again. 0.8.0 has no migration code and doesn't do either for you unattended. Interactive publishing goes through neither the executor nor a key, so an app with no session keys needs only the new address; with it set, connecting or publishing installs the executor best-effort.

For each session key, connect the user and enroll the key again. That installs the executor with the admin wallet and replaces the key's target. A key can't do this itself: until the account has the new executor, a session-key publish fails with AUTOMATION_UNSUPPORTED_ACCOUNT, and once it has, a key still approved for the old one fails with MODULAR_SIGNER_ACTIVATION_FAILED.

import { enrollPublishAutomation } from '@seedprotocol/publish/thirdweb'

export async function grantKeyAgain(managedAddress: string, sessionKeyAddress: string) {
  const { authorization } = await enrollPublishAutomation({ managedAddress, sessionKeyAddress })
  return authorization.uid // store it in place of the old uid
}

Enrolling attests a new publishAuthorization and leaves the old one in place until it expires. An app that sends through createManagedAccountTxSender gets none of this from publish: its account has to be deployed before its first publish, and it calls ensureExecutorModuleInstalled itself, which only session keys need. See After the factory moves to a new executor.

Session-key helpers take wallets and expiresAt

Affects: code that calls ensureAutomationSessionKey or ensureExecutorModuleInstalled, or imports ensureManagedSignerSessionKey, defaultApprovedTargetsForModularPublish or toThirdwebSessionKeyPermissions. Changed in: @seedprotocol/publish 0.8.0.

ensureAutomationSessionKey requires expiresAt, with no ten-year default, and refuses a time that has passed with MODULAR_SIGNER_ACTIVATION_FAILED. From JavaScript, leaving it out fails with the same code.

import { ensureAutomationSessionKey } from '@seedprotocol/publish/thirdweb'

export async function grant(managedAddress: string, sessionKeyAddress: string) {
  await ensureAutomationSessionKey({ managedAddress, sessionKeyAddress })
}

import { ensureAutomationSessionKey } from '@seedprotocol/publish/thirdweb'

export async function grant(managedAddress: string, sessionKeyAddress: string) {
  const expiresAt = Math.floor(Date.now() / 1000) + 30 * 24 * 3600
  await ensureAutomationSessionKey({ managedAddress, sessionKeyAddress, expiresAt })
}

ensureExecutorModuleInstalled takes a function that returns the admin wallet, called only when an install has to be sent. The second argument was a thirdweb Account it ignored. On /thirdweb, pass undefined for the connected in-app admin.

import { ensureExecutorModuleInstalled } from '@seedprotocol/publish/thirdweb'
import type { Account } from 'thirdweb/wallets'

export function install(managedAddress: string, adminAccount: Account) {
  return ensureExecutorModuleInstalled(managedAddress, adminAccount, {
    modularAccountModuleContract: '0xa4799d6D6AF110D5d69437488aBC31A5ef8ACA5f',
  })
}

import { ensureExecutorModuleInstalled } from '@seedprotocol/publish/thirdweb'

export function install(managedAddress: string) {
  return ensureExecutorModuleInstalled(managedAddress, undefined, {
    modularAccountModuleContract: '0xa4799d6D6AF110D5d69437488aBC31A5ef8ACA5f',
  })
}

@seedprotocol/publish now exports these functions too, along with enrollPublishAutomation, revokePublishAutomation and removeAutomationSessionKey, and none of them needs thirdweb. There the wallets are required: userWallet sends as the account and admin is the admin EOA. Enroll and revoke refuse a userWallet that sends from another address, on both entries, with MANAGED_ACCOUNT_UNAVAILABLE. See Session keys without thirdweb.

Three exports left /thirdweb. ensureManagedSignerSessionKey and defaultApprovedTargetsForModularPublish were deprecated, since interactive publishing needs no session key. toThirdwebSessionKeyPermissions has no replacement, because grants no longer go through thirdweb's SDK; buildAutomationSessionKeyPermissions still gives the permissions.

import {
  defaultApprovedTargetsForModularPublish,
  ensureManagedSignerSessionKey,
  toThirdwebSessionKeyPermissions,
} from '@seedprotocol/publish/thirdweb'

import { buildAutomationSessionKeyPermissions } from '@seedprotocol/publish/thirdweb'

const { approvedTargets } = buildAutomationSessionKeyPermissions()
console.log(approvedTargets) // the configured executor

Grants default to 90 days

Affects: apps that enroll without expiresAt or attest a publishAuthorization without expirationTime, and code that reads PUBLISH_AUTHORIZATION_DEFAULT_EXPIRATION_SECS. Changed in: @seedprotocol/publish and @seedprotocol/eas 0.8.0.

Those defaults, and the constant, are 90 days; they were 365. Keys enrolled before the upgrade keep their end until they're enrolled again, which the executor change requires. Enroll again before the end to renew, or pass the window you want:

import { enrollPublishAutomation } from '@seedprotocol/publish/thirdweb'

export async function grantForAYear(managedAddress: string, sessionKeyAddress: string) {
  const expiresAt = Math.floor(Date.now() / 1000) + 365 * 24 * 3600
  return enrollPublishAutomation({ managedAddress, sessionKeyAddress, expiresAt })
}

Enroll refuses a funded account

Affects: apps that enroll session keys on accounts holding ETH. Changed in: @seedprotocol/publish 0.8.0.

Enrollment, renewal included, fails with AUTOMATION_ACCOUNT_FUNDED before anything is sent when the account's balance plus EntryPoint deposit is above maxAutomationExposureWei, 0.001 ETH by default. A failed read of those fails with MODULAR_SIGNER_ACTIVATION_FAILED. The re-enrollment above can hit this, so check before you start. Withdraw the ETH, or raise the limit for an account that holds it on purpose. An automation publish over the limit logs a warning and goes ahead.

import { initPublish } from '@seedprotocol/publish'

initPublish({
  thirdwebClientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID,
  uploadApiBaseUrl: import.meta.env.VITE_SEED_UPLOAD_API_URL,
  maxAutomationExposureWei: 50_000_000_000_000_000n, // 0.05 ETH
})

Large uploads need confirming

Affects: apps and pipelines that publish more than 25 MiB of files, or more than 100 MiB. Changed in: @seedprotocol/publish 0.8.0.

A publish adds up its uploads in checking, before it registers a schema or reads a file. Over 25 MiB it fails with UploadNeedsConfirmError unless it has confirmUpload: true, and in Chromium a smaller publish can fail the same way on a low-memory device. Over 100 MiB it fails with UploadTooLargeError, which confirmUpload doesn't lift. item.publish() rejects with these errors themselves, on Node and with Turbo too, so an unattended pipeline that used to pass stops here.

import type { IItem } from '@seedprotocol/sdk'

export async function publishFromPipeline(item: IItem<any>) {
  await item.publish()
}

import type { IItem } from '@seedprotocol/sdk'

export async function publishFromPipeline(item: IItem<any>) {
  await item.publish({ confirmUpload: true, maxUploadBytes: 500 * 2 ** 20 })
}

An app with a user present asks and publishes again, as Confirm large uploads shows. confirmUploadAboveBytes: Infinity in the config doesn't turn off the memory check. See Upload limits.

getUnpublishedRelatedItems is removed

Affects: code that imports getUnpublishedRelatedItems. Changed in: @seedprotocol/sdk 0.8.0.

summarizePublishUploads(item, { publishMode }) returns the same list as unpublishedRelatedItems, with uploadCount, uploadBytes and uploadSizes, and reads file sizes only. summarizePublishWork still returns the list too.

import { getUnpublishedRelatedItems, type IItem } from '@seedprotocol/sdk'

export async function blockers(item: IItem<any>) {
  return getUnpublishedRelatedItems(item)
}

import { summarizePublishUploads, type IItem } from '@seedprotocol/sdk'

export async function blockers(item: IItem<any>) {
  const { unpublishedRelatedItems } = await summarizePublishUploads(item)
  return unpublishedRelatedItems
}

See Other read helpers.

A repeat init never changes addresses

Affects: apps that change addresses by calling client.init again. Changed in: @seedprotocol/sdk 0.8.0.

A repeat client.init leaves the stored addresses alone, whatever addresses holds. In 0.7.13 a different non-empty set replaced them. Only the first init, or the first after client.stop(), applies them, and of overlapping inits the first call's addresses win. This replaces the 0.7.13 rule.

import { client, type SeedConstructorOptions } from '@seedprotocol/sdk'

export async function switchAccount(options: SeedConstructorOptions, account: string) {
  await client.init({ ...options, addresses: [account] })
}

import { client } from '@seedprotocol/sdk'

export async function switchAccount(account: string) {
  await client.setAddresses([account])
}

See Addresses.

SeedProvider and SeedClientGate apply address changes

Affects: apps that pass addresses to SeedProvider, or in SeedClientGate's initConfig, and hosts that pass [] while a wallet loads. Changed in: @seedprotocol/react 0.8.0.

A change to the prop goes through client.setAddresses, so a change to [] clears the stored addresses, which 0.7.13 kept. A host that passes [] for a moment while a connected wallet loads loses them. Leaving the prop out changes nothing, so leave it out until the wallet is known.

import type { ReactNode } from 'react'
import { SeedProvider } from '@seedprotocol/react'
import type { SeedConstructorOptions } from '@seedprotocol/sdk'

declare const config: SeedConstructorOptions['config']

export function SeedRoot({ wallet, children }: { wallet?: string; children: ReactNode }) {
  return (
    <SeedProvider config={config} addresses={wallet ? [wallet] : []}>
      {children}
    </SeedProvider>
  )
}

import type { ReactNode } from 'react'
import { SeedProvider } from '@seedprotocol/react'
import type { SeedConstructorOptions } from '@seedprotocol/sdk'

declare const config: SeedConstructorOptions['config']

export function SeedRoot({ wallet, children }: { wallet?: string; children: ReactNode }) {
  return (
    <SeedProvider config={config} addresses={wallet ? [wallet] : undefined}>
      {children}
    </SeedProvider>
  )
}

A remount changes no addresses, whatever the prop holds. In 0.7.13 a remount with a different non-empty set replaced them, so an app that unmounts the provider or gate across a user switch now calls client.setAddresses with the new addresses. See Changing addresses.

relations rejects unknown values

Affects: untyped code that passes relations: 'urls' or any other value outside 'expand' and 'uids' to queryBySchema, getSeed or getSeeds. Changed in: @seedprotocol/query 0.8.0.

Such a call rejects with a TypeError (relations must be 'expand' or 'uids', got "urls") before any request. TypeScript already refused 'urls' in 0.7.13, where JavaScript got UIDs and the related seeds were still fetched.

import { queryBySchema } from '@seedprotocol/query'

const posts = await queryBySchema('post', { relations: 'urls' })

import { queryBySchema } from '@seedprotocol/query'

const posts = await queryBySchema('post', { relations: 'uids' })

external_id keeps its name again

Affects: code written against 0.7.13's keys for a non-relation property whose EAS name ends in _id or _ids. Changed in: @seedprotocol/query 0.8.0.

Only bytes32 and bytes32[] properties are relations. A string external_id, which 0.7.13 returned as external, is back under external_id and externalId, as in 0.7.12, and its value isn't fetched as a related seed. Keys of real relations don't change: author_id is still author. The name rule now applies only to an attestation with no type.

import { queryBySchema } from '@seedprotocol/query'

const { items } = await queryBySchema('post', { relations: 'uids' })
const ids = items.map((post) => post.data.external)

import { queryBySchema } from '@seedprotocol/query'

const { items } = await queryBySchema('post', { relations: 'uids' })
const ids = items.map((post) => post.data.external_id)

See SeedRecord.

Hand-built query results need listed

Affects: code that builds a QueryBySchemaResult, such as a mock or an adapter. Changed in: @seedprotocol/query 0.8.0.

listed is required. It's the number of Seeds the listing returned for the page, before Seeds with no Version are left out. Paging code can drop its second listing: listed < limit ends the listing, and listed === limit doesn't promise more, so the next page can be empty.

import type { QueryBySchemaResult } from '@seedprotocol/query'

export const emptyPage: QueryBySchemaResult = { items: [], limit: 25, skip: 0 }

import type { QueryBySchemaResult } from '@seedprotocol/query'

export const emptyPage: QueryBySchemaResult = { items: [], limit: 25, skip: 0, listed: 0 }

See Page through results.

The first reads after upgrading are cold

Affects: apps that cache items with @seedprotocol/query. Changed in: @seedprotocol/query 0.8.0.

The item cache codes are e6 for 'expand' and e7 for 'uids'; they were e3 and e5. Records cached by 0.7.13, on disk included, aren't read, so the first reads after the upgrade assemble every record again. See Caching.

The document lookup table is removed

Affects: saved MappingDocuments with a top-level lookups, code that passes lookups to applyMapping, applyMappingAsync, resolveLookup, previewForEdge or FieldMapper, and code that imports MappingLookups. Changed in: @seedprotocol/mapping 0.8.0.

Lookups read lookup.entries on the edge. Nothing warns at run time: a table in a saved document, or an option passed from JavaScript, is ignored, and its values count as misses. Stored { value, ref } entries still apply. Move a table onto its edges before you apply the document; entries then match without regard to case or spacing, where the table needed the exact text.

import type { MappingDocument } from '@seedprotocol/mapping'

export const saved: MappingDocument = {
  version: 1,
  sourceKind: 'rss',
  mappings: [{ sourceId: 'creator', propertyName: 'author', resolve: 'lookup' }],
  lookups: { author: { 'Jane Doe': 'jane' } },
}

import { lookupEntriesFromMapping, type MappingDocument } from '@seedprotocol/mapping'

type OlderDocument = MappingDocument & {
  lookups?: Record<string, Record<string, string | string[]>>
}

export function moveLookupsOntoEdges({ lookups = {}, ...doc }: OlderDocument): MappingDocument {
  const mappings = doc.mappings.map((edge) => {
    const table = lookups[edge.propertyName]
    if (edge.resolve !== 'lookup' || !table) return edge
    const moved = Object.entries(table).map(([value, refs]) => ({ value, refs: [refs].flat() }))
    return { ...edge, lookup: { ...edge.lookup, entries: [...lookupEntriesFromMapping(edge), ...moved] } }
  })
  return { ...doc, mappings }
}

Run that once on each saved document and save the result. See Saving and loading a mapping.

FieldMapper shows its built-in lookup editor

Affects: apps that render FieldMapper with lookup edges and without renderLookup or slots.lookups: false, and apps that pass onLookupsChange. Changed in: @seedprotocol/mapping 0.8.0.

The text editor needed onLookupsChange, which is gone, so these apps now get an input they didn't have, on each lookup row by default. It writes lookup.entries through onChange. Hide it if your app sets entries elsewhere:

import { FieldMapper, type FieldMapperProps } from '@seedprotocol/mapping/react'

export function Mapper(props: FieldMapperProps) {
  return <FieldMapper {...props} />
}

import { FieldMapper, type FieldMapperProps } from '@seedprotocol/mapping/react'

export function Mapper(props: FieldMapperProps) {
  return <FieldMapper {...props} slots={{ ...props.slots, lookups: false }} />
}

See Built-in editor.

connectSourceToProperty returns the list

Affects: code that calls connectSourceToProperty from @seedprotocol/mapping/react. Changed in: @seedprotocol/mapping 0.8.0.

It returns FieldMapping[]. It returned { mappings, clearedLookupProps }.

import type { FieldMapping, SourceNode, TargetProperty } from '@seedprotocol/mapping'
import { connectSourceToProperty } from '@seedprotocol/mapping/react'

export function connect(edges: FieldMapping[], sources: SourceNode[], targets: TargetProperty[]) {
  return connectSourceToProperty(edges, sources, targets, 'title', 'title').mappings
}

import type { FieldMapping, SourceNode, TargetProperty } from '@seedprotocol/mapping'
import { connectSourceToProperty } from '@seedprotocol/mapping/react'

export function connect(edges: FieldMapping[], sources: SourceNode[], targets: TargetProperty[]) {
  return connectSourceToProperty(edges, sources, targets, 'title', 'title')
}

probeGateway rejects a bare signal

Affects: JavaScript that still calls probeGateway(url, signal). Changed in: @seedprotocol/arweave 0.8.0.

The call rejects with TypeError: probeGateway takes options: pass { signal }, not an AbortSignal before any request. The signal was ignored in 0.7.13.

import { probeGateway } from '@seedprotocol/arweave'

const controller = new AbortController()
const healthy = await probeGateway('https://zigza.xyz', controller.signal)

import { probeGateway } from '@seedprotocol/arweave'

const controller = new AbortController()
const healthy = await probeGateway('https://zigza.xyz', { signal: controller.signal })

createTransaction is typed

Affects: TypeScript that uses the result of createTransaction, or the ArweaveTransaction type. Changed in: @seedprotocol/arweave 0.8.0.

ArweaveTransaction is the arweave package's Transaction, and createTransaction returns Promise<ArweaveTransaction>; both were any. Nothing changes at run time. Wrong use of a declared member stops compiling. Reading an undeclared property still compiles, because Transaction has an index signature.

import { BaseArweaveClient } from '@seedprotocol/arweave'

const tx = await BaseArweaveClient.createTransaction('hello')
tx.addTag('Version', 1)

import { BaseArweaveClient } from '@seedprotocol/arweave'

const tx = await BaseArweaveClient.createTransaction('hello')
tx.addTag('Version', '1')

See Transaction methods.

Errors and messages apps may match

Affects: code that matches error messages, and exhaustive switches on ManagedAccountPublishErrorCode. Changed in: @seedprotocol/sdk and @seedprotocol/publish 0.8.0.

getPublishModels throws UnknownModelError, with modelName and schemaName, and its message is Model "Nope" not found.; it was a plain Error reading No model named Nope.

import { getPublishModels } from '@seedprotocol/sdk'

export async function publishModels(names: string[]) {
  try {
    return await getPublishModels(names)
  } catch (error) {
    if (error instanceof Error && error.message.startsWith('No model named')) return []
    throw error
  }
}

import { getPublishModels, UnknownModelError } from '@seedprotocol/sdk'

export async function publishModels(names: string[]) {
  try {
    return await getPublishModels(names)
  } catch (error) {
    if (error instanceof UnknownModelError) return []
    throw error
  }
}

Model.create with a name that can't publish rejects with the reserved-word message alone, Model "Event" publishes as "event", … or Property "view" publishes as "view", …. The Model "X" could not create its properties: prefix is gone for this case, and with no properties it rejects too, where it resolved. With waitForReady: false it throws. Nothing stays in schema.models, so saveNewVersion() isn't blocked.

Renaming a property to such a name still doesn't throw, but validate() now returns an error with code reserved_name. While the bad name stands, saveNewVersion() resolves with '' if nothing else changed, and rejects with the reserved-word message if there's a valid edit to save. See Reserved Solidity words.

A direct EAS backward reference fails with Direct EAS publish from <address> can't fill a reference backwards: …, code unchanged. With no wallet, a PublishManager.createPublish run fails with PublishWalletMissingError (code: 'PUBLISH_WALLET_MISSING'), but item.publish() stops before that with a plain Error with the same text, so match the class only on direct runs. ManagedAccountPublishErrorCode gains AUTOMATION_ACCOUNT_FUNDED, PUBLISH_TOO_LARGE and MULTI_PUBLISH_NOT_ROUTED, so an exhaustive switch needs the three cases.

Upgrading from 0.7.12 to 0.7.13

Released: 2026-10-29. The SDK parts come first, then the packages around it. The Changelog lists everything else in 0.7.13.

Names that publish as a Solidity word don't load

Affects: schema files, and models and properties created in code, whose EAS name is a word the Solidity ABI reserves. Changed in: @seedprotocol/sdk 0.7.13.

The words are constructor, error, event, fallback, function, receive, struct, calldata, memory, storage, payable, indexed, tuple, returns, constant, external, internal, private, public, pure, view and override. EAS couldn't register or attest a schema under one of them, so a publish failed at its first encode. The check is on the EAS name, so a property Returns and a model Event are refused too; a List of Relation is exempt, since it publishes as <name><Model>Ids. A schema file with such a name now fails to load, so client.init rejects:

Could not load config.schema: Schema blog: Post.view: Property "view" publishes as "view", which EAS schemas can't use (a reserved Solidity ABI word). Rename it.

ModelProperty.create with such a name rejects with Failed to write property "view": …, and Model.create rejects for such a model name when you pass properties. Rename the property or model, and raise version:

"view": { "type": "Number" },
"returns": { "type": "Text" }

"viewCount": { "type": "Number" },
"returnPolicy": { "type": "Text" }

Don't rename a loaded property to one of these words in code either: the rename isn't saved, and the next saveNewVersion() rejects with the same message. See Reserved Solidity words.

Missing files read undefined

Affects: code that reads the value of an Image, File or Html property whose file may not be on this device, such as an item synced from another device. Changed in: @seedprotocol/sdk and @seedprotocol/react 0.7.13.

When the file isn't found, value is undefined. It was the storage seed's ID for an Html property, the file name for an Image, and 'No file found' for a File, which code couldn't tell from content. The new valueStatus says which case applies: 'missing' (with the path looked for in missingFile.path), 'fetching' while the property loads, and 'resolved' otherwise; it's always 'resolved' for other types. refResolvedValue and localStoragePath still name the file, and the property reads it again when the file is saved, by a download or another tab. useItemProperty returns valueStatus too, and re-renders when it changes.

if (attachment.value === 'No file found') showPlaceholder()

import type { IItemProperty } from '@seedprotocol/sdk'

export function attachmentUrl(attachment: IItemProperty): string | undefined {
  if (attachment.valueStatus === 'missing') {
    console.warn('Not on this device yet:', attachment.missingFile?.path)
    return undefined
  }
  if (attachment.valueStatus === 'fetching') return undefined
  return typeof attachment.value === 'string' ? attachment.value : undefined
}

See valueStatus and missingFile.

Empty addresses on a repeat init keep the stored ones

Affects: apps that sign a user out by passing empty addresses to client.init again, or by changing the addresses they pass to SeedProvider or in SeedClientGate's initConfig to []. Changed in: @seedprotocol/sdk 0.7.13.

A repeat client.init with the same config and empty addresses ([], or { owned: [], watched: [] }) keeps the stored addresses, so a remount before a wallet connects no longer drops them. It cleared them. A different non-empty set still replaces them, and the first init of a process, or the first after client.stop(), still clears them with []. To sign out, clear them yourself:

import { client } from '@seedprotocol/sdk'

export async function signOut() {
  await client.setAddresses([])
}

In 0.8.0 a repeat init never changes addresses. See Addresses.

ClientNotInitializedError replaces matching the message

Affects: code that tells a call made before init, or after client.stop(), from other errors by its message. Changed in: @seedprotocol/sdk 0.7.13.

Item.find rejects with ClientNotInitializedError (code: 'CLIENT_NOT_INITIALIZED', exported from both entries) once readyTimeout passes without an open database, and every client method that needs init throws it before init has finished and after stop() or unload(). Both used a plain Error. The message is still ClientManager is not initialized. Please call init() first., so code that matches it keeps working, but instanceof or code doesn't depend on the text:

import { ClientNotInitializedError, Item } from '@seedprotocol/sdk'

try {
  const post = await Item.find({ modelName: 'Post', seedLocalId })
  renderPost(post)
} catch (error) {
  if (error instanceof ClientNotInitializedError) showNotice('Seed is still starting.')
  else throw error
}

See Errors.

React: early creates and the status types

Affects: code that calls useCreateModelProperty().create before the client is ready, and code that compares useGlobalServiceStatus()'s status or internalStatus with a string. Changed in: @seedprotocol/react 0.7.13.

create called before the app database is open rejects with ClientNotInitializedError, where it rejected with No stored schema has the name or schema file id "<id>", which read like a misspelt schema ID. That message now means only that no stored schema matches.

status is typed ClientManagerState | 'stopped' and internalStatus ClientManagerState | 'ready' | 'stopped'; both were string. A comparison with a value outside the union no longer type-checks. 'ready' is an internalStatus value, not a status one:

const { status } = useGlobalServiceStatus()
if (status === 'ready') return null

The hook also returns stopReason: 'reset' when client.resetLocalData() stopped the client, in this tab or another, and 'stop' after client.stop() or client.unload().

import { useCreateModelProperty, useGlobalServiceStatus } from '@seedprotocol/react'
import { ClientNotInitializedError } from '@seedprotocol/sdk'

export function AddSubtitle() {
  const { create } = useCreateModelProperty()
  const { status, stopReason } = useGlobalServiceStatus()

  if (status === 'stopped') return <p>{stopReason === 'reset' ? 'Local data was deleted.' : 'Signed out.'}</p>

  const addSubtitle = async () => {
    try {
      await create('blog', 'Post', { name: 'subtitle', dataType: 'Text' })
    } catch (error) {
      if (error instanceof ClientNotInitializedError) showNotice('Seed is still starting. Try again in a moment.')
      else throw error
    }
  }

  return <button onClick={addSubtitle} disabled={status !== 'idle'}>Add a subtitle</button>
}

See useGlobalServiceStatus and useCreateModelProperty.

relations: 'urls' is removed

Affects: code that passes relations: 'urls' to queryBySchema, getSeed or getSeeds. Changed in: @seedprotocol/query 0.7.13.

RelationsMode is 'expand' | 'uids'. 'urls' fetched the same related seeds as 'expand', so it saved no requests. Use 'expand', or 'uids' to skip fetching related seeds:

const posts = await queryBySchema('post', { relations: 'urls' })

import { queryBySchema } from '@seedprotocol/query'

const posts = await queryBySchema('post', { relations: 'expand' })

Untyped code that still passes 'urls' gets no error: its relations come back as UIDs, as with 'uids', but the related seeds are still fetched. In 0.8.0 it rejects with a TypeError.

Relation keys are the same in every mode

Affects: code that reads relations from query records or changelog entries under their EAS names (author_id, author_identity_ids) or camelCase copies (authorId, authorIdentityIds), and properties whose EAS name ends in _id or _ids. Changed in: @seedprotocol/query 0.7.13.

Relations come back under their schema key with relations: 'uids', with 'expand' (also for a related seed that's missing), and in changelog entries: author_id as author, and a list's author_identity_ids as authors. A camelCase copy is added only when it differs (feature_image_id comes back as feature_image and featureImage), so authorId and authorIdentityIds are gone. In 0.7.12, 'uids' records kept the EAS names and their camelCase copies.

The key comes from the EAS name alone. A property whose EAS name ends in _id or _ids is read as a relation and loses the suffix, whatever its type, so a Text external_id comes back as external, under no other key. A list's key keeps only the first word of its EAS name, so co_author_identity_ids comes back as cos. In 0.8.0 a non-relation keeps its name, and setQueryModels gives lists their schema keys.

import { queryBySchema } from '@seedprotocol/query'

const { items } = await queryBySchema('post', { relations: 'uids' })

for (const post of items) {
  const authorUids = post.data.authors // was author_identity_ids and authorIdentityIds
  const coverUid = post.data.feature_image // was feature_image_id and featureImageId
  console.log(post.seedUid, authorUids, coverUid)
}

The cache keys changed with the record shape, so records cached by 0.7.12, on disk included, aren't read, and the first reads after the upgrade assemble every record again. See SeedRecord and Caching.

queryBySchema pages can be short

Affects: code that pages through queryBySchema or queryBySchemaForMonth and stops at the first page with fewer items than limit. Changed in: @seedprotocol/query 0.7.13.

queryBySchema, queryBySchemaForMonth and assembleSeeds leave out a Seed with no Version from its attester, as getSeed and getSeeds have since 0.7.12. They returned it with versionUid: '' and no properties. limit and skip still count the Seeds listed before that, so a page can hold fewer items than limit, or none, while later pages still have items. Code that read versionUid === '' to skip such records can drop the check. A page doesn't say whether more follow; to page to the end, stop when the source's own listing comes back short. In 0.8.0 listed gives that count, and Page through results uses it. See queryBySchema.

createEasNodeDispatcher is async

Affects: code that calls createEasNodeDispatcher, and subclasses of NodeEasClient that override getDispatcher. Changed in: @seedprotocol/eas 0.7.13.

createEasNodeDispatcher(options?) returns Promise<Dispatcher | undefined>. It loads undici's Agent with a dynamic import, so a bundled @seedprotocol/eas (Astro with ssr.noExternal, say) finds undici, where the first EAS request failed with Cannot find module 'undici/lib/dispatcher/agent.js'. Await it:

const dispatcher = createEasNodeDispatcher({ keepAliveTimeoutMs: 10_000 })
const eas = new NodeEasClient({ dispatcher: dispatcher ?? false })

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

const dispatcher = await createEasNodeDispatcher({ keepAliveTimeoutMs: 10_000 })
const eas = new NodeEasClient({ dispatcher: dispatcher ?? false })

createEasGraphQLClient's dispatcher option takes the promise as it is. NodeEasClient's protected getDispatcher() returns Promise<Dispatcher | undefined>, so an override returns a promise too. See registerNodeEasPlatform.

Automation needs ensureEasSchemasForModels

Affects: apps that publish with an automation session key, and code that matches the missing-schema message. Changed in: @seedprotocol/publish 0.7.13.

A publish now registers only the EAS schemas it attests: the models of the item and its drafts, the properties it sets or removes, and the storage transaction of a seed that uploads. An owner's publish no longer registers schemas for properties it leaves empty, so publishing once with the owner's wallet no longer prepares every schema an automation key might need. Run ensureEasSchemasForModels with the owner's wallet instead, before automation starts and again after a schema version adds a property.

An automation key that meets a missing schema throws EasSchemasNotRegisteredError (code: 'EAS_SCHEMAS_NOT_REGISTERED'), whose missing lists every missing definition, checked before anything is sent. It was a plain Error naming the first one, … Call ensureEasSchemasForItem with the owner wallet first.; the message now names ensureEasSchemasForModels, and a failed publish's errorMessage changes with it. Match the class or code:

import { EasSchemasNotRegisteredError, ensureEasSchemasForModels } from '@seedprotocol/publish'

// With the owner's wallet, before automation runs, and again after a schema version adds a property:
const { registered } = await ensureEasSchemasForModels(['Post'], ownerWallet)
console.log(`Registered ${registered.length} EAS schemas`)

// Where automation reports a failed publish:
export function reportPublishError(error: unknown) {
  if (error instanceof EasSchemasNotRegisteredError) {
    alertOwner(`Register these EAS schemas with the owner wallet: ${error.missing.join(', ')}`)
  } else {
    throw error
  }
}

Pass { dryRun: true } to get the missing definitions without sending anything. See Other exports and Model and property schemas.

probeGateway takes an options object

Affects: code that calls probeGateway(baseUrl, signal). Changed in: @seedprotocol/arweave 0.7.13.

The second argument is { signal?, timeoutMs?, recordCircuit? }. A probe times out after timeoutMs (default 5,000) with or without a signal; with a signal it had no timeout. A probe the caller aborts resolves false without counting as a failure, where it opened the host's circuit for 60 seconds; a timeout still counts. recordCircuit: false probes a host whose circuit is open and leaves the circuit as it is.

const healthy = await probeGateway('https://zigza.xyz', controller.signal)

import { probeGateway } from '@seedprotocol/arweave'

const controller = new AbortController()
const healthy = await probeGateway('https://zigza.xyz', { signal: controller.signal, timeoutMs: 3_000 })

JavaScript that still passes the signal second gets no error: the signal is ignored and the 5-second timeout applies. In 0.8.0 the call rejects. See Other read helpers.

permagate.io leaves the default gateways

Affects: apps that rely on the default read gateways, and code that reads DEFAULT_ARWEAVE_GATEWAYS. Changed in: @seedprotocol/arweave 0.7.13.

DEFAULT_ARWEAVE_GATEWAYS is ['arweave.net', 'zigza.xyz', 'ar.seedprotocol.io']. Reads, probes, status checks and the failover in nextArweaveGatewayUrl and SeedHtml no longer go to permagate.io, so the next gateway after arweave.net is zigza.xyz. Links on permagate.io still parse and get re-hosted: it's in the new KNOWN_ARWEAVE_GATEWAYS, which isKnownArweaveGatewayHostname and link parsing check. See The default gateway and its fallbacks.

Feed guids and Atom fields

Affects: apps that serve feeds with @seedprotocol/feed, and code that passes items with their own title, updated or links to createFeed. Changed in: @seedprotocol/feed 0.7.13.

An item with a storage transaction and no link of its own, such as an Image item, has the RSS guid ar://<txId>, so its Atom entry ID and JSON Feed item ID are that too. Its link is still https://<public host>/raw/<txId>. The guid was that link, so it changed whenever arweaveDomain did. Feed readers show these items once more as new, and after that a gateway change doesn't repeat them. A guid is no longer moved onto the public gateway with an item's other Arweave links. A cached document keeps the old guids until it's rebuilt: the first page when query's collection, the site config or cacheBust changes, and later pages and archives when their TTLs run out. To switch at once, delete the files in CACHE_DIR and restart.

In Atom, an item's own title, updated and links win over the defaults again, as before 0.7.12. A field that is present but null also replaces the default, so updated: null gives an entry with no <updated>. See Field mapping.

Lookup entries take a list of refs

Affects: code that builds or reads mapping lookup entries, calls lookupRefFromEntries or resolveLookupMapped, or builds FieldMapperLookupRow objects itself. Changed in: @seedprotocol/mapping 0.7.13.

LookupEntry is { value: string; refs: string[] }, so one entry can name several items, as for a joint byline. A List target gets every ref, a Relation target the first. lookupRefFromEntries is replaced by lookupRefsFromEntries, which returns the list, and resolveLookupMapped by resolveLookup, which returns { refs, unmatched, split }. Saved MappingDocuments keep working: a stored { value, ref } applies as refs: [ref], and lookupEntriesFromMapping returns it in the new shape.

const authorEdge: FieldMapping = {
  sourceId: 'author',
  propertyName: 'author',
  resolve: 'lookup',
  lookup: { entries: [{ value: 'Jane Doe', ref: janeId }] },
}

const ref = lookupRefFromEntries(authorEdge.lookup?.entries, 'Jane Doe')

import { lookupRefsFromEntries, resolveLookup, type FieldMapping } from '@seedprotocol/mapping'

const authorEdge: FieldMapping = {
  sourceId: 'author',
  propertyName: 'authors',
  resolve: 'lookup',
  lookup: {
    entries: [
      { value: 'Jane Doe', refs: [janeId] },
      { value: 'Sam Ortiz & Mira Chen', refs: [samId, miraId] },
    ],
  },
}

const refs = lookupRefsFromEntries(authorEdge.lookup?.entries, 'Jane Doe') // [janeId]
const { refs: matched, unmatched } = resolveLookup(authorEdge, 'Pat Lee') // [], ['Pat Lee']

Entries now match without regard to case or spacing ('MIRA CHEN' finds 'Mira Chen'); the deprecated document-level lookups table still needs the exact text. FieldMapperLookupRow has a required onSplitChange, so a lookup row your code builds, in a test or a custom renderer, needs one. See LookupEntry and Relation lookups.

Gateway Hyper: upgrade the operator and its clients together

Affects: Gateway Hyper operators that restrict clients with an allowlist, and their clients. Changed in: @seedprotocol/gateway-hyper 0.7.13.

A client refused by address gets the 403 for every request: the operator's 403 carries connection: close, and the client opens a new stream for its next request. That needs 0.7.13 on both sides. While the operator or the client runs 0.7.12, sequential requests alternate between the 403 and a 502 (Unexpected end of stream). See Restricting who can connect.

Node 20.18.1 for query, feed and feed-hyper

Affects: apps that run @seedprotocol/query, @seedprotocol/feed or @seedprotocol/feed-hyper on Node older than 20.18.1. Changed in: those packages, 0.7.13.

Their engines declare Node 20.18.1 or later, the range @seedprotocol/eas already declared; query and feed declared none, and feed-hyper Node 20. npm warns on an older Node, and refuses the install only with engine-strict set. Upgrade Node to 20.18.1 or later.

Upgrading from 0.7.11 to 0.7.12

Released: 2026-10-27. The SDK parts come first, then the packages around it. The Changelog lists everything else in 0.7.12.

Validation codes are names

Affects: code that reads code on ItemCreateValidationError.problems, ItemPropertySaveValidationError.validationErrors or validate() results, or that matches validation messages. Changed in: @seedprotocol/sdk 0.7.12.

Every check has a named code: type for a wrong type, pattern, min_length, max_length_exceeded, enum_violation, format for a Date that isn't one, and unknown_data_type. A property definition's own checks add required, unknown_field, minimum, maximum and rule_not_applicable. array_not_allowed, missing_type and unknown_property are unchanged. Type and pattern failures used to be numbers in strings ('41', '53', '62'), and a minLength miss was coded max_length_exceeded. An enum miss is one problem, Expected one of: "draft", "live". Received: "nope", where it was two Expected union value problems, and the other problems on a property with an enum keep their own codes instead of enum_violation. Messages changed with the codes (Text must be at least 3 characters.), so match on code:

import { Item, ItemCreateValidationError } from '@seedprotocol/sdk'

try {
  await Item.create({ modelName: 'Post', schemaName: 'Blog', title: form.title, status: form.status })
} catch (error) {
  if (!(error instanceof ItemCreateValidationError)) throw error
  for (const problem of error.problems) {
    switch (problem.code) {
      case 'min_length':
        showFieldError(problem.property, 'Too short.')
        break
      case 'enum_violation':
        showFieldError(problem.property, 'Pick one of the listed options.')
        break
      default:
        showFieldError(problem.property, problem.message)
    }
  }
}

See ItemPropertySaveValidationError for which rule gives which code.

Schemas with misplaced rules or unknown types don't load

Affects: schema files, and properties defined in code, that set pattern, minLength or maxLength on a type other than Text or Html, or that name a type that doesn't exist. Changed in: @seedprotocol/sdk 0.7.12.

Those rules were ignored on other types, and an unknown type name was kept (blob was read as Blob). A schema file with either now fails to load before anything is stored, so client.init rejects, for example with Could not load config.schema: Schema Blog: Post.wordCount: validation.maxLength only apply to Text and Html properties (this one is Number). Remove it or use enum. or … unknown type "Integer". Expected one of: Text, Number, …. In code, the property's validate() reports rule_not_applicable or unknown_data_type. Remove the rule and use one of the ten data types:

"wordCount": { "type": "Number", "validation": { "maxLength": 6 } },
"rating": { "type": "Integer" }

"wordCount": { "type": "Number" },
"rating": { "type": "Number" }

validation.custom no longer fails the property's validation: the schema loads and logs [seed] schema <name>: <Model>.<property>: Custom validators are not supported … the first time it's stored. The rule still has no effect. See Validation.

Item.getById doesn't hold

Affects: code that calls unload() after Item.getById, or keeps an item from it across long work. Changed in: @seedprotocol/sdk 0.7.12.

Item.getById(id) takes a cache hold only when called with { hold: true }, as Item.find has since 0.7.10. Without one, the item stays cached for the grace period after the lookup. Item.createById still holds. An unload() after a plain getById now releases a hold someone else took, such as a mounted useItem's, so drop it, or pass { hold: true } when you keep the item:

const post = Item.getById(seedLocalId)
renderPost(post)
post?.unload()

import { Item } from '@seedprotocol/sdk'

const post = Item.getById(seedLocalId) // no hold: don't unload() it
renderPost(post)

const kept = Item.getById(seedLocalId, { hold: true }) // one hold: unload() it when done
try {
  await exportPost(kept)
} finally {
  kept?.unload()
}

See Cache helpers.

Item.find before init rejects

Affects: code that calls Item.find before client.init or after client.stop(), such as a module that loads data when it's imported. Changed in: @seedprotocol/sdk 0.7.12.

Item.find resolved undefined then, as for an item that doesn't exist. It now waits for the database for readyTimeout (15 seconds by default) and rejects with a plain Error whose message is ClientManager is not initialized. Please call init() first. and which has no code. A find called while client.init runs waits for it and works. Start lookups once client.init has been called, or in React inside SeedClientGate; to tell this rejection from a failed load, match the message. 0.7.13 gives it a class and a code; see ClientNotInitializedError replaces matching the message. See Item.find.

Item.create checks relation targets

Affects: code that creates items with Relation or List of Relation values, such as imports that create related items in any order. Changed in: @seedprotocol/sdk 0.7.12.

The initial relation values are checked when the create's write is applied, as an assignment's are. A seedLocalId that names no item rejects the create with OutboxOpFailedError (message Relation target not found: <id>, errorName: 'RelationTargetError'), whose cause is a RelationTargetError listing the missing IDs in targets, and nothing is written. 0.7.11 stored the dangling ID. A target whose own create is still queued is waited for, and seedUids and the new item's own ID pass. Create the targets first, then:

import { Item, OutboxOpFailedError, RelationTargetError } from '@seedprotocol/sdk'

try {
  await Item.create({ modelName: 'Post', schemaName: 'Blog', title: 'Hello', author: authorId })
} catch (error) {
  if (error instanceof OutboxOpFailedError && error.cause instanceof RelationTargetError) {
    showError(`Missing author: ${error.cause.targets.join(', ')}`)
  } else {
    throw error
  }
}

See Validation.

removeLocalCopiesForAddresses keeps unpublished edits

Affects: code that calls client.removeLocalCopiesForAddresses, such as a sign-out flow. Changed in: @seedprotocol/sdk 0.7.12.

A copy whose publisher is still an owned address and that has an unpublished edit or a pending outbox write is kept, and its local ID is listed in the result's new keptSeedLocalIds. 0.7.11 deleted it, and its edits, with the rest. A sign-out flow that calls it before it removes the account from the owned addresses now leaves those items on the device. Pass { includeUnpublished: true } to remove them too:

import { client } from '@seedprotocol/sdk'

const { keptSeedLocalIds } = await client.removeLocalCopiesForAddresses([address])
if (keptSeedLocalIds.length > 0) {
  showNotice(`${keptSeedLocalIds.length} items with unpublished edits stay on this device.`)
}

// To remove those too:
await client.removeLocalCopiesForAddresses([address], { includeUnpublished: true })

See client.

arweave.net is the default gateway

Affects: apps that read or publish through Seed's gateway, ar.seedprotocol.io, without setting arweaveDomain, and code that compares Arweave URLs with a host. Changed in: @seedprotocol/arweave and @seedprotocol/sdk 0.7.12.

DEFAULT_ARWEAVE_HOST, and so the default arweaveDomain, is arweave.net. Reads try it first, and publish writes it into the links of the Html it uploads. DEFAULT_ARWEAVE_GATEWAYS is arweave.net, permagate.io, zigza.xyz, ar.seedprotocol.io (0.7.13 drops permagate.io; see permagate.io leaves the default gateways), and DEFAULT_ARWEAVE_GRAPHQL_URL is https://arweave.net/graphql. An app that sets arweaveDomain: 'arweave.net' can drop it. An app that wants Seed's gateway sets it:

import { client } from '@seedprotocol/sdk'
import schema from './seed.schema.json'

await client.init({
  config: { schema, arweaveDomain: 'ar.seedprotocol.io' },
})

An Html value now reads back with its Arweave links on this reader's first read gateway, while the stored file keeps them as written, so code that compares a read Html value with the markup it saved can see other hosts. See Gateway settings and Links in published content.

getArweaveUrlForTransaction returns the /raw/ URL

Affects: code that calls getArweaveUrlForTransaction (from @seedprotocol/sdk, @seedprotocol/query or @seedprotocol/arweave), or that reads query's image arweaveUrl fields and storage URLs. Changed in: @seedprotocol/arweave, @seedprotocol/sdk and @seedprotocol/query 0.7.12.

There is one getArweaveUrlForTransaction, @seedprotocol/arweave's, re-exported by the SDK and query. It returns {first read gateway}/raw/{id}, the URL this reader loads from, which can be a sidecar or proxy; it was {read host}/{id}. Query's image arweaveUrl fields and storage URLs use it. For a URL that leaves this reader, such as a share link or one in content you publish, use getPublicArweaveRawUrl (install @seedprotocol/arweave at the same version):

import { getPublicArweaveRawUrl } from '@seedprotocol/arweave'
import { getArweaveUrlForTransaction } from '@seedprotocol/sdk'

const shareUrl = getPublicArweaveRawUrl(txId) // https://arweave.net/raw/<txId>, for links others open
const readUrl = getArweaveUrlForTransaction(txId) // this reader's first read gateway, for loading here

See Media references.

uploadApiBaseUrl doesn't fall back to the gateway

Affects: apps with transport: 'http-gateway', or 'hybrid' falling back to HTTP, whose gateway also serves the upload API and that don't set uploadApiBaseUrl. Changed in: @seedprotocol/arweave 0.7.12.

resolveSeedGatewayEndpoints resolves an unset uploadApiBaseUrl to '', where it used the gateway's base URL. With the new default host that would be arweave.net, where no upload API runs. Set uploadApiBaseUrl to your gateway's upload API. Proxy and sidecar modes still upload through the proxy or sidecar. See resolveSeedGatewayEndpoints.

Custom query sources implement one listing method

Affects: code that registers its own QueryDataSource. Changed in: @seedprotocol/query 0.7.12.

listSeedsByUidPrefix is removed. listSeedsBySchemaName(schemaName, opts) gets the filters in opts: uidPrefix and the new attesters, both normalized, with limit and skip applying after them. A source spread from the remote one inherited its listSeedsByUidPrefix, so a uidPrefix read still filtered. Now a source that reads only limit and skip still type-checks but returns Seeds the call meant to leave out. A custom getSeedByUid gets the UID in lowercase.

const onePublisher: QueryDataSource = {
  ...remote,
  kind: 'local',
  listSeedsBySchemaName(schemaName, { limit, skip }) {
    return remote.listSeedsBySchemaName(schemaName, { limit, skip })
  },
  listSeedsByUidPrefix(schemaName, uidPrefix, { limit, skip }) {
    return remote.listSeedsByUidPrefix(schemaName, uidPrefix, { limit, skip })
  },
}

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

const publisher = '0xe870b14fcff4a408e6ecb65bd40f64d08859efb3' // lowercase, as opts.attesters is
const remote = createRemoteQueryDataSource()

const onePublisher: QueryDataSource = {
  ...remote,
  kind: 'local',
  listSeedsBySchemaName(schemaName, { limit, skip, uidPrefix, attesters }) {
    if (attesters && !attesters.includes(publisher)) return Promise.resolve([])
    return remote.listSeedsBySchemaName(schemaName, { limit, skip, uidPrefix, attesters: [publisher] })
  },
}

registerLocalQuerySource(onePublisher)

To list one publisher's Seeds in a single call, queryBySchema(name, { attesters: [address] }) needs no custom source. See QueryDataSource and One publisher's items.

normalizeBytes32Hex is strict and toSnakeCase is removed

Affects: code that imports toSnakeCase from @seedprotocol/eas, or passes values that aren't full 32-byte hex strings to normalizeBytes32Hex. Changed in: @seedprotocol/eas 0.7.12.

toSnakeCase kept the naming rule from before 0.7.4 (HTMLPage → htmlpage); use easName (html_page), which builds the names Seed writes to EAS. normalizeBytes32Hex returns '' unless the value is 64 hex digits, with or without 0x; it padded short values and turned other characters into 0. Check for '':

import { toSnakeCase } from '@seedprotocol/eas'

const easModelName = toSnakeCase(modelName)

import { easName, normalizeBytes32Hex } from '@seedprotocol/eas'

const easModelName = easName(modelName)

const seedUid = normalizeBytes32Hex(input)
if (!seedUid) throw new Error(`Not a Seed UID: ${input}`)

The indexer's timeout also rejects with a new message, EAS indexer request timed out after <n> ms, for code that matched the old one. See UID and address helpers.

Feed readers show items again once

Affects: apps that serve feeds with @seedprotocol/feed. Changed in: @seedprotocol/feed 0.7.12.

Atom entry IDs and JSON Feed item IDs are the item's RSS guid, where they were the Seed UID, so after the upgrade a feed reader shows each item of an existing Atom or JSON feed once more as new. An item with its own storage transaction now links to the public gateway's /raw/ URL (https://arweave.net/raw/<id> with the default host, where it was https://ar.seedprotocol.io/<id>), and the handlers use that link as its guid, so the RSS items of an Image feed show again too. Nothing in code needs to change; tell subscribers if a repeat matters. In createFeed, an item's own updated and links no longer override Atom's; 0.7.13 restores them and changes the guid of stored-transaction items (see Feed guids and Atom fields). See Field mapping.

Gateway Hyper timeouts and options

Affects: Gateway Hyper operators and clients, and code that passes storePath or gives serveRawTunnel both keyFile and keyPair. Changed in: @seedprotocol/gateway-hyper 0.7.12.

• Timeouts. The default upstreamTimeoutMs is 130,000 (it was 30,000) and requestTimeoutMs 150,000 (it was 60,000), in the CLI too, above the 120 seconds publish waits for an upload batch. --upstream-timeout-ms and --request-timeout-ms values set for that reason can go.
• storePath is removed from the serveTunnel, connectTunnel, createGatewayProxy and createTunnelSession options, so TypeScript rejects it (TS2353). Nothing read it; delete it.
• https:// upstreams. serveTunnel throws for one, and seed-gateway serve --upstream https://… stops. The framed tunnel speaks plain HTTP to its upstream: point it at a plain HTTP address, or use raw TCP mode to carry TLS end to end.
• Keys. serveRawTunnel with both keyFile and keyPair throws Pass keyFile or keyPair, not both; keyPair used to win. Pass one.

See seed-gateway serve and serveTunnel.

React: schema IDs and the stopped status

Affects: apps that pass schema IDs to useModelProperty or useCreateModelProperty, and code that reads useGlobalServiceStatus(). Changed in: @seedprotocol/react 0.7.12.

useModelProperty(schemaId, …) and useCreateModelProperty().create(schemaId, …) no longer cut a trailing -<n> off a schema ID that no stored schema has as its name or file ID, so blog-2 no longer resolves to blog. useModelProperty finds nothing for such an ID, and create rejects with No stored schema has the name or schema file id "blog-2", which it also does when called before the app database is open (0.7.13 rejects with ClientNotInitializedError then; see React: early creates and the status types). Pass the schema's name or file ID, and call create once the client is ready. See useCreateModelProperty.

After client.stop(), useGlobalServiceStatus() reports status and internalStatus as 'stopped' until the next init starts; they read 'idle', so a stopped client looked ready. status is typed string, so TypeScript doesn't flag a check that misses 'stopped' (0.7.13 narrows the type; see React: early creates and the status types):

import { useGlobalServiceStatus } from '@seedprotocol/react'

export function ClientStatus() {
  const { status } = useGlobalServiceStatus()
  if (status === 'stopped') return <p>Signed out.</p>
  if (status === 'initFailed') return <p>Seed didn't start.</p>
  if (status !== 'idle') return <p>Starting…</p>
  return null
}

useCreateItem now creates a new item for a second call with other values or another model, where it returned the first call's item; only a repeat of the same call shares it. See useGlobalServiceStatus and useCreateItem.

seedVitePlugin rejects unknown options

Affects: apps whose seedVitePlugin options include autoInit or a misspelt name. Changed in: @seedprotocol/vite 0.7.12.

The plugin throws when the Vite config loads: seedVitePlugin: autoInit was removed. Initialize the SDK from your app (client.init(), or <SeedProvider>)., or for any other unknown option seedVitePlugin: unknown option "fsModule". It takes fsModules, debug, includeNodePolyfills, isolationHeaders. Both were ignored. Remove or fix the option.

includeNodePolyfills: true now polyfills timers too, so an alias of timers to timers-browserify added for rssXmlToSources can go. See Options.

FieldMapper themes use --sfm-* only

Affects: apps that style FieldMapper with --fm-* or --map-* CSS variables. Changed in: @seedprotocol/mapping 0.7.12.

The --fm-* and --map-* variables are removed. Each --fm-<name> color is --sfm-color-<name>, and --fm-map-N and --map-N are --sfm-map-N:

.seed-field-mapper {
  --fm-ink: #1d1d1f;
  --fm-map-1: #0a7cff;
}

.seed-field-mapper {
  --sfm-color-ink: #1d1d1f;
  --sfm-map-1: #0a7cff;
}

applyMapping and applyMappingAsync also copy a source's value only, so an empty frontmatter field or Markdown body maps to '', not the field's name or "Full document". See Classes and CSS variables.

Publish wallets can be 'modular'

Affects: code that switches on a publish wallet's kind or checks kind === 'smart'. Changed in: @seedprotocol/publish 0.7.12.

PublishWalletKind adds 'modular', the modular executor's in-app EOA, which publishes as the user's ManagedAccount. ConnectButton with useModularExecutor and ensureSmartWalletThenPublish's modular path register that wallet as 'modular', where they said 'smart'. A 'modular' wallet signs data items, and direct EAS refuses it as it does 'smart':

import type { PublishWalletKind } from '@seedprotocol/publish'

export function walletLabel(kind: PublishWalletKind | undefined): string {
  switch (kind) {
    case 'eoa':
      return 'Wallet'
    case 'smart':
    case 'modular':
      return 'Smart account'
    default:
      return 'Unknown wallet'
  }
}

Two more publish changes can affect error handling and holds. A failed revocation of retracted properties rejects with the new PublishRetractionError (code: 'PUBLISH_RETRACTION_FAILED'), not the attestation-failure message; PublishManager.retryAttestations(seedLocalId) still sends it again. And every publish holds its item, PublishManager.createPublish and ensureWalletThenPublish included, so a hold you take around them, as createPublish doesn't hold the item asked for 0.7.10, is no longer needed but does no harm. See Wallets.

Upgrading from 0.7.10 to 0.7.11

Released: 2026-10-24. Deprecated aliases are removed, and a few fixes change what code sees. The Changelog lists everything else in 0.7.11.

Removed aliases

Affects: code that imports any of these. Changed in: @seedprotocol/sdk, @seedprotocol/publish, @seedprotocol/eas and @seedprotocol/arweave 0.7.11.

import { Db, FileManager } from '@seedprotocol/sdk/node'
import { configurePublish } from '@seedprotocol/publish'

import { NodeDb, NodeFileManager } from '@seedprotocol/sdk/node'
import { initPublish } from '@seedprotocol/publish'

Publish authorizations report revocation and expiry

Affects: code that calls assessPublishAuthorization or assessPublishAuthorizationLive, switches on PublishAuthorizationAssessStatus, or calls enrollPublishAutomation without expiresAt. Changed in: @seedprotocol/eas and @seedprotocol/publish 0.7.11.

PublishAuthorizationAssessStatus has a new value, 'revoked', so a switch that covers every case needs one more. assessPublishAuthorizationLive returns it for a revoked grant, which it reported as 'valid' in 0.7.10, and returns 'expired' once the attestation's EAS expiration has passed; its expirationTime is now set. Calling assessPublishAuthorization yourself, pass the attestation's revoked and expirationTime, which getPublishAuthorizationFromEas now returns.

import type { PublishAuthorizationAssessStatus } from '@seedprotocol/eas'

function grantLabel(status: PublishAuthorizationAssessStatus): string {
  switch (status) {
    case 'valid':
      return 'Active'
    case 'revoked':
      return 'Withdrawn'
    case 'expired':
      return 'Expired'
    case 'scope_mismatch':
    case 'unknown':
      return 'Not recognized'
  }
}

enrollPublishAutomation without expiresAt now ends the session key and its grant 365 days after enrollment. In 0.7.10 the key kept thirdweb's ten-year window while the grant's attestation expired after a year. Keys enrolled before keep their window. attestPublishAuthorization throws when wallet isn't the identity account. See Tool attestations.

clear() on an unloaded property writes nothing

Affects: code that calls clear() on a property it kept past the grace period. Changed in: @seedprotocol/sdk 0.7.11.

clear() on a stopped property rejects with EntityUnloadedError, as in 0.7.10, but now before it writes. In 0.7.10 the value was cleared anyway. Code that caught the error and counted the value as cleared has to look the property up again and clear it.

Tests see init errors

Affects: test suites that run the SDK with NODE_ENV=test or IS_SEED_DEV set. Changed in: @seedprotocol/sdk 0.7.11.

With either set, client.init used to carry on when storing its config or app state, adding the schema's models or, on Node, running migrations failed. It now rejects, as it does in production. A suite that passed only because of that fails at init. NODE_ENV=test still turns off offline retries.

Upgrading from 0.7.9 to 0.7.10

Released: 2026-10-24. The first four parts cover the release's main change, how long loaded instances stay in memory. The Changelog lists everything else in 0.7.10.

Lookups don't hold

Affects: code that calls unload() after Item.find, Item.all, ItemProperty.find or ItemProperty.all, and code that keeps an item it looked up across long work. Changed in: @seedprotocol/sdk 0.7.10.

Those four lookups take a cache hold only when called with hold: true. Item.create and ItemProperty.create still take one unless you pass hold: false, and so do Item.getById (until 0.7.12, see Item.getById doesn't hold) and Item.createById. unload() still releases one hold, but after a lookup without a hold you have none to release: the call releases a hold someone else took, such as a mounted useItem's, and the item can unload under them. Drop it:

import { Item } from '@seedprotocol/sdk'
import type { Post } from './types'

const post = (await Item.find({ modelName: 'Post', seedLocalId })) as Post | undefined
if (post) {
  showTitle(post.title)
  post.unload()
}

import { Item } from '@seedprotocol/sdk'
import type { Post } from './types'

const post = (await Item.find({ modelName: 'Post', seedLocalId })) as Post | undefined
if (post) showTitle(post.title)

Code that keeps the item longer than the grace period, such as a Node import or a long upload, holds it and releases the hold when it's done. Item.retain(item) takes a hold on an instance you already have.

import { Item } from '@seedprotocol/sdk'
import type { Post } from './types'

const post = (await Item.find({ modelName: 'Post', seedLocalId, hold: true })) as Post | undefined
if (!post) throw new Error('Post not found')
try {
  post.body = await renderBody(post.seedLocalId)
  await post.properties.find((p) => p.propertyName === 'body')?.save()
} finally {
  post.unload()
}

Schema, Model and ModelProperty lookups and creates take no hold either unless called with hold: true, but definitions stay cached until they're destroyed or evicted or the client stops, held or not. An unload() after one of those lookups can go too. See unload.

Unheld items unload after 60 seconds

Affects: apps that kept Item or ItemProperty instances without a hold and relied on them staying loaded. Changed in: @seedprotocol/sdk 0.7.10.

An Item or ItemProperty no one holds stays cached for the grace period, entityCache.unloadGraceMs in SeedConfig (60000 ms by default), after its last unload() or its last lookup without a hold, then stops. A hold taken meanwhile keeps the same instance. In 0.7.9 every lookup held, and an item no one unloaded never stopped. Hold the items you keep, as in Lookups don't hold, or raise the grace period:

import { client } from '@seedprotocol/sdk'
import schema from '../seed.schema.json'

await client.init({ config: { schema, entityCache: { unloadGraceMs: 10 * 60_000 } } })

Values above 2147483647 (about 24.8 days), Infinity included, unload at once, because a timer can't wait that long. 0 stops an instance at its last unload(), and an instance that was never held stays cached until it's evicted or the client stops.

Writes on an unloaded instance throw

Affects: code that writes to or publishes an instance it kept. Changed in: @seedprotocol/sdk 0.7.10.

Assigning a property, setValue(), save(), publish() and unpublish() on an Item or ItemProperty that has stopped throw EntityUnloadedError, with a message that names the item: Cannot set title on Post <seedLocalId>: this Item instance was unloaded. …. In 0.7.9 an assignment on a stopped instance did nothing and publish() never settled. Reads still return the last values. Look the item up again:

import { EntityUnloadedError, Item } from '@seedprotocol/sdk'
import type { Post } from './types'

async function setTitle(post: Post, title: string) {
  try {
    post.title = title
  } catch (error) {
    if (!(error instanceof EntityUnloadedError)) throw error
    const fresh = (await Item.find({ modelName: 'Post', seedLocalId: post.seedLocalId })) as Post | undefined
    if (fresh) fresh.title = title
  }
}

React hooks hold what they show

Affects: components that keep an item from useItem, useItems or useCreateItem outside the hook. Changed in: @seedprotocol/react 0.7.10.

useItem and useItems hold the items they show while mounted and release them on unmount, so an item no mounted hook shows unloads after the grace period. In 0.7.9 they kept every item loaded for the life of the page. Code that keeps using an item after its component unmounts, such as a save that finishes later, holds it with Item.retain(item) and calls unload() when done. The schema, model and model property hooks hold what they show the same way.

useCreateItem's createItem and useCreateItemProperty create without a hold. An instance you keep in state stops after the grace period, and the next assignment throws. Keep the seedLocalId and render the item through useItem, or pass hold: true as the third argument and unload() the item yourself:

import { useState } from 'react'
import type { Item } from '@seedprotocol/sdk'
import { useCreateItem } from '@seedprotocol/react'

export function useDraft() {
  const { createItem } = useCreateItem()
  const [draft, setDraft] = useState<Item<any>>()
  const start = async () => setDraft(await createItem('Post', { title: 'Untitled' }))
  return { draft, start }
}

import { useState } from 'react'
import { useCreateItem, useItem } from '@seedprotocol/react'

export function useDraft() {
  const { createItem } = useCreateItem()
  const [draftId, setDraftId] = useState<string>()
  const { item: draft } = useItem({ modelName: 'Post', seedLocalId: draftId })
  const start = async () => setDraftId((await createItem('Post', { title: 'Untitled' }))?.seedLocalId)
  return { draft, start }
}

useCreateModel and useCreateModelProperty create without a hold too; definitions stay cached anyway. See useItem and useCreateItem.

client.stop() returns a promise

Affects: code that calls client.stop() or client.unload(), keeps instances across a stop, or has a Node liveQuery subscription open when it stops. Changed in: @seedprotocol/sdk 0.7.10.

stop() and unload() return a Promise<void> that resolves once the outbox has stopped, every cached instance is stopped and dropped, in the browser this tab has handed leadership to another tab, and the database is closed. They work in any state, before init and after a failed one. An init called while a stop is running waits for it. An instance kept from before the stop is stopped for good: look the item up again after the next init.

import { client } from '@seedprotocol/sdk'

client.stop()

import { client } from '@seedprotocol/sdk'

subscription.unsubscribe()
await client.stop()

On Node, a BaseDb.liveQuery subscription still open at the stop no longer keeps the process alive: its next poll runs on the closed database and it gets an error (Failed query: …). Unsubscribe before stopping. From 0.7.12 the stop completes the subscription instead, with no error. See Stopping the client.

Older browsers fail with UnsupportedBrowserError

Affects: browser apps whose users may have an older browser, and onInitError handlers. Changed in: @seedprotocol/sdk 0.7.10.

Seed supports Chrome and Edge 102, Firefox 114 and Safari 26 or later. In a browser without OPFS, FileSystemFileHandle.createWritable or Web Locks, client.init rejects with UnsupportedBrowserError (code === 'BROWSER_UNSUPPORTED', the absent features in missing), and SeedProvider and SeedClientGate pass it to onInitError. A retry fails the same way, so show an update message instead of a retry button. checkBrowserSupport() checks before init. See UnsupportedBrowserError and Handling init errors.

Apps that install ZenFS move to 2.7.7

Affects: apps that list @zenfs/core or @zenfs/dom in their own dependencies, for example for fsModules in @seedprotocol/vite or @seedprotocol/next. Changed in: @seedprotocol/sdk 0.7.10.

The SDK pins @zenfs/core 2.7.7 and @zenfs/dom 1.2.14 (it was 2.5.6 and 1.2.9). Pin yours to the same versions, or two copies of ZenFS break the file system:

{
  "dependencies": {
    "@zenfs/core": "2.7.7",
    "@zenfs/dom": "1.2.14"
  }
}

createPublish doesn't hold the item

Affects: code that publishes with PublishManager.createPublish or ensureWalletThenPublish. Changed in: @seedprotocol/sdk and @seedprotocol/publish 0.7.10.

item.publish(), publishItem and usePublishItem hold the item until the publish settles. createPublish and ensureWalletThenPublish don't, and an item from Item.find now has no hold, so it can unload partway through a publish that outlasts the grace period. Hold it until the publish settles (from 0.7.12 createPublish holds it too, and your own hold does no harm):

import { Item } from '@seedprotocol/sdk'
import { PublishManager, getPublishWallet, waitForPublishActor } from '@seedprotocol/publish'

const post = (await Item.find({ modelName: 'Post', seedLocalId, hold: true })) as Item<any> | undefined
if (!post) throw new Error('Post not found')
try {
  const wallet = getPublishWallet()
  if (!wallet) throw new Error('Connect a wallet first.')
  const address = wallet.publisherAddress ?? wallet.signer.address
  const run = await PublishManager.createPublish(post, address, wallet, {
    dataItemSigner: wallet.dataItemSigner,
  })
  if (run) await waitForPublishActor(run, post.seedLocalId)
} finally {
  post.unload()
}

See PublishManager.createPublish.

seed-gateway checks --port

Affects: scripts that run seed-gateway connect with --port 0 or a port that isn't a number. Changed in: @seedprotocol/gateway-hyper 0.7.10.

--port 0 picks a free port, and the command prints the URL it listens on ([Seed Protocol] Local sidecar: http://127.0.0.1:<port>). A value that isn't a whole number from 0 to 65535 stops the command with --port must be 0–65535. In 0.7.9, 0 and a value that isn't a number fell back to 1984. See seed-gateway CLI.

Upgrading from 0.7.7 to 0.7.9

Released: 0.7.8 on 2026-10-20 and 0.7.9 on 2026-10-22. The parts are grouped by package, and each says which release made the change; within a group the 0.7.9 parts come first. 0.7.9 reverses some of 0.7.8's behavior, so each part describes what 0.7.9 does. From 0.7.8, read only the parts changed in 0.7.9. The Changelog lists everything else in 0.7.9 and 0.7.8.

Databases older than 0.7.7 are recreated

Affects: apps whose users last opened the app with SDK 0.7.6 or older. Changed in: @seedprotocol/sdk 0.7.9 and 0.7.11.

At the first start on 0.7.9 or later, a local database last opened by an SDK older than 0.7.7 is dropped and created again, with this console warning: [seed-protocol] This local database was written by an SDK older than 0.7.7. It is being recreated: unpublished items are dropped, and published items come back through EAS sync. From 0.7.11 the SDK first copies the database to seed.before-recreate-<ms>.db beside seed.db, and the warning ends A copy of the old database is at <path>.; when the copy fails, the database is opened as it is. Files under filesDir stay. The repairs that 0.7.1 to 0.7.6 databases got at start-up are gone with it.

The copy holds the drafts, but the SDK has no way to load them back. To keep your users' drafts in the app, have them publish before the upgrade, or ship 0.7.8 first and let the app start once on it before you move to 0.7.9: a database 0.7.8 has opened isn't recreated. A database last opened by 0.7.7 is recreated only if 0.7.7's background clean-up never finished in it; the same two steps keep its drafts, and 0.7.11 copies it first too. See Storage.

Rejected values stay shown

Affects: apps that show a value after validation rejected it, apps that use useDebouncedItemProperty, and apps that copied the useDraftProperty helper. Changed in: @seedprotocol/sdk and @seedprotocol/react 0.7.9.

This reverses Rejected values roll back. A value that breaks a rule stays on the property, post.title and the cached instance, with the reasons in saveValidationErrors, until the next assignment. It isn't written, so a fresh load or another process reads the stored value. useDebouncedItemProperty keeps the rejected text in the input with error set. Code that read property.value after a rejection as the stored value has to check saveValidationErrors first.

A write that's refused (an OwnershipError) or fails shows the property's current value again: its newest pending value from any tab, else the stored one. The ownership check now runs when the write is applied, after the setter returns.

Copies of the 0.7.7 useDraftProperty (the one with rolledBack and a setValue branch) show a false "Changed in another tab" after a refused write. Replace yours with the one in Hold unsaved text in the input; its signature and return value are the same. See Writing.

Writes go through the outbox

Affects: code that waits on save(), handles its errors, or reads the database right after an assignment. Changed in: @seedprotocol/sdk 0.7.8, 0.7.9 (errors from file writes, no time limit).

An assignment queues a write, and the leader tab applies it (The outbox). save() resolves once the write is applied. It no longer rejects after 10 seconds; from 0.7.12, save({ timeoutMs }) sets a limit. A write that fails when it's applied rejects with an error whose name is 'OutboxOpFailedError', code 'OUTBOX_OP_FAILED', and errorName the original error's class. That includes failed Image, File and Html writes ('TypeError' for a URL that can't be fetched, 'Error' for No file data found) and a Relation to a local item that doesn't exist ('RelationTargetError'). An ownership refusal is still an OwnershipError. Match code and errorName (OutboxOpFailedError is exported from 0.7.11):

try {
  await coverProp.save()
} catch (error) {
  if (error instanceof TypeError) showError("The image couldn't be downloaded.")
  else throw error
}

import { OutboxSaveTimeoutError, OwnershipError } from '@seedprotocol/sdk'

const failedAs = (error: unknown, errorName: string) =>
  (error as { code?: string }).code === 'OUTBOX_OP_FAILED' &&
  (error as { errorName?: string }).errorName === errorName

try {
  await coverProp.save({ timeoutMs: 30_000 })
} catch (error) {
  if (error instanceof OwnershipError) showError("You can't edit this post.")
  else if (error instanceof OutboxSaveTimeoutError) showError('Saving the cover is taking a while. It will finish in the background.')
  else if (failedAs(error, 'TypeError')) showError("The image couldn't be downloaded.")
  else throw error
}

timeoutMs is on the ItemProperty class; the IItemProperty type that item.properties holds doesn't declare it until 0.7.13. ItemCreateError's cause is usually such an error. See save.

setValue takes one argument

Affects: code that calls setValue(value, { before }). Changed in: @seedprotocol/sdk 0.7.9.

The before option and the PropertyValueSnapshot type are gone. To show a value without saving it, call showValue (new in 0.7.8); it no longer remembers a value to go back to.

titleProp.setValue(draft, { before: savedTitle })

titleProp.showValue(draft) // shown, not saved
titleProp.setValue(draft) // saved

status means loaded

Affects: code that compares an entity's status with 'idle', or calls waitForEntityIdle. Changed in: @seedprotocol/sdk 0.7.9.

status on a Schema, Model, ModelProperty, Item or ItemProperty is 'loading' | 'ready' | 'error'. Their machines start in idle, so 'idle' no longer means loaded. waitForEntityIdle is removed; each entity has waitForReady({ timeout }). useGlobalServiceStatus().status is the client manager's state and still reaches 'idle'.

import { waitForEntityIdle } from '@seedprotocol/sdk'

await waitForEntityIdle(post)
if (model.status === 'idle') showFields(model)

await post.waitForReady()
if (model.status === 'ready') showFields(model)

See Identity and metadata fields.

Request syncs with client.syncFromEas()

Affects: code that emits syncDbWithEas. Changed in: @seedprotocol/sdk 0.7.9.

The SDK no longer listens for any event, so eventEmitter.emit('syncDbWithEas') does nothing. Until 0.7.12, which logs a warning outside production, nothing warned. The same goes for fs.downloadAll.request; the download runs after each sync anyway. requestEasSyncFromEventBus and the 'event_bus' sync source are removed.

import { eventEmitter } from '@seedprotocol/sdk'

eventEmitter.emit('syncDbWithEas')

import { client } from '@seedprotocol/sdk'

await client.syncFromEas()

Synced values don't replace unpublished edits

Affects: apps that sync items the user also edits on another device, and apps that copied syncAndFindReplacedEdits from these docs. Changed in: @seedprotocol/sdk 0.7.8.

An unpublished edit now stays the value when sync brings a newer published one. If the synced value differs from both the edit and the value the edit replaced, the SDK records a conflict on the property (property.conflict, item.conflicts(), resolveConflict('local' | 'remote')). The docs' syncAndFindReplacedEdits helper, which found edits sync had replaced, finds nothing; use src/syncConflicts.ts from What wins when both devices edit. No React hook re-renders on a conflict, so read them after client.syncFromEas(). See Conflicts.

Item holds and blob: URLs

Affects: code that calls property.unload(), and code that keeps a blob: URL from an Image or File value. Changed in: @seedprotocol/sdk 0.7.8.

An item holds its properties, and its last unload() or destroy() stops the ones nobody else holds. Each ItemProperty.find() or create() is one hold, released by one property.unload(), so call item.unload() once rather than unloading each property. The SDK revokes a blob: URL it made for an Image or File value when the value changes and when the property stops; read property.value again after a change instead of keeping the URL. See unload and File, Image and Html properties.

Clearing a published value publishes the removal

Affects: apps that set a published property to '' or null, and publish code that reads getPublishPendingDiff or calls getPublishUploadData. Changed in: @seedprotocol/sdk 0.7.9.

An empty value used to be skipped at publish, so the old value stayed on chain. Now the next publish attests the type's empty value, and other apps read the property as absent. property.clear() does the same, and clear({ retract: true }) revokes the property's attestations instead (clear). Boolean and Date have no empty value: clear() rejects with ClearNotSupportedError, and a published Boolean or Date whose draft is empty fails publish validation with publish_clear_unsupported. On Image, File and Html, an empty value ('', null) clears the property. See Remove a published value.

For code that builds publishes itself: getPublishPendingDiff entries gain change ('set' | 'removed' | 'retracted'), and list a property under its storage name (authorId). getPublishUploadData(item, options) takes the options second. Publishing a property with no stored definition throws; it used to attest it as string <name>.

Schemas: ids from names, same-version edits replace the file

Affects: apps with config.schema files, apps that import schemas with importJsonSchema, and apps that define rules in code. Changed in: @seedprotocol/sdk 0.7.9.

• On a fresh database, ids the SDK assigns come from the names (the first 10 hex characters of SHA3-256 of blog, blog/Post, blog/Post/title), so adding a property no longer changes every id. A database that already has the schema keeps its ids, and an id in the file is used with or without $schema.
• An edit at the same version no longer duplicates models: the SDK warns and replaces the stored schema file, so the previous version's file is gone. Keep raising version with every edit.
• A schema is applied at start only when it changed; the first start after the upgrade applies it once more.
• importJsonSchema(input, version) uses version only when the JSON has none. Minimal <name>-v<n>.json files in the working directory are no longer imported at init.
• Validation rules on properties defined in code are stored with the property and apply after a restart.

See The schema file format.

Raw SQL reads

Affects: apps that query metadata themselves. Changed in: @seedprotocol/sdk 0.7.8 (outbox), 0.7.9 (names).

An edit reaches metadata when its write is applied, so await property.save() before reading it. New rows store a single Relation, Image, File or Html property under its storage name (authorId), and rows are matched to their property by propertyId: group or filter on propertyId (rows without one by their name), as pickLatestMetadataRowPerProperty does. See Tables.

Removed exports

Affects: code that imports any of these. Changed in: @seedprotocol/sdk 0.7.9.

EasClient from the main entry is now BaseEasClient from @seedprotocol/eas, and on Node the SDK registers NodeEasClient, which keeps its own connection pool. To send EAS requests through fetch's defaults, after client.init:

import { EasClient } from '@seedprotocol/sdk'
import { NodeEasClient } from '@seedprotocol/eas/node'

EasClient.configure(new NodeEasClient({ dispatcher: false }))

See Using Seed in Node and Electron.

Smaller SDK changes

• addresses.persisted fires only when the owned or watched addresses differ from the ones this tab last announced (0.7.8). A setAddresses() call that changes nothing no longer fires it.
• Item.all waits for its items only with waitForReady: true (0.7.8); the default returns them while they load. It also takes a signal.
• watchEntityRows has no since option (0.7.9).

React hooks

Affects: apps that use @seedprotocol/react. Changed in: @seedprotocol/react 0.7.8, 0.7.9 where marked.

useCreateModelProperty().create returns a Promise of the ModelProperty:

const property = create('blog', 'Post', { name: 'summary', dataType: 'Text' })

const property = await create('blog', 'Post', { name: 'summary', dataType: 'Text' })

• useCreateItem's createItem takes ItemCreateOptions third, so { validate: false } works there. A call made while another is in flight returns the first call's promise and item, whatever model and values it was given, and creates nothing; it used to return undefined. Await one create before starting the next. From 0.7.12 only a repeat of the same call shares the first one's item. See useCreateItem.
• After client.stop(), the status hooks and SeedClientGate follow the next client.init(), so a key that remounted the gate can go. See After client.stop().
• Hooks outside SeedProvider. useItems and useItemProperties still throw without it. The others fall back to a shared client and log a development warning, and from 0.8 they will throw too. See Which hooks need SeedProvider.
• react-dom 18 or 19 is a peer dependency.
• Live query errors from useLiveQuery and BaseDb.liveQuery go to debug (seedSdk:browser:db:Db), not console.error; the hook still returns them.
• SeedProvider no longer refetches useItemProperties on itemProperty.saved (0.7.9); it refetches once per save, when the change feed (on Node, its live query) reports the write.
• isClientReadySnapshot comes from @seedprotocol/sdk (0.7.9). @seedprotocol/react re-exports it from 0.7.12.

Publishing uploads only signed data items

Affects: apps that set useArweaveBundler, arweaveJwk or signArweaveTransactions, apps that left useArweaveBundler unset, and code that compares a cost estimate's path with 'l1'. Changed in: @seedprotocol/publish 0.7.9.

The L1 path is gone: every publish uploads signed data items through the upload API, or to Turbo with payment: { storage: 'user' }. useArweaveBundler: true changes nothing, useArweaveBundler: false makes initPublish throw PublishPaymentConfigError, and arweaveJwk and signArweaveTransactions are removed. An app that left useArweaveBundler unset used the L1 path and now needs a data item signer for items with Image, File or Html values: ConnectButton registers one, or pass dataItemSigner or signDataItems.

initPublish({ ...config, useArweaveBundler: false, arweaveJwk })

import { initPublish } from '@seedprotocol/publish'

initPublish({ ...config, uploadApiBaseUrl: '/seed-api' })

A publish saved during an L1 step comes back interrupted; publish the item again. An estimate's arweave.path is always 'bundler'. See initPublish.

Publishing also revokes retracted properties after the attestations. A failure there waits in the new retractionFailureRecoverable state, which PublishManager.retryAttestations retries, so add it wherever your code lists recoverable states. item.unpublish() revokes the Seed first, then the properties, then the Versions. See Handle failures and resume.

query, eas and feed

Affects: apps that use @seedprotocol/query, @seedprotocol/eas or @seedprotocol/feed. Changed in: 0.7.9, except where marked.

expandRelations is replaced by relations: 'expand' | 'urls' | 'uids' (0.7.13 removes 'urls'; see relations: 'urls' is removed). An expandRelations option passed from untyped code is ignored, so relations come back expanded.

const posts = await queryBySchema('post', { expandRelations: false })

import { queryBySchema } from '@seedprotocol/query'

const posts = await queryBySchema('post', { relations: 'urls' })

• query: the …Feed… aliases are removed (use the names without Feed), and so are QueryCacheConfig.backgroundRefresh and refreshInterval. queryBySchemaForMonth bounds the month in UTC. A property whose attestation is the empty value is left out of the record. See queryBySchema.
• eas: getEasSchemaUidBySchemaName and fetchEasSchemaUidBySchemaName are removed. Look a property schema up by its full definition with getEasSchemaUidForExactDefinition('bytes32 post'), a model's with the model schema lookup. An IEasClient of your own gets the 30-second request limit (0.7.8) only if it builds its client with createEasGraphQLClient.
• feed: FEED_SITE_URL and FEED_EXPAND_RELATIONS are removed (feeds always expand relations), as are initializeSeedClient, getClient and teardownSeedClient (use initializeFeedPlatform and teardownFeedPlatform), and GraphQLItem is now FeedItem. TransformOptions requires itemUrlBase and itemUrlPath. initializeFeedPlatform keeps EAS and Arweave clients already registered. The first page is checked on every request, and its Cache-Control max-age is CACHE_MAX_AGE (default 0, was 3600). Archive months are UTC. See Caching.

Upgrading from 0.7.5 to 0.7.7

Released: 0.7.6 and 0.7.7, both on 2026-10-18. Each part says which release made the change. From 0.7.6, read only the parts changed in 0.7.7, which come first. The Changelog lists everything else in 0.7.7 and 0.7.6.

Client calls after client.stop() throw

Affects: code that uses the client after client.stop() or client.unload(), or stops it twice. Changed in: @seedprotocol/sdk 0.7.7.

After stop() or unload(), client methods such as getAddresses, setAddresses and syncFromEas throw ClientManager is not initialized. Please call init() first. until client.init runs again. They used to keep working on the open database. A second stop() or unload() logs a console.warn and returns.

client.stop()
const { owned } = await client.getAddresses() // read the stopped client's database

const { owned } = await client.getAddresses()
client.stop()

See client.

Errors keep their class

Affects: code that matches the message of an error from save(), item.publish() or usePublishItem. Changed in: @seedprotocol/sdk 0.7.7.

ItemProperty.save() and item.publish() reject with the error that was thrown. They used to reject with a new Error that copied its message, so instanceof, code and cause were lost. usePublishItem's error is the same error. save()'s message no longer starts with Failed to save property <name>: :

try {
  await coverProp.save()
} catch (error) {
  if (error instanceof Error && error.message === 'Failed to save property cover: No file data found') {
    showError('Choose an image file.')
  }
}

import { OwnershipError } from '@seedprotocol/sdk'

try {
  await coverProp.save()
} catch (error) {
  if (error instanceof OwnershipError) showError("You can't edit this post.")
  else if (error instanceof Error && error.message === 'No file data found') showError('Choose an image file.')
  else throw error
}

A publish that fails after it started rejects with Publish of <seedLocalId> failed at <step>: …, and its cause is now the step's own error, such as a ManagedAccountPublishError. See save and publish.

Rejected values roll back

Affects: apps that show a value after validation rejected it, and apps that copied the useDraftProperty helper. Changed in: @seedprotocol/sdk 0.7.7.

A value that fails its property's rules doesn't stay in memory any more: property.value, post.title, Item.find and Item.all return the value from before the assignment, as they already did after an ownership refusal. The reasons are still in saveValidationErrors. To keep the user's invalid text on screen so they can fix it, hold it in component state.

The useDraftProperty helper from earlier versions of these docs breaks on this: after a rejected value it shows a false "Changed in another tab" and drops the text on blur. 0.7.9 reverses the rollback and removes setValue's before option, so take the current helper as Rejected values stay shown says.

Item.create throws ItemCreateError

Affects: code that handles Item.create failures for File, Image, Html or ItemStorage values. Changed in: @seedprotocol/sdk 0.7.7.

When one of those values fails to save for a reason other than its property's rules, Item.create throws ItemCreateError instead of a plain Error. The message is the same, so code that matched it keeps working. Its code ('save_failed' or 'property_not_loaded'), property and cause say what failed:

import { Item, ItemCreateError } from '@seedprotocol/sdk'

const values = { modelName: 'Post', schemaName: 'Blog', title, attachment: file }

try {
  await Item.create(values)
} catch (error) {
  if (error instanceof ItemCreateError) showFieldError(error.property, "This file couldn't be saved.")
  else throw error
}

ItemCreateError is exported from @seedprotocol/sdk, not from @seedprotocol/sdk/node. See Item.create.

File values work after a reload

Affects: apps that worked around a File value going stale after a page reload. Changed in: @seedprotocol/sdk 0.7.7.

Each time an item loads, the SDK makes a new URL for its File and Image values, so property.value works as a link in a later session. A hook that rebuilt the URL with FileManager.getContentUrlFromPath, like the useFileUrl these docs used to show, can go:

const { property } = useItemProperty({ seedLocalId, propertyName: 'attachment' })
const url = useFileUrl(property) // a fresh blob: URL from property.localStoragePath

const { property } = useItemProperty({ seedLocalId, propertyName: 'attachment' })
const url = property?.value

The first init after the upgrade clears the URLs that 0.7.5 and 0.7.6 stored with File and Image values. See Offer a file for download.

Relations hold Seed UIDs after a publish

Affects: code that compares a Relation or List value with a related item's seedLocalId. Changed in: @seedprotocol/sdk and @seedprotocol/publish 0.7.7.

Publishing an item rewrites its stored Relation values to the related items' seedUids, and a List of relations to a JSON array of them, as an EAS sync of the same attestations stores them. They used to keep the drafts' seedLocalIds. Compare against both IDs:

const theirPosts = posts.filter((post) => post.author === author.seedLocalId)

const ids = [author.seedLocalId, author.seedUid].filter(Boolean)
const theirPosts = posts.filter((post) => post.author && ids.includes(post.author))

See Relations between items and Find the items that point at an item.

Direct EAS refuses updates to earlier requests

Affects: apps that build or reorder publish batches themselves and attest straight to EAS. Changed in: @seedprotocol/publish 0.7.7.

On the direct-EAS route, a propertiesToUpdate entry that targets a request attested earlier in the batch is refused before anything is sent, with ManagedAccountPublishError code PUBLISH_PREFLIGHT_FAILED. Before, the update was applied to a request already sent and never reached the chain. The SDK's own batches don't contain such entries, so item.publish() isn't affected. See Rules and errors.

Production hosting must send the isolation headers

Affects: browser apps whose host doesn't send Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy. Changed in: @seedprotocol/sdk 0.7.6.

Without cross-origin isolation, SQLite can't keep the database in the browser's private file system (OPFS). The client used to fall back to an in-memory database, which lost everything on reload. Browser client.init now rejects with DatabaseNotPersistentError (code: 'DB_NOT_PERSISTENT'), and the error reaches SeedClientGate's and SeedProvider's onInitError. The dev server gets the headers from the Vite plugin; check that your production host sends them too. See Headers in production, Production hosting for Next.js, and DatabaseNotPersistentError.

Install @seedprotocol/vite to import @seedprotocol/sdk/vite

Affects: apps that import the plugin from @seedprotocol/sdk/vite. Changed in: @seedprotocol/sdk 0.7.6.

@seedprotocol/vite is an optional peer of the SDK, no longer a dependency, so installing the SDK doesn't bring Vite with it. @seedprotocol/sdk/vite still re-exports the plugin, but only when your app installs @seedprotocol/vite; otherwise the import fails with ERR_MODULE_NOT_FOUND: Cannot find package '@seedprotocol/vite'. Install it and import from it:

npm install --save-dev @seedprotocol/vite

import { seedVitePlugin } from '@seedprotocol/sdk/vite'

import { seedVitePlugin } from '@seedprotocol/vite'

The Vite plugin's defaults changed

Affects: apps that use seedVitePlugin. Changed in: @seedprotocol/vite 0.7.6.

The plugin now does less by default: it sends the isolation headers, builds workers as ES modules, keeps the dev pre-bundle in order and dedupes the packages your app has. The Node polyfills and fs aliases are opt-in, and it sets no optimizeDeps.include or exclude lists. What the plugin configures lists everything. To upgrade:

1. Delete node_modules/.vite and restart the dev server.
2. Remove autoInit from the plugin's options. It's no longer in the options type, so TypeScript rejects it, and from 0.7.12 the plugin throws on it.
3. Remove workarounds copied from older plugin versions or app configs: optimizeDeps.exclude entries for Seed packages, sqlocal, drizzle-orm or SQLite WASM, optimizeDeps.include entries for the SDK's dependencies, and aliases for nanoid-dictionary, debug or the ZenFS entry files. Under pnpm, an exclude entry for the SDK breaks vite dev.
4. Drop node-linker=hoisted from .npmrc if you added it for Seed. pnpm's default layout works.
5. Set includeNodePolyfills: true only if another dependency of your app needs Node built-ins or the Buffer, process or global globals in the browser. The SDK, @seedprotocol/react and @seedprotocol/publish don't.
6. Set fsModules: ['fs', 'fs/promises', 'node:fs', 'node:fs/promises'] only if your own code or a dependency imports fs in the browser.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { seedVitePlugin } from '@seedprotocol/vite'

export default defineConfig({
  plugins: [react(), ...seedVitePlugin({ autoInit: true })],
  optimizeDeps: { exclude: ['@seedprotocol/sdk', 'sqlocal'] },
})

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { seedVitePlugin } from '@seedprotocol/vite'

export default defineConfig({
  plugins: [react(), ...seedVitePlugin()],
})

Before 0.7.12, includeNodePolyfills didn't cover timers, so a page that called rssXmlToSources from @seedprotocol/mapping failed after vite build with Module "timers" has been externalized for browser compatibility. 0.7.12 polyfills it; see In a browser. Troubleshooting lists the errors a leftover workaround produces.

Import Drizzle operators from the SDK

Affects: apps that install drizzle-orm to write their own queries. Optional. Changed in: @seedprotocol/sdk 0.7.6.

@seedprotocol/sdk/drizzle re-exports drizzle-orm from the SDK's own copy, so your app doesn't have to install Drizzle or keep it on 0.44:

import { eq } from 'drizzle-orm'