> ## Documentation Index > Fetch the complete documentation index at: https://docs.soran.domains/llms.txt > Use this file to discover all available pages before exploring further. # SDK reference > Every constructor option, method, type, and error in @sorandomains/lookup. Everything the `Soran` class does is a read-only Soroban RPC simulation. The SDK builds no write transactions — writes (registering, issuing, reverse records, primaries) are address-authorized transactions built and signed by wallets. ## Constructor ```ts theme={null} new Soran(options?: SoranOptions) ``` | Option | Type | Default | Semantics | | -------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `network` | `"testnet"` | `"testnet"` | Deployment preset (`"mainnet"` after launch); fills `rpcUrl`, `passphrase`, `registryId`, and `primaryId` | | `rpcUrl` | `string` | preset | Soroban RPC endpoint — any RPC you trust, including your own; `http://` allowed only for localhost | | `passphrase` | `string` | preset | Network passphrase | | `registryId` | `string` | preset | The immutable Registry contract id | | `primaryId` | `string \| null` | preset | PrimaryName contract id; `null` explicitly disables the primary-name feature; malformed ids throw at construction | | `registrars` | `Record` | `{}` | Registrar ids for namespaces running closed (registrar-side) resolution | | `reverseNamespaces` | `string[]` | `[]` | Namespaces `reverseLookup` probes, in priority order; malformed labels throw at construction | | `resolverCacheTtlMs` | `number` | `30_000` | Namespace→resolver pointer cache TTL; `0` disables caching | | `hintUrl` | `string` | — | Namespace-**list** hint endpoint for `reverseLookup`; liveness-only, never in the trust path | | `timeoutMs` | `number` | — | Upper bound on how long any single chain read may keep the caller waiting; on expiry the call rejects with a `SoranError` of code `"TIMEOUT"`. Bounds the wait only — the underlying request is not cancelled. Unset = no bound | ## Resolution | Method | Returns | Semantics | | ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `resolve(name)` | `Promise` | The address the name pays to; `null` when unissued, expired, or no resolver — decided by contract logic | | `record(name)` | `Promise` | Full record: `{ name, address, node, resolver }` (node hex-encoded; resolver id that answered, or `null`) | | `text(name, key)` | `Promise` | A text record (`"url"`, `"avatar"`, …), or `null` | | `verify(name, address)` | `Promise` | Does the name resolve to this address right now? The confirm-time pay-to-name safety check | | `assurance(name)` | `Promise` | Opt-in trust verdict on the namespace's resolver — see [assurance](/sdk/assurance) | | `details(name)` | `Promise` | The full live picture in one call — resolution, holder, expiry, generation, namespace owner/registrar/resolver, policy, permanence, and assurance. Several parallel chain reads per call; cache briefly on detail pages. Registration *date* is deliberately absent — the chain stores no issue timestamp; derive it from the name's `issued` event via an indexer and treat it as informational | ## Identity & enumeration All 0.4.0 additions — see [Identity & enumeration](/sdk/identity) for the trust model of each. | Method | Returns | Trust bucket | | ------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `namesOf(address)` | `Promise` | Hint-discovered, **chain-verified** per candidate (`holder_of_node`, contract expiry-gated); needs `hintUrl`, else CONFIG | | `reverseNames(address, namespaces?)` | `Promise` | Chain-verified; all reverse claims, primary flagged and always included | | `profile(name)` | `Promise` | Chain-verified reads of the standard `PROFILE_KEYS`; values are holder-authored free text | | `identity(name)` | `Promise` | details + profile fail-closed; the three display-name enrichments degrade to null | | `walletProfile(address)` | `Promise` | primary + reverse + holdings + profile; `names` null without `hintUrl` | | `history(name)` | `Promise` | **Indexed, informational** — entries carry ledger + txHash for independent verification; needs `hintUrl` | ## Reverse and primary | Method | Returns | Semantics | | ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reverseLookup(address, namespaces?)` | `Promise` | Primary name first (when `primaryId` set), then per-namespace `name_of` probes in parallel with deterministic priority; every answer contract-verified. Namespace-probe failures throw; a failed *primary* read degrades to the probes. With **no** source at all (no primary, no configured/passed namespaces, no hint) it throws a `SoranError` of code `"CONFIG"` instead of silently answering `null` | | `reverseVerify(address, name)` | `Promise` | Verifies the address's contract-verified reverse record is exactly this name; `false` for malformed addresses or resolverless namespaces | | `primaryOf(address)` | `Promise` | The declared cross-namespace primary name; self-verifying on chain; read failures **throw**, never masquerade as "no primary"; `null` when the feature is unconfigured | ## Namespace-level reads | Method | Returns | Semantics | | ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `namespace(ns)` | `Promise<{ owner, resolver } \| null>` | Owner address and resolver id of a namespace; `null` if unregistered | | `isAvailable(ns)` | `Promise` | `true` when the label is unregistered in the Registry. Reserved labels also read as available but can't be claimed through the open window — the console tells you when a label is reserved | ## Hashing The exact on-chain hashing, exposed for interoperability: | Method | Returns | Semantics | | --------------------- | --------------------- | --------------------------------------------------------------------- | | `namehash(namespace)` | `Promise` | Registry node of a top-level namespace: `sha256(ZERO32 ‖ sha256(ns))` | | `node(name)` | `Promise` | Full node of `label.namespace`: `sha256(nsNode ‖ sha256(label))` | ## Exported helpers and types ### parseName ```ts theme={null} parseName(name: string): { label: string; namespace: string } ``` Normalizes case (input is lowercased before validation) and splits `label.namespace`; throws `SoranError` unless both parts are canonical labels (`[a-z0-9-]`, 1–63 chars, no leading or trailing hyphen). The same label validation every name-taking SDK method applies to its input. (Methods taking a bare namespace validate the single label the same way; malformed addresses return `null`/`false` rather than throwing.) ### SoranError ```ts theme={null} class SoranError extends Error { name = "SoranError"; code: SoranErrorCode; // machine-readable category } type SoranErrorCode = | "INVALID_INPUT" // bad name/label/address from the caller | "CONFIG" // bad or missing constructor options / no reverse source | "RPC" // network or transport failure | "SIMULATION" // the node rejected the read | "ARCHIVED" // the entry exists but its rent lapsed | "ABI" // a contract answered with an unexpected shape | "TIMEOUT"; // the configured timeoutMs elapsed ``` Thrown whenever a chain read cannot be completed or input is malformed — so a transient error is never silently mistaken for "unregistered" or "no address". A `null` return always means a *successful* read that found nothing. Branch on `code`, not on message text. ### NameRecord ```ts theme={null} type NameRecord = { name: string; address: string | null; node: string; // hex resolver: string | null; // resolver contract that answered, if any }; ``` ### NameAssurance ```ts theme={null} type NameAssurance = { resolverAttested: boolean; // live pointer === Registry-attested resolver resolverTainted: boolean; // attested resolver has upgraded at least once resolverLocked: boolean; // pointer locked, can no longer change trustworthy: boolean; // locked ∧ attested ∧ ¬tainted }; ``` ### NameDetails / NamespaceDetails The `details()` aggregate: name-level `{ name, node, address, resolver, holder, expiresAt, generation }` (holder is non-null even for an **expired** name — check `expiresAt`, where `0n` = never expires and `null` = never issued) plus `namespace: { namespace, owner, registrar, resolver, permanent, policy }` and the `assurance` verdict. All live chain reads; nothing indexed. ### DEPLOYMENTS The known public deployment presets (`testnet` today; `mainnet` at launch), exported so you can read the exact ids the SDK uses — see [installation](/sdk/installation#network-presets).