cbdc-solution · API 参考

对外银行 API：Facade

Facade 同时注册 gRPC 9600 与 HTTP 9601，Proto package 为 cbdc_facade.v1。成功和失败都使用含 code、message、timestamp 的统一响应 envelope。

WalletService

RPC	HTTP	用途
`GenerateWalletId`	`POST /api/v1/wallets/generate-id`	由 BizHub 生命周期权威分配钱包 ID
`CreateWallet`	`POST /api/v1/wallets`	从 X.509 CSR 或 Idemix member material 创建钱包
`RenewWalletCert`	`POST /api/v1/wallets/{wallet_id}/certificate/renew`	续期 X.509 证书
`BatchGetWalletInfo`	`POST /api/v1/wallets/batch-get`	批量查询状态与标签/标记
`ListWalletKeys`	`GET /api/v1/wallets/{wallet_id}/keys`	查询策略成员与版本
`RegisterWalletKey`	`POST /api/v1/wallets/{wallet_id}/keys`	增加 X.509 / Idemix owner key
`RegisterCaIdentity`	`POST /api/v1/ca/identities`	为银行自持 key 注册 CA identity
`RelayIdemixCredential`	`POST /api/v1/ca/idemix-credential`	中继 blind Idemix enrollment

TransferService

RPC	HTTP	用途
`PrepareTransfer`	`POST /api/v1/transfers/prepare`	锁定输入并返回 base64 `tx_data`、费用和可签名 key
`SubmitTransfer`	`POST /api/v1/transfers/submit`	提交银行签名；`sender` 仅用于路由到准备交易的分片

TransactionService

RPC	HTTP	用途
`ListTransactions`	`POST /api/v1/transactions/query`	按钱包、时间、tx id、token type、action、status 分页查询

所有银行侧请求经过 Ed25519 签名中间件。确切 header、规范化算法和时钟窗口见 cbdc-facade/internal/auth/。

Wallet Node API

Proto package 为 cbdc_token.v1，服务名已改为 WalletNodeOpsService，定义于 cbdc-token/api/v1/walletnode.proto。主要分组：

分组	RPC
钱包	`ListWallets`、`GetWalletBalance`、`GetWalletInfo`、`CreateWallet`、`RegisterWallet`、`GenerateWalletID`、`RenewWalletCert`
策略与密钥	`CreateIdemixPolicyWallet`、`RegisterWalletKey`、`ListWalletKeys`、`GetPolicyBalance`、`EnsurePolicyWallet`、`GetPolicyMigrationStatus`
CA	`RegisterCaIdentity`、`RelayIdemixCredential`
转账	`PrepareTransfer`、`SubmitTransfer`、`CancelTransfer`、`Transfer`
交易	`ListTransactions`、`GetTransaction`
结算	`CreateSettlementRequest`、`QuerySettlementRequest`、`ListSettlementRequests`、`SubmitRedeemSignature`、`PrepareRedeem`、`SubmitRedeem`
管理同步	`GetAssetMarks`、`GetWalletMarks`、`ListApprovals`、`GetApproval`、`EnsureInstitutionWallet`

Wallet Node 的 HTTP 9502 是内部/兼容面；新的银行对外入口是 Facade 9601。

其他 Token 节点

服务	端口	RPC 概要
`IssuerService`	`9100`	`IssueToken`、`TotalSupply`
`EndorserService`	`9300`	`Init`
`AuditorService`	`9750`	审计查询、规则与拒绝相关操作

Endorser 初始化由开发控制器执行；手工调试可运行：

./dev/cbdc-dev init endorser

BizHub API

BizHub 统一监听 9000 并强制 mTLS。API 分三组：

Runtime API

api/runtime/v1：

WalletService
NodeRegistryService
ClientAuthDataService

Runtime 服务主要面向 Wallet Node、Facade、Issuer、Auditor 等服务身份；具体方法用 mtls.RequireRoles 限制角色。

Management API

api/management/v1：

NodeRegistryManagementService
InstitutionManagementService
RuleManagementService
FeeManagementService
MarkManagementService
TagManagementService
AuditRejectionQueryService

这些服务面向 Central，代码明确要求 RoleCentral。

业务兼容 API

api/v1/bizhub：RuntimeConfigService、FeeService、SettlementService、ApprovalService、BizhubAuditorService、IndexerService。

mode 边界

BizHub -mode runtime 只注册 runtime 专属服务，-mode management 只注册 management 专属服务；空 mode 在开发环境同时启用。公共业务兼容服务当前无条件注册。all 会被拒绝。

Central API

Central HTTP 8000 注册管理 Web 使用的全量服务，包括账户、用户、审计、审批、交易、规则、费用、机构、钱包、结算、统计、通知等。内部 gRPC 8001 仅注册：

NotificationService
ApprovalInstanceService
ApprovalTaskService
ApprovalEventService

业务数据服务多为 BizHub / Auditor 的代理；Central 自有服务操作 cbdc_central。

开发 CLI

./dev/cbdc-dev 是权威开发命令：

text

up / start / restart / stop / teardown
status / logs / doctor / plan
debug / docker
verify / init endorser

常用示例见快速开始，完整参数见源码仓库 dev/USAGE.md。

构建与测试

根 Makefile 的主要用途是构建，不是日常环境控制：

make go-build       # 编译所有 Go module
make build          # 构建业务镜像
make verify-protos  # 检查公共 Proto 快照

集成环境中使用控制器：

./dev/cbdc-dev up --verify
./dev/cbdc-dev up --verify-all

cbdc-solution · API 参考 ​

对外银行 API：Facade ​

WalletService ​

TransferService ​

TransactionService ​

Wallet Node API ​

其他 Token 节点 ​

BizHub API ​

Runtime API ​

Management API ​

业务兼容 API ​

Central API ​

开发 CLI ​

构建与测试 ​