Wallet Password Recovery — Privacy-Preserving Workflow

Helping someone recover the password to a crypto wallet they own but have been locked out of (forgotten or partially-remembered passphrase).

This package is built around one rule:

The owner extracts a password verification hash from their own wallet and shares ONLY that with the helper. The hash lets the helper test candidate passwords but does NOT contain spendable private keys. The helper (Marc) can crack the password without ever holding the wallet or being able to move funds.

This is the same model used by reputable recovery projects and services — btcrecover (Christopher Gurnee, now maintained by 3rdIteration), Dave Bitcoin's Wallet Recovery Services, and standard hashcat / John the Ripper *2john extractors.

---

The three documents

File	Audience	Purpose
README.md (this file)	Both	Workflow, trust model, responsible-use, consent template
FOR-WALLET-OWNERS.md	The wallet owner	How to extract the non-spendable hash and what to send
FOR-ME-cracking.md	The helper (Marc)	How to crack the password from the hash (local + cloud GPU)
docs/OWNER-PRECHECKS.md	Owner	Integrity + balance checks to run before extracting
docs/OPERATOR-QUICKSTART.md	Helper	The walletrec uv CLI: assess / integrity / balance / plan / hints
docs/HARDWARE-AND-COST.md	Helper	Mac vs TrueNAS RTX 4060 vs cloud — will a 1-week job fit?
docs/OPENSSL-BACKUPS.md	Helper	openssl enc backups (Schildbach Android wallet): identify, crack, tooling
scripts/	Both	Docker extractor, hashcat launcher, btcrecover tokenlist (placeholders)
walletrec/	Helper	Stdlib-only Python package behind the CLI (zero third-party deps)

The walletrec toolkit (uv)

A small standard-library-only CLI automates the checks the prose docs describe. Set up once with uv sync, then:

uv run walletrec assess    wallet.hash              # KDF / iterations / difficulty
uv run walletrec integrity wallet.dat               # file health + sha256 (owner-side)
uv run walletrec balance   <address>                # watch-only balance, no secrets
uv run walletrec plan --mask '<shape>' --mode 11300 # Mac vs RTX 4060 vs cloud, time & cost
uv run walletrec hints     templates/hints-profile.toml  # memory hints -> masks + tokenlist

See docs/OPERATOR-QUICKSTART.md for the full walkthrough.

---

The workflow, end to end

   OWNER (holds wallet + funds)                 HELPER / Marc (holds only a hash)
   ┌──────────────────────────────┐             ┌──────────────────────────────┐
   │ 1. Work on a COPY of the      │            │                              │
   │    wallet. Original stays     │             │                             │
   │    offline + backed up.       │             │                             │
   │                               │             │                             │
   │ 2. Run the right extractor    │             │                             │
   │    (bitcoin2john / btcrecover │             │                             │
   │    extract-script) to produce │  hash only  │                             │
   │    a small verification hash  │ ──────────► │ 3. Load hash into hashcat / │
   │    e.g.  $bitcoin$96$....      │  (text)    │    btcrecover / John        │
   │                               │             │                             │
   │ 4. Confirms hash has NO key   │             │ 4. Turn the owner's memory  │
   │    material before sending.   │             │    hints into an efficient  │
   │                               │             │    attack (mask / tokenlist │
   │                               │  password   │    / rules / typos).        │
   │ 6. Uses recovered password    │ ◄────────── │ 5. Cracks → returns the     │
   │    on their OWN wallet to      │  (text)     │    plaintext password.      │
   │    regain access.             │             │                             │
   └──────────────────────────────┘             └──────────────────────────────┘

The wallet file, seed phrase, and private keys never leave the owner's machine. The helper only ever sees a hash that can verify a password guess, not decrypt funds.

---

Trust model — why this is safe for both sides

What the extracted hash is. A blob like $bitcoin$96$... (from a Bitcoin Core wallet.dat) or a btcrecover extract string. It contains: the KDF parameters (algorithm, iteration count, salt) and a small encrypted check value. Testing a password = derive the key, decrypt the check value, see if it validates.

What it is NOT. It is not the encrypted private keys, and for the btcrecover extract-scripts it is a deliberately truncated piece that is cryptographically insufficient to recover or spend any key even if fully cracked. See btcrecover's extract-scripts documentation:

"...the extract scripts ... produce a file ... which does not contain any private keys, only enough information to allow btcrecover to test password guesses. Because of this, it's safe to run btcrecover ... on an untrusted or online computer."

Consequences of the model:

• The helper cannot steal funds — there are no spendable keys in what they hold.
• The owner keeps sole custody the whole time.
• Even a full compromise of the helper's machine or a rented cloud GPU leaks only the hash, not the wallet.
• Worst realistic case: the helper learns the password — which is useless without the wallet file the owner never sent. (The owner should still rotate/move funds to a fresh wallet afterwards as good hygiene; see below.)

Residual risks to be honest about:

• If the owner sends the whole wallet.dat / seed by mistake, the model breaks. The point of FOR-WALLET-OWNERS.md is to prevent exactly that.
• bitcoin2john-style hashes for some wallets contain the full encrypted master key (enough to spend if cracked). btcrecover's extract-scripts are the safer choice because they strip that down. When only a *2john hash is available, the owner should treat the recovered password as compromised and move funds afterward.
• A recovered password is sensitive. Transmit it over an encrypted channel and have the owner move funds to a newly-generated wallet once access is restored.

---

Responsible use — read before doing anything

This toolkit is only for wallets the requester legitimately owns and controls.

1. Ownership + written authorisation first. Before touching any hash, get the owner to sign the authorisation below (or an equivalent). No signed authorisation → no work.
2. This recovers a password, not ownership. It cannot and does not establish who owns a wallet. If there is any dispute over ownership, stop.
3. Privacy guarantee. The helper only ever receives a non-spendable verification hash — never the wallet file, seed phrase, or private keys.
4. No third-party / found / "help me into someone else's" wallets. Do not proceed on a wallet the requester cannot demonstrate they control (e.g. cannot describe its transaction history, addresses, or provide the file themselves).
5. Data minimisation. Delete hashes, wordlists derived from personal hints, and any recovered password once the job is done.
6. Jurisdiction. Unauthorised access to others' wallets is a crime (e.g. computer- misuse / unauthorised-access statutes) in essentially every jurisdiction. The consent step is what keeps this on the right side of that line.

---

Consent / authorisation template

The owner fills in and signs this before the helper starts. Keep a copy.

WALLET PASSWORD RECOVERY — OWNER AUTHORISATION

I, ______________________________ ("the Owner"), confirm that:

1. I am the sole legitimate owner of, and control, the cryptocurrency wallet
   described below. I have lost or partially forgotten its password/passphrase.

   Wallet type / software ......: __________________________  (e.g. Bitcoin Core)
   Identifying detail ..........: __________________________
       (an address it holds, approx balance, or creation date — NOT the seed)
   Approx. date I lost access ..: __________________________

2. I am asking ______________________ ("the Helper") to help me recover ONLY the
   password to this wallet.

3. I understand and agree that:
   - I will send the Helper ONLY an extracted verification hash / extract file.
   - I will NOT send the wallet file, seed phrase, or any private keys.
   - The Helper cannot access or move my funds with what I send.
   - This process recovers a password; it does not transfer ownership.
   - Once access is restored I will move my funds to a newly-generated wallet.

4. I authorise the Helper to test password guesses against this hash, including on
   rented cloud hardware, using only the non-spendable hash.

Owner signature: ______________________   Date: ____________
Helper signature: _____________________   Date: ____________

---

Quick start

• Owner: open FOR-WALLET-OWNERS.md, find your wallet type, run the matching extractor on a copy, send Marc the resulting hash text (and anything you remember about the password).
• Helper (Marc): open FOR-ME-cracking.md, load the hash, build an attack from the owner's memory hints, run locally or on a hash-only cloud GPU.

References

• hashcat — example hashes & modes: https://hashcat.net/wiki/doku.php?id=example_hashes
• hashcat — main wiki: https://hashcat.net/wiki/
• btcrecover — docs: https://btcrecover.readthedocs.io/
• btcrecover — extract scripts: https://btcrecover.readthedocs.io/en/latest/Extract_Scripts/
• btcrecover — GitHub (3rdIteration fork, actively maintained): https://github.com/3rdIteration/btcrecover
• John the Ripper: https://www.openwall.com/john/ · https://github.com/openwall/john
• Dave Bitcoin — Wallet Recovery Services: https://www.walletrecoveryservices.com/