> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet Lifecycle: From Creation to Continued Ownership

> Follow a SocketFi wallet through its full lifecycle — creation, activation, daily use, credential updates, recovery, and indefinite continued ownership.

A SocketFi wallet is not tied to a session, a device, or a set of credentials. It is a Soroban smart contract deployed on Stellar that persists independently of everything else. Sessions expire. Devices get replaced. Credentials rotate. The wallet stays. Understanding this distinction is the single most important concept when building on SocketFi, because it shapes every decision from how you store user identities to how you design your recovery UX.

<Note>
  Sessions are temporary. Wallets are permanent. A user who logs out, switches devices, or recovers from a lost phone always returns to the same wallet — same address, same assets, same history.
</Note>

## The Six Phases

<Steps>
  <Step title="Creation">
    Wallet creation happens automatically the first time a user registers. The user creates a passkey; SocketFi deploys a Soroban smart contract wallet, binds the passkey to it, and initializes on-chain state including recovery configuration and nonce tracking.

    ```text theme={null}
    User registration
      ↓
    Passkey creation + verification
      ↓
    Smart wallet deployed: CDXXXXXXXXXX...
      ↓
    Credential bound to wallet
    ```

    The wallet address is assigned here and never changes.
  </Step>

  <Step title="Activation">
    After deployment, the wallet becomes active and can immediately receive assets, authorize transactions, and interact with Soroban contracts. No additional setup or funding is required from the user or your application.

    **An active wallet can:**

    * Receive and hold assets
    * Sign and execute transactions
    * Invoke Soroban contracts
    * Enforce spending policies
    * Participate in recovery flows
  </Step>

  <Step title="Daily Usage">
    This is the longest phase. Users authenticate repeatedly across sessions and devices, and the wallet resolves to the same on-chain contract every time.

    ```text theme={null}
    Authenticate
      ↓
    Passkey verified
      ↓
    Wallet resolved: CDXXXXXXXXXX...   ← always the same address
      ↓
    Session created
      ↓
    Transactions authorized and executed
    ```

    Each transaction requires an explicit passkey-signed authorization. The wallet's nonce increments with every executed operation, preventing replay.
  </Step>

  <Step title="Credential Updates">
    Users regularly get new devices, retire old ones, or proactively upgrade their security posture. Credential rotation lets them swap out the passkey bound to their wallet without touching assets or changing the wallet address.

    ```text theme={null}
    Current passkey authorizes rotation
      ↓
    New passkey registered + proof of possession verified
      ↓
    Wallet credential updated
    ```

    **What changes:** the bound passkey credential\
    **What stays the same:** wallet address, all assets, policies, transaction history, ownership

    <Note>
      Credential rotation requires the user to still have access to their current passkey. If the passkey is already lost, use account recovery instead.
    </Note>
  </Step>

  <Step title="Recovery">
    When a user loses access to their passkey — broken phone, deleted credential, hardware failure — account recovery restores access without creating a new wallet or moving assets.

    ```text theme={null}
    Passkey lost
      ↓
    Identity verified
      ↓
    Recovery authorized
      ↓
    New passkey registered
      ↓
    Wallet credential replaced
    ```

    **Before recovery:** wallet `CDXXXXXXXXXX...`, 500 USDC, passkey A\
    **After recovery:** wallet `CDXXXXXXXXXX...`, 500 USDC, passkey B

    The wallet is identical. Only the authentication credential changed.
  </Step>

  <Step title="Continued Ownership">
    After a credential update or recovery, the wallet continues operating exactly as before. The user retains:

    * The same wallet address
    * All assets and balances
    * All applied policies
    * Full transaction history
    * Complete ownership

    The lifecycle cycle — daily usage, credential updates, recovery — can repeat indefinitely. The wallet does not have an expiry.
  </Step>
</Steps>

## Address Permanence

No operation in the wallet lifecycle changes the `CDXXXXX...` address. This table summarizes what changes and what stays the same across key events:

| Event               | Address | Assets | Ownership | Credential |
| ------------------- | ------- | ------ | --------- | ---------- |
| New login / session | ✅ Same  | ✅ Same | ✅ Same    | ✅ Same     |
| Device change       | ✅ Same  | ✅ Same | ✅ Same    | ✅ Same     |
| Credential rotation | ✅ Same  | ✅ Same | ✅ Same    | 🔄 Updated |
| Account recovery    | ✅ Same  | ✅ Same | ✅ Same    | 🔄 Updated |

## Sessions vs Wallets

A session is a temporary access token your application uses to identify a user for the duration of their visit. It is not the wallet.

```text theme={null}
Session                    Wallet
──────────────────         ──────────────────────────────
Created on login           Deployed once on first sign-up
Expires after inactivity   Persists forever on Stellar
Revoked on logout          Unaffected by logout or expiry
Scoped to one device/tab   Accessible from any device
```

Deleting a session does not delete the wallet. Revoking a session does not remove assets. The wallet continues to exist on-chain regardless of session state.

## Common Questions

<AccordionGroup>
  <Accordion title="Does a new login create a new wallet?">
    No. Returning users authenticate and resolve their existing wallet. `authenticate()` returns the same wallet address on every successful login.
  </Accordion>

  <Accordion title="Does recovery create a new wallet?">
    No. Recovery updates the authentication credential stored in the existing wallet contract. The wallet, its address, and all its assets remain completely unchanged.
  </Accordion>

  <Accordion title="Can a wallet exist without an active session?">
    Yes. The wallet lives on-chain independently of any session. Sessions connect your application to the wallet temporarily; the wallet persists whether or not a session is active.
  </Accordion>

  <Accordion title="Can users lose assets during credential updates?">
    No. Credential rotation and recovery only touch the authentication state inside the wallet contract. Assets are never moved, transferred, or at risk during either operation.
  </Accordion>
</AccordionGroup>