Welcome to ANS

Quickstart

Use this sequence if you just want to get from zero to a registered name and a public identity profile.

1. Open the app. Visit arcnames.xyz.
2. Connect a wallet. Rabby is generally smoother than MetaMask on ARC Testnet.
3. Switch to ARC Testnet. The app can add or switch the network automatically when the wallet supports it.
4. Fund gas. Use Circle Faucet to get testnet USDC.
5. Search and register a name. If the name is available, confirm the transaction in the wallet.
6. Open Identity. Choose your primary name, upload an avatar, and connect a Twitter/X handle.

Core Concepts

Domains

The `Domains` section is the core registration and lookup surface of the application.

What users can do

• Search any `.arc` name
• Check whether the name is available
• Register an available name on-chain
• Inspect recent registrations
• See related suggestions
• Inspect taken-domain public profile data

Name rules

• Length must be between 3 and 32 characters
• Allowed characters: lowercase a-z, digits 0-9, hyphen -
• Registration is first-come, first-served
• Names do not expire in the current contract design

Identity

The `Identity` section is the profile management layer for the connected wallet.

Current identity capabilities

• Load all names owned by the connected wallet via getNames(address)
• Select one name as the primary name inside the app
• Upload or replace a public avatar for the primary domain
• Remove the avatar
• Attach or remove a Twitter/X handle

Public Profiles

Public profile data is no longer stored only in the browser. It is now persisted in Vercel Blob and served publicly.

Profile fields

• avatar
• avatarPathname
• twitter
• address
• name
• updatedAt

Avatar behavior

• Only image uploads are accepted
• The current size limit is 1 MB
• Files are uploaded to Blob through a signed flow
• Profiles reference the final public Blob URL

Taken Domain Display

When a searched domain is already registered, the search result becomes a lightweight public profile card.

If profile data exists

• The result icon becomes the public avatar
• The Twitter/X handle appears in the result metadata
• The owner address remains visible and linked to the explorer

If profile data does not exist

• The result falls back to the standard taken-domain state
• Owner address and explorer actions are still shown

Architecture

The project has three implementation layers.

1. Smart contract

The contract in NameRegistry.sol manages registration and read-side ownership logic.

2. Frontend

The UI in arc-ens.html handles wallet UX, search, registration, identity flows, and profile editing.

3. Serverless API

Small Vercel Functions provide read failover, Blob uploads, and public profile persistence.

Contract Reference

Main public contract functions:

register(string name)
resolve(string name) returns (address)
isAvailable(string name) returns (bool)
getNames(address owner) returns (string[] memory)
reverseResolve(address addr) returns (string memory)
nameCount(address owner) returns (uint256)

Current tradeoffs

• No on-chain primary-name setter yet
• No on-chain avatar metadata yet
• NameRegistered uses string indexed name, which is less convenient for some log consumers

API Reference

The app exposes a small server-side surface on the same Vercel project.

POST /api/rpc

ARC JSON-RPC proxy with failover and basic rate-limit retry behavior.

POST /api/blob-upload

Issues a secure upload token for avatar upload after verifying the signed identity proof.

GET /api/profile

Returns the public profile for a specific wallet + domain pair.

POST /api/profile

Verifies a signed payload, then writes the public profile JSON to Blob.

Storage & Security

Storage model

• Avatars are stored in public Vercel Blob objects
• Profile JSON is also stored in Blob
• The app reads profile data by wallet address + domain name

Authorization model

• The frontend builds a signed proof message
• The wallet signs that message
• The server verifies the recovered address
• Only after verification does the server accept upload or save profile data

Local Development

Because the app depends on Vercel Functions and Vercel Blob, local development should run through Vercel instead of a bare static server.

npm install
vercel env pull .env.local
vercel dev

Required tooling:

• Node.js 18+
• npm
• Vercel CLI
• Wallet with ARC Testnet support

Vercel Deployment

The project is already structured for Vercel deployment.

vercel deploy --prod

Required project state:

• project linked in Vercel CLI
• Blob store attached to the project
• BLOB_READ_WRITE_TOKEN present in environments

Current root rewrite behavior comes from vercel.json.

Troubleshooting

Wallet reconnect

The app restores a previously authorized wallet on reload through a quiet account check. If the user explicitly disconnects through the UI, auto-restore is suppressed until reconnect.

MetaMask instability on ARC

Rabby is usually more reliable than MetaMask on ARC Testnet. The app still contains network repair and warning logic for MetaMask users.

Blob upload issues

If avatar upload fails, check that the Vercel project still has an attached Blob store and that BLOB_READ_WRITE_TOKEN exists in the active environment.