> ## 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 Creation: From Sign-Up to Active Smart Wallet

> How SocketFi automatically handles passkey registration, smart contract deployment, credential binding, and wallet activation in a single SDK call.

When a new user signs up through your application, SocketFi does not ask them to create a wallet. The wallet is created for them automatically as part of the authentication flow. A single SDK call — `await socketfi.authenticate()` — handles passkey registration, deploys a Soroban smart contract wallet, binds the credential to that wallet, and returns a session. By the time control returns to your application, the user already owns a fully functional non-custodial smart wallet with a stable `CDXXXXX...` address.

## Creation Flow

<Steps>
  <Step title="Passkey Registration">
    The user's device creates a WebAuthn credential during sign-up. Supported authenticators include Face ID, Touch ID, Windows Hello, Android Passkeys, and hardware security keys. Private key material never leaves the device — only the public credential is transmitted.

    ```text theme={null}
    User device
      ↓
    Create WebAuthn credential
      ↓
    Return: Credential ID + Public Key + Attestation
    ```
  </Step>

  <Step title="Credential Verification">
    SocketFi verifies the WebAuthn registration response: challenge integrity, authenticator signature, and attestation data. Only verified credentials proceed to wallet deployment.

    ```text theme={null}
    Verify challenge response
      ↓
    Verify authenticator signature
      ↓
    Accept registration
    ```
  </Step>

  <Step title="Smart Wallet Deployment">
    Once the credential is verified, SocketFi deploys a new Soroban smart contract wallet on the Stellar network. Each wallet is independent — users never share contracts.

    ```text theme={null}
    Verified credential
      ↓
    Deploy Soroban smart contract
      ↓
    Generate stable wallet address: CDXXXXXXXXXX...
    ```

    <Note>
      The wallet address is globally unique, permanent, and starts with `CD`. It never changes — not after credential rotation, not after account recovery.
    </Note>
  </Step>

  <Step title="Credential Binding">
    The verified passkey is bound to the deployed wallet as its primary authorization credential. Future wallet operations require a signature from this bound credential.

    ```text theme={null}
    Wallet contract
      ↓
    Bind primary passkey credential
    ```
  </Step>

  <Step title="Wallet Activation">
    The wallet is initialized with its default on-chain state and becomes active. The wallet can now receive assets, execute transactions, interact with Soroban contracts, and enforce policies.
  </Step>

  <Step title="Session Created">
    With the wallet active, SocketFi creates a session and returns it to your application. The user is authenticated and their wallet is immediately ready for use.

    ```typescript theme={null}
    const session = await socketfi.authenticate();
    // session.userProfile.id       → your user's identifier
    // session.socketfiAccessToken  → session token for backend verification
    ```
  </Step>
</Steps>

## The SDK Call That Does It All

From your application's perspective, the entire six-step flow above is a single awaited call:

```typescript theme={null}
import { socketfi } from "./socketfi";

async function handleSignUp() {
  const session = await socketfi.authenticate();

  // For new users: passkey created, wallet deployed, session returned.
  // For returning users: passkey verified, existing wallet resolved, session returned.
  // Your code never needs to distinguish between the two.

  console.log("User ID:", session.userProfile.id);
  return session;
}
```

<Tip>
  The same `authenticate()` call handles both new and returning users. For returning users it resolves the existing wallet rather than deploying a new one — your integration code is identical in both cases.
</Tip>

## Default Wallet State

Every newly created wallet is initialized with the following on-chain state:

| State Component     | Purpose                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Auth Credential** | The bound passkey public key that authorizes wallet operations                            |
| **Recovery Config** | Pre-configured recovery state so account recovery is available from day one               |
| **Nonce State**     | Sequential nonce counter initialized at `0` to prevent replay attacks                     |
| **Policy Config**   | Default policy set; can be extended with spending limits, contract restrictions, and more |

<Note>
  Recovery is configured during wallet creation — not retroactively. This means every wallet supports account recovery from the moment it is activated, without requiring migration.
</Note>

## Wallet Address Properties

The wallet address assigned during deployment has four important properties:

* **Globally unique** — no two wallets share an address
* **Persistent** — the address never changes over the wallet's lifetime
* **Chain-verifiable** — anyone can inspect the wallet contract at that address on Stellar
* **Stable across updates** — credential rotation and account recovery leave the address unchanged

You can safely treat the wallet address as the canonical identity for a user in your backend systems.

## What Can Fail

Wallet creation can fail at several stages. Your application should handle these cases gracefully:

<AccordionGroup>
  <Accordion title="Failed passkey registration">
    The user declined the passkey prompt, the authenticator timed out, or the device does not support WebAuthn. Prompt the user to retry or check device compatibility.
  </Accordion>

  <Accordion title="Credential verification failure">
    The registration response did not pass server-side verification. This is rare and typically indicates a tampered response or network issue. Restart the registration flow.
  </Accordion>

  <Accordion title="Wallet deployment failure">
    The Soroban deployment transaction failed — usually due to a transient network condition. Retry after a brief delay; the deployment is idempotent if the credential was not already bound.
  </Accordion>
</AccordionGroup>