Skip to main content
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.
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.

​
The Six Phases

1

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.
The wallet address is assigned here and never changes.
2

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
3

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.
Each transaction requires an explicit passkey-signed authorization. The wallet’s nonce increments with every executed operation, preventing replay.
4

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.
What changes: the bound passkey credential
What stays the same: wallet address, all assets, policies, transaction history, ownership
Credential rotation requires the user to still have access to their current passkey. If the passkey is already lost, use account recovery instead.
5

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.
Before recovery: wallet CDXXXXXXXXXX..., 500 USDC, passkey A
After recovery: wallet CDXXXXXXXXXX..., 500 USDC, passkey BThe wallet is identical. Only the authentication credential changed.
6

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.

​
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:

​
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.
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

No. Returning users authenticate and resolve their existing wallet. authenticate() returns the same wallet address on every successful login.
No. Recovery updates the authentication credential stored in the existing wallet contract. The wallet, its address, and all its assets remain completely unchanged.
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.
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.