sirius/docs/DESIGN-signed-records-manifest.md

Signed records manifest (BNS records v1)

Status: shipped v1 — gateway GET/POST /api/records/<name> and verified GET /api/dns/<name> live on silentmode.st/navigate.st; owner-tracking in the indexer live; portal DNS editor + wallet-side signMessage + signRecordsManifest shipped. Native DNS server (UDP :53 → BCDN name → verified records) is a v2 follow-up. Related: DESIGN-tld-registry.md, PROTOCOL.md, public explainer at silentmode.st/sirius-x/docs/#signed-records. Mirrored to site-sirius-x/docs/DESIGN-signed-records-manifest.md so it rides the next push-split to the sirius forge.

Problem

Every records edit today is a chain UPD:

• costs ~1,300 sat + service fee
• caps records at ~150 bytes of payload
• rules out DNS-style records (A/AAAA/MX/TXT/CNAME/NS) at any useful scale
• makes TXT-verification churn (ACME, DKIM, DMARC) actively expensive

We want records to be:

• free to edit — no chain tx per change
• unlimited size — accommodate whole DNS record sets
• trustless — no operator can substitute their own records for the owner's
• backwards compatible — existing on-chain h / s3 / p / u records keep working

Design

The chain says who owns the name. A signed manifest says what the owner's records are. Resolvers verify both.

The manifest — _records.json

Lives at the Sia bucket the name's on-chain records.s3 already points at, under the fixed filename _records.json. Shape:

{
  "v": 1,
  "name": "bitcoin.cash",
  "seq": 42,
  "updated_at": "2026-09-12T00:00:00Z",
  "dns": {
    "A":     ["1.2.3.4"],
    "AAAA":  ["2001:db8::1"],
    "MX":    [{"pref": 10, "host": "mail.example.com"}],
    "TXT":   ["v=spf1 include:_spf.silentmode.st -all"],
    "CNAME": null,
    "NS":    []
  },
  "meta":  { "note": "optional free-form" },
  "sig":   "H3n… (BCH message signature, base64)"
}

Rules:

• v: schema version, currently 1.
• name: the fully-qualified name the manifest belongs to. Resolver rejects a manifest whose name field doesn't match the URL it was fetched from.
• seq: monotonic integer. Resolvers cache the highest seen; blobs with an older or equal seq are rejected as replays.
• updated_at: ISO-8601 UTC. Human-readable only — verification is on seq.
• dns.*: DNS record slots. null or [] means "not set". A/AAAA/TXT are string arrays. MX is objects {pref, host}. NS is a string array of host names. Additional slots (CAA, SRV) reserved for v2.
• meta: unstructured; ignored by DNS resolvers, useful for portal UI.
• sig: BCH-style message signature (same format libauth.signMessage produces) over the canonical bytes of the envelope (see below).

Canonicalisation and signing

The signable bytes are the JSON serialisation of the manifest without the sig field, with:

• keys sorted lexicographically at every level
• no insignificant whitespace (JSON.stringify with no space arg)
• \u-escape every non-ASCII character
• null fields OMITTED ("CNAME": null becomes absent)

The signature is sign(sha256(canonical_bytes)) with the wallet key whose address currently holds the name's NFT certificate.

Verification, at the resolver:

1. Read the name's chain record. Follow records.s3 to the Sia bucket.
2. Fetch _records.json from that bucket.
3. Extract sig, recompute sha256(canonical_bytes) over the rest.
4. Recover the signing pubkey → derive the CashAddress → compare to the current NFT owner address from the chain.
5. Compare seq to the cached last-seen seq for this name. Reject if not strictly greater.
6. If everything matches: cache the new seq, apply the DNS records.

Any step failing means "no records" — the resolver falls back to whatever was already on the chain (h, s3 for content, etc.).

Endpoints (gateway)

GET /api/records/<name> — read-through of the signed manifest. Returns 200 with the JSON if present, 404 if missing, 5xx on Sia errors. Cacheable for a minute. Anyone can call this; it's public.

POST /api/records/<name> — write. Body IS the manifest JSON. The gateway:

1. Verifies the signature matches the current on-chain NFT owner.
2. Verifies seq is strictly greater than the last-seen seq (from GETing the current manifest if any).
3. Uploads the JSON to the name's Sia bucket at _records.json.
4. Returns 200 with {seq, bytes, sia_key}.

Rate-limit: 1 write / 5 s per name. Refuses if the on-chain record has no s3 pointer yet — the name has no storage location, no place to write.

Precedence and interaction with existing records

The signed manifest complements the on-chain records — it doesn't replace them:

• Content (h, s3, p, u, ip) still comes from chain.
• DNS records come from the manifest — chain has never carried them.

A future extension (v2) could allow the manifest to override h/s3/etc. for owners who want everything off-chain. Not shipped in v1 because the existing content model already works.

Threat model

• Operator tampers with the manifest. Signature verification catches it — the resolver rejects and falls back to on-chain records.
• Replay of an old manifest. seq monotonicity catches it — resolvers keep the highest-seen seq.
• Owner's key compromised. Same as chain-side compromise: attacker controls the NFT and can sign whatever. Move the name to a new key.
• Sia object deleted. The name still resolves via chain records; DNS records disappear until the manifest is republished.
• Gateway hostility. The gateway signs nothing itself — it only relays and enforces seq monotonicity. A hostile gateway can refuse to accept writes but cannot forge them; users can bypass it entirely by writing directly to Sia with their own credentials (v2 flow).

What ships in v1

• The spec (this doc).
• Gateway /api/records/<name> (GET + POST) with signature verification and Sia read-through.
• Portal DNS editor that composes a manifest, asks the wallet to sign, and POSTs to the gateway.
• Resolver support in Theseus + Ariadne staged behind a flag until the portal-side has been in production for a week.

What ships in v2

• Direct-to-Sia write flow for users who hold their own S3 credentials.
• Owner-controlled manifest that overrides h/s3/etc. entirely.
• CAA/SRV/HTTPS records.
• Federated resolver caches for seq (mitigates the case where two writes race and each thinks its seq is winning).