feat(hd): allow invalid checksums for puzzle wallets

[oritwoen]

Some puzzle answers have a bad BIP39 checksum, and fixing it changes the wallet. allowInvalidChecksum lets deriveHDWallet handle them explicitly. The Movie Enigma solution reproduces its published address without changing a word.

[coldtea-pr-lens]

◈ PR Lens

🟢 +0 new · 🟠 ~7 changed · 🔴 -0 removed · 2 flows · 7 files · commit 2471b7c

Architecture

7 components touched across 4 lanes.

Open the interactive canvas

Inside the changed components — 2 views

Component view — HD Derivation & BIP39 Core

BIP39 structural validation and seed derivation across curves with optional checksum bypass.

Component view — Client Interfaces & Operations

MCP, Pi extension, and public API passing checksum options and returning warnings.

Data flow

Deriving HD wallet with checksum override · Inspecting mnemonic phrase validity

Open the interactive canvas

The other flows — 1 sequence

Inspecting mnemonic phrase validity

Drill down

Client Interfaces — 3 components

🟡 CHANGED Public Library API

Exports updated HDWalletOptions with allowInvalidChecksum and Wallet with checksum warnings.

• src/types.ts:36-75

🟡 CHANGED MCP Server

Accepts allowInvalidChecksum on keys_derive_hd_wallet and returns three-part mnemonic validation diagnostics.

• src/mcp.ts:157-296

🟡 CHANGED Pi Coding Agent Extension

Exposes allowInvalidChecksum parameter and guidelines for puzzle derivation to the Pi coding agent.

• packages/pi/extensions/keys.ts:146-235

Tool Operations — 1 component

🟡 CHANGED Tool Operations Dispatcher

Dispatches HD derivation with the checksum override and runs granular three-part BIP39 inspections.

• src/tool-operations.ts:67-535

Blockchain Engine — 1 component

🟡 CHANGED Abstract Blockchain

Coordinates HD key derivation and attaches checksum failure warnings to the derived wallet.

• src/blockchain.ts:108-129

Derivation ＆ Mnemonics — 2 components

🟡 CHANGED HD Derivation Manager

Derives master keys while requiring valid word counts and word lists even when the checksum is bypassed.

• src/utils/hd.ts:15-50

🟡 CHANGED BIP39 Mnemonic Engine

Splits mnemonic validation into separate word count, wordlist membership, and checksum checks.

• src/utils/bip39/index.ts:102-139

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.
• The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
• GitHub will not let you zoom an image in a comment. The link under each diagram opens it on an interactive canvas, where you can zoom, pan and step through the flow.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Come say hi on Discord