chipi-stack 2.1.0__tar.gz → 2.2.0__tar.gz

{chipi_stack-2.1.0/chipi_stack.egg-info → chipi_stack-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipi-stack
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for Starknet Gasless Transactions via Chipi
 Author-email: Carlos Castillo <carlos@chipipay.com>, Roberto Yamanaka <roberto@chipipay.com>
 License-Expression: MIT
@@ -25,6 +25,10 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: typing-extensions>=4.9.0
+Requires-Dist: poseidon-py>=0.1.5
+Requires-Dist: pycryptodome>=3.20.0
+Requires-Dist: garaga==1.1.0
+Requires-Dist: eth-keys>=0.5.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
@@ -75,6 +79,28 @@ uv add chipi-stack
   - `pydantic>=2.0.0` - Data validation
   - `httpx>=0.27.0` - HTTP client
   - `cryptography>=42.0.0` - AES encryption
+  - `garaga==1.1.0` - Cairo-compatible BN-curve math for SHHH Ed25519 signing
+  - `eth-keys>=0.5.0` - secp256k1 ECDSA for SHHH EIP-191 signing
+  - `poseidon-py>=0.1.5` - Poseidon hash (used by SHHH SNIP-12 envelopes)
+  - `pycryptodome>=3.20.0` - keccak256 (used by SHHH EIP-191)
+
+### macOS Apple Silicon installation note
+
+Garaga's BN-curve math links against libssl. On macOS 14 Sonoma+ on
+Apple Silicon, the system libssl can mis-link during the garaga build.
+If `pip install chipi-stack` fails with "library not loaded" or
+"Symbol not found" mentioning `libssl` / `libcrypto`, install OpenSSL 3
+via Homebrew and re-install:
+
+```bash
+brew install openssl@3
+export LDFLAGS="-L$(brew --prefix openssl@3)/lib"
+export CPPFLAGS="-I$(brew --prefix openssl@3)/include"
+pip install --force-reinstall chipi-stack
+```
+
+Linux and Intel Macs are unaffected. Windows is untested for the SHHH
+Ed25519 signer specifically; the rest of the SDK works on Windows.
 
 ## Quick Start
 

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/README.md

@@ -37,6 +37,28 @@ uv add chipi-stack
   - `pydantic>=2.0.0` - Data validation
   - `httpx>=0.27.0` - HTTP client
   - `cryptography>=42.0.0` - AES encryption
+  - `garaga==1.1.0` - Cairo-compatible BN-curve math for SHHH Ed25519 signing
+  - `eth-keys>=0.5.0` - secp256k1 ECDSA for SHHH EIP-191 signing
+  - `poseidon-py>=0.1.5` - Poseidon hash (used by SHHH SNIP-12 envelopes)
+  - `pycryptodome>=3.20.0` - keccak256 (used by SHHH EIP-191)
+
+### macOS Apple Silicon installation note
+
+Garaga's BN-curve math links against libssl. On macOS 14 Sonoma+ on
+Apple Silicon, the system libssl can mis-link during the garaga build.
+If `pip install chipi-stack` fails with "library not loaded" or
+"Symbol not found" mentioning `libssl` / `libcrypto`, install OpenSSL 3
+via Homebrew and re-install:
+
+```bash
+brew install openssl@3
+export LDFLAGS="-L$(brew --prefix openssl@3)/lib"
+export CPPFLAGS="-I$(brew --prefix openssl@3)/include"
+pip install --force-reinstall chipi-stack
+```
+
+Linux and Intel Macs are unaffected. Windows is untested for the SHHH
+Ed25519 signer specifically; the rest of the SDK works on Windows.
 
 ## Quick Start
 

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/chipi_sdk/__init__.py

@@ -46,6 +46,7 @@ from .models.wallet import (
     GetWalletResponse,
     PasskeyMetadata,
     PrepareWalletCreationResponse,
+    ShhhSignerKind,
     WalletData,
     WalletType,
     PrepareWalletUpgradeParams,
@@ -163,17 +164,22 @@ from .constants import (
     DEFAULT_PAGINATION,
     ERRORS,
     LEGACY_CHIPI_CLASS_HASHES,
+    LEGACY_SHHH_CLASS_HASHES,
     PAYMASTER_CONFIG,
     SERVICE_TYPES,
     SESSION_DEFAULTS,
     SESSION_ENTRYPOINTS,
     SESSION_ERRORS,
+    SHHH_ENVELOPE_TAGS,
+    SHHH_KIND_GAS_OVERHEAD,
+    SHHH_VERIFIER_CLASS_HASHES,
     SKU_CONTRACTS,
     STARKNET_NETWORKS,
     TOKEN_DECIMALS,
     WALLET_CLASS_HASHES,
     WALLET_RPC_ENDPOINTS,
     get_wallet_type_from_class_hash,
+    is_known_shhh_class_hash,
 )
 
 # Utilities
@@ -236,6 +242,7 @@ __all__ = [
     "PrepareWalletCreationResponse",
     "WalletData",
     "WalletType",
+    "ShhhSignerKind",
     "PrepareWalletUpgradeParams",
     "PrepareWalletUpgradeResponse",
     "ExecuteWalletUpgradeParams",
@@ -319,7 +326,12 @@ __all__ = [
     "TOKEN_DECIMALS",
     "WALLET_CLASS_HASHES",
     "LEGACY_CHIPI_CLASS_HASHES",
+    "LEGACY_SHHH_CLASS_HASHES",
+    "SHHH_ENVELOPE_TAGS",
+    "SHHH_KIND_GAS_OVERHEAD",
+    "SHHH_VERIFIER_CLASS_HASHES",
     "get_wallet_type_from_class_hash",
+    "is_known_shhh_class_hash",
     "WALLET_RPC_ENDPOINTS",
     # Utilities
     "camel_to_snake",

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/chipi_sdk/constants.py

@@ -1,7 +1,7 @@
 """Constants used across Chipi SDK."""
 
 from typing import Optional
-from .models.wallet import WalletType
+from .models.wallet import ShhhSignerKind, WalletType
 
 
 # API Versioning
@@ -95,6 +95,7 @@ CHAIN_TOKEN_TYPES = {
 WALLET_CLASS_HASHES: dict[WalletType, str] = {
     WalletType.CHIPI: "0x0484bbd2404b3c7264bea271f7267d6d4004821ac7787a9eed7f472e79ef40d1",  # v33 — latest, spending policy + audit fixes
     WalletType.READY: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f",
+    WalletType.SHHH: "0x075dfb396145926bffa6beb659897f46cc082a50b211d80871cff7f1038fa58a",  # V8.4 ShhhAccount — declared 2026-05-15, audit-closed
 }
 
 # Previous CHIPI wallet class hashes still deployed on-chain (newest → oldest)
@@ -106,6 +107,54 @@ LEGACY_CHIPI_CLASS_HASHES: list[str] = [
     "0x02de1565226d5215a38b68c4d9a4913989b54edff64c68c45e453c417b44cd83", # v28
 ]
 
+# Deprecated SHHH class hashes still deployed on-chain. V8 series ships
+# without an `upgrade` selector, so existing instances at deprecated classes
+# cannot self-upgrade — they redeploy at the current SHHH class hash.
+LEGACY_SHHH_CLASS_HASHES: list[str] = [
+    "0x03bc539295abd3e59bd9ea799d12fe3331748d484bc77bff45b302b1636a87d9",  # V8.3 — deprecated 2026-05-15
+]
+
+# SHHH ShhhAccount verifier class hashes (V8.4, mainnet).
+# Account dispatches `verify` to one of these via library_call_syscall based
+# on the owner's `kind_tag`. Chipi routes as consumer; we do not redeclare.
+SHHH_VERIFIER_CLASS_HASHES: dict[ShhhSignerKind, str] = {
+    ShhhSignerKind.STARK: "0x00d09209b2da9d49fc805ba26380ba4ce25aa641116c10eb178e1051a71dbf68",
+    ShhhSignerKind.ED25519: "0x030a7dfc03e59cef6e41699e734abd2df53ce393a052221c02c6e07665949f74",
+    ShhhSignerKind.SECP256K1: "0x03e81667a46bd5287e09a9600fa98d28fdc477735f2689f5f4e8e95f37b67b74",
+    ShhhSignerKind.EIP191_SECP256K1: "0x03a75997862059c36cb8e204fb3027eb6d1fdf933488d42c2db4528118d084e6",
+    ShhhSignerKind.EIP712_SECP256K1: "0x072a3f77e8c28bfea2ade91ec3fb83b6290169d1ed8c1b2396704231841c6474",
+    ShhhSignerKind.P256: "0x01b600709af54c8838e5f18ddad3a26feeb47cb124c239f55a0f1b7a780e2d8a",
+    ShhhSignerKind.WEBAUTHN_P256: "0x074f6efd2af9025cd8cab41a4565bc73b6ef097214c31352838fcdbac0a44657",
+    ShhhSignerKind.JWT_ES256: "0x002efce875fa3e73e04d825d8ebade53e188cc995dfe0c55a6a2f7fa6c59f497",
+    ShhhSignerKind.JWT_ES256_APPLE_SUB: "0x06b67762218a25fdd28e25b063480893a5cef9cdeecbc663e32d444d5734c471",
+    ShhhSignerKind.BLS12_381: "0x02623721e74a9ad3e0ba639065f5631a09bf900913de6ab21ea6984973cd2cd1",
+}
+
+# Upper-bound l2_gas overhead per SHHH signer kind, in addition to base
+# paymaster execution cost. Numbers from snforge runs at tag v8.4
+# (252-byte calls, single owner, no session key). Paymaster adds ~5M margin.
+# Threshold envelopes: sum the per-owner cost + ~3M aggregation overhead.
+# Session-key envelopes (SNIP-163 4-felt): ~2M + session-policy enforcement.
+SHHH_KIND_GAS_OVERHEAD: dict[ShhhSignerKind, int] = {
+    ShhhSignerKind.STARK: 2_000_000,
+    ShhhSignerKind.SECP256K1: 5_000_000,
+    ShhhSignerKind.EIP191_SECP256K1: 10_000_000,
+    ShhhSignerKind.EIP712_SECP256K1: 12_000_000,
+    ShhhSignerKind.P256: 30_000_000,
+    ShhhSignerKind.ED25519: 33_000_000,
+    ShhhSignerKind.WEBAUTHN_P256: 35_000_000,
+    ShhhSignerKind.JWT_ES256: 60_000_000,
+    ShhhSignerKind.JWT_ES256_APPLE_SUB: 62_000_000,
+    ShhhSignerKind.BLS12_381: 80_000_000,
+}
+
+# Inner-envelope routing tags per the V8.4 Pluggable-Signer SNIP draft.
+SHHH_ENVELOPE_TAGS = {
+    "V2_SNIP12": "V2_SNIP12",
+    "V2_THRESHOLD": "V2_THRESHOLD",
+    # Session-key envelopes are the SNIP-163 4-felt format (no version tag).
+}
+
 
 def get_wallet_type_from_class_hash(class_hash: str) -> Optional[str]:
     """
@@ -115,7 +164,7 @@ def get_wallet_type_from_class_hash(class_hash: str) -> Optional[str]:
         class_hash: Class hash to look up
 
     Returns:
-        Wallet type string ("CHIPI" or "READY"), or None if unknown
+        Wallet type string ("CHIPI", "READY", or "SHHH"), or None if unknown
     """
     def normalize(h: str) -> str:
         import re
@@ -129,12 +178,39 @@ def get_wallet_type_from_class_hash(class_hash: str) -> Optional[str]:
         return "CHIPI"
     if any(normalize(h) == normalized for h in LEGACY_CHIPI_CLASS_HASHES):
         return "CHIPI"
+    if normalize(WALLET_CLASS_HASHES[WalletType.SHHH]) == normalized:
+        return "SHHH"
+    if any(normalize(h) == normalized for h in LEGACY_SHHH_CLASS_HASHES):
+        return "SHHH"
     return None
 
+
+def is_known_shhh_class_hash(class_hash: str) -> bool:
+    """
+    True if a class hash is a registered SHHH ShhhAccount class (current or
+    legacy) OR one of the 10 V8.4 verifier classes. Used by the backend to
+    reject unknown class hashes when an integrator opts into SHHH via
+    wallet_type="SHHH" (plan D4 safety net — open SDK option, no per-org gate).
+    """
+    import re
+
+    def normalize(h: str) -> str:
+        return re.sub(r"^0x0+", "0x", h.lower())
+
+    normalized = normalize(class_hash)
+
+    if normalize(WALLET_CLASS_HASHES[WalletType.SHHH]) == normalized:
+        return True
+    if any(normalize(h) == normalized for h in LEGACY_SHHH_CLASS_HASHES):
+        return True
+    return any(normalize(h) == normalized for h in SHHH_VERIFIER_CLASS_HASHES.values())
+
+
 # RPC Endpoints per Wallet Type
 WALLET_RPC_ENDPOINTS: dict[WalletType, str] = {
     WalletType.CHIPI: "https://starknet-mainnet.public.blastapi.io/rpc/v0_7",
     WalletType.READY: "https://cloud.argent-api.com/v1/starknet/mainnet/rpc/v0.7",
+    WalletType.SHHH: "https://starknet-mainnet.public.blastapi.io/rpc/v0_7",
 }
 
 # Paymaster Configuration

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/chipi_sdk/execute_paymaster.py

@@ -58,6 +58,34 @@ async def execute_paymaster_transaction(
             )
             raise ValueError(error_msg)
 
+        # SHHH V8.4 ShhhAccount wallets cannot use the legacy
+        # prepare-typed-data → sign → execute-sponsored-transaction
+        # flow because the Chipi paymaster cannot synthesize SHHH
+        # envelopes server-side. Route SHHH OEs through the
+        # execute-sponsored-raw forwarder which expects pre-signed
+        # calldata. The legacy flow below is unchanged for
+        # CHIPI / READY.
+        if wallet.wallet_type == WalletType.SHHH:
+            from .shhh.execute_paymaster_raw import execute_shhh_sponsored_raw
+            from .shhh.snip12_hash import Call as ShhhCall
+
+            shhh_calls = [
+                ShhhCall(
+                    contract_address=c.get("contractAddress") or c.get("to"),
+                    entrypoint=c["entrypoint"],
+                    calldata=list(c.get("calldata") or []),
+                )
+                for c in calls
+            ]
+            return await execute_shhh_sponsored_raw(
+                client=client,
+                bearer_token=bearer_token,
+                wallet_public_key=wallet.public_key,
+                wallet_encrypted_private_key=wallet.encrypted_private_key,
+                encrypt_key=encrypt_key,
+                calls=shhh_calls,
+            )
+
         # Use READY RPC endpoint for now (matches TypeScript implementation)
         rpc_url = WALLET_RPC_ENDPOINTS[WalletType.READY]
         account_class_hash = WALLET_CLASS_HASHES[WalletType.READY]
@@ -168,6 +196,33 @@ def execute_paymaster_transaction_sync(
             )
             raise ValueError(error_msg)
 
+        # SHHH parity for the sync API. Sync callers with WalletType.SHHH
+        # would otherwise fall into the legacy prepare-typed-data flow,
+        # which the paymaster cannot synthesize an envelope for and
+        # returns TRANSACTION_EXECUTION_ERROR. Mirror the async branch
+        # above via execute_shhh_sponsored_raw_sync (shared payload
+        # construction, sync HTTP).
+        if wallet.wallet_type == WalletType.SHHH:
+            from .shhh.execute_paymaster_raw import execute_shhh_sponsored_raw_sync
+            from .shhh.snip12_hash import Call as ShhhCall
+
+            shhh_calls = [
+                ShhhCall(
+                    contract_address=c.get("contractAddress") or c.get("to"),
+                    entrypoint=c["entrypoint"],
+                    calldata=list(c.get("calldata") or []),
+                )
+                for c in calls
+            ]
+            return execute_shhh_sponsored_raw_sync(
+                client=client,
+                bearer_token=bearer_token,
+                wallet_public_key=wallet.public_key,
+                wallet_encrypted_private_key=wallet.encrypted_private_key,
+                encrypt_key=encrypt_key,
+                calls=shhh_calls,
+            )
+
         # Use READY account class hash (matches TypeScript implementation)
         account_class_hash = WALLET_CLASS_HASHES[WalletType.READY]
 
@@ -260,10 +315,15 @@ async def execute_paymaster_transaction_with_session(
         else:
             session = session_dict
 
-        # Validate this is a CHIPI wallet
-        if wallet.wallet_type and wallet.wallet_type != WalletType.CHIPI:
+        # Accept CHIPI v29 + SHHH V8.4 (both embed SNIP-163 sessions;
+        # the 4-felt session sig fast path at account.cairo:389 runs
+        # the same on either class).
+        if wallet.wallet_type and wallet.wallet_type not in (
+            WalletType.CHIPI,
+            WalletType.SHHH,
+        ):
             raise ChipiSessionError(
-                f"Session keys only work with CHIPI wallets. Got: {wallet.wallet_type}",
+                f"Session execution requires CHIPI or SHHH wallet type. Got: {wallet.wallet_type}",
                 SESSION_ERRORS["INVALID_WALLET_TYPE_FOR_SESSION"],
             )
 
@@ -275,6 +335,34 @@ async def execute_paymaster_transaction_with_session(
         if not session_private_key:
             raise ValueError("Failed to decrypt session private key")
 
+        # SHHH branch — route through V8.4 OE path with the 4-felt
+        # session sig (bypasses chipi-back's CHIPI-shaped
+        # prepare-typed-data + execute-sponsored-transaction). Mirrors
+        # the TypeScript SHHH branch shipped in sdks#288.
+        if wallet.wallet_type == WalletType.SHHH:
+            from .shhh.execute_paymaster_raw import (
+                execute_shhh_session_sponsored_raw,
+            )
+            from .shhh.snip12_hash import Call as ShhhCall
+
+            shhh_calls = [
+                ShhhCall(
+                    contract_address=c.get("contractAddress") or c.get("to"),
+                    entrypoint=c["entrypoint"],
+                    calldata=list(c.get("calldata") or []),
+                )
+                for c in calls
+            ]
+            return await execute_shhh_session_sponsored_raw(
+                client=client,
+                bearer_token=bearer_token,
+                wallet_public_key=wallet.public_key,
+                session_private_key=session_private_key,
+                session_public_key=session.public_key,
+                session_valid_until=session.valid_until,
+                calls=shhh_calls,
+            )
+
         # Use CHIPI RPC endpoint and class hash
         account_class_hash = WALLET_CLASS_HASHES[WalletType.CHIPI]
 
@@ -375,13 +463,47 @@ def execute_paymaster_transaction_with_session_sync(
         else:
             session = session_dict
 
-        # Validate this is a CHIPI wallet
-        if wallet.wallet_type and wallet.wallet_type != WalletType.CHIPI:
+        # Accept CHIPI v29 + SHHH V8.4 — see async path above for details.
+        if wallet.wallet_type and wallet.wallet_type not in (
+            WalletType.CHIPI,
+            WalletType.SHHH,
+        ):
             raise ChipiSessionError(
-                f"Session keys only work with CHIPI wallets. Got: {wallet.wallet_type}",
+                f"Session execution requires CHIPI or SHHH wallet type. Got: {wallet.wallet_type}",
                 SESSION_ERRORS["INVALID_WALLET_TYPE_FOR_SESSION"],
             )
 
+        # SHHH branch (sync) — same shape as the async path.
+        if wallet.wallet_type == WalletType.SHHH:
+            session_private_key_sync = decrypt_private_key(
+                session.encrypted_private_key, params["encryptKey"]
+            )
+            if not session_private_key_sync:
+                raise ValueError("Failed to decrypt session private key")
+
+            from .shhh.execute_paymaster_raw import (
+                execute_shhh_session_sponsored_raw_sync,
+            )
+            from .shhh.snip12_hash import Call as ShhhCall
+
+            shhh_calls = [
+                ShhhCall(
+                    contract_address=c.get("contractAddress") or c.get("to"),
+                    entrypoint=c["entrypoint"],
+                    calldata=list(c.get("calldata") or []),
+                )
+                for c in calls
+            ]
+            return execute_shhh_session_sponsored_raw_sync(
+                client=client,
+                bearer_token=bearer_token,
+                wallet_public_key=wallet.public_key,
+                session_private_key=session_private_key_sync,
+                session_public_key=session.public_key,
+                session_valid_until=session.valid_until,
+                calls=shhh_calls,
+            )
+
         # Use CHIPI account class hash
         account_class_hash = WALLET_CLASS_HASHES[WalletType.CHIPI]
 

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/chipi_sdk/models/__init__.py

@@ -23,6 +23,7 @@ from .wallet import (
     GetWalletResponse,
     PasskeyMetadata,
     PrepareWalletCreationResponse,
+    ShhhSignerKind,
     WalletData,
     WalletType,
 )
@@ -101,6 +102,7 @@ __all__ = [
     "GetWalletResponse",
     "PasskeyMetadata",
     "PrepareWalletCreationResponse",
+    "ShhhSignerKind",
     "WalletData",
     "WalletType",
     # Transaction

{chipi_stack-2.1.0 → chipi_stack-2.2.0}/chipi_sdk/models/wallet.py

@@ -17,12 +17,41 @@ def to_camel(string: str) -> str:
 class WalletType(str, Enum):
     """
     Supported wallet types.
-    
-    - CHIPI: OpenZeppelin account with SNIP-9 session keys support (default)
-    - READY: Argent X Account v0.4.0
+
+    - CHIPI: OpenZeppelin account with SNIP-9 session keys support (legacy v29).
+    - READY: Argent X Account v0.4.0.
+    - SHHH (default post-P2.2): V8.4 ShhhAccount — pluggable-signer
+      Starknet account dispatching to one of 10 verifier classes (STARK,
+      ED25519, SECP256K1, EIP191/EIP712, P256, WEBAUTHN_P256, JWT_ES256,
+      JWT_ES256_APPLE_SUB, BLS12_381). Requires CHIPI_SHHH_ENABLED on
+      the backend.
     """
     CHIPI = "CHIPI"
     READY = "READY"
+    SHHH = "SHHH"
+
+
+class ShhhSignerKind(str, Enum):
+    """
+    SHHH signer kinds (V8.4 ShhhAccount). The `kind_tag` value the account
+    uses to dispatch `verify` to the matching verifier class via
+    library_call_syscall. See SHHH_VERIFIER_CLASS_HASHES and
+    SHHH_KIND_GAS_OVERHEAD in chipi_sdk.constants.
+
+    No WebAuthn signer in Python — server-side only; WebAuthn requires a
+    browser/RN context. Wallet creation with wallet_type=SHHH and no
+    signer_kind raises in Python (per plan D10).
+    """
+    STARK = "STARK"
+    ED25519 = "ED25519"
+    SECP256K1 = "SECP256K1"
+    EIP191_SECP256K1 = "EIP191_SECP256K1"
+    EIP712_SECP256K1 = "EIP712_SECP256K1"
+    P256 = "P256"
+    WEBAUTHN_P256 = "WEBAUTHN_P256"
+    JWT_ES256 = "JWT_ES256"
+    JWT_ES256_APPLE_SUB = "JWT_ES256_APPLE_SUB"
+    BLS12_381 = "BLS12_381"
 
 
 class WalletData(BaseModel):
@@ -47,12 +76,36 @@ class DeploymentData(BaseModel):
 
 class CreateWalletParams(BaseModel):
     """Parameters for creating a new wallet."""
-    
+
     encrypt_key: Optional[str] = Field(None, description="Encryption key for private key")
     external_user_id: str = Field(..., description="External user identifier")
     user_id: Optional[str] = Field(None, description="Internal user ID")
-    wallet_type: Optional[WalletType] = Field(WalletType.CHIPI, description="Type of wallet to create")
+    # P2.2 default flip (re-applied 2026-05-29 after #270 revert and the
+    # post-revert SHHH bug-fix run). Mirrors the TS SDK default and
+    # matches every production mainnet smoke from 2026-05-26 onward.
+    # Callers who explicitly pass wallet_type=CHIPI / READY are
+    # unaffected.
+    wallet_type: Optional[WalletType] = Field(
+        WalletType.SHHH,
+        description="Type of wallet to create (defaults to SHHH V8.4 post-P2.2)",
+    )
     use_passkey: Optional[bool] = Field(False, description="Whether to use passkey authentication")
+    signer_kind: Optional[ShhhSignerKind] = Field(
+        None,
+        description=(
+            "Required when wallet_type=SHHH is set EXPLICITLY. When SHHH "
+            "is reached via the default-flip (caller omitted wallet_type), "
+            "the SDK falls back to STARK to match the TS SDK and the live "
+            "on-chain smokes. Wallet CREATION from Python currently "
+            "supports STARK only — non-STARK kinds (ED25519, "
+            "EIP191_SECP256K1, etc.) raise NotImplementedError at create "
+            "time and will be enabled by a follow-up PR that adds the "
+            "external-rooted (MetaMask, Phantom, Apple) wallet-adapter "
+            "deploy paths. The chipi_sdk.shhh envelope BUILDERS for those "
+            "kinds remain usable today for signing OEs on existing SHHH "
+            "wallets (see chipi_sdk.shhh.signers)."
+        ),
+    )
 
 
 class GetWalletResponse(BaseModel):