TZ2AT system design and FAQ.

TZ2AT turns Tezos chain activity, selected OBJKT marketplace context, and user-requested hydration into AT Protocol records. The system is built around one hard rule: live head indexing comes first, and every slower process must run beside it rather than in front of it.

Downstream products are appviews, feed generators, wallet experiences, analytics tools, and social graph services. They consume TZ2AT by reading category PDS repos, subscribing to a firehose, or asking the relay for targeted projections.

System Map

Design invariant: if a route can lag, it must lag independently. OBJKT, TzKT hydration, entity provisioning, S3 archive, and PDS publication can be behind without making the rolling indexer stop following head.

Event Grammar

TZ2AT treats chain and marketplace records as statements made from nouns, verbs, and parameters. The verb is the action: sale, offer, transfer, curation add, listing, bid, wallet claim, and related event types. The nouns are the identity-centered things involved: wallets, contracts, tokens, marketplaces, currencies, platforms, and chains. Parameters are the values that make the statement precise: price, amount, token ID, block level, operation hash, timestamp, source, and provenance.

This is the source of the noun repo convention. TZ2AT makes nouns durable by giving them categorized repos or stable repo-local records. It stores verbs as event records inside the repos they describe. That means repo placement is itself semantic context, not just an implementation detail.

A flat event stream can tell you that something happened. The PDS tree tells you which durable things the event belongs to, so an appview can reconstruct the map: wallet to token, token to contract, contract to marketplace, marketplace to currency, and all of it back to Tezos provenance.

Data Routes

PDS Tree

TZ2AT publishes records into repos organized by what the repo is about. Appviews should usually start from the repo for the noun they are displaying, then follow references and graph edges outward. The repo category is part of the semantic statement: wallet repos hold wallet-centered facts, contract repos hold contract and token facts, and marketplace repos hold market action context.

How To Build An Appview

Minimal repo read

const host = "https://contracts.tz2at.store";
const repo = "did:plc:example";
const collection = "store.tz2at.token.definition";

const url = host + "/xrpc/com.atproto.repo.listRecords"
  + "?repo=" + encodeURIComponent(repo)
  + "&collection=" + encodeURIComponent(collection)
  + "&limit=100";

const records = await fetch(url).then((r) => r.json());

Wallet hydration flow

await fetch("https://tz2at.xyz/hydrate/wallet/async", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    did: "did:plc:youruser",
    walletAddress: "tz1...",
    maxPages: 20
  })
});

Firehose Use

Use the JSON firehose for simple web consumers and the ATProto sync firehose when you want native repo operations.

const ws = new WebSocket("wss://tz2at.xyz/firehose");
ws.onmessage = (message) => {
  const envelope = JSON.parse(message.data);
  if (envelope.event?.$type === "store.tz2at.fa2.transfer") {
    // update your local token movement projection
  }
};

Common Records

Records include provenance fields so appviews can trace whether a fact came from Octez, TzKT hydration, OBJKT, the lifecycle historian, or a user identity proof route.

Retention And Reliability

TZ2AT has three practical storage temperatures:

• Hot: Postgres and live PDS repos for fresh query and firehose use.
• Warm: S3 block/event archives for replay after hot eviction.
• Cold: deeper archive for data that should be kept but rarely queried.

Permanent entity anchors, such as wallet genesis, wallet last-seen, contract genesis, contract last-seen, and OBJKT profile anchors, are designed to survive ordinary hot retention. High-volume event copies can be evicted from hot storage once they are archived and no longer needed for fresh appview queries.

FAQ

FAQ version: current live architecture as of 2026-05-28. See the builder manual for the full record catalog and API list, or the user guide for the wallet claim flow.