Atlas Registry

Registry is a data storage in the Atlas network. It stores signed envelopes, serves them to any authenticated client, and federates with other registries to form a distributed data layer. Each registry specializes by declaring which Schema.org types it accepts.

Registries are essentially a database with thin HTTP 2.0+ REST API layer supporting advanced filters over JSON data structures.

Role in the Network

Each registry publishes a DataCatalog envelope describing what types of data it stores, who operates it, and how to reach it. This self-description is the unit of discovery — guide registries index and verify content of these catalogs so clients can find the right registry reliably for the data they need.

Registry DataCatalog Envelope

{
  "@context": "https://schema.org",
  "@type": "DataCatalog",
  "additionalType": "atlas:registry",
  "name": "Social Media Registry",
  "url": "https://social.registry.example",
  "dataset": [
    { "@type": "Dataset", "name": "SocialMediaPosting" },
    { "@type": "Dataset", "name": "Comment" },
    { "@type": "Dataset", "name": "Person" },
    { "@type": "Dataset", "name": "LikeAction" },
    { "@type": "Dataset", "name": "FollowAction" }
  ],
  "publisher": [{
    "@type": "OrganizationRole",
    "name": "Operator Name"
  }]
}

Registry Roles

Registries serve different functions depending on their configuration. A single node can combine roles.

Role	Description
Standard Registry	Stores envelopes for its declared types, responds to queries, validates authorship and structure on ingestion.
Guide Registry	Maintains scored `DataCatalog` entries from other registries. Enables cross-registry search and discovery routing. Clients configure preferred guides in their Custodian preferences.
Shelter Registry	Acts as a persistent inbox and outbox for identities. Other registries crawl shelter envelopes for replication, ensuring data availability even when the user is offline.

Authentication

Every request to a registry carries three Atlas headers that prove identity and authorization. This is the same Atlas Sign transport contract used across the network.

Authenticated Request

GET /envelopes/type/SocialMediaPosting HTTP/2.0
atlas-identity:  <root-public-key>
atlas-signature: t=1712150400; s=<falcon-signature>
atlas-proofs:    [{ "data": { "@type": "Permit", ... }, "signature": "..." },
                  { "data": { "@type": "Intangible", "additionalType": "atlas:proofOfWork" }, ... }]

Header	Format	Purpose
`atlas-identity`	Base64 public key	Stable identity of the requester.
`atlas-signature`	`t=<timestamp>; s=<signature>`	Falcon signature over timestamp, method, and path — proves the request was issued by the identity.
`atlas-proofs`	JSON array	Portable proof bundle: delegated-key Permit, Proof of Work, and any additional attestations.

HTTP API

Registries expose a uniform HTTP/2 API for envelope CRUD, blob storage, and identity verification. All mutating endpoints require authentication. See Registry Client for the TypeScript wrapper.

Submit Envelopes

POST /envelopes HTTP/2.0
Content-Type: application/json
atlas-identity:  <root-public-key>
atlas-signature: t=1712150400; s=<falcon-signature>
atlas-proofs:    [...]

[
  {
    "signature": "<falcon-signature-base64>",
    "data": {
      "@context": "https://schema.org",
      "@type": "SocialMediaPosting",
      "text": "Hello from Atlas.",
      "datePublished": "2026-04-03T12:00:00.000Z"
    }
  }
]

// Response
{ "ok": true, "hashes": ["a1b2c3d4e5..."] }

Query Examples

// By Schema.org type
GET /envelopes/type/SocialMediaPosting?take=20&skip=0

// Full-text search with freshness window
GET /envelopes/search?type=Article&window=DAYS_7

// Filtered query with JSON where clause
GET /envelopes?where={"data.@type":"Person","data.name":"Alice"}&orderBy={"createdAt":"desc"}

// Envelope counts grouped by type
GET /envelopes/counts?groupBy=type

// Single envelope by hash
GET /envelopes/a1b2c3d4e5...

Method	Path	Purpose
GET	`/envelopes`	Query with where, orderBy, take, skip, select
GET	`/envelopes/type/:type`	Filter by Schema.org type
GET	`/envelopes/search`	Search by type and freshness window
GET	`/envelopes/counts`	Statistics with groupBy and distinct
GET	`/envelopes/:hash`	Single envelope by hash
POST	`/envelopes`	Submit a batch of signed envelopes
POST	`/blobs`	Upload binary via chunked Content-Range
GET	`/blobs/:cid`	Download blob by CID
POST	`/identity/challenge`	Liveness challenge-response

Blob Storage

Binary attachments — images, documents, media — are uploaded separately to /blobs in 5 MB chunks using Content-Range headers. The registry returns a CIDv1 content identifier, size, encoding format, and both HTTP and IPFS URLs. Envelopes reference blobs through contentUrl fields in their data payload.

Chunked Blob Upload

POST /blobs HTTP/2.0
Content-Type: application/octet-stream
Content-Range: bytes 0-5242879/10485760
atlas-identity:  <root-public-key>
atlas-signature: t=1712150400; s=<falcon-signature>
atlas-proofs:    [...]

<binary data>

// Response (final chunk)
{
  "cid": "bafkrei...",
  "size": 10485760,
  "encodingFormat": "image/jpeg",
  "url": "https://social.registry.example/blobs/bafkrei...",
  "ipfsUrl": "ipfs://bafkrei..."
}

Federation

Registries form a federated network by exchanging DataCatalog envelopes. On startup, a registry announces its catalog to configured guide registries and known peers. Guide registries score and index these catalogs so clients can discover registries by content type.

Peer availability is monitored through identity challenges — each registry periodically sends a random challenge string and verifies the signature to confirm the peer is live and owns its claimed identity.

Identity Challenge

POST /identity/challenge HTTP/2.0
Content-Type: application/json
atlas-identity:  <requester-public-key>
atlas-signature: t=1712150400; s=<falcon-signature>
atlas-proofs:    [...]

{ "challenge": "<random-string>" }

// Response — registry signs the challenge with its own key
{
  "publicKey": "<registry-public-key>",
  "signature": "<falcon-signature-over-challenge>"
}

Guide registries maintain quality scores for each peer, updated from ReviewAction envelopes.

Score	Measures
Quality	Overall data quality of hosted envelopes
Consistency	Hash and signature verification pass rate
Availability	Uptime from liveness challenge responses
Latency	Response time to queries and challenges
Completeness	Coverage of declared dataset scopes

FairShares

Registries participate in the FairShares economy. Every identity receives equal weekly FairShares. Querying a registry consumes query units purchased with FairShares, and publishing envelopes burns FairShares proportionally. The registry tracks balances via DigitalDocument envelopes with weekly rollovers.

Balance formula per week: next = floor(current × (1 − burnRate)) + weeklyIncome. This ensures balances converge to a fixed equilibrium — hoarding is unprofitable, and active participants naturally maintain access.

Data Fidelity

Registries track burn metrics from connected peers across seven freshness windows: 1 day, 7 days, 30 days, 180 days, 1 year, 5 years, and all time. Data fidelity scores measure total FairShares burned per identity, type, and time window — enabling guide registries to rank content by real usage signals rather than arbitrary metrics.

Bridges

Registries can ingest data from external protocols through configurable bridges. Ingested content is signed with the registry node's key, wrapped in Atlas envelopes, and enriched with keywords for search.

Bridge	Source	Mapped Types
ATProto (Bluesky)	Posts, profiles, follows	`SocialMediaPosting`, `Person`, `FollowAction`
Nostr	Events by kind	Schema.org types mapped per event kind
RSS	Feed items	`Article`
ActivityPub	Actors, activities	`Person`, various action types
DNS	Zone files	`WebSite` envelopes

ATProto Bridge Mapping

// Bluesky post (ATProto)
{
  "text": "Hello from Bluesky!",
  "createdAt": "2026-04-03T10:00:00.000Z",
  "$type": "app.bsky.feed.post"
}

// ↓ Mapped to Atlas Envelope
{
  "signature": "<node-signature>",
  "data": {
    "@context": "https://schema.org",
    "@type": "SocialMediaPosting",
    "text": "Hello from Bluesky!",
    "datePublished": "2026-04-03T10:00:00.000Z",
    "identifier": "at://did:plc:.../app.bsky.feed.post/...",
    "keywords": ["bluesky", "at-protocol-import"]
  }
}

Configuration

Registry behavior is declared in its DataCatalog envelope. An operator manages storage policies, bridge integrations, and dataset scopes through the configuration object.

Registry Configuration

{
  "storage": {
    "enabled": true,
    "guides": ["https://guide.registry.example"],
    "trustAnchorKeys": ["<public-key-base64>"],
    "identityPolicy": {
      "acceptMode": "any",
      "minIdentityAgeDays": 0
    },
    "ingestionLimits": {
      "maxItemsPerIdentityPerDay": 1000
    },
    "queryPolicy": {
      "maxResultsPerQuery": 100,
      "rateLimitPerIpPerMinute": 60,
      "initialFreeQueryUnits": 1000,
      "queryUnitsPerFairShare": 10
    },
    "rentingPolicy": {
      "enabled": false
    },
    "shelterPolicy": {
      "allowedRequesterPublicKeys": []
    }
  },
  "bridges": {
    "atproto": { "enabled": true, "actors": ["did:plc:..."], "pullProfiles": true },
    "nostr": { "enabled": false },
    "rss": { "enabled": true, "feeds": ["https://blog.example/rss"] },
    "activitypub": { "enabled": false }
  }
}

Config	Controls
`storage.guides`	Guide registries this registry announces to
`storage.trustAnchorKeys`	Public keys trusted for identity bootstrapping
`storage.identityPolicy`	Identity acceptance mode (`any`, `trusted`, `none`) and minimum age
`storage.ingestionLimits`	Max envelopes per identity per day
`storage.queryPolicy`	Rate limits, result caps, free query units, FairShares exchange rate
`storage.rentingPolicy`	Shelter lease pricing and peer limits
`storage.shelterPolicy`	Allowed requester keys for shelter access
`bridges`	Enable and configure external protocol bridges (ATProto, Nostr, RSS, ActivityPub)
`dataset`	Array of Schema.org type scopes the registry accepts