Expand description
§Wanning 闸核心(wanning-core)
中国合规场景下,给任何 agent 插的支付闸 —— 意图层标准件。
闸坐在「agent 的消费意图」和「支付管道(支付宝免密/微信支付)」之间, 只做四件事,不碰资金流、不参与结算、不持有任何资金:
- 预算——用户一次授权设总预算(单位:人民币分,u64,全程禁浮点), 闸对每笔意图做原子扣减,超额即拒。
- 撤销——kill switch:撤销即永久拒绝该委托的一切后续意图(即时生效)。
- 重放——同一 nonce 在同一作用域内只允许成功消费一次,重放即拒。
- 审计——每一条决策(放行/拒绝)append-only 落 WAL,可回放重建账本状态。
语义对齐 Mist 的 DSA 授权层(预算扣减 / 撤销即时 / 重放 nonce / fail-closed),
但刻意不依赖 mist-core crate:Mist 是链上/ZK 形态(金额是链上单位,
依赖 k256/ed25519/ZK 电路),Wanning 是人民币分语义的链下闸,强行复用会拖进
一整棵加密依赖树却用不到任何代码。各语义点在代码里以 // 语义对齐 mist-core
注释标注,便于将来对账。
模块地图(闸判定语义见 gate):
| 模块 | 职责 |
|---|---|
delegation | 授权(用户 → agent):预算上限 / 有效期 / nonce 作用域 / 支出策略 |
intent | 消费意图(agent 发起的一笔待判定消费) |
gate | 闸判定面:按 fail-closed 顺序检查并原子扣减 |
policy | 支出策略(W-27):速率 / 类目预算 / 商户名单 / 禁止时段 |
error | 错误分层:业务拒绝 ≠ 错误;CoreError 只管 API 误用/状态被破坏 |
budget | 预算账本:分/元语义,remaining ≥ 0 不变量 |
revocation | 撤销集合(kill switch) |
replay | nonce 防重放登记 |
wal | 审计日志(append-only JSONL)+ 回放重建 |
pending | 人在环待支付(W-53a,第一形态):五段事件链 + 三钉 + 档位 |
state | 运行时状态:闸 + 审计(write-ahead)+ 待支付台账 + 时钟;replay 重建 |
clock | 可注入时钟(测试不 sleep,过期语义可控) |
paths | 默认路径(W-43a):~/.wanning 解析与 WAL 目录自动创建 |
sha256 | SHA-256(FIPS 180-4,零依赖手写;W-23 锚点的底层哈希) |
anchor | 审计锚点(W-23):所有者侧密钥锚住链尾,堵住 W-21 已知边界 |
合规边界见 docs/compliance-redlines.md(无豁免):本 crate 是意图层软件,
资金路径永远是「用户实名支付工具 → 商户」,没有任何我们的位置。
Modules§
- anchor
- 审计锚点(W-23):所有者侧密钥锚住 WAL 前缀,堵住完整性链的已知边界。
- budget
- 预算账本(BudgetLedger):分/元语义的确定性账本。
- clock
- 可注入时钟(Clock)。
- delegation
- 授权(Delegation):用户(钱的主人)→ agent 的一次授权。
- error
- 核心错误类型。
- gate
- 闸判定面(Gate):四卖点的语义核心。
- intent
- 消费意图(SpendIntent):agent 发起的一笔待判定消费。
- paths
- W-43a 产品化:默认路径与 WAL 目录自动创建。
- pending
- 人在环待支付(W-53a,第一形态)。
- policy
- 支出策略层(W-27):总预算之外的确定性策略维度。
- replay
- nonce 防重放登记(ReplayRegistry)。
- revocation
- 撤销集合(RevocationSet):kill switch。
- sha256
- SHA-256(FIPS 180-4)——零依赖手写,所有者侧审计锚点(W-23)的底层哈希。
- state
- 闸的完整运行状态(
WanningState):闸 + 审计日志 + 待支付台账 + 时钟。 - wal
- 审计日志(WAL):append-only JSONL,每条记录一行。