How to interact with the subdomain manager contract

The TON monorepo provides dns-manual-code.fc, a subdomain manager contract that stores DNS records for arbitrary subdomains. This page documents every message and get-method the contract exposes.

Private key backup: permanent loss risk

The subdomain manager is controlled exclusively by the Ed25519 private key corresponding to the stored public key. Losing this key makes it impossible to add, modify, or delete subdomain records, upgrade the contract, or change the owner key. Back up the private key before deploying on mainnet.

Bind the contract to a domain

After deploying the subdomain manager, bind it to a .ton domain by sending op::change_dns_record to the domain item contract:

• key: SHA-256("dns_next_resolver")
• value: cell containing dns_next_resolver#ba93 with the subdomain manager address

dns_next_resolver#ba93 resolver:MsgAddressInt = DNSRecord;

All queries for *.domain.ton are then delegated to the subdomain manager.

Resolution chain

When resolving sub.domain.ton:

1. Root DNS delegates to the .ton collection
2. Collection resolves domain to the item contract
3. Item contract returns dns_next_resolver pointing to the subdomain manager
4. Subdomain manager resolves sub and returns the DNS record

Contract storage layout

Field	Size	Description
contract_id	32 bits	Contract identifier
last_cleaned	64 bits	Timestamp for replay protection cleanup
public_key	256 bits	Owner Ed25519 public key for message authentication
root	dict	Prefix tree: domain name to category dictionary
old_queries	dict	64-bit query IDs for replay protection

Message format

All messages are external (signed by the owner private key).

Field	Size	Description
signature	512 bits	Ed25519 signature over the rest of the message
contract_id	32 bits	Must match stored contract_id
query_id	64 bits	Must be >= now() << 32. Old queries are cleaned up after 64 seconds. The lower 32 bits form a unique message ID within a second.
op	6 bits	Operation code (see table below)
payload	variable	Operation-specific data

Domain name encoding in messages

The name field in VSet, VDel, DSet, and DDel payloads uses an Either encoding:

• 1-bit flag: if 1, the name is stored in a cell reference; if 0, the name is inlined
• Inline format: 6-bit length (in bytes) followed by length × 8 bits of name data
• The name must be at least 2 bytes (16 bits), and the last byte must be 0x00 (null terminator)

Opcodes

Opcode	Hex	Name	Payload	Description
0	0x00	Noop	(none)	No operation (used as separator in chained operations)
1	0x01	SMsg	8-bit mode + cell ref (message)	Send a raw internal message from the contract
9	0x09	CodeUpgrade	cell ref (new code)	Replace the contract code
11	0x0B	VSet	uint256 category + domain name + maybe_ref value	Set a DNS record for a subdomain + category
12	0x0C	VDel	uint256 category + domain name	Delete a DNS record for a subdomain + category
21	0x15	DSet	domain name + maybe_ref (category dict)	Replace the entire category dictionary for a subdomain
22	0x16	DDel	domain name	Delete all records for a subdomain
31	0x1F	TSet	maybe_ref (new root dict)	Replace the entire domain table
32	0x20	TDel	(none)	Clear the entire domain table
51	0x33	OSet	uint256 (new public key)	Change the owner public key

Destructive operations

TSet (31) and TDel (32) rewrite or erase every subdomain record held by the contract.

• Risk: TSet replaces the entire domain table with a new root dict; TDel clears the table. Neither operation can be undone.
• Scope: every subdomain record stored in the manager contract.
• Mitigation: export the current root dict via a dnsresolve(_, 0) call before signing; retain the previous signed message as a replay option (only if the contract allows re-signing within the query_id window).
• Environment: test the full batch on TON Testnet before sending the same payload on mainnet.

Chaining multiple operations

The contract’s process_ops function iterates in a loop, allowing multiple operations in a single external message. After reading an op and its payload from the current slice, if remaining data or references exist, parsing continues. When the current slice is exhausted, the next cell reference is loaded and processing continues from there.

VSet, VDel, DSet, DDel, TSet, TDel, SMsg, CodeUpgrade, and Noop operations can all be batched into one signed message.

Caution

OSet (51) is handled before process_ops and is mutually exclusive with all other operations. If the message op is OSet, the public key is updated and no further ops are processed.

Set a subdomain record (VSet)

To point sub.domain.ton to a wallet address:

1. Encode the domain: sub becomes sub\0 in TON DNS internal format (null-terminated, reversed component order)
2. Compute the category key: SHA-256("wallet")
3. Build the value cell: dns_smc_address#9fd3 with the target wallet address
4. Send an external message with op 0x0B, the category, the encoded domain name, and the value as a maybe_ref

Delete a subdomain record (VDel)

Same as VSet but with op 0x0C and no value cell. Removes the record for the specified category + domain combination.

Domain name encoding

TON DNS uses a reversed, null-terminated encoding. Domain components are split by ., each component is null-terminated, and the order is reversed.

Domain	Encoded bytes
sub	sub\0
a.b	b\0a\0
x.y.z	z\0y\0x\0

The dnsresolve get-method expects this encoding in the subdomain slice.

Get-methods

Method	Signature	Returns
get_contract_id	() -> int	32-bit contract identifier
get_public_key	() -> int	256-bit owner public key
dnsresolve	(slice, int) -> (int, cell)	(bits_consumed, record_cell)

dnsresolve parses the subdomain slice, looks up the domain in the root dictionary, and returns either:

• The full category dictionary if category is 0
• A specific record if category matches a stored key
• A dns_next_resolver if the subdomain has remaining components to resolve

Related pages

• TON DNS: resolution architecture
• TON DNS reference: record type TL-B schemas, categories
• Domain item contract: register domains and set the dns_next_resolver binding