Customer wallet extractor

Role in the system

The customer wallet extractor is the owner-side entry point for a non-custodial case. It reads a supported encrypted wallet and emits only the serialized safe test piece used by the password-search network. It does not search for the password, decrypt the wallet, sign recovery work, or perform the final wallet recovery.

The extractor reuses the same wallet-engine code as the high-trust server path. Within a family it selects the supported format automatically—for example, Electrum legacy versus BIE1 or one of the three MultiBit formats. The owner chooses the wallet family; the owner does not choose a hashcat mode.

Offline file path
wallet file → offline CLI or GUI → safe extract ── owner-controlled handoff ──→ Distribrute
     └──────────── complete wallet stops here ────────────┘

Blockchain.com GUID path
wallet GUID → blockchain.info → encrypted backup in local process → safe extract → handoff
                 └──── the extractor never contacts Distribrute ────┘

The public recovery-request form remains contact-only: it accepts neither a wallet nor an extract. After a case is reviewed, an owner-created extract currently enters the case through a controlled intake and onboarding step. A general self-service extract-submission field is not live yet.

Offline CLI and GUI

Two front ends share the same extraction core:

Neither offline interface contains a networking dependency or an automatic submission path. The owner must deliberately move the resulting extract into the case workflow. Clipboard use is a local privacy tradeoff: other software on the owner’s computer may be able to read clipboard contents.

The GUI displays an additional warning for MultiBit Classic .key mode before the extract is copied. The CLI is non-interactive and does not pause for that warning, so the case workflow must still surface and record the partial-WIF disclosure.

Supported inputs

For a Bitcoin Core SQLite descriptor wallet, use a cleanly closed backupwallet copy. A live database with write-ahead-log or journal sidecars is rejected. Electrum, MultiBit, and Blockchain.com inputs are read into memory with a 64 MiB file-size cap; Bitcoin Core is opened through its read-only path rather than being copied into a temporary file.

Exact compatibility remains case-reviewed. A successful extraction proves only that the file has a supported testable shape; it does not prove ownership, password recoverability, or wallet value.

Offline command-line workflow

distribrute-extract-offline bitcoin-core --wallet wallet.dat
distribrute-extract-offline blockchain   --file wallet.aes.json
distribrute-extract-offline electrum     --wallet default_wallet
distribrute-extract-offline multibit     --wallet mbhd.wallet.aes

On success, the final standard-output line is the exact extract string. That makes the CLI pipeable, but it does not make the extract public data. The string identifies the wallet family and carries enough encrypted material to test candidates. It should be sent only through the case-specific path provided after review.

The optional --json form is intended for controlled tooling:

distribrute-extract-offline --json electrum --wallet default_wallet

The password is never requested during extraction. The tool does not test candidates or determine whether the wallet contains spendable funds.

Blockchain.com GUID retrieval

An owner who has a Blockchain.com wallet ID but no exported backup needs to retrieve the encrypted wallet before the one-block safe test piece can be created. That path is a separate binary, distribrute-extract-blockchain, so the ordinary CLI and GUI remain network-free.

The network transport is a build-time opt-in:

cargo build --release -p distribrute-extract-blockchain --features net
distribrute-extract-blockchain --guid <wallet-id>

The opt-in client compiles a BoringSSL-backed transport and therefore needs CMake, Clang, and a C/C++ toolchain. On minimal Linux installations, bindgen may also need an explicit system-include path. None of those dependencies are pulled into the ordinary offline CLI or GUI.

The implemented flow is:

1. Validate that the wallet ID is a 36-character UUID.
2. Open a wallet session with blockchain.info.
3. Request the encrypted wallet with resend_code=true, which may send one authorization email.
4. Let the owner approve that email and explicitly press Enter before another request is made.
5. Re-fetch with resend_code=false; there is no background polling or automatic email resend.
6. Derive the same $blockchainx$ safe extract used by the offline-backup path.

The opt-in transport uses a Chrome-like TLS and HTTP/2 profile because the wallet API is behind a Cloudflare browser check. Requests are hard-pinned to https://blockchain.info/, cross-host redirects are disabled, and requests have a 30-second timeout. Network errors are deliberately generic so the GUID and bearer token do not appear in logs or error messages.

This path has been validated end to end against the live service on Linux: session creation, owner email approval, encrypted-wallet retrieval, and extract equality with the offline path. Wallets that require a separate two-factor code are not supported by this binary; they must use an exported backup or a reviewed alternative intake path.

The online extractor never contacts Distribrute, but it is not anonymous from Blockchain.com. blockchain.info necessarily receives the wallet ID, session request, source network information, and email-approval interaction. The retrieved encrypted wallet also exists in the extractor process’s memory before it is reduced to the safe test piece.

File and memory boundary

The extractor code does not write wallet bytes to a temporary file. For the in-memory offline paths, the outer wallet buffer is wrapped in zeroizing storage and scrubbed when dropped. That is useful hardening, not a claim that every copy disappears:

• wallet-engine parsers can create transient allocations that are not reliably zeroized;
• SQLite’s internal C allocations cannot be reliably scrubbed by the Rust wrapper;
• the online Blockchain.com payload currently passes through ordinary string allocations;
• operating-system swap, crash dumps, malware, and other processes remain outside the tool’s control.

Running the offline build on a trusted, preferably disconnected machine reduces those risks. A malicious or corrupted wallet can still attack a parser, so an offline label is not a substitute for using a reviewed build and keeping the host patched.

Build and release evidence

The source repository pins the Rust toolchain and dependency lockfile. Its current automated evidence has deliberately different scopes:

• corpus tests assert byte equality with the recovery engines for Bitcoin Core, Electrum, and MultiBit;
• the Blockchain.com offline and GUID paths call the same one-block extraction function;
• the offline CLI release gate rejects networking dependencies, observes zero network syscalls during a representative extraction, and requires malformed, empty, or oversized inputs to fail cleanly;
• a two-clean-build reproducibility check targets the offline CLI;
• CI definitions build and test the workspace and compile the opt-in wreq transport;
• a tag-triggered release workflow is defined to produce checksums, an SBOM, and build provenance for Linux, macOS, and Windows artifacts.

No public version tag has been published yet. The CLI, GUI, and opt-in GUID retrieval are live in source code, but that status must not be read as a generally available signed desktop release. Platform signing, notarization, and the first multi-platform tagged build remain release work.

What the extractor does not change

Creating the extract locally changes wallet custody, not the fleet’s behavior:

• operators still receive the safe test piece and assigned candidates;
• a determined operator can still inspect a password found on its own machine;
• format-specific disclosures, including the Electrum address-prefix and MultiBit partial-WIF limits, still apply;
• a safe-piece match is not automatically a verified recovery;
• the wallet may resolve to addresses with no spendable balance after it is unlocked.

The extractor is also separate from the planned Recovery Room application. Extraction happens before the search; Recovery Room is intended for the post-match wallet unlock, transaction review, and local signing ceremony.

Continue with End-to-end recovery, Custodial vs non-custodial, and the Trust model.