如何修复 UniSat 钱包“尝试访问超出缓冲区长度”错误？ （错误修复）

对 UniSat 钱包中的缓冲区长度错误进行故障排除

1. 当钱包尝试从 BRC-20 代币传输或铭文负载中解析格式错误或过大的二进制数据时，通常会在二维码扫描或交易签名期间出现此错误。

2. 根本原因在于 UniSat 的内部缓冲区处理如何解释来自不受信任输入的字节序列，尤其是在解析具有非标准编码或截断的铭文数据的序数时。

3. 用户在与嵌入自定义脚本或超过 Bitcoin 块结构施加的 4MB 大小限制的实验铭文交互时最常遇到该问题。

4. 它与网络连接或 RPC 节点配置错误无关，而是与 UniSat 负责 UTXO 序列化的本机 WASM 模块内的严格边界检查有关。

5. 该错误并不表示钱包损坏或种子短语泄露 - 它反映了针对低级解码例程中不安全内存访问的运行时防护。

无需修改代码即可立即解决问题

1. 如果使用 UniSat Web 钱包，请清除浏览器缓存和本地存储，然后在尝试另一次扫描或签名操作之前重新加载界面。

2.从二维码导入切换到手动交易广播：通过区块链浏览器复制原始十六进制，粘贴到UniSat的“Broadcast Raw TX”工具中，并确认而不触发缓冲区解析逻辑。

3. 避免在可疑或新铸造的序数上单击“查看铭文”，尤其是那些源自未知铸币者合约或包含嵌套 JSON 结构的序数。

4. 禁用 MetaMask 或 Rainbow 等浏览器扩展，这些扩展可能会将冲突的脚本上下文注入 UniSat 的沙盒 iframe 环境中。

5. 在处理大型铭文时，使用 UniSat Mobile (v3.8.2+) 而不是桌面版本 - 其本机缓冲区分配器比基于 WebAssembly 的桌面版本更稳健地处理边缘情况。

针对自定义集成的开发人员级修复

1. 在将任何铭文数据传递给 UniSat 的decodeInscription()实用程序之前，强制执行严格的有效负载验证，拒绝超过 3.9MB 或前 16 个位置包含空字节的有效负载。

2. 使用 try/catch 块包装对signPsbt()的所有调用，并通过 BitGo 或 Blockstream Green PSBT 端点实施回退到外部签名。

3. 通过在调用Uint8Array.from()之前添加针对MAX_BUFFER_SIZE = 4194304的预检长度检查来修补 UniSat 的buffer-utils.ts 。

4. 将直接使用Buffer.from(hexString, 'hex')替换为Buffer.allocUnsafe() ，然后显式长度限制以防止旧 Node.js 环境中的溢出。

5. 审核第三方库，例如bip174和bitcoinjs-lib版本 - 旧版本缺乏 BRC-20 传输所需的边界感知 PSBT 解析。

社区验证的恢复步骤

1. 导出钱包的扩展公钥 (xpub) 并验证其与 UniSat 设置中显示的密钥匹配 — 这可确认没有发生密钥派生损坏。

2. 使用 mempool.space API 手动重建 UTXO，并根据 UniSat 显示的余额交叉检查确认的余额 - 差异表明同步不完整，而不是缓冲区故障。

3. 使用 12 字种子将钱包重新导入 Sparrow Wallet，以验证交易历史记录的完整性；如果 Sparrow 显示完整历史记录，则问题仅存在于 UniSat 的渲染层中。

4. 监视 UniSat 的 GitHub 问题页面以获取 PR #1427 和 #1509 — 这些包含应用于 v3.9.0+ 的修补程序，可解决 base64 到二进制转换管道中的差一错误。

5. 避免从早于 2024 年 3 月的备份恢复钱包 - v3.7.0 之前的快照可能包含格式错误的 indexDB 条目，从而在补水期间触发错误的缓冲区溢出。

常见问题解答

问：此错误是否意味着我的 BRC-20 代币丢失了？答：不会。错误发生在展示或签名过程中，而不是在链上结算过程中。您的代币仍然受到您的私钥的保护，并且可以通过 ordinals.com 等浏览器查看。

问：我可以通过更改 RPC 端点来绕过该错误吗？答：不需要。UniSat Wallet 使用自己的索引服务，不依赖外部 RPC 进行铭文解析。切换节点对缓冲区验证逻辑的影响为零。

问：该漏洞是否可以远程利用？答：不存在已知的远程代码执行向量。仅当用户启动的操作加载恶意制作的本地文件或二维码时才会触发该错误 - 不存在基于网络的注入路径。

问：为什么 UniSat 显示此错误，而 Xverse 不显示？答：Xverse 实现了更宽松的缓冲区约束，并将复杂的铭文解析推迟到后端服务。 UniSat 在客户端执行所有解码，使其对格式错误的输入更加敏感。