# @bsv/payment-express-middleware 中文文档

规范地址：https://npmcn.com/package/%40bsv/payment-express-middleware/

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

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

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

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

- 包体积（解压后）：83.4 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：express \>=4\.18\.0 \<6，@bsv/sdk ^2\.1\.6 \|\| ^3\.0\.0 \|\| ^4\.0\.1，@types/express \>=4\.17\.0 \<6
- 首次发布：2025-01-06T18:29:06.008Z
- 最新版本发布：2026-10-28T01:23:19.907Z
- 近 30 天下载量：15941（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 15 个）

## 中文简介

BSV 区块链服务货币化快取中件

## 安装

```sh
npm install @bsv/payment-express-middleware
```

也可以使用：`pnpm add @bsv/payment-express-middleware`、`yarn add @bsv/payment-express-middleware`、`bun add @bsv/payment-express-middleware`

## README

# @bsv/ paying- sext-middleware (中文(简体) )

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

为已认证的遗产提供中间软件 `x-bsv-payment` JSON流传. 这个 运行后 `@bsv/auth-express-middleware`,发布 HTTP `402` 挑战, 验证 Atomic BEEF 交易, 解剖时拒绝再利用交易 ID,内化输出为0,并曝光经核实的付款收据.

该议定书不同于在下列文书中新近实施的BRC-121 `@bsv/402-pay`。故意选择一个协议;其标题和客户端 合同不可互换.

2.1.8版本删除了中间软件付款头的上限. 已经有一个信头 从客户端收到的付款经过解析,其付款无论大小都经过核实. HTTP 服务器、 CDN、 代理和WAF 配置自有运输预算; 配置 并验证支持付款证明的全部路径。 堕落者 `maxPaymentHeaderBytes` 选项仍然为源兼容性所接受,但 忽略,包括旧应用程序仍然提供值。 移动任意 用于 HTTP 服务器或边缘的预定运输策略,并删除此选项.

原子BEEF验证、犬类基础64、衍生物核查、付款 定价、钱包接受和原子重放保护仍然适用。 无效 付款内容被拒绝。 SDK 2.8.5 提高客户头容量; 并不限制此中间软件从其他兼容性接受的内容 客户。 不需要BRC100呼叫,电线或钱包数据迁移. 来源 发布是一个单独的保护发布步骤.

## 所需资源

-   22号节点或更新
-   4.18快车或更新车,包括快车5
-   `@bsv/auth-express-middleware` 在中间的软件链上
-   执行 BRC- 100 钱包 `internalizeAction`

一揽子船舶原生无害环境管理和共同JS的切入点,包括申报 两个模块系统.

## 安装

```bash
npm install @bsv/payment-express-middleware @bsv/auth-express-middleware @bsv/sdk express
```

Express是一种对等依赖,所以中间软件使用应用程序的单相 快跑时间和类型图. 这可防止重复的快递设施 从制作 `PaymentRequest` 或返回的与 应用程序的路由类型.

## 基本用途

```ts
import express from 'express'
import { createAuthMiddleware } from '@bsv/auth-express-middleware'
import { createPaymentMiddleware, type PaymentRequest } from '@bsv/payment-express-middleware'

const app = express()

app.use(express.json())
app.use(createAuthMiddleware({ wallet }))
app.use(
  createPaymentMiddleware({
    wallet,
    calculateRequestPrice(req) {
      if (req.path === '/free') return 0
      if (req.path === '/premium') return 500
      return 100
    },
    replayStore
  })
)

app.get('/premium', (req: PaymentRequest, res) => {
  res.json({
    accepted: req.payment?.accepted,
    satoshisPaid: req.payment?.satoshisPaid,
    txid: req.payment?.txid
  })
})
```

价格必须 `0` 或正安全整数。 零费用请求继续进行 并附有可接受的零值收据。 无效或失败的定价返回稳定 `500` 答复,绝不授权请求.

## 流动

1.  认证中间软件验证对等点并提供压缩 `req.auth.identityKey`。 。 。 .
    
2.  `calculateRequestPrice` 返回所需的 stoshis.
    
3.  若无 `x-bsv-payment` 页眉已存在, 中间软件返回 `402` 改为:
    
    -   `x-bsv-payment-version: 1.0`
    -   `x-bsv-payment-satoshis-required`
    -   `x-bsv-payment-derivation-prefix`
4.  客户端用一个JSON头重试:
    
    ```json
    {
      "derivationPrefix": "<canonical-base64>",
      "derivationSuffix": "<canonical-base64>",
      "transaction": "<base64-atomic-beef>"
    }
    ```
    
5.  中间软件对收到的信头进行解析,验证衍生 前缀, 剖析 Atomic BEEF 交易, 减少遗留的超包容性 申报对象的信封及其依赖性关闭,并要求 输出为零以覆盖当前价格.
    
6.  钱包必须验证并新接受汇款 `{ accepted: true }` 从 `internalizeAction`。合并/重播类似或错误 结果不授权路径.
    
7.  只有在钱包验证后,中间软件才在解析时声称 交易编号。 防止与a配对的无效衍生材料 毒害回放店的公开交易.
    
8.  `next()` 运行与 `req.payment`,以及 `x-bsv-payment-satoshis-paid` 报告实际产出值.
    

钱包判决必须曝光 `accepted` 和可选 `isMerge` 作为自己的数据 属性; 继承或获取者支持的权力被拒绝, 不 利用进入者。 格式不当、重复、资金不足、被拒绝或含糊不清 付款从不打电话 `next`。 。 。 .

## 选项

```ts
const payment = createPaymentMiddleware({
  wallet,
  calculateRequestPrice,
  replayStore,
  logger
})
```

-   `wallet` 需要并且必须提供 `internalizeAction`。 。 。 .
-   `calculateRequestPrice` 可能是同步或同步,默认为 100个佐藤.
-   `replayStore` 必须执行原子 `claim(transactionId): boolean | Promise<boolean>`返回时返回 `false` 若为 交易已被使用 .
-   `maxPaymentHeaderBytes` ; 标题预算属于 hTTP 服务器或边缘.
-   `logger` 可提供 `error` 财务报告和审定财务报表 `warn` 方法。 。 。 内部故障发送 作为结构化上下文,但从未在HTTP回复中被曝光.

启动时无效的选项类型失败 .

## 重放存储

`InMemoryPaymentReplayStore` 是安全的单一进程默认值。 它会:

-   在一个过程中对每笔交易进行一次解析;
-   仅记录报告为新接受的钱包的交易;
-   在达到固定能力而不是驱逐时拒绝新的索赔要求 旧的重放标记;以及
-   当进程重新启动时,丢失所有索赔.

其默认容量为10万索赔. 适用于试验和 捆绑的单流程服务,而非横向规模或持久性 部署.

生产服务应注入一个数据库支持的共用耐用储存库 或 缓存原始,带有原子插入-if-缺漏语义:

```ts
const replayStore = {
  async claim(transactionId: string) {
    return await database.insertPaymentClaimIfAbsent(transactionId)
  }
}
```

不执行 `claim` 作为单独的读写操作。 继续重放 至少只要交易可以接受 再来一次 衍生非ce 证明服务器创建了前缀; 它不是 已过期的单用途重放数据库.

## 收款

经批准后:

```ts
interface PaymentReceipt {
  satoshisPaid: number
  accepted: true
  tx: string
  txid: string
}
```

`satoshisPaid` 是输出零的实际值,可能大于 要求的价格。 免费申请为零 `tx`编号 :`txid` 为空.

## 错误行为

| 状态 | 代码 | 含义 |
| --- | --- | --- |
| 400个 | `ERR_MALFORMED_PAYMENT` | 信头重复、 大小过大、 JSON 无效, 或有无效字段 |
| 400个 | `ERR_INVALID_DERIVATION_PREFIX` | 服务器没有创建所提供前缀 |
| 400个 | `ERR_INVALID_PAYMENT` | 原子 BEEF 无效或输出为0 资金不足 |
| 400个 | `ERR_PAYMENT_FAILED` | 钱包无法接受支付 |
| 402 (韩语) | `ERR_PAYMENT_REQUIRED` | 对付款提出质疑 |
| 409个 | `ERR_PAYMENT_REPLAYED` | 交易已经提出或未被新接受 |
| 500个 | `ERR_SERVER_MISCONFIGURED` | Auth 中间软件未提供有效身份 |
| 500个 | `ERR_PAYMENT_INTERNAL` | 定价失败或返回无效值 |
| 第503条 | `ERR_PAYMENT_UNAVAILABLE` | 无法创建挑战或重放存储 |

公用错误故意省略钱包、回放存储和定价例外 留言.

## 公共服务和浏览器访问

此中件不强制CORS或CSP. 可保留公共支付服务 在默认情况下交叉来源,而操作员可选择配置一个允许列表 应用程序或边缘层。 浏览器客户端需要 `x-bsv-payment-*` 通过 CORS 曝光的响应头 。 永不将通配符来源与 (原始内容存档于2018-09-26). Credited CORS.

## 安全说明

-   使用 HTTPS; 付款和身份头不是机密层 .
-   首先运行认证,然后运行授权/支付路径 中间软件功能.
-   使用持久的原子回放存储,用于多个过程或复制.
-   钱包错误和拒收汇款从未被插入回放 存储; 及时调查一个无法播放的再播放存储, 因为钱包 可能已经在独立大门前接受了交易.
-   监视器 `409` 财务报告和审定财务报表 `503` 利率和重放容量.
-   将定价视为安全敏感、决定性的要求政策.
-   钱包继续负责验证和安全内置 提供BRC-29汇款.
-   应用正常的请求/标题限制和在服务边缘限制的速率.
-   锁定失败被控制,不能中断付款授权或 更改 HTTP 结果 .

## API 密码

运行时间导出 :

-   `createPaymentMiddleware`
-   `InMemoryPaymentReplayStore`

出口类型 :

-   `BSVPayment`
-   `PaymentLogger`
-   `PaymentMiddlewareOptions`
-   `PaymentReceipt`
-   `PaymentReplayStore`
-   `PaymentRequest`

见 [API.md (英语)](https://npmcn.com/package/%40bsv/payment-express-middleware/API.md) 用于生成的签名.

## 发展

```bash
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test:coverage
pnpm pack:check
```

测试套房是决定性的,不叫公共API. `pack:check` 建立和验证无害环境管理和共同JS中准确的npm沥青球 消费者探测器 测试不重建包作为副作用.

## 许可证

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

## SDK4 热补丁对等要求

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

## 常见问题

### @bsv/payment-express-middleware 是什么？

BSV 区块链服务货币化快取中件

### 如何安装 @bsv/payment-express-middleware？

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

### @bsv/payment-express-middleware 支持 TypeScript 吗？

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

### @bsv/payment-express-middleware 支持 ESM 还是 CommonJS？

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

### @bsv/payment-express-middleware 需要什么版本的 Node\.js？

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

### @bsv/payment-express-middleware 可以商用吗？

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

### @bsv/payment-express-middleware 的下载量有多少？

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

### @bsv/payment-express-middleware 还在维护吗？

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