# @debridge-finance/borderless-validation-sdk 中文文档

规范地址：https://npmcn.com/package/%40debridge-finance/borderless-validation-sdk/

版本：0\.6\.0
npm 元数据更新时间：2026-11-11T16:41:02.200Z
中文译文更新时间：2026-11-12T10:08:22.069Z
软件包许可：BUSL-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%40debridge-finance/borderless-validation-sdk
原文对照：https://npmcn.com/package/%40debridge-finance/borderless-validation-sdk/?lang=original
项目主页：https://github.com/debridge-finance/borderless-validation-sdk-ts#readme
源码仓库：https://github.com/debridge-finance/borderless-validation-sdk-ts

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

- 包体积（解压后）：3.1 MB，628 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^3\.0\.0 \|\| ^4\.0\.0，bs58 \>=5\.0\.0，viem \>=2\.0\.0，@solana/web3\.js \>=1\.90\.0
- 首次发布：2026-04-17T13:56:24.127Z
- 最新版本发布：2026-11-11T16:41:01.984Z
- 近 30 天下载量：2600（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

验证无边意图的 SDK API 响应

## 安装

```sh
npm install @debridge-finance/borderless-validation-sdk
```

也可以使用：`pnpm add @debridge-finance/borderless-validation-sdk`、`yarn add @debridge-finance/borderless-validation-sdk`、`bun add @debridge-finance/borderless-validation-sdk`

## README

# @debridge-finance/ 无边界验证- sdk

DeBridge 验证 SDK **无边际意图** API (英语:`POST /v1.0/bundle`答复.

## 目的

当用户向deBridge API提交捆绑请求时,响应包含预期用户会签名的交易和可签名的有效载荷(EIP-712消息,许可,索拉纳交易等).

**每个字段的用户标志都是潜在的攻击矢量.** 如果API被泄露(MITM,服务器错误,恶意重写),用户可以不知不觉地在耗尽资金的交易上签名.

这个SDK在签约前运行在客户端上. 它验证反应结构,并对照原始请求、协议变量和特定环境的白名单检查可标志的有效载荷.

### 减少威胁

-   **MITM攻击** 与API的终点相对.
-   **API 一侧的臭虫** 产生错误的反应.
-   **API 信任减少** ——客户不再需要接受API基于信仰的反应.
-   **回归安全网** 当测试新的API版本时.

## 安装

```bash
npm install @debridge-finance/borderless-validation-sdk
```

宣布的同伴依赖范围 :

-   `@solana/web3.js >= 1.90.0`
-   `bs58 >= 5.0.0`
-   `viem >= 2.0.0`
-   `zod ^3.0.0 || ^4.0.0`

## 基本用途

```ts
import {
    createValidator,
    Environment,
    ViolationCode,
} from "@debridge-finance/borderless-validation-sdk";

const validator = createValidator({ environment: Environment.Prod });

const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";

const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
}).then(res => res.json());

const result = validator.validate(url, request, response);

if (!result.ok) {
    if (result.violations.some(v => v.code === ViolationCode.HigherApiVersion)) {
        // Special case: the API response was produced for a newer validation
        // version than this SDK supports. The SDK cannot reliably validate it.
        // Decide in your app whether to block, warn, update the SDK, or use
        // another fallback flow.
        console.error("API validation version is newer than SDK support:", result.violations);
        return;
    }

    if (result.violations.some(v => v.code === ViolationCode.UnexpectedValidationError)) {
        // Special case: this indicates an internal Validation SDK error.
        // The client app must decide how to handle it: block signing, report
        // telemetry, retry after SDK update, or use another fallback flow.
        console.error("Validation SDK internal error:", result.violations);
        return;
    }

    console.error("Validation failed:", result.violations);
    // Do NOT let the user sign anything.
    return;
}

// Safe to proceed with signing.
```

### API 密码

```ts
createValidator(config: ValidatorConfig): Validator

type ValidatorConfig = {
    environment: Environment;
};

type Validator = {
    validate(url: string, request: object, response: object): ValidationResult;
};

type ValidationResult = {
    ok: boolean;             // true if no violations
    violations: Violation[]; // all issues found
};

type Violation = {
    code: ViolationCode;     // machine-readable identifier
    message: string;         // human-readable description
    path: string;            // JSON path of the offending field
    expected?: unknown;      // the value the validator expected (concrete, comparable to `actual`)
    actual?: unknown;        // the value found in the response (concrete, comparable to `expected`)
    details?: unknown;       // extra machine-readable context (e.g. caught error object)
};
```

`validator.validate()` **从不扔** - 每一个错误条件都报告为: `Violation`安全呼叫任何代码路径.

## UI团队整合指南

SDK是用来运行的 **介于** 接收 API 回复并提交用户签名。 把它接入接缝.

### 1\. 呼叫地点

```
┌───────────────┐     ┌─────────┐     ┌────────────────────┐     ┌───────────────┐
│ Build request │ ──▶ │ fetch() │ ──▶ │ validator.validate │ ──▶ │ Sign / submit │
└───────────────┘     └─────────┘     └────────────────────┘     └───────────────┘
                                              │
                                              ▼
                                     ok ? proceed : block
```

-   **在此之前 `validate`数字 :** 用户尚未看到或签署任何文件.
-   **之后 `validate`数字 :** 若为 `result.ok === false`, (中文(简体) ), **不转发任何可标志的有效载荷** (意向信息,许可,交易)到钱包. API 响应无法信任 .

### 2\. 选择环境

```ts
import { Environment } from "@debridge-finance/borderless-validation-sdk";
```

-   `Environment.Prod` ——无煤气特性的生产.
-   `Environment.Gasless` ——具有无气特性的生产.
-   `Environment.Dev` ——开发者环境(又名Stage).

通过同样的环境 您的应用程序已经配置 —— 不要让它成为用户选择 .

### 3\. 传递您拨打的确切的 URL

```ts
const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";
const response = await fetch(url, { ... });
const result = validator.validate(url, request, response);
```

这个 `url` 参数用于API兼容性和未来端点检查。 传出你交给的相同字符串 `fetch`;在发布中明确启用之前,不要依赖URL验证.

### 4\. 处理侵权行为

打开 `result.ok === false`数字 :

1.  **堵住签名流.** 不要显示钱包弹出或将任何待决 tx 写入状态 .
2.  **完整记录 `violations` 数组** 到错误报告系统(Sentry / Datadog /等)。 包含 `code`, (中文(简体) ), `path`, (中文(简体) ), `expected`, (中文(简体) ), `actual`, (中文(简体) ), `details`。 。 。 .
3.  **向用户显示通用错误 .** 不泄露原始内容 `Violation` 数据输入UI——消息是给开发者的,而不是最终用户的. 单"引文无效,请重试"即可.
4.  **不自动重试 .** 如果API被泄露,重复会更糟糕. 让用户手动触发重试 .

### 5\. 浏览器兼容性

SDK同时作为CJS和ESM发布,只使用与浏览器兼容的API(无) `fs`, (中文(简体) ), `crypto`, (中文(简体) ), `Buffer`, (中文(简体) ), `process`) (中文(简体) ).

摇树:无害环境管理建筑保留了被命名的出口。 只导入 `createValidator` 将不会拉入未使用的验证器 .

### 6\. 套装大小

大约1 MB已解开(其中很多是源地图——投放生产). 最重的对等级是 `@solana/web3.js`如果你的应用只处理 EVM 交易, 你的捆绑者树摇应该消除它的大部分.

### 7\. 类型脚本

全面申报船舶 `dist/types/`。 。 。 . `ValidatorConfig`, (中文(简体) ), `ValidationResult`, (中文(简体) ), `Violation`,以及 `ViolationCode` 全部出口——直接使用,不要重新申报.

### 8\. 不做什麽

-   ❌ **不要跳过验证** 因为"API是我们自己的。" 妥协探测是整点.
-   ❌ **不要变异 `request` 或者说 `response`** aPI呼叫和 `validate()` ——验证人需要用户收到的准确的有效载荷.
-   ❌ **不要解释 `violations[].message` 方案** ——电文措辞在版本之间可能会有变化. 分会 `code` 换句话说.
-   ❌ **如果 `environment` 变化.** 通过 `createValidator` 每个环境.

## 发展

见 [`CLAUDE.md`](https://npmcn.com/package/%40debridge-finance/borderless-validation-sdk/CLAUDE.md) 项目惯例、审定规则和安全准则. 见 [`src/README.md`](https://npmcn.com/package/%40debridge-finance/borderless-validation-sdk/src/README.md) 用于概述源代码结构和验证流程.

-   单位测试 : `npm test`
-   Zod 3 单元相容性测试 : `npm run test:zod3`
-   Zod 3 E2E相容性测试 : `npm run test:e2e:zod3`
-   Zod 3 E2E相容性测试( CI 模式): `npm run test:e2e:zod3:ci`
-   Zod 3/4 完全兼容性检查 : `npm run test:zod-compat`
-   单位测试覆盖率 : `npm run coverage`
-   E2E 测试( 默认使用阶段 API; 覆盖到 `API_BASE_URL`: `npm run test:e2e`
-   使用校验大小写记录的 E2E 测试 : `npm run test:e2e:record-validation-cases`
-   E2E测试( CI 模式, 串行加较长的超时): `npm run test:e2e:ci`
-   E2E覆盖率: `npm run coverage:e2e`
-   下载匹配的 Java 验证器 CLI : `npm run download:java-validator-cli`
-   比较类型脚本和 Java E2E 验证结果: `npm run test:e2e:java-parity`
-   全面建设 : `npm run build`
-   仅建立无害环境管理: `npm run build:esm`
-   只构建 CJS : `npm run build:cjs`
-   仅构建类型声明 : `npm run build:types`
-   清洁构建输出 : `npm run clean`

### 释放

Nx公司从常规承诺的 PR 标题中剪辑了释放:

1.  将公关定为一项常规承诺: `fix: ...` (标出), `feat: ...` (未成年人), `feat!: ...` (主要内容). 其他类型(`ci`, (中文(简体) ), `chore`, (中文(简体) ), `docs`, (中文(简体) ), `test`, (中文(简体) ), `refactor`,不触发释放.
2.  挤出公关 `master`。 。 。 .
3.  行动- **创建发行** • 运行工作流程 `master`; 勾选 `dry-run` 预览下一个版本,并 先换换日志 经批准后 `release` 环境 工作流程起伏 `package.json`, (中文(简体) ), 更新 `CHANGELOG.md`,推动 `v<version>` 标签,创建 GitHub 发布 并发布软件包到 npm(受托出版,无 npm 令牌).

发布合并的更改而无需修改 `fix:`编号 :`feat:` 标题,设置 `version` (单位:千美元)`patch`, (中文(简体) ), `minor`, (中文(简体) ), `major` 或者说 `1.2.3`) (中文(简体) ). 如果 npm 发布步骤失败, 则重新运行 Create Release with `publish_only`。 。 。 .

## Java 等同 E2E 验证

此检查通过 TypeScript SDK 及其运行存储器的 E2E 验证大小写 Java端口,然后验证两种执行产生等效的验证结果.

### 1\. 核对

从根使用 TypeScript SDK 版本 `package.json`数字 :

```bash
npm run test:e2e:java-parity
```

要选择另一个 TypeScript SDK 版本的 Java 版本, 请通过该版本 明确:

```bash
npm run test:e2e:java-parity [-- <typescript-sdk-version>]
```

参数只选择 Java 释放映射 。 它不检查或安装该版本的TypeScript SDK;TypeScript结果总是来自当前工作树.

命令需要Java和访问 GitHub 发布. 对于认证的 GitHub 访问, 它使用 `GITHUB_TOKEN`, (中文(简体) ), `GH_TOKEN`,或由 `gh auth token`顺序.

### 2\. 执行流程和生成的文件

命令执行以下步骤:

1.  从命令行参数或根确定请求的 TypeScript SDK 版本 `package.json`。 。 。 .
    
2.  查找最新发布的 Java 发布注释包含 `TypeScript SDK tag: v<version>` 并期望释放中包含一个 `cli-*.jar` 资产.
    
3.  下载和验证Java CLI, 除非同一经核实的发布已经在下面缓存 :
    
    ```text
    .cache/java-validation-sdk/releases/<typescript-version>/<java-release-tag>/
    ```
    
    此目录包含 CLI JAR 及其 `metadata.json` 缓存元数据 .
    
4.  检查Java CLI是否支持预期的CLI合同版本.
    
5.  运行普通的 TypeScript E2E 套件,并启用校验大小写记录。 每个杰斯特工人 将其验证器输入和 TypeScript 结果写入单独的 JSONL 文件 :
    
    ```text
    .cache/recorded-validation-cases/<date>__<unix-timestamp>/
    └── recorded-cases__pid-<pid>.jsonl
    ```
    
    每个JSONL行包含测试身份,验证器 URL,请求,响应,验证器配置, 和类型脚本 `ValidationResult` 一个验证人引用.
    
6.  以相同的顺序向 Java CLI 守护进程发送所有记录的输入并读取一个 Java `ValidationResult` 每个输入.
    
7.  比较相应的TypeScript和Java结果. 最多10个不匹配被打印到 操纵台 完整的不匹配报告写到:
    
    ```text
    .cache/java-validation-sdk/parity-check-runs/<date>__<unix-timestamp>/mismatches.json
    ```
    

临时 `.cache/recorded-validation-cases/latest-run.json` 文件连接 E2E 记录器 当命令完成时,将删除。 成功对等检查也会删除 其记录的验证案例。 如果 E2E 执行或对等比较失败,则记录的案例是 留作调查之用. 仅在不匹配需要时创建对等检查运行目录 报告.

### 3\. 比较规则

生下来的 `ValidationResult` 不直接比较对象。 每个结果都缩小为这个形状:

```ts
{
    ok: boolean;
    violations: Array<{
        code: string;
        path: string;
        expected?: unknown;
        actual?: unknown;
    }>;
}
```

比较内容包括:

-   顶级 `ok` 数值;
-   违反次数,包括重复违反次数;
-   每一个违反者 `code` 财务报告和审定财务报表 `path`· ;
-   存在值和 JSON 值 `expected` 财务报告和审定财务报表 `actual`· ;
-   内嵌值类型、字符串外壳和阵列元素顺序 `expected` 财务报告和审定财务报表 `actual`。 。 。 .

比较前:

-   违反情况加以分类,因此两个SDK报告违反情况的顺序并不重要;
-   对象密钥按递归排序,因此对象属性顺序无关紧要; 2;
-   未排序数组,因此其元素顺序仍然重要.

比较故意忽略:

-   违反 `message` \* 文本;
-   违反 `details`· ;
-   任何其他违规领域;
-   任何其他顶级结果字段.

正常化后,两个结果对象进行序列化和精确比较. 任何剩余 差异作为对等不匹配报告.

## 许可证

BUSL-1.1号线

## 常见问题

### @debridge-finance/borderless-validation-sdk 是什么？

验证无边意图的 SDK API 响应

### 如何安装 @debridge-finance/borderless-validation-sdk？

在项目目录运行 npm install @debridge-finance/borderless-validation-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3\.0\.0 \|\| ^4\.0\.0）、bs58（\>=5\.0\.0）、viem（\>=2\.0\.0）、@solana/web3\.js（\>=1\.90\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @debridge-finance/borderless-validation-sdk 支持 TypeScript 吗？

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

### @debridge-finance/borderless-validation-sdk 支持 ESM 还是 CommonJS？

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

### @debridge-finance/borderless-validation-sdk 可以商用吗？

@debridge-finance/borderless-validation-sdk 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @debridge-finance/borderless-validation-sdk 的下载量有多少？

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

### @debridge-finance/borderless-validation-sdk 还在维护吗？

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