@chipi-stack/backend 14.15.1 → 14.17.0

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
 import { C as ChipiClient } from './client-D6SDBu5p.js';
-import { Call, ProviderInterface, Account } from 'starknet';
+import { Call, TypedData, ProviderInterface, Account } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -755,11 +755,18 @@ declare class X402Facilitator {
      * Verify a payment signature is valid (doesn't execute the transfer).
      *
      * Checks:
-     * 1. Nonce has not been used (replay protection)
-     * 2. Payment has not expired (validUntil > now)
-     * 3. Asset is USDC mainnet
-     * 4. Amount is positive
-     * 5. Addresses are non-empty
+     * 1. x402 version is 1
+     * 2. Network is starknet-mainnet
+     * 3. Nonce has not been used (replay protection)
+     * 4. Payment has not expired (validUntil > now)
+     * 5. Asset is USDC mainnet
+     * 6. Amount is positive
+     * 7. Addresses are non-empty
+     * 8. Signature: with a `provider`, the payer account's `is_valid_signature`
+     *    must return 'VALID'. Without one, only its presence is checked (not a
+     *    cryptographic check). SHHH payloads must sign exactly one transfer
+     *    of `amount` of `asset` to `toAddress`; their signature is checked
+     *    on-chain at settle.
      */
     verify(payment: PaymentPayload): Promise<VerifyResponse>;
     /**
@@ -780,6 +787,150 @@ declare class X402Facilitator {
     settle(payment: PaymentPayload): Promise<SettleResponse>;
 }
 
+/**
+ * SNIP-12 typed-data hash for `OutsideExecution` — TypeScript reference.
+ *
+ * Vendored from haycarlitos/shhh-wallet-cairo @ v8.4 commit 3975532
+ *   source: scripts/ts/snip12-hash.ts
+ *   license: MIT (Copyright (c) 2026 Carlos Castillo and contributors)
+ *
+ * MUST produce byte-identical output to `compute_snip12_hash` in
+ * `src/outside_execution.cairo` at the same commit. If the canonical
+ * Cairo source ships a breaking change, the upstream Shhh maintainer
+ * will open a PR against this file (per Q3 of SHHH_INTEGRATION_ANSWERS.md).
+ */
+
+declare const STARKNET_MESSAGE_PREFIX: string;
+declare const OE_DOMAIN_NAME: string;
+declare const OE_DOMAIN_VERSION = 2n;
+declare const OE_DOMAIN_REVISION = 1n;
+declare const SIG_VERSION_V1_HEX_ASCII: string;
+declare const SIG_VERSION_V2_SNIP12: string;
+declare const SIG_VERSION_V2_THRESHOLD: string;
+declare const ISRC9_V2_ID: bigint;
+declare const ISIGNER_ID: bigint;
+declare const ISIGNER_CANONICAL_LABEL = "ISigner_V1";
+/** Recomputes the canonical `ISIGNER_ID` at runtime. */
+declare function computeISignerId(): bigint;
+type OutsideExecution = {
+    caller: bigint | string;
+    nonce: bigint | string;
+    execute_after: bigint;
+    execute_before: bigint;
+    calls: Call[];
+};
+declare function hashCall(call: Call): bigint;
+declare function hashCalls(calls: Call[]): bigint;
+declare function hashStarknetDomain(chainIdFelt: bigint | string): bigint;
+declare function hashOutsideExecutionStruct(oe: OutsideExecution): bigint;
+/**
+ * The authoritative SNIP-12 message hash for an OutsideExecution.
+ * Signers sign over this felt252 (or its hex-ASCII re-encoding for
+ * Phantom UX compatibility — see snip12HashToHexAsciiBytes).
+ */
+declare function computeSnip12Hash(oe: OutsideExecution, contractAddress: bigint | string, chainIdFelt: bigint | string): bigint;
+/**
+ * Phantom hex-ASCII envelope helper. Phantom signs a string; we give it
+ * a 64-byte hex-ASCII representation of the SNIP-12 hash, and the Cairo
+ * verifier re-computes the hash and compares byte-by-byte.
+ */
+declare function snip12HashToHexAsciiBytes(h: bigint): Uint8Array;
+
+/**
+ * Run calls on a SHHH wallet signed by an EXTERNAL Starknet wallet that is
+ * one of its owners or guardians: Bramble, Braavos, Ready/Argent, an
+ * OpenZeppelin account or another Chipi wallet, registered with the
+ * `STARK_SNIP12` kind.
+ *
+ * The external wallet signs an `Approval { Wallet, Hash }` typed data with
+ * `wallet_signTypedData` (see `signers/stark-snip12.ts`). Nothing is
+ * decrypted: the key stays in the external wallet. Chipi's paymaster
+ * relays the outside execution gaslessly, like any other SHHH OE.
+ *
+ * Two steps so the signing can happen wherever the wallet lives:
+ *   1. `prepareExternalOwnerExecution` → `{ outsideExecution, typedData }`
+ *   2. `submitExternalOwnerExecution` with the wallet's signature
+ * `executeShhhWithExternalSigner` does both with a `signTypedData` callback.
+ */
+
+interface PreparedExternalOwnerExecution {
+    walletAddress: string;
+    outsideExecution: OutsideExecution;
+    /** SNIP-12 hash of the OE (what the Approval carries as `Hash`). */
+    messageHash: bigint;
+    /** What the external wallet signs with `wallet_signTypedData`. */
+    typedData: TypedData;
+    chainId: string;
+}
+/** Step 1: build the OE (max 2h window) and the typed data to sign. */
+declare function prepareExternalOwnerExecution(params: {
+    /** The SHHH wallet's address. */
+    walletAddress: string;
+    calls: Call[];
+    nonce?: bigint;
+    /** Defaults to mainnet. */
+    chainId?: bigint | string;
+}): PreparedExternalOwnerExecution;
+/**
+ * Step 2: wrap the wallet's signature and relay the OE through Chipi's
+ * paymaster (`/transactions/execute-sponsored-raw`). Returns the tx hash;
+ * wait for it before treating the call as done.
+ */
+declare function submitExternalOwnerExecution(params: {
+    client: ChipiClient;
+    bearerToken: string;
+    prepared: PreparedExternalOwnerExecution;
+    /** The external wallet's `wallet_signTypedData` result, as returned. */
+    signature: Array<string | number | bigint>;
+    /** u32 index of the external wallet in the SHHH wallet's owner_set. */
+    ownerIndex: number | bigint;
+    /**
+     * The external wallet's address and STARK key (from `resolveStarkSnip12Signer`).
+     * When given, the signature is checked off-chain first, so a wrong wallet or
+     * key fails here. Without it nothing is checked before relaying, and a wrong
+     * signature only shows up as a reverted transaction. Pass it whenever you can.
+     */
+    signer?: {
+        address: string;
+        starkPubkey: bigint | string;
+    };
+    externalUserId?: string;
+}): Promise<string>;
+/** Both steps, with the external wallet's `signTypedData` as a callback. */
+declare function executeShhhWithExternalSigner(params: {
+    client: ChipiClient;
+    bearerToken: string;
+    walletAddress: string;
+    calls: Call[];
+    ownerIndex: number | bigint;
+    signTypedData: (typedData: TypedData) => Promise<Array<string | number | bigint>>;
+    signer?: {
+        address: string;
+        starkPubkey: bigint | string;
+    };
+    nonce?: bigint;
+    chainId?: bigint | string;
+    externalUserId?: string;
+}): Promise<string>;
+/**
+ * Run calls signed by a raw STARK key that is owner `ownerIndex` of the
+ * wallet, relayed gaslessly. For the step right after a guardian recovery:
+ * the recovered key is a new owner (recovery adds, it never replaces), and
+ * it signs `propose_rotate_owner` to move owner 0 onto a fresh key, which is
+ * the key every other SDK call signs with. Keep `privateKey` in memory only.
+ */
+declare function executeShhhWithStarkKey(params: {
+    client: ChipiClient;
+    bearerToken: string;
+    walletAddress: string;
+    calls: Call[];
+    privateKey: string | bigint;
+    ownerIndex: number | bigint;
+    nonce?: bigint;
+    chainId?: bigint | string;
+    externalUserId?: string;
+}): Promise<string>;
+
 /**
  * Main Chipi SDK class
  */
@@ -906,6 +1057,33 @@ declare class ChipiSDK {
     signTypedDataArray({ params }: {
         params: SignTypedDataParams;
     }): Promise<string[]>;
+    /**
+     * Run calls on a SHHH wallet, signed by an external Starknet wallet that is
+     * one of its `STARK_SNIP12` owners (Bramble, Braavos, Ready/Argent, OZ, or
+     * another Chipi wallet). The wallet signs an `Approval` typed data through
+     * `signTypedData` (its `wallet_signTypedData`); Chipi's paymaster relays the
+     * outside execution gaslessly. Returns the tx hash: wait for it.
+     *
+     * @example
+     * ```typescript
+     * // Bramble approves an agent session on the user's Chipi wallet.
+     * const bramble = window.starknet_bramble;
+     * const txHash = await sdk.executeWithExternalSigner({
+     *   params: {
+     *     walletAddress: wallet.publicKey,
+     *     ownerIndex: 1, // Bramble's index in the wallet's owner set
+     *     calls: buildSessionSetupCalls(wallet.publicKey, sessionConfig, policies),
+     *     signTypedData: (typedData) =>
+     *       bramble.request({ type: "wallet_signTypedData", params: typedData }),
+     *   },
+     *   bearerToken,
+     * });
+     * ```
+     */
+    executeWithExternalSigner({ params, bearerToken, }: {
+        params: Omit<Parameters<typeof executeShhhWithExternalSigner>[0], "client" | "bearerToken">;
+        bearerToken?: string;
+    }): Promise<string>;
     /**
      * Transfer tokens
      */
@@ -1472,54 +1650,147 @@ declare class SessionTxVerifier {
     verifyTransfer(params: VerifyTransferParams): Promise<VerifyTransferResult>;
 }
 
+/** SRC-6 `is_valid_signature` magic value: the short string 'VALID'. */
+declare const STARKNET_SIGNATURE_VALID = "0x56414c4944";
+/** Anything with a starknet.js-style `callContract` (e.g. `RpcProvider`). */
+interface StarknetCallProvider {
+    callContract(call: {
+        contractAddress: string;
+        entrypoint: string;
+        calldata?: string[];
+    }): Promise<string[]>;
+}
+type StarknetSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED";
+    detail?: string;
+};
+/** `0x` + 64 hex, lowercase. Wallets differ on padding; compare on this. */
+declare function normalizeStarknetAddress(address: string): string;
+/**
+ * Asks the account itself (SRC-6 `is_valid_signature`) whether `signature`
+ * signs `messageHash`. The full signature array is passed through, so
+ * multi-felt signatures (Argent, Braavos, multisig) work.
+ *
+ * Only 'VALID' counts: accounts return 0 or panic on a bad signature, and a
+ * lax "anything non-zero" check would accept garbage. An account that is not
+ * deployed yet comes back as ACCOUNT_NOT_DEPLOYED so the caller can fall back
+ * to `verifyUndeployedStarknetSignature`.
+ */
+declare function isValidStarknetSignature(provider: StarknetCallProvider, accountAddress: string, messageHash: string, signature: Array<string | number | bigint>): Promise<StarknetSignatureCheck>;
+/** Account classes whose undeployed signatures we can check off-chain. */
+declare const COUNTERFACTUAL_ACCOUNT_CLASSES: {
+    /** OpenZeppelin AccountUpgradeable 3.0 (Bramble's default account). */
+    readonly OPENZEPPELIN_V3: "0x01d1777db36cdd06dd62cfde77b1b6ae06412af95d57a13dc40ac77b8a702381";
+    /** Argent X / Ready 0.4 (`WALLET_CLASS_HASHES.READY`). */
+    readonly ARGENT_V0_4: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f";
+};
+/** What a wallet returns from `wallet_deploymentData`. */
+interface StarknetDeploymentData {
+    address: string;
+    class_hash: string;
+    salt: string;
+    calldata: string[];
+}
+type UndeployedSignatureCheck = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH" | "INVALID_SIGNATURE";
+};
 /**
- * SNIP-12 typed-data hash for `OutsideExecution` — TypeScript reference.
+ * Checks a signature from an account that is not deployed yet (new Bramble
+ * and Ready accounts stay counterfactual until their first transaction), using
+ * the wallet's `wallet_deploymentData`:
  *
- * Vendored from haycarlitos/shhh-wallet-cairo @ v8.4 commit 3975532
- *   source: scripts/ts/snip12-hash.ts
- *   license: MIT (Copyright (c) 2026 Carlos Castillo and contributors)
- *
- * MUST produce byte-identical output to `compute_snip12_hash` in
- * `src/outside_execution.cairo` at the same commit. If the canonical
- * Cairo source ships a breaking change, the upstream Shhh maintainer
- * will open a PR against this file (per Q3 of SHHH_INTEGRATION_ANSWERS.md).
+ * 1. The class must be one we know how to read: OpenZeppelin 3.0 or Argent 0.4
+ *    without a guardian.
+ * 2. The address must be the one those exact constructor arguments deploy to.
+ * 3. The signature must be the owner key's ECDSA signature of the hash.
  */
+declare function verifyUndeployedStarknetSignature(deployment: StarknetDeploymentData, messageHash: string, signature: Array<string | number | bigint>): UndeployedSignatureCheck;
 
-declare const STARKNET_MESSAGE_PREFIX: string;
-declare const OE_DOMAIN_NAME: string;
-declare const OE_DOMAIN_VERSION = 2n;
-declare const OE_DOMAIN_REVISION = 1n;
-declare const SIG_VERSION_V1_HEX_ASCII: string;
-declare const SIG_VERSION_V2_SNIP12: string;
-declare const SIG_VERSION_V2_THRESHOLD: string;
-declare const ISRC9_V2_ID: bigint;
-declare const ISIGNER_ID: bigint;
-declare const ISIGNER_CANONICAL_LABEL = "ISigner_V1";
-/** Recomputes the canonical `ISIGNER_ID` at runtime. */
-declare function computeISignerId(): bigint;
-type OutsideExecution = {
-    caller: bigint | string;
-    nonce: bigint | string;
-    execute_after: bigint;
-    execute_before: bigint;
-    calls: Call[];
-};
-declare function hashCall(call: Call): bigint;
-declare function hashCalls(calls: Call[]): bigint;
-declare function hashStarknetDomain(chainIdFelt: bigint | string): bigint;
-declare function hashOutsideExecutionStruct(oe: OutsideExecution): bigint;
 /**
- * The authoritative SNIP-12 message hash for an OutsideExecution.
- * Signers sign over this felt252 (or its hex-ASCII re-encoding for
- * Phantom UX compatibility — see snip12HashToHexAsciiBytes).
- */
-declare function computeSnip12Hash(oe: OutsideExecution, contractAddress: bigint | string, chainIdFelt: bigint | string): bigint;
+ * Sign in with Starknet (SIWS): the SNIP-12 equivalent of Sign-In with
+ * Ethereum. The server issues a one-time nonce, the wallet signs this typed
+ * data, and the server checks the signature with the account itself.
+ *
+ * The typed data is kept to what every wallet accepts: SNIP-12 revision 1,
+ * mainnet chain id in the domain, single-line printable ASCII strings (Bramble
+ * refuses anything else), and no custom `u256`.
+ */
+declare const SIWS_DOMAIN_NAME = "Sign in with Starknet";
+declare const SIWS_DOMAIN_VERSION = "1";
+declare const SIWS_CHAIN_ID = "SN_MAIN";
+interface StarknetSignInParams {
+    /** Host asking for the sign-in, e.g. "vela-starknet.vercel.app". */
+    domain: string;
+    /** Full URL of the app, e.g. "https://vela-starknet.vercel.app". */
+    uri: string;
+    /** Account that signs. Any padding; stored as 0x + 64 hex. */
+    address: string;
+    /** One-time server nonce (letters and digits). */
+    nonce: string;
+    /** Shown to the user in the wallet. */
+    statement?: string;
+    /** Unix seconds. Defaults to now. */
+    issuedAt?: number;
+    /** Unix seconds. */
+    expirationTime: number;
+}
+interface StarknetSignInMessage {
+    domain: string;
+    address: string;
+    statement: string;
+    uri: string;
+    nonce: string;
+    issuedAt: number;
+    expirationTime: number;
+}
+/** Typed data for the wallet's `wallet_signTypedData`. */
+declare function createStarknetSignInTypedData(params: StarknetSignInParams): TypedData;
+interface VerifyStarknetSignInParams {
+    /** The typed data the wallet signed, as returned to the client. */
+    typedData: TypedData;
+    /** The wallet's `wallet_signTypedData` result (hex or decimal felts). */
+    signature: Array<string | number | bigint>;
+    /** Mainnet RPC (starknet.js `RpcProvider` or anything with `callContract`). */
+    provider: StarknetCallProvider;
+    /** What this server issued. Anything else is refused. */
+    expected: {
+        domain: string;
+        uri: string;
+        nonce: string;
+        now?: number;
+    };
+    /**
+     * The wallet's `wallet_deploymentData`, for accounts not deployed yet
+     * (new Bramble/Ready accounts). Only used when the RPC says the account
+     * does not exist.
+     */
+    deploymentData?: StarknetDeploymentData;
+}
+type StarknetSignInFailure = "MALFORMED" | "WRONG_CHAIN" | "WRONG_DOMAIN" | "WRONG_URI" | "WRONG_NONCE" | "EXPIRED" | "NOT_YET_VALID" | "INVALID_SIGNATURE" | "ACCOUNT_NOT_DEPLOYED" | "UNSUPPORTED_ACCOUNT_CLASS" | "ADDRESS_MISMATCH";
+type VerifyStarknetSignInResult = {
+    ok: true;
+    address: string;
+    message: StarknetSignInMessage;
+} | {
+    ok: false;
+    reason: StarknetSignInFailure;
+};
 /**
- * Phantom hex-ASCII envelope helper. Phantom signs a string; we give it
- * a 64-byte hex-ASCII representation of the SNIP-12 hash, and the Cairo
- * verifier re-computes the hash and compares byte-by-byte.
+ * Verifies a SIWS signature. The typed data is rebuilt from its message with
+ * `createStarknetSignInTypedData`, so a client can't swap in other types or a
+ * testnet domain; then the account is asked with `is_valid_signature`, or, if
+ * it isn't deployed yet and `deploymentData` is given, checked off-chain.
+ *
+ * The caller still owns the nonce: issue it once, and consume it before or
+ * right after calling this (never accept the same nonce twice).
  */
-declare function snip12HashToHexAsciiBytes(h: bigint): Uint8Array;
+declare function verifyStarknetSignIn(params: VerifyStarknetSignInParams): Promise<VerifyStarknetSignInResult>;
 
 /**
  * Deterministic ShhhAccount (V8.4) address derivation.
@@ -1726,6 +1997,128 @@ declare function starkOwnerId(starkPubKey: bigint): bigint;
  */
 declare function starkPubkeyFelts(starkPubKey: bigint | string): bigint[];
 
+/**
+ * STARK_SNIP12 signer for SHHH V8.4 ShhhAccount: Starknet browser wallets
+ * (Bramble, Braavos, Ready/Argent, OpenZeppelin accounts) and Chipi wallets
+ * as co-owners or guardians of a SHHH wallet.
+ *
+ * Why not the `STARK` kind: these wallets never sign a raw hash. Their only
+ * signing method, `wallet_signTypedData`, signs the SNIP-12 message hash,
+ * which always folds in the signing wallet's own address. So the OE hash is
+ * wrapped in an `Approval { Wallet, Hash }` typed data that the wallet signs
+ * as-is, and `StarkSnip12Verifier` rebuilds it on-chain (the Starknet twin of
+ * the EIP-712 verifier MetaMask uses).
+ *
+ * Reference: shhh-wallet-cairo `src/signer/stark_snip12/verifier.cairo` and
+ * `scripts/ts/gen-stark-snip12-fixture.mjs` (same typed data, same hash).
+ *
+ * Pubkey layout: `[stark_pubkey, signer_account_address]`. Payload: `[r, s]`.
+ */
+
+declare const STARK_SNIP12_KIND_TAG = "STARK_SNIP12";
+/**
+ * The typed data the external wallet signs (`wallet_signTypedData`) to
+ * approve the OE whose SNIP-12 hash is `messageHash` on `walletAddress`.
+ * Plain ASCII, revision 1, `chainId` in the domain: Bramble's strict rules.
+ */
+declare function starkSnip12ApprovalTypedData(params: {
+    /** The SHHH wallet being approved (the account address). */
+    walletAddress: string;
+    /** SNIP-12 hash of the OutsideExecution (`computeOeHash`). */
+    messageHash: bigint | string;
+    /** Defaults to "SN_MAIN". Hex chain ids are converted. */
+    chainId?: bigint | string;
+}): TypedData;
+/** The hash the external wallet's key signs (what the verifier checks). */
+declare function starkSnip12ApprovalHash(params: {
+    walletAddress: string;
+    messageHash: bigint | string;
+    /** The external wallet's account address. */
+    signerAddress: string;
+    chainId?: bigint | string;
+}): bigint;
+/** Pubkey felts for `propose_add_owner` / `initiate_recovery`. */
+declare function starkSnip12PubkeyFelts(starkPubkey: bigint | string, signerAddress: string): bigint[];
+/** On-chain owner id commitment for a STARK_SNIP12 owner (dedupe key). */
+declare function starkSnip12OwnerCommitment(starkPubkey: bigint | string, signerAddress: string): bigint;
+/** What a wallet returned from `wallet_signTypedData`, split into its parts. */
+interface ParsedStarknetWalletSignature {
+    r: bigint;
+    s: bigint;
+    /** Argent / Ready include the signer's public key. */
+    pubkey?: bigint;
+    /** A Chipi (SHHH) wallet returns its own V2_SNIP12 envelope: the owner index. */
+    shhhOwnerId?: bigint;
+}
+/**
+ * Reads the signature shapes Starknet wallets return:
+ * - `[r, s]`: OpenZeppelin (Bramble), Braavos with a STARK signer;
+ * - `[1, 0, pubkey, r, s]`: Argent / Ready (one Starknet signer);
+ * - `[V2_SNIP12, owner_id, 'STARK', r, s]`: a Chipi (SHHH) wallet.
+ * Anything else (multisig, hardware or webauthn signers) is refused.
+ */
+declare function parseStarknetWalletSignature(signature: Array<string | number | bigint>): ParsedStarknetWalletSignature;
+/** Off-chain check of an approval signature, before relaying it. */
+declare function verifyStarkSnip12Approval(params: {
+    walletAddress: string;
+    messageHash: bigint | string;
+    signerAddress: string;
+    starkPubkey: bigint | string;
+    signature: Array<string | number | bigint>;
+    chainId?: bigint | string;
+}): boolean;
+/**
+ * The V2_SNIP12 envelope for a STARK_SNIP12 owner: pass the wallet's raw
+ * `wallet_signTypedData` result; it is normalized to `[r, s]`.
+ */
+declare function buildStarkSnip12Envelope(params: {
+    signature: Array<string | number | bigint>;
+    /** u32 index of this owner in the SHHH wallet's owner_set. */
+    ownerIndex: bigint;
+}): bigint[];
+/**
+ * Which STARK key signs for `signerAddress`, proven by an approval signature
+ * the wallet just produced (e.g. for the "add trusted wallet" step). Sources,
+ * in order:
+ * - Argent / Ready: the key inside the signature;
+ * - Chipi (SHHH) wallet: the key whose commitment matches `get_owner(id)`;
+ * - an undeployed account: `wallet_deploymentData` (OpenZeppelin, Argent 0.4);
+ * - OpenZeppelin (Bramble): `get_public_key`;
+ * - Braavos: `get_signers` (STARK only, no hardware or webauthn signers).
+ * The chosen key must verify the approval, or this throws.
+ */
+declare function resolveStarkSnip12Signer(params: {
+    provider: StarknetCallProvider;
+    signerAddress: string;
+    walletAddress: string;
+    messageHash: bigint | string;
+    signature: Array<string | number | bigint>;
+    deploymentData?: StarknetDeploymentData;
+    chainId?: bigint | string;
+}): Promise<{
+    starkPubkey: bigint;
+    pubkeyFelts: bigint[];
+}>;
+
+/**
+ * Whether a SHHH verifier class is declared on the network. A wallet can
+ * register a kind whose class is not declared (`propose_add_verifier_class`
+ * stores only the hash), and every signature of that kind would then fail.
+ * Check before proposing a kind that is new on the network, such as
+ * `STARK_SNIP12` before its mainnet declare.
+ */
+
+/** Anything with a starknet.js-style `getClassByHash` (e.g. `RpcProvider`). */
+interface StarknetClassProvider {
+    getClassByHash(classHash: string): Promise<unknown>;
+}
+/**
+ * `true` when the verifier class for `kind` (or `classHash`) is declared,
+ * `false` when the RPC answers CLASS_HASH_NOT_FOUND (28). Other RPC errors
+ * are thrown: an outage is not "not declared".
+ */
+declare function isShhhVerifierDeclared(provider: StarknetClassProvider, kind: ShhhSignerKind, classHash?: string): Promise<boolean>;
+
 /**
  * Ed25519 signer for SHHH V8.4 ShhhAccount.
  *
@@ -2265,9 +2658,10 @@ declare function buildJwtAppleSubEnvelopeFromTestKey(params: {
  *
  * Wave B PR B1. The V8.4 ShhhAccount gates every owner-set mutation
  * through a propose → wait-timelock → execute flow (`@external` fns
- * in `src/account.cairo`). Each entrypoint is `_assert_self_call`-gated,
- * which means callers wrap these `Call`s inside an OutsideExecution and
- * submit through the paymaster.
+ * in `src/account.cairo`). The propose and cancel entrypoints are
+ * `_assert_self_call`-gated, which means callers wrap these `Call`s inside
+ * an OutsideExecution and submit through the paymaster (see below for the
+ * permissionless ones).
  *
  * This module produces the `Call` (`{ contractAddress, entrypoint,
  * calldata }`) shape that `oe.ts:buildOutsideExecution` expects. It
@@ -2304,11 +2698,15 @@ declare function buildJwtAppleSubEnvelopeFromTestKey(params: {
  * but does not remove existing ones. The integrator's UI is expected
  * to follow with `propose_remove_owner` for stale devices.
  *
- * finalize_recovery is the only entrypoint here that is NOT
- * `_assert_self_call`-gated — it's permissionless after the 7d window,
- * so anyone can call it directly without an OE wrapper. The function
- * still returns a Call so the integrator can dispatch via their
- * normal account abstraction layer.
+ * Not every entrypoint here is `_assert_self_call`-gated. The
+ * propose_* calls, cancel_pending_op, initiate_recovery and
+ * cancel_recovery are (they need an OE signed by an owner, or by a
+ * guardian for a single-call initiate_recovery). Every execute_* call
+ * and finalize_recovery are permissionless once their timelock has
+ * elapsed: anyone can submit them, directly or inside an owner's OE, because
+ * the wallet re-checks the stored payload commitment. The builders still
+ * return a Call so the integrator can dispatch via their normal account
+ * abstraction layer.
  */
 
 /** `src/owner_set/interface.cairo:10` — `pub const ROLE_OWNER: felt252 = 'OWNER'`. */
@@ -2320,6 +2718,8 @@ declare const OP_ADD_OWNER: bigint;
 declare const OP_REMOVE_OWNER: bigint;
 declare const OP_ROTATE_OWNER: bigint;
 declare const OP_SET_THRESHOLD: bigint;
+/** `src/governance/pending_ops.cairo:23` — `OP_ADD_VERIFIER_CLASS: felt252 = 'ADD_VERIFIER'`. */
+declare const OP_ADD_VERIFIER_CLASS: bigint;
 /**
  * Per-op timelocks in seconds. Match `src/governance/pending_ops.cairo:42-50`
  * exactly. Exposed so SDK consumers can predict timelock expiry without
@@ -2339,11 +2739,16 @@ declare const TIMELOCK_SECONDS: {
 /** `DEFAULT_OP_EXPIRY_SECONDS` from `pending_ops.cairo:78`. The window is
  * measured from `valid_after`, not from propose time:
  * `expires_at = now + timelock + DEFAULT_OP_EXPIRY_SECONDS`
- * (governance/component.cairo). So a 48h op (add_owner, set_threshold) lives
- * 16 days from propose and a 7d recovery lives 21. Read `get_pending_op` for
+ * (governance/component.cairo). So a 48h op (add_owner, set_threshold,
+ * add_verifier) lives 16 days from propose and a 24h op 15. Read
+ * `get_pending_op` (or the `OpProposed` event, `parseOpProposedEvents`) for
  * the exact `expires_at` instead of adding 14d to the propose timestamp. The
  * op auto-expires at that point even if no one calls cancel; UI should
- * reflect it so users don't sit on a stale op. */
+ * reflect it so users don't sit on a stale op.
+ *
+ * Recovery is not a pending op and has no expiry: an initiated recovery
+ * stays pending until an owner cancels it or anyone finalizes it after the
+ * 7d timelock. */
 declare const DEFAULT_OP_EXPIRY_SECONDS = 1209600;
 /** Owner role on-chain. ROLE_OWNER can sign OEs; ROLE_GUARDIAN can
  * only `initiate_recovery` (no general signing power). */
@@ -2429,6 +2834,32 @@ declare function buildCancelPendingOpCall(args: {
     walletAddress: bigint | string;
     opId: bigint | string;
 }): Call;
+/**
+ * Build a `propose_add_verifier_class(proposer, kind, class_hash)` call.
+ *
+ * A wallet only verifies the kinds in its `verifier_classes` map; a Chipi
+ * passkey wallet starts with `STARK` only. To add an owner or guardian of
+ * another kind (e.g. `STARK_SNIP12` for Bramble), put this call and
+ * `buildProposeAddOwnerCall` in the same owner-signed OE, wait 48h, then
+ * run `buildExecuteAddVerifierClassCall` BEFORE `buildExecuteAddOwnerCall`
+ * (execute_add_owner validates the new pubkey through the verifier).
+ * Reverts with `'SHHH: verifier already set'` if the kind is registered;
+ * check `readVerifierClass` first.
+ */
+declare function buildProposeAddVerifierClassCall(args: {
+    walletAddress: bigint | string;
+    proposer: number;
+    kind: ShhhSignerKind;
+    /** Defaults to `SHHH_VERIFIER_CLASS_HASHES[kind]`. */
+    classHash?: bigint | string;
+}): Call;
+/** Build an `execute_add_verifier_class(op_id, kind, class_hash)` call (permissionless after 48h). */
+declare function buildExecuteAddVerifierClassCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+    kind: ShhhSignerKind;
+    classHash?: bigint | string;
+}): Call;
 /**
  * Build an `initiate_recovery(proposer, new_owner_kind, new_pubkey_bytes,
  * new_role, new_weight, new_label)` call.
@@ -2506,6 +2937,51 @@ declare function isReadyToExecute(validAfterSecs: number | bigint, nowSecs: numb
  * `number` seconds — truncates via floor.
  */
 declare function secondsUntilExecutable(validAfterSecs: number | bigint, nowSecs: number): number;
+/** One entry of a wallet's owner_set (`get_owner`). */
+interface ShhhOwnerRecord {
+    /** u32 index: what `owner_id` means in envelopes and governance calls. */
+    ownerId: number;
+    kind: string;
+    /** poseidon(kind, pubkey...) — compare with `ownerCommitment`. */
+    pubkeyHash: bigint;
+    role: "OWNER" | "GUARDIAN" | "RECOVERY_ONLY" | string;
+    weight: number;
+    addedAt: number;
+    label: string;
+    revoked: boolean;
+}
+/** A governance op from an `OpProposed` event. */
+interface ShhhProposedOp {
+    opId: bigint;
+    opKind: string;
+    proposer: number;
+    payload: bigint;
+    validAfter: number;
+    expiresAt: number;
+}
+/** `get_pending_recovery` decoded. */
+interface ShhhPendingRecovery {
+    initiatedAt: number;
+    validAfter: number;
+    newOwnerHash: bigint;
+    isActive: boolean;
+}
+/** Every owner and guardian of a SHHH wallet, revoked ones included (ids stay stable). */
+declare function readShhhOwners(provider: StarknetCallProvider, walletAddress: bigint | string): Promise<ShhhOwnerRecord[]>;
+/** The class hash registered for `kind` on this wallet, or 0n if none. */
+declare function readVerifierClass(provider: StarknetCallProvider, walletAddress: bigint | string, kind: ShhhSignerKind): Promise<bigint>;
+/** The wallet's pending recovery (`isActive: false` when there is none). */
+declare function readPendingRecovery(provider: StarknetCallProvider, walletAddress: bigint | string): Promise<ShhhPendingRecovery>;
+/**
+ * Governance ops proposed in a transaction, from its receipt events. The
+ * op_id mixes in the block timestamp and a counter, so it can only be read
+ * back after the propose lands: pass `receipt.events` here.
+ */
+declare function parseOpProposedEvents(events: Array<{
+    from_address?: string;
+    keys: string[];
+    data: string[];
+}>, walletAddress?: bigint | string): ShhhProposedOp[];
 
 /**
  * SHHH V8.4 threshold envelope assembly + gas estimation.
@@ -2532,11 +3008,12 @@ declare function secondsUntilExecutable(validAfterSecs: number | bigint, nowSecs
  *     ...env_n,
  *   ]
  *
- * Each inner envelope is a V2_SNIP12 single-owner envelope
- * (`wrap_v2_snip12_envelope` output) from a different owner. Nested
- * threshold envelopes are NOT permitted — the Cairo `_verify_sub_envelope`
- * recursively checks the inner tag and rejects anything except
- * V2_SNIP12.
+ * Each inner frame is `[owner_id, kind_tag, ...payload]`: a single-owner
+ * envelope WITHOUT its V2_SNIP12 tag, which the outer V2_THRESHOLD tag
+ * replaces (`_verify_sub_envelope` reads `owner_id` at index 0). Callers
+ * still pass the per-kind builders' V2_SNIP12 envelopes; the builder strips
+ * the tag and `parseThresholdEnvelope` puts it back. Nested threshold
+ * envelopes are not permitted.
  *
  * Cairo-enforced invariants this module replicates client-side so
  * mis-shaped envelopes fail at the SDK boundary with a clear message
@@ -2589,7 +3066,8 @@ declare function buildThresholdEnvelope(args: {
 }): bigint[];
 /**
  * Split a V2_THRESHOLD envelope back into its constituent inner
- * V2_SNIP12 envelopes. Inverse of `buildThresholdEnvelope`.
+ * V2_SNIP12 envelopes (the tag is restored on each frame). Inverse of
+ * `buildThresholdEnvelope`.
  *
  * Useful for UI flows that need to display "N of M signers signed
  * so far" status without re-deriving from individual envelopes. Also
@@ -3049,4 +3527,4 @@ declare class ShhhAccount {
  */
 declare function submitViaAccount(funded: Account): ShhhSubmit;
 
-export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, VIEW_SELECTORS, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isThinkDecision, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, submitViaAccount, validateSpendingPolicyConfig, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, type ApproveBody, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, COUNTERFACTUAL_ACCOUNT_CLASSES, ChipiAi, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiTreasury, ChipiWallets, type ComputeAddressInput, type ContractEventLog, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, type ExecuteResult, type ForTreasuryConfig, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, type ListTreasuriesOptions, type ListTreasuriesResult, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type MultisigAllowance, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_ADD_VERIFIER_CLASS, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, type ParsedStarknetWalletSignature, type PreparedExternalOwnerExecution, type ProposeBody, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, SIWS_CHAIN_ID, SIWS_DOMAIN_NAME, SIWS_DOMAIN_VERSION, STARKNET_MESSAGE_PREFIX, STARKNET_SIGNATURE_VALID, STARK_SNIP12_KIND_TAG, SessionTxVerifier, type SessionTxVerifierConfig, type SetTreasuryPolicyOptions, ShhhAccount, type ShhhAccountOptions, type ShhhExecuteOptions, type ShhhOwnerRecord, type ShhhPendingRecovery, type ShhhProposedOp, type ShhhSignedExecution, type ShhhSubmit, type ShhhX402Wallet, type StarknetCallProvider, type StarknetClassProvider, type StarknetDeploymentData, type StarknetSignInFailure, type StarknetSignInMessage, type StarknetSignInParams, type StarknetSignatureCheck, TIMELOCK_SECONDS, type TreasuryPolicy, type TreasuryProposal, type TreasuryProposalSignature, type TreasurySummary, type TreasuryTransport, type TxHashStore, type UndeployedSignatureCheck, VIEW_SELECTORS, type VerifyStarknetSignInParams, type VerifyStarknetSignInResult, type VerifyTransferFailure, type VerifyTransferParams, type VerifyTransferResult, type WaitForTransactionOptions, type WaitForTransactionResult, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildAddSessionKeyCall, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteAddVerifierClassCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeAddVerifierClassCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildRemoveSpendingPolicyCall, buildRevokeSessionKeyCall, buildSessionSetupCalls, buildSetSpendingPolicyCall, buildStarkEnvelope, buildStarkSnip12Envelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, createStarknetSignInTypedData, decryptPrivateKey, ed25519OwnerId, ed25519OwnerPubkeyParam, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191OwnerPubkeyParam, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, executeShhhWithExternalSigner, executeShhhWithStarkKey, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, isShhhVerifierDeclared, isThinkDecision, isValidStarknetSignature, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, normalizeEntrypoints, normalizeStarknetAddress, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseOpProposedEvents, parseStarknetWalletSignature, parseThresholdEnvelope, prepareExternalOwnerExecution, readPendingRecovery, readShhhOwners, readVerifierClass, resolveShhhChainId, resolveStarkSnip12Signer, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, signTypedDataArray, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, starkSnip12ApprovalHash, starkSnip12ApprovalTypedData, starkSnip12OwnerCommitment, starkSnip12PubkeyFelts, submitExternalOwnerExecution, submitViaAccount, validateSpendingPolicyConfig, verifyStarkSnip12Approval, verifyStarknetSignIn, verifyUndeployedStarknetSignature, waitForTransaction, webauthnOwnerId, webauthnOwnerPubkeyParam, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };