# @bsv/overlay-discovery-services 中文文档

规范地址：https://npmcn.com/package/%40bsv/overlay-discovery-services/

版本：2\.2\.9
npm 元数据更新时间：2026-10-28T01:32:49.902Z
中文译文更新时间：2026-11-08T17:28:21.184Z
软件包许可：SEE LICENSE IN LICENSE\.txt

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

原始 npm 页面：https://www.npmjs.com/package/%40bsv/overlay-discovery-services
原文对照：https://npmcn.com/package/%40bsv/overlay-discovery-services/?lang=original
项目主页：https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-discovery-services#readme
源码仓库：https://github.com/bsv-blockchain/ts-stack

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

- 包体积（解压后）：407 kB，166 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：@bsv/sdk ^2\.4\.0 \|\| ^3\.0\.0 \|\| ^4\.0\.1
- 首次发布：2024-11-30T03:23:02.830Z
- 最新版本发布：2026-10-28T01:32:49.456Z
- 近 30 天下载量：8465（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 15 个）

## 中文简介

BSV 块链重叠服务引擎

## 安装

```sh
npm install @bsv/overlay-discovery-services
```

也可以使用：`pnpm add @bsv/overlay-discovery-services`、`yarn add @bsv/overlay-discovery-services`、`bun add @bsv/overlay-discovery-services`

## README

# @bsv/重叠-发现-服务

补丁候选人 `2.2.9` 更新打包的第一当事方运行时间或开发依赖范围。 此只使用元数据补丁保存了公共API,对等范围,有线格式和默认. 不需要额外的消费者或数据迁移;早期的迁移指南仍然适用.

[![npm version](https://img.shields.io/npm/v/@bsv/overlay-discovery-services)](https://www.npmjs.com/package/@bsv/overlay-discovery-services) [![npm downloads](https://img.shields.io/npm/dm/@bsv/overlay-discovery-services)](https://www.npmjs.com/package/@bsv/overlay-discovery-services)

BSV覆盖网络的发现层. 执行 **船舶** (服务主机互联协议)和 **苏丹解放军** (Service Lookup Protocol)——让覆盖节点的两种协议广告它们所主控的主题和它们所暴露的取景服务,因此同行可以在没有中央注册的情况下找到对方.

这个包裹船:

-   `SHIPTopicManager` 编号 : `SHIPLookupService` ——招生和查询SHIP广告信使
-   `SLAPTopicManager` 编号 : `SLAPLookupService` ——招生和查询SLAP广告代币
-   `WalletAdvertiser` - 一个统包 `Advertiser` 使用 BRC- 100 钱包创建、查找和撤销 Ship/ SLAP 广告的操作

MongoDB的发现页标命令等同创建时间戳 `_id`,为引擎溢出探测器保留稳定的限定页.

发行候选人将包装的重叠依赖推进到支持可选保留录取历史. 这个软件包保留了它现有的行为,不能自动保留历史. 不需要消费者或数据库迁移.

## 安装

```bash
npm install @bsv/overlay-discovery-services
```

要求节点.js 22或更新. 安装 `@bsv/sdk` 与此软件包并排为 满足同伴的依赖。 覆盖引擎、钱包工具箱客户端和 MongoDB驱动程序为直接运行时间依赖.

## 快速启动( 广告)

```ts
import { WalletAdvertiser } from '@bsv/overlay-discovery-services'

const advertiser = new WalletAdvertiser(
  'main', // chain
  privateKeyHex, // dedicated root signing key; keep secret
  'https://my-storage.example.com', // wallet storage URL
  'https://my-overlay.example.com' // advertisable URI clients should connect to
)
await advertiser.init()

// Advertise that we host the tm_identity topic and ls_identity lookup service.
await advertiser.createAdvertisements([
  { protocol: 'SHIP', topicOrServiceName: 'tm_identity' },
  { protocol: 'SLAP', topicOrServiceName: 'ls_identity' }
])

// Recover this identity's current advertisements for reconciliation/revocation.
const mine = await advertiser.findAllAdvertisements('SHIP')
```

这个 `tm_identity` 编号 : `ls_identity` 成对发现归属身份证书. 广告只当节点已经主机了该话题和查询服务时. 发现确定候选终点;应用程序必须分别验证 证书签名并应用其选定的认证人信任政策。 身份钥匙 `did:key` 解析是决定性的,不使用覆盖查询.

为TerraTestNet,通过 `ttn` 作为链和 TTN 钱包存储 URL。 除非我们.. 被覆盖 `lookupResolverConfig`广告商使用孤立的 `teratestnet` 解析器预设和 TTN Arcade 支持的钱包服务.

## 快速启动( 覆盖操作员)

在您的覆盖节点上挂载 SHIP/ SLAP 主题管理器和查询服务, 以便同行可以通过您的端点发布和发现广告 :

```ts
import {
  SHIPLookupService,
  SHIPStorage,
  SHIPTopicManager,
  SLAPLookupService,
  SLAPStorage,
  SLAPTopicManager
} from '@bsv/overlay-discovery-services'

const topicManagers = {
  tm_ship: new SHIPTopicManager(),
  tm_slap: new SLAPTopicManager()
}

const lookupServices = {
  ls_ship: new SHIPLookupService(new SHIPStorage(db)),
  ls_slap: new SLAPLookupService(new SLAPStorage(db))
}
```

把这些地图传给 `Engine`,或用您所选的 重叠服务包装.

## 使用大小写

### 运行可发现的上覆服务

主办一个专题(例如:. `tm_identity`),并发布SPHE广告,这样其他节点会向您传递相关的交易.

### 为特定主题查找端点

```ts
const hosts = await engine.lookup({
  service: 'ls_ship',
  query: { topics: ['tm_identity'], limit: 100 }
})
```

`WalletAdvertiser.findAllAdvertisements()` 只故意返回 该广告主拥有的加密认证广告 身份证明 使用SHIP/SLAP查询服务来发现其他身份.

### 下线服务

```ts
const mine = await advertiser.findAllAdvertisements('SLAP')
await advertiser.revokeAdvertisements(mine.filter(a => a.topicOrService === 'ls_identity'))
```

## API 密码

| 导出 | 目的 |
| --- | --- |
| `SHIPTopicManager` | 将造型精良的船舶和航天公司广告产品告知 `tm_ship` 专题 |
| `SLAPTopicManager` | 将配制精良的 SLAP 广告产品告知 `tm_slap` 专题 |
| `SHIPLookupService` 编号 : `SLAPLookupService` | 索引和答复发现查询 |
| `SHIPStorage` 编号 : `SLAPStorage` | MongoDB支持的发现记录 |
| `WalletAdvertiser` | 高级广告/发现/撤销API,由钱包支持 |
| `isAdvertisableURI` 编号 : `isValidTopicOrServiceName` | 验证助手 |

## 运行时间和安全

该软件包公布了与无害环境管理和共同JS切入点相匹配的软件包 条件特定的类型脚本声明. 广告名称,签名, URIs, Canonic PushDrop 信封, 和身份到锁键链接是 招生前审定. 查询对象只必须包含有文件记录 plain-data 字段. 低于最多1 000个记录的结果; `limit` 接受 0至1,000的整数, `skip` 被绑定,并且 `limit: 0` 返回一个 空页。 刻意地贴上标签 而不是依赖一个没有约束的 `findAll` 反应.

`WalletAdvertiser` 保留其构造器 `privateKey` 作为公共案例 属性仅用于后向兼容。 这个值是根钱包 暗号 使用专用密钥, 将实例保存在一个信任的进程内 永远不要日志、序列化、返回、检查或传递给插件或未信任的代码. 创建和取消路径绑定请求的输入/输出以及钱包的最终 签名交易; 取消对每个一佐佐佐领的认证, 它的拥有者,元数据, 和精确的出处之前, 要求钱包签名.

`parseAdvertisement()` 仅因公众而验证犬科结构 界面是同步的。 它不能确定签名的真实性。 偏爱 专题管理录取决定或 `WalletAdvertiser`已经核实的发现和 撤销担保决定的方法.

发现广告包含公共连接端点. 处理已发现 主机作为不信任的网络输入:保留 TLS 验证,应用请求超时, 不转发证书以发现来源,并验证答复。 这个 HTTP 服务,主机为 Ship 和 SLAP , 通常仍可任意获取 浏览器和移动源; 仅在一个 部署有一套真正关闭的呼叫器 CORS 不替换协议或 行政认证.

## 发展

从寄存器根 :

```bash
pnpm --filter @bsv/overlay-discovery-services format:check
pnpm --filter @bsv/overlay-discovery-services lint
pnpm --filter @bsv/overlay-discovery-services typecheck
pnpm --filter @bsv/overlay-discovery-services test
pnpm --filter @bsv/overlay-discovery-services test:coverage
pnpm --filter @bsv/overlay-discovery-services pack:check
```

包检查核实公布的柏油球、申报和清洁无害环境管理 和普通JS消费者.

## 许可证

当前 TS Stack 更改根据 Open BSV 许可证版本 6 获得许可; 参见 [LICENSE.txt (英语)](https://npmcn.com/package/%40bsv/overlay-discovery-services/LICENSE.txt)。该软件包还保留了统一前代码 在开放BSV许可证版本4下. 补给者必须保留 [第三次议会 NoTICES.md](https://npmcn.com/package/%40bsv/overlay-discovery-services/THIRD_PARTY_NOTICES.md) 和适用的文本在 [`LICENSES/`](https://npmcn.com/package/%40bsv/overlay-discovery-services/LICENSES/)。 。 。 .

## SDK4 热补丁对等要求

SDK4 对等替代开始于 `@bsv/sdk ^4.0.1`,恢复数字 钱包结果和遗留线条相容性。 现有的SDK2/3替代品和 下限不变。 SDK4 用户应安装 4. 0.1 个热补丁; 不 需要应用程序-wallet线或数据迁移.

## 常见问题

### @bsv/overlay-discovery-services 是什么？

BSV 块链重叠服务引擎

### 如何安装 @bsv/overlay-discovery-services？

在项目目录运行 npm install @bsv/overlay-discovery-services，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bsv/sdk（^2\.4\.0 \|\| ^3\.0\.0 \|\| ^4\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bsv/overlay-discovery-services 支持 TypeScript 吗？

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

### @bsv/overlay-discovery-services 支持 ESM 还是 CommonJS？

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

### @bsv/overlay-discovery-services 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bsv/overlay-discovery-services 可以商用吗？

@bsv/overlay-discovery-services 使用 SEE LICENSE IN LICENSE\.txt 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @bsv/overlay-discovery-services 的下载量有多少？

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

### @bsv/overlay-discovery-services 还在维护吗？

最新版本 2\.2\.9 发布于 2026/10/28（11 天前）；至今共发布 37 个版本，其中过去 12 个月发布了 15 个；首次发布于 2024/11/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。