@seedprotocol/arweave

@seedprotocol/arweave is how Seed packages reach Arweave, where published files and long-form content live. It picks a gateway (an HTTP server that serves Arweave data), falls back to others when one is down, reads transaction data and tags, and checks whether an upload has landed. The SDK, @seedprotocol/query and @seedprotocol/feed use it, and the SDK re-exports most of it. Use it directly in a script or server that reads Arweave content without the SDK, or to inspect what the SDK resolved.

import { BaseArweaveClient, fetchArweaveRawTextAcrossGateways } from '@seedprotocol/arweave'
import { registerNodeArweavePlatform } from '@seedprotocol/arweave/node'

It doesn't upload: building, signing and sending uploads is @seedprotocol/publish's job. Permanence explains what's stored on Arweave and why.

Install

npm install @seedprotocol/arweave

It has no Seed dependencies and no peer dependencies. The SDK and @seedprotocol/query install it for you.

Entry points

There is no /react entry. DefaultArweaveClient works in browsers and Node; register it with BaseArweaveClient.configure(new DefaultArweaveClient()). The SDK registers it during client.init. It loads the arweave npm client only on first use, for the data fallback and createTransaction. The URL and gateway helpers that don't go through the registered client (getRawUrl, fetchArweaveRawTextAcrossGateways, resolveSeedGatewayEndpoints, …) work anywhere fetch does.

The default gateway and its fallbacks

Reads go to a primary gateway, arweave.net by default, and fall back through a list of public gateways:

const DEFAULT_ARWEAVE_HOST = 'arweave.net'
const DEFAULT_ARWEAVE_GATEWAYS = ['arweave.net', 'zigza.xyz', 'ar.seedprotocol.io']

A primary you set goes first, followed by each default not already in the list: with example.org as the primary, the order is example.org, arweave.net, zigza.xyz, ar.seedprotocol.io. Seed's own gateway is last; an app that wants it first sets arweaveDomain: 'ar.seedprotocol.io' (here through registerNodeArweavePlatform, or in the SDK's config, see Client and configuration). Under the SDK, arweaveDomain is also the host publish writes into Html links (Links in published content).

Environment variables

They're read from process.env only. In a browser build, VITE_ARWEAVE_HOST has no effect unless your bundler defines process.env. Under the SDK, client.init sets the host from arweaveDomain with setHost, so the host variables don't apply after init.

registerNodeArweavePlatform

Registers the Node client and sets the primary gateway.

function registerNodeArweavePlatform(options?: { arweaveDomain?: string }): void

Importing @seedprotocol/arweave/node registers the client as a side effect; calling the function also sets the primary. It doesn't lock the host, so the environment variables and the read probe can still change it. Call it before setHost, because it resets a host set earlier. Without a registered client, the transaction methods throw ArweaveClient not configured.

import { registerNodeArweavePlatform } from '@seedprotocol/arweave/node'
import { BaseArweaveClient, fetchArweaveRawTextAcrossGateways } from '@seedprotocol/arweave'

registerNodeArweavePlatform({ arweaveDomain: 'arweave.net' })

const txId = process.argv[2]!
const tags = await BaseArweaveClient.getTransactionTags(txId)
console.log(tags.find((t) => t.name === 'Content-Type')?.value)

const text = await fetchArweaveRawTextAcrossGateways(txId)
console.log(text?.slice(0, 200))

BaseArweaveClient

The process-wide gateway setting and the registered client, as static methods. ArweaveClient is the same class.

Gateway settings

Transaction methods

These go through the registered client.

getTransactionTagsByIds

The tags of many transactions, in batched GraphQL requests, keyed by transaction ID. The SDK uses it to check downloads against their Content-SHA-256 tag.

function getTransactionTagsByIds(
  transactionIds: readonly string[],
  options?: { client?: GraphQLClient; batchSize?: number; onError?: (error: unknown) => void },
): Promise<Map<string, TransactionTag[]>>

An ID the gateway doesn't know yet, such as a fresh upload that isn't indexed, is missing from the map. A failed batch is skipped, not thrown. The query is exported as GET_TRANSACTIONS_TAGS_BY_IDS.

One copy of the package

The registered client and the gateway settings live in module state, and assertSingleArweaveModule() throws DuplicateArweaveModuleError when the client was registered through another copy of this package; @seedprotocol/query calls it before every read. When two copies happen and how to fix it is in query's troubleshooting.

Gateway probing and fallback

A probe is GET {base}/info; a gateway is healthy when that returns a 2xx JSON object within 5 seconds, whether or not the caller passed a signal. A host that fails a probe is skipped for 60 seconds (a circuit breaker), then tried again. A probe the caller aborts resolves false and doesn't count as a failure.

ensureReadGatewaySelected

Probes the primary and then each fallback in order, and switches the gateway to the first healthy one.

function ensureReadGatewaySelected(signal?: AbortSignal): Promise<string>

It returns the selected host. The result is cached for 3 minutes (1 minute when nothing was healthy, in which case the last healthy host is kept). When signal aborts before a gateway passes, nothing is cached and it returns the last healthy host, else the current one. It does nothing while the host is locked with setHost.

fetchArweaveRawTextAcrossGateways

Reads a transaction's data as text, trying gateways until one returns a non-empty body.

function fetchArweaveRawTextAcrossGateways(
  transactionId: string,
  options?: { fallbackHosts?: readonly string[]; timeoutMs?: number },
): Promise<string | undefined>

It tries the preferred read gateways first, then runs ensureReadGatewaySelected (unless a sidecar or proxy is active) and tries the resolved and fallback gateways. Each body goes through the content read transform when one is registered; a gateway whose body can't be read, or whose transform throws, is skipped. The bytes are decoded as UTF-8, so a binary body comes back with U+FFFD in place of invalid sequences. It returns undefined when none had it. It never throws.

fetchArweaveRawBytesAcrossGateways

The same read as fetchArweaveRawTextAcrossGateways, with the same options, gateway order and errors, returning the body as bytes without decoding it.

function fetchArweaveRawBytesAcrossGateways(
  transactionId: string,
  options?: { fallbackHosts?: readonly string[]; timeoutMs?: number },
): Promise<Uint8Array | undefined>

The bytes are the transaction's data only while no content read transform is registered. With one registered it returns the transform's output, and there's no option to skip the transform, as getTransactionData's decode: false does. @seedprotocol/archive's exportArchive downloads Arweave content through it.

fetchTransactionStatusAcrossGateways

Checks whether a gateway has a transaction, trying gateways in order. BaseArweaveClient.getTransactionStatus calls it with the defaults.

function fetchTransactionStatusAcrossGateways(
  transactionId: string,
  options?: { timeoutMs?: number; totalTimeoutMs?: number; baseUrls?: readonly string[] },
): Promise<TransactionStatus>

Each attempt is GET {base}/{txId}, without downloading the body. Gateways whose circuit is open are skipped, unless every one is open, in which case all are tried. The first gateway to answer with a 2xx to 4xx status decides the result: any 2xx comes back as 200 (present), and a 404 is returned without asking the other gateways. A timeout, network error, 5xx or 429 counts as a failure against that gateway's circuit and moves on to the next. When no gateway answers, status is 504 if the last attempt timed out and otherwise that attempt's status (500 for a network error, or when there was nothing to try). confirmed is always null. It never throws.

Other read helpers

The circuit breaker is exported too (isGatewayHostCircuitOpen, getGatewayHostCircuitState, listOpenGatewayCircuitHosts, recordGatewayHostSuccess, recordGatewayHostFailure, beginGatewayHostHalfOpenProbe, cancelGatewayHostHalfOpenProbe (ends a half-open probe without a result, so the next caller can probe the host), normalizeGatewayHostKey, configureGatewayCircuitBreaker({ failureThreshold?, openDurationMs? })). The reset…ForTests functions are for tests only.

Experimental: content read transform

Groundwork for private publishing. A transform registered with setArweaveContentReadTransform sees content after it's fetched and before it's used, for example to decrypt it. Nothing in the Seed packages registers one, and the signature may change.

type ArweaveContent = { bytes: Uint8Array; contentType?: string }
type ArweaveContentReadContext = { transactionId: string }
type ArweaveContentReadTransform = (
  content: ArweaveContent,
  context: ArweaveContentReadContext,
) => ArweaveContent | Promise<ArweaveContent>

function setArweaveContentReadTransform(transform: ArweaveContentReadTransform | undefined): void
function hasArweaveContentReadTransform(): boolean
function transformArweaveContent(content: ArweaveContent, context: ArweaveContentReadContext): Promise<ArweaveContent>
function readArweaveContentResponse(response: Response, context: ArweaveContentReadContext): Promise<ArweaveContent>
function getResponseMediaType(response: Response): string | undefined

Reads that go through it: fetchArweaveRawTextAcrossGateways, fetchArweaveRawBytesAcrossGateways, BaseArweaveClient.getTransactionData (not with decode: false) and @seedprotocol/query's rich-text hydration (which then re-hosts the links in each body). Gateway URLs handed straight to the browser, such as SeedImage's progressive gatewayHref, media links and feed image URLs, don't, and neither does the SDK's browser download worker.

setPreferredArweaveReadBaseUrls

Gateways tried before all others for /raw reads, typically the one your app uploads through, which has a new upload before the public gateways do.

function setPreferredArweaveReadBaseUrls(urls: readonly string[]): void
function getPreferredArweaveReadBaseUrls(): string[]

Each entry is a base URL with scheme and any path, e.g. https://app.example.com/api/seed-gateway. A relative path such as /api/seed-gateway resolves against the page origin and is dropped where there is none (Node). Pass [] to clear. It doesn't change uploads, GraphQL or BaseArweaveClient's host. BaseArweaveClient.getTransactionData tries these gateways too. The SDK sets it from config.gateway.preferredReadBaseUrls.

Proxy and Hyper transports

Besides public HTTP gateways, an upload API and gateway can be reached over the Hyper network, either through a local sidecar (seed-gateway connect <operator key>, listening on http://127.0.0.1:1984) or through your app server (a proxy route built with createGatewayProxy from @seedprotocol/gateway-hyper). Gateway Hyper explains the setup.

resolveSeedGatewayEndpoints

Works out which gateway and upload API to use for a transport setting, probing the proxy or sidecar first.

function resolveSeedGatewayEndpoints(
  config: SeedGatewayConfig,
  options?: { signal?: AbortSignal; timeoutMs?: number; forceSidecarProbe?: boolean; origin?: string },
): Promise<ResolvedSeedGatewayEndpoints>

'hyper' probes the sidecar from wherever the code runs, so a web app on a public origin sends every visitor's browser a request to 127.0.0.1:1984, where most visitors run no sidecar. In a browser, 'hybrid' tries the sidecar only when the page's origin is loopback (localhost, 127.0.0.1, [::1] or *.localhost), or with hyper.probeSidecarFromBrowser: true, for a page that is meant to reach it, such as an Electron or desktop shell. hyper.probeSidecar: false skips the sidecar probe, and hyper.probeProxy turns the proxy's /info check on or off on its own (default: probeSidecar's value, else true); without that check, a set proxyBaseUrl is used even when it's down. A healthy probe result is cached for 3 minutes and a failed one for 60 seconds; forceSidecarProbe: true or invalidateSidecarProbeCache() clears them. timeoutMs is one budget for all of the resolve's probes (each probe still times out after 5 seconds on its own). A probe cut short by it or by signal counts as unreachable for that resolve only: it isn't cached or recorded in the circuit breaker. client.init passes no timeoutMs. A relative proxyBaseUrl needs options.origin outside a browser.

With a sidecar or proxy active, reads try it first and then the public gateway and the default list, so /raw reads and re-hosted links still work when it's down. Status checks ask only it and the preferred read gateways.

ResolvedSeedGatewayEndpoints:

setResolvedSeedGatewayEndpoints and getResolvedSeedGatewayEndpoints store the result for the read helpers; the SDK calls the setter during init. getReadGatewayHostsForConfig(resolved) gives the read host list for a result (with a sidecar or proxy active, its base URL followed by the public gateway and the defaults as https:// URLs), resolveProxyBaseUrl(url, { origin? }) turns a relative proxy URL into an absolute one, and resolveSidecarOrigin(config) gives the sidecar's address as { host, port, baseUrl } from hyper.localSidecarHost and localSidecarPort, else 127.0.0.1:1984 (host leaves out port 80 and 443; baseUrl always has the port).

SeedGatewayConfig

interface SeedGatewayConfig {
  transport?: 'http-gateway' | 'hyper' | 'hybrid'
  arweaveDomain?: string
  uploadApiBaseUrl?: string
  proxyBaseUrl?: string
  preferredReadBaseUrls?: string[]
  hyper?: {
    gatewayHyperKey?: string
    localSidecarHost?: string // default '127.0.0.1'
    localSidecarPort?: number // default 1984
    probeSidecar?: boolean // default true
    probeProxy?: boolean // default probeSidecar, else true
    probeSidecarFromBrowser?: boolean // default false
  }
  // Shorthands for the hyper fields: gatewayHyperKey, localSidecarHost, localSidecarPort, probeSidecar
}

seedGatewayConfigFromSeedConfig(seedConfig) builds one from an SDK-style config (top-level arweaveDomain and uploadApiBaseUrl win over the gateway ones; probeProxy and probeSidecarFromBrowser are read from gateway.hyper only), and seedGatewayConfigFromClientContext(context) from the SDK client's context. Note that resolveSeedGatewayEndpoints reads only the nested hyper object; the shorthands are merged into it by seedGatewayConfigFromSeedConfig. The SDK's gateway options are described in Client and configuration.

Upload status helpers

Read-only checks on an upload made through an upload API (uploadApiBaseUrl) or a gateway. There's no Arweave testnet, so uploads go to mainnet and cost real AR even when its attestations are on OP Sepolia.

Media references

Helpers for turning a stored value (an Arweave transaction ID, a Seed UID, a URL) into something you can display. The SDK re-exports them, with its own resolveMediaRef that also loads local files.

In a React app, useNormalizedFeedItemFields classifies a feed item's fields and the SeedMedia* components resolve and render raw media strings.

Links in Html

Links into Arweave inside an Html value name a gateway. Seed readers re-host them onto their own read gateways before showing the Html, and publish puts them back on the public gateway before upload; Links in published content says which reader does what. These are the helpers that do it. The SDK's main entry re-exports rehostArweaveLinksInHtml, nextArweaveGatewayUrl, mapUrlAttribute, parseArweaveTransactionLink and the types ArweaveTransactionLink and HtmlArweaveRefs.

An Arweave link is the URL in a src, href or poster attribute, or a candidate in a srcset, when it is one of:

• ar://<id>
• /raw/<id> on any host, after any path prefix, so an app proxy's URL counts
• /<id> on a known gateway: a host of a read base URL at a host's root, a host in KNOWN_ARWEAVE_GATEWAYS, a subdomain of either, *.arweave.net or *.ar-io.net
• {base}/<id> under a read base URL with a path prefix, such as https://app.example.com/api/seed-gateway/<id>. Such a base doesn't make /<id> on its host's root a link

<id> is a 43-character transaction ID, and whatever follows it (path, query, hash) is kept. A bare /<id> on any other host isn't treated as a link, because the path shape is common elsewhere. URLs in other attributes or in text are left alone.

type ArweaveTransactionLink = {
  transactionId: string
  form: 'raw' | 'bare' // `/raw/<id>` (and `ar://<id>`), or `/<id>`
  rest: string // path, query and hash after the ID, e.g. '/index.html' or '?v=2'
}
type ArweaveLinkOptions = { baseUrls?: readonly string[] }
type HtmlArweaveRefs = 'gateway' | 'ar'

import { publishedArweaveLinksInHtml, rehostArweaveLinksInHtml } from '@seedprotocol/arweave'

const id = 'Xb1kQ3t9mZp4Rr8sVw2yLc6nHf0jDg5aEu7iOq1xYzM'
const html = `<img src="ar://${id}"><a href="https://ar.seedprotocol.io/${id}">file</a>`

console.log(rehostArweaveLinksInHtml(html, { baseUrls: ['https://zigza.xyz'] }))
// <img src="https://zigza.xyz/raw/Xb1k…"><a href="https://zigza.xyz/Xb1k…">file</a>

console.log(publishedArweaveLinksInHtml(html, { to: 'ar', publicBaseUrl: 'https://arweave.net' }))
// <img src="ar://Xb1k…"><a href="ar://Xb1k…">file</a>

Constants

Types

Related

• Permanence: what's on Arweave and how gateways fit in
• Arweave and gateways: transports and fallbacks in depth, and how readers re-host Html links
• Gateway Hyper: the sidecar and proxy
• Client and configuration: the SDK's gateway settings
• @seedprotocol/eas: the attestation side
• Read published Seed data: reading content without the SDK