# @bonfida/spl-name-service 中文文档

规范地址：https://npmcn.com/package/%40bonfida/spl-name-service/

版本：4\.0\.1
npm 元数据更新时间：2026-09-11T04:18:06.155Z
中文译文更新时间：2026-11-08T10:52:52.548Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bonfida/spl-name-service
原文对照：https://npmcn.com/package/%40bonfida/spl-name-service/?lang=original
项目主页：https://dev.sns.id/
源码仓库：https://github.com/SolanaNameService/sns-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，433 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：@solana/web3\.js ^1\.98\.2
- 首次发布：2021-05-05T09:57:19.241Z
- 最新版本发布：2026-08-03T16:29:16.604Z
- 近 30 天下载量：48318（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：192（近 12 个月 16 个）

## 中文简介

![SNS logo](https://www.sns.id/assets/logo/brand.svg)

## 安装

```sh
npm install @bonfida/spl-name-service
```

也可以使用：`pnpm add @bonfida/spl-name-service`、`yarn add @bonfida/spl-name-service`、`bun add @bonfida/spl-name-service`

## README

![SNS logo](https://www.sns.id/assets/logo/brand.svg)

# SNS Java 脚本 SDK

[![npm](https://img.shields.io/npm/v/@bonfida%2Fspl-name-service)](https://www.npmjs.com/package/@bonfida/spl-name-service) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40bonfida/LICENSE)

JavaScript SDK 用于解决索拉纳名称服务(SNS)域,读取记录和所有权数据,并构建 SNS 交易指令 `@solana/web3.js` 1.x (中文(简体) ).

> **搬去V3吗?** 此发布并非完全后向兼容 。 评议 [更改日志](https://npmcn.com/package/%40bonfida/spl-name-service/CHANGELOG.md) 用来打破变化和移民笔记.

## 安装

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

SDK 对等者依赖 `@solana/web3.js` `^1.98.2`为RPC业务提供网络3.js连接。 虽然Node.js是主测试环境,但浏览器应用程序通过相容的捆绑器得到充分支持.

读取APIs获取并解码账户数据. 变异绑定返回 `TransactionInstruction`, (中文(简体) ), `Promise<TransactionInstruction>`,或 `Promise<TransactionInstruction[]>`。将返回的指令添加到交易中,设置其付费人和最近的blockhash,收集账户meta所需的签名,并通过您的应用程序提交交易.

### 子路径导入

虽然根入点仍然可用,但应用程序也可以使用子路径导入:

```ts
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";
```

支持的子路径是 `address`, (中文(简体) ), `bindings`, (中文(简体) ), `constants`, (中文(简体) ), `domain`, (中文(简体) ), `errors`, (中文(简体) ), `instructions`, (中文(简体) ), `nft`, (中文(简体) ), `record`, (中文(简体) ), `states`, (中文(简体) ), `twitter`, (中文(简体) ), `types`,以及 `utils`。 。 。 .

## 快速启动

### 解决域

```ts
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());
```

### 获取主域

```ts
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);
```

### 列出所有者的域

```ts
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`));
```

## 域输入 决议

使用每个 API 所需的表单, 而不是将名称自己正常化 :

| API 家庭 | 所需投入 | 范围 |
| --- | --- | --- |
| 域解析为 `resolve` 财务报告和审定财务报表 `safeResolve` | 完整后缀名称, 例如 `mydomain.sns` 或者说 `mydomain.sol` | `.sns` 财务报告和审定财务报表 `.sol` 域 |
| 顶级写法, 如注册、 传输、 燃烧和背景变化 | 小写 `mydomain.sns` | 仅顶级域; 子域不被接受 |
| 记录读取和写入 | 小写 `mydomain.sns` 或者说 `sub.mydomain.sns` | 顶级域或一级子域 |
| 子域创建 | 小写 `sub.mydomain.sns` | 一级子域 |
| 衍生和原始名称账户助手 | TLD 三角或原始输入, 例如 `mydomain` 或者说 `sub.mydomain` | 遵守每个低级助手的账户格式合同 |

## API 参考

### 决议

-   **`resolve`** - 决心 `.sns` 通过SNS-IP 5所有权优先和 `.sol` 通过其犬科SRS记录.
    
    ```ts
    resolve(connection: Connection, domain: string, config?: ResolveConfig): Promise<PublicKey>
    ```
    
-   **`safeResolve`** 接下来 `resolve`,但对于带有 `.sol` 后缀,它也会解决相应的 `.sns` 域并丢出 `SnsSolResolutionMismatchError` 如果目标不同.
    
    ```ts
    safeResolve(connection: Connection, domain: string, config?: ResolveConfig): Promise<PublicKey>
    ```
    

### 记录读取和验证

-   **`getRecord`** ——取出并核实一V2记录.
    
    ```ts
    getRecord(connection: Connection, domain: string, record: Record, options?: { deserialize?: boolean }): Promise<RecordResult>
    ```
    
-   **`getMultipleRecords`** ——返回结果为输入顺序;缺失的记录账户为 `undefined` 在相应的索引中.
    
    ```ts
    getMultipleRecords(connection: Connection, domain: string, records: Record[], options?: { deserialize?: boolean }): Promise<(RecordResult | undefined)[]>
    ```
    

下列独立助手并非来自 `RecordResult`数字 :

-   **`getRecordV1Key`** 编号 : **`getRecordV2Key`** ——从 TLD- trimmed 域中获取记录账户密钥, 如 `mydomain`。 。 。 .
    
    ```ts
    getRecordV1Key(domain: string, record: Record): PublicKey
    getRecordV2Key(domain: string, record: Record): PublicKey
    ```
    
-   **`serializeRecordContent`** 编号 : **`deserializeRecordContent`** ——编码存储内容,或解码存储内容.
    
    ```ts
    serializeRecordContent(content: string, record: Record): Buffer
    deserializeRecordContent(content: Buffer, record: Record): string
    ```
    
-   **`verifyStaleness`** ——独立取取并检查V2记录的沉滞性验证.
    
    ```ts
    verifyStaleness(connection: Connection, record: Record, domain: string): Promise<boolean>
    ```
    
-   **`verifyRightOfAssociation`** ——独立取取并检查V2唱片的关联权验证.
    
    ```ts
    verifyRightOfAssociation(connection: Connection, record: Record, domain: string, verifier?: Buffer): Promise<boolean>
    ```
    

### 记录写入

同步返回一个函数 `TransactionInstruction`数字 :

-   **`createRecord`**
    
    ```ts
    createRecord(domain: string, record: Record, content: string, owner: PublicKey, payer: PublicKey): TransactionInstruction
    ```
    
-   **`updateRecord`**
    
    ```ts
    updateRecord(domain: string, record: Record, content: string, owner: PublicKey, payer: PublicKey): TransactionInstruction
    ```
    
-   **`deleteRecord`**
    
    ```ts
    deleteRecord(domain: string, record: Record, owner: PublicKey, payer: PublicKey): TransactionInstruction
    ```
    
-   **`setRecordStalenessVerifier`**
    
    ```ts
    setRecordStalenessVerifier(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
    ```
    
-   **`setRecordRoaVerifier`**
    
    ```ts
    setRecordRoaVerifier(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
    ```
    
-   **`validateRecordRoa`**
    
    ```ts
    validateRecordRoa(domain: string, record: Record, owner: PublicKey, payer: PublicKey, verifier: PublicKey): TransactionInstruction
    ```
    
-   **`validateRecordRoaEthereum`** —— 说 `signature` 是 64 字节,并且 `expectedPubkey` 是一个20字节的Ethereum地址.
    
    ```ts
    validateRecordRoaEthereum(domain: string, record: Record, owner: PublicKey, payer: PublicKey, signature: Buffer, expectedPubkey: Buffer): TransactionInstruction
    ```
    

### 登记和生命周期

登记仅限于小写顶层 `.sns` 名称。 返回形状因操作而异:

-   **`registerDomain`** ——返回注册指令,并可能预留"一权委托人"关联子账户指令. 选中的薄荷必须有配置的 Pyth 价格种子 .
    
    ```ts
    registerDomain(domain: string, space: number, buyer: PublicKey, buyerTokenAccount: PublicKey, mint?: PublicKey, referrerKey?: PublicKey): Promise<TransactionInstruction[]>
    ```
    
-   **`registerDomainWithNft`** ——返回一"狼-NFT"注册指令. 衍生 `nameAccount` 财务报告和审定财务报表 `reverseLookupAccount` 在召唤之前.
    
    ```ts
    registerDomainWithNft(domain: string, space: number, nameAccount: PublicKey, reverseLookupAccount: PublicKey, buyer: PublicKey, nftSource: PublicKey, nftMint: PublicKey): TransactionInstruction
    ```
    
-   **`transferDomain`** ——取回当前所有者并返回一个传输指令.
    
    ```ts
    transferDomain(connection: Connection, domain: string, newOwner: PublicKey): Promise<TransactionInstruction>
    ```
    
-   **`burnDomain`** 返回一个燃烧指令; `target` 接受回收的灯塔.
    
    ```ts
    burnDomain(domain: string, owner: PublicKey, target: PublicKey): TransactionInstruction
    ```
    
-   **`setPrimaryDomain`** – 返回一个已生成域账户的指令 .
    
    ```ts
    setPrimaryDomain(connection: Connection, nameAccount: PublicKey, owner: PublicKey): Promise<TransactionInstruction>
    ```
    
-   **`setBackground`** ——返回设置已发布的自定义背景所需的指令.
    
    ```ts
    setBackground(connection: Connection, domain: string, bg: CustomBg, owner: PublicKey): Promise<TransactionInstruction[]>
    ```
    

### 子域

-   **`createSubdomain`** ——返回名称账户创建指令,并在没有反向账户时,返回反向查看指令. `subdomain` 必须是小写单关 `.sns` 子域名.
    
    ```ts
    createSubdomain(connection: Connection, subdomain: string, owner: PublicKey, space?: number, feePayer?: PublicKey): Promise<TransactionInstruction[]>
    ```
    
-   **`transferSubdomain`** ——返回一个传输指令. 何时 `owner` 省略,该函数检索当前所有者;设置 `isParentOwnerSigner` 当母所有者授权转让时.
    
    ```ts
    transferSubdomain(connection: Connection, subdomain: string, newOwner: PublicKey, isParentOwnerSigner?: boolean, owner?: PublicKey): Promise<TransactionInstruction>
    ```
    
-   **`findSubdomains`** ——返回父名账户密钥的倒解子域标签.
    
    ```ts
    findSubdomains(connection: Connection, parentKey: PublicKey): Promise<string[]>
    ```
    

### 所有权和反向查询

-   **`getSnsDomainKeysForOwner`** ——返回直接注册拥有的顶级名账户密钥.
    
    ```ts
    getSnsDomainKeysForOwner(connection: Connection, wallet: PublicKey): Promise<PublicKey[]>
    ```
    
-   **`getSnsDomainsForOwner`** ——在那些直接拥有的密钥中添加了TLD-无反向名称;它排除了象征性域,子域,以及没有反向数据的条目.
    
    ```ts
    getSnsDomainsForOwner(connection: Connection, wallet: PublicKey): Promise<{ domain: string; key: PublicKey }[]>
    ```
    
-   **`getSnsNftsForOwner`** ——以反向数据返回已符号化域.
    
    ```ts
    getSnsNftsForOwner(connection: Connection, owner: PublicKey): Promise<{ domain: string; key: PublicKey; mint: PublicKey }[]>
    ```
    
-   **`getSolDomainKeysForOwner`** ——返回未过期、直接拥有钱包的顶级记录公钥 `.sol` 记录。 记录不包括在内.
    
    ```ts
    getSolDomainKeysForOwner(connection: Connection, wallet: PublicKey): Promise<PublicKey[]>
    ```
    
-   **`getSolDomainsForOwner`** ——返回未过期、直接拥有钱包的顶层 `.sol` 记录。 已返回 `domain` 值为 TLD- trimmed; 符号化域、 子域和错误的单个记录除外.
    
    ```ts
    getSolDomainsForOwner(connection: Connection, wallet: PublicKey): Promise<{ domain: string; key: PublicKey }[]>
    ```
    
-   **`getSolNftsForOwner`** - 返回未过期的托肯-2022 `.sol` 区域。 结果包括TLD-trimmed名称,SRS记录密钥,和象征性薄荷.
    
    ```ts
    getSolNftsForOwner(connection: Connection, owner: PublicKey): Promise<{ domain: string; key: PublicKey; mint: PublicKey }[]>
    ```
    
-   **`getAllSnsDomains`** ——返回原始的顶级注册程序账户,其 `account.data` 切入32字节的登记所有者字段.
    
    ```ts
    getAllSnsDomains(connection: Connection): Promise<GetProgramAccountsResponse>
    ```
    
-   **`getAllSolDomains`** ——返回原始的顶级SRS程序账户,包括过期记录,其 `account.data` 切入32字节的SRS所有者字段。 拥有者字节可以代表钱包地址或Token-2022 mint.
    
    ```ts
    getAllSolDomains(connection: Connection): Promise<GetProgramAccountsResponse>
    ```
    
-   **`getPrimaryDomain`** ——返回主名账户密钥,无 TLD 倒取名,并 stale 状态.
    
    ```ts
    getPrimaryDomain(connection: Connection, owner: PublicKey): Promise<{ domain: PublicKey; reverse: string; stale: boolean }>
    ```
    
-   **`getMultiplePrimaryDomains`** ——按输入顺序返回无 TLD 主名; 缺少条目为 `undefined`。 。 。 .
    
    ```ts
    getMultiplePrimaryDomains(connection: Connection, wallets: PublicKey[]): Promise<(string | undefined)[]>
    ```
    
-   **`reverseLookup`** ——返回一个没有 TLD 的倒置名称 .
    
    ```ts
    reverseLookup(connection: Connection, nameAccount: PublicKey, parent?: PublicKey): Promise<string>
    ```
    
-   **`reverseLookupBatch`** ——按输入顺序返回无 TLD 名称;缺少倒转记录为 `undefined`。 。 。 .
    
    ```ts
    reverseLookupBatch(connection: Connection, nameAccounts: PublicKey[]): Promise<(string | undefined)[]>
    ```
    

### 高级 API

对于账户层面的整合,根导出还包括衍生物和原始名称注册帮助者,例如: `getSnsDomainKeySync`, (中文(简体) ), `getSolDomainKeySync`, (中文(简体) ), `getReverseKeySync`, (中文(简体) ), `getReverseKeyFromDomainKey`, (中文(简体) ), `getHashedNameSync`, (中文(简体) ), `getNameAccountKeySync`, (中文(简体) ), `createNameRegistry`, (中文(简体) ), `updateNameRegistry`, (中文(简体) ), `deleteNameRegistry`,以及 `createReverse`。 。 。 .

NFT帮助者和状态类包括域-薄荷/所有者/记录检索, `NameRegistryState`, (中文(简体) ), `PrimaryDomain`,和NFT国家出口. `CustomBg`, (中文(简体) ), `getCustomBgKeys`,以及 `setBackground` 支持已发布的自定义背景 。 这个 `devnet` export 提供了 devnet 特定绑定和常数。 低级教学班和原始状态解码器也出口用于专业集成.

遗产 Twitter注册API仍被出口用于高级相容性. 它们不属于所建议的域解析或登记路径.

## 证件和移徙

-   [开发者文档](https://dev.sns.id/)
-   [v4 迁移指南](https://npmcn.com/package/%40bonfida/spl-name-service/CHANGELOG.md)
-   [SNS 反应 v4 读取](https://npmcn.com/package/%40bonfida/react/README.md)
-   [SDK 单列波概览](https://npmcn.com/package/%40bonfida/README.md)
-   [SNS 指南](https://guide.sns.id/)

## 许可证

本项目可在 [MIT 许可证](https://npmcn.com/package/%40bonfida/LICENSE)。 。 。 .

## 常见问题

### 如何安装 @bonfida/spl-name-service？

在项目目录运行 npm install @bonfida/spl-name-service，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@solana/web3\.js（^1\.98\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bonfida/spl-name-service 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bonfida/spl-name-service 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bonfida/spl-name-service 可以商用吗？

@bonfida/spl-name-service 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bonfida/spl-name-service 的下载量有多少？

根据 npm 官方下载统计，@bonfida/spl-name-service 在 2026/10/09 – 2026/11/07 这 30 天内被下载 48,318 次，日均约 1,611 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bonfida/spl-name-service 还在维护吗？

最新版本 4\.0\.1 发布于 2026/08/04（3 个月前）；至今共发布 192 个版本，其中过去 12 个月发布了 16 个；首次发布于 2021/05/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。