algorand / algorand/js-algorand-sdk

mnemonicToSecretKey: unhelpful error when given a 24-word BIP-39 mnemonic (Pera Universal Wallet)

未关闭
#1,064 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
TypeScript
星标
297
派生
214
平均合并
1 小时 3 分钟
30 天内合并 PR
3

描述

## Summary

`algosdk.mnemonicToSecretKey()` throws a generic `failed to decode mnemonic` error when given a 24-word BIP-39 mnemonic exported from Pera Wallet's Universal Wallet. There is no indication that the format is wrong or what format is expected.

## Steps to Reproduce

1. Create a new wallet in Pera Wallet (iOS/Android) — the default type is **Universal Wallet**
2. Export the passphrase: Settings → Security → Show Passphrase
3. Copy the 24-word mnemonic
4. Try to use it with algosdk:

\`\`\`typescript
import algosdk from "algosdk";
algosdk.mnemonicToSecretKey("word1 word2 ... word24");
// ❌ Error: failed to decode mnemonic
\`\`\`

## Expected Behavior

The error message should indicate the format mismatch clearly, e.g.:

\`\`\`
Error: failed to decode mnemonic — expected a 25-word Algorand mnemonic, received 24 words.
Pera Universal Wallet exports a BIP-39 24-word mnemonic which is not compatible with algosdk.
Use a legacy Algorand Account in Pera (25 words) or generate one via algosdk.generateAccount().
\`\`\`

## Root Cause

Pera Wallet introduced **Universal Wallets** (BIP-39 HD standard, 24 words) alongside the legacy **Algo25 Wallets** (Algorand-native, 25 words + checksum). The two formats are incompatible. algosdk only supports the Algo25 format but gives no indication of this in the error.

## Impact

Developers using Pera Wallet (the most popular Algorand wallet) for local development or scripting will hit a silent dead end. The current error message `failed to decode mnemonic` gives zero actionable guidance — users assume they copied the wrong words, not that the format is fundamentally different.

## Workaround

In Pera Wallet, explicitly create a legacy **Algorand Account** (not a Universal Wallet) to get a 25-word algosdk-compatible mnemonic. Alternatively, generate one directly:

\`\`\`typescript
const account = algosdk.generateAccount();
const mnemonic = algosdk.secretKeyToMnemonic(account.sk); // always 25 words
\`\`\`

## Suggested Fix

In the `mnemonicToSecretKey` / `seedFromMnemonic` function, check the word count before attempting to decode and throw a descriptive error:

\`\`\`typescript
const words = mnemonic.trim().split(/\s+/);
if (words.length !== 25) {
throw new Error(
\`Invalid mnemonic: expected 25 words, got \${words.length}. \` +
\`If using Pera Wallet, make sure to export from a legacy Algorand Account, not a Universal Wallet.\`
);
}
\`\`\`

## Environment

- algosdk: v3.5.2
- Pera Wallet: Universal Wallet (default new account type)
- Discovered while building: https://github.com/firedintern/algorand-x402-api

贡献指南

这个仓库没有索引到贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。