@chipi-stack/backend 14.3.1 → 14.6.0

package/dist/wallets.mjs

@@ -1,22 +1,727 @@
-import { WALLET_RPC_ENDPOINTS, WALLET_CLASS_HASHES, API_ENDPOINTS, ChipiTransactionError, ChipiApiError } from '@chipi-stack/shared';
-import CryptoES2 from 'crypto-es';
-import { RpcProvider, ec, hash, Account, num, CairoCustomEnum, CairoOption, CairoOptionVariant, CallData } from 'starknet';
+import { shortString, hash, RpcProvider, ec, Account, num, CairoCustomEnum, CairoOption, CairoOptionVariant, CallData } from 'starknet';
+import { WALLET_RPC_ENDPOINTS, SHHH_VERIFIER_CLASS_HASHES, WALLET_CLASS_HASHES, API_ENDPOINTS, ChipiTransactionError, ChipiApiError } from '@chipi-stack/shared';
+import CryptoES from 'crypto-es';
+import { randomBytes } from 'crypto';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+function poseidon(values) {
+  const felts = values.map((v) => typeof v === "bigint" ? "0x" + v.toString(16) : v);
+  return BigInt(hash.computePoseidonHashOnElements(felts));
+}
+function ownerCommitment(kindTag, pubkey) {
+  return poseidon([kindTag, ...pubkey]);
+}
+function computeAddressSalt(primaryKind, pubkey) {
+  if (pubkey.length === 0) {
+    throw new Error(
+      "computeAddressSalt: pubkey must contain at least one felt \u2014 empty signer material is rejected to prevent silent address mismatch."
+    );
+  }
+  const kindTag = BigInt(shortString.encodeShortString(primaryKind));
+  const pubkeyHash = ownerCommitment(kindTag, pubkey);
+  return poseidon([kindTag, pubkeyHash]);
+}
+function computeShhhAddress(input) {
+  const {
+    classHash,
+    primaryKind,
+    pubkey,
+    verifierClassHash,
+    label = "primary",
+    deployerAddress = 0n
+  } = input;
+  const salt = computeAddressSalt(primaryKind, pubkey);
+  const kindTag = BigInt(shortString.encodeShortString(primaryKind));
+  const labelFelt = BigInt(shortString.encodeShortString(label));
+  const ctor = [
+    kindTag,
+    verifierClassHash,
+    BigInt(pubkey.length),
+    ...pubkey,
+    labelFelt
+  ];
+  const addressHex = hash.calculateContractAddressFromHash(
+    "0x" + salt.toString(16),
+    "0x" + classHash.toString(16),
+    ctor.map((x) => typeof x === "bigint" ? "0x" + x.toString(16) : x),
+    "0x" + deployerAddress.toString(16)
+  );
+  return BigInt(addressHex);
+}
+var init_compute_wallet_address = __esm({
+  "src/shhh/compute-wallet-address.ts"() {
+  }
+});
+function toBigInt(x) {
+  if (typeof x === "bigint") return x;
+  if (typeof x === "number") return BigInt(x);
+  return BigInt(x);
+}
+function poseidonSpan(values) {
+  const felts = values.map((v) => typeof v === "bigint" ? "0x" + v.toString(16) : v);
+  return BigInt(hash.computePoseidonHashOnElements(felts));
+}
+function hashCall(call) {
+  const calldataFelts = CallData.toHex(
+    Array.isArray(call.calldata) ? call.calldata : [call.calldata]
+  );
+  const calldataItems = calldataFelts.map((x) => BigInt(x));
+  const calldataHash = poseidonSpan(calldataItems);
+  return poseidonSpan([
+    CALL_TYPE_HASH_REV1,
+    toBigInt(call.contractAddress),
+    toBigInt(hash.getSelectorFromName(call.entrypoint)),
+    calldataHash
+  ]);
+}
+function hashCalls(calls) {
+  const callHashes = calls.map(hashCall);
+  return poseidonSpan(callHashes);
+}
+function hashStarknetDomain(chainIdFelt) {
+  return poseidonSpan([
+    STARKNET_DOMAIN_TYPE_HASH_REV1,
+    BigInt(OE_DOMAIN_NAME),
+    OE_DOMAIN_VERSION,
+    toBigInt(chainIdFelt),
+    OE_DOMAIN_REVISION
+  ]);
+}
+function hashOutsideExecutionStruct(oe) {
+  const callsArrayHash = hashCalls(oe.calls);
+  return poseidonSpan([
+    OUTSIDE_EXECUTION_TYPE_HASH_REV1,
+    toBigInt(oe.caller),
+    toBigInt(oe.nonce),
+    oe.execute_after,
+    oe.execute_before,
+    callsArrayHash
+  ]);
+}
+function computeSnip12Hash(oe, contractAddress, chainIdFelt) {
+  const domainHash = hashStarknetDomain(chainIdFelt);
+  const structHash = hashOutsideExecutionStruct(oe);
+  return poseidonSpan([
+    BigInt(STARKNET_MESSAGE_PREFIX),
+    domainHash,
+    toBigInt(contractAddress),
+    structHash
+  ]);
+}
+function snip12HashToHexAsciiBytes(h) {
+  const hex = h.toString(16).padStart(64, "0");
+  return new TextEncoder().encode(hex);
+}
+var OUTSIDE_EXECUTION_TYPE_HASH_REV1, CALL_TYPE_HASH_REV1, STARKNET_DOMAIN_TYPE_HASH_REV1, STARKNET_MESSAGE_PREFIX, OE_DOMAIN_NAME, OE_DOMAIN_VERSION, OE_DOMAIN_REVISION, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD;
+var init_snip12_hash = __esm({
+  "src/shhh/snip12-hash.ts"() {
+    OUTSIDE_EXECUTION_TYPE_HASH_REV1 = 0x5a4b49e17039355cd95d1f0981d75901191d1319b1f4b05a9a791d218d7e0cn;
+    CALL_TYPE_HASH_REV1 = 0x3635c7f2a7ba93844c0d064e18e487f35ab90f7c39d00f186a781fc3f0c2ca9n;
+    STARKNET_DOMAIN_TYPE_HASH_REV1 = 0x1ff2f602e42168014d405a94f75e8a93d640751d71d16311266e140d8b0a210n;
+    STARKNET_MESSAGE_PREFIX = shortString.encodeShortString("StarkNet Message");
+    OE_DOMAIN_NAME = shortString.encodeShortString("Account.execute_from_outside");
+    OE_DOMAIN_VERSION = 2n;
+    OE_DOMAIN_REVISION = 1n;
+    shortString.encodeShortString("V1_HEX_ASCII");
+    SIG_VERSION_V2_SNIP12 = shortString.encodeShortString("V2_SNIP12");
+    SIG_VERSION_V2_THRESHOLD = shortString.encodeShortString("V2_THRESHOLD");
+    BigInt(
+      "0x1d1144bb2138366ff28d8e9ab57456b1d332ac42196230c3a602003c89872"
+    );
+    BigInt(
+      "0x94c5a761f34b25a4e603c651ac0e1fc4fad9cdb5517f7fa1bb54044c7e5ef8"
+    );
+  }
+});
+var init_threshold = __esm({
+  "src/shhh/threshold.ts"() {
+    init_snip12_hash();
+    BigInt(SIG_VERSION_V2_SNIP12);
+    BigInt(SIG_VERSION_V2_THRESHOLD);
+  }
+});
+function buildOutsideExecution(params) {
+  const nowSec = BigInt(Math.floor(Date.now() / 1e3));
+  const after = params.executeAfter ?? nowSec - BigInt(OE_EXECUTE_AFTER_CLOCK_SKEW_BUFFER);
+  const before = params.executeBefore ?? nowSec + BigInt(MAX_OE_VALIDITY_WINDOW_SECONDS) - BigInt(OE_EXECUTE_AFTER_CLOCK_SKEW_BUFFER);
+  if (before <= after) {
+    throw new Error(
+      `executeBefore (${before}) must be strictly greater than executeAfter (${after}).`
+    );
+  }
+  if (before - after > BigInt(MAX_OE_VALIDITY_WINDOW_SECONDS)) {
+    throw new Error(
+      `OE validity window ${before - after}s exceeds max ${MAX_OE_VALIDITY_WINDOW_SECONDS}s (audit M-2). Adjust executeBefore.`
+    );
+  }
+  return {
+    caller: params.caller ?? ANY_CALLER_FELT,
+    nonce: params.nonce,
+    execute_after: after,
+    execute_before: before,
+    calls: params.calls
+  };
+}
+function computeOeHash(oe, accountAddress, chainId) {
+  return computeSnip12Hash(oe, accountAddress, chainId);
+}
+function wrapV2Snip12Envelope(params) {
+  const tag = typeof params.kindTag === "bigint" ? params.kindTag : BigInt(shortString.encodeShortString(params.kindTag));
+  return [
+    BigInt(SIG_VERSION_V2_SNIP12),
+    params.ownerId,
+    tag,
+    ...params.payload.map((v) => typeof v === "bigint" ? v : BigInt(v))
+  ];
+}
+var ANY_CALLER_FELT, MAX_OE_VALIDITY_WINDOW_SECONDS, OE_EXECUTE_AFTER_CLOCK_SKEW_BUFFER;
+var init_oe = __esm({
+  "src/shhh/oe.ts"() {
+    init_snip12_hash();
+    init_threshold();
+    ANY_CALLER_FELT = BigInt(shortString.encodeShortString("ANY_CALLER"));
+    MAX_OE_VALIDITY_WINDOW_SECONDS = 2 * 60 * 60;
+    OE_EXECUTE_AFTER_CLOCK_SKEW_BUFFER = 60;
+  }
+});
+async function ensureGaragaInit() {
+  if (garagaInitPromise) return garagaInitPromise;
+  const attempt = (async () => {
+    const garaga = await import('garaga');
+    await garaga.init();
+    return garaga;
+  })();
+  garagaInitPromise = attempt;
+  try {
+    return await attempt;
+  } catch (err) {
+    if (garagaInitPromise === attempt) garagaInitPromise = null;
+    throw err;
+  }
+}
+function bytesToLeU256(bytes) {
+  if (bytes.length !== 32) {
+    throw new Error(`Ed25519 value must be exactly 32 bytes; got ${bytes.length}.`);
+  }
+  let low = 0n;
+  let high = 0n;
+  for (let i = 0; i < 16; i++) low += BigInt(bytes[i]) << BigInt(8 * i);
+  for (let i = 0; i < 16; i++) high += BigInt(bytes[16 + i]) << BigInt(8 * i);
+  return { low, high };
+}
+function bytesToLeBigInt(bytes) {
+  let x = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) x = x << 8n | BigInt(bytes[i]);
+  return x;
+}
+function ed25519SignedBytes(messageHash) {
+  return snip12HashToHexAsciiBytes(messageHash);
+}
+function ed25519PubkeyFelts(publicKey) {
+  const { low, high } = bytesToLeU256(publicKey);
+  return [low, high];
+}
+async function buildEd25519Envelope(params) {
+  const ownerIndex = params.ownerIndex ?? 0n;
+  if (ownerIndex < 0n || ownerIndex >= 0x100000000n) {
+    throw new Error(
+      `buildEd25519Envelope: ownerIndex ${ownerIndex} is out of u32 range [0, 2^32). owner_id is the u32 INDEX into the wallet's owner_set (0 for primary, 1 for second, etc.); do NOT pass an owner_commitment or pubkey here.`
+    );
+  }
+  if (params.privateKey.length !== 32) {
+    throw new Error(
+      `Ed25519 private key must be exactly 32 bytes; got ${params.privateKey.length}.`
+    );
+  }
+  const ed = await import('@noble/ed25519');
+  const garaga = await ensureGaragaInit();
+  const publicKey = await ed.getPublicKeyAsync(params.privateKey);
+  const signedBytes = ed25519SignedBytes(params.messageHash);
+  const signature = await ed.signAsync(signedBytes, params.privateKey);
+  const R = signature.slice(0, 32);
+  const s = signature.slice(32, 64);
+  const payload = garaga.eddsaCalldataBuilder(
+    bytesToLeBigInt(R),
+    bytesToLeBigInt(s),
+    bytesToLeBigInt(publicKey),
+    signedBytes,
+    false
+  );
+  return wrapV2Snip12Envelope({
+    ownerId: ownerIndex,
+    kindTag: ED25519_KIND_TAG,
+    payload
+  });
+}
+var ED25519_KIND_TAG, garagaInitPromise;
+var init_ed25519 = __esm({
+  "src/shhh/signers/ed25519.ts"() {
+    init_compute_wallet_address();
+    init_oe();
+    init_snip12_hash();
+    ED25519_KIND_TAG = "ED25519";
+    BigInt(shortString.encodeShortString(ED25519_KIND_TAG));
+    garagaInitPromise = null;
+  }
+});
+var encryptPrivateKey, decryptPrivateKey;
+var init_encryption = __esm({
+  "src/lib/encryption.ts"() {
+    encryptPrivateKey = (privateKey, password) => {
+      if (!privateKey || !password) {
+        throw new Error("Private key and password are required");
+      }
+      return CryptoES.AES.encrypt(privateKey, password).toString();
+    };
+    decryptPrivateKey = (encryptedPrivateKey, password) => {
+      if (!encryptedPrivateKey || !password) {
+        throw new Error("Encrypted private key and password are required");
+      }
+      try {
+        const bytes = CryptoES.AES.decrypt(encryptedPrivateKey, password);
+        const decrypted = bytes.toString(CryptoES.enc.Utf8);
+        if (!decrypted) {
+          throw new Error("Decryption resulted in empty string");
+        }
+        return decrypted;
+      } catch (error) {
+        if (error instanceof Error) {
+          throw error;
+        }
+        throw new Error(`Decryption failed: ${error}`);
+      }
+    };
+  }
+});
+
+// src/encryption.ts
+var init_encryption2 = __esm({
+  "src/encryption.ts"() {
+    init_encryption();
+  }
+});
+function buildStarkEnvelope(params) {
+  const pkHex = "0x" + (typeof params.privateKey === "bigint" ? params.privateKey : BigInt(params.privateKey)).toString(16).padStart(64, "0");
+  const sig = ec.starkCurve.sign("0x" + params.messageHash.toString(16), pkHex);
+  const r = BigInt("0x" + sig.r.toString(16));
+  const s = BigInt("0x" + sig.s.toString(16));
+  const ownerIndex = params.ownerIndex ?? 0n;
+  if (ownerIndex < 0n || ownerIndex >= 0x100000000n) {
+    throw new Error(
+      `buildStarkEnvelope: ownerIndex ${ownerIndex} is out of u32 range [0, 2^32). owner_id is the u32 INDEX into the wallet's owner_set (0 for primary, 1 for second, etc.); do NOT pass an owner_commitment or pubkey here.`
+    );
+  }
+  return wrapV2Snip12Envelope({
+    ownerId: ownerIndex,
+    kindTag: STARK_KIND_TAG,
+    payload: [r, s]
+  });
+}
+var STARK_KIND_TAG;
+var init_stark = __esm({
+  "src/shhh/signers/stark.ts"() {
+    init_compute_wallet_address();
+    init_oe();
+    STARK_KIND_TAG = "STARK";
+    BigInt(shortString.encodeShortString(STARK_KIND_TAG));
+  }
+});
+
+// src/shhh/execute-paymaster-raw.ts
+var execute_paymaster_raw_exports = {};
+__export(execute_paymaster_raw_exports, {
+  executeShhhSponsoredRaw: () => executeShhhSponsoredRaw,
+  resolveShhhChainId: () => resolveShhhChainId,
+  serializeExecuteFromOutsideV2Calldata: () => serializeExecuteFromOutsideV2Calldata
+});
+function resolveShhhChainId(params) {
+  if (params.override !== void 0) {
+    return typeof params.override === "bigint" ? "0x" + params.override.toString(16) : params.override;
+  }
+  const url = (params.baseUrl ?? "").toLowerCase();
+  if (url.includes("sepolia")) return SN_SEPOLIA_CHAIN_ID;
+  return SN_MAIN_CHAIN_ID;
+}
+function serializeExecuteFromOutsideV2Calldata(params) {
+  const out = [];
+  const oe = params.outsideExecution;
+  const toBig = (v) => typeof v === "bigint" ? v : BigInt(v);
+  out.push(toBig(oe.caller));
+  out.push(toBig(oe.nonce));
+  out.push(oe.execute_after);
+  out.push(oe.execute_before);
+  out.push(BigInt(oe.calls.length));
+  for (const call of oe.calls) {
+    out.push(BigInt(call.contractAddress));
+    out.push(BigInt(hash.getSelectorFromName(call.entrypoint)));
+    const callData = Array.isArray(call.calldata) ? call.calldata : [];
+    out.push(BigInt(callData.length));
+    for (const datum of callData) {
+      out.push(typeof datum === "bigint" ? datum : BigInt(datum));
+    }
+  }
+  out.push(BigInt(params.signature.length));
+  for (const sigFelt of params.signature) {
+    out.push(sigFelt);
+  }
+  return out.map((v) => "0x" + v.toString(16));
+}
+function newOeNonce() {
+  const tsMs = BigInt(Date.now());
+  const rand = BigInt(Math.floor(Math.random() * 16777215));
+  return tsMs << 24n | rand;
+}
+async function executeShhhSponsoredRaw(params) {
+  const signerKind = params.signerKind ?? "STARK";
+  const SDK_SHIPPED_OE_KINDS = ["STARK", "ED25519"];
+  if (!SDK_SHIPPED_OE_KINDS.includes(signerKind)) {
+    throw new Error(
+      `SHHH signerKind="${signerKind}" is not yet shipped from the SDK (Wave B ships STARK + ED25519). Wait for the follow-up PR that adds external-rooted (MetaMask, Phantom, passkey, Apple) signing.`
+    );
+  }
+  const privateKeyHex = decryptPrivateKey(params.wallet.encryptedPrivateKey, params.encryptKey);
+  if (!privateKeyHex) {
+    throw new Error(
+      "Failed to decrypt private key for SHHH OE. Verify the encryptKey matches the one used at wallet creation."
+    );
+  }
+  const oe = buildOutsideExecution({
+    nonce: params.nonce ?? newOeNonce(),
+    calls: params.calls,
+    caller: ANY_CALLER_FELT
+  });
+  const chainId = resolveShhhChainId({
+    override: params.chainId,
+    baseUrl: params.client.baseUrl
+  });
+  const messageHash = computeOeHash(oe, params.wallet.publicKey, chainId);
+  let signature;
+  if (signerKind === "STARK") {
+    signature = buildStarkEnvelope({
+      privateKey: privateKeyHex,
+      messageHash
+    });
+  } else {
+    const edKeyHex = privateKeyHex.startsWith("0x") ? privateKeyHex.slice(2) : privateKeyHex;
+    if (edKeyHex.length !== 64) {
+      throw new Error(
+        `SHHH ED25519 private key is ${edKeyHex.length} hex chars; expected 64 (32 raw bytes). The stored ciphertext does not look like a Chipi-held Ed25519 key \u2014 check wallet provenance.`
+      );
+    }
+    const edPrivKey = Uint8Array.from(Buffer.from(edKeyHex, "hex"));
+    signature = await buildEd25519Envelope({
+      privateKey: edPrivKey,
+      messageHash
+    });
+  }
+  const calldata = serializeExecuteFromOutsideV2Calldata({
+    outsideExecution: oe,
+    signature
+  });
+  const response = await params.client.post({
+    endpoint: "/transactions/execute-sponsored-raw",
+    bearerToken: params.bearerToken,
+    body: {
+      accountAddress: params.wallet.publicKey,
+      calldata,
+      signerKind,
+      ...params.externalUserId ? { externalUserId: params.externalUserId } : {}
+    }
+  });
+  if (!response || !response.transactionHash) {
+    throw new Error(
+      "execute-sponsored-raw response missing transactionHash. Check the chipi-back logs for upstream paymaster errors."
+    );
+  }
+  return response.transactionHash;
+}
+var SN_MAIN_CHAIN_ID, SN_SEPOLIA_CHAIN_ID;
+var init_execute_paymaster_raw = __esm({
+  "src/shhh/execute-paymaster-raw.ts"() {
+    init_encryption2();
+    init_oe();
+    init_stark();
+    init_ed25519();
+    SN_MAIN_CHAIN_ID = "0x534e5f4d41494e";
+    SN_SEPOLIA_CHAIN_ID = "0x534e5f5345504f4c4941";
+  }
+});
 
 // src/wallets.ts
-var encryptPrivateKey = (privateKey, password) => {
-  if (!privateKey || !password) {
-    throw new Error("Private key and password are required");
+init_compute_wallet_address();
+init_ed25519();
+init_encryption2();
+
+// src/migrate-to-shhh.ts
+init_encryption2();
+
+// src/execute-paymaster-transaction.ts
+init_encryption2();
+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];
+    if (r == null || s == null) {
+      throw new Error(`Signature elements must not be null/undefined. Got r=${r}, s=${s}`);
+    }
+    return { r: String(r), s: String(s) };
+  }
+  if (signature && typeof signature === "object" && "r" in signature && "s" in signature) {
+    const sig = signature;
+    if (sig.r == null || sig.s == null) {
+      throw new Error(`Object signature has null/undefined fields. Got r=${sig.r}, s=${sig.s}`);
+    }
+    return {
+      r: String(sig.r),
+      s: String(sig.s)
+    };
+  }
+  throw new Error("Unrecognized signature format from account.signMessage()");
+}
+
+// src/execute-paymaster-transaction.ts
+var executePaymasterTransaction = async ({
+  params,
+  bearerToken,
+  client
+}) => {
+  try {
+    const { encryptKey, wallet, calls, saveToDatabase, usePasskey } = params;
+    if (!encryptKey) {
+      throw new Error(
+        usePasskey ? "encryptKey is required when using passkey. The passkey authentication should have provided the encryptKey." : "encryptKey is required for transaction execution"
+      );
+    }
+    const walletType = wallet.walletType ?? "READY";
+    if (walletType === "SHHH") {
+      const { executeShhhSponsoredRaw: executeShhhSponsoredRaw2 } = await Promise.resolve().then(() => (init_execute_paymaster_raw(), execute_paymaster_raw_exports));
+      const shhhSignerKind = (wallet.signerKind ?? "STARK") || "STARK";
+      return await executeShhhSponsoredRaw2({
+        client,
+        bearerToken,
+        wallet: {
+          publicKey: wallet.publicKey,
+          encryptedPrivateKey: wallet.encryptedPrivateKey,
+          walletType: wallet.walletType
+        },
+        encryptKey,
+        calls,
+        signerKind: shhhSignerKind
+      });
+    }
+    const isKnownType = Object.prototype.hasOwnProperty.call(WALLET_RPC_ENDPOINTS, walletType) && Object.prototype.hasOwnProperty.call(WALLET_CLASS_HASHES, walletType);
+    const rpcUrl = isKnownType ? WALLET_RPC_ENDPOINTS[walletType] : WALLET_RPC_ENDPOINTS["CHIPI"];
+    const accountClassHash = isKnownType ? WALLET_CLASS_HASHES[walletType] : WALLET_CLASS_HASHES["CHIPI"];
+    let privateKeyDecrypted;
+    try {
+      privateKeyDecrypted = decryptPrivateKey(wallet.encryptedPrivateKey, encryptKey);
+    } catch {
+      throw new Error("Failed to decrypt private key. Verify the encryptKey is correct.");
+    }
+    const provider = new RpcProvider({ nodeUrl: rpcUrl });
+    const account = new Account({
+      provider,
+      address: wallet.publicKey,
+      signer: privateKeyDecrypted
+    });
+    const prepareResponse = await client.post({
+      endpoint: "/transactions/prepare-typed-data",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        calls,
+        accountClassHash
+      }
+    });
+    if (!prepareResponse || typeof prepareResponse !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/prepare-typed-data: response is not an object"
+      );
+    }
+    let typedData2;
+    let resolvedWalletType;
+    if ("typedData" in prepareResponse) {
+      const resp = prepareResponse;
+      typedData2 = resp.typedData;
+      if (resp.walletType && Object.prototype.hasOwnProperty.call(WALLET_CLASS_HASHES, resp.walletType)) {
+        resolvedWalletType = resp.walletType;
+      }
+    } else if (prepareResponse && "types" in prepareResponse && "message" in prepareResponse) {
+      typedData2 = prepareResponse;
+    } else {
+      const apiMessage2 = prepareResponse && typeof prepareResponse.message === "string" ? prepareResponse.message : void 0;
+      throw new Error(
+        apiMessage2 ?? "Invalid response from /transactions/prepare-typed-data: typedData is missing. This may occur for older STARKNET wallets that don't support paymaster transactions. Please ensure the wallet is a CHIPI wallet type."
+      );
+    }
+    if (!typedData2 || typeof typedData2 !== "object" || !("types" in typedData2) || !("message" in typedData2)) {
+      throw new Error(
+        "Invalid typedData received from backend: missing 'types' or 'message' field. This may occur for older STARKNET wallets that don't support paymaster transactions."
+      );
+    }
+    const userSignature = await account.signMessage(typedData2);
+    const normalizedSig = normalizeSignature(userSignature);
+    const result = await client.post({
+      endpoint: "/transactions/execute-sponsored-transaction",
+      bearerToken,
+      body: {
+        publicKey: wallet.publicKey,
+        typedData: typedData2,
+        userSignature: normalizedSig,
+        saveToDatabase,
+        walletType: resolvedWalletType ?? walletType
+      }
+    });
+    if (!result || typeof result !== "object") {
+      throw new Error(
+        "Invalid response from /transactions/execute-sponsored-transaction: response is not an object"
+      );
+    }
+    const apiMessage = typeof result.message === "string" ? result.message : void 0;
+    if (typeof result.transactionHash !== "string" || result.transactionHash.trim().length === 0) {
+      throw new Error(apiMessage ?? "Response does not contain transaction hash");
+    }
+    return result.transactionHash;
+  } catch (error) {
+    console.error("Error sending transaction with paymaster", error);
+    throw error;
   }
-  return CryptoES2.AES.encrypt(privateKey, password).toString();
 };
+BigInt(
+  shortString.encodeShortString("SHHH_BOOTSTRAP_V8_4")
+);
+var UPGRADE_ENTRYPOINT = "upgrade";
+var BOOTSTRAP_ENTRYPOINT = "bootstrap_from_sessions";
+function _asHex(x) {
+  return typeof x === "bigint" ? "0x" + x.toString(16) : x;
+}
+function labelToFelt(label) {
+  if (label.length === 0) return 0n;
+  for (let i = 0; i < label.length; i++) {
+    if (label.charCodeAt(i) > 127) {
+      throw new RangeError(
+        `migrate label must be ASCII-only (starknet.js short-string encoder rejects non-ASCII)`
+      );
+    }
+  }
+  if (label.length > 31) {
+    throw new RangeError(
+      `migrate label must fit in felt252 short-string (\u226431 ASCII characters); got ${label.length}`
+    );
+  }
+  return BigInt(shortString.encodeShortString(label));
+}
+function buildMigrationCalls(params) {
+  const upgradeCall = {
+    contractAddress: _asHex(params.legacyAccountAddress),
+    entrypoint: UPGRADE_ENTRYPOINT,
+    calldata: [_asHex(params.shhhAccountClassHash)]
+  };
+  const labelFelt = labelToFelt(params.label ?? "migrated");
+  const bootstrapCall = {
+    contractAddress: _asHex(params.legacyAccountAddress),
+    entrypoint: BOOTSTRAP_ENTRYPOINT,
+    calldata: [
+      _asHex(params.legacyPublicKey),
+      _asHex(params.starkVerifierClassHash),
+      "0x" + labelFelt.toString(16)
+    ]
+  };
+  return [upgradeCall, bootstrapCall];
+}
+
+// src/migrate-to-shhh.ts
+async function migrateChipiWalletToShhh(params) {
+  const prepare = await params.client.post({
+    endpoint: "/chipi-wallets/prepare-migrate-to-shhh",
+    bearerToken: params.bearerToken,
+    body: {
+      walletId: params.walletId,
+      externalUserId: params.externalUserId
+    }
+  });
+  if (prepare.migrationPath === "ALREADY_MIGRATED") {
+    return {
+      kind: "ALREADY_MIGRATED",
+      walletAddress: prepare.walletAddress,
+      onChainClassHash: prepare.onChainClassHash,
+      primaryKind: prepare.primaryKind
+    };
+  }
+  if (prepare.migrationPath === "STRANDED") {
+    throw new Error(
+      "SHHH stranded-state recovery is not yet shipped in the SDK client. The wallet is at V8.4 class hash but primary_kind == 0, which means a prior migration completed `upgrade(SHHH)` but the `bootstrap_from_sessions` call silently reverted. Recovery requires `bootstrap_from_sessions_signed`; see `buildBootstrapSignedCall` in @chipi-stack/backend/src/shhh/migrate.ts."
+    );
+  }
+  if (prepare.migrationPath !== "HAPPY") {
+    throw new Error(
+      "SHHH migration: unexpected migrationPath " + JSON.stringify(prepare.migrationPath) + " returned by chipi-back. This SDK build only handles HAPPY / STRANDED / ALREADY_MIGRATED; upgrade @chipi-stack/backend to a version that knows this path."
+    );
+  }
+  const privateKeyHex = decryptPrivateKey(params.wallet.encryptedPrivateKey, params.encryptKey);
+  if (!privateKeyHex) {
+    throw new Error(
+      "Failed to decrypt STARK private key for migration. Verify the encryptKey matches the one used at wallet creation."
+    );
+  }
+  const starkKeyPub = BigInt(ec.starkCurve.getStarkKey(privateKeyHex));
+  const calls = buildMigrationCalls({
+    legacyAccountAddress: params.wallet.publicKey,
+    legacyPublicKey: starkKeyPub,
+    shhhAccountClassHash: BigInt(prepare.shhhClassHash),
+    starkVerifierClassHash: BigInt(prepare.shhhVerifierClassHash),
+    label: prepare.label
+  });
+  const transactionHash = await executePaymasterTransaction({
+    params: {
+      encryptKey: params.encryptKey,
+      wallet: {
+        publicKey: params.wallet.publicKey,
+        encryptedPrivateKey: params.wallet.encryptedPrivateKey,
+        // Explicit walletType: the wallet IS still CHIPI v29 at sign
+        // time. The upgrade(SHHH) inside the multicall changes the
+        // class hash mid-tx; that's after signature verification.
+        walletType: "CHIPI"
+      },
+      calls,
+      // Persist the migration tx so it shows up in the user's tx
+      // history. The on-chain receipt is the load-bearing artifact;
+      // the DB row is convenience surfacing.
+      saveToDatabase: true
+    },
+    bearerToken: params.bearerToken,
+    client: params.client
+  });
+  const execute = await params.client.post({
+    endpoint: "/chipi-wallets/execute-migrate-to-shhh",
+    bearerToken: params.bearerToken,
+    body: {
+      walletId: params.walletId,
+      externalUserId: params.externalUserId,
+      transactionHash
+    }
+  });
+  return { kind: "MIGRATED", ...execute };
+}
 
 // src/wallets.ts
 var ChipiWallets = class {
   constructor(client) {
     this.client = client;
     this.getPrivateKeyAX = () => {
-      const privateKeyBytes = CryptoES2.lib.WordArray.random(32);
-      const privateKey = privateKeyBytes.toString(CryptoES2.enc.Hex);
+      const privateKeyBytes = CryptoES.lib.WordArray.random(32);
+      const privateKey = privateKeyBytes.toString(CryptoES.enc.Hex);
       const fullPrivateKey = `0x${privateKey}`;
       const maxStarknetValue = BigInt(
         "0x800000000000000000000000000000000000000000000000000000000000000"
@@ -25,6 +730,20 @@ var ChipiWallets = class {
       return `0x${privateKeyBigInt.toString(16)}`;
     };
   }
+  /**
+   * Create a new wallet on Starknet (gasless, paymaster-sponsored).
+   *
+   * **PIN is weak — not recommended for production.** `encryptKey` here
+   * doubles as the only thing decrypting the wallet's private key. A
+   * user-typed PIN is short, low-entropy, and trivially compromised
+   * by shoulder-surfing or phishing. Production embedded-wallet apps
+   * should derive `encryptKey` from a platform passkey
+   * (`@chipi-stack/chipi-passkey` `getWalletEncryptKey` for the legacy
+   * PRF flow, or — preferred — `createShhhPasskey` for new SHHH
+   * V8.4 wallets where the P-256 key never leaves the platform
+   * authenticator at all). PIN remains only as a last-resort
+   * recovery surface for users without WebAuthn / biometrics.
+   */
   async createWallet(params) {
     try {
       const {
@@ -32,8 +751,25 @@ var ChipiWallets = class {
         externalUserId,
         bearerToken,
         userId,
-        walletType = "CHIPI",
-        // Default to CHIPI wallet
+        // P2.2 default flip (re-applied 2026-05-29 after #270 revert and
+        // the post-revert SHHH bug-fix run #271–#296). New wallets
+        // default to SHHH V8.4 instead of legacy CHIPI v29 — pluggable-
+        // signer Starknet account, guardian recovery, threshold support
+        // out of the box. Existing wallets unaffected; this only
+        // changes the default for callers that omit `walletType`.
+        // Callers who explicitly pass `walletType: "CHIPI"` or
+        // `"READY"` continue producing those.
+        //
+        // Server-side override: chipi-back's CHIPI_SHHH_DEFAULT env
+        // var (chipi-back#267) lets ops force the legacy default back
+        // for callers that bypass the SDK and POST to /chipi-wallets
+        // directly without walletType.
+        //
+        // signerKind under the SHHH branch defaults to "STARK" further
+        // down — same kind the original #267 P2.2 used and the same
+        // kind every mainnet smoke since 2026-05-26 has been signing
+        // under.
+        walletType = "SHHH",
         classHash: customClassHash,
         usePasskey,
         chain
@@ -46,18 +782,102 @@ var ChipiWallets = class {
         }
         throw new Error("encryptKey is required for wallet creation");
       }
+      const isShhh = walletType === "SHHH";
+      const effectiveSignerKind = isShhh ? params.signerKind ?? "STARK" : void 0;
+      const SDK_SHIPPED_SHHH_KINDS = ["STARK", "ED25519"];
+      if (isShhh && !SDK_SHIPPED_SHHH_KINDS.includes(
+        effectiveSignerKind
+      )) {
+        throw new Error(
+          `SHHH signerKind=${effectiveSignerKind} is not yet shipped from the SDK (Wave B ships STARK + ED25519). Use signerKind="STARK" or "ED25519", or wait for the follow-up PRs that add external-rooted (MetaMask, Phantom, passkey, Apple) deploy support.`
+        );
+      }
       const rpcUrl = walletType === "READY" ? WALLET_RPC_ENDPOINTS.READY : WALLET_RPC_ENDPOINTS.CHIPI;
       const provider = new RpcProvider({ nodeUrl: rpcUrl });
       const privateKeyAX = this.getPrivateKeyAX();
       const starkKeyPubAX = ec.starkCurve.getStarkKey(privateKeyAX);
-      const constructorCallData = this.buildConstructorCallData(walletType, starkKeyPubAX);
-      const accountClassHash = customClassHash ?? (walletType === "READY" ? WALLET_CLASS_HASHES.READY : WALLET_CLASS_HASHES.CHIPI);
-      const publicKey = hash.calculateContractAddressFromHash(
-        starkKeyPubAX,
-        accountClassHash,
-        constructorCallData,
-        0
-      );
+      let constructorCallData;
+      let accountClassHash;
+      let publicKey;
+      let deploymentSalt;
+      let shhhOwnerPubkeyFelts;
+      let shhhKeyForEncryption = privateKeyAX;
+      if (isShhh) {
+        let pubkeyFelts;
+        let shhhPrivateKeyHex;
+        if (effectiveSignerKind === "STARK") {
+          pubkeyFelts = [BigInt(starkKeyPubAX)];
+          shhhPrivateKeyHex = privateKeyAX;
+        } else if (effectiveSignerKind === "ED25519") {
+          if (params.ownerPubkeyFelts && params.ownerPubkeyFelts.length > 0) {
+            if (params.ownerPubkeyFelts.length !== 2) {
+              throw new Error(
+                `SHHH ED25519 ownerPubkeyFelts must be [low_u128, high_u128] (2 felts); got ${params.ownerPubkeyFelts.length}.`
+              );
+            }
+            pubkeyFelts = params.ownerPubkeyFelts.map((s) => BigInt(s));
+            shhhPrivateKeyHex = "";
+          } else {
+            const edPrivKey = randomBytes(32);
+            const ed = await import('@noble/ed25519');
+            const edPubKey = await ed.getPublicKeyAsync(edPrivKey);
+            pubkeyFelts = ed25519PubkeyFelts(edPubKey);
+            shhhPrivateKeyHex = Buffer.from(edPrivKey).toString("hex");
+          }
+        } else {
+          throw new Error(
+            `SHHH signerKind=${effectiveSignerKind} reached the address-derivation block without an implementation.`
+          );
+        }
+        shhhOwnerPubkeyFelts = pubkeyFelts.map((f) => "0x" + f.toString(16));
+        shhhKeyForEncryption = shhhPrivateKeyHex;
+        const verifierClassHash = BigInt(
+          SHHH_VERIFIER_CLASS_HASHES[effectiveSignerKind]
+        );
+        const shhhClassHash = customClassHash ?? WALLET_CLASS_HASHES.SHHH;
+        const computedAddress = computeShhhAddress({
+          classHash: BigInt(shhhClassHash),
+          primaryKind: effectiveSignerKind,
+          pubkey: pubkeyFelts,
+          verifierClassHash
+        });
+        publicKey = "0x" + computedAddress.toString(16);
+        accountClassHash = shhhClassHash;
+        const labelFelt = BigInt(shortString.encodeShortString("primary"));
+        const kindTagFelt = BigInt(shortString.encodeShortString(effectiveSignerKind));
+        constructorCallData = [
+          kindTagFelt.toString(),
+          verifierClassHash.toString(),
+          pubkeyFelts.length.toString(),
+          ...pubkeyFelts.map((f) => f.toString()),
+          labelFelt.toString()
+        ];
+        const salt = (() => {
+          const ownerCommit = BigInt(
+            hash.computePoseidonHashOnElements([
+              "0x" + kindTagFelt.toString(16),
+              ...pubkeyFelts.map((f) => "0x" + f.toString(16))
+            ])
+          );
+          return BigInt(
+            hash.computePoseidonHashOnElements([
+              "0x" + kindTagFelt.toString(16),
+              "0x" + ownerCommit.toString(16)
+            ])
+          );
+        })();
+        deploymentSalt = "0x" + salt.toString(16);
+      } else {
+        constructorCallData = this.buildConstructorCallData(walletType, starkKeyPubAX);
+        accountClassHash = customClassHash ?? (walletType === "READY" ? WALLET_CLASS_HASHES.READY : WALLET_CLASS_HASHES.CHIPI);
+        publicKey = hash.calculateContractAddressFromHash(
+          starkKeyPubAX,
+          accountClassHash,
+          constructorCallData,
+          0
+        );
+        deploymentSalt = starkKeyPubAX;
+      }
       const account = new Account({ provider, address: publicKey, signer: privateKeyAX });
       const typedDataResponse = await this.client.post({
         endpoint: `${API_ENDPOINTS.CHIPI_WALLETS}/prepare-creation`,
@@ -67,19 +887,41 @@ var ChipiWallets = class {
           publicKey,
           walletType,
           starkKeyPubAX,
-          ...customClassHash && { classHash: customClassHash }
+          ...customClassHash && { classHash: customClassHash },
+          // 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
+          // wallet row columns.
+          ...isShhh && {
+            signerKind: effectiveSignerKind,
+            ownerPubkeyFelts: shhhOwnerPubkeyFelts
+          }
         }
       });
-      const { typedData, accountClassHash: accountClassHashResponse } = typedDataResponse;
-      const userSignature = await account.signMessage(typedData);
+      const { typedData: typedData2, accountClassHash: accountClassHashResponse } = typedDataResponse;
+      let userSignaturePayload;
+      if (isShhh) {
+        userSignaturePayload = {
+          r: "0x0",
+          s: "0x0",
+          recovery: 0
+        };
+      } else {
+        const userSignature = await account.signMessage(typedData2);
+        userSignaturePayload = {
+          r: userSignature.r.toString(),
+          s: userSignature.s.toString(),
+          recovery: userSignature.recovery
+        };
+      }
       const deploymentData = {
         class_hash: accountClassHashResponse,
-        salt: starkKeyPubAX,
+        salt: deploymentSalt,
         unique: `${num.toHex(0)}`,
         calldata: constructorCallData.map((value) => num.toHex(value))
       };
-      const encryptedPrivateKey = encryptPrivateKey(privateKeyAX, encryptKey);
-      const encryptedPrivateKeyBackup = params.encryptKeyBackup ? encryptPrivateKey(privateKeyAX, params.encryptKeyBackup) : void 0;
+      const encryptedPrivateKey = shhhKeyForEncryption === "" ? void 0 : encryptPrivateKey(shhhKeyForEncryption, encryptKey);
+      const encryptedPrivateKeyBackup = params.encryptKeyBackup && shhhKeyForEncryption !== "" ? encryptPrivateKey(shhhKeyForEncryption, params.encryptKeyBackup) : void 0;
       const executeTransactionResponse = await this.client.post({
         endpoint: `${API_ENDPOINTS.CHIPI_WALLETS}`,
         bearerToken,
@@ -89,13 +931,15 @@ var ChipiWallets = class {
           publicKey,
           walletType,
           chain,
-          userSignature: {
-            r: userSignature.r.toString(),
-            s: userSignature.s.toString(),
-            recovery: userSignature.recovery
-          },
-          typedData,
-          encryptedPrivateKey,
+          userSignature: userSignaturePayload,
+          typedData: typedData2,
+          ...encryptedPrivateKey !== void 0 && { encryptedPrivateKey },
+          // SHHH: write the signer kind to the new wallet row. P0.3's
+          // STARK-only path uses a Chipi-held STARK key, so
+          // ownerPublicKey stays unset (encryptedPrivateKey carries
+          // the same key the verifier checks against). External-rooted
+          // wallets will pass ownerPublicKey instead in a follow-up PR.
+          ...isShhh && { signerKind: effectiveSignerKind },
           ...encryptedPrivateKeyBackup && { encryptedPrivateKeyBackup },
           ...params.authMethod && { authMethod: params.authMethod },
           ...params.credentialId && { credentialId: params.credentialId },
@@ -229,6 +1073,31 @@ var ChipiWallets = class {
       body: params
     });
   }
+  /**
+   * Migrate a CHIPI v29 wallet to SHHH V8.4 in-place at the same
+   * on-chain address. Composes the two-phase chipi-back endpoint:
+   * prepare returns the path decision + parameters, then this method
+   * builds the [upgrade, bootstrap_from_sessions] multicall locally,
+   * signs the V8.4 OE with the wallet's STARK key (decrypted via
+   * the user's encryptKey), and sends the signed calldata to the
+   * execute endpoint. Server forwards verbatim to the paymaster.
+   *
+   * Returns `{kind: "ALREADY_MIGRATED"}` if the wallet is already
+   * SHHH on chain (DB row gets patched server-side; no on-chain tx
+   * fires); otherwise `{kind: "MIGRATED", transactionHash, ...}`.
+   *
+   * Throws on STRANDED-state recovery, UNDEPLOYED wallets, and
+   * other deferred-feature paths with actionable error messages.
+   *
+   * Endpoints contract shipped in chipi-back task #28 (PR #272).
+   */
+  async migrateToShhh(params, bearerToken) {
+    return migrateChipiWalletToShhh({
+      client: this.client,
+      bearerToken,
+      ...params
+    });
+  }
 };
 
 export { ChipiWallets };