Native Usernames

What a name is

A native username such as @alice is a short, readable pointer to an Asentum address. Instead of pasting ase15xs6rgdp5x... you send to @alice. Names live in a system contract that is part of the chain itself, so every wallet, app, explorer and bot can read them from any node without a third-party service.

• The address stays the account. Your balance, stake and history belong to your address. The name only points at it. Selling or transferring a name never moves funds.
• Resolved at signing time. Wallets look the name up when you build the transaction, not earlier, so the transaction goes to whoever owns the name at that moment.
• Both are shown. Confirm screens show the name and the address it resolves to (for example @alice with ase15xs6...yggla5), so you can always check where the ASE goes.
• Display is @name. There is no suffix such as .ase.

Activation

Names went live with release 0.9.0 at block 1,200,000 on the testnet (chain 1423), on 7 November 2026. At the start of that block the registry was installed at the system address ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqty736ey together with the reserved list, and registrations opened in the same block.

• A node older than 0.9.0 has no name lookups (it answers 404). Apps should treat that as names being off and keep showing plain addresses.
• Names have no expiry on the testnet.
• Testnet names do not carry over to mainnet. Mainnet starts with an empty registry.

Naming rules

• 3 to 24 characters.
• Only lowercase letters a-z, digits 0-9 and the hyphen -. ASCII only: lookalike letters from other alphabets are refused.
• No hyphen at the start or the end, and no double hyphen (my--name).
• A name cannot start with 0x or ase1, so it can never be mistaken for an address.
• Case does not matter: @Alice, ALICE and alice are the same name. A single leading @ is accepted and ignored.
• Each address can register at most 5 names per 43,200 blocks (one day at the 2 second target block time).

Fees

Shorter names cost more. The fee is paid once, at registration.

• Send exactly the fee as the value of the register call. Any other amount reverts and nothing is charged beyond gas.
• Half of every fee is burned (sent to ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqph4djanawk, which nobody holds a key for). The other half goes to the treasury, ase13qvpuh46hzcchnq0pjy037f8rv4utlq62l6zpj.
• Transfers, primary changes and records cost only gas.

Primary names

An address can own several names but has one primary name. The primary name is what apps show next to your address (the explorer, the airdrop leaderboard, Social and Communities).

• Your first name becomes your primary name automatically.
• Call setPrimary(name) to switch to another name you own, or clearPrimary() to show no name.
• Transferring a name away clears it as your primary name. The new owner does not get it as their primary name until they set it.

Records

The owner can attach a few text records to a name. Records are printable ASCII. Setting a record to an empty value deletes it. When a name is transferred its records are cleared, so the new owner starts clean.

Records are text written by the name owner. Apps should show them as plain text, never as HTML, and treat links as untrusted.

Reserved names

Some names are reserved from the start to protect users from impersonation: network names, roles such as admin and support, and partner projects. A reserved name cannot be registered. Only the registrar address can release one (to its rightful owner, free of charge) or change the list. This is the registry's only admin power: it cannot take, move or edit a name somebody owns.

The registrar can add more reserved names later. Use isReserved(name) or isAvailable(name) to check the current state.

How to register

With the explorer

1. Open explorer.asentum.com/names.
2. Search for a name. The page shows whether it is free, why not if it is taken, reserved or invalid, and the exact fee.
3. Connect the Asentum Chrome extension or the Telegram wallet and confirm the registration. Check that the amount matches the fee.
4. Once the transaction is in a block the name is yours. Your first name is your primary name; with more than one you can choose which one is primary on the same page.

From code

Registering is an ordinary contract call to ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqty736ey: method register, the name as the only argument, the fee as the value, and a gas limit of about 300,000.

import { NAME_REGISTRY_CONTRACT, nameFeeWei, normalizeName } from '@asentum/sdk';

const name = normalizeName('@MyName');           // "myname", or null if invalid
const tx = await wallet.sendCall({
  to: NAME_REGISTRY_CONTRACT,                    // ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqty736ey
  method: 'register',
  args: [name],
  valueWei: nameFeeWei(name),                    // exactly the fee, or it reverts
  gasLimit: 300_000n,
});
await tx.wait();

// Optional: pick which of your names is the primary one.
await wallet.sendCall({ to: NAME_REGISTRY_CONTRACT, method: 'setPrimary', args: [name], gasLimit: 300_000n });

With @asentum/sdk 0.3.1 the same is one line: await (await wallet.registerName(name)).wait(). The same with @asentum/connect in a dapp:

import { useContract } from '@asentum/connect';

const REGISTRY = 'ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqty736ey';
const registry = useContract(REGISTRY);

// Check first (free view call), then register with value = the fee in wei.
const info = await registry.view('isAvailable', ['myname']);
if (info.available) {
  const txHash = await registry.call('register', ['myname'], info.fee);
}

Node API

Every node from release 0.9.0 answers two lookups. Each runs one view call and counts toward the caller's view-call rate limit.

GET https://testnet.asentum.com/name/alice

{
  "active": true,
  "name": "alice",
  "address": "0xa1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
  "ase1": "ase15xs6rgdp5xs6rgdp5xs6rgdp5xs6rgdpyggla5",
  "blockNumber": "1200345"
}

GET https://testnet.asentum.com/name-of/ase15xs6rgdp5xs6rgdp5xs6rgdp5xs6rgdpyggla5

{
  "active": true,
  "address": "0xa1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
  "ase1": "ase15xs6rgdp5xs6rgdp5xs6rgdp5xs6rgdpyggla5",
  "name": "alice",
  "blockNumber": "1200345"
}

• Add ?blockTag=finalized to read finalized state instead of the tip.
• Before activation the answer is { "active": false, "error": "names not active", "activatesAt": "1200000" }.
• Input that breaks the naming rules returns error: "invalid name" (or "invalid address").
• Nodes older than 0.9.0 answer 404. Treat that the same as not active and fall back to showing the address.

JSON-RPC

The same lookups are available as JSON-RPC methods on the node's POST / endpoint. The first parameter is the name or address; an optional second parameter "finalized" reads finalized state.

curl -s https://testnet.asentum.com -H 'content-type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1,
  "method": "ase_resolveName",
  "params": ["@alice"]
}'

// result: the same body as GET /name/:name

{ "jsonrpc": "2.0", "id": 1, "method": "ase_lookupAddress",
  "params": ["ase15xs6rgdp5xs6rgdp5xs6rgdp5xs6rgdpyggla5", "finalized"] }

On a node without names the methods fail with JSON-RPC error -32601 (method not found).

SDK

@asentum/sdk 0.3.0 added the name lookups (they go through the node API above), and 0.3.1 added a wallet method for every write. The developer guide has worked examples.

import { AsentumClient, normalizeName, formatName, nameFeeWei,
         NamesNotActiveError, NameNotFoundError } from '@asentum/sdk';

const client = new AsentumClient('https://testnet.asentum.com');

// Name to address (ase1), or null when nobody owns it.
const owner = await client.resolveName('@alice');

// Address to its primary name (without the @), or null.
const name = await client.lookupAddress('ase15xs6rgdp5xs6rgdp5xs6rgdp5xs6rgdpyggla5');
if (name) console.log(formatName(name)); // "@alice"

// A "to" field: "@name" is resolved, an address is passed through.
const { address, name: shown } = await client.resolveRecipient('@alice');

// On a node older than 0.9.0 every lookup throws NamesNotActiveError.

Contract methods

The registry is a JavaScript system contract at ase1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqty736ey. Addresses inside the contract are lowercase hex (what msg.sender is). Every method except register refuses a non-zero value.

There is no approve or operator method: only the owner can move a name. A contract can own names, so a marketplace holds listed names in escrow. See Building a names marketplace.

Writes

Views (free, POST /view)

Events

Indexers can follow the registry from its events. In eth_getTransactionReceipt logs, topics[0] is the BLAKE3 hash of the event name and data is the JSON payload.

Using names in your app

• Resolve at action time. Look the name up when the user sends, not when the page loads, and show the resolved ase1 address on the confirm step.
• Show @name with the address available. Put the primary name next to the address, never instead of a way to see the address.
• Stay quiet until active. Hide name features until a lookup returns active: true, and treat a 404 from an older node the same way.
• Treat names and records as text. Render them as plain text, never as HTML.
• Cache lightly. Primary names can change at any block. A short cache (a minute or so) for display is fine; never cache for sending.