Aptos Names Service (ANS) — Complete Deep Dive

Aptos Names Service — V1 vs V2 Deep Dive

ANS is Aptos's domain name system — alice.apt instead of 0x1a2b3c.... It went through a complete architectural rewrite from V1 to V2 in October 2023. This page explains exactly what changed, why, and what it unlocks.

Why the Rewrite? The Token v1 Problem

ANS V1 was built on Aptos Token v1, the original NFT standard. Token v1 has a fundamental design problem: tokens don't have their own on-chain addresses. They exist inside a TokenStore resource on the owner's account, indexed by (creator, collection, name, property_version).

This means:

• No deterministic addresses — you can't predict where a name's data lives on-chain. To look up alice.apt, you need to know who owns it first, then look inside their TokenStore.
• No direct resource storage — you can't attach custom data (like resolution records) directly to the token. V1 used separate Table-based registries to store name records.
• Property version complexity — every mutation increments a property version, creating a new "instance" of the token. This made tracking ownership messy.
• No composability — other contracts can't easily reference or interact with a specific name token because it has no stable address.

The V2 Solution: Token Objects

Token Objects (the aptos_token_objects framework) solve all of these problems. Each token is an Object — a first-class on-chain entity with its own address. This is the key insight:

// V1: Name data lives in a separate Table, disconnected from the token
struct NameRegistryV1 {
    registry: Table<NameRecordKeyV1, NameRecordV1>
}

// V2: Name data lives ON the token object itself
// The NameRecord struct is stored at the token's address
struct NameRecord has key {
    domain_name: String,
    expiration_time_sec: u64,
    target_address: Option<address>,
    transfer_ref: Option<TransferRef>,
    registration_time_sec: u64,
    extend_ref: ExtendRef,
}

With Objects, each .apt name IS an on-chain object at a deterministic address. The name's resolution data, expiration, and ownership are all stored directly on that object.

What Token Objects Unlock

The ExtendRef — Why Renewal Works in V2

One of the most important Object capabilities is the ExtendRef. When an ANS name object is created, the contract saves an ExtendRef inside the NameRecord. This ref allows the contract to later modify the object's resources — specifically, to update expiration_time_sec.

// V2 renewal — modify the object in-place
public fun renew_domain(user: &signer, domain_name: String, renewal_duration_secs: u64) {
    let name_record = borrow_global_mut<NameRecord>(token_addr);
    name_record.expiration_time_sec = name_record.expiration_time_sec + renewal_duration_secs;
    // The ExtendRef proves the contract has authority to do this
}

In V1, this was impossible. To "renew" a name, you'd have to burn the old token and mint a new one — losing the property version history and breaking any references.

Subdomain Expiration Policies — A V2-Only Feature

V2 introduces the SubdomainExt struct with an subdomain_expiration_policy field:

• MANUAL_SET_EXPIRATION (0) — the subdomain has its own expiration, set by the domain owner. It can outlive or predate the parent domain.
• LOOKUP_DOMAIN_EXPIRATION (1) — the subdomain automatically expires when the parent domain expires. No manual management needed.

This is critical for organizations. A company owning company.apt can create team.company.apt with auto-follow policy, so when they renew the parent domain, all subdomains automatically stay valid.

The Router Architecture

Since V1 and V2 coexist on mainnet, the Router is the unified entry point. Currently in MODE_V1_AND_V2:

// Router logic (simplified)
public entry fun register_domain(user: &signer, domain_name: String, years: u64) {
    if (mode == MODE_V1_AND_V2) {
        // New registrations always go to V2
        v2_1_domains::register_domain(router_signer, user, domain_name, years * SECS_PER_YEAR);
    } else {
        domains::register_domain(user, domain_name, years);
    }
}

// Resolution checks V2 first, falls back to V1
public fun get_target_addr(domain: String, subdomain: Option<String>): Option<address> {
    let v2_result = v2_1_domains::get_target_address(domain, subdomain);
    if (option::is_some(&v2_result)) return v2_result;
    // Fall back to V1
    domains::get_name_address(subdomain, domain)
}

Migration: V1 → V2

Users migrate via router::migrate_name():

1. V1 token is transferred to the router's resource account (effectively burned)
2. A new V2 Token Object is created with the same name
3. Target address and primary name settings are copied over
4. Domains expired before March 7, 2024 get 1 free year of renewal
5. Domain must be migrated before its subdomains (parent-first)

Pricing: 75% Cheaper in V2

V2 also switched from exponential to linear multi-year pricing. In V1, year 2 cost 110% of year 1 (compounding). In V2, 2 years = 2x the annual price. Simple.

Integration Points

• TypeScript SDK (src/api/ans.ts): Full ANS class — getTargetAddress(), getPrimaryName(), registerName(), renewDomain(), plus batch queries for all names on an account
• Indexer (ans_processor.rs): Writes to 8 PostgreSQL tables tracking all v1+v2 lookups, registrations, and primary names in real-time
• On-chain resolution: Any Move contract calls router::get_target_addr(domain, subdomain) — one line to resolve a name
• Wallets: aptos-wallet-adapter displays primary names instead of raw addresses everywhere
• Web: aptosnames.com for registration and management

Who Built It

Current Status (April 2026)

• V2 on mainnet with router in MODE_V1_AND_V2
• 5 open issues, 2 open PRs (Move 2 syntax migration)
• Bug bounty active via HackenProof
• Last push: March 2026
• Stable, production infrastructure — not under heavy development anymore

Related Systems

Other Deep Dives

View this report interactively with Advanced / ELI5 tabs at https://aptos-intelligence.vercel.app/#ans-deep-dive. Plain-text version: /reports/ans-deep-dive.txt.