CC 充值流程

CC（Canton Coin）是 Canton Network Global Synchronizer 的原生代币，由 Splice DSO 以 Amulet 合约发行，不是 Rocky 发行的代币。本文介绍用户如何把自己钱包里的 CC 充值到 Rocky 交易账户。同一套流程也适用于 Rocky 支持的所有 Token Standard（CIP-56）资产，差别只在链上转账方式（见 §四）。

涉及概念：Canton Party、Holding、Token Standard、canton-bridge。如果不熟悉，请先阅读 Canton 网络介绍。

当前可充值的资产以 GET /v1/assets 返回的 deposit_enabled 字段为准。线上目前为：CC、CUSD、CBTC、cETH、USDC.B、USDCx、USX、aCC。

一、总览

Rocky 运行在 Canton MainNet。充值是用户从自己的钱包 party 向 Rocky 交易所 party 发起的一笔真实链上转账，Rocky 不代用户创建任何合约，也不持有用户私钥。

用户钱包 (Rocky Wallet / Console / Loop / Send)
   │  1. POST /v1/deposits/reference  →  target_party_id + deposit_ref
   │  2. 在钱包里向 target_party_id 转账，reason/memo 填 deposit_ref
   ▼
Canton Global Synchronizer
   │  用户 Holding −N，交易所 Holding +N
   ▼
canton-bridge consumer（订阅 Ledger API 更新流）
   │  3. 校验收款方 / 资产 / deposit_ref / 发送方 / 金额
   │  4. 用交易所 party（KMS 签名）对 PlatformAccount 执行 Credit
   │  5. 发布 NATS chain.events.deposit
   ▼
internal-ledger
   │  6. 幂等入账 ledger.spot_balances.free += N
   │  7. deposit_intents 状态 → credited
   ▼
前端轮询 GET /v1/deposits 与余额，显示已入账

关键点：没有 deposit_ref 的转账不会自动入账（见 §六）。

二、用户视角

用钱包登录 Rocky（/v1/wallet/challenge → /v1/wallet/verify，得到 session token）
在充值页选择资产、填写金额，Rocky 生成一条充值引用（deposit_ref），有效期 1 小时
按页面指引在钱包中向 Rocky 交易所 party 转账，并把 deposit_ref 填入转账的 reason / memo（Rocky Wallet 与 Send Wallet 由前端自动填好）
转账在 Synchronizer 确认后，canton-bridge 通常在数秒内观察到并入账
充值记录状态变为 credited，现货余额增加

充值不收取 Rocky 手续费。钱包或 validator 显示的 traffic / gas 费属于节点流量费，由用户侧承担。

三、API

所有接口使用 Authorization: Bearer <session_token>（来自 POST /v1/wallet/verify）。

3.1 创建充值引用

POST /v1/deposits/reference

请求字段	必填	说明
`asset`	是	资产符号或别名，如 `CC`、`CUSD`
`amount_expected`	否	预期金额（字符串，正数）。填写后链上金额必须完全一致才入账
`provider`	否	钱包 provider，默认取 session 的 provider
`binding_id`	否	钱包绑定 ID，默认取 session 的绑定

响应：

{
  "deposit_id": "1a2b3c4d-…",
  "asset": "CC",
  "wallet_symbol": "CC",
  "target_party_id": "<Rocky 交易所 party>",
  "deposit_ref": "rocky:deposit:1a2b3c4d-…",
  "reason_metadata_key": "splice.lfdecentralizedtrust.org/reason",
  "expires_at": "2026-09-07T07:30:00Z",
  "chain_action_policy": {
    "customer_chain_tx_window_hours": 12,
    "deposit_ref_required": true
  }
}

target_party_id 就是 EXCHANGE_PARTY_ID，所有资产共用
deposit_ref 必须原样放进转账的 reason_metadata_key 对应的 metadata 字段
wallet_symbol / wallet_display_name / aliases 是该资产在钱包里显示的名称，便于前端引导用户选对资产
引用与创建它的 session party 绑定：链上转账的发送方必须是这个 party

3.2 充值记录

GET /v1/deposits

返回当前用户最近 100 条充值意图：

字段	说明
`deposit_id`、`asset`、`amount_expected`、`deposit_ref`	创建时的信息
`status`	`pending`（等待链上转账）→ `observed`（bridge 已看到转账）→ `credited`（已入账）；另有 `expired`、`rejected`
`chain_tx_id`、`canton_update_id`	入账后对应的链上 update，可在 Canton Scan 或任一托管你 party 的 participant 上核验
`created_at`、`expires_at`、`credited_at`	时间戳（UTC）

3.3 Send Wallet 专用

POST /v1/deposits/send/transfer-factory

仅限 Send Wallet session。前端把钱包需要的 Token Standard TransferFactory choice 参数交给 Rocky 组装（经 canton-bridge），再交由 Send Wallet 签名提交。其他钱包直接在钱包内完成转账，不需要此接口。

四、链上转账方式

资产	链上机制	说明
`CC`	Splice Amulet `TransferPreapproval`	Rocky 交易所 party 预先登记了 CC 的 TransferPreapproval，用户钱包通过它直接把 CC 发给交易所 party。bridge 从 `TransferPreapproval_Send*` 事件中读取收款方、金额和 `deposit_ref`
`CUSD`、`CBTC`、`cETH`、`USDC.B`、`USDCx`、`USX`、`aCC`	Token Standard（CIP-56）`TransferFactory`	转账可能是 Direct（直接到账）或 Offer（生成 `TransferInstruction`，需交易所接受）。收款方为交易所 party 且 reason 以 `rocky:deposit:` 开头的 Offer 由 bridge 自动接受，接受动作同样由 KMS 签名

bridge 只识别 canton-bridge 配置中登记过的 instrument（admin party + instrument id 都要匹配）。同名但 instrument 不同的代币（例如旧版 USDCx）会被拒绝并记录日志。

五、资金流

以充值 N 个资产为例：

层	变化
链上 Holding	用户 party `−N`，交易所 party `+N`
Daml `PlatformAccount(asset)`	`Credit` 后 `+N`，`chain_tx_id` 记录来源 update
Rocky 分户账	`ledger.spot_balances.free` `+N`，`deposit_intents.status = credited`

入账落在现货钱包；如需用于永续合约保证金，再通过 Spot Transfer 划转。

六、bridge 入账校验与异常处理

canton-bridge 只对同时满足以下条件的转账入账：

收款方是当前 Rocky 交易所 party
资产 instrument 已登记
reason metadata 以 rocky:deposit: 开头，且能匹配到一条状态为 pending / observed 的充值意图
意图未过期（创建后 1 小时内）
发送方 party 等于创建意图时的 session party
若意图带 amount_expected，链上金额必须完全一致
同一 chain_tx_id / deposit_ref 只入账一次（幂等）

异常	处理
`deposit_ref` 缺失、过期、不存在或已使用	不入账，记录 warn 日志
instrument 不匹配	不入账，记录 error 日志
发送方 party 与意图不一致	不入账
金额与 `amount_expected` 不一致	不入账，进入人工核对
钱包转账成功但 bridge 未观察到	保留链上 update id，运维检查 Ledger 更新流
链上已到交易所 party，但 Daml `Credit` 失败	运维重试幂等命令或人工对账

用户手工把资产打给交易所 party 而没有有效 rocky:deposit: 引用时，资产会进入托管 party，但不会自动增加余额，需要联系客服人工核对。

七、开发环境

本地 / dev 环境可以不经真实转账直接铸造余额：

POST /v1/deposits/seed（需要 DEV_TOOLS_ENABLED=true，线上关闭）：经 canton-bridge 用 SHADOW_USER_PARTY_ID 创建 DepositIntent Daml 合约并入账。DepositIntent 模板只在这条开发路径上使用，MainNet 充值不创建它。详见 Seed Deposit
现货 session 的 Dev Faucet

八、相关文档

Canton 网络介绍
提现申请、提现查询
Spot Transfer（现货与永续账户之间划转）
现货链上结算
后端仓库 doc/user-deposit-withdrawal-architecture.md（充值提现架构与资金流的内部参考）

一、总览​

二、用户视角​

三、API​

3.1 创建充值引用​

3.2 充值记录​

3.3 Send Wallet 专用​

四、链上转账方式​

五、资金流​

六、bridge 入账校验与异常处理​

七、开发环境​

八、相关文档​