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.
Available without advertisement until external audit closes. The on-chain
classes are live on Starknet mainnet and have been smoke-tested end-to-end
(STARK, Ed25519, EIP-191, WebAuthn P-256, Apple JWT) — see
scripts/receipts/.
What “signer kind” means
A SHHH V8.4 wallet stores owners, not a fixed key shape. Each owner has akind_tag that the account uses to dispatch signature verification to the matching verifier class via Starknet’s library_call_syscall. That means one wallet can hold owners of different kinds simultaneously — the headline use case is a passkey on a phone plus a MetaMask on a laptop, both controlling the same wallet.
The SDK’s walletType: "SHHH" plus a signerKind selects which verifier the primary owner uses at wallet creation. Additional owners (with the same or different kinds) can be added later via recovery’s propose_add_owner flow.
Available kinds
signerKind | Verifier | Cycle 1 status | Use it for |
|---|---|---|---|
STARK | ECDSA on STARK curve | Default — shipped + smoked | Server-held key, programmatic wallets, fastest gas |
ED25519 | Ed25519 | Shipped + smoked | Phantom (Solana) users importing to Starknet |
EIP191_SECP256K1 | secp256k1 + EIP-191 personal_sign | Shipped + smoked | MetaMask / any EVM-rooted wallet |
WEBAUTHN_P256 | P-256 over WebAuthn assertions | Shipped (browser) | Platform passkeys — Touch ID / Face ID / Windows Hello / Android biometrics |
JWT_ES256_APPLE_SUB | ES256 over Apple’s id_token | Shipped + smoked | ”Sign in with Apple” rooted Starknet wallet |
JWT_ES256 | Generic ES256 over JWT | Wave C | Service-account auth (machine-to-machine) |
SECP256K1 | Raw secp256k1 ECDSA | Wave C | Bitcoin / Cosmos / raw secp256k1 keys |
EIP712_SECP256K1 | secp256k1 + EIP-712 | Wave C | EIP-712-signed payloads from EVM wallets |
P256 | Raw P-256 (no WebAuthn) | Wave C | Hardware tokens / YubiKeys / SE-bound keys |
BLS12_381 | BLS12-381 | Wave D | Committee multisig (Ethereum validator-style) |
Picking a kind
Browser / Expo onboarding — use a passkey
WEBAUTHN_P256 is the default for new SHHH wallets in browser and Expo:
walletType: "SHHH" + signerKind: "WEBAUTHN_P256" is implied.
EVM user importing to Starknet — EIP191_SECP256K1
If the user already has MetaMask (or any wallet that implements personal_sign), use their existing key as the SHHH owner:
Solana user importing to Starknet — ED25519
Same pattern: the integrator’s Phantom adapter signs the 32-byte messageHash via the wallet’s signMessage API; the SDK wraps the raw signature into the SHHH envelope. Phantom does NOT expose the private key (and the SDK does not need it) — the adapter returns the signature directly.
buildEd25519Envelope({ privateKey, messageHash }) builder is also available — that path keeps the key inside the SDK. The Phantom flow above is the headline browser path.
Server / programmatic — STARK
For wallets you control server-side (gift-card recipients, AI agents, internal automations), STARK is the fastest path. The SDK holds the encrypted STARK key and decrypts it server-side with the org’s encryption key.
iOS-first consumer flows — JWT_ES256_APPLE_SUB
Bind a Starknet wallet to a specific sub claim from “Sign in with Apple”. Multi-tenant friendly: the verifier checks the claim AND the Apple team’s signing key. Use for LATAM iOS users who don’t have MetaMask but do have Apple IDs.
Gas overhead [#gas-overhead]
The paymaster reserves gas per signer kind. Heavier curves cost more L2 gas to verify on chain:| Kind | l2_gas overhead | Comment |
|---|---|---|
| STARK | 2M | Cheapest — native curve |
| SECP256K1 | 5M | |
| EIP191_SECP256K1 | 10M | secp256k1 + 32-byte BE re-encode |
| EIP712_SECP256K1 | 12M | secp256k1 + EIP-712 hashing |
| P256 | 30M | |
| ED25519 | 33M | |
| WEBAUTHN_P256 | 35M | P-256 + SHA-256 over clientDataJSON |
| JWT_ES256 | 60M | ES256 + JWT header/payload parse |
| JWT_ES256_APPLE_SUB | 62M | ES256 + sub extraction |
| BLS12_381 | 80M | Pairing-heavy |
Self-custodial implications by kind
| Kind | Where the key lives | Chipi’s view |
|---|---|---|
| STARK (server) | Chipi-held, encrypted at rest with the org’s encryptKey | Encrypted-at-rest, decryptable server-side |
| STARK (client, PIN) | Encrypted in localStorage / Secure Enclave with the user’s PIN | Ciphertext only, but PIN is the key |
| STARK (client, passkey-PRF) | Encrypted with a key the platform authenticator derives via WebAuthn PRF | Ciphertext only; PRF must be available for decrypt |
| ED25519 / EIP191_SECP256K1 / EIP712_SECP256K1 | External wallet (Phantom / MetaMask) | Chipi never sees the key |
| WEBAUTHN_P256 | Inside platform authenticator (Secure Enclave / TPM) | Chipi never sees the key; cannot be extracted |
| JWT_ES256_APPLE_SUB | Apple’s signing infrastructure | Chipi sees only the signed id_token; depends on Apple |
WEBAUTHN_P256 and the external-wallet kinds give you the strongest “Chipi cannot move the user’s funds” story. STARK (server) is the weakest but most operationally convenient.
