Managing your name

Your Soran name can carry receiving addresses, a public profile and subnames for different purposes. The holder controls its records; the namespace’s policy determines rights such as transfer and renewal.

I want to…	Start here
Change my Stellar address or required memo	Payment instructions
Add Bitcoin, Ethereum or other network addresses	Network addresses
Add an avatar, website or social handles	Publish your profile
Show my name when an app looks up my wallet	Account display names
Create `shop.alice.nova` under my name	Create subnames
Transfer or renew my name	Transfer · Renewal

Open your name in the app

Find your name through Soran’s lookup and open its public record. You can inspect the holder, ownership conditions and receiving instructions without signing in to the operator console. Choose Manage this name in Payment and identity, then Connect your wallet. The holder can change Stellar payment instructions. The wallet controlling the receiving address can choose its display and primary names. Network addresses and Subnames have their own management controls on the same page. The app’s wallet editing flow uses a classic G account. A name held by a C contract needs an integration that supplies that contract’s authorization; connecting its fee-paying G wallet does not make the G wallet the holder. Profile fields use the Holder SDK or a configured MCP integration. The examples below use Holder 0.10.0. Check release status for package and namespace contract requirements.

Connect your wallet

npm install @sorandomains/holder@0.10.0 @stellar/stellar-sdk@^17

import { SoranHolder, type TxSigner } from "@sorandomains/holder";

declare const walletSigner: TxSigner;
declare const deployment: {
  registryId: string;
  lookupId: string;
  primaryId: string;
  rpcUrl: string;
  passphrase: string;
};

const me = new SoranHolder({
  signer: walletSigner,
  registryId: deployment.registryId,
  lookupId: deployment.lookupId,
  primaryId: deployment.primaryId,
  rpcUrl: deployment.rpcUrl,
  passphrase: deployment.passphrase,
});

Use one matching deployment configuration. walletSigner implements publicKey() and signTransaction(xdr, options). A backend can use keypairSigner with a securely supplied secret. Keep signing keys out of frontend configuration. This example uses a classic G transaction-source account. For a contract-held name, supply the Holder SDK’s contractWallet adapter as well as a G transaction payer. The C wallet authorizes supported actions using the format its deployed __check_auth accepts. M destinations are payment routes, not signer identities.

Claim a username

Read claimQuote for the current price, receiving treasury, admission rules and ownership terms.
Build a request with createClaimIntent and review the complete receiving destination.
Authorize claim. Issuance, fee, destination and receipt succeed together.

See the signup and recovery examples. Claiming alice.nova is separate from applying for the top-level namespace nova. Both G accounts and C contract wallets can claim on compatible Registrars. C claiming requires contract_claim_version() == 1; choosing a C receiving destination alone does not make that contract the claimant or upgrade an older Registrar.

Address and memo together

In the app, enter the complete destination under Payment and identity. Choose Add a memo if the recipient requires one, enter its exact type and value, then choose Sign & update. After confirmation, check the refreshed payment instructions. From code, use setPayment to update the address and memo together:

await me.setPayment("alice.nova", {
  address: exchangeAddress,
  memo: { type: "id", value: "123456" },
});

// Explicitly remove the memo while selecting the complete destination:
await me.setPayment("alice.nova", {
  address: myAddress,
  memo: { type: "none" },
});

The native Resolver updates both fields atomically on chain. Memos are optional: ordinary records without a configured instruction resolve with none. After configuration, missing or invalid payment state fails instead of reverting to an ordinary address.

Choose the right write method

Method	Use and limits
`setPayment(name, destination)`	Set the complete G/M/C destination and memo. Use this for required memos and M routes.
`setRecord(name, address)`	Update a memo-free Resolver address. The contract refuses a write that would discard a required memo or M routing ID.
`setAddress(name, address)`	Change an ordinary name’s Registrar target, which Resolver instructions may override. The SDK first requires a current direct memo-free payment. This method does not edit subnames.

Read the effective address and memo with Lookup’s resolvePayment. G supports none, id, text and hash memos. M and C support none only. Pass the full M address to setPayment; its exact base G and u64 ID are stored through set_muxed. The ID never becomes a transaction memo. See destination examples and exact constraints.

Profile records

Use setProfile to publish standard fields such as your avatar, description, website and social handles, including on a subname you control. It submits one transaction per key, in order; earlier confirmed writes remain if a later field fails. The current holder authorizes the records, while the information itself is self-published. Published MCP 0.10.0 also supports these writes on ordinary names and subnames through a configured local signer; hosted MCP is read-only. clearText retracts a field by writing an empty value; it does not erase blockchain history. Standard profile readers treat empty text as unset. Payment memos use setPayment, not text records. Follow Publish your profile for the complete example and read-back step.

Network addresses

Publish a separate address for each additional network your namespace enables. The app’s Network addresses section and the SDK’s setChainAddress manage these records. Stellar continues to use setPayment. These are mainnet destination addresses, even when Soran’s naming contracts are on Stellar testnet. Follow Add network addresses to save and verify them.

Subnames

When your namespace enables subnames, you can create one child level under a name you hold, such as shop.alice.nova. The parent holder controls each child’s receiving instructions and profile. A different receiving wallet does not gain ownership. Use Create and manage subnames for the app flow and SDK examples. The existing setPayment, setRecord, profile and display-name methods accept child names. Claiming, setAddress, individual name transfers and renewals remain operations on ordinary name.namespace names.

Account display names

In the name’s Display name controls, choose Set as display name, then optionally Set as primary name. The receiving wallet must authorize these choices. In code:

await me.setReverse("alice.nova");
await me.setPrimary("alice.nova");

Reverse and Primary writes require the address’s authorization and a current forward match. Owning a name that pays to someone else’s account does not let you elect that account’s identity. The SDK checks Primary’s Registry anchor before signing. Use clearReverse(namespace) and clearPrimary() to remove account elections. G/C elections do not distinguish customer memos on a shared account. Changing the payment destination to M can invalidate a previous G/C election; use the M methods below for that exact route.

Muxed display names

M elections require a configured lookupId and Lookup capability muxed_identity_version() == 1, available on the current testnet deployment. A custom Registry or passphrase does not inherit an unrelated Lookup pin. The signer must control the base G account. A customer who receives an exchange deposit M address cannot sign for the exchange.

const muxedAddress =
  "MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAAAAAABUTGI4";

// The active name must already resolve to this exact M address.
await me.setReverseMuxed("customer420.nova", muxedAddress);
// Optional: select the same verified reverse name across namespaces.
await me.setPrimaryMuxed("customer420.nova", muxedAddress);

Make the active name resolve to the exact M address with setPayment.
Elect the namespace reverse name with setReverseMuxed.
Optionally elect that same verified reverse name as Primary with setPrimaryMuxed.

Each call is a separate transaction. If Primary is cancelled, the successful reverse election remains. Changing or clearing reverse can stop a Primary using the old election from verifying. Claiming a name or publishing a destination does not elect display names automatically.

await me.clearReverseMuxed("nova", muxedAddress);
await me.clearPrimaryMuxed(muxedAddress);

The four M election methods write to Universal Lookup. Authorization binds the name or namespace, base G and exact u64 ID. They leave payment instructions unchanged. ID "0" is distinct from the base G account. A transfer or reissue advances generation and requires a fresh election. Setting or clearing a display name in Lookup or Primary pays network costs and any required record or instance storage rent. These calls do not renew shared Wasm code. Your transaction’s fee payer still pays for the write; this update does not automatically sponsor it. Check the simulated fee before signing. Operators can maintain existing elections with the contract’s permissionless touch_reverse_muxed and touch_primary_muxed calls. A touch maintains the existing record and instance and renews code by at most 17,280 ledgers per call, paid by its transaction’s fee payer. It does not create an election or make stale proof valid. See the contract ABI and stored records.

Name transfer

For an ordinary name such as alice.nova, the current holder proposes a transfer:

await me.proposeNameTransfer("alice.nova", recipientAddress);
const pending = await me.pendingNameTransfer("alice.nova");

The intended recipient then accepts with its own Holder client:

Method	Receiving details after acceptance
`acceptNameTransferWithDestination(intent)`	Atomically installs the reviewed G/M/C destination from a `TransferIntent`.
`acceptNameTransfer(name)`	Uses the recipient’s ordinary default route. The sender’s memo or M destination is not copied.

The explicit intent binds the pending proposal, sender, recipient, generation and expiry. Acceptance preserves the name’s expiry and advances generation. Namespace transfer policy and name activity gates apply. Changing the parent name’s ownership invalidates its existing subnames. They cannot be transferred independently; the new holder recreates the children they want. To withdraw a pending proposal, call me.cancelNameTransfer("alice.nova") instead. Transferring one name is separate from transferring its namespace.

Renew a finite name

Read renewalPreview(name) before authorizing renewal. It returns the exact generation and stored destination, including active: false for an expired name. This preview does not make an expired name resolve for payments. Use renewName with a RenewIntent binding the holder, generation, existing expiry, immutable term and accepted new-expiry bounds.

Rule	Holder renewal behavior
Earliest renewal	Last `min(30 days, term)` of a finite lease
After expiry	Allowed while the same recorded ownership generation remains, subject to reservation rules
Exclusive renewal grace	Owner-configured, from 0 to 90 days; defaults to 0 and protects eligible expiries from reissue
Extension	One immutable term from `max(now, expiry)`, no more than 100 years from execution
Fees	No separate username renewal fee; network/storage costs apply
Independence	Public-claim pause, app eligibility and namespace ownership epochs do not block renewal

Zero-term names and stale generations are ineligible. Renewal preserves generation and reactivates its stored receiving instructions. Owner reclaim rights still follow namespace policy. An eligible grace period delays reissue; it does not keep an expired name resolving or transferable. Enabling grace protects expiries at or after activation, not names already expired then. A reserved name cannot be renewed by the old holder once it becomes reissuable. Read the current Registrar’s grace settings before relying on a renewal window. Subnames have no separate renewal. Renewing the same parent ownership restores its valid subnames; a reissued parent does not restore the former holder’s children. See the exact lifecycle ABI before constructing a transfer or renewal intent.

Errors and uncertain submissions

Simulation catches many permission/policy failures before signing. Existing Holder methods use HolderError; native methods use NativeClaimError with kind, optional contract code/name and txHash. A transaction that reached the network can carry that recovery hash. Check uncertain inclusion before retrying. Preflight success does not guarantee later submission success or remove its network fee.

​Open your name in the app

​Connect your wallet

​Claim a username

​Address and memo together

​Choose the right write method

​Profile records

​Network addresses

​Subnames

​Account display names

​Muxed display names

​Name transfer

​Renew a finite name

​Errors and uncertain submissions