WALLET & SECURITY

How FOID Wallet v3 Works Under the Hood.

No extension. No seed phrase to memorize. Just a password and your passkey.

Most people who want to try FOID on mobile don't have MetaMask installed. FOID Wallet v3 lets anyone spin up a wallet in about 30 seconds — just a password and a passkey (Touch ID / Face ID). A 12-word recovery phrase is generated for backup, but you never need to manage it day to day. No extension, no friction.

This is a hot wallet for small amounts, not a vault. Use MetaMask or a hardware wallet for anything you'd be upset to lose. Think of FOID Wallet as somewhere to park $10-100 so you can interact with FOID — pray, hold a MiFOID, place on the Loreboard. It's fully open source, so you can inspect exactly how it handles your keys.

The short version

Your keys are encrypted with your password (and, on supported devices, your biometrics) and stored only on your device. The password is never sent anywhere and never stored. When you sign a transaction, the decrypted key only ever exists inside an isolated Web Worker, never on the page itself. If you clear your browser storage without your 12-word phrase, the wallet is gone — so write the phrase down.

How it works

1. Create

A 12-word BIP-39 mnemonic is generated, and a private key is derived from it via BIP-44 HD derivation. You pick a password (6+ characters). A WebAuthn passkey is created (Touch ID / Face ID / Windows Hello). Your password is run through Argon2id (64MB, memory-hard) to derive an encryption key — falling back to PBKDF2 (600k iterations) on devices without WASM. If your device supports WebAuthn PRF, a second key derived from your biometrics is XOR'd with the password key, so both factors are required. Your private key and mnemonic are then encrypted with AES-256-GCM, and the vault's integrity is sealed with HMAC-SHA-256. Only the encrypted blob lives in localStorage. The password is never stored anywhere.

2. Unlock

You enter your password and the passkey prompt fires for biometrics. Password attempts are rate-limited with exponential backoff — too many wrong tries and you're made to wait. The vault's HMAC is verified to catch tampering. Your password plus the PRF output re-derive the exact same encryption key, and AES-GCM decrypts the private key straight into a Web Worker — never onto the main thread. A 30-minute session begins and auto-locks on timeout or when you close the page.

3. Sign

Transactions go through the embedded connector (wagmi-compatible). Value is capped at 1 ETH per transaction as a guardrail against catastrophic mistakes. Signing happens inside the Web Worker where the key lives, so a cross-site scripting (XSS) bug on the main thread still can't read it. The session refreshes on each signing operation. No popups, no extensions.

Security layers

• Encryption at rest — AES-256-GCM (12-byte IV, 32-byte salt). The encrypted blob in localStorage is useless without your password. Vault integrity is verified via HMAC-SHA-256, so tampered vaults are rejected outright.
• Key derivation — Argon2id with 64MB memory-hard parameters (primary). Fallback: PBKDF2 with 600k iterations for devices without WASM. GPU brute-force is impractical against either.
• Dual-factor encryption — On devices that support PRF, the encryption key is the password-derived key XOR the biometric-derived key. You need both to decrypt.
• Worker session isolation — The decrypted private key lives inside a Web Worker, never on the main thread. XSS cannot read Worker memory. 30-minute auto-lock. Sensitive byte arrays are explicitly zeroed after use.
• Password rate-limiting — Exponential backoff on wrong-password attempts, stamped with a vault nonce. This slows brute-force even for someone with physical access to your device.
• Recovery & export — Your BIP-39 12-word phrase is the master backup: restore on any device with your words plus a new password. Private-key export requires a double-tap confirmation, and the clipboard auto-clears after 30 seconds. Older v1 wallets auto-migrate to v3 the next time you unlock.

If you forget your password

There's no reset button, and that's by design — no one at FOID can decrypt your vault for you. Your 12-word recovery phrase is the only way back in: enter it on any device, set a new password, and you're restored. If you have neither the password nor the phrase, the funds are unrecoverable. This is the trade-off for a wallet that trusts no server with your keys.

For what transactions cost, see parameters.txt.