RAILGUN 私人余额少了：核对查看权限、扫描与POI分桶
链小知 · 进阶 · 核验 · 依官方文档整理
按本人已保存的地址、Wallet SDK回调与余额记录，区分公开余额、view-only读取、扫描缺口和Spendable资格，避免把日志缺项当零资产。
开始前准备
- 准备本人有权查看的脱敏记录：公链网络/合约、0zk地址或本地wallet ID、SDK版本、UTXO/TXID扫描与balance回调及采集时间。
- 不需要导出或导入view key、spending key、助记词或encryptionKey；分享核对表前移除这些材料和完整私人历史。
- 方法依据当前官方SDK文档示例，不是已安装包/链上状态实测。
1. 确认公私地址与当前链
公链0x地址余额与RAILGUN 0zk私人余额分别记录；0zk不是rollup地址，也不是rg1地址。相同token symbol不能代替网络/合约身份。
官方Privacy System Contracts明确Ethereum、Polygon、BNB Chain、Arbitrum，与treasury/staking另列。先检查已有记录指向隐私系统及正确chain，不能把源钱包ERC20减少量直接当当前0zk可花余额。
检查结果：核对表有chain、隐私合约、0zk/本地wallet ID与token身份，公链余额没有并入私有余额。
2. 辨认只读权限而不提交查看凭据
View-only缺spending key，可以读余额/历史而不能create transactions；从原客户端配置或已存记录确认isViewOnlyWallet与wallet ID，签名按钮不可用不等余额消失。
Viewing Key是会披露账户记录的敏感材料，不能视为公开地址。同一Wiki前文写区块范围可限定，末NOTE却称scoping upcoming且key不可撤回；不能据本地扫描起点或一个年份标签保证接收者只看该年，也不执行分享或生成。
检查结果：只记录权限类型和是否有合法查看上下文，权限不足/范围未知不补成零余额。
3. 把UTXO扫描、TXID扫描和余额回调配对
私人余额由加密commitment同步和本地解密聚合形成。已有UTXO/TXID scan记录分别保留progress、scanStatus、chain和时间，再找同一wallet的onBalanceUpdateCallback；扫描日志存在不代表最终余额已更新。
官方示例对progress有0–1与0–100注释差异，不能盲目乘100或把数值1当100%完成。按实际客户端/版本的完成信号核对；只有失败/中断记录时标扫描未完成。refreshBalances的walletIdFilter与chain应属于目标wallet，未运行刷新不填新的扫描回执。
检查结果：扫描与余额记录属于同wallet/chain且能按时间配对；进度尺度或完成信号未知明确列出。
4. 按wallet、chain、版本和bucket分开余额
回调记录含railgunWalletID、chain、txidVersion、balanceBucket、erc20Amounts及nftAmounts。以这四项区分同一快照，保留最新事件的原金额；重复回调不能当多笔入金叠加。
官方示例balanceCache仅以bucket作为Map键，同bucket后一次set会覆盖前一次。若原应用保存多wallet/chain，先核对显示余额是否取到了别的wallet最近事件；不能仅凭getSpendableBalances()缺结果判断该wallet没有资产。V2/V3注释属于示例版本，按原记录实际txidVersion保留。
检查结果：每个余额值有完整身份与时间，缓存覆盖、重复事件和跨版本数据未混加。
5. 把总持有与可花费资格分列
Spendable、ShieldPending、ShieldBlocked、ProofSubmitted、MissingInternalPOI、MissingExternalPOI和Spent分别保留。ProofSubmitted或merkle扫描完成都不自动等于Spendable，Spent不是可花余额；不能为凑总额把已消费与当前桶简单相加。
POI独立于core并为可选的app/broadcaster assurance层，不能把某个bucket解释成任何平台都会接受。支持PPOI的wallet正文提初始1小时standby，但经过一小时仍需要当前证明/回调证据；原blocked/missing状态和具体错误按原app支持流程核对。
检查结果：输出已观察余额与Spendable可用额两栏，缺证明或资格未知没有被改成丢失/已解冻。
6. 限定数值、时间与完成范围
对每个ERC20金额保留原整数表示和token地址；换成人类数量前使用已取得的该token decimals，NFT列表不按ERC20金额相加。没有金额/精度或balance回调时标未取得，不从美元估值倒算币数量。
把源shield记录、扫描结果、POI bucket与显示快照并列；0.25%shield协议扣费只是独立费用规则，不能用该比例修补缺失回调或以等待时长补造当前余额。结果可为权限缺口、扫描未完整、缓存身份不匹配、证明资格待核或已取得同范围余额记录。
检查结果：结论绑定原wallet/chain/版本/时间，未访问私人余额或完成现行余额验收的范围明确。
怎样确认完成
- 形成按wallet/chain/txidVersion/bucket的原余额与扫描/权限对照表。
- 差异原因有具体记录或待补证字段；不使用秘密材料、发刷新、绕过检查或执行资金动作。
常见错误与边界
- 将公开0x余额、0zk余额与Spendable余额混为一项，或将Spent加回可用金额。
- 把Viewing Key当公开无风险信息，或从同页矛盾的区块范围描述保证可撤销/定年授权。
- progress尺度错误、只以bucket缓存多wallet/chain、重复回调累加造成显示差异。
- POI/扫描成功不证明任意平台认可；缺记录、失败和时间经过均不是零资产/自动可用证明。