Wallet Upgrades & Custom Accounts

Chipi wallets run as smart contracts on StarkNet. The "class hash" determines which contract code the wallet uses. Upgrading a wallet swaps its class hash to a newer or different implementation.

Common upgrade paths:

• - READY → CHIPI: Argent X wallets upgrading to Chipi's session-enabled account
• - CHIPI v29 → v33: Older Chipi wallets upgrading to the latest version with spending policy and audit fixes
• - Custom accounts: Deploy your own StarkNet account implementation

| Type | Description | Session Keys | Default | |------|-------------|-------------|---------| | CHIPI | Chipi session account (v33) | Yes | Yes | | READY | Argent X v0.4.0 | No | No | | Custom | Any SRC-6 account | Depends | No |

The current CHIPI default is v33 (0x0484bbd2404b3c7264bea271f7267d6d4004821ac7787a9eed7f472e79ef40d1). Verified on StarkNet mainnet.

Wallet upgrades require the API secret key — they must run on your server, not in the browser.

typescriptimport { ChipiSDK } from "@chipi-stack/backend";

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

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

// Step 2: User signs on client, sends signature to your backend

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

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

For custom account implementations, pass the classHash parameter when creating a wallet:

typescript// 99% of users — just use the default:
const wallet = await sdk.createWallet({
  params: { encryptKey: pin, externalUserId: userId, chain: "STARKNET" },
  bearerToken,
});

// Custom account — pass a class hash:
const wallet = await sdk.createWallet({
  params: {
    encryptKey: pin,
    externalUserId: userId,
    chain: "STARKNET",
    classHash: "0xYOUR_CLASS_HASH",
  },
  bearerToken,
});

Requirements for custom accounts:

• - Must be declared on StarkNet mainnet
• - Must implement SRC-6 (__validate__, __execute__)
• - SNIP-9 recommended for paymaster compatibility

The public account registry at github.com/chipi-pay/account-registry lists StarkNet account implementations compatible with Chipi.

Anyone can submit via PR. Submissions are validated against a JSON schema and verified on-chain.

The registry is informational — the SDK works without it. Custom class hashes can always be passed directly.