Get started

The registry protocol

A useful record.An inspectable origin.

Describe what your software does, identify its publisher, and preserve the signature behind the record. MARS gives discovery something concrete to work with.

  • Canonical JSON
  • Ed25519 signatures
  • Versioned records
A closer lookAn entry, with its provenance attached.

Identity, content, and a publisher signature form a registry entry. The diagram illustrates the contract, not a live verification.

  1. 01Describe the entity
  2. 02Attach publisher identity
  3. 03Sign the canonical record

01 / record

The capability. In context.

The shared envelope keeps identity and provenance beside the payload. The payload schema describes the kind of software inside.

publisher-fields.json · illustrative excerpt
{
  "marsVersion": "1.0.0",
  "entryDid": "did:oas:example:agent:field-notes",
  "entryType": "AgentDefinition",
  "name": "Field Notes",
  "version": "1.2.0",
  "publisherDid": "did:oas:example:hmr:publisher",
  "publishedAt": "2026-09-01T12:00:00Z",
  "description": "An illustrative research capability.",
  "tags": ["research", "citations"],
  "itemSchemaUri": "https://example.org/schemas/agent.json",
  "itemData": {
    "license": "Apache-2.0",
    "capabilities": ["research", "summarize"]
  }
}

One envelope. Several layers.

Identity. The entry DID identifies the record. The publisher DID identifies the controller signing it.

Content. The schema URI, item data, and content hash describe exactly what was published.

Context. Optional service endpoints, relationships, lineage, and attestations give readers more to inspect.

The excerpt omits the content hash, signature, and registry fields. It is a reading aid, not a complete publish request.

02 / signing

Sign what you author.

The publisher signing profile preserves authorship while allowing the registry to manage its own lifecycle and sequence information.

MARS-PUBLISHER-SIGNING-V1 serializes the entry, removes only the explicit top-level fields shown here, and applies JCS canonicalization before Ed25519 signing.

All other fields remain signed. That includes publisherDid, itemData, itemDataHash, and any bondReference. The signature uses strict, unpadded base64url encoding.

Validation checks that the key controller matches the publisher DID and satisfies the registry’s trust policy.

registry-managed exclusions
signature
sequence
updatedAt
lifecycleStatus
verifiableAttestations
shardAssignment
anchorProjection
anchorState
anchorTxHash
anchorBlockHeight
anchorProof

03 / publication

From publisher to registry.

The current reference workflow validates a request and persists its accepted record in PostgreSQL. Every step has a specific responsibility.

  1. 01

    Prepare

    Construct a typed entry, hash its payload, and sign the publisher-authored fields.

  2. 02

    Authorize

    Use a valid session, publication capability, and route-scoped idempotency key.

  3. 03

    Validate

    Check the schema, DID, content hash, controller-bound signature, sequence, and required bond policy.

  4. 04

    Persist

    Store the accepted record and make its current state and version history available to readers.

External Sigil commitments follow a separate staged path: shadow, admitted private canary, then governed activation. A record marked active is not by itself proof of an authoritative on-chain anchor.

04 / read and follow

Resolve once. Stay informed.

Read the latest entry, pin a version, inspect stored lineage, or subscribe to catalog changes. The record stays useful after publication.

  • Resolve and version

    URL-encode the DID in an entry path. Fetch a known version or a bounded newest-first history page.

  • Follow the events

    WebSocket subscriptions select relevant types, namespaces, events, and DIDs from the catalog.

  • Exchange deliberately

    Configured peers exchange signed envelopes. Sync requests bind the sender, recipient, nonce, and typed payload.

Inspect every request and response in the API overview →