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

# Wallet Upgrades

> How to upgrade wallets between types and versions — READY to CHIPI, or CHIPI v29 to v33.

## Overview

Wallet upgrades change a wallet's on-chain account contract. Common upgrade paths:

* **READY to CHIPI**: Argent X wallets upgrading to Chipi's session-enabled account
* **CHIPI v29 to v33**: Older Chipi wallets upgrading to the latest version with spending policy and audit fixes

<Note>Wallet upgrades are server-only operations that require the API secret key. They cannot be performed from frontend hooks.</Note>

## How It Works

The upgrade is a two-step process:

1. **Prepare**: Call `prepareWalletUpgrade()` to get SNIP-12 typed data describing the upgrade
2. **Sign and Execute**: Have the wallet owner sign the typed data, then call `executeWalletUpgrade()` with the signature

The backend handles the actual `upgrade` syscall on StarkNet.

## READY to CHIPI Upgrade

Upgrade an Argent X wallet to a Chipi session-enabled wallet:

```typescript theme={null}
import { ChipiSDK } from "@chipi-stack/backend";

const sdk = new ChipiSDK({
  apiPublicKey: "pk_prod_...",
  apiSecretKey: "sk_prod_...",
});

// Step 1: Prepare
const upgrade = await sdk.prepareWalletUpgrade({
  walletAddress: "0x04abc...def",
});

console.log(upgrade.currentWalletType); // "READY"
console.log(upgrade.targetWalletType);  // "CHIPI"

// Step 2: Sign (with user's private key)
const signature = await account.signMessage(upgrade.typedData);

// Step 3: Execute
const result = await sdk.executeWalletUpgrade({
  walletAddress: "0x04abc...def",
  typedData: upgrade.typedData,
  signature: [signature.r.toString(), signature.s.toString()],
});

console.log(result.transactionHash);
console.log(result.newWalletType); // "CHIPI"
```

## CHIPI Version Upgrade

Upgrade an older CHIPI wallet (e.g., v29) to the latest version (v33):

```typescript theme={null}
const upgrade = await sdk.prepareWalletUpgrade({
  walletAddress: "0x04abc...def",
  // No targetClassHash needed — defaults to latest CHIPI (v33)
});

console.log(upgrade.currentWalletType); // "CHIPI"
console.log(upgrade.targetWalletType);  // "CHIPI" (same type, newer version)
```

## Custom Class Hash

To upgrade to a specific class hash (e.g., a community-submitted account):

```typescript theme={null}
const upgrade = await sdk.prepareWalletUpgrade({
  walletAddress: "0x04abc...def",
  targetClassHash: "0x0484bbd...", // specific version
});
```

## Python

```python theme={null}
from chipi_sdk import ChipiSDK, ChipiSDKConfig, PrepareWalletUpgradeParams, ExecuteWalletUpgradeParams

sdk = ChipiSDK(config=ChipiSDKConfig(
    api_public_key="pk_prod_...",
    api_secret_key="sk_prod_...",
))

# Prepare
upgrade = sdk.prepare_wallet_upgrade(
    PrepareWalletUpgradeParams(wallet_address="0x04abc...def")
)

# Sign (with user's key) then execute
result = sdk.execute_wallet_upgrade(
    ExecuteWalletUpgradeParams(
        wallet_address="0x04abc...def",
        typed_data=upgrade.typed_data,
        signature=["0xr", "0xs"],
    )
)
print(f"Upgraded: {result.transaction_hash}")
```

## After Upgrade

After a successful upgrade:

* The wallet's class hash changes on-chain
* Session keys become available (if upgrading from READY to CHIPI)
* Existing balances and transaction history are preserved
* The wallet address stays the same