UQRP Protocol

Quick Reference: This is a condensed overview. For the complete technical specification including formal grammar (ABNF), encryption wire formats, and implementation requirements, see the Full Protocol Specification.

Try it now

Overview

ResolveDB encodes public service data and hosted-record reads in DNS queries and responses. Public answers can use shared DNS caching; authenticated private answers always use TTL 0.

Client                    DNS Resolver              ResolveDB
   |                           |                          |
   |-- get.quebec.weather.public.v1.resolvedb.net ------>|
   |                           |                          |
   |<-- TXT "v=rdb1;s=ok;d={"theme":"dark"}" ------------|
   |                           |                          |
   |-- (cached locally) ------>|                          |

Query Format

UQRP queries are structured DNS hostnames with each component serving a specific purpose:

<operation>.<params>.<resource>.<namespace>.<version>.resolvedb.<tld>

Examples

# Weather by city (public service)
dig TXT get.seattle.weather.public.v1.resolvedb.net +short

# Weather by coordinates (d = decimal point, _ separates lat/lon)
dig TXT get.47d6062_-122d3321.weather.public.v1.resolvedb.net +short

# Weather by IP location
dig TXT get.ip-8-8-8-8.weather.public.v1.resolvedb.net +short

# Weather by what3words (hyphens replace dots)
dig TXT get.w3w-filled-count-soap.weather.public.v1.resolvedb.net +short

# 3-day forecast
dig TXT get.seattle.forecast.public.v1.resolvedb.net +short

# GeoIP lookup
dig TXT geoip.ip-8-8-8-8.public.v1.resolvedb.net +short

# Stock quote
dig TXT get.AAPL.stock.public.v1.resolvedb.net +short

# Forex rate
dig TXT get.USD-EUR.forex.public.v1.resolvedb.net +short

# Crypto price
dig TXT get.BTC-USD.crypto.public.v1.resolvedb.net +short

# Authenticated hosted-record request
get.auth-rdbq<52>.config.acme-catalog.v1.resolvedb.net

Operations

Note: Write operations (put, delete) are handled via the REST API at api.resolvedb.com, not via DNS queries. DNS is optimized for reads; writes flow through the API.

Schema Discovery (info Operation)

Get JSON Schema for a registered public resource to understand its response format:

# Via DNS
dig TXT info.weather.public.v1.resolvedb.net +short

# Via HTTP (copy-paste any query - operation and params are ignored)
curl 'https://doh.resolvedb.io/schema?q=weather.public.v1.resolvedb.net'
curl 'https://doh.resolvedb.io/schema?q=get.seattle.weather.public.v1.resolvedb.net'

Response includes:

• schema: JSON Schema with field types, descriptions, and examples
• meta: Auth requirements, rate limits, default TTL
• dns_format: Query template and example response
• error_responses: Expected error codes and descriptions

See Schema Access in the full spec.

Parameter Encoding

Parameters requiring special characters are encoded using DNS-safe prefixes. All prefixes use hyphens (-) as separators since colons are not valid in DNS labels per RFC 1035.

Coordinate Encoding

For lat/lon coordinates, use d as decimal point and _ as separator:

# 47.6062, -122.3321 becomes:
dig TXT get.47d6062_-122d3321.weather.public.v1.resolvedb.net +short

Namespace Query Tokens

Private hosted records use an opaque token minted under the namespace API. The token is placed in the first label after the operation and is returned only once. Parameterized records place their key-parameter labels after it:

get.auth-rdbq<52>.config.acme-catalog.v1.resolvedb.net

Response Format

Successful data answers are DNS TXT records with a semicolon-delimited UQRP envelope, except that the units, sun, and moon services return direct flat key=value fields. Hosted records use this core shape:

v=rdb1;s=ok;t=data;e=<plain|b64>;f=<json|text>;ttl=<seconds>;d=<payload>

TXT RDATA can contain multiple 255-byte character strings. Concatenate them in order before parsing. Split the envelope at ;d= so payload characters are not mistaken for metadata. Decode d according to e before parsing f=json. The envelope ttl= field is a configured hint. Inspect the DNS answer RR TTL for the effective resolver cache lifetime; successful private RR TTL is always 0.

Query-level failures are primarily represented by DNS RCODE:

The larger status/error-envelope vocabulary in the full draft is not a promise that every listed status is emitted by the production v1 request paths. E014 is reserved and is not emitted.

Namespaces

ResolveDB places one namespace label in every UQRP name. public selects the public service surface; another non-reserved label identifies a hosted namespace.

Public Namespace

Globally accessible data through standardized interfaces:

get.london.weather.public.v1.resolvedb.net
get.AAPL.stock.public.v1.resolvedb.net

Hosted Namespace

Hosted namespaces are private by default. Use the opaque query token returned by the API over DoH or DoT so passive observers between the client and TLS endpoint cannot read the bearer credential:

get.auth-rdbq<52>.config.acme-catalog.v1.resolvedb.net

Namespace Rules

The dashboard and API enforce a server-maintained reserved-name denylist. Namespace UUIDs identify API resources only and are not DNS aliases.

TTL & Caching

Public service, dataset, and operator-managed public-read answers can be cached according to their DNS TTL. Successful authenticated private-record answers always use TTL 0, regardless of the record's configured ttl_seconds.

Write Operations

Write operations (put, delete) use the HTTP API, not DNS. See API Reference for details.

# Create a record after creating the `acme-catalog` namespace
curl -X POST https://api.resolvedb.com/api/v1/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"record": {"key": "config.acme-catalog.v1", "data": "eyJoZWxsbyI6IndvcmxkIn0="}}'

# Delete a record
curl -X DELETE https://api.resolvedb.com/api/v1/records/<record-uuid> \
  -H "Authorization: Bearer YOUR_API_KEY"

After the sync fleet applies the write, the record is available through the private-record gate using a namespace query token.

Record listing is provided by GET /api/v1/records; DNS list, search, and chunk retrieval are not implemented in UQRP v1. Hosted record payloads are limited to 2,586 decoded bytes by the API so the complete rendered UQRP value fits the core's 3,500-byte DNS envelope limit.

Security

ResolveDB implements multiple security layers:

Layer 1: DNSSEC

ECDSA P-256 and Ed25519 signing with automatically refreshed RRSIGs. Negative answers use DNSSEC-signed NSEC black lies.

Layer 2: Content Integrity

Dataset facts include a separate Ed25519 operator attestation in addition to DNSSEC answer authenticity and integrity.

Layer 3: Encryption

Applications can encrypt hosted values before storing them. ResolveDB does not manage customer plaintext encryption keys.

Layer 4: Query Privacy

DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) encrypt queries in transit:

See DNS Access Methods for details and code examples.

Authentication

Hosted-product query tokens are passed via the auth- prefix:

get.auth-rdbq<52>.resource.namespace.v1.resolvedb.net

Complete Specification

This quick reference covers the essentials. For comprehensive details, see:

• Full Protocol Specification - Draft specification with implemented and planned sections clearly marked
• DNS Access Methods - DoH JSON API, DoH wire format, and DoT configuration

Ready to build?

Create an account and start using the UQRP protocol.