> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/foundations/web3/ton-dns",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# TON DNS

> On-chain hierarchical domain name service for TON Network

TON DNS is a service for translating human-readable domain names (such as `example.ton` or `mysite.temp.ton`) into TON smart contract addresses, ADNL addresses used by services on the TON Network, and other network entities.

## What TON DNS resolves

TON DNS records can point to several types of addresses:

* **Wallet addresses**: on-chain smart contract addresses stored under the `wallet` category, allowing users to send cryptocurrency directly to a human-readable domain name instead of a raw address.
* **ADNL addresses**: used to locate TON Sites running on the TON Network.
* **TON Storage Bag IDs**: identifiers for files and data stored via TON Storage.
* **Next resolver references**: delegation of subdomains to another DNS smart contract.
* **Text records**: arbitrary UTF-8 text associated with a domain name.

## Implementation

TON DNS is built as a tree of DNS smart contracts. The root contract lives on the masterchain; its address is stored in blockchain configuration parameter #4. `.ton` is the only first-level domain. Each `.ton` domain is an NFT following the TEP-0081 standard: the resolver contract acts as an NFT collection and each registered domain is an NFT item, making domains transferable through any NFT-compatible wallet or marketplace.

The `.t.me` namespace operates as a delegated sub-resolver on the same infrastructure, implementing the same `dnsresolve` interface and supporting the same record types as `.ton` domains.

Every DNS smart contract exposes a `dnsresolve` get-method:

```func theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
(int, cell) dnsresolve(slice subdomain, int category)
```

`subdomain` is the portion of the domain name remaining to be resolved. `category` is the SHA-256 hash of the record category name, or `0` to retrieve all records. The method returns the number of bits consumed and a cell containing the DNS record. If fewer bits were consumed than the full subdomain length, the returned cell is a `dns_next_resolver` pointing to the contract that handles the remainder.

## DNS record types

DNS record values are described by TL-B schemas. The following record types are defined:

* `dns_adnl_address`: stores a 256-bit ADNL address for network services such as TON Sites. An optional protocol list describes supported protocols.

  ```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  dns_adnl_address#ad01 adnl_addr:bits256 flags:(## 8) { flags <= 1 }
    proto_list:flags . 0?ProtoList = DNSRecord;
  ```

* `dns_smc_address`: stores any smart contract address on the TON Blockchain, including wallets. An optional capability list describes the capabilities of the contract. Under the standard `wallet` category, this record enables sending funds to a domain name.

  ```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  dns_smc_address#9fd3 smc_addr:MsgAddressInt flags:(## 8) { flags <= 1 }
    cap_list:flags . 0?SmcCapList = DNSRecord;
  ```

* `dns_next_resolver`: delegates resolution of subdomains to another DNS smart contract at the specified address.

  ```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  dns_next_resolver#ba93 resolver:MsgAddressInt = DNSRecord;
  ```

* `dns_storage_address`: stores a 256-bit TON Storage Bag ID, allowing domain names to be assigned to files stored via TON Storage.

  ```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  dns_storage_address#7473 bag_id:bits256 = DNSRecord;
  ```

* `dns_text`: stores arbitrary UTF-8 text using the `Text` chunked encoding defined in the block layout specification.

  ```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  dns_text#1eda _:Text = DNSRecord;
  ```

### Record categories

When querying a DNS contract, the caller specifies a category to select which record type to retrieve. Categories are identified by the SHA-256 hash of a UTF-8 category name string. The standard categories defined by TEP-0081 are:

| Category name       | Purpose                                    |
| ------------------- | ------------------------------------------ |
| `wallet`            | Default wallet address (`dns_smc_address`) |
| `site`              | TON Site ADNL address (`dns_adnl_address`) |
| `dns_next_resolver` | Subdomain delegation (`dns_next_resolver`) |
| `storage`           | TON Storage Bag ID (`dns_storage_address`) |

Passing category `0` retrieves all records stored for the domain.

## Domain lifecycle

Registered domains must be renewed annually by sending 0.015 TON to the domain contract. There is no grace period: once a domain has gone more than one year without renewal, anyone can trigger its release by calling `dns_balance_release` on the contract with a minimum payment. The domain then re-enters auction for one week, with the caller as the initial bidder.

## Ecosystem integration

TON domain names such as `.ton` domains are recognized by wallet applications and explorers in the TON ecosystem. Users can send cryptocurrency to a TON DNS domain name instead of copying a 256-bit account identifier.

TON DNS also integrates with other TON services:

* [TON Sites](/foundations/web3/ton-sites): a `dns_adnl_address` record pointing to an ADNL address gives a site a human-readable `.ton` domain.
* [TON Storage](/foundations/web3/ton-storage): a `dns_storage_address` record maps a domain name to a Bag ID, making stored files addressable by name.
* [TON Proxy](/foundations/web3/ton-proxy): resolves `.ton` domains to ADNL addresses before routing HTTP traffic to the target site.