SDK 架构
理解公开包、内部协议核心、运行时边界、网关契约和链上事实来源。
x402-paysdk 是一个统一版本的 npm 包，提供三个明确分离的入口。这种分离是安全边界，不只是命名方式。
x402-paysdk/pay付款运行时钱包签名 · 报价验证 · 结算
x402-paysdk/receive收款运行时PaymentRef 创建与生命周期
x402-paysdk/merchant仅限后端凭据 · 订单 · 通知 · 对账
协议核心URL · x402 payload · 已签名上下文 · 校验
↓
网关契约HTTP 路由 · facilitator relay · 收据 · 恢复
↓
链上事实EVM USDC 转账与确认数
公开包与内部模块
| 层级 | 是否公开 | 职责 |
|---|---|---|
x402-paysdk/pay | 是 | 付款协商、钱包签名、结算、收据验证、恢复、交易查询 |
x402-paysdk/receive | 是 | PaymentRef 创建、读取、列表和撤销 |
x402-paysdk/merchant | 是 | 后端商户认证、refs、订单、退款、通知、收据和对账 |
| 共享协议核心 | 不直接公开 | URL、x402 payload、signed offer、校验和有界 HTTP reader |
| 网关核心 | HTTP 契约 | 解析 ref、绑定上下文、relay facilitator、签发收据、查询链 |
仓库仍然保留角色独立的 source workspace，使依赖方向可以被审查。发布构建会把这些模块收进一个独立 npm artifact，并把内部引用改成包内路径。
运行时边界
付款运行时
付款端只接收公开支付上下文和宿主提供的 WalletSigner，不能接触商户 API key、notify key 或后端订单凭据。
收款运行时
收款端创建和管理 PaymentRef，不会签署付款，也不决定商户是否履约。
商户后端
商户入口持有服务端凭据并连接商户数据库。它返回证据和不匹配项，业务代码负责从 unpaid 到 fulfilled 的原子转换。
依赖方向
Textpay ──────┐receive ──┼──> 内部协议核心 ──> 网关 HTTP 契约 ──> 链merchant ─┘
TypeScript SDK 不依赖 Rust crate，网关也不会导入 SDK。双方通过版本化 schema、HTTP 路由、签名 envelope 和 receipt 字段连接。
状态所有权
| 状态 | 所有者 | 原因 |
|---|---|---|
| 钱包私钥 | 钱包宿主 | 签名权限不进入 SDK 或网关 |
| Ref 元数据 | 网关 RefStore | 处理过期、撤销和支付上下文 |
| 支付终局性 | 链与收据归档 | 默认网关没有 payment-state table |
| 商户订单 | 商户数据库 | 履约策略属于应用 |
| 可选网关订单 | 租户隔离 OrderStore | 只在明确启用 order mode 时存在 |
| Notify nonce | 商户共享存储 | 跨后端实例防重放 |
扩展规则
- 共享协议行为先进入内部核心，再通过拥有该操作的角色暴露。
- 不能从
x402-paysdk/pay暴露商户凭据或订单 mutation。 - 任何入口都不能添加直接转账 fallback。
- 新链族必须单独分析签名、重放、结算和终局性。
- Signed receipt 能证明网关输出，但不能取代链确认。