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

# Smart Wallets: Programmable On-Chain Accounts on Soroban

> What makes SocketFi wallets smart — programmable policies, passkey authorization, built-in recovery, fee abstraction, and Soroban contract execution.

Every SocketFi wallet is a Soroban smart contract, not a traditional externally owned account (EOA). That distinction matters. A traditional wallet is just a private key that can sign anything — it has no logic, no rules, and no built-in safety nets. A SocketFi smart wallet is a programmable account that verifies passkey signatures, enforces spending policies, manages its own nonce state, supports credential rotation, and enables account recovery — all enforced on-chain by the contract itself, not by any off-chain service.

## Traditional Wallet vs Smart Wallet

| Capability               | Traditional Wallet  | SocketFi Smart Wallet    |
| ------------------------ | ------------------- | ------------------------ |
| Hold and transfer assets | ✅ Yes               | ✅ Yes                    |
| Sign transactions        | ✅ Yes               | ✅ Yes                    |
| Policy enforcement       | ❌ No                | ✅ Yes                    |
| Spending limits          | ❌ No                | ✅ Yes                    |
| Contract restrictions    | ❌ No                | ✅ Yes                    |
| Account recovery         | ⚠️ Seed phrase only | ✅ Native, no seed phrase |
| Fee abstraction          | ❌ No                | ✅ Yes                    |
| Replay protection        | ❌ External          | ✅ Built-in nonce system  |
| Passkey authorization    | ❌ No                | ✅ Yes                    |
| Credential rotation      | ❌ No                | ✅ Yes                    |

## Five Wallet Capabilities

A SocketFi smart wallet is composed of five capabilities that work together to process every request:

<CardGroup cols={2}>
  <Card title="Authorization Engine" icon="shield-check">
    Verifies that every state-changing operation is accompanied by a valid passkey signature, a correct sequential nonce, and a non-expired authorization window. If any check fails, execution stops immediately.
  </Card>

  <Card title="Policy Engine" icon="list-check">
    Evaluates the wallet's configured policies — spending limits, allowed contracts, time windows — after authorization passes but before execution. All policies must pass; any single failure blocks the transaction.
  </Card>

  <Card title="Fee Engine" icon="coins">
    Manages transaction fee calculation, collection, deferred fee tracking, and settlement. Supports fee abstraction so users are not required to hold XLM to pay for operations.
  </Card>

  <Card title="Recovery Engine" icon="rotate-left">
    Handles the credential replacement logic for account recovery flows. Enforces identity verification requirements and authorization rules before updating the wallet's bound credential.
  </Card>

  <Card title="Wallet State" icon="database">
    Maintains the on-chain state that all other engines read and write: the bound credential, policy configuration, nonce counter, recovery configuration, and fee state.
  </Card>
</CardGroup>

## How Authorization Flows Through the Wallet

When your application calls `requestTransaction()`, the request travels through each engine in sequence:

```text theme={null}
requestTransaction({ contractId, method, args })
  ↓
Authorization Engine   ← verify passkey signature, nonce, expiration
  ↓
Policy Engine          ← evaluate spending limits, contract allowlist, etc.
  ↓
Fee Engine             ← calculate and collect fees
  ↓
Execution              ← invoke the Soroban contract
  ↓
Wallet State updated   ← increment nonce, update policy counters
```

Failure at any stage stops execution and returns an error to your application. The wallet state is only updated after successful execution.

## Requesting a Transaction

Submitting a transaction through the SDK requires only the contract target, method name, and arguments. The SDK handles authorization message construction, prompts the user for their passkey signature, and submits the authorized transaction to the network.

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

async function transferTokens(recipient: string, amount: bigint) {
  const result = await socketfi.requestTransaction({
    contractId: "CCONTRACTADDRESS...",
    method: "transfer",
    args: {
      to: recipient,
      amount: amount,
    },
  });

  if (result.success) {
    console.log("Transaction hash:", result.transactionHash);
  }

  return result;
}
```

<Note>
  Your application never constructs or handles raw passkey signatures. The SDK manages the full authorization flow internally — building the authorization message, invoking the passkey prompt on the user's device, and submitting the signed transaction.
</Note>

## Wallet Lifecycle and State

Smart wallet state evolves over the wallet's lifetime. Here is how state changes across key lifecycle events:

| Lifecycle Event      | State Changes                                                                   |
| -------------------- | ------------------------------------------------------------------------------- |
| Wallet created       | Credential bound, nonce set to 0, recovery configured, default policies applied |
| Transaction executed | Nonce incremented, policy counters updated                                      |
| Policy updated       | Policy config in wallet state updated (requires authorization)                  |
| Credential rotation  | Bound credential replaced (requires current credential authorization)           |
| Account recovery     | Bound credential replaced (requires recovery authorization)                     |

The wallet address — `CDXXXXX...` — is set at deployment and never changes across any of these events.

## Contract Awareness

Because SocketFi wallets are themselves Soroban contracts, they can participate in contract-to-contract interactions with full authorization awareness. When your wallet invokes another contract, the wallet contract propagates authorization context through the call chain:

```text theme={null}
Your application
  ↓
SocketFi wallet contract
  ↓
DeFi protocol contract A
  ↓
Liquidity pool contract B
```

The wallet verifies authorization before forwarding execution to any downstream contract. This means complex multi-step interactions are as secure as simple transfers — the wallet remains the enforcement layer throughout.