Installation and configuration

Install Lookup 0.11.0 to read names, payment instructions and identity records. It needs no signer. The testnet preset uses the current Registry, Lookup and Primary deployment.

npm install @sorandomains/lookup@0.11.0 @stellar/stellar-sdk@^17

Use Node.js 22.12 or newer. The supported Stellar SDK peer range is >=17 <18. The package is ESM with TypeScript types and supports Node, browsers and workers. To write records, use the Holder SDK. To issue names or configure a namespace, use the Owner SDK. Their TxSigner adapters use a classic G account as the transaction source. Holder also accepts a contractWallet adapter with a C address and signAuthorization callback for supported contract-wallet operations, including native claims. The C wallet authorizes the exact Soroban invocation through its __check_auth implementation; the separate G transaction signer pays network fees and submits. This requires wallet-specific authorization code and Registrar contract_claim_version() == 1 for claims. It does not imply every Holder method or hosted prepare route supports C holders; the current network-address write methods use the G signer.

Universal mode is the default

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

const soran = new Soran({
  network: "testnet",
  reverseNamespaces: ["nova"],
  hintUrl: "https://api.soran.domains",
  timeoutMs: 10_000,
});

This example uses the bundled testnet configuration. Universal Lookup discovers each namespace’s Registrar and Resolver on chain. For a custom deployment, provide its matching registryId, lookupId, rpcUrl and passphrase. The quickstart shows explicit current testnet IDs. Pinning those values lets you select a deployment independently of package updates.

A missing Lookup configuration throws CONFIG.
A custom Registry or network passphrase does not inherit an unrelated Lookup or Primary pin.
The SDK currently provides a testnet preset only.

Configure Primary reads

In universal mode, primaryId has three meanings:

Value	G/C Primary behavior
Explicit contract ID	Must match `Lookup.primary()`.
Omitted for a custom deployment	Use Lookup’s configured Primary anchor.
`null`	Disable G/C Primary reads.

Complete-M Primary is stored in Lookup and does not use this Primary pin.

Explicit direct compatibility mode

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

// Supply a reviewed deployment; these are your application's configuration.
declare const deployment: {
  registryId: string;
  primaryId: string;
  rpcUrl: string;
  passphrase: string;
};

const direct = new Soran({
  registryId: deployment.registryId,
  rpcUrl: deployment.rpcUrl,
  passphrase: deployment.passphrase,
  resolutionMode: "direct",
  primaryId: deployment.primaryId,
});

Choose direct mode only for an integration that deliberately reads native Resolvers itself. lookupId: null also selects it. Direct mode checks Registry, Registrar authority and payment capability. Version 1 selects the native payment ABI; version 2 additionally requires destination version 2 and supports M. Failed or unknown capability reads throw instead of selecting an older ABI. lookup, namespaceMetadata, nameMetadata and M identity reads require universal mode. The new status and batch/history reads also require universal mode and their matching contract capabilities.

Other options

Option	Purpose
`reverseNamespaces`	Ordered namespace candidates for reverse probing; default empty
`hintUrl`	Optional indexed discovery for namespace candidates, holdings and history
`resolverCacheTtlMs`	Direct-mode routing cache lifetime; default 30,000 ms, `0` disables it
`timeoutMs`	Per-chain-read wait bound; a larger aggregate can take longer; does not cancel the underlying request

HTTPS is required except for allowed local-development hosts. Names are checked for ASCII before lowercasing, and whitespace is not trimmed. Malformed configuration or name input must be corrected rather than retried as an absent record. See reference for methods, result types and typed failures.

Write-client fee limit

Owner 0.12.0 and Holder 0.10.0 include a shared per-transaction fee ceiling. Use the matching release configuration. Add maxNetworkFeeStroops to either write client’s configuration to cap the total network fee for each transaction, including storage restoration:

// Options for Owner 0.12.0 or Holder 0.10.0.
const feeOptions = {
  maxNetworkFeeStroops: 50_000_000n, // 5 XLM per transaction
};

The default is 5 XLM. This is a maximum, not a flat charge. The client checks the final transaction before asking the signer to approve it. Username prices and namespace application fees remain separate contract payments. maxNativeFeeStroops remains an optional additional limit for native operations; the lower applicable limit wins. If you omit maxNetworkFeeStroops, an explicitly configured maxNativeFeeStroops supplies the general ceiling too. Valid limits are positive bigint values up to 4_294_967_295n stroops. A restoration and the requested write are separate transactions, each subject to the ceiling. For workflows such as setProfile that submit several transactions, the limit applies to each transaction rather than the whole workflow. Review the estimates before raising the limit.

​Universal mode is the default

​Configure Primary reads

​Explicit direct compatibility mode

​Other options

​Write-client fee limit

Universal mode is the default

Configure Primary reads

Explicit direct compatibility mode

Other options

Write-client fee limit