Lookup SDK reference

Use this reference for Lookup 0.11.0. Start with installation for configuration or resolving payments for a practical flow. Lookup performs reads through Soroban RPC and optionally uses HTTP discovery/history. Writes belong to the Owner and Holder SDKs.

Constructor

new Soran(options?: SoranOptions) accepts:

Option	Type	Meaning
`network`	`"testnet"`	Supported preset; no mainnet preset yet
`registryId`, `rpcUrl`, `passphrase`	`string`	Coherent deployment and network overrides
`lookupId`	`string` or `null`	Verified Lookup ID; `null` explicitly selects direct mode
`resolutionMode`	`"universal"` or `"direct"`	Universal by default
`primaryId`	`string` or `null`	Optional G/C Primary anchor check; `null` disables that path
`reverseNamespaces`	`string[]`	Ordered candidate namespaces
`hintUrl`	`string`	Optional HTTP discovery/history API
`resolverCacheTtlMs`	`number`	Direct routing cache, default 30,000 ms
`timeoutMs`	`number`	Per-read waiting bound

Custom Registry/passphrase settings inherit no unrelated Lookup or Primary pin. There is no registrars option or silent closed-resolution fallback in this API.

Methods

Payments and metadata

Method	Result
`lookup(name)`	Native payment or legacy address with explicitly unknown memo capability; universal only
`resolvePayment(name)`	Complete `PaymentDestination`
`verifyPayment(name,payment)`	Fresh exact tuple comparison
`resolve(name)`, `record(name)`, `verify(name,address)`	Native memo-free address convenience methods
`namespaceMetadata(namespace)`	Owner, current routing, policy, provenance and permanence, or `null`; universal only
`nameMetadata(name)`	Holder, built-in target, generation, expiry, active/no-expiry flags, or `null`; universal only
`nameStatus(name)`	Registration state including suspended children, name, ledger and timestamp; universal status capability `1`
`text(name,key)`	One text value or `null`
`assurance(name)`	Resolver provenance, not payment or Lookup-code attestation
`namespace(namespace)`, `isAvailable(namespace)`	Owner/Resolver subset and namespace ownership absence check
`details(name)`	Ownership metadata plus complete effective native payment

SDK metadata uses camelCase, such as builtinAddress, expiresAt and namespacePermanent. Contract ABI fields use snake_case. Generations and ownership timestamps are exact bigint values; encode them explicitly when producing JSON, usually as decimal strings.

Network addresses and subnames

Method	Result
`chainPolicy(namespace)`	`ChainNetwork[]` of currently enabled additional networks
`chainAddress(name,network)`	Canonical address string or `null` for that explicitly selected network
`subnamePolicy(namespace)`	`"enabled"`, `"creation-disabled"` or `"suspended"`
`subnameRecord(name)`	Raw `SubnameRecord` or `null`, including removed/stale child state
`subnames(parent,{offset?,limit?})`	On-chain child page: `parent`, `policy`, `records`, `offset`, `nextOffset`

Network reads require compatible multichain contracts and owner enablement. Disabled, unsupported, inactive and failed reads remain errors, distinct from a successful absent record. Network examples show reads and holder writes. Subname pages use offsets and limits of 1–16, defaulting to 16. SubnameRecord contains parentNode: Uint8Array, parentGeneration: bigint, generation: bigint, address: string and active: boolean. A stored record’s active flag alone does not establish current parent ownership, lifetime or namespace policy. Use current metadata and payment reads for live decisions. See subname examples. Supported resolution names have two or three labels. Parent registration/lifecycle operations and namespace inputs retain their original grammar. Child details() and identity() require Universal Lookup mode. They return CONFIG in direct mode because that path cannot provide complete child ownership metadata.

Display names

Method	Result
`reverse(namespace,address)`	Scoped verified account name or `null`
`primaryOf(address)`	Configured Primary answer or `null`
`reverseVerify(address,name)`	Scoped reverse comparison
`reverseLookup(address,namespaces?)`	Primary then ordered namespace probes
`reverseNames(address,namespaces?)`	Verified names among bounded namespace candidates
`batchReadLimit()`	Contract-advertised reverse batch limit, checked against the SDK maximum
`primaryBatchReadLimit()`	Contract-advertised Primary batch limit, checked independently
`primaryBatch(addresses)`	One bounded cross-namespace batch; `BatchNames`
`reverseBatch(namespace,addresses)`	One bounded namespace batch; `BatchNames`
`primaryNames(addresses)`	History helper for up to 256 identities; `ObservedIdentityName[]`
`reverseMany(namespace,addresses)`	Namespace history helper for up to 256 identities; `ObservedIdentityName[]`

Batch/history methods require universal mode. The SDK supports batch capabilities 1, 2 and 3 with their advertised limits; query both limit methods before forming batches. They accept G, C and complete M addresses. primaryNames (many addresses) differs from reverseNames (one address across namespace candidates). See history examples and resource handling. nameStatus returns state.kind as namespaceMissing, registrarMissing, unregistered, active, expired or suspended. Active, expired and suspended states include state.record with registrar, a hex node, holder, bigint generation and bigint expiresAt. The envelope’s ledger is a number and timestamp is bigint. Status does not establish payment readiness or claimability.

Profiles, discovery and helpers

Method	Result
`profile(name)`, `identity(name)`	Standard text fields and full identity aggregate
`namesOfPage(address,{cursor?,limit?})`	Verified holdings page, continuation, coverage and check counts
`namesOf(address)`	Compatibility holdings aggregate; throws when incomplete
`walletProfile(address)`	Primary, reverse, first holdings page and profile
`history(name)`	Bounded indexed informational history
`namehash(namespace)`, `node(name)`	`Promise<Uint8Array>` containing the 32 raw hash bytes; explicit hex conversion

Complete muxed-address identity

reverse, primaryOf, reverseVerify, reverseLookup, reverseNames and walletProfile accept a complete M address in universal mode. The deployed Lookup must report muxed_identity_version() == 1, as the current testnet deployment does. The SDK checks the Registry and capability versions before reading the exact base G and u64 ID. It never falls back to the G account, a memo or another ID. Direct mode rejects M identity reads with CONFIG. M Primary is stored in Lookup independently of the G/C primaryId. Holdings accept G/C only; walletProfile(M) returns both holdings: null and names: null. See elections and verification.

Payment types

type PaymentMemo =
  | { type: "none" }
  | { type: "id"; value: string }
  | { type: "text"; value: string }
  | { type: "hash"; value: string };
type PaymentDestination = { address: string; memo: PaymentMemo };

address must be a valid G, M or C address. A required memo needs G; M and C support none only. Preserve an M address’s embedded unsigned 64-bit ID.

Helper	Input and result
`encodeMuxedAddress(account, id)`	G account and canonical decimal-string u64 ID → complete M address
`decodeMuxedAddress(address)`	M address → `{ account, id }`, with an exact decimal-string ID

Neither helper converts a muxed ID into a memo. Other exports include payment validation/encoding helpers, LookupResult, NameMetadata, NamespaceMetadata and NamespacePolicy. See destination examples and payment constraints.

Failures

Branch on SoranError.code:

Code	Meaning
`INVALID_INPUT`	Invalid name, address or other caller input
`CONFIG`	Missing, incompatible or invalid configuration
`RPC`, `TIMEOUT`	A request failed or exceeded its wait bound
`SIMULATION`	The contract read was rejected
`ARCHIVED`	State requires restoration; it is not an absent record
`ABI`	The response does not match the expected interface
`PAYMENT_REQUIRED`	An address-only call would discard a required memo
`LEGACY_MEMO_UNKNOWN`	Legacy address data cannot establish memo requirements
`INCOMPLETE`	The bounded holdings aggregate cannot return a complete result
`CHAIN_DISABLED`	Namespace policy excludes the requested additional network
`UNSUPPORTED_NETWORK`	The requested network ID is outside the supported catalogue
`MULTICHAIN_UNSUPPORTED`	A checked implementation lacks the multichain interface
`SUBNAMES_UNSUPPORTED`	A checked implementation lacks the subname interface

Recognized top-level Lookup contract failures also carry contractCode and contractError. Unknown formats stay unclassified; nested diagnostic strings are not promoted to top-level errors. Use these typed fields instead of parsing messages. Primary/reverse null has the documented proof limitation. Lookup/version checks are not executable-code pins; see governance.

​Constructor

​Methods

​Payments and metadata

​Network addresses and subnames

​Display names

​Profiles, discovery and helpers

​Complete muxed-address identity

​Payment types

​Failures