Skip to content
Directory

Quickstart: Run a Node

By the end of this guide, anyone on the internet will be able to resolve addresses at your domain and get back signed routing contracts.

The 10-second protocol

A conforming DRS node is:

  1. Two DNS records. _drs._tcp.<domain> SRV points to your node; _drskey.<domain> TXT publishes your Ed25519 public key.
  2. One HTTP endpoint. POST /resolve returns { address, routes, issued_at, expires_at, signature }, canonicalized with JCS and Ed25519-signed.
  3. That’s it.

You can paste that into an LLM and have a working node in a few minutes. The reference implementation below does it on Cloudflare Workers.

Two paths

The reference implementation runs on Cloudflare Workers with automated DNS setup. If your domain’s DNS is on Cloudflare, follow the steps below — the CLI handles everything.

If your DNS is on another provider (Route 53, GoDaddy, Namecheap, etc.), you create two DNS records manually and can host the DRS anywhere. See DNS Records — Creating Records by Provider.

What you need (Cloudflare path)

  • A domain with DNS on Cloudflare.
  • A Cloudflare API token with Zone:DNS:Edit, Account:Workers Scripts:Edit, Account:Workers KV Storage:Edit.
  • Node.js 20+ and pnpm.

1. Clone and install

Terminal window
git clone https://github.com/drs-xyz/drs.git
cd drs
pnpm install

2. Initialize your node

Terminal window
drs init --domain yourcompany.com --cf-token <your-cloudflare-token>

This single command:

  • Generates an Ed25519 keypair (your signing key).
  • Creates two KV namespaces (addresses and config).
  • Creates DNS records: _drs._tcp.yourcompany.com SRV and _drskey.yourcompany.com TXT.
  • Enables DNSSEC on the zone (protects DNS records from cache poisoning).
  • Writes initial config to KV.

Save the output — you’ll need the private key and KV namespace IDs.

3. Store the signing key

Terminal window
cd packages/drs-worker
wrangler secret put DRS_SIGNING_KEY --env yourcompany
# Paste the base64 private key when prompted.

4. Configure wrangler.toml

Add your domain as an environment in packages/drs-worker/wrangler.toml:

[env.yourcompany]
vars = { DOMAIN = "yourcompany.com" }
routes = [{ pattern = "yourcompany.com/*", zone_name = "yourcompany.com" }]


[[env.yourcompany.kv_namespaces]]
binding = "ADDRESSES"
id = "<addresses-kv-id-from-step-2>"


[[env.yourcompany.kv_namespaces]]
binding = "CONFIG"
id = "<config-kv-id-from-step-2>"

5. Declare what you accept (optional)

Terminal window
drs update-config \
  --accepts '[{"value_type":"USDC","transfer_type":"ethereum"},{"value_type":"ETH","transfer_type":"ethereum"}]' \
  --cf-token <token> --account-id <id> --kv-namespace <config-kv-id>

This populates the optional capability manifest served at /.well-known/directory.json. Clients MUST NOT require it, but publishing a manifest helps senders decide whether to attempt a resolution.

6. Add your first address

Terminal window
drs add-address alice --routes '[
  {"value_type":"USDC","transfer_type":"ethereum","destination":"0xABC..."},
  {"value_type":"ETH","transfer_type":"ethereum","destination":"0xABC..."}
]' --cf-token <token> --account-id <id> --kv-namespace <addresses-kv-id>

7. Deploy

Terminal window
cd packages/drs-worker
wrangler deploy --env yourcompany

8. Test it

Terminal window
drs check-dns yourcompany.com


# Resolve alice — get a real signed routing contract.
curl -s -X POST https://yourcompany.com/resolve \
  -H 'Content-Type: application/json' \
  -d '{"address":"alice@yourcompany.com"}' | jq


# Full end-to-end: resolve + verify signature against DNS keys.
drs test-resolve alice@yourcompany.com

That’s it. alice@yourcompany.com is now a live Directory address. Anyone with the SDK can resolve it, verify the signature, and know exactly where to send value.

Try it locally first

Terminal window
pnpm dev
# Starts a local DRS node at http://localhost:8787
# Pre-seeded with test addresses, real Ed25519 signing.
Terminal window
curl -s -X POST http://localhost:8787/resolve \
  -H 'Content-Type: application/json' \
  -d '{"address":"alice@localhost.directory.dev"}' | jq

Non-Cloudflare path

1. Generate your keypair

Terminal window
pnpm tsx scripts/gen-keypair.ts

2. Create DNS records

Add two records in your DNS provider’s dashboard:

TypeNameValue
SRV_drs._tcp10 5 443 yourcompany.com
TXT_drskeyv=drs1; k=ed25519; p=YOUR_BASE64_PUBLIC_KEY

Enable DNSSEC on your DNS provider if available.

3. Run the DRS

The DRS is a stateless HTTPS API. The reference implementation uses Hono and can run on any Node.js host. For production, wrap it in any HTTPS server behind nginx/caddy, Docker, or a PaaS. The only requirement is HTTPS on the domain your SRV record points to.

The storage layer is a simple KVStore interface — just get and put. Implement it against Redis, Postgres, SQLite, or anything else. A MemoryKV adapter ships with the project for local dev.

4. Verify

Terminal window
dig _drs._tcp.yourcompany.com SRV
dig _drskey.yourcompany.com TXT
drs check-dns yourcompany.com

What’s next

  • Add more addresses: drs add-address
  • Manage addresses as YAML files: drs sync --dir ./addresses
  • Rotate keys (multiple _drskey records are supported): drs rotate-key
  • See all commands: CLI Reference
  • Understand the protocol: How It Works