@chipi-stack/backend 14.15.1 → 14.17.0

package/dist/index.js

@@ -173,9 +173,9 @@ function assertValidV2Snip12Envelope(envelope) {
   }
   return envelope[1];
 }
-function _tryDecodeShortString(felt) {
+function _tryDecodeShortString(felt2) {
   try {
-    return starknet.shortString.decodeShortString("0x" + felt.toString(16));
+    return starknet.shortString.decodeShortString("0x" + felt2.toString(16));
   } catch {
     return null;
   }
@@ -199,14 +199,20 @@ function buildThresholdEnvelope(args) {
       );
     }
     seenOwners.add(key);
-    out.push(BigInt(env.length));
-    for (const felt of env) {
-      if (felt < 0n) {
+    if (env.length < 3) {
+      throw new Error(
+        `THRESH: inner envelope ${i} must have at least [tag, owner_id, kind_tag]; got ${env.length} felts`
+      );
+    }
+    const frame = env.slice(1);
+    out.push(BigInt(frame.length));
+    for (const felt2 of frame) {
+      if (felt2 < 0n) {
         throw new RangeError(
           `THRESH: envelope ${i} contains negative felt (cannot serialize as felt252)`
         );
       }
-      out.push(felt);
+      out.push(felt2);
     }
   }
   return out;
@@ -239,15 +245,26 @@ function parseThresholdEnvelope(envelope) {
         `THRESH: inner ${i} would overflow envelope (env_len ${envLen}, cursor ${cursor}, total ${envelope.length})`
       );
     }
-    const inner = envelope.slice(cursor, cursor + envLen);
-    for (const felt of inner) {
-      if (felt < 0n) {
+    const frame = envelope.slice(cursor, cursor + envLen);
+    for (const felt2 of frame) {
+      if (felt2 < 0n) {
         throw new RangeError(
           `THRESH: inner ${i} contains negative felt (cannot serialize as felt252)`
         );
       }
     }
-    const ownerId = assertValidV2Snip12Envelope(inner);
+    const ownerId = frame[0];
+    if (ownerId >= 0x100000000n) {
+      if (ownerId === V2_THRESHOLD_TAG) {
+        throw new Error(
+          `THRESH: inner ${i}: nested threshold envelopes are not allowed; inner frames are [owner_id, kind_tag, ...payload]`
+        );
+      }
+      throw new Error(
+        `THRESH: inner ${i} owner_id 0x${ownerId.toString(16)} is not a u32; inner frames are [owner_id, kind_tag, ...payload] with no V2_SNIP12 tag`
+      );
+    }
+    const inner = [V2_SNIP12_TAG, ...frame];
     const key = ownerId.toString();
     if (seenOwners.has(key)) {
       throw new Error(
@@ -550,6 +567,7 @@ var init_stark = __esm({
 var execute_paymaster_raw_exports = {};
 __export(execute_paymaster_raw_exports, {
   executeShhhSponsoredRaw: () => executeShhhSponsoredRaw,
+  newOeNonce: () => newOeNonce,
   resolveShhhChainId: () => resolveShhhChainId,
   serializeExecuteFromOutsideV2Calldata: () => serializeExecuteFromOutsideV2Calldata
 });
@@ -887,13 +905,26 @@ function unwrapPrepareResponse(response) {
     apiMessage ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing"
   );
 }
+function feltEquals(value, expected) {
+  try {
+    return BigInt(value) === expected;
+  } catch {
+    return false;
+  }
+}
 function normalizeSignature(signature) {
   if (Array.isArray(signature)) {
     if (signature.length < 2) {
       throw new Error(`Array signature must have at least 2 elements, got ${signature.length}`);
     }
-    const r = signature[0];
-    const s = signature[1];
+    const isArgentSingle = signature.length === 5 && feltEquals(signature[0], 1n) && feltEquals(signature[1], 0n);
+    if (signature.length !== 2 && !isArgentSingle) {
+      throw new Error(
+        `Unsupported ${signature.length}-felt signature: expected [r, s] or Argent [1, 0, pubkey, r, s].`
+      );
+    }
+    const r = isArgentSingle ? signature[3] : signature[0];
+    const s = isArgentSingle ? signature[4] : signature[1];
     if (r == null || s == null) {
       throw new Error(`Signature elements must not be null/undefined. Got r=${r}, s=${s}`);
     }
@@ -1608,7 +1639,10 @@ var ChipiWallets = class {
           publicKey,
           walletType,
           starkKeyPubAX,
-          ...customClassHash && { classHash: customClassHash },
+          // The class the address above was computed with. SHHH always
+          // names it: chipi-back's default for clients that name none is
+          // the class SDKs up to 14.16 used (V8.4), not ours.
+          ...(customClassHash || isShhh) && { classHash: accountClassHash },
           // SHHH: tell chipi-back which signer kind + pubkey felts
           // produced this deployment so it can validate against the
           // expected SHHH constructor shape and populate the new
@@ -1620,6 +1654,11 @@ var ChipiWallets = class {
         }
       });
       const { typedData: typedData2, accountClassHash: accountClassHashResponse } = typedDataResponse;
+      if (isShhh && (!accountClassHashResponse || BigInt(accountClassHashResponse) !== BigInt(accountClassHash))) {
+        throw new Error(
+          `prepare-creation returned class ${accountClassHashResponse ?? "(none)"}, but the wallet address was computed with ${accountClassHash}. Not deploying.`
+        );
+      }
       let userSignaturePayload;
       if (isShhh) {
         userSignaturePayload = {
@@ -1958,9 +1997,9 @@ var ChipiTransactions = class {
   /**
    * Get on-chain transaction status
    */
-  async getTransactionStatus(hash11, bearerToken) {
+  async getTransactionStatus(hash13, bearerToken) {
     return this.client.get({
-      endpoint: `${shared.API_ENDPOINTS.TRANSACTIONS}/${hash11}/status`,
+      endpoint: `${shared.API_ENDPOINTS.TRANSACTIONS}/${hash13}/status`,
       bearerToken
     });
   }
@@ -2138,14 +2177,14 @@ function normalizeEntrypoints(entrypoints) {
   return entrypoints.map((entry) => {
     const value = String(entry).trim();
     if (HEX_FELT.test(value) || DECIMAL_FELT.test(value)) {
-      const felt = BigInt(value);
-      if (felt >= FIELD_PRIME) {
+      const felt2 = BigInt(value);
+      if (felt2 >= FIELD_PRIME) {
         throw new shared.ChipiSessionError(
           `Session entrypoint ${value} is not a valid felt (>= field prime).`,
           shared.SESSION_ERRORS.SESSION_ENTRYPOINT_NOT_ALLOWED
         );
       }
-      return starknet.num.toHex(felt);
+      return starknet.num.toHex(felt2);
     }
     if (CAIRO_IDENTIFIER.test(value)) {
       return starknet.hash.getSelectorFromName(value);
@@ -3547,6 +3586,122 @@ var ChipiAi = class {
     });
   }
 };
+var STARKNET_SIGNATURE_VALID = "0x56414c4944";
+function toFeltHex(value) {
+  return starknet.num.toHex(BigInt(value));
+}
+function normalizeStarknetAddress(address) {
+  return `0x${BigInt(address).toString(16).padStart(64, "0")}`;
+}
+function isContractNotFound(err) {
+  const e = err;
+  if (e?.baseError?.code === 20 || e?.code === 20) return true;
+  return /contract not found/i.test(e?.message ?? String(err));
+}
+async function isValidStarknetSignature(provider, accountAddress, messageHash, signature) {
+  try {
+    const sig = signature.map(toFeltHex);
+    const result = await provider.callContract({
+      contractAddress: normalizeStarknetAddress(accountAddress),
+      entrypoint: "is_valid_signature",
+      calldata: [toFeltHex(messageHash), toFeltHex(sig.length), ...sig]
+    });
+    const first = result?.[0];
+    if (first !== void 0 && BigInt(first) === BigInt(STARKNET_SIGNATURE_VALID)) {
+      return { valid: true };
+    }
+    return { valid: false, reason: "INVALID_SIGNATURE" };
+  } catch (err) {
+    if (isContractNotFound(err)) return { valid: false, reason: "ACCOUNT_NOT_DEPLOYED" };
+    return {
+      valid: false,
+      reason: "INVALID_SIGNATURE",
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+var COUNTERFACTUAL_ACCOUNT_CLASSES = {
+  /** OpenZeppelin AccountUpgradeable 3.0 (Bramble's default account). */
+  OPENZEPPELIN_V3: "0x01d1777db36cdd06dd62cfde77b1b6ae06412af95d57a13dc40ac77b8a702381",
+  /** Argent X / Ready 0.4 (`WALLET_CLASS_HASHES.READY`). */
+  ARGENT_V0_4: "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f"
+};
+function starkVerify(r, s, messageHash, publicKey) {
+  const x = BigInt(publicKey).toString(16).padStart(64, "0");
+  const sig = new starknet.ec.starkCurve.Signature(BigInt(r), BigInt(s));
+  for (const prefix of ["02", "03"]) {
+    try {
+      if (starknet.ec.starkCurve.verify(sig, toFeltHex(messageHash), prefix + x)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function verifyUndeployedStarknetSignature(deployment, messageHash, signature) {
+  const classHash = normalizeStarknetAddress(deployment.class_hash);
+  const calldata = deployment.calldata.map(toFeltHex);
+  const sig = signature.map(toFeltHex);
+  let publicKey;
+  let r;
+  let s;
+  if (classHash === COUNTERFACTUAL_ACCOUNT_CLASSES.OPENZEPPELIN_V3) {
+    if (calldata.length !== 1 || sig.length !== 2) {
+      return { valid: false, reason: "INVALID_SIGNATURE" };
+    }
+    [publicKey] = calldata;
+    [r, s] = sig;
+  } else if (classHash === COUNTERFACTUAL_ACCOUNT_CLASSES.ARGENT_V0_4) {
+    if (calldata.length !== 3 || BigInt(calldata[0]) !== 0n || BigInt(calldata[2]) !== 1n) {
+      return { valid: false, reason: "UNSUPPORTED_ACCOUNT_CLASS" };
+    }
+    if (sig.length !== 5 || BigInt(sig[0]) !== 1n || BigInt(sig[1]) !== 0n) {
+      return { valid: false, reason: "INVALID_SIGNATURE" };
+    }
+    if (BigInt(sig[2]) !== BigInt(calldata[1])) {
+      return { valid: false, reason: "INVALID_SIGNATURE" };
+    }
+    publicKey = calldata[1];
+    [, , , r, s] = sig;
+  } else {
+    return { valid: false, reason: "UNSUPPORTED_ACCOUNT_CLASS" };
+  }
+  const expected = starknet.hash.calculateContractAddressFromHash(
+    toFeltHex(deployment.salt),
+    classHash,
+    calldata,
+    0
+  );
+  if (normalizeStarknetAddress(expected) !== normalizeStarknetAddress(deployment.address)) {
+    return { valid: false, reason: "ADDRESS_MISMATCH" };
+  }
+  return starkVerify(r, s, messageHash, publicKey) ? { valid: true } : { valid: false, reason: "INVALID_SIGNATURE" };
+}
+
+// src/x402/facilitator.ts
+var TRANSFER_SELECTOR2 = BigInt(starknet.hash.getSelectorFromName("transfer"));
+function shhhTransferMatches(oeCalldata, payload) {
+  try {
+    const felts = oeCalldata.map((v) => BigInt(v));
+    const [, , , executeBefore, callsLen] = felts;
+    if (callsLen !== 1n) return { ok: false, reason: "SHHH payment must be exactly one transfer" };
+    const [to, selector, len, recipient, low, high] = felts.slice(5, 11);
+    if (to !== BigInt(payload.asset) || selector !== TRANSFER_SELECTOR2 || len !== 3n) {
+      return { ok: false, reason: "SHHH payment call is not a transfer of the payment asset" };
+    }
+    if (recipient !== BigInt(payload.toAddress)) {
+      return { ok: false, reason: "SHHH payment pays a different recipient" };
+    }
+    if (low + (high << 128n) !== BigInt(payload.amount)) {
+      return { ok: false, reason: "SHHH payment amount differs from the declared amount" };
+    }
+    if (executeBefore <= BigInt(Math.floor(Date.now() / 1e3))) {
+      return { ok: false, reason: "SHHH payment has expired (execute_before in the past)" };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: "Malformed SHHH oeCalldata" };
+  }
+}
 var InMemoryNonceStore = class {
   constructor() {
     this.used = /* @__PURE__ */ new Set();
@@ -3589,11 +3744,18 @@ var X402Facilitator = 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.
    */
   async verify(payment) {
     const { payload } = payment;
@@ -3649,6 +3811,8 @@ var X402Facilitator = class _X402Facilitator {
       if (!Array.isArray(oeCalldata) || oeCalldata.length === 0) {
         return { valid: false, reason: "Missing SHHH oeCalldata" };
       }
+      const bound = shhhTransferMatches(oeCalldata, payment.payload);
+      if (!bound.ok) return { valid: false, reason: bound.reason };
       return { valid: true };
     }
     if (!this.provider) {
@@ -3669,22 +3833,25 @@ var X402Facilitator = class _X402Facilitator {
       valid_until: String(payload.validUntil),
       nonce: payload.nonce
     });
-    const msgHash = starknet.typedData.getMessageHash(paymentTypedData, payload.fromAddress);
+    let msgHash;
     try {
-      const result = await this.provider.callContract({
-        contractAddress: payload.fromAddress,
-        entrypoint: "is_valid_signature",
-        calldata: [msgHash, "2", payload.signature.r, payload.signature.s]
-      });
-      const VALID = "0x56414c4944";
-      if (result[0] === VALID || result[0] === BigInt(VALID).toString()) {
-        return { valid: true };
-      }
-      return { valid: false, reason: "Invalid SNIP-12 signature" };
+      msgHash = starknet.typedData.getMessageHash(paymentTypedData, payload.fromAddress);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      return { valid: false, reason: `Signature verification failed: ${message}` };
+      return { valid: false, reason: `Malformed payment: ${message}` };
+    }
+    const check = await isValidStarknetSignature(this.provider, payload.fromAddress, msgHash, [
+      payload.signature.r,
+      payload.signature.s
+    ]);
+    if (check.valid) return { valid: true };
+    if (check.reason === "ACCOUNT_NOT_DEPLOYED") {
+      return { valid: false, reason: "Payer account is not deployed" };
     }
+    return {
+      valid: false,
+      reason: check.detail ? `Signature verification failed: ${check.detail}` : "Invalid SNIP-12 signature"
+    };
   }
   /**
    * Settle a verified payment by executing the USDC transfer via paymaster.
@@ -3813,7 +3980,7 @@ var signTypedData = async ({
     throw error;
   }
 };
-function toFeltHex(x) {
+function toFeltHex2(x) {
   return "0x" + x.toString(16).padStart(64, "0");
 }
 var signTypedDataArray = async ({
@@ -3843,7 +4010,7 @@ var signTypedDataArray = async ({
       messageHash,
       ownerIndex: 0n
     });
-    return envelope.map(toFeltHex);
+    return envelope.map(toFeltHex2);
   }
   const provider = new starknet.RpcProvider({ nodeUrl: shared.WALLET_RPC_ENDPOINTS[walletType] });
   const account = new starknet.Account({ provider, address: wallet.publicKey, signer: privateKeyDecrypted });
@@ -3851,144 +4018,643 @@ var signTypedDataArray = async ({
   return [r, s];
 };
 
-// src/chipi-sdk.ts
-var ChipiSDK = class {
-  constructor(config) {
-    this.client = new ChipiClient(config);
-    this.nodeUrl = config.nodeUrl || shared.STARKNET_NETWORKS.MAINNET;
-    this.apiSecretKey = config.apiSecretKey;
-    this.wallets = new ChipiWallets(this.client);
-    this.transactions = new ChipiTransactions(this.client);
-    this.skuPurchases = new ChipiSkuPurchases(this.client);
-    this.skus = new ChipiSkus(this.client);
-    this.sessions = new ChipiSessions(this.client);
-    this.exchanges = new ChipiExchanges(this.client);
-    this.treasury = new ChipiTreasury(this.client, config.apiSecretKey);
-    this.ai = new ChipiAi(this.client, config.apiSecretKey, this.sessions);
-    this.executeTransaction = this.executeTransaction.bind(this);
-    this.executeTransactionWithSession = this.executeTransactionWithSession.bind(this);
-    this.transfer = this.transfer.bind(this);
-    this.approve = this.approve.bind(this);
-    this.callAnyContract = this.callAnyContract.bind(this);
-    this.createWallet = this.createWallet.bind(this);
-    this.recordSendTransaction = this.recordSendTransaction.bind(this);
-    this.purchaseSku = this.purchaseSku.bind(this);
-    this.getUsdAmount = this.getUsdAmount.bind(this);
-    this.signTypedData = this.signTypedData.bind(this);
-    this.signTypedDataArray = this.signTypedDataArray.bind(this);
-    this.createPaymasterAdapter = this.createPaymasterAdapter.bind(this);
-    this.createX402Facilitator = this.createX402Facilitator.bind(this);
+// src/shhh/execute-external-owner.ts
+init_oe();
+init_execute_paymaster_raw();
+init_stark();
+
+// src/shhh/signers/stark-snip12.ts
+init_compute_wallet_address();
+init_oe();
+var ROLE_OWNER = BigInt(starknet.shortString.encodeShortString("OWNER"));
+var ROLE_GUARDIAN = BigInt(starknet.shortString.encodeShortString("GUARDIAN"));
+var OP_ADD_OWNER = BigInt(starknet.shortString.encodeShortString("ADD_OWNER"));
+var OP_REMOVE_OWNER = BigInt(starknet.shortString.encodeShortString("REMOVE_OWNER"));
+var OP_ROTATE_OWNER = BigInt(starknet.shortString.encodeShortString("ROTATE_OWNER"));
+var OP_SET_THRESHOLD = BigInt(starknet.shortString.encodeShortString("SET_THRESHOLD"));
+var OP_ADD_VERIFIER_CLASS = BigInt(starknet.shortString.encodeShortString("ADD_VERIFIER"));
+var TIMELOCK_SECONDS = {
+  ADD_OWNER: 172800,
+  // 48h
+  REMOVE_OWNER: 86400,
+  // 24h
+  ROTATE_OWNER: 86400,
+  // 24h
+  SET_THRESHOLD: 172800,
+  // 48h
+  ADD_VERIFIER: 172800,
+  // 48h
+  REMOVE_VERIFIER: 86400,
+  // 24h
+  ADD_GUARDIAN: 86400,
+  // 24h
+  REMOVE_GUARDIAN: 86400,
+  // 24h
+  RECOVERY: 604800
+  // 7d — `TIMELOCK_RECOVERY`, the headline UX gate
+};
+var DEFAULT_OP_EXPIRY_SECONDS = 1209600;
+function _felt2(x, field = "felt") {
+  const v = typeof x === "bigint" ? x : BigInt(x);
+  if (v < 0n) {
+    throw new RangeError(`${field} must be a non-negative felt; got ${v.toString()}`);
   }
-  /**
-   * Resolve bearer token - uses provided token or falls back to apiSecretKey
-   */
-  resolveBearerToken(bearerToken) {
-    const token = bearerToken ?? this.apiSecretKey;
-    if (!token) {
-      throw new Error(
-        "Authentication required: either pass a bearerToken or configure the SDK with an apiSecretKey"
+  return v;
+}
+function _encodeOwnerInput(input) {
+  if (input.weight < 0) {
+    throw new RangeError(`NewOwnerInput.weight must be non-negative; got ${input.weight}`);
+  }
+  const kindFelt = _felt2(BigInt(starknet.shortString.encodeShortString(input.kind)), "kind");
+  const roleFelt = input.role === "OWNER" ? ROLE_OWNER : ROLE_GUARDIAN;
+  const pubkey = input.pubkeyBytes.map((p, i) => _felt2(p, `pubkeyBytes[${i}]`));
+  return [
+    kindFelt,
+    BigInt(pubkey.length),
+    ...pubkey,
+    roleFelt,
+    BigInt(input.weight),
+    _felt2(BigInt(starknet.shortString.encodeShortString(input.label)), "label")
+  ];
+}
+function _call(walletAddress, entrypoint, calldata) {
+  for (let i = 0; i < calldata.length; i++) {
+    if (calldata[i] < 0n) {
+      throw new RangeError(
+        `calldata[${i}] must be a non-negative felt; got ${calldata[i].toString()}`
       );
     }
-    return token;
-  }
-  /**
-   * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
-   *
-   * @example
-   * ```typescript
-   * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
-   * const paymaster = sdk.createPaymasterAdapter();
-   *
-   * const txHash = await new TxBuilder(account, { paymaster })
-   *   .transfer(USDC, [{ to, amount }])
-   *   .sendSponsored(); // gasless!
-   * ```
-   */
-  createPaymasterAdapter(bearerToken) {
-    const token = this.resolveBearerToken(bearerToken);
-    return new ChipiPaymasterAdapter(this.client, token);
-  }
-  /**
-   * Create an X402Facilitator for verifying and settling x402 payments.
-   *
-   * @example
-   * ```typescript
-   * const facilitator = sdk.createX402Facilitator();
-   *
-   * // With custom nonce store (Redis)
-   * const facilitator = sdk.createX402Facilitator(bearerToken, {
-   *   nonceStore: {
-   *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
-   *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
-   *   },
-   * });
-   * ```
-   */
-  createX402Facilitator(bearerToken, config) {
-    const token = this.resolveBearerToken(bearerToken);
-    return new X402Facilitator(this.client, token, config);
-  }
-  /**
-   * Execute a gasless transaction
-   */
-  async executeTransaction({
-    params,
-    bearerToken
-  }) {
-    return this.transactions.executeTransaction({
-      params,
-      bearerToken: this.resolveBearerToken(bearerToken)
-    });
-  }
-  /**
-   * Execute a gasless transaction using a session key.
-   *
-   * This uses the 4-element session signature format instead of owner signature.
-   * The session must be:
-   * 1. Generated via `sessions.createSessionKey()`
-   * 2. Registered on-chain via `sessions.addSessionKeyToContract()`
-   *
-   * CHIPI wallets only - will throw if wallet type is not CHIPI.
-   *
-   * @example
-   * ```typescript
-   * // 1. Create session key (store externally)
-   * const session = sdk.sessions.createSessionKey({ encryptKey });
-   *
-   * // 2. Register on contract (one-time)
-   * await sdk.sessions.addSessionKeyToContract({
-   *   encryptKey,
-   *   wallet,
-   *   sessionConfig: {
-   *     sessionPublicKey: session.publicKey,
-   *     validUntil: session.validUntil,
-   *     maxCalls: 1000,
-   *     allowedEntrypoints: []
-   *   }
-   * }, bearerToken);
-   *
-   * // 3. Execute transactions with session (no owner key needed)
-   * const txHash = await sdk.executeTransactionWithSession({
-   *   params: { encryptKey, wallet, session, calls },
-   *   bearerToken
-   * });
-   * ```
-   */
-  async executeTransactionWithSession({
-    params,
-    bearerToken
-  }) {
-    return this.sessions.executeTransactionWithSession(
-      params,
-      this.resolveBearerToken(bearerToken)
-    );
   }
-  /**
-   * Sign SNIP-12 typed data without executing a transaction.
-   *
-   * Purely local operation: decrypt private key → sign → return { r, s }.
-   * No API calls are made. Useful for x402 payment signatures and other
-   * off-chain signing flows.
+  return {
+    contractAddress: typeof walletAddress === "bigint" ? "0x" + walletAddress.toString(16) : walletAddress,
+    entrypoint,
+    calldata: calldata.map((v) => "0x" + v.toString(16))
+  };
+}
+function buildProposeAddOwnerCall(args) {
+  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "propose_add_owner", calldata);
+}
+function buildExecuteAddOwnerCall(args) {
+  const calldata = [_felt2(args.opId), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "execute_add_owner", calldata);
+}
+function buildProposeRemoveOwnerCall(args) {
+  return _call(args.walletAddress, "propose_remove_owner", [
+    BigInt(args.proposer),
+    BigInt(args.ownerId)
+  ]);
+}
+function buildExecuteRemoveOwnerCall(args) {
+  return _call(args.walletAddress, "execute_remove_owner", [
+    _felt2(args.opId),
+    BigInt(args.ownerId)
+  ]);
+}
+function buildProposeRotateOwnerCall(args) {
+  return _call(args.walletAddress, "propose_rotate_owner", [
+    BigInt(args.proposer),
+    BigInt(args.ownerId),
+    BigInt(args.newPubkeyBytes.length),
+    ...args.newPubkeyBytes
+  ]);
+}
+function buildExecuteRotateOwnerCall(args) {
+  return _call(args.walletAddress, "execute_rotate_owner", [
+    _felt2(args.opId),
+    BigInt(args.ownerId),
+    BigInt(args.newPubkeyBytes.length),
+    ...args.newPubkeyBytes
+  ]);
+}
+function buildProposeSetThresholdCall(args) {
+  return _call(args.walletAddress, "propose_set_threshold", [
+    BigInt(args.proposer),
+    BigInt(args.newThreshold)
+  ]);
+}
+function buildExecuteSetThresholdCall(args) {
+  return _call(args.walletAddress, "execute_set_threshold", [
+    _felt2(args.opId),
+    BigInt(args.newThreshold)
+  ]);
+}
+function buildCancelPendingOpCall(args) {
+  return _call(args.walletAddress, "cancel_pending_op", [_felt2(args.opId)]);
+}
+function _verifierClassHash(kind, classHash) {
+  const h = classHash ?? shared.SHHH_VERIFIER_CLASS_HASHES[kind];
+  if (!h) throw new Error(`No verifier class hash known for kind "${kind}".`);
+  return _felt2(h, "classHash");
+}
+function buildProposeAddVerifierClassCall(args) {
+  const kindFelt = BigInt(starknet.shortString.encodeShortString(args.kind));
+  return _call(args.walletAddress, "propose_add_verifier_class", [
+    BigInt(args.proposer),
+    kindFelt,
+    _verifierClassHash(args.kind, args.classHash)
+  ]);
+}
+function buildExecuteAddVerifierClassCall(args) {
+  const kindFelt = BigInt(starknet.shortString.encodeShortString(args.kind));
+  return _call(args.walletAddress, "execute_add_verifier_class", [
+    _felt2(args.opId),
+    kindFelt,
+    _verifierClassHash(args.kind, args.classHash)
+  ]);
+}
+function buildInitiateRecoveryCall(args) {
+  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
+  return _call(args.walletAddress, "initiate_recovery", calldata);
+}
+function buildCancelRecoveryCall(args) {
+  return _call(args.walletAddress, "cancel_recovery", [BigInt(args.ownerId)]);
+}
+function buildFinalizeRecoveryCall(args) {
+  return _call(args.walletAddress, "finalize_recovery", _encodeOwnerInput(args.newOwner));
+}
+var VIEW_SELECTORS = {
+  get_pending_op: starknet.hash.getSelectorFromName("get_pending_op"),
+  get_pending_recovery: starknet.hash.getSelectorFromName("get_pending_recovery"),
+  get_owner: starknet.hash.getSelectorFromName("get_owner")
+};
+function _toSecondsBigInt(value, field) {
+  if (typeof value === "bigint") return value;
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${field} must be a finite timestamp; got ${value}`);
+  }
+  return BigInt(Math.floor(value));
+}
+function isReadyToExecute(validAfterSecs, nowSecs) {
+  return _toSecondsBigInt(nowSecs, "nowSecs") >= _toSecondsBigInt(validAfterSecs, "validAfterSecs");
+}
+function secondsUntilExecutable(validAfterSecs, nowSecs) {
+  const remaining = _toSecondsBigInt(validAfterSecs, "validAfterSecs") - _toSecondsBigInt(nowSecs, "nowSecs");
+  return remaining <= 0n ? 0 : Number(remaining);
+}
+function _decodeShort(value) {
+  const v = BigInt(value);
+  return v === 0n ? "" : starknet.shortString.decodeShortString(starknet.num.toHex(v));
+}
+function _view(provider, walletAddress, entrypoint, calldata = []) {
+  return provider.callContract({
+    contractAddress: typeof walletAddress === "bigint" ? starknet.num.toHex(walletAddress) : walletAddress,
+    entrypoint,
+    calldata: calldata.map((v) => starknet.num.toHex(BigInt(v)))
+  });
+}
+async function readShhhOwners(provider, walletAddress) {
+  const [countFelt] = await _view(provider, walletAddress, "owner_count");
+  const count = Number(BigInt(countFelt));
+  const owners = [];
+  for (let id = 0; id < count; id++) {
+    owners.push(decodeShhhOwnerRecord(id, await _view(provider, walletAddress, "get_owner", [id])));
+  }
+  return owners;
+}
+function decodeShhhOwnerRecord(ownerId, felts) {
+  if (felts.length < 9) {
+    throw new Error(`get_owner returned ${felts.length} felts; expected 9 (OwnerRecord).`);
+  }
+  return {
+    ownerId,
+    kind: _decodeShort(felts[0]),
+    pubkeyHash: BigInt(felts[1]),
+    role: _decodeShort(felts[4]),
+    weight: Number(BigInt(felts[5])),
+    addedAt: Number(BigInt(felts[6])),
+    label: _decodeShort(felts[7]),
+    revoked: BigInt(felts[8]) !== 0n
+  };
+}
+async function readVerifierClass(provider, walletAddress, kind) {
+  const [h] = await _view(provider, walletAddress, "get_verifier_class", [
+    BigInt(starknet.shortString.encodeShortString(kind))
+  ]);
+  return BigInt(h ?? 0);
+}
+async function readPendingRecovery(provider, walletAddress) {
+  const r = await _view(provider, walletAddress, "get_pending_recovery");
+  return {
+    initiatedAt: Number(BigInt(r[0])),
+    validAfter: Number(BigInt(r[1])),
+    newOwnerHash: BigInt(r[2]),
+    isActive: BigInt(r[3]) !== 0n
+  };
+}
+var OP_PROPOSED_KEY = BigInt(starknet.hash.getSelectorFromName("OpProposed"));
+function parseOpProposedEvents(events, walletAddress) {
+  const wallet = walletAddress === void 0 ? void 0 : BigInt(walletAddress);
+  return events.filter(
+    (e) => e.keys.length >= 3 && BigInt(e.keys[0]) === OP_PROPOSED_KEY && (wallet === void 0 || e.from_address !== void 0 && BigInt(e.from_address) === wallet)
+  ).map((e) => ({
+    opId: BigInt(e.keys[1]),
+    opKind: _decodeShort(e.keys[2]),
+    proposer: Number(BigInt(e.data[0])),
+    payload: BigInt(e.data[1]),
+    validAfter: Number(BigInt(e.data[2])),
+    expiresAt: Number(BigInt(e.data[3]))
+  }));
+}
+
+// src/shhh/signers/stark-snip12.ts
+var STARK_SNIP12_KIND_TAG = "STARK_SNIP12";
+var STARK_KIND_TAG_FELT2 = BigInt(starknet.shortString.encodeShortString("STARK"));
+var V2_SNIP12_FELT = BigInt(starknet.shortString.encodeShortString("V2_SNIP12"));
+function domainChainId(chainId) {
+  if (typeof chainId === "string" && !chainId.startsWith("0x")) return chainId;
+  return starknet.shortString.decodeShortString(toFeltHex(chainId));
+}
+function felt(value) {
+  return BigInt(value);
+}
+function starkSnip12ApprovalTypedData(params) {
+  return {
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      Approval: [
+        { name: "Wallet", type: "ContractAddress" },
+        { name: "Hash", type: "felt" }
+      ]
+    },
+    primaryType: "Approval",
+    domain: {
+      name: "Shhh",
+      version: "1",
+      chainId: domainChainId(params.chainId ?? "SN_MAIN"),
+      revision: "1"
+    },
+    message: {
+      Wallet: normalizeStarknetAddress(params.walletAddress),
+      Hash: toFeltHex(params.messageHash)
+    }
+  };
+}
+function starkSnip12ApprovalHash(params) {
+  const td = starkSnip12ApprovalTypedData(params);
+  return BigInt(starknet.typedData.getMessageHash(td, normalizeStarknetAddress(params.signerAddress)));
+}
+function starkSnip12PubkeyFelts(starkPubkey, signerAddress) {
+  const pub = felt(starkPubkey);
+  const account = BigInt(normalizeStarknetAddress(signerAddress));
+  if (pub === 0n || account === 0n) {
+    throw new Error("starkSnip12PubkeyFelts: the key and the account address must be non-zero.");
+  }
+  return [pub, account];
+}
+function starkSnip12OwnerCommitment(starkPubkey, signerAddress) {
+  return ownerCommitment(
+    BigInt(starknet.shortString.encodeShortString(STARK_SNIP12_KIND_TAG)),
+    starkSnip12PubkeyFelts(starkPubkey, signerAddress)
+  );
+}
+function parseStarknetWalletSignature(signature) {
+  const sig = signature.map((v) => felt(v));
+  if (sig.length === 2) return { r: sig[0], s: sig[1] };
+  if (sig.length === 5 && sig[0] === 1n && sig[1] === 0n) {
+    return { pubkey: sig[2], r: sig[3], s: sig[4] };
+  }
+  if (sig.length === 5 && sig[0] === V2_SNIP12_FELT && sig[2] === STARK_KIND_TAG_FELT2) {
+    return { shhhOwnerId: sig[1], r: sig[3], s: sig[4] };
+  }
+  throw new Error(
+    `This wallet returned a ${sig.length}-felt signature that isn't a single STARK key (multisig, hardware or passkey signers aren't supported as a SHHH co-owner yet).`
+  );
+}
+function starkVerifyX(r, s, msgHash, pubkeyX) {
+  const x = pubkeyX.toString(16).padStart(64, "0");
+  const sig = new starknet.ec.starkCurve.Signature(r, s);
+  for (const prefix of ["02", "03"]) {
+    try {
+      if (starknet.ec.starkCurve.verify(sig, toFeltHex(msgHash), prefix + x)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function verifyStarkSnip12Approval(params) {
+  const { r, s } = parseStarknetWalletSignature(params.signature);
+  const h = starkSnip12ApprovalHash(params);
+  return starkVerifyX(r, s, h, felt(params.starkPubkey));
+}
+function buildStarkSnip12Envelope(params) {
+  if (params.ownerIndex < 0n || params.ownerIndex >= 0x100000000n) {
+    throw new Error(
+      `buildStarkSnip12Envelope: ownerIndex ${params.ownerIndex} is out of u32 range. Pass the owner's index in the owner_set, not its commitment.`
+    );
+  }
+  const { r, s } = parseStarknetWalletSignature(params.signature);
+  return wrapV2Snip12Envelope({
+    ownerId: params.ownerIndex,
+    kindTag: STARK_SNIP12_KIND_TAG,
+    payload: [r, s]
+  });
+}
+function recoverStarkKeys(r, s, msgHash) {
+  const out = [];
+  for (const bit of [0, 1]) {
+    try {
+      const point = new starknet.ec.starkCurve.Signature(r, s).addRecoveryBit(bit).recoverPublicKey(msgHash.toString(16).padStart(64, "0"));
+      out.push(point.toAffine().x);
+    } catch {
+    }
+  }
+  return out;
+}
+async function tryCall(provider, contractAddress, entrypoint, calldata = []) {
+  try {
+    return await provider.callContract({ contractAddress, entrypoint, calldata });
+  } catch {
+    return null;
+  }
+}
+async function resolveStarkSnip12Signer(params) {
+  const signer = normalizeStarknetAddress(params.signerAddress);
+  const parsed = parseStarknetWalletSignature(params.signature);
+  const approvalHash = starkSnip12ApprovalHash(params);
+  const candidates = [];
+  if (parsed.pubkey !== void 0) candidates.push(parsed.pubkey);
+  if (parsed.shhhOwnerId !== void 0) {
+    const felts = await tryCall(params.provider, signer, "get_owner", [
+      toFeltHex(parsed.shhhOwnerId)
+    ]);
+    const record = felts && felts.length >= 9 ? decodeShhhOwnerRecord(0, felts) : null;
+    if (record && !record.revoked && record.kind === "STARK" && record.role === "OWNER") {
+      for (const key2 of recoverStarkKeys(parsed.r, parsed.s, approvalHash)) {
+        if (ownerCommitment(STARK_KIND_TAG_FELT2, [key2]) === record.pubkeyHash) candidates.push(key2);
+      }
+    }
+    if (candidates.length === 0) {
+      throw new Error(
+        `Couldn't confirm the Chipi wallet's signer: owner ${parsed.shhhOwnerId} of ${signer} is not an active STARK owner whose key made this signature.`
+      );
+    }
+  }
+  if (params.deploymentData && normalizeStarknetAddress(params.deploymentData.address) === signer) {
+    const cls = normalizeStarknetAddress(params.deploymentData.class_hash);
+    const cd = params.deploymentData.calldata;
+    if (cls === COUNTERFACTUAL_ACCOUNT_CLASSES.OPENZEPPELIN_V3 && cd.length === 1) {
+      candidates.push(felt(cd[0]));
+    }
+    if (cls === COUNTERFACTUAL_ACCOUNT_CLASSES.ARGENT_V0_4 && cd.length === 3) {
+      candidates.push(felt(cd[1]));
+    }
+  }
+  if (candidates.length === 0) {
+    const oz = await tryCall(params.provider, signer, "get_public_key");
+    if (oz && oz.length >= 1) candidates.push(felt(oz[0]));
+  }
+  if (candidates.length === 0) {
+    const signers = await tryCall(params.provider, signer, "get_signers");
+    if (signers && signers.length >= 1) {
+      const starkLen = Number(BigInt(signers[0]));
+      const rest = signers.slice(1 + starkLen);
+      const onlyStark = rest.every((v) => BigInt(v) === 0n);
+      if (starkLen === 1 && onlyStark) candidates.push(felt(signers[1]));
+    }
+  }
+  const key = candidates.find((k) => starkVerifyX(parsed.r, parsed.s, approvalHash, k));
+  if (key === void 0) {
+    throw new Error(
+      "Couldn't confirm which key signs for this wallet. It may use a hardware or passkey signer, a multisig, or an account type we don't read yet."
+    );
+  }
+  return { starkPubkey: key, pubkeyFelts: starkSnip12PubkeyFelts(key, signer) };
+}
+
+// src/shhh/execute-external-owner.ts
+function prepareExternalOwnerExecution(params) {
+  const walletAddress = normalizeStarknetAddress(params.walletAddress);
+  const outsideExecution = buildOutsideExecution({
+    nonce: params.nonce ?? newOeNonce(),
+    calls: params.calls,
+    caller: exports.ANY_CALLER_FELT
+  });
+  const chainId = resolveShhhChainId({ override: params.chainId });
+  const messageHash = computeOeHash(outsideExecution, walletAddress, chainId);
+  const typedData2 = starkSnip12ApprovalTypedData({ walletAddress, messageHash, chainId });
+  return { walletAddress, outsideExecution, messageHash, typedData: typedData2, chainId };
+}
+async function submitExternalOwnerExecution(params) {
+  const { prepared } = params;
+  if (params.signer && !verifyStarkSnip12Approval({
+    walletAddress: prepared.walletAddress,
+    messageHash: prepared.messageHash,
+    signerAddress: params.signer.address,
+    starkPubkey: params.signer.starkPubkey,
+    signature: params.signature,
+    chainId: prepared.chainId
+  })) {
+    throw new Error(
+      "The signature doesn't match this wallet's registered key. Sign with the same wallet and account you added."
+    );
+  }
+  const envelope = buildStarkSnip12Envelope({
+    signature: params.signature,
+    ownerIndex: BigInt(params.ownerIndex)
+  });
+  const calldata = serializeExecuteFromOutsideV2Calldata({
+    outsideExecution: prepared.outsideExecution,
+    signature: envelope
+  });
+  const response = await params.client.post({
+    endpoint: "/transactions/execute-sponsored-raw",
+    bearerToken: params.bearerToken,
+    body: {
+      accountAddress: prepared.walletAddress,
+      calldata,
+      ...params.externalUserId ? { externalUserId: params.externalUserId } : {}
+    }
+  });
+  if (!response?.transactionHash) {
+    throw new Error(
+      "execute-sponsored-raw response missing transactionHash. Check the chipi-back logs for upstream paymaster errors."
+    );
+  }
+  return response.transactionHash;
+}
+async function executeShhhWithExternalSigner(params) {
+  const prepared = prepareExternalOwnerExecution(params);
+  const signature = await params.signTypedData(prepared.typedData);
+  return submitExternalOwnerExecution({ ...params, prepared, signature });
+}
+async function executeShhhWithStarkKey(params) {
+  const walletAddress = normalizeStarknetAddress(params.walletAddress);
+  const outsideExecution = buildOutsideExecution({
+    nonce: params.nonce ?? newOeNonce(),
+    calls: params.calls,
+    caller: exports.ANY_CALLER_FELT
+  });
+  const chainId = resolveShhhChainId({ override: params.chainId });
+  const messageHash = computeOeHash(outsideExecution, walletAddress, chainId);
+  const signature = buildStarkEnvelope({
+    privateKey: params.privateKey,
+    messageHash,
+    ownerIndex: BigInt(params.ownerIndex)
+  });
+  const calldata = serializeExecuteFromOutsideV2Calldata({ outsideExecution, signature });
+  const response = await params.client.post({
+    endpoint: "/transactions/execute-sponsored-raw",
+    bearerToken: params.bearerToken,
+    body: {
+      accountAddress: walletAddress,
+      calldata,
+      signerKind: "STARK",
+      ...params.externalUserId ? { externalUserId: params.externalUserId } : {}
+    }
+  });
+  if (!response?.transactionHash) {
+    throw new Error(
+      "execute-sponsored-raw response missing transactionHash. Check the chipi-back logs for upstream paymaster errors."
+    );
+  }
+  return response.transactionHash;
+}
+
+// src/chipi-sdk.ts
+var ChipiSDK = class {
+  constructor(config) {
+    this.client = new ChipiClient(config);
+    this.nodeUrl = config.nodeUrl || shared.STARKNET_NETWORKS.MAINNET;
+    this.apiSecretKey = config.apiSecretKey;
+    this.wallets = new ChipiWallets(this.client);
+    this.transactions = new ChipiTransactions(this.client);
+    this.skuPurchases = new ChipiSkuPurchases(this.client);
+    this.skus = new ChipiSkus(this.client);
+    this.sessions = new ChipiSessions(this.client);
+    this.exchanges = new ChipiExchanges(this.client);
+    this.treasury = new ChipiTreasury(this.client, config.apiSecretKey);
+    this.ai = new ChipiAi(this.client, config.apiSecretKey, this.sessions);
+    this.executeTransaction = this.executeTransaction.bind(this);
+    this.executeTransactionWithSession = this.executeTransactionWithSession.bind(this);
+    this.transfer = this.transfer.bind(this);
+    this.approve = this.approve.bind(this);
+    this.callAnyContract = this.callAnyContract.bind(this);
+    this.createWallet = this.createWallet.bind(this);
+    this.recordSendTransaction = this.recordSendTransaction.bind(this);
+    this.purchaseSku = this.purchaseSku.bind(this);
+    this.getUsdAmount = this.getUsdAmount.bind(this);
+    this.signTypedData = this.signTypedData.bind(this);
+    this.signTypedDataArray = this.signTypedDataArray.bind(this);
+    this.executeWithExternalSigner = this.executeWithExternalSigner.bind(this);
+    this.createPaymasterAdapter = this.createPaymasterAdapter.bind(this);
+    this.createX402Facilitator = this.createX402Facilitator.bind(this);
+  }
+  /**
+   * Resolve bearer token - uses provided token or falls back to apiSecretKey
+   */
+  resolveBearerToken(bearerToken) {
+    const token = bearerToken ?? this.apiSecretKey;
+    if (!token) {
+      throw new Error(
+        "Authentication required: either pass a bearerToken or configure the SDK with an apiSecretKey"
+      );
+    }
+    return token;
+  }
+  /**
+   * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
+   *
+   * @example
+   * ```typescript
+   * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
+   * const paymaster = sdk.createPaymasterAdapter();
+   *
+   * const txHash = await new TxBuilder(account, { paymaster })
+   *   .transfer(USDC, [{ to, amount }])
+   *   .sendSponsored(); // gasless!
+   * ```
+   */
+  createPaymasterAdapter(bearerToken) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new ChipiPaymasterAdapter(this.client, token);
+  }
+  /**
+   * Create an X402Facilitator for verifying and settling x402 payments.
+   *
+   * @example
+   * ```typescript
+   * const facilitator = sdk.createX402Facilitator();
+   *
+   * // With custom nonce store (Redis)
+   * const facilitator = sdk.createX402Facilitator(bearerToken, {
+   *   nonceStore: {
+   *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
+   *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
+   *   },
+   * });
+   * ```
+   */
+  createX402Facilitator(bearerToken, config) {
+    const token = this.resolveBearerToken(bearerToken);
+    return new X402Facilitator(this.client, token, config);
+  }
+  /**
+   * Execute a gasless transaction
+   */
+  async executeTransaction({
+    params,
+    bearerToken
+  }) {
+    return this.transactions.executeTransaction({
+      params,
+      bearerToken: this.resolveBearerToken(bearerToken)
+    });
+  }
+  /**
+   * Execute a gasless transaction using a session key.
+   *
+   * This uses the 4-element session signature format instead of owner signature.
+   * The session must be:
+   * 1. Generated via `sessions.createSessionKey()`
+   * 2. Registered on-chain via `sessions.addSessionKeyToContract()`
+   *
+   * CHIPI wallets only - will throw if wallet type is not CHIPI.
+   *
+   * @example
+   * ```typescript
+   * // 1. Create session key (store externally)
+   * const session = sdk.sessions.createSessionKey({ encryptKey });
+   *
+   * // 2. Register on contract (one-time)
+   * await sdk.sessions.addSessionKeyToContract({
+   *   encryptKey,
+   *   wallet,
+   *   sessionConfig: {
+   *     sessionPublicKey: session.publicKey,
+   *     validUntil: session.validUntil,
+   *     maxCalls: 1000,
+   *     allowedEntrypoints: []
+   *   }
+   * }, bearerToken);
+   *
+   * // 3. Execute transactions with session (no owner key needed)
+   * const txHash = await sdk.executeTransactionWithSession({
+   *   params: { encryptKey, wallet, session, calls },
+   *   bearerToken
+   * });
+   * ```
+   */
+  async executeTransactionWithSession({
+    params,
+    bearerToken
+  }) {
+    return this.sessions.executeTransactionWithSession(
+      params,
+      this.resolveBearerToken(bearerToken)
+    );
+  }
+  /**
+   * Sign SNIP-12 typed data without executing a transaction.
+   *
+   * Purely local operation: decrypt private key → sign → return { r, s }.
+   * No API calls are made. Useful for x402 payment signatures and other
+   * off-chain signing flows.
    *
    * @example
    * ```typescript
@@ -4012,6 +4678,39 @@ var ChipiSDK = class {
   async signTypedDataArray({ params }) {
     return signTypedDataArray({ params });
   }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async executeWithExternalSigner({
+    params,
+    bearerToken
+  }) {
+    return executeShhhWithExternalSigner({
+      ...params,
+      client: this.client,
+      bearerToken: this.resolveBearerToken(bearerToken)
+    });
+  }
   /**
    * Transfer tokens
    */
@@ -4128,8 +4827,8 @@ var ChipiSDK = class {
   /**
    * Get on-chain transaction status (supports polling for confirmation)
    */
-  async getTransactionStatus(hash11, bearerToken) {
-    return this.transactions.getTransactionStatus(hash11, this.resolveBearerToken(bearerToken));
+  async getTransactionStatus(hash13, bearerToken) {
+    return this.transactions.getTransactionStatus(hash13, this.resolveBearerToken(bearerToken));
   }
   /**
    * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
@@ -4501,12 +5200,135 @@ function x402Middleware(config) {
     next();
   };
 }
+var SIWS_DOMAIN_NAME = "Sign in with Starknet";
+var SIWS_DOMAIN_VERSION = "1";
+var SIWS_CHAIN_ID = "SN_MAIN";
+var DEFAULT_STATEMENT = "Sign in. This request costs nothing and moves no funds.";
+function assertPrintableAscii(field, value) {
+  if (!/^[\x20-\x7e]*$/.test(value)) {
+    throw new Error(`SIWS ${field} must be single-line printable ASCII`);
+  }
+}
+function createStarknetSignInTypedData(params) {
+  const message = {
+    domain: params.domain,
+    address: normalizeStarknetAddress(params.address),
+    statement: params.statement ?? DEFAULT_STATEMENT,
+    uri: params.uri,
+    nonce: params.nonce,
+    issuedAt: params.issuedAt ?? Math.floor(Date.now() / 1e3),
+    expirationTime: params.expirationTime
+  };
+  for (const field of ["domain", "statement", "uri", "nonce"]) {
+    assertPrintableAscii(field, message[field]);
+  }
+  if (!/^[A-Za-z0-9]{8,}$/.test(message.nonce)) {
+    throw new Error("SIWS nonce must be at least 8 letters or digits");
+  }
+  if (!Number.isInteger(message.issuedAt) || !Number.isInteger(message.expirationTime)) {
+    throw new Error("SIWS times must be whole unix seconds");
+  }
+  if (message.expirationTime <= message.issuedAt) {
+    throw new Error("SIWS expirationTime must be after issuedAt");
+  }
+  return {
+    types: {
+      StarknetDomain: [
+        { name: "name", type: "shortstring" },
+        { name: "version", type: "shortstring" },
+        { name: "chainId", type: "shortstring" },
+        { name: "revision", type: "shortstring" }
+      ],
+      SignIn: [
+        { name: "domain", type: "string" },
+        { name: "address", type: "ContractAddress" },
+        { name: "statement", type: "string" },
+        { name: "uri", type: "string" },
+        { name: "nonce", type: "string" },
+        { name: "issuedAt", type: "timestamp" },
+        { name: "expirationTime", type: "timestamp" }
+      ]
+    },
+    primaryType: "SignIn",
+    domain: {
+      name: SIWS_DOMAIN_NAME,
+      version: SIWS_DOMAIN_VERSION,
+      chainId: SIWS_CHAIN_ID,
+      revision: "1"
+    },
+    message: { ...message }
+  };
+}
+var MAX_SKEW_SECONDS = 60;
+var SIWS_CHAIN_ID_FELT = BigInt(starknet.shortString.encodeShortString(SIWS_CHAIN_ID));
+function isMainnetChainId(chainId) {
+  if (chainId === SIWS_CHAIN_ID) return true;
+  if (typeof chainId === "bigint") return chainId === SIWS_CHAIN_ID_FELT;
+  if (typeof chainId !== "string" || !/^(0x[0-9a-f]+|[0-9]+)$/i.test(chainId)) return false;
+  return BigInt(chainId) === SIWS_CHAIN_ID_FELT;
+}
+async function verifyStarknetSignIn(params) {
+  const { typedData: typedData2, signature, provider, expected, deploymentData } = params;
+  const raw = typedData2?.message;
+  if (!raw || !Array.isArray(signature) || signature.length === 0) {
+    return { ok: false, reason: "MALFORMED" };
+  }
+  if (!isMainnetChainId(typedData2.domain?.chainId)) return { ok: false, reason: "WRONG_CHAIN" };
+  let canonical;
+  let message;
+  try {
+    canonical = createStarknetSignInTypedData({
+      domain: String(raw.domain),
+      uri: String(raw.uri),
+      address: String(raw.address),
+      nonce: String(raw.nonce),
+      statement: String(raw.statement),
+      issuedAt: Number(raw.issuedAt),
+      expirationTime: Number(raw.expirationTime)
+    });
+    message = canonical.message;
+  } catch {
+    return { ok: false, reason: "MALFORMED" };
+  }
+  if (message.domain !== expected.domain) return { ok: false, reason: "WRONG_DOMAIN" };
+  if (message.uri !== expected.uri) return { ok: false, reason: "WRONG_URI" };
+  if (message.nonce !== expected.nonce) return { ok: false, reason: "WRONG_NONCE" };
+  const now = expected.now ?? Math.floor(Date.now() / 1e3);
+  if (now >= message.expirationTime) return { ok: false, reason: "EXPIRED" };
+  if (message.issuedAt > now + MAX_SKEW_SECONDS) return { ok: false, reason: "NOT_YET_VALID" };
+  const messageHash = starknet.typedData.getMessageHash(canonical, message.address);
+  const onChain = await isValidStarknetSignature(provider, message.address, messageHash, signature);
+  if (onChain.valid) return { ok: true, address: message.address, message };
+  if (onChain.reason !== "ACCOUNT_NOT_DEPLOYED") return { ok: false, reason: "INVALID_SIGNATURE" };
+  if (!deploymentData) return { ok: false, reason: "ACCOUNT_NOT_DEPLOYED" };
+  if (normalizeStarknetAddress(deploymentData.address) !== message.address) {
+    return { ok: false, reason: "ADDRESS_MISMATCH" };
+  }
+  const offChain = verifyUndeployedStarknetSignature(deploymentData, messageHash, signature);
+  return offChain.valid ? { ok: true, address: message.address, message } : { ok: false, reason: offChain.reason };
+}
 
 // src/shhh/index.ts
 init_snip12_hash();
 init_compute_wallet_address();
 init_oe();
 init_stark();
+function isClassHashNotFound(err) {
+  const e = err;
+  if (e?.baseError?.code === 28 || e?.code === 28) return true;
+  return /class hash not found/i.test(e?.message ?? String(err));
+}
+async function isShhhVerifierDeclared(provider, kind, classHash = shared.SHHH_VERIFIER_CLASS_HASHES[kind]) {
+  try {
+    await provider.getClassByHash(classHash);
+    return true;
+  } catch (err) {
+    if (isClassHashNotFound(err)) return false;
+    throw err;
+  }
+}
+
+// src/shhh/index.ts
 init_ed25519();
 
 // src/shhh/signers/eip191.ts
@@ -5174,150 +5996,6 @@ async function buildJwtAppleSubEnvelopeFromTestKey(params) {
   });
   return { envelope, pubkey, idToken };
 }
-var ROLE_OWNER = BigInt(starknet.shortString.encodeShortString("OWNER"));
-var ROLE_GUARDIAN = BigInt(starknet.shortString.encodeShortString("GUARDIAN"));
-var OP_ADD_OWNER = BigInt(starknet.shortString.encodeShortString("ADD_OWNER"));
-var OP_REMOVE_OWNER = BigInt(starknet.shortString.encodeShortString("REMOVE_OWNER"));
-var OP_ROTATE_OWNER = BigInt(starknet.shortString.encodeShortString("ROTATE_OWNER"));
-var OP_SET_THRESHOLD = BigInt(starknet.shortString.encodeShortString("SET_THRESHOLD"));
-var TIMELOCK_SECONDS = {
-  ADD_OWNER: 172800,
-  // 48h
-  REMOVE_OWNER: 86400,
-  // 24h
-  ROTATE_OWNER: 86400,
-  // 24h
-  SET_THRESHOLD: 172800,
-  // 48h
-  ADD_VERIFIER: 172800,
-  // 48h
-  REMOVE_VERIFIER: 86400,
-  // 24h
-  ADD_GUARDIAN: 86400,
-  // 24h
-  REMOVE_GUARDIAN: 86400,
-  // 24h
-  RECOVERY: 604800
-  // 7d — `TIMELOCK_RECOVERY`, the headline UX gate
-};
-var DEFAULT_OP_EXPIRY_SECONDS = 1209600;
-function _felt2(x, field = "felt") {
-  const v = typeof x === "bigint" ? x : BigInt(x);
-  if (v < 0n) {
-    throw new RangeError(`${field} must be a non-negative felt; got ${v.toString()}`);
-  }
-  return v;
-}
-function _encodeOwnerInput(input) {
-  if (input.weight < 0) {
-    throw new RangeError(`NewOwnerInput.weight must be non-negative; got ${input.weight}`);
-  }
-  const kindFelt = _felt2(BigInt(starknet.shortString.encodeShortString(input.kind)), "kind");
-  const roleFelt = input.role === "OWNER" ? ROLE_OWNER : ROLE_GUARDIAN;
-  const pubkey = input.pubkeyBytes.map((p, i) => _felt2(p, `pubkeyBytes[${i}]`));
-  return [
-    kindFelt,
-    BigInt(pubkey.length),
-    ...pubkey,
-    roleFelt,
-    BigInt(input.weight),
-    _felt2(BigInt(starknet.shortString.encodeShortString(input.label)), "label")
-  ];
-}
-function _call(walletAddress, entrypoint, calldata) {
-  for (let i = 0; i < calldata.length; i++) {
-    if (calldata[i] < 0n) {
-      throw new RangeError(
-        `calldata[${i}] must be a non-negative felt; got ${calldata[i].toString()}`
-      );
-    }
-  }
-  return {
-    contractAddress: typeof walletAddress === "bigint" ? "0x" + walletAddress.toString(16) : walletAddress,
-    entrypoint,
-    calldata: calldata.map((v) => "0x" + v.toString(16))
-  };
-}
-function buildProposeAddOwnerCall(args) {
-  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "propose_add_owner", calldata);
-}
-function buildExecuteAddOwnerCall(args) {
-  const calldata = [_felt2(args.opId), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "execute_add_owner", calldata);
-}
-function buildProposeRemoveOwnerCall(args) {
-  return _call(args.walletAddress, "propose_remove_owner", [
-    BigInt(args.proposer),
-    BigInt(args.ownerId)
-  ]);
-}
-function buildExecuteRemoveOwnerCall(args) {
-  return _call(args.walletAddress, "execute_remove_owner", [
-    _felt2(args.opId),
-    BigInt(args.ownerId)
-  ]);
-}
-function buildProposeRotateOwnerCall(args) {
-  return _call(args.walletAddress, "propose_rotate_owner", [
-    BigInt(args.proposer),
-    BigInt(args.ownerId),
-    BigInt(args.newPubkeyBytes.length),
-    ...args.newPubkeyBytes
-  ]);
-}
-function buildExecuteRotateOwnerCall(args) {
-  return _call(args.walletAddress, "execute_rotate_owner", [
-    _felt2(args.opId),
-    BigInt(args.ownerId),
-    BigInt(args.newPubkeyBytes.length),
-    ...args.newPubkeyBytes
-  ]);
-}
-function buildProposeSetThresholdCall(args) {
-  return _call(args.walletAddress, "propose_set_threshold", [
-    BigInt(args.proposer),
-    BigInt(args.newThreshold)
-  ]);
-}
-function buildExecuteSetThresholdCall(args) {
-  return _call(args.walletAddress, "execute_set_threshold", [
-    _felt2(args.opId),
-    BigInt(args.newThreshold)
-  ]);
-}
-function buildCancelPendingOpCall(args) {
-  return _call(args.walletAddress, "cancel_pending_op", [_felt2(args.opId)]);
-}
-function buildInitiateRecoveryCall(args) {
-  const calldata = [BigInt(args.proposer), ..._encodeOwnerInput(args.newOwner)];
-  return _call(args.walletAddress, "initiate_recovery", calldata);
-}
-function buildCancelRecoveryCall(args) {
-  return _call(args.walletAddress, "cancel_recovery", [BigInt(args.ownerId)]);
-}
-function buildFinalizeRecoveryCall(args) {
-  return _call(args.walletAddress, "finalize_recovery", _encodeOwnerInput(args.newOwner));
-}
-var VIEW_SELECTORS = {
-  get_pending_op: starknet.hash.getSelectorFromName("get_pending_op"),
-  get_pending_recovery: starknet.hash.getSelectorFromName("get_pending_recovery"),
-  get_owner: starknet.hash.getSelectorFromName("get_owner")
-};
-function _toSecondsBigInt(value, field) {
-  if (typeof value === "bigint") return value;
-  if (!Number.isFinite(value)) {
-    throw new TypeError(`${field} must be a finite timestamp; got ${value}`);
-  }
-  return BigInt(Math.floor(value));
-}
-function isReadyToExecute(validAfterSecs, nowSecs) {
-  return _toSecondsBigInt(nowSecs, "nowSecs") >= _toSecondsBigInt(validAfterSecs, "validAfterSecs");
-}
-function secondsUntilExecutable(validAfterSecs, nowSecs) {
-  const remaining = _toSecondsBigInt(validAfterSecs, "validAfterSecs") - _toSecondsBigInt(nowSecs, "nowSecs");
-  return remaining <= 0n ? 0 : Number(remaining);
-}
 
 // src/shhh/index.ts
 init_threshold();
@@ -5413,6 +6091,7 @@ Object.defineProperty(exports, "Currency", {
 });
 exports.APPLE_ISSUER = APPLE_ISSUER;
 exports.BOOTSTRAP_DOMAIN_SEPARATOR = BOOTSTRAP_DOMAIN_SEPARATOR;
+exports.COUNTERFACTUAL_ACCOUNT_CLASSES = COUNTERFACTUAL_ACCOUNT_CLASSES;
 exports.ChipiAi = ChipiAi;
 exports.ChipiBrowserSDK = ChipiBrowserSDK;
 exports.ChipiClient = ChipiClient;
@@ -5427,11 +6106,17 @@ exports.ChipiTreasury = ChipiTreasury;
 exports.ChipiWallets = ChipiWallets;
 exports.DEFAULT_OP_EXPIRY_SECONDS = DEFAULT_OP_EXPIRY_SECONDS;
 exports.OP_ADD_OWNER = OP_ADD_OWNER;
+exports.OP_ADD_VERIFIER_CLASS = OP_ADD_VERIFIER_CLASS;
 exports.OP_REMOVE_OWNER = OP_REMOVE_OWNER;
 exports.OP_ROTATE_OWNER = OP_ROTATE_OWNER;
 exports.OP_SET_THRESHOLD = OP_SET_THRESHOLD;
 exports.ROLE_GUARDIAN = ROLE_GUARDIAN;
 exports.ROLE_OWNER = ROLE_OWNER;
+exports.SIWS_CHAIN_ID = SIWS_CHAIN_ID;
+exports.SIWS_DOMAIN_NAME = SIWS_DOMAIN_NAME;
+exports.SIWS_DOMAIN_VERSION = SIWS_DOMAIN_VERSION;
+exports.STARKNET_SIGNATURE_VALID = STARKNET_SIGNATURE_VALID;
+exports.STARK_SNIP12_KIND_TAG = STARK_SNIP12_KIND_TAG;
 exports.SessionTxVerifier = SessionTxVerifier;
 exports.ShhhAccount = ShhhAccount;
 exports.TIMELOCK_SECONDS = TIMELOCK_SECONDS;
@@ -5448,6 +6133,7 @@ exports.buildEd25519EnvelopeFromSignature = buildEd25519EnvelopeFromSignature;
 exports.buildEip191EnvelopeFromPrivateKey = buildEip191EnvelopeFromPrivateKey;
 exports.buildEip191EnvelopeFromSignature = buildEip191EnvelopeFromSignature;
 exports.buildExecuteAddOwnerCall = buildExecuteAddOwnerCall;
+exports.buildExecuteAddVerifierClassCall = buildExecuteAddVerifierClassCall;
 exports.buildExecuteRemoveOwnerCall = buildExecuteRemoveOwnerCall;
 exports.buildExecuteRotateOwnerCall = buildExecuteRotateOwnerCall;
 exports.buildExecuteSetThresholdCall = buildExecuteSetThresholdCall;
@@ -5458,6 +6144,7 @@ exports.buildJwtAppleSubEnvelopeFromTokenResponse = buildJwtAppleSubEnvelopeFrom
 exports.buildMigrationCalls = buildMigrationCalls;
 exports.buildOutsideExecution = buildOutsideExecution;
 exports.buildProposeAddOwnerCall = buildProposeAddOwnerCall;
+exports.buildProposeAddVerifierClassCall = buildProposeAddVerifierClassCall;
 exports.buildProposeRemoveOwnerCall = buildProposeRemoveOwnerCall;
 exports.buildProposeRotateOwnerCall = buildProposeRotateOwnerCall;
 exports.buildProposeSetThresholdCall = buildProposeSetThresholdCall;
@@ -5466,6 +6153,7 @@ exports.buildRevokeSessionKeyCall = buildRevokeSessionKeyCall;
 exports.buildSessionSetupCalls = buildSessionSetupCalls;
 exports.buildSetSpendingPolicyCall = buildSetSpendingPolicyCall;
 exports.buildStarkEnvelope = buildStarkEnvelope;
+exports.buildStarkSnip12Envelope = buildStarkSnip12Envelope;
 exports.buildThresholdEnvelope = buildThresholdEnvelope;
 exports.buildWebAuthnEnvelopeFromAssertion = buildWebAuthnEnvelopeFromAssertion;
 exports.buildWebAuthnEnvelopeFromPrivateKey = buildWebAuthnEnvelopeFromPrivateKey;
@@ -5476,6 +6164,7 @@ exports.computeISignerId = computeISignerId;
 exports.computeOeHash = computeOeHash;
 exports.computeShhhAddress = computeShhhAddress;
 exports.computeSnip12Hash = computeSnip12Hash;
+exports.createStarknetSignInTypedData = createStarknetSignInTypedData;
 exports.ed25519OwnerId = ed25519OwnerId;
 exports.ed25519OwnerPubkeyParam = ed25519OwnerPubkeyParam;
 exports.ed25519PubkeyFelts = ed25519PubkeyFelts;
@@ -5485,12 +6174,16 @@ exports.eip191OwnerPubkeyParam = eip191OwnerPubkeyParam;
 exports.eip191PubkeyFelts = eip191PubkeyFelts;
 exports.estimateThresholdGasOverhead = estimateThresholdGasOverhead;
 exports.executeShhhSponsoredRaw = executeShhhSponsoredRaw;
+exports.executeShhhWithExternalSigner = executeShhhWithExternalSigner;
+exports.executeShhhWithStarkKey = executeShhhWithStarkKey;
 exports.hashCall = hashCall;
 exports.hashCalls = hashCalls;
 exports.hashOutsideExecutionStruct = hashOutsideExecutionStruct;
 exports.hashStarknetDomain = hashStarknetDomain;
 exports.isReadyToExecute = isReadyToExecute;
+exports.isShhhVerifierDeclared = isShhhVerifierDeclared;
 exports.isThinkDecision = isThinkDecision;
+exports.isValidStarknetSignature = isValidStarknetSignature;
 exports.jwtAppleSubHash = jwtAppleSubHash;
 exports.jwtAppleSubOwnerId = jwtAppleSubOwnerId;
 exports.jwtAppleSubPubkeyFelts = jwtAppleSubPubkeyFelts;
@@ -5499,12 +6192,20 @@ exports.locateSubClaim = locateSubClaim;
 exports.messageHashToNonceB64url = messageHashToNonceB64url;
 exports.migrateChipiWalletToShhh = migrateChipiWalletToShhh;
 exports.normalizeEntrypoints = normalizeEntrypoints;
+exports.normalizeStarknetAddress = normalizeStarknetAddress;
 exports.ownerCommitment = ownerCommitment;
 exports.parseAppleIdToken = parseAppleIdToken;
 exports.parseDerEcdsaSignature = parseDerEcdsaSignature;
 exports.parseEip191Signature = parseEip191Signature;
+exports.parseOpProposedEvents = parseOpProposedEvents;
+exports.parseStarknetWalletSignature = parseStarknetWalletSignature;
 exports.parseThresholdEnvelope = parseThresholdEnvelope;
+exports.prepareExternalOwnerExecution = prepareExternalOwnerExecution;
+exports.readPendingRecovery = readPendingRecovery;
+exports.readShhhOwners = readShhhOwners;
+exports.readVerifierClass = readVerifierClass;
 exports.resolveShhhChainId = resolveShhhChainId;
+exports.resolveStarkSnip12Signer = resolveStarkSnip12Signer;
 exports.secondsUntilExecutable = secondsUntilExecutable;
 exports.serializeExecuteFromOutsideV2Calldata = serializeExecuteFromOutsideV2Calldata;
 exports.signBootstrapMessage = signBootstrapMessage;
@@ -5513,8 +6214,16 @@ exports.signTypedDataArray = signTypedDataArray;
 exports.snip12HashToHexAsciiBytes = snip12HashToHexAsciiBytes;
 exports.starkOwnerId = starkOwnerId;
 exports.starkPubkeyFelts = starkPubkeyFelts;
+exports.starkSnip12ApprovalHash = starkSnip12ApprovalHash;
+exports.starkSnip12ApprovalTypedData = starkSnip12ApprovalTypedData;
+exports.starkSnip12OwnerCommitment = starkSnip12OwnerCommitment;
+exports.starkSnip12PubkeyFelts = starkSnip12PubkeyFelts;
+exports.submitExternalOwnerExecution = submitExternalOwnerExecution;
 exports.submitViaAccount = submitViaAccount;
 exports.validateSpendingPolicyConfig = validateSpendingPolicyConfig;
+exports.verifyStarkSnip12Approval = verifyStarkSnip12Approval;
+exports.verifyStarknetSignIn = verifyStarknetSignIn;
+exports.verifyUndeployedStarknetSignature = verifyUndeployedStarknetSignature;
 exports.waitForTransaction = waitForTransaction;
 exports.webauthnOwnerId = webauthnOwnerId;
 exports.webauthnOwnerPubkeyParam = webauthnOwnerPubkeyParam;