Explorer integration

The end-to-end recipe for a block explorer or dashboard, names next to addresses with forward confirmation, search across all three namespaces and both registries, name detail pages, the events to index, and the trust rule for an index.

Purpose

This is the package for a block explorer, portfolio dashboard or analytics surface that wants to show @alice or alice.arc next to an address, offer name search, and render a page per name. It walks each surface end to end and states which data may come from an index and which must be read from the chain before display.

Contracts, endpoints, and the optional speed layer

• Chain reads through @arcns/resolve (viem, eth_call): resolve(), resolveAll(), reverse(), records(), text(). This is the source of truth.
• REST at https://api.arcns.io: the same reads over HTTP with cache-control: public, max-age=5, open CORS, 20 requests per second per client. See API.
• Your index of the events below: fast lists, history, search-as-you-type. Never the value shown as current without a chain check.
• ArcScan. Name display on testnet.arcscan.app is controlled by Blockscout. A BENS-compatible subgraph and a public GraphQL mirror are planned; this page gains their URLs when published.

Flow 1: a name next to an address

Reverse resolution, with forward confirmation already applied by the SDK.

export async function nameFor(address: `0x${string}`): Promise<string | null> {
  const p = await arcns.reverse(address);
  // p = { name: "@alice" | "alice.arc" | "bob.circle", namespace, registry, product, node, address, controller }
  // null -> no primary (or a stale one) -> show the truncated address
  return p?.name ?? null;
}

There is exactly one primary per address across all three namespaces (one verbatim ENS ReverseRegistrar). The SDK returns it only if it forward-confirms: an @handle primary must still be owned by the address; a .arc / .circle primary must resolve back to the address (addr(node, 0x804cef52), then coin type 60) in our registry. A stale string is null, never the previous owner.

reverse() is not cached and makes 2 to 4 eth_calls. For a 50-row table, coalesce concurrent reads of the same address and keep any cache you add short (15 seconds or less), invalidated on the ReverseClaimed, NameChanged and Transfer events you index.

A minimal React component that keeps the address on title and renders the namespace badge and registry short-address next to the name:

import { useEffect, useState } from "react";
import { namespaceLabel } from "@arcns/resolve";
import { arcns } from "./resolver";

const short = (a: string) => `${a.slice(0, 6)}…${a.slice(-4)}`;

export function AddressName({ address }: { address: `0x${string}` }) {
  const [p, setP] = useState<Awaited<ReturnType<typeof arcns.reverse>>>(null);
  useEffect(() => {
    let alive = true;
    arcns.reverse(address).then((r) => alive && setP(r)).catch(() => alive && setP(null));
    return () => { alive = false; };
  }, [address]);
  if (!p) return <span title={address} style={{ fontFamily: "monospace" }}>{short(address)}</span>;
  return (
    <span title={`${address} · ${namespaceLabel(p.namespace)} · registry ${p.registry}`}>
      {p.name} <small>{namespaceLabel(p.namespace)} · {short(p.registry)}</small>
    </span>
  );
}

Flow 2: the search bar

A user types alice, @alice, alice.arc or alice.circle. Show all three namespaces side by side, and for a TLD every pinned registry, and never auto-select.

resolveAll() returns every registry that holds the name and has a record, ours first, without throwing on disagreement. Use looksLikeName(input) first so a pasted 0x… goes to the address page instead of a name error. An index can drive the suggestion list while typing; the row a user clicks is confirmed on chain before its page renders.

Flow 3: the name page

Fields to show for one name, every one of them from a chain read at render time:

Flow 4: ownership and history

Ownership is the ERC-721 Transfer history of the HandleRegistry (handles) or the TLD's BaseRegistrarImplementation (.arc, .circle), plus NewOwner on the ENS registry for subnames. Current owner is a chain read (ownerOf / owner(node)); the list of past owners may come from your index. A burned handle has no owner: the SDK reports not-found with reason: "nft-burned", and the last owner is never shown as current.

Events to index

The .arc / .circle registry, registrar, resolver profiles and reverse registrar reuse the ENS contracts verbatim, so the events are the ENS events. The exact ABIs ship with the deployment file (see Contracts); the ArcNS-specific ArcNSResolver ABI is checked into contracts/abi/ in the repository.

Index at the addresses in the deployment file and at the pinned peer registry's contracts if you want its .arc / .circle names in search; label those rows with their registry, as the SDK does.

Trust rules

The index lags the chain; show the block it is at. Every chain read the SDK makes is pinned to one block and carries epoch; a record whose epoch is older than the name's current epoch does not exist and is never displayed. An rpc-error is "could not verify", never "does not exist".

Minimum interface

• Search bar: accepts alice, @alice, alice.arc, alice.circle, 0x…; shows all three namespaces and both registries side by side; never auto-selects.
• Address page: the primary name (forward-confirmed) next to the address, with the namespace badge and registry short-address; the truncated address when there is none.
• Name page: the fields in flow 3; the sunset banner when tld.status === "sunset"; a 410 / tld-retired page after sunsetAt.
• Token page: the /nft/:name card and attributes for the ERC-721.

Avoid misleading output:

Failure modes and edge cases

Handoff

• We give: the SDK, the API, the events above, the deployment file when published, and this page.
• We need: the block your index is at, the URL of your name pages so we can link to them from external_url, and the RPC you read from so we can confirm it serves chain id 5042002.
• Contact: [email protected].

Questions

Questions: [email protected].