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

# v14.5.0 — SHHH V8.4 is the new default

> What changed when chipi-stack v14.5.0 flipped the createWallet default from CHIPI v29 to SHHH V8.4 STARK, who's affected, and the safe upgrade path for existing integrations.

<Info>
  v14.5.0 ships SHHH V8.4 ShhhAccount as the new default wallet class —
  pluggable signer kinds, guardian recovery, threshold support — alongside
  every legacy CHIPI v29 + READY path. Existing wallets are unaffected;
  only NEW wallets created via `createWallet` without an explicit
  `walletType` see the change. SHHH V8.4 is available without being
  formally advertised until external audit closes.
</Info>

## TL;DR — does this affect me?

| Your setup                                                                               | Action you need to take                                                                                 |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Pinned to `@chipi-stack/backend@14.4.x` (or earlier)                                     | **None.** Default unchanged on the version you have. Upgrade when you're ready.                         |
| Upgrading to `@chipi-stack/backend@14.5.0` AND you pass `walletType: "CHIPI"` explicitly | **None.** Your CHIPI v29 wallets still produce CHIPI v29 wallets.                                       |
| Upgrading to `@chipi-stack/backend@14.5.0` AND you pass `walletType: "READY"`            | **None.** READY (Argent X v0.4.0) is unchanged.                                                         |
| Upgrading to `@chipi-stack/backend@14.5.0` AND you OMIT `walletType`                     | **Read this page.** New wallets now deploy as SHHH V8.4 with `signerKind: "STARK"` by default.          |
| Operating end-user wallets via the dashboard                                             | **None.** Your existing wallets keep working; new dashboard-created wallets default to SHHH V8.4 STARK. |

## What changed

In every version up to and including `@chipi-stack/backend@14.4.x`, omitting `walletType` from `createWallet` produced a CHIPI v29 wallet (legacy OpenZeppelin account with SNIP-9 session-keys support). As of `@chipi-stack/backend@14.5.0`, the same call produces a **SHHH V8.4** wallet with `signerKind: "STARK"`.

The wallet's address is computed differently for SHHH V8.4 (`computeShhhAddress`), so a wallet created with the new default has a different address than one created at the same `externalUserId` would have under the old default. **Address determinism IS preserved within the same default** — calling `createWallet` twice with the same inputs against v14.5.0 produces the same SHHH address.

The behavior matrix:

| Caller passes                                 | Pre-v14.5.0 result                                       | Post-v14.5.0 result                                                                                        |
| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Nothing (omits `walletType`)                  | CHIPI v29                                                | **SHHH V8.4 STARK** ← changed                                                                              |
| `walletType: "CHIPI"`                         | CHIPI v29                                                | CHIPI v29 (unchanged)                                                                                      |
| `walletType: "READY"`                         | READY                                                    | READY (unchanged)                                                                                          |
| `walletType: "SHHH"`, `signerKind: "STARK"`   | SHHH (opt-in, since the SHHH builders landed in the SDK) | SHHH (unchanged)                                                                                           |
| `walletType: "SHHH"` w/o `signerKind` (TS)    | implicit STARK                                           | implicit STARK                                                                                             |
| `wallet_type=SHHH` w/o `signer_kind` (Python) | ValueError                                               | **ValueError** (Python keeps the explicit-SHHH strictness; only the default-flip path falls back to STARK) |

## What you get for free

SHHH V8.4 closes the three biggest gaps the legacy CHIPI v29 had:

1. **Guardian recovery** — 7-day timelocked lost-key recovery without giving up custody. See [recovery](/services/gasless/recovery).
2. **Multi-device + multi-owner** — add a passkey or MetaMask owner to an existing wallet via a 48-hour timelocked `propose_add_owner` flow.
3. **Threshold (N-of-M)** — multi-owner approvals with mixed signer kinds. See [threshold](/services/gasless/threshold).

You also get the pluggable-signer model: a single account class dispatches to 10 verifier classes (`STARK`, `Ed25519`, `EIP-191`, `EIP-712`, `P-256`, `WebAuthn P-256`, `JWT ES256`, `JWT ES256 Apple Sub`, `BLS12-381`, `SECP256K1`). Browser onboarding can default to passkey-rooted Starknet wallets; EVM and Solana users can keep their existing wallets. See the [passkey API reference](/sdk/passkeys/api) for the browser-side surface.

## Sessions still work

If your app relies on SNIP-9 / SNIP-163 session keys (the canonical CHIPI v29 use case), **they work on SHHH V8.4 too.** V8.4 embeds the same SNIP-163 component; `executeTransactionWithSession`, `createSessionKey`, `addSessionKeyToContract`, and `revokeSessionKey` accept both `walletType: "CHIPI"` and `walletType: "SHHH"` wallets transparently as of v14.5.0.

## Three rollback levers

If something goes wrong:

1. **Pin your dependency** — keep `@chipi-stack/backend@14.4.x` until you're ready to upgrade. The default flip only affects integrators who actively bump.
2. **Pin `walletType: "CHIPI"`** — pass it explicitly on every `createWallet` call. The legacy v29 path is supported indefinitely.
3. **Server-side kill switch** — `chipi-back` honors a `CHIPI_SHHH_DEFAULT` env var. If your direct callers bypass the SDK and POST to `/chipi-wallets` without `walletType`, ops can force the legacy default back without a redeploy. See [chipi-back PR #267](https://github.com/chipi-pay/chipi-back/pull/267).

## Upgrade walkthrough

### TypeScript / Node

```bash theme={null}
pnpm add @chipi-stack/backend@^14.5.0
# or yarn / npm
```

If you want SHHH V8.4 explicitly (the new default):

```ts theme={null}
const wallet = await sdk.createWallet({
  params: {
    encryptKey,
    externalUserId,
    chain: Chain.STARKNET,
    // walletType omitted — defaults to SHHH V8.4 STARK
  },
  bearerToken,
});
// wallet.walletType === "SHHH"
// wallet.signerKind === "STARK"
```

If you want to keep producing legacy CHIPI v29 for now:

```ts theme={null}
const wallet = await sdk.createWallet({
  params: {
    encryptKey,
    externalUserId,
    chain: Chain.STARKNET,
    walletType: "CHIPI", // explicit — keeps the legacy default
  },
  bearerToken,
});
```

### Python

The Python package version is independent from the TypeScript fixed-version group. The default flip lands in `chipi-stack@2.1.0` (current floor on PyPI) — same release wave, separate version.

```bash theme={null}
uv add 'chipi-stack>=2.1.0'
# or pip
```

```python theme={null}
from chipi_sdk import CreateWalletParams, WalletType

# Defaults to SHHH V8.4 STARK (signer_kind fills in via the default-flip path).
result = await sdk.acreate_wallet(
    CreateWalletParams(
        encrypt_key=encrypt_key,
        external_user_id=external_user_id,
    ),
    bearer_token=bearer_token,
)

# Or, keep producing CHIPI v29:
result = await sdk.acreate_wallet(
    CreateWalletParams(
        encrypt_key=encrypt_key,
        external_user_id=external_user_id,
        wallet_type=WalletType.CHIPI,
    ),
    bearer_token=bearer_token,
)
```

Important Python-specific quirk: explicit `wallet_type=SHHH` WITHOUT `signer_kind` still raises `ValueError` (preserving the original opinionated check — Python has no browser context to default to `WEBAUTHN_P256`). Only the default-flip path (omitting `wallet_type`) falls back to STARK. This is intentional: integrators who explicitly opt into SHHH should pick a signer kind.

### React / Next.js / Expo

```bash theme={null}
pnpm add @chipi-stack/chipi-react@^14.5.0 @chipi-stack/nextjs@^14.5.0
# or @chipi-stack/chipi-expo for React Native
```

The `useCreateWallet` hook surface is unchanged. Same default-flip semantics — omit `walletType` to get SHHH V8.4 STARK, pass it explicitly to keep the legacy path.

## Migrating existing wallets

The default flip ONLY affects NEW wallets. Existing CHIPI v29 wallets keep working as-is and can be upgraded in place — without changing the wallet's address — via the migration flow.

If you want your existing user base to get recovery, multi-device, and threshold, see the [migration guide](/services/gasless/migration). The short version:

```tsx theme={null}
import { useMigrateWalletToShhh } from "@chipi-stack/chipi-react";

function MigrateButton({ wallet }) {
  const { migrateAsync, isLoading } = useMigrateWalletToShhh();

  async function onClick() {
    const encryptKey = await promptForPin();
    const outcome = await migrateAsync({
      walletId: wallet.id,
      externalUserId: user.id,
      wallet: {
        publicKey: wallet.publicKey,
        encryptedPrivateKey: wallet.encryptedPrivateKey,
      },
      encryptKey,
      bearerToken,
    });
    // outcome.kind: "MIGRATED" | "ALREADY_MIGRATED"
  }
}
```

This preserves the wallet's address — on-chain history, USDC balance, NFT ownership, external integrators (gift recipients, x402 sellers) don't need to update anything. The class hash flips from CHIPI v29 (`0x053f4f87…f459f2a`) to SHHH V8.4 (`0x075dfb39…fa58a`) atomically with a `bootstrap_from_sessions` call that rebuilds the owner set.

## Other v14.5.0 surfaces

The default flip is the headline change. The release also includes:

* **`@chipi-stack/chipi-passkey@2.2.0`** — `createShhhPasskey` + `signShhhMessage`: true WebAuthn P-256 signer, NO PRF. The private key never leaves the platform authenticator. Pairs with `signerKind: "WEBAUTHN_P256"` for SHHH wallets.
* **x402 SHHH support** — `X402ShhhClient` ships SHHH V8.4 buyers for HTTP 402 pay-per-request APIs. The facilitator detects SHHH payments and routes through the V8.4 dispatch path automatically.
* **Sessions on SHHH (TS + Python)** — `executeTransactionWithSession` accepts both CHIPI v29 and SHHH V8.4 wallets. Same 4-felt session signature shape on both.
* **Recovery + threshold React hooks** — `useGuardianRecovery`, `useThresholdSign`, and the `<Recover />` route component for shipping recovery / multi-device / threshold UIs.
* **PIN-is-weak warnings** — the canonical security note is now reachable from every onboarding entry point.

For the per-package PRs and source of every claim above, see:

* [`@chipi-stack/backend` repo PRs labeled v14.5.0](https://github.com/chipi-pay/sdks/pulls?q=label%3Av14.5.0)
* [Production mainnet smoke receipts](https://github.com/chipi-pay/sdks/tree/main/scripts/receipts)

## Posture

SHHH V8.4 is **available** in v14.5.0 — every code path ships for all 10 signer kinds. The server-side kinds that can run end-to-end on mainnet (STARK, ED25519, EIP-191) have signed live transactions on Starknet mainnet — receipts under [`scripts/receipts/cycle-2/`](https://github.com/chipi-pay/sdks/tree/main/scripts/receipts/cycle-2). Browser-rooted kinds (`WEBAUTHN_P256`) and Apple-Developer-gated kinds (`JWT_ES256_APPLE_SUB`) are smoke-tested with synthesized fixtures matching the on-chain verifier shape; their first real mainnet smoke needs a browser session or Apple Developer credentials respectively.

SHHH is **not yet formally advertised** until the external audit closes. Use it in production today; the audit-completion announcement will simply move SHHH from "available" to "recommended" without changing the SDK surface.

## Where to ask questions

If something on this page is wrong, ambiguous, or out of sync with what you're seeing in your integration, please open an issue at [`chipi-pay/sdks`](https://github.com/chipi-pay/sdks/issues) with the SDK version you're on and a minimal repro. Every speculative claim above is meant to be traceable to a specific source artifact; if you find one that isn't, that's a doc bug we want to fix.