Skip to main content

​
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
Wallet upgrades are server-only operations that require the API secret key. They cannot be performed from frontend hooks.

​
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: 
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): 
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): 
const upgrade = await sdk.prepareWalletUpgrade({
  walletAddress: "0x04abc...def",
  targetClassHash: "0x0484bbd...", // specific version
});

​
Python

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