# Divi Name Service (DVNS)

> A name points to a Divi address, so people send Divi to `bert`, `knight@siegeworlds` or `@handle` instead of a 34-character address. Records live on the Divi chain; https://name.divi.cx indexes them and builds the payment that writes them. Names are no safer than addresses: a mistyped name is a different name. Always show the user the name AND the address it resolves to before sending.

- API base: https://name.divi.cx/api/v1/ — every call takes `network=mainnet|testnet` (query, or `network` in a POST body); mainnet is the default.
- OpenAPI 3.1: https://name.divi.cx/openapi.json
- Developer guide: https://name.divi.cx/docs/
- Games, sidechains and gamer tags: https://name.divi.cx/docs/gamer-tags.html
- Errors are `{"error": "..."}` with a 4xx/5xx status. CORS is open. No API key.

## Names

- A label is 1–32 of `a-z 0-9 - _`, not starting or ending with `-` or `_`. Input is lower-cased.
- Top-level names (`bert`, `siegeworlds`) need at least 3 characters. Every top-level name is also a namespace.
- Tags live in a namespace: `knight@siegeworlds`. `@handle` is shorthand for `handle@telegram`.
- Reserved, never registrable: divi, telegram, name, names, admin, support, official, wallet, irondivi (`telegram` is held by the service for Telegram usernames).
- Names never expire.

## Fees (DIVI, paid to the registry address in the same transaction)

| registration | fee |
|---|---|
| 3-letter name | 10000 |
| 4-letter name | 5000 |
| 5-letter name | 1000 |
| 6+ letters | 500 |
| tag (name@ns) | 10 |
| update / delete | 10 |

Read live values from `GET /api/v1/info` (`fees_divi`) or price one name with `GET /api/v1/fee?name=…&op=register`.

## Send Divi to a name (any wallet)

1. `GET /api/v1/resolve/{name}` → `{name, divi, owner, fields, …}`. 404 means not registered (a `pending` list may show it is waiting to confirm; pending names do not resolve).
2. Show "Send to {name} ({divi})" and get confirmation.
3. Send to `divi` as a normal payment. Never cache a resolution across sessions without re-resolving: owners can repoint names.

## Register / update / delete (any wallet)

1. `POST /api/v1/build` with JSON `{network, op: "register"|"update"|"delete", name, payer, divi, owner?, auth?, fields?}`.
   - `payer` pays and must sign input 0. For update/delete it must own the name (or own / be signer of the tag's namespace).
   - `divi` is where the name sends Divi (required on register). `owner` defaults to `payer`.
   - `fields` is a string map: `kind` (person, org, game, sidechain, gamertag, telegram, …), `site` (https URL), `signer`, `policy` (open|closed), `chain.<id>` (the name's identity/address on another chain or game, ≤128 chars), any other key.
   - Update REPLACES the whole record: resend `divi`, `owner` and every field to keep.
   - 409 = would be rejected (taken, not owner, missing auth); nothing is spent. For a tag the body carries `auth_message`.
2. The answer has `send: {to, amount, memo, from}`: pay `amount` DIVI to `to` (the registry), attach `memo` as the OP_RETURN data, spend only coins of `from`. Raw-transaction builders use `outputs` (OP_RETURN script + fee output) and add inputs (input 0 from payer), change and network fee. The record must be ≤599 bytes.
3. Broadcast, then `POST /api/v1/notify {network, txid}` so the name shows as pending with any problem it will hit.
4. It applies once confirmed (records apply by height, then txid; the indexer re-checks the last 10 blocks). Poll `GET /api/v1/resolve/{name}`.

## Tags and namespaces (games, sidechains, communities)

A tag `x@ns` is allowed when ANY of:
- the payer owns `ns` or is its `signer`;
- `ns` has `policy=open` (anyone may register an unused tag);
- the request carries `auth`: a Divi `signmessage` signature (base64) by the namespace's owner or signer over exactly
  `DVNS1 auth <name> <owner> <divi>` (e.g. `DVNS1 auth knight@siegeworlds y2wg… y2wg…`).

So a game registers its title once (`kind=game`, `signer=<its server's Divi address>`), and its server signs `auth` for each player who proves they own an in-game account. The player pays 10 DIVI and owns the tag. `dvns sign-auth --wif-file KEY --name knight@siegeworlds --owner ADDR --divi ADDR` produces the signature; any Divi signmessage works.

Telegram: a Mini App posts `Telegram.WebApp.initData` to `POST /api/v1/auth/telegram {network, init_data, payer, divi, owner?}`; the service verifies it, reads the @username and returns `{name: "<username>@telegram", auth, …}` to pass to /build.

## Find names

- `GET /api/v1/names?ns=siegeworlds` — every tag in a namespace.
- `GET /api/v1/names?address=ADDR` — every name pointing at or owned by an address (one player's names across games).
- `GET /api/v1/names?kind=game&top=true`, `q=substring`, `limit` (≤1000), `offset`.
- `GET /api/v1/names/{name}/history`, `GET /api/v1/history`, `GET /api/v1/pending`.

## Record format (for indexers)

OP_RETURN text, first line `DVNS1`, then one `key=value` per line: `op`, `name`, `divi`, `owner`, then fields. The same transaction pays the fee to the registry address (`GET /api/v1/info` → `registry`). Full protocol: SPEC.md in the divi-name-service repository.