cbdc-facade

Facade 是面向银行客户端的 API 网关，监听 gRPC 9600 与 HTTP 9601。当前已经实现银行侧 Wallet、Transfer、Transaction 三个服务，不再是空脚手架。

目录

cbdc-facade/
├── api/v1/
│   ├── common.proto
│   ├── wallet.proto
│   ├── transfer.proto
│   └── transaction.proto
├── cmd/facade/
├── internal/
│   ├── auth/       Ed25519 签名认证与公钥缓存
│   ├── client/     BizHub + Wallet Node 连接与分片路由
│   ├── service/    三个 API service
│   └── server/     gRPC / HTTP / codec
└── conf/core.yaml

Facade 无本地数据库，也不运行 FSC / Panurus 节点。

请求鉴权

internal/auth 包含：

• 请求规范化；
• Ed25519 PKIX PEM 公钥解析；
• skewWindow 防重放时间边界；
• 原子替换的内存快照；
• 启动 warm-start 与周期 refresh；
• {InstitutionCode, ClientID} context identity。

业务 service 以签名 context 为调用方身份，不信任请求字段声称的机构身份。

银行侧服务

WalletService

支持钱包 ID 分配、X.509 / Idemix 钱包创建、证书续期、批量信息查询、策略 key 查询/注册、CA identity 注册和 blind Idemix credential relay。

CreateWallet 通过 oneof key_material 合并 X.509 与 Idemix 创建入口：

• X.509：银行提交 CSR，可选择从创建时启用 policy；
• Idemix：银行提交 member identity 与 audit info，平台不持有其秘密 key；
• 响应仅返回必要的钱包、证书和 policy 信息，不返回内部 shard routing。

TransferService

提供两步外部签名流：

1. PrepareTransfer 返回 tx_id、base64 tx_data、费用结果、eligible_keys 和 required_signatures；
2. 银行在系统外签名；
3. SubmitTransfer 携 sender、tx_id、signature 和可选 key_id 提交。

sender 用于重新路由到准备交易的 Wallet Node；对外响应不暴露 shard。

TransactionService

ListTransactions 支持钱包、时间、tx ID、token type、action type、status 和分页过滤，实际查询委托给目标 Wallet Node。

路由

internal/client.Clients 提供：

• WalletNodeFor(walletID)；
• WalletNodeByShard(code)；
• SoleWalletNode()，仅在配置恰好一个节点时可用。

出站依赖

目标	传输	用途
BizHub :9000	mTLS	auth client 快照、钱包 ID / CA 等权威操作
Wallet Node :9500	gRPC client	钱包、转账、交易具体执行

Facade 的 BizHub client cert/key 在配置中显式填写；证书角色为 facade，BizHub service 再按具体 RPC 调用 mtls.RequireRoles。

响应格式

成功响应由各 Proto 定义统一的 code/message/timestamp/data/details。HTTP errorEncoder 将 Kratos error 映射为同形状的 ErrorResponse，同时保留对应 HTTP status。

配置与 Docker

核心配置：

biz:
  server:
    grpc: { address: 0.0.0.0:9600 }
    http: { address: 0.0.0.0:9601 }
  upstreams:
    bizhub: { address: host.docker.internal:9000 }
    walletNodes:
      - shardCode: "1"
        address: host.docker.internal:9500
  clientAuth:
    skewWindow: 60s
    refreshInterval: 60s

镜像为 Ubuntu 24.04 运行时；entrypoint 只对 YAML 执行环境变量替换。

测试

internal/auth 覆盖 canonicalization、cache 与 middleware；internal/client 覆盖路由；internal/service/wallet_test.go 覆盖银行侧钱包映射；internal/server/http_test.go 覆盖 HTTP envelope / codec。