# Namada 屏蔽余额不完整：核 CLI 扫描高度、birthday 和本地缓存

整理：链小知（AI 辅助）
资料核对日期：2026-10-14
引用地址：https://lianxiaozhi.com/tools/guides/namada-cli-shielded-sync-birthday-cache-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

根据已有客户端记录，分开链身份、查看权限、扫描起止高度、索引器与缓存异常，避免把没扫到写成余额归零。

## 使用工具
- [Namada CLI 与文件系统钱包](https://lianxiaozhi.com/tools/namada-cli) · [官方入口](https://docs.namada.net/introduction/install/binaries/overview-of-binaries)

## 前置条件
- 准备脱敏的客户端版本、chain ID、base directory 摘要、原同步高度和错误；密钥只保留类型与别名，不复制查看密钥、花费密钥、助记词或密码。

## 1. 先确认是同一条链和同一个本地钱包

官方区分 namadac 客户端、namadaw 钱包、namadan 节点，namada client 与 namadac 等价。先按原记录核组件、版本与链；节点已同步不等于屏蔽钱包已扫描。

默认钱包路径是 <NAMADA_BASE_DIR>/{chain_id}/wallet.toml，--base-dir 会改变位置。主网页当前列 chain ID 为 namada.5f5de2dd1b88cba30586420；另一链或另一目录的空钱包不能代表原账户余额。主网版本表与旧评论不同，保留原版本而不猜升级组合。

核对结果：组件、版本、chain ID 和目录可以对应，未把另一钱包或节点进度当原屏蔽账户。
依据：[Namada：客户端、节点与钱包二进制的区别](https://docs.namada.net/introduction/install/binaries/overview-of-binaries)
依据：[Namada：文件系统钱包及链目录](https://docs.namada.net/users/wallet/file-system-wallet)
依据：[Namada：主网 chain ID 与版本表](https://docs.namada.net/networks/mainnets)
依据：[Namada：MASP 与本地视图的范围](https://docs.namada.net/users/shielded-accounts)

## 2. 区分收款地址、查看密钥和花费密钥

znam 是公开收款目标，zvknam 是查看密钥，可看账户收支和余额但不能花费；zsknam 是花费密钥，可派生查看密钥和地址。只有收款地址不足以扫描出该账户的私有余额。

同步页既写默认从用户钱包导入 MASP 密钥，又特别强调首次检查相应密钥时须通过 --viewing-keys 或 --spending-keys 提供，后续可复用已存内容。不要仅凭默认导入描述就推断原首次扫描已覆盖目标密钥；只核原别名和导入阶段，排错材料无需暴露密钥原值。

核对结果：原扫描使用的账户权限明确，未把查看能力、收款目标与花费授权混为一谈。
依据：[Namada：查看密钥、花费密钥与付款地址的权限](https://docs.namada.net/users/addresses)
依据：[Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)

## 3. 把 birthday 与同步终点分开

birthday 是密钥生成前的区块高度，供扫描跳过此前区块；未指定时默认 genesis，派生的查看密钥继承生日。直接传给 shielded-sync 的密钥也可附带 <<$BLOCK。这里只记录原生日高度，不重加密钥或改生日。

namadac shielded-sync 默认同步到链尖，--to-height $BLOCKHEIGHT 则限制最大高度。原收款区块若不在生日到扫描终点的范围内，不能用这次扫描证明该笔不存在；生日过晚的记录留待恢复原始材料。

核对结果：扫描起点、终点与待核收款高度分列，截止高度未冒充全历史扫描。
依据：[Namada：MASP 密钥、birthday 与地址](https://docs.namada.net/users/shielded-accounts/masp-keys)
依据：[Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)

## 4. 核实际数据来源，区分 indexer 与 RPC

屏蔽同步可以从节点 RPC 获取数据；官方更推荐能处理大量 MASP 数据的索引器。--with-indexer 的参数应为以 /api/v1 结尾的索引器 URL，不是任意节点地址。只保留原 host、路径和错误，移除凭据查询值。

公共 RPC 文档中的 --node 指向所选节点；其透明余额示例不能替代屏蔽扫描。节点落后、数据源失败或同步未结束时，结果保持不完整，不能填成零余额。官方基础设施列表本身不保证此刻可用。

核对结果：索引器、RPC 和网络对应，失败、落后或缺响应未变成无余额结论。
依据：[Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)
依据：[Namada：公共 RPC 的节点参数和信任前提](https://docs.namada.net/introduction/public-rpc)

## 5. 按本地保存进度判断中断范围

shielded-sync 下载并处理截至指定高度的本地 MASP 视图，用密钥识别属于该用户的 notes；它需要周期性继续，才能跟上链尖。同步命令结束不是付款、兑换或资金到账回执。

官方说正常 CTRL-C 等停止信号会先保存工作，下次同步可继续。这个说明不能扩成断电、强杀或文件损坏也一定保存成功；核原最后保存高度和停止方式，缺记录就留未知。

核对结果：已处理范围和停止方式有依据，未从一条中断日志推断全量完成或资金实收。
依据：[Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)
依据：[Namada：MASP 与本地视图的范围](https://docs.namada.net/users/shielded-accounts)

## 6. 缓存损坏时先界定恢复条件

官方只在屏蔽钱包损坏且同步不能正常工作时，将重新从零扫描列为最后手段；列出的生成文件是 shielded.dat、shielded.tmp、speculative_shielded.dat、shielded_sync.cache、shielded_sync.cache.tmp。它们与 wallet.toml 的密钥钱包不是同一文件。

清除这些生成文件后仍需重新提供必要查看或花费密钥，才能重扫。本篇只整理原异常与所需恢复条件，不删文件、导出密钥或启动同步；没有可确认的密钥和原链材料时，不能承诺可恢复余额。

核对结果：生成缓存、密钥钱包和重新扫描条件分清，未把删除钱包或重新建账户当修复成功。
依据：[Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)
依据：[Namada：文件系统钱包及链目录](https://docs.namada.net/users/wallet/file-system-wallet)
依据：[Namada：MASP 密钥、birthday 与地址](https://docs.namada.net/users/shielded-accounts/masp-keys)

## 常见错误
- 将查看密钥当可公开分享的地址，或将节点同步当屏蔽扫描。
- 为了加速随意提高 birthday，或将有限 --to-height 结果当全历史。
- 把任何同步错误记为零余额，或照缓存清单误删 wallet.toml。

## 完成检查
- 能列出同一账户的链、目录、密钥角色、扫描范围、数据源及异常层。
- 官方方法已核；个人客户端版本、账户资料、实际同步和余额结果未验证。

## 相关知识

## 官方依据
- [Namada：客户端、节点与钱包二进制的区别](https://docs.namada.net/introduction/install/binaries/overview-of-binaries)
- [Namada：文件系统钱包及链目录](https://docs.namada.net/users/wallet/file-system-wallet)
- [Namada：主网 chain ID 与版本表](https://docs.namada.net/networks/mainnets)
- [Namada：查看密钥、花费密钥与付款地址的权限](https://docs.namada.net/users/addresses)
- [Namada：MASP 密钥、birthday 与地址](https://docs.namada.net/users/shielded-accounts/masp-keys)
- [Namada：屏蔽同步、高度、索引器与缓存恢复](https://docs.namada.net/users/shielded-accounts/shielded-sync)
- [Namada：公共 RPC 的节点参数和信任前提](https://docs.namada.net/introduction/public-rpc)
- [Namada：MASP 与本地视图的范围](https://docs.namada.net/users/shielded-accounts)