SNS JavaScript SDK

JavaScript SDK for resolving Solana Name Service (SNS) domains, reading records and ownership data, and constructing SNS transaction instructions with @solana/web3.js 1.x.

Migrating from v3? This release is not fully backward compatible. Review the changelog for breaking changes and migration notes.

Installation

npm install @bonfida/spl-name-service @solana/web3.js

The SDK has a peer dependency on @solana/web3.js ^1.98.2. Supply a web3.js Connection for RPC operations. While Node.js is the primary tested environment, browser applications are fully supported via compatible bundlers.

Read APIs fetch and decode account data. Mutation bindings return TransactionInstruction, Promise<TransactionInstruction>, or Promise<TransactionInstruction[]>. Add the returned instruction(s) to a transaction, set its fee payer and recent blockhash, collect the signatures required by its account metas, and submit that transaction through your application.

Subpath Imports

While the root entry point remains available, applications can also use subpath imports:

import { getPrimaryDomain } from "@bonfida/spl-name-service/address";
import { resolve, safeResolve } from "@bonfida/spl-name-service/domain";
import { getMultipleRecords, Record } from "@bonfida/spl-name-service/record";

Supported subpaths are address, bindings, constants, domain, errors, instructions, nft, record, states, twitter, types, and utils.

Quick Start

Resolve A Domain

import { Connection } from "@solana/web3.js";
import { resolve } from "@bonfida/spl-name-service/domain";

const connection = new Connection("https://your-rpc-endpoint.example");
const owner = await resolve(connection, "mydomain.sns"); // Or use `safeResolve`.

console.log(owner.toBase58());

Get A Primary Domain

import { Connection, PublicKey } from "@solana/web3.js";
import { getPrimaryDomain } from "@bonfida/spl-name-service/address";

const connection = new Connection("https://your-rpc-endpoint.example");
const wallet = new PublicKey("<WALLET_ADDRESS>");
const primaryDomain = await getPrimaryDomain(connection, wallet);

console.log(`${primaryDomain.reverse}.sns`, primaryDomain.stale);

List Domains For An Owner

import { Connection, PublicKey } from "@solana/web3.js";
import {
  getSnsDomainsForOwner,
  getSnsNftsForOwner,
  getSolDomainsForOwner,
  getSolNftsForOwner,
} from "@bonfida/spl-name-service/address";

const connection = new Connection("https://your-rpc-endpoint.example");
const wallet = new PublicKey("<WALLET_ADDRESS>");

const snsDomains = await getSnsDomainsForOwner(connection, wallet);
const snsNfts = await getSnsNftsForOwner(connection, wallet);
const solDomains = await getSolDomainsForOwner(connection, wallet);
const solNfts = await getSolNftsForOwner(connection, wallet);

console.log(snsDomains.map(({ domain }) => `${domain}.sns`));
console.log(snsNfts.map(({ domain }) => `${domain}.sns`));
console.log(solDomains.map(({ domain }) => `${domain}.sol`));
console.log(solNfts.map(({ domain }) => `${domain}.sol`));

Domain Inputs And Resolution

Use the form required by each API rather than normalizing names yourself:

API Reference

Resolution

• resolve — resolves .sns through SNS-IP 5 ownership precedence and .sol through its canonical SRS record.

  resolve(connection: Connection, domain: string, config?: ResolveConfig): Promise<PublicKey>
  

• safeResolve — follows resolve, but for domains with a .sol suffix, it also resolves the corresponding .sns domain and throws SnsSolResolutionMismatchError if the targets differ.

  safeResolve(connection: Connection, domain: string, config?: ResolveConfig): Promise<PublicKey>
  

Record Reads And Validation

• getRecord — fetches and verifies one V2 record.

  getRecord(connection: Connection, domain: string, record: Record, options?: { deserialize?: boolean }): Promise<RecordResult>
  

• getMultipleRecords — returns results in input order; a missing record account is undefined at its corresponding index.

  getMultipleRecords(connection: Connection, domain: string, records: Record[], options?: { deserialize?: boolean }): Promise<(RecordResult | undefined)[]>
  

The following standalone helpers do not come from RecordResult:

• getRecordV1Key / getRecordV2Key — derive record account keys from a TLD-trimmed domain such as mydomain.

  getRecordV1Key(domain: string, record: Record): PublicKey
  getRecordV2Key(domain: string, record: Record): PublicKey
  

• serializeRecordContent / deserializeRecordContent — encode content for storage, or decode stored content.

  serializeRecordContent(content: string, record: Record): Buffer
  deserializeRecordContent(content: Buffer, record: Record): string
  

• verifyStaleness — independently fetches and checks a V2 record's staleness validation.

  verifyStaleness(connection: Connection, record: Record, domain: string): Promise<boolean>
  

• verifyRightOfAssociation — independently fetches and checks a V2 record's right-of-association validation.

  verifyRightOfAssociation(connection: Connection, record: Record, domain: string, verifier?: Buffer): Promise<boolean>
  

Record Writes

Each function below synchronously returns one TransactionInstruction:

• createRecord

  createRecord(domain: string, record: Record, content: string, owner: PublicKey, payer: PublicKey): TransactionInstruction
  

• updateRecord

  updateRecord(domain: string, record: Record, content: string, owner: PublicKey, payer: PublicKey): TransactionInstruction
  

• deleteRecord

  deleteRecord(domain: string, record: Record, owner: PublicKey, payer: PublicKey): TransactionInstruction
  

• setRecordStalenessVerifier

  setRecordStalenessVerifier(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
  

• setRecordRoaVerifier

  setRecordRoaVerifier(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
  

• validateRecordRoa

  validateRecordRoa(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
  

• validateRecordRoaEthereum — signature is 64 bytes and expectedPubkey is a 20-byte Ethereum address.

  validateRecordRoaEthereum(domain: string, record: Record, owner: PublicKey, payer: PublicKey, signature: Buffer, expectedPubkey: Buffer): TransactionInstruction
  

Registration And Lifecycle

Registration is limited to a lowercase top-level .sns name. Return shapes differ by operation:

• registerDomain — returns the registration instruction and may prepend an idempotent referrer associated-token-account instruction. The selected mint must have a configured Pyth price feed.

  registerDomain(domain: string, space: number, buyer: PublicKey, buyerTokenAccount: PublicKey, mint?: PublicKey, referrerKey?: PublicKey): Promise<TransactionInstruction[]>
  

• registerDomainWithNft — returns one Wolves-NFT registration instruction. Derive nameAccount and reverseLookupAccount before calling it.

  registerDomainWithNft(domain: string, space: number, nameAccount: PublicKey, reverseLookupAccount: PublicKey, buyer: PublicKey, nftSource: PublicKey, nftMint: PublicKey): TransactionInstruction
  

• transferDomain — retrieves the current owner and returns one transfer instruction.

  transferDomain(connection: Connection, domain: string, newOwner: PublicKey): Promise<TransactionInstruction>
  

• burnDomain — returns one burn instruction; target receives reclaimed lamports.

  burnDomain(domain: string, owner: PublicKey, target: PublicKey): TransactionInstruction
  

• setPrimaryDomain — returns one instruction for an already derived domain account.

  setPrimaryDomain(connection: Connection, nameAccount: PublicKey, owner: PublicKey): Promise<TransactionInstruction>
  

• setBackground — returns the instructions required to set an issued custom background.

  setBackground(connection: Connection, domain: string, bg: CustomBg, owner: PublicKey): Promise<TransactionInstruction[]>
  

Subdomains

• createSubdomain — returns the name-account creation instruction and, when the reverse account is absent, a reverse-lookup instruction. subdomain must be a lowercase one-level .sns subdomain.

  createSubdomain(connection: Connection, subdomain: string, owner: PublicKey, space?: number, feePayer?: PublicKey): Promise<TransactionInstruction[]>
  

• transferSubdomain — returns one transfer instruction. When owner is omitted, the function retrieves the current owner; set isParentOwnerSigner when the parent owner authorizes the transfer.

  transferSubdomain(connection: Connection, subdomain: string, newOwner: PublicKey, isParentOwnerSigner?: boolean, owner?: PublicKey): Promise<TransactionInstruction>
  

• findSubdomains — returns reverse-resolved subdomain labels for a parent name-account key.

  findSubdomains(connection: Connection, parentKey: PublicKey): Promise<string[]>
  

Ownership And Reverse Lookup

• getSnsDomainKeysForOwner — returns directly registry-owned top-level name-account keys.

  getSnsDomainKeysForOwner(connection: Connection, wallet: PublicKey): Promise<PublicKey[]>
  

• getSnsDomainsForOwner — adds TLD-less reverse names to those directly owned keys; it excludes tokenized domains, subdomains, and entries without reverse data.

  getSnsDomainsForOwner(connection: Connection, wallet: PublicKey): Promise<{ domain: string; key: PublicKey }[]>
  

• getSnsNftsForOwner — returns tokenized domains with reverse data.

  getSnsNftsForOwner(connection: Connection, owner: PublicKey): Promise<{ domain: string; key: PublicKey; mint: PublicKey }[]>
  

• getSolDomainKeysForOwner — returns the record public keys for non-expired, directly wallet-owned top-level .sol records. Tokenized records are excluded.

  getSolDomainKeysForOwner(connection: Connection, wallet: PublicKey): Promise<PublicKey[]>
  

• getSolDomainsForOwner — returns non-expired, directly wallet-owned top-level .sol records. Returned domain values are TLD-trimmed; tokenized domains, subdomains, and malformed individual records are excluded.

  getSolDomainsForOwner(connection: Connection, wallet: PublicKey): Promise<{ domain: string; key: PublicKey }[]>
  

• getSolNftsForOwner — returns non-expired Token-2022 tokenized .sol domains. Results include the TLD-trimmed name, SRS record key, and token mint.

  getSolNftsForOwner(connection: Connection, owner: PublicKey): Promise<{ domain: string; key: PublicKey; mint: PublicKey }[]>
  

• getAllSnsDomains — returns raw top-level registry program accounts whose account.data is sliced to the 32-byte registry-owner field.

  getAllSnsDomains(connection: Connection): Promise<GetProgramAccountsResponse>
  

• getAllSolDomains — returns raw top-level SRS program accounts, including expired records, whose account.data is sliced to the 32-byte SRS owner field. The owner bytes can represent either a wallet address or a Token-2022 mint.

  getAllSolDomains(connection: Connection): Promise<GetProgramAccountsResponse>
  

• getPrimaryDomain — returns the primary name-account key, TLD-less reverse name, and stale status.

  getPrimaryDomain(connection: Connection, owner: PublicKey): Promise<{ domain: PublicKey; reverse: string; stale: boolean }>
  

• getMultiplePrimaryDomains — returns TLD-less primary names in input order; missing entries are undefined.

  getMultiplePrimaryDomains(connection: Connection, wallets: PublicKey[]): Promise<(string | undefined)[]>
  

• reverseLookup — returns one TLD-less reverse name.

  reverseLookup(connection: Connection, nameAccount: PublicKey, parent?: PublicKey): Promise<string>
  

• reverseLookupBatch — returns TLD-less names in input order; missing reverse records are undefined.

  reverseLookupBatch(connection: Connection, nameAccounts: PublicKey[]): Promise<(string | undefined)[]>
  

Advanced APIs

For account-level integrations, the root export also includes derivation and raw name-registry helpers such as getSnsDomainKeySync, getSolDomainKeySync, getReverseKeySync, getReverseKeyFromDomainKey, getHashedNameSync, getNameAccountKeySync, createNameRegistry, updateNameRegistry, deleteNameRegistry, and createReverse.

NFT helpers and state classes include domain-mint/owner/record retrieval, NameRegistryState, PrimaryDomain, and NFT state exports. CustomBg, getCustomBgKeys, and setBackground support issued custom backgrounds. The devnet export provides devnet-specific bindings and constants. Low-level instruction classes and raw state decoders are also exported for specialized integrations.

Legacy Twitter registry APIs remain exported for advanced compatibility use. They are not part of the recommended domain-resolution or registration path.

Documentation And Migration

• Developer documentation
• v4 migration guide
• SNS React v4 README
• SDK monorepo overview
• SNS guide

License

This project is available under the MIT License.