Sparrow Wallet 助記詞恢復工具命令列參數詳解

一、先把問題界定清楚

在比特幣錢包實務中，助記詞恢復通常有兩種入口：一是圖形介面手動操作，二是命令列工具批量處理、稽核或離線重建。Sparrow Wallet 的生態以桌面端最為知名，若你使用的是它配套的命令列腳本、自建 CLI，或將 GUI 的工作流程以腳本方式執行，參數設計的核心仍是把助記詞、BIP39 密語、派生路徑、網路、掃描深度與輸出格式明確化。

命令列參數的價值不在於少按幾次滑鼠，而在於可重現、可稽核、可離線。一次恢復若涉及多個帳戶、多個腳本類型或大量歷史地址，參數化能降低人為錯誤，也能把恢复結果固定成可驗算的資產。

二、恢復流程的四個階段

1. 載入助記詞：從標準輸入、參數或檔案讀取 12、15、18、21 或 24 個英文單字。
2. 生成種子與主鍵：套用 BIP39 演算法，必要時混入 passphrase。
3. 派生並掃描地址：按 purpose、coin type、account 與 change/receive 索引產生地址。
4. 匯出錢包資料：依格式輸出錢包檔、描述符、地址清單或 JSON 報告。

每個階段都可能對應不同參數。理解參數前，先理解階段，才能避免只背選項而用錯場景。

三、核心參數總覽

| 參數 | 作用 | 常用值或說明 |
|---|---|---|
| --mnemonic | 直接傳入助記詞 | 適合測試，不適合敏感環境 |
| --mnemonic-file | 從檔案讀取助記詞 | 建議搭配 chmod 600 |
| --bip39-passphrase | 傳入 BIP39 密語 | 大小寫、空格與字元需完全一致 |
| --passphrase-file | 從檔案讀取密語 | 降低 shell history 洩漏風險 |
| --derivation-path | 指定 HD 錢包派生路徑 | 例如 m/84h/0h/0h/0 |
| --account | 指定帳戶編號 | 0、1、2 等 |
| --purpose | 指定腳本或地址類型 | p2pkh、p2wpkh、p2wpkh-p2sh、p2tr |
| --network | 指定比特幣網路 | mainnet、testnet、signet、regtest |
| --gap-limit | 設定地址搜尋間隙 | 20、50、100 或更高 |
| --scan-depth | 控制掃描深度 | 接收與找零地址可分開設定 |
| --start-index | 從指定地址序號開始 | 適合已知交易地址時恢復 |
| --end-index | 設定掃描結束序號 | 與 start-index 搭配 |
| --fingerprint | 主金鑰指紋 | 用於驗證助記詞與密語 |
| --watch-only | 僅匯出公開錢包 | 不輸出私密金鑰 |
| --descriptor | 輸出錢包描述符 | 方便匯入其他相容工具 |

| --export | 匯出格式 | json、csv、wallet、descriptor |
| --output | 指定輸出檔案或目錄 | 建議搭配 --dry-run 預覽 |
| --offline | 離線模式 | 不呼叫外部索引器 |
| --log-level | 控制日誌等級 | info、debug、warn、quiet |
| --dry-run | 模擬執行 | 驗證參數但不寫入檔案 |
| --overwrite | 覆蓋既有輸出 | 僅在確認後使用 |
| --cache-dir | 快取目錄 | 適合反覆稽核同一錢包 |
| --threads | 併發執行緒 | 加速地址衍生與掃描 |

四、最重要幾組參數的實務細節

1. --mnemonic 與 --mnemonic-file

助記詞是種子來源。12 個字最常見，但 15、18、21、24 個字也可能是合法長度。工具通常需檢查詞數、英文單字是否在 BIP39 詞庫中，以及最後一字是否作為校驗字。

若從 shell 傳入 --mnemonic，命令可能被記錄於 history，並可能在處理程序中短暫暴露。因此敏感操作應優先使用 --mnemonic-file。檔案權限建議為 600，恢復完成後以安全方式刪除。某些工具也接受標準輸入，適合以管道傳入且避免直接落盤。

2. --bip39-passphrase

BIP39 密語是第 25 詞。沒有設定密語與設定空密語在部分實作中差異極大：未設定通常使用空字串，設定錯誤則會派生出完全不同的種子。 passphrase 可能包含空白、標點、大小寫，且必須逐字一致。若原始錢包有密語，務必使用 --passphrase-file 或安全傳入，並在完成後清除。

3. --derivation-path

派生路徑決定公開與私有金鑰如何展開。不同腳本類型對應不同路徑。若路徑錯誤，工具可能仍會成功匯出，但地址餘額與交易歷史可能全部錯誤。因此排錯第一步通常是確認路徑。

常見範例如下：

• P2PKH 舊式地址：m/44h/0h/0h
• P2SH-P2WPKH 相容隔離見證地址：m/49h/0h/0h
• P2WPKH 原生隔離見證地址：m/84h/0h/0h
• Taproot 位址：m/86h/0h/0h

帳戶層級路徑通常會再加上 /0 或 /1，分別代表 receive 與 change。部分工具可能使用 0' 作為 hardened 標記，需依文件統一。多帳戶則以 account 索引遞增，例如 0、1、2。

4. --gap-limit 與 --scan-depth

HD 錢包會順序產生地址。掃描器不能無限預知地址，必須依靠地址間隙假設。gap-limit 過小，會漏掉中間已使用地址；gap-limit 過大，會浪費時間與記憶體。

若錢包曾長期離線、收到多筆外部捐款地址，或你只記得某個交易地址，可調整 --start-index 或提高 --scan-depth。實務建議從 20 或 50 開始；若餘額明顯少於預期，再逐步提高到 100、250 或更高。

5. --purpose、--network 與 --export

--purpose 與 --derivation-path 應相互一致。例如 p2wpkh 通常搭配 m/84h。--network 錯置最常見，因為 testnet 與 mainnet 的 coin type 或位址首碼不同。輸出格式方面，wallet 適合後續匯入工具，json 適合稽核，csv 適合報表，descriptor 適合跨工具遷移。

6. --fingerprint、--watch-only 與 --descriptor

--fingerprint 是主公開金鑰的識別碼。恢復後若指紋與原始錢包不符，幾乎可確定助記詞、密語或派生路徑有誤。--watch-only 適合建立監視錢包，避免輸出私密金鑰。--descriptor 輸出後可匯入支援描述符的錢包，也便於後續與備份比對。

五、常見命令列組合

基本恢復並輸出 JSON：

sparrow-cli restore --mnemonic-file ./seed.txt --derivation-path m/84h/0h/0h/0 --network mainnet --gap-limit 100 --export json --output ./wallet.json --offline --log-level info

加入 BIP39 密語並輸出描述符：

sparrow-cli restore --mnemonic-file ./seed.txt --passphrase-file ./passphrase.bin --derivation-path m/49h/0h/0h/0 --purpose p2wpkh-p2sh --export descriptor --output ./wallet.descriptor

僅匯出監視錢包並驗證指紋：

sparrow-cli restore --mnemonic-file ./seed.txt --watch-only --fingerprint 0xabcdef12 --account 0 --export wallet --output ./watch-only.spw --overwrite

模擬稽核多帳戶：

sparrow-cli restore --mnemonic-file ./seed.txt --account 1 --derivation-path m/84h/0h/0h/1 --dry-run --gap-limit 250 --threads 4

六、安全與離線注意事項

1. 避免在共用主機直接傳入助記詞，必要時使用檔案或標準輸入。
2. 完成後安全清除臨時檔案，並確認備份媒介未被覆寫。
3. 若只需稽核餘額，優先使用 --watch-only 與 descriptor，不要輸出私密金鑰。
4. 使用 --offline 降低資料外洩，但若需檢查歷史交易，需搭配可驗證的離線索引器或已同步節點。
5. 執行 --dry-run 確認輸出範圍，再正式寫入檔案。
6. 對重要操作保留版本、網路、指紋、時間戳與檔案雜湊，形成可稽核紀錄。

七、排錯清單

| 問題現象 | 優先檢查參數 | 檢查方向 |
|---|---|---|
| 餘額少於預期 | --gap-limit、--scan-depth | 提高掃描深度，確認 change 與 receive 皆已掃描 |
| 地址完全不同 | --derivation-path、--purpose | 比對原始錢包腳本類型與帳戶路徑 |
| 工具報錯助記詞無效 | --mnemonic-file | 檢查詞數、單字拼寫、空格與行尾符號 |
| 有密語仍找不到錢包 | --bip39-passphrase、--passphrase-file | 逐字核對大小寫、空白、不可見字元 |
| 匯出的錢包無法匯入 | --export、--format | 確認輸出格式與目標工具相容 |
| CPU 與記憶體飆高 | --threads、--gap-limit | 降低併發與掃描深度，分批稽核 |
| 網路位址錯誤 | --network | 區分 mainnet、testnet、signet 與 regtest |

八、參數化策略建議

若你的目標只是恢復單一錢包，參數可以精簡。但若目標是資產盤點、事故復原或跨機構稽核，建議建立固定的參數模板。

可先定義三個環境變數：網路、派生路徑、輸出格式。接著將助記詞與密語分別放入受保護檔案。每次執行前用 --dry-run 檢查是否只會覆寫指定目錄。完成後用 fingerprint 與 descriptor 比對備份，並保存一份不含助記詞的稽核報告。

對於多帳戶錢包，不要直接猜測路徑。可先用最小 gap-limit 對 0、1、2 三個帳戶做快速掃描，找出有活動痕跡的帳戶後，再針對該帳戶提高掃描深度。對於 Taproot 或複合腳本，更應該同時匯出 descriptor，方便後續在其他支援工具中驗證。

九、小結

Sparrow Wallet 助記詞恢復工具的命令列參數可歸納為六大類：助記詞來源、密語來源、派生與腳本、網路與掃描、輸出與稽核、安全與併發。真正穩定的恢復不是背一條長指令，而是把每個參數對應到明確階段。只要清楚助記詞、passphrase、derivation path、gap limit、network 與 export 的意義，就能在離線、批量與高敏感場景中建立可重現、可驗證、可稽核的錢包恢復流程。