Overview and initPublish

@seedprotocol/publish is the write path to the public networks. It takes an item from the SDK's local database, uploads its files to Arweave, and makes its EAS attestations from the user's account. It also handles wallets, cost estimates, revocation and a few tool attestations. The SDK and @seedprotocol/react don't publish anything on their own: the SDK's item.publish() and react's usePublishItem hand the item to this package, and fail with "Publishing is not configured" until initPublish has run.

import { initPublish, getPublishConfig, PublishManager } from '@seedprotocol/publish'

Install

npm install @seedprotocol/sdk @seedprotocol/publish
npm install thirdweb # for @seedprotocol/publish/thirdweb

Publish declares these peer dependencies: @seedprotocol/sdk and @seedprotocol/react at exactly its own version, react and react-dom (18 or 19), @tanstack/react-query 5, and thirdweb 5. thirdweb is optional: the root entry point loads without it. You need it for @seedprotocol/publish/thirdweb (ConnectButton and the in-app wallets), and for useModularExecutor with a wallet that doesn't send as the ManagedAccount (Wallets). @tanstack/react-query isn't optional: the root entry point fails to load without it, on Node too. npm refuses an SDK at another version with ERESOLVE unable to resolve dependency tree. Don't get past that with --legacy-peer-deps: npm then installs the mismatched SDK and leaves out @seedprotocol/react. The Seed toolkit has the same-version rule for every package. npm may also print ERESOLVE overriding peer dependency warnings about ox, which permissionless depends on; the install completes.

On Node, run any process that loads the publish package with node --import @seedprotocol/sdk/node-eas-lodash (the SDK alone doesn't need it). See Using Seed in Node and Electron.

Entry points

Both entry points export PublishProvider and usePublishConfig. The two PublishProviders differ only in whether they wrap thirdweb's provider. See Components and hooks.

Importing the root entry point in a browser starts PublishManager straight away, and it resumes any publish the local database has marked in_progress. A publish it can't resume, such as one cut off while uploading through the upload API or Turbo, is marked interrupted instead, and the user publishes again. A publish another open tab is still running is left to that tab. On Node, nothing starts until you call PublishManager.ready().

initPublish

Registers the publish configuration and the executors behind the SDK's item.publish() and item.unpublish(). Call it once, at module level, before anything renders or publishes.

function initPublish(config: PublishConfig): void

It checks the config first, and throws without registering anything when:

• payment contradicts another option (PublishPaymentConfigError);
• useArweaveBundler is false (PublishPaymentConfigError): "useArweaveBundler: false is no longer supported. Publish uploads signed data items through the upload API's bundler routes (or Turbo with payment.storage: 'user'); remove the option.";
• uploadApiBaseUrl is empty and payment.storage isn't 'user': "initPublish: uploadApiBaseUrl is required (the upload API that stores files on Arweave), unless payment.storage is "user".";
• uploadApiBaseUrl is set but isn't an absolute http(s) URL or a path from the page's origin such as /seed-api: "initPublish: uploadApiBaseUrl must be an absolute http(s) URL or a path from the page's origin, got "<value>".";
• the chain has no known EAS deployment and you didn't pass easContractAddress and schemaRegistryAddress;
• SeedConfig.eas.chainId names a different chain from the publish chain.

It checks nothing else, so any other missing option surfaces later, when something needs it. Then it:

• points the SDK's EAS reads (sync, schema lookups) at the publish chain. Until it runs, the SDK's EAS sync waits for it;
• registers the publish executor (publishItem), so item.publish() and react's usePublishItem publish;
• registers the revoke executor, so item.unpublish() works;
• sets the publisher stamped on new drafts to the registered publish wallet's publisherAddress (or its signer's address);
• starts a background worker in the leader tab that follows each upload until it lands in an Arweave L1 bundle (it polls every 45 seconds);
• with useModularExecutor and modularAccountModuleContract, adds the executor address to the addresses the SDK syncs.

Example

import { initPublish, type PublishConfig } from '@seedprotocol/publish'

export const publishConfig: PublishConfig = {
  thirdwebClientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID,
  uploadApiBaseUrl: import.meta.env.VITE_UPLOAD_API_BASE_URL,
  useModularExecutor: true,
  autoDeployManagedAccount: true,
}

initPublish(publishConfig)

This is the setup these docs recommend for an app that uses ConnectButton:

• useModularExecutor: true has ConnectButton connect the in-app wallet and publish from the ManagedAccount it administers. The in-app wallet signs the data items, so item.publish() needs no dataItemSigner.
• autoDeployManagedAccount: true is what deploys a new user's ManagedAccount in this setup, just before its first attestations. Without it, that user's first publish fails at creatingAttestations with MANAGED_ACCOUNT_NOT_DEPLOYED.

VITE_UPLOAD_API_BASE_URL is the address of an upload API your app can reach, such as a local Gateway Hyper sidecar at http://127.0.0.1:1984 or your own server's proxy. There's no public Seed upload API (Seed's gateway); without one, use payment: { storage: 'user' }.

Options

Connection and chain

thirdweb wallets (thirdweb)

Account mode for other wallets (EIP-1193, viem, Privy, ethers)

Attestation routing

checking picks the route. With useDirectEas, the publish attests straight to EAS and skips the checks below. Each item takes up to three transactions: an attest for a new Seed, an attest for a new Version, and one multiAttest for its properties. With useModularExecutor, it always calls multiPublish through the ManagedAccount, and autoDeployManagedAccount deploys the account first in creatingAttestations when it has no code. A wallet that sends as its publisherAddress, with a different signer and a kind other than 'eoa', skips that step and the in-app wallet, so its account must already be deployed. Otherwise the publisher address decides: an address with contract code publishes through multiPublish on the Seed contract inside the account, and one with no code attests straight to EAS. An EIP-7702-delegated EOA counts as having no code.

Attesting straight to EAS without useDirectEas needs a wallet that says it's an EOA (kind: 'eoa', see Wallets) and both sends and signs as the publisher. A wallet with no kind takes the registered publish wallet's kind when it has the same signer. checking refuses the publish otherwise:

• The wallet has kind: 'smart' or 'modular': the publisher is an undeployed smart account. If the registered publish wallet publishes as that address and has a deploy function, checking calls it, waits until the RPC shows the account's code, and publishes through multiPublish. ConnectButton registers one for its smart wallet, so a new user's first publish deploys the account. Without one, it fails with ManagedAccountPublishError code MANAGED_ACCOUNT_NOT_DEPLOYED: "The publishing smart account <address> is not deployed on <chain> yet. Deploy it first (your wallet's setup flow, or deploySmartWalletContract from @seedprotocol/publish/thirdweb), then publish again."
• It sends as another address, which EAS would record as the attester: "The publish wallet sends as <sender>, not as the publisher <address>, which has no contract deployed on <chain>. …"
• It signs as another address: "The publish wallet signs as <signer>, not as the publisher <address>. Attesting directly to EAS would record the wrong attester."
• It has no kind: "The publisher <address> has no contract on <chain>, and the publish wallet doesn't say whether it is an EOA or an undeployed smart account. Build it with fromEip1193Provider or fromEthersWallet, set kind: 'eoa' on the PublishWallet, or set useDirectEas to attest directly anyway."

When the code lookup itself fails, the publish fails with "Could not verify whether the publisher is a deployed contract on <chain>. Check your RPC connection and retry."

multiPublish needs this package and the deployed contracts to be the same version. Before sending, a contract publish runs assertMultiPublishRouted, and on contracts without the selector it sends (MULTI_PUBLISH_SELECTOR, 0xa1263421) it fails with ManagedAccountPublishError code MULTI_PUBLISH_NOT_ROUTED: "…The deployed contracts and this SDK are different versions; nothing was sent." The check passes when it can't run, and the simulation decides. Direct EAS calls no Seed contract and has no such requirement.

Arweave uploads

Each file goes up as an ANS-104 data item signed by the user's key, in one batch to the upload API, whose bundler pays; with payment.storage: 'user' the data items go straight to Turbo instead, paid from the signer's Turbo credits. See Uploads and ANS-104 data items.

Who pays and approval

Costs and hooks

Approving publishes

authorizePublish runs as the first step of every publish (authorizing), before it registers schemas, uploads or attests anything. Use it to confirm the cost with the user, check a quota, or charge for the publish.

type AuthorizePublish = (request: {
  item: IItem<any>
  seedLocalId: string
  publishMode: 'patch' | 'new_version'
  payment: ResolvedPublishPayment // who will pay, as resolvePublishPayment returns it
  getEstimate: () => Promise<PublishCostEstimate> // fetches prices: call it only if you need it
}) => PublishAuthorization | boolean | void | Promise<PublishAuthorization | boolean | void>

type PublishAuthorization = { token?: string }

• Return false, or throw, to refuse: the publish fails at authorizing with PublishNotAuthorizedError (a thrown error becomes its cause).
• Return true, nothing, or {} to go ahead.
• Return { token } to go ahead and send the token to the upload API as the X-Seed-Publish-Authorization header (PUBLISH_AUTHORIZATION_HEADER) on this publish's upload requests (/api/upload/arweave/batch), so its operator can meter or bill against it. It isn't sent to Turbo.

A publish resumed after a reload isn't asked again once it got past authorizing. One restored before that asks the config's hook, because a per-publish hook isn't saved.

import { initPublish, type PublishConfig } from '@seedprotocol/publish'

export const publishConfig: PublishConfig = {
  thirdwebClientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID,
  uploadApiBaseUrl: import.meta.env.VITE_UPLOAD_API_BASE_URL,
  useModularExecutor: true,
  autoDeployManagedAccount: true,
  authorizePublish: async ({ getEstimate }) => {
    const { work } = await getEstimate()
    return window.confirm(`Publish ${work.attestationCount} attestations and ${work.uploadCount} uploads?`)
  },
}

initPublish(publishConfig)

getPublishConfig

Returns the config with defaults applied.

function getPublishConfig(): ResolvedPublishConfig

Throws "@seedprotocol/publish: Call initPublish() or ensure PublishProvider is mounted with config before using the publish package" when nothing has registered a config.

Returns

Every PublishConfig field you passed, plus these resolved ones:

usePublishConfig() returns the raw PublishConfig from React context, without these defaults.

Example

import { getPublishConfig } from '@seedprotocol/publish'

export function attestationLink(seedUid: string) {
  const { easChain } = getPublishConfig()
  return `${easChain.explorerUrl}/attestation/view/${seedUid}`
}

item.publish() and publishItem

Once initPublish has run, the SDK's item.publish(options) publishes. It hands the item to publishItem, the executor initPublish registers, which starts a publish with the registered publish wallet and waits for it to finish. React's usePublishItem calls item.publish() too.

function publishItem(item: IItem<any>, options?: ItemPublishOptions): Promise<void>
function waitForPublishActor(actor: ActorRef<any, any>, seedLocalId: string): Promise<void>

options are CreatePublishOptions. publishItem waits for PublishManager.ready(), starts the publish through ensureWalletThenPublish (which hands it to ensureSmartWalletThenPublish with useModularExecutor, unless the registered wallet sends as its publisher), and resolves when the publish reaches success. Like every publish, it holds the item until the publish settles, so an item looked up without a hold doesn't unload mid-publish. It signs data items with the signer createPublish defaults to.

publishItem rejects with the errors below. item.publish() rejects with the same object and usePublishItem sets it as its error, so instanceof ManagedAccountPublishError and its code work there too. UploadTooLargeError and UploadNeedsConfirmError arrive as themselves, so instanceof and their estimate work too. Any other failure at a step and a failed attestation reject with a plain Error whose cause is the error the publish stopped on. The rejections item.publish() adds before the publish starts (ownership, already publishing) are on Item.

• "No publish wallet is connected. Connect one (useSeedWallet().connect, or setPublishWallet) before publishing." or "The publish wallet has no publisher address." when nothing usable is registered. With useModularExecutor, an empty registry gives the second. These are plain Errors; a PublishManager.createPublish run with no wallet fails in checking with PublishWalletMissingError (code: 'PUBLISH_WALLET_MISSING') and the same text, which waitForPublishActor gives as cause;
• a ManagedAccountPublishError (MANAGED_ACCOUNT_UNAVAILABLE) with useModularExecutor, when the in-app wallet or its ManagedAccount isn't connected;
• "Publish of <id> did not start: it is already publishing in this tab or another.";
• UploadTooLargeError (code: 'UPLOAD_TOO_LARGE') or UploadNeedsConfirmError (code: 'UPLOAD_NEEDS_CONFIRM') from the upload limits;
• "Publish of <id> failed at <step>: …" when the publish ends in failure. For example at authorizing when authorizePublish refuses, or at checking with one of the refusals under Attestation routing in Options;
• "Creating attestations for <id> failed: …. Uploads are kept; retry with PublishManager.retryAttestations('<id>')." when it stops in a recoverable attestation failure;
• a PublishRetractionError (code: 'PUBLISH_RETRACTION_FAILED') when the attestations were made but revoking the retracted properties failed (retractionFailureRecoverable): "Revoking the retracted properties of <id> failed: …. The new attestations are in place; retry with PublishManager.retryAttestations('<id>') to send the revocation again.";
• "Publish of <id> was stopped before it finished." when something stops it, such as stopPublish, or ConnectButton when another wallet takes over or the user disconnects.

waitForPublishActor is the waiting half on its own, for an actor from createPublish.

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

// With the recommended config (useModularExecutor) and ConnectButton.
export async function publishPost(post: Item<any>) {
  // The in-app wallet signs the data items; the ManagedAccount attests.
  await post.publish()
}

PublishManager

The object that runs publishes. Each publish is a state machine for one item, keyed by its seedLocalId, and each step is saved to the local publish_processes table.

const PublishManager: {
  createPublish(
    item: Item<any>,
    address: string,
    account?: PublishWallet,
    options?: CreatePublishOptions,
  ): Promise<ActorRef<any, any> | undefined>
  retryAttestations(seedLocalId: string, account?: PublishWallet): void
  stopPublish(seedLocalId: string): void
  stopAll(): void
  ready(): Promise<void>
  getPublish(seedLocalId: string): ActorRef<any, any> | undefined
  query(seedLocalId: string): Snapshot | undefined
  getService(): ActorRef<any, any>
}

Simplified: the real return types are XState actor and snapshot types. PublishManager also has savePublish, addSubscription and removeSubscription, which the package uses internally.

PublishManager.createPublish

Starts publishing one item.

createPublish(item, address, account?, options?): Promise<ActorRef<any, any> | undefined>

It resolves as soon as the publish has started, with its actor. The publish carries on in the background; follow it with useItemPublishStatus. It resolves undefined, without starting anything, when:

• address is empty;
• the item is already publishing in this tab;
• another tab holds the item's publish lock (a Web Lock named seed:publish:<seedLocalId>).

Calls made before the manager has finished restoring saved publishes are queued and run once it's ready.

A publish holds its item until it stops (success, failure or stopped), so an item you found without a hold doesn't unload after the grace period mid-upload. A publish waiting in a recoverable failure keeps the hold. An item that isn't in the cache takes none. See unload.

CreatePublishOptions

Items with Html, Image or File values need a signer for their uploads, dataItemSigner or signDataItems, from the options or the config. Without either, the publish fails at creatingArweaveDataItems with "@seedprotocol/publish: uploading data items needs signDataItems or a dataItemSigner (pass one at createPublish or in the PublishProvider config). It must be an EOA's key: …".

A dataItemSigner you pass here is kept in memory only, not in the publish's publish_processes row. A publish resumed after a reload falls back to the config's dataItemSigner. Rows saved by 0.7.3 or earlier can still hold an arweaveJwk in a database a later release has opened since; clear completed run history to delete them.

What a publish does

1. authorizing: calls authorizePublish, if you set one. Without it, this step passes straight through.
2. checking: checks that the item is owned (isItemOwned), that the local database and RPC are on the publish chain, that no related item has been unpublished, that the upload limits allow the publish (from file sizes, before any file is read), and that there's a publisher address; when the item has retracted properties, checks that the wallet can revoke their attestations and fails if it can't (an automation session key, or a Seed the executor attested); fails with PublishWalletMissingError when the run has no wallet and none is registered; registers, with account, the missing EAS schemas this publish attests under (the model of the item and of each draft published with it, each property that has a value or whose empty value removes a live attestation, and string storage_transaction_id for a seed that uploads a file), checking them all before it sends anything; an automation session key can't register schemas, so a missing one fails the publish with EasSchemasNotRegisteredError; picks multiPublish or direct EAS; validates the item for that route; deploys or refuses an undeployed smart account (Attestation routing in Options), validating again after a deploy.
3. Arweave steps, only when the item or a related item has Html, Image or File values: preparingHtmlEmbedded, creatingArweaveDataItems, uploadingViaBundler (which uploads to Turbo with payment.storage: 'user'). Html with materialized images then runs rewritingHtmlEmbedded and a second pass, on either attestation route: creatingArweaveDataItemsPhase2 and uploadingViaBundlerPhase2.
4. creatingAttestations (multiPublish) or creatingAttestationsDirectToEas. multiPublish sends the item and every draft published with it in one transaction, so a failure attests none of them, and both sides of a relation cycle between drafts are attested together. With useModularExecutor, creatingAttestations first deploys the ManagedAccount when autoDeployManagedAccount is set and it has no code. Before sending, it simulates the call and estimates its gas from the sending account (the estimate plus 30%, or 5,000,000 when no estimate can be made). A publish that needs more gas than a block holds fails with ManagedAccountPublishError code PUBLISH_TOO_LARGE and nothing is sent; publish some of its related drafts on their own first. The direct-EAS route goes request by request and records each Seed locally as soon as it's attested, so a retry after a partial failure doesn't attest it again. On that route a relation back to an item the publish is still creating is left out for the item's next publish.
5. revokingRetractedProperties: revokes the attestations of retracted properties that are still live, one multiRevoke per schema from the Seed's attester, and marks them retracted locally. With nothing retracted it passes straight through. An EOA publisher signs this as a second transaction.
6. success or failure.

A failure before the attestations ends in failure. A failure while attesting waits in attestationFailureRecoverable (or attestationFailureRecoverableDirectToEas) with the uploads kept, for retryAttestations. A failure while revoking waits in retractionFailureRecoverable with the attestations made; retryAttestations sends the revocations again, and the next publish also sends any still live. A publish an older release saved in a step that no longer exists is marked interrupted when it's restored; publish the item again. Publishing and revoking items covers each case.

Example

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

// With the recommended config (useModularExecutor) and ConnectButton,
// the registered wallet is the in-app wallet and publisherAddress is its ManagedAccount.
export async function publish(item: Item<any>) {
  const wallet = getPublishWallet()
  if (!wallet) throw new Error('Connect a wallet first.')
  const address = wallet.publisherAddress ?? wallet.signer.address
  const run = await PublishManager.createPublish(item, address, wallet)
  return run !== undefined // false: already publishing here or in another tab
}

PublishManager.retryAttestations

Retries the attestations of a publish waiting in attestationFailureRecoverable or attestationFailureRecoverableDirectToEas, without uploading again, or the revocations of one waiting in retractionFailureRecoverable.

retryAttestations(seedLocalId: string, account?: PublishWallet): void

Uses account, or the registered publish wallet when omitted. Returns nothing; follow the result with useItemPublishStatus. Does nothing (and logs a warning) when this tab isn't running a publish for that item.

PublishManager.stopPublish

Stops one publish and marks its row interrupted. Releases its publish lock.

stopPublish(seedLocalId: string): void

Nothing already uploaded or attested is undone.

PublishManager.stopAll

Stops every publish running in this tab and releases their locks.

stopAll(): void

Unlike stopPublish, it leaves their rows in_progress, so the next page load resumes them. ConnectButton calls it when the user disconnects and when another wallet takes over; see ConnectButton.

PublishManager.ready

Starts the manager if it hasn't started, and resolves once it has restored saved publishes and is accepting new ones.

ready(): Promise<void>

In the browser the manager starts on import, so you don't need it. On Node, call await PublishManager.ready() before createPublish. Restoring waits up to 60 seconds for the SDK's database, polling every 2 seconds; SEED_PUBLISH_RESTORE_WAIT_MS and SEED_PUBLISH_RESTORE_POLL_MS change those times.

PublishManager.getPublish and query

getPublish(seedLocalId) returns the running publish for an item, or the last one that finished in this tab, as an XState actor. undefined when there's neither. query(seedLocalId) returns that actor's current snapshot, or undefined; it only reads. Prefer the hooks in React.

Wallets

A publish needs a PublishWallet: a signer (signs messages and data items), a txSender (submits transactions) and, optionally, a kind. The adapters build one and mark it as genuine, which createPublish checks. Wallets lists the adapters, which sender each config selects, and how to publish from a ManagedAccount without thirdweb.

type PublishWalletKind = 'eoa' | 'smart' | 'modular'

type PublishWallet = {
  signer: SeedSigner
  txSender: SeedTxSender
  kind?: PublishWalletKind // 'eoa': a plain key; 'smart': a smart account; 'modular': an EOA that publishes as a ManagedAccount; unset: unknown
}

kind matters on one route: a publisher with no contract code attests straight to EAS only from a kind: 'eoa' wallet (Attestation routing in Options). An unknown kind is refused there, not guessed. 'modular' is an admin EOA that publishes as its ManagedAccount: the in-app EOA that ConnectButton (with useModularExecutor) and ensureSmartWalletThenPublish register, or a signer paired with createManagedAccountTxSender. It signs data items like an EOA, and is refused for direct EAS like 'smart'.

setPublishWallet(session) registers the wallet that publishes and revokes by default. It also sets the SDK's owned addresses to the session's ownedAddresses, signer, sender and publisherAddress (watched addresses are kept), and claims unclaimed drafts for publisherAddress. getPublishWallet() returns it (or null). clearPublishWallet() forgets it and clears the SDK's owned addresses, keeping watched ones; it returns a Promise<void>. After that, new drafts are signed-out drafts that the next connected wallet claims, and drafts stamped with the old wallet are read-only until it reconnects. ConnectButton and useSeedWallet call both for you.

type PublishWalletSession = PublishWallet & {
  ownedAddresses?: string[]
  publisherAddress?: string // the attester; defaults to signer.address
  adminAddress?: string // the smart account's admin EOA, when there is one
  dataItemSigner?: SeedSigner // an EOA key that signs data items for a smart account
  deploy?: () => Promise<void> // deploys the publisher's smart account when it has no code
}

dataItemSigner is the session's data item signer: a publish as the session's publisherAddress uses it unless you pass one or the config sets one (see dataItemSigner). deploy is what a first publish from an undeployed kind: 'smart' account calls in checking. ConnectButton sets all three extra fields; see ConnectButton.

Other exports

These are documented in the guides or on other pages:

Related

• Publishing your first item and Publishing and revoking items
• Identity and signing: which account is the author
• Wallets, Components and hooks, Cost estimates and payment, Revocation, Tool attestations, Domain ownership
• Costs and who pays: who pays gas and storage in each wallet setup
• Gateway Hyper: reaching an upload API
• @seedprotocol/eas and @seedprotocol/arweave