> ## Documentation Index > Fetch the complete documentation index at: https://docs.haptixwallet.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Guardian Social Recovery > Timelocked non-custodial recovery for lost or stolen devices with asymmetric owner veto. # Timelocked Guardian Social Recovery Traditional crypto wallets force users to write down a **12-word seed phrase**. If they lose their phone, they restore the wallet by typing the seed phrase on a new device. However, seed phrases are the single largest source of hacks, phishing scams, and permanent balance loss in Web3. Haptix is **100% seedless**: your private keys are non-exportable hardware credentials stored inside the physical chip of your phone (**Android StrongBox / Apple Secure Enclave**). **The fundamental security question:**\ *If you drop your phone in the ocean, how do you recover your funds without a seed phrase?* **The Haptix solution:**\ An on-chain **Asymmetric Guardian Social Recovery Engine** enforced directly by the Solana smart contract bytecode. *** ## The Asymmetric Security Model The foundational security guarantee of Haptix recovery is asymmetric: > **A guardian can *start* an emergency freeze, but they can never *steal funds* or finish a recovery if the owner vetos.** ```text theme={null} ┌────────────────────────────────────────────────────────────────────────┐ │ RECOVERY STATE MACHINE │ │ │ │ [Normal Operation] ──(Phone Lost)──> [Guardian: initiate_recovery] │ │ │ │ │ ▼ │ │ [ Wallet Frozen ] │ │ [ Timelock Active ] │ │ │ │ │ ┌─────────────────────────────┴────────────┐ │ │ ▼ ▼ │ │ [ Unauthorized Attempt ] [ Legitimate Loss ]│ │ │ │ │ │ Owner: cancel_recovery Timelock Elapses │ │ ("Keep My Keys") │ │ │ │ ▼ │ │ ▼ [ execute_recovery ]│ │ [ Unfrozen ] │ │ │ [ Proposal Cleared ] ▼ │ │ [ Keys Rotated ]│ │ [ Address Intact]│ └────────────────────────────────────────────────────────────────────────┘ ``` *** ## On-Chain Instruction Breakdown | Instruction | Who Signs | Effect on Smart Account | | :- | :- | :- | | **`set_guardian`** | **Owner (2-of-2 Passkeys)** | Configures or updates the guardian's Solana address on-chain. | | **`initiate_recovery`** | **Guardian Alone** | Staged replacement keys are recorded, `initiated_at` timestamp is set, and the wallet is **frozen**. | | **`cancel_recovery`** | **Owner (2-of-2 Passkeys)** | Clears the proposal, unfreezes the wallet. Guardian is completely excluded from canceling. | | **`execute_recovery`** | **Permissionless (Anyone)** | Installs the replacement keys onto the PDA. Strictly gated by `now >= initiated_at + timelock`. | *** ## The 4-Stage Recovery Lifecycle ### Stage 1: Setup & Recovery Link Sharing During setup or anytime from **Settings → Recovery**, the wallet displays the dedicated **Guardian on-chain rescue** card: ![Recovery Link and QR Code](https://mintcdn.com/haptix-docs/6VupIqEznV9-h12Z/assets/recovery/recovery-qr-share.jpg?fit=max\&auto=format\&n=6VupIqEznV9-h12Z\&q=85\&s=6759e26b40151fc0ca554afe217176e3) Shareable Guardian Recovery Link & QR Code targeting the live Web Portal * **Live Web Portal Link**: `https://haptix-passkeys.vercel.app/recover.html?wallet=` * **Zero Command-Line Required**: Anyone with a standard laptop, tablet, or mobile browser can act as your guardian. *** ### Stage 2: Emergency Freeze via Web Portal If your phone is lost or stolen, your Guardian opens the [Emergency Recovery Portal](https://haptix-passkeys.vercel.app/recover.html) from any browser (Mac, Windows, iOS, Android): ![Emergency Recovery Portal Frozen](https://mintcdn.com/haptix-docs/6VupIqEznV9-h12Z/assets/recovery/recovery-portal-frozen.png?fit=max\&auto=format\&n=6VupIqEznV9-h12Z\&q=85\&s=95ad50840e8cc3c62ead3f2ea168845b) Guardian Emergency Recovery Portal during an active freeze on Solana Devnet 1. Guardian connects their wallet (`Phantom`, `Solflare`, `Backpack`, or hardware wallet). 2. The portal checks on-chain state to confirm the guardian key matches. 3. Guardian clicks **"Freeze lost phone"** and signs the transaction. 4. **Instant On-Chain Effect**: * Outgoing transfers from the lost device are **immediately blocked**. * Proposed replacement passkeys are staged on-chain. * An on-chain countdown timer (**Dispute Window**) begins. * Funds do **not** move anywhere—they remain locked safely in the smart account. *** ### Stage 3: The Owner's Veto ("Keep My Keys") What if your phone was not actually lost, or a compromised guardian attempted an unauthorized takeover? ![Owner Veto and Keep My Keys](https://mintcdn.com/haptix-docs/6VupIqEznV9-h12Z/assets/recovery/recovery-veto-flow.jpg?fit=max\&auto=format\&n=6VupIqEznV9-h12Z\&q=85\&s=9e53043834c49410fe1513d97867473b) Owner Veto Protection: The real owner cancels the takeover with 2-of-2 hardware biometrics * The mobile app displays the **Recovery Flow** dispute status. * The owner taps **"Veto and keep my keys"** and approves with both hardware passkeys (Touch ID / Face ID). * **On-Chain Result**: The smart contract instantly invalidates the guardian's proposal, resets the timer, and unfreezes the wallet. * **Guardian Defense Guarantee**: A rogue guardian can never force a recovery as long as the true owner holds their device. *** ### Stage 4: Timelock Expiration & Key Rotation If the old phone was genuinely destroyed or lost, the owner does not veto. Once the dispute window timer reaches `00:00:00`: ![Timelock Elapsed and Candidate Keys](https://mintcdn.com/haptix-docs/6VupIqEznV9-h12Z/assets/recovery/recovery-timelock-elapsed.jpg?fit=max\&auto=format\&n=6VupIqEznV9-h12Z\&q=85\&s=98147cc518cc7c866b823b5d60918682) Timelock elapsed: Candidate replacement keys can now be permanently installed 1. The app displays **"Timelock elapsed"** and reveals the **Candidate Replacement Passkeys**. 2. On the new replacement device, the user taps **"Hold to Finalize Recovery"**. 3. **On-Chain Execution**: * The contract verifies `Clock::get()?.unix_timestamp >= initiated_at + timelock`. * The contract permanently swaps the old dead keys for your new device's passkeys. * The wallet is unfrozen. * **Your wallet address, SPL tokens, and SOL balance remain 100% identical!** *** ## Smart Contract Security Invariants Our on-chain program enforces these strict security rules: 1. **Anti-Griefing Invariant (`ERR_RECOVERY_IN_PROGRESS`)**: A guardian cannot perpetually restart the timer or grief the owner. `initiate_recovery` rejects any call if a recovery is already in flight. 2. **Permissionless Execution (`execute_recovery`)**: The final installation requires **nobody's signature**—it is gated solely by on-chain time. This prevents deadlocks if a guardian becomes unreachable after starting the freeze. 3. **Address Integrity**: Because PDA seeds are tied to `[b"haptix_wallet", &primary_passkey[1..33]]`, key rotation updates the authorized signer state without modifying the on-chain account address. 4. **2-of-2 Quorum for Governance**: Updating the guardian address (`set_guardian`) requires a full 2-of-2 hardware passkey quorum, preventing malware from secretly replacing your guardian. *** ## Frequently Asked Questions > **Can my guardian steal my money?** > > **No.** The guardian address has zero spending authority. It can only call `initiate_recovery`, which freezes the wallet. Only your passkeys can authorize transfers. > **What if my guardian loses their wallet keypair?** > > As long as you have your phone, you can rotate your guardian at any time under **Settings → Recovery → Change Guardian** (requires 2-of-2 biometric authorization). > **How long is the dispute timelock?** > > * **Mainnet Standard:** 24 hours (86,400 seconds). > * **Devnet Testing:** 30–60 seconds for fast developer iteration. > **Do I need SOL to initiate recovery?** > > No. The [Emergency Recovery Portal](https://haptix-passkeys.vercel.app/recover.html) features an automatic fee sponsorship relayer that deposits gas for the guardian if their balance is zero. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.