Atlas Guide

A Guide is a registry that acts as a directory service for the Atlas network. It indexes DataCatalog envelopes published by other registries, continuously monitors their availability, and maintains precomputed quality scores so clients can discover and route queries to the best data source for any given type.

In a network where registries specialize by content type, a client needs a way to answer: "who has the best SocialMediaPosting data right now?" A Guide answers that question through materialized views and guided search.

Materialized Views

A Guide maintains three precomputed, periodically refreshed views that capture registry quality, availability, and expertise. These views are stored alongside envelope data and automatically attached to API responses.

Identity

Each registry keeps its individual materialized view of information on identity. This is created automatically when it first receives an envelope from a new author. Key fields:

{
  "hash": "b3a1f8...",           // Blake3 hash of publicKey
  "publicKey": "<base64>",
  "verificationStatus": "VERIFIED",
  "fairShares": 420,
  "lastSeenAt": "2026-04-03T12:00:30.000Z",
  "queryUnits": 1000,
  "createdAt": "2026-03-01T08:00:00.000Z",
  "updatedAt": "2026-04-03T12:00:30.000Z"
}

FairShares

Each registry maintains its own local view of every identity's FairShares balance. There is no blockchain or global consensus — registries actively exchange TradeAction envelopes and each tries to match the highest totalBurn it observes from peers, which over time drives balances toward agreement across the network.

Payment Decisions

Because balances are subjective, each registry evaluates payments independently:

• Instant — Balance is sufficient and transaction volume is within normal range.
• Delayed — Balance is marginal or volume is unusually high. The registry introduces a random delay to guard against simultaneous double-spending across registries.
• Rejected — Balance is negative.

Weekly Reconciliation

During the weekly burn-and-income cycle, if an identity's balance has gone negative due to double-spending, verified registry operators are advised to automatically assign at least a −1 score on the integrity topic for the offending identity, provided the overspend is smaller than 10× the weekly income. When an identity's integrity score exceeds the negative standard threshold (square root of the second highest integrity scorer), the identity is banned from issuing TradeAction envelopes and all of its envelopes are excluded from burn calculations.

Natural Decay

Because trust scores are allocated with a one-year validity, negative integrity penalties decay naturally as the underlying trust envelopes expire. A one-time offender will eventually recover without any manual intervention. However, registries are free to reallocate scores at any time depending on the severity of the overspending — repeat or egregious abuse can be penalized more aggressively and renewed before expiry.

Data Fidelity

Measures how much the community has invested in a registry's data of a given type. For each connected registry, the Guide tracks total FairShares burned per Schema.org type across seven freshness windows. Higher totalBurn signals stronger community confidence in that registry's data.

{
  "type": "SocialMediaPosting",
  "additionalType": null,
  "window": "DAYS_7",
  "totalBurn": 3200,
  "identityHash": "b3a1f8..."
}

Data fidelity is recalculated every minute. The Guide fetches envelopes from each connected registry, filters for verified authors with positive FairShares, and sums the burn proofs (MoneyTransfer envelopes) linked to each content envelope.

Competence

Topic expertise scores per identity. Derived from trust reviews embedded in Person envelopes. Each competence pairs a topic string with a numeric score.

{
  "topic": "climate",
  "score": 12,
  "identityHash": "b3a1f8..."
}

PresentedEnvelope Composition

Every envelope returned by a registry API is a PresentedEnvelope — the raw signed envelope enriched with its author's materialized view data. The author field always includes competences. For DataCatalog envelopes (discovery responses), dataFidelity is additionally included.

// Every PresentedEnvelope includes an author object
// with materialized views attached:
{
  "signature": "...",
  "hash": "e4c9d2...",
  "data": { "@type": "SocialMediaPosting", "text": "..." },
  "authorHash": "b3a1f8...",
  "author": {
    "verificationStatus": "VERIFIED",
    "fairShares": 420,
    "competences": [
      { "topic": "climate", "score": 12, "identityHash": "b3a1f8..." },
      { "topic": "tech", "score": 5, "identityHash": "b3a1f8..." }
    ]
  }
}

// DataCatalog envelopes additionally include dataFidelity:
{
  "signature": "...",
  "hash": "a7f3b1...",
  "data": { "@type": "DataCatalog", "url": "https://social.registry.example", ... },
  "authorHash": "b3a1f8...",
  "author": {
    "verificationStatus": "VERIFIED",
    "fairShares": 420,
    "competences": [...],
    "dataFidelity": [
      { "type": "SocialMediaPosting", "window": "DAYS_7", "totalBurn": 3200, "identityHash": "b3a1f8..." },
      { "type": "Person", "window": "ALL_TIME", "totalBurn": 8100, "identityHash": "b3a1f8..." }
    ]
  }
}

This design means clients never need to query materialized views separately — quality signals travel alongside the data they describe.

Discovery

Discovery is a continuous background process with four stages:

1. Announce — Each registry publishes its DataCatalog envelope to configured guide URLs on startup and on configuration changes.
2. Monitor — The Guide polls every known registry with a cryptographic challenge-response every 30 seconds. A successful response updates lastSeenAt; a failure leaves the timestamp stale, eventually marking the registry as offline.
3. Refresh — Every minute the Guide recalculates DataFidelity scores by fetching envelopes from connected registries and summing eligible burn proofs.
4. Query — Clients query the Guide to discover available registries. The response is a list of DataCatalog envelopes with dataFidelity scores attached, enabling the client to choose the best source.

// Query a Guide for registries that serve SocialMediaPosting
GET /envelopes/search?type=SocialMediaPosting&window=DAYS_7

// Response — DataCatalog envelopes enriched with dataFidelity
[
  {
    "hash": "a7f3b1...",
    "data": {
      "@type": "DataCatalog",
      "url": "https://social.registry.example",
      "dataset": [
        { "@type": "Dataset", "name": "SocialMediaPosting" },
        { "@type": "Dataset", "name": "Person" }
      ],
      "publisher": [{ "@type": "OrganizationRole", "name": "SocialNode" }]
    },
    "author": {
      "verificationStatus": "VERIFIED",
      "fairShares": 420,
      "competences": [...],
      "dataFidelity": [
        { "type": "SocialMediaPosting", "window": "DAYS_7", "totalBurn": 3200 },
        { "type": "SocialMediaPosting", "window": "ALL_TIME", "totalBurn": 14800 },
        { "type": "Person", "window": "DAYS_7", "totalBurn": 1100 }
      ]
    }
  },
  {
    "hash": "c2d4e6...",
    "data": {
      "@type": "DataCatalog",
      "url": "https://news.registry.example",
      "dataset": [
        { "@type": "Dataset", "name": "SocialMediaPosting" },
        { "@type": "Dataset", "name": "Article" }
      ]
    },
    "author": {
      "dataFidelity": [
        { "type": "SocialMediaPosting", "window": "DAYS_7", "totalBurn": 900 }
      ]
    }
  }
]

Guided Search

guidedSearch is the primary client API for discovery-routed queries. It automates the full flow: query the Guide for registries serving a type, select the registry with the highest dataFidelity.totalBurn for the requested freshness window, then forward the query to that registry and return the results.

import { createRegistryClient } from '@app_/registry-client';

const client = createRegistryClient({
  publicKey: userPublicKey,
  delegatedPrivateKey: delegatedKey,
  proofs: [proofOfWork],
});

// guidedSearch queries the Guide, picks the best registry, and fetches data
const posts = await client.guidedSearch(
  'https://guide.example.com',     // Guide URL
  'SocialMediaPosting',           // Schema.org type
  {                                // Query forwarded to the winning registry
    where: { public: true },
    orderBy: { createdAt: 'desc' },
    take: 20,
  },
  'DAYS_7',                       // Freshness window (default: ALL_TIME)
);

// Fetch all currently-available registry catalogs from a Guide
const catalogs = await client.getConnectedCatalogs(
  'https://guide.example.com',
);
// Returns DataCatalog envelopes where author.lastSeenAt >= now - 60s

Protocol Methods

The registry client exposes several Guide-aware methods: