> ## 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 Policies: Programmable On-Chain Transaction Rules

> Configure spending limits, contract restrictions, and time windows that the wallet enforces on-chain — plus recovery controls and fee policies.

Wallet policies are rules stored in the wallet's on-chain state that the smart contract evaluates before executing any transaction. A valid passkey signature is necessary to authorize a transaction, but it is not sufficient — every active policy must also pass. Policies give you fine-grained control over what an authorized user can do, adding a programmable safety layer that protects users from accidental overspending, interaction with unapproved contracts, or other undesirable wallet behavior.

## Why Policies Exist

A traditional wallet has no concept of policy: a valid signature equals execution. SocketFi smart wallets separate the authorization question (*who is signing?*) from the policy question (*should this be allowed?*):

```text theme={null}
Traditional wallet:
  Valid signature → Execute

SocketFi smart wallet:
  Valid signature → Policy evaluation → Execute (only if all policies pass)
```

This means even a fully authenticated user can be protected by wallet-level rules they or your application configured. Policies are enforced by the on-chain contract, so they cannot be bypassed at the application layer.

## Policy Categories

SocketFi wallets support five categories of policy:

### Spending Limits

Restrict the total value that can leave the wallet over a rolling time window. Spending limits can be applied globally or per-asset.

```text theme={null}
Policy: max 500 USDC per day

Transaction: transfer 200 USDC  →  200 < 500  ✅ Allowed
Transaction: transfer 350 USDC  →  200 + 350 > 500  ❌ Rejected
```

### Contract Restrictions

Maintain an allowlist of Soroban contract addresses the wallet may interact with. Any invocation targeting a contract not on the list is rejected before execution.

```text theme={null}
Allowed contracts:
  CCONTRACT_A...
  CCONTRACT_B...

Transaction: invoke CCONTRACT_A...  ✅ Allowed
Transaction: invoke CCONTRACT_X...  ❌ Rejected (not on allowlist)
```

### Authorization Rules

Introduce additional authorization requirements for specific operation types. For example, you might require extra verification for transfers above a high-value threshold, or restrict which wallet operations are available to a specific session type.

### Recovery Controls

Govern when and how account recovery may proceed. Examples include mandatory waiting periods between a recovery request and execution, approval thresholds, or restrictions on who may initiate recovery.

### Fee Controls

Limit the maximum fee a transaction may consume, restrict which assets may be used to pay fees, or cap deferred fee balances. Transactions that would exceed fee policy are rejected before submission.

## Policy Evaluation Order

Policies are evaluated after authorization passes but before any execution occurs. The evaluation order is:

```text theme={null}
① Verify signature (Authorization Engine)
② Verify nonce     (Authorization Engine)
③ Verify expiration (Authorization Engine)
─────────────────────────────────────────
④ Evaluate Spending Limit policies    (Policy Engine)
⑤ Evaluate Contract Restriction policies
⑥ Evaluate Authorization Rule policies
⑦ Evaluate Fee Control policies
⑧ Evaluate Recovery Control policies (only for recovery ops)
─────────────────────────────────────────
⑨ Execute
```

Every policy must pass. If any single policy fails, execution stops immediately and the wallet state is not changed.

## Multiple Policies

Wallets can have multiple active policies of the same or different categories. All must pass for a transaction to execute:

```text theme={null}
Policy 1: Spending limit — max 500 USDC/day
Policy 2: Contract allowlist — only contracts A, B, C
Policy 3: Fee limit — max 0.1 XLM per transaction

Transaction: transfer 200 USDC to CCONTRACT_A...

  Policy 1: 200 USDC ≤ 500 USDC daily limit  ✅
  Policy 2: CCONTRACT_A is on the allowlist   ✅
  Policy 3: Fee = 0.05 XLM ≤ 0.1 XLM         ✅

→ Execute
```

```text theme={null}
Transaction: transfer 200 USDC to CCONTRACT_X...

  Policy 1: 200 USDC ≤ 500 USDC daily limit  ✅
  Policy 2: CCONTRACT_X is NOT on allowlist   ❌

→ Reject immediately (Policy 3 is never evaluated)
```

<Warning>
  Any single policy failure stops execution immediately. The remaining policies in the evaluation chain are not checked. Design your policy set with this in mind — a policy that fires frequently for legitimate transactions will block those transactions entirely.
</Warning>

## Wallet Policy Profiles

Different applications call for different policy configurations. Here are three common profiles to use as starting points:

<AccordionGroup>
  <Accordion title="Consumer Wallet">
    Focused on protecting everyday users from accidental large transfers and phishing.

    ```text theme={null}
    Spending limit:        500 USDC / day
    Contract allowlist:    [app contract, DEX contract]
    Fee limit:             0.5 XLM / transaction
    ```

    This profile lets users do everything they need for normal app usage while capping potential loss from a compromised session.
  </Accordion>

  <Accordion title="Gaming Wallet">
    Locked to the game's own contract ecosystem to prevent assets from being moved outside the game environment.

    ```text theme={null}
    Contract allowlist:    [game items contract, marketplace contract]
    Spending limit:        1000 game tokens / day
    Contract restriction:  block all contracts not on allowlist
    ```

    Players can trade within the game freely, but no external contract can drain the wallet.
  </Accordion>

  <Accordion title="Fintech Wallet">
    Designed for high-value transactions with additional controls on large transfers and fee exposure.

    ```text theme={null}
    Spending limit:        10,000 USDC / day
    High-value threshold:  additional authorization required above 2,500 USDC
    Fee limit:             1.0 XLM / transaction
    Contract allowlist:    [payment processor, custody contract]
    ```

    Routine transactions proceed normally. High-value transfers trigger additional authorization steps.
  </Accordion>
</AccordionGroup>

## Updating Policies

Policy updates are themselves protected wallet operations. They require a valid authorization from the wallet's bound credential — just like any other state-changing operation.

```typescript theme={null}
// Update a spending limit policy (SDK handles authorization internally)
const result = await socketfi.requestTransaction({
  contractId: walletAddress,
  method: "update_policy",
  args: {
    policyType: "spending_limit",
    asset: "USDC",
    limitPerDay: 1000n,
  },
});
```

<Note>
  Because policy updates require wallet authorization, a compromised session cannot silently remove safety policies. The passkey holder must explicitly approve any policy change.
</Note>

## Policy Failure Reasons

| Failure                     | Cause                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------- |
| **Spending limit exceeded** | The requested transfer would push the rolling window spend over the configured limit  |
| **Contract not allowed**    | The target contract is not on the wallet's allowlist                                  |
| **Fee limit exceeded**      | The transaction fee exceeds the configured maximum                                    |
| **Recovery rule violated**  | A recovery operation does not meet configured waiting period or approval requirements |
| **Time restriction active** | The operation is outside the configured time window                                   |