# RAILGUN 私人余额少了：核对查看权限、扫描与POI分桶

整理：链小知（AI 辅助）
资料核对日期：2026-10-12
引用地址：https://lianxiaozhi.com/tools/guides/railgun-view-only-poi-balance-record-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

按本人已保存的地址、Wallet SDK回调与余额记录，区分公开余额、view-only读取、扫描缺口和Spendable资格，避免把日志缺项当零资产。

## 使用工具
- [RAILGUN](https://lianxiaozhi.com/tools/railgun) · [官方入口](https://railgun.org/)

## 前置条件
- 准备本人有权查看的脱敏记录：公链网络/合约、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身份，公链余额没有并入私有余额。
依据：[RAILGUN Wallets and Keys](https://docs.railgun.org/wiki/learn/wallets-and-keys.md)
依据：[RAILGUN 官方钱包链接与隐私合约](https://docs.railgun.org/wiki/learn/helpful-links.md)

## 2. 辨认只读权限而不提交查看凭据

View-only缺spending key，可以读余额/历史而不能create transactions；从原客户端配置或已存记录确认isViewOnlyWallet与wallet ID，签名按钮不可用不等余额消失。

Viewing Key是会披露账户记录的敏感材料，不能视为公开地址。同一Wiki前文写区块范围可限定，末NOTE却称scoping upcoming且key不可撤回；不能据本地扫描起点或一个年份标签保证接收者只看该年，也不执行分享或生成。

核对结果：只记录权限类型和是否有合法查看上下文，权限不足/范围未知不补成零余额。
依据：[RAILGUN View-Only Wallets](https://docs.railgun.org/developer-guide/wallet/private-wallets/view-only-wallets.md)
依据：[RAILGUN Wallets and Keys](https://docs.railgun.org/wiki/learn/wallets-and-keys.md)

## 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且能按时间配对；进度尺度或完成信号未知明确列出。
依据：[RAILGUN Private Balances](https://docs.railgun.org/developer-guide/wallet/private-balances.md)
依据：[RAILGUN Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks.md)
依据：[RAILGUN Updating Balances](https://docs.railgun.org/developer-guide/wallet/private-balances/updating-balances.md)

## 4. 按wallet、chain、版本和bucket分开余额

回调记录含railgunWalletID、chain、txidVersion、balanceBucket、erc20Amounts及nftAmounts。以这四项区分同一快照，保留最新事件的原金额；重复回调不能当多笔入金叠加。

官方示例balanceCache仅以bucket作为Map键，同bucket后一次set会覆盖前一次。若原应用保存多wallet/chain，先核对显示余额是否取到了别的wallet最近事件；不能仅凭getSpendableBalances()缺结果判断该wallet没有资产。V2/V3注释属于示例版本，按原记录实际txidVersion保留。

核对结果：每个余额值有完整身份与时间，缓存覆盖、重复事件和跨版本数据未混加。
依据：[RAILGUN Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks.md)

## 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可用额两栏，缺证明或资格未知没有被改成丢失/已解冻。
依据：[RAILGUN Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks.md)
依据：[RAILGUN Private Proofs of Innocence](https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence.md)

## 6. 限定数值、时间与完成范围

对每个ERC20金额保留原整数表示和token地址；换成人类数量前使用已取得的该token decimals，NFT列表不按ERC20金额相加。没有金额/精度或balance回调时标未取得，不从美元估值倒算币数量。

把源shield记录、扫描结果、POI bucket与显示快照并列；0.25%shield协议扣费只是独立费用规则，不能用该比例修补缺失回调或以等待时长补造当前余额。结果可为权限缺口、扫描未完整、缓存身份不匹配、证明资格待核或已取得同范围余额记录。

核对结果：结论绑定原wallet/chain/版本/时间，未访问私人余额或完成现行余额验收的范围明确。
依据：[RAILGUN Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks.md)
依据：[RAILGUN Private Balances](https://docs.railgun.org/developer-guide/wallet/private-balances.md)
依据：[RAILGUN 协议扣费与Broadcaster费用](https://docs.railgun.org/wiki/learn/railgun-deductions.md)

## 常见错误
- 将公开0x余额、0zk余额与Spendable余额混为一项，或将Spent加回可用金额。
- 把Viewing Key当公开无风险信息，或从同页矛盾的区块范围描述保证可撤销/定年授权。
- progress尺度错误、只以bucket缓存多wallet/chain、重复回调累加造成显示差异。
- POI/扫描成功不证明任意平台认可；缺记录、失败和时间经过均不是零资产/自动可用证明。

## 完成检查
- 形成按wallet/chain/txidVersion/bucket的原余额与扫描/权限对照表。
- 差异原因有具体记录或待补证字段；不使用秘密材料、发刷新、绕过检查或执行资金动作。

## 相关知识
- [原始、解码和整理后的链上数据有什么区别？](https://lianxiaozhi.com/learn/raw-decoded-curated-data)
- [把数据上链，与只保存数据哈希有什么区别？](https://lianxiaozhi.com/learn/data-onchain-vs-offchain)
- [钱包签消息与签交易有什么区别？不付 Gas 的签名也要读内容](https://lianxiaozhi.com/learn/wallet-message-vs-transaction)
- [区块确认与最终性是什么？交易成功和充值到账为何不同步](https://lianxiaozhi.com/learn/confirmations-and-finality)

## 官方依据
- [RAILGUN Wallets and Keys](https://docs.railgun.org/wiki/learn/wallets-and-keys.md)
- [RAILGUN 官方钱包链接与隐私合约](https://docs.railgun.org/wiki/learn/helpful-links.md)
- [RAILGUN 协议扣费与Broadcaster费用](https://docs.railgun.org/wiki/learn/railgun-deductions.md)
- [RAILGUN Private Proofs of Innocence](https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence.md)
- [RAILGUN View-Only Wallets](https://docs.railgun.org/developer-guide/wallet/private-wallets/view-only-wallets.md)
- [RAILGUN Private Balances](https://docs.railgun.org/developer-guide/wallet/private-balances.md)
- [RAILGUN Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks.md)
- [RAILGUN Updating Balances](https://docs.railgun.org/developer-guide/wallet/private-balances/updating-balances.md)