Reverse and Primary names

A reverse lookup turns an address into a verified display name. Use reverse for one namespace, or primaryOf for the address’s preferred name across namespaces. Use the five live wallet examples to test both directions. Each has an elected Nova reverse name and Primary name; the hello-world contract example is forward-only. Lookup 0.11.0 supports G/C account identities and complete M-address identities. M single reads require universal mode and a Lookup with muxed_identity_version() == 1; the current testnet deployment provides it.

const scoped = await soran.reverse("nova", address);
const primary = await soran.primaryOf(address);
const preferred = await soran.reverseLookup(address, ["nova", "acme"]);
const candidates = await soran.reverseNames(address, ["nova", "acme"]);

How verification works

A returned name must be canonical and active. Its current generation and routing must forward-resolve to the requested address in the expected namespace. A required memo is allowed in a G account identity proof and remains part of the separate payment instruction. A supported subname, such as pay.alice.nova, can also be elected. Its proof depends on the live parent binding and subname policy. Parent ownership changes or child suspension invalidate the previous live answer. The receiving identity authorizes its election; control of the parent name alone does not authorize an election for another address. Combine an elected name with its profile to show an avatar, description or social links. Additional network addresses are forward records; these reverse and Primary methods identify Stellar G/C/M destinations. G/C Primary and reverse identify an account. They do not identify an individual customer or subaccount behind a pooled exchange address. A customer’s name and memo should not be presented as the identity of everyone using that address.

Muxed identities use the complete address

A muxed lookup asks about the complete M destination. The same G account with IDs "0", "420" and "18446744073709551615" has three separate elections. None falls back to the G account, another ID or G plus memo. A name that pays to M cannot serve as a forward proof for the base G account. The underlying G account authorizes each M election. If an exchange controls it, the exchange must sign. A deposit customer cannot elect a name merely because they received an M address. The election proves an account-authorized name for a payment route, not a person’s real-world identity.

import { encodeMuxedAddress } from "@sorandomains/lookup";

const account = "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ";
const m0 = encodeMuxedAddress(account, "0");
const m420 = encodeMuxedAddress(account, "420");
const mMax = encodeMuxedAddress(account, "18446744073709551615");
const muxedReverse = await soran.reverse("nova", m420);
const muxedPrimary = await soran.primaryOf(m420);
// m0, m420, mMax and account each identify a different lookup input.

These addresses illustrate distinct inputs; an election is not guaranteed. The SDK decodes M and calls Lookup’s reverse_muxed or primary_name_muxed with the exact u64 ID. Never convert that ID to a JavaScript number. Direct mode rejects M identity reads. Use the Holder SDK to create elections. Name ownership alone cannot authorize a Primary record for a destination you do not control.

History screens

For several addresses in a history screen, use Lookup 0.11.0’s history helpers:

const addresses = [account, m420]; // preserves full G/C/M identities
const preferred = await soran.primaryNames(addresses);
const inNova = await soran.reverseMany("nova", addresses);

for (const row of preferred) {
  if (row.kind === "name") console.log(row.address, row.name);
  else if (row.kind === "none") console.log(row.address, "No verified election returned");
  else console.log(row.address, "Read failed", row.errorCode, row.errorName);
  console.log("Observed at", row.ledger, row.timestamp);
}

Each accepts up to 256 identities, preserves order and duplicates, and attaches the ledger/time of each successful call to its rows. The helper checks the Lookup anchor and batch capability once, then requests up to 16 Primary identities or 32 identities in one namespace per call. A leading host budget failure halves the current batch until it fits. The smaller size is used for the remaining rows. Ordinary contract errors appear as kind: "error"; restoration, transport, ABI and single-item budget failures reject the helper. Catch those failures and show an unavailable state. Use primaryBatch(addresses) or reverseBatch(namespace, addresses) for one explicit contract invocation. They return {ledger, timestamp, results} and do not split a failed call. Query primaryBatchReadLimit() and batchReadLimit() before forming batches. The current deployment advertises 16 and 32, respectively; compatible older deployments can report lower limits. Older or custom namespace contracts can also need smaller batches. These helpers return elected display names, not an inventory of names owned by an address. The contract reference describes the raw ABI. G/C entries still have the underlying proof limitations below. A none result does not establish that no stored declaration exists. Re-resolve payment instructions before paying; a display-name result is not a destination.

Discovery scope

reverseLookup tries Primary first, then ordered namespace candidates. Candidates can come from its argument, reverseNamespaces, or a configured indexer hint. reverseNames checks those candidates and includes a verified Primary when available. Neither method enumerates every namespace on chain. The old HTTP /v1/reverse/:address route is a holder hint, not the source of these verified reverse answers. Holdings and reverse records answer different questions.

Absence and failures

G/C addresses

primaryOf returning null means Primary returned no currently verified election. The Primary ABI may return None after a dependent proof read fails, so null cannot distinguish every absence from every internal failure. Resolver reverse has a similar limitation. Nonempty answers are forward-checked. Lookup-level errors, including missing Primary configuration, still throw. reverseLookup and reverseNames can recover from a Primary failure by probing namespace candidates; failed namespace probes are not fabricated empty results.

M addresses

Missing elections and proven stale matches return null. Malformed records, failed capability checks, unavailable dependencies and unsupported interfaces throw. They never trigger a base-G fallback. The stored Registrar, Resolver and generation must match current routing and the exact M payment. An M Primary must also match its namespace’s current verified M reverse election.

Primary configuration

primaryId configures the G/C path. A custom Primary must match the Registry anchor; an explicit ID in universal mode must also match Lookup’s configured Primary. M Primary is stored in Lookup and does not depend on this separate contract or pin.

​How verification works

​Muxed identities use the complete address

​History screens

​Discovery scope

​Absence and failures

​G/C addresses

​M addresses

​Primary configuration