CBDC Wiki

主题

cbdc-token/app/walletnode ​

Wallet Node 是银行钱包与 Token 交易的执行节点。它是 cbdc-token 中的 FSC / Panurus 应用，提供 gRPC 9500、HTTP 9502、WebSocket P2P 9501 和 FSC Web 9503。

目录与运行边界 ​

text
cbdc-token/app/walletnode/
├── cmd/walletnode/       启动与 Wire DI
├── configs/              app 示例配置
└── internal/
    ├── biz/              钱包、转账、交易、赎回
    ├── client/           BizHub clients
    ├── conf/             Bootstrap schema
    ├── identity/         X.509 wallet 构造
    ├── server/           gRPC / HTTP / OpenAPI
    ├── service/          WalletNodeOpsService
    └── worker/           FinalityWorker

应用没有自建 Ent data layer；FSC / Token 本地状态由 Panurus persistence 落到 Postgres，待提交交易与 finality watcher 含进程内状态。

启动序列 ​

当前代码要求 biz.cbdc.shardCode 非空，并与 walletid.SingleShard 一致；不满足会在启动时 panic。这是当前单分片约束，而不是机构码校验。

主要业务能力 ​

钱包与策略 ​

  • X.509 钱包创建、注册、状态与证书续期；
  • Idemix-primary policy wallet；
  • 多成员 X.509 / Idemix key 注册与查询；
  • owner policy projection、版本迁移与余额检查；
  • 可恢复的 EnsureInstitutionWallet / EnsurePolicyWallet；
  • CA identity 注册与 blind Idemix credential relay。

交易 ​

  • PrepareTransfer：选币、锁定输入、构造待签数据；
  • SubmitTransfer：校验指定 key_id 的预提交签名、审计、背书与广播；
  • CancelTransfer：释放 pending token 锁；
  • Transfer：托管式兼容调用；
  • ListTransactions / GetTransaction；
  • PrepareRedeem / SubmitRedeem。

策略钱包流程会验证 member identity / audit info，且不再假定 Keys[0] 就是签名成员。

API ​

服务定义：cbdc-token/api/v1/walletnode.proto，service 为 cbdc_token.v1.WalletNodeOpsService。它有钱包、策略、转账、交易、结算、审批和标记等 30+ RPC；分类清单见 API 参考。

银行外部客户端应优先调用 Facade 9601，而不是直接依赖 Wallet Node 的内部 API 与 shard 地址。

路由与动态发现 ​

Facade 与 BizHub 根据 wallet.ShardOf(wallet_id) 选择 Wallet Node。Wallet Node 通过 nodesdk.NewNodeResolverSyncForNode 从 BizHub 拉取 Auditor / Endorser 快照，并同步到本地 FSC endpoint service；它不是 Auditor / Endorser 地址的注册方。

API 响应不应向银行暴露 shard_code 或内部节点地址。

P2P 与证书 ​

cbdc-token/conf/walletnode-1/core.yaml：

  • fsc.p2p.type: websocket；
  • maxSubConns: 8192；
  • server/client roots 指向 /data/keys/ca-cert.pem；
  • node.crt 同时用于 FSC P2P 与 BizHub mTLS。

gen_crypto.sh 为 Wallet Node 叶证书生成 extendedKeyUsage=clientAuth,serverAuth，并加入 walletnode-<shard>.cbdc.sign.global、短名和 localhost DNS SAN。

选币与 finality ​

选择器支持：

  • memory：单进程默认；
  • distributed：Redis 后端，用于多副本协调。

FinalityWorker 等待 Token SDK finality：成功调用 ConfirmSpent，失败/超时调用 UnlockAll。pending transaction 和 watcher 均含内存态，部署切流时需要考虑请求亲和与恢复。

Docker ​

Wallet Node 与 Auditor / Issuer / Endorser 共用 cbdc-token 镜像。镜像构建 /usr/bin/walletnode，运行命令为：

text
walletnode --conf /app-conf