Skip to main content

​
Install

The only peer dependency is @stellar/stellar-sdk (>=13 <17). The package is ESM, ships TypeScript types, and runs in both browsers (WebCrypto) and Node (node:crypto) with no bundler shims.
Published on npm as @sorandomains/lookup; source on GitHub.

​
The simplest setup

A network preset fills in the RPC URL, network passphrase, Registry id, and PrimaryName id for you. Every field is individually overridable.

​
Network presets

The testnet preset (the default) ships these values, exported as DEPLOYMENTS: A mainnet preset is populated at mainnet launch. Until then, targeting mainnet means passing rpcUrl, passphrase, registryId, and primaryId: null explicitly — the constructor always starts from a preset and explicit fields override it, so omitting primaryId would inherit the testnet PrimaryName id from the default preset.

​
Bring your own RPC

Every SDK call is a read-only Soroban RPC simulation, so the RPC endpoint is the one piece of infrastructure you actually trust. Point it anywhere — including your own node:
Plain http:// URLs are accepted only for localhost / 127.0.0.1 / [::1]. A production consumer over unencrypted HTTP would let an on-path attacker forge every read the SDK makes, so the SDK refuses it.

​
All options

A few options deserve context:
  • primaryId — the platform-deployed PrimaryName contract (one immutable instance per network). undefined inherits the preset; null explicitly disables the primary-name feature even when the preset ships one. See reverse lookup and primary names.
  • registrars — for namespaces that run closed (registrar-side) resolution instead of a public resolver, map the namespace label to its Registrar contract id and resolve() will ask it directly.
  • reverseNamespaces — reverse records live on per-namespace resolvers, and the chain cannot enumerate namespaces, so reverseLookup must be told which ones to probe. Defaults to [].
  • resolverCacheTtlMs — how long the namespace→resolver pointer is cached. The pointer can change for a reclaimable namespace, so long-lived instances should keep this bounded (default 30 seconds; 0 disables caching).
  • hintUrl — a liveness-only fallback that supplies the list of namespaces to probe when reverseNamespaces isn’t set. It is never in the trust path: a lying hint can hide a name, never forge one.

​
Fail-closed construction

Configuration mistakes surface at new Soran(...), not deep inside your render path:
  • A malformed primaryId (not a C… contract strkey) throws a SoranError immediately.
  • A malformed label in reverseNamespaces throws a SoranError immediately.

​
Next

Resolving names

resolve, verify, records — and the confirm-time re-check.

SDK reference

Every method and type in one table.