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

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.

​

TL;DR — does this affect me?

​

What changed

​

What you get for free

1. Guardian recovery — 7-day timelocked lost-key recovery without giving up custody. See 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.

​

Sessions still work

​

Three rollback levers

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.

​

Upgrade walkthrough

​

TypeScript / Node

pnpm add @chipi-stack/backend@^14.5.0
# or yarn / npm

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"

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

​

Python

uv add 'chipi-stack>=2.1.0'
# or pip

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,
)

​

React / Next.js / Expo

pnpm add @chipi-stack/chipi-react@^14.5.0 @chipi-stack/nextjs@^14.5.0
# or @chipi-stack/chipi-expo for React Native

​

Migrating existing wallets

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"
  }
}

​

Other v14.5.0 surfaces

• @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.

• @chipi-stack/backend repo PRs labeled v14.5.0
• Production mainnet smoke receipts

​

Posture

​

Where to ask questions