@chipi-stack/backend 14.4.0 → 14.6.0

package/dist/wallets-DxKnh21Q.d.ts

@@ -0,0 +1,221 @@
+import { CreateWalletParams, CreateWalletResponse, CreateCustodialWalletParams, WalletData, GetWalletParams, GetWalletResponse, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, GetTokenBalanceParams, GetTokenBalanceResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse } from '@chipi-stack/types';
+import { C as ChipiClient } from './client-CqD_yGH0.js';
+
+/**
+ * SDK-side orchestrator for the CHIPI v29 → SHHH V8.4 migration flow.
+ *
+ *   1. POST /chipi-wallets/prepare-migrate-to-shhh
+ *      Returns the path decision (HAPPY / STRANDED / ALREADY_MIGRATED)
+ *      plus the parameters the SDK uses to build the [upgrade(SHHH),
+ *      bootstrap_from_sessions] multicall locally.
+ *
+ *   2. Build the multicall via `buildMigrationCalls`. Targets the
+ *      wallet itself (CHIPI v29 sessions account → V8.4 ShhhAccount).
+ *
+ *   3. Broadcast the multicall through the **existing CHIPI v29
+ *      transaction flow** (`executePaymasterTransaction` →
+ *      `/transactions/prepare-typed-data` → SDK signs `(r, s)` locally
+ *      → `/transactions/execute-sponsored` → paymaster relay). The
+ *      wallet is still CHIPI v29 at sign time, so the signature must
+ *      use CHIPI v29's `(r, s)` SNIP-12 format — not V8.4's V2_SNIP12
+ *      envelope.
+ *
+ *      This is the historical bug fixed by this refactor. The
+ *      original orchestrator (PR #282) used V8.4's
+ *      `buildStarkEnvelope` + `serializeExecuteFromOutsideV2Calldata`
+ *      and sent a 5-felt envelope `[V2_SNIP12, KIND_TAG, len, r, s]`
+ *      to the wallet. CHIPI v29's
+ *      `sessions-smart-contract/src/account.cairo::execute_from_outside_v2`
+ *      read `sig[0:2]` as `(r, s)`, got bogus values, panicked with
+ *      `SRC9: invalid signature` (line 430). Because CHIPI v29's
+ *      `_execute_calls` swallows `Result::Err` at line 684, the outer
+ *      tx still SUCCEEDED but the upgrade(SHHH) call never ran. The
+ *      class hash stayed CHIPI v29. The wallet panic was confirmed by
+ *      reading the inner-call `result` field: ASCII-decoded to
+ *      literal `SRC9: invalid signature`. Reference receipt:
+ *      `0x0535ed9ca8628f1c82ee2005d84017e59a02436597df371d516b97c2c93a516a`
+ *      (staging wallet `0x1434aadce…`).
+ *
+ *   4. POST /chipi-wallets/execute-migrate-to-shhh with the tx hash.
+ *      chipi-back verifies the on-chain class hash flipped to SHHH
+ *      V8.4 and patches the DB row.
+ *
+ * Stranded-state recovery (STRANDED path) is NOT shipped here. The
+ * SDK has the builders (`buildBootstrapSignedCall`,
+ * `computeBootstrapMessage`, `signBootstrapMessage`) but the flow is
+ * sufficiently different from HAPPY that surfacing it cleanly needs
+ * its own UI affordance. Throws a clear deferred-feature error so
+ * the calling dashboard can route to a stranded-recovery UI.
+ */
+
+/**
+ * Response shape from chipi-back's `prepare-migrate-to-shhh`. Mirrors
+ * the union the server returns; the SDK orchestrator switches on
+ * `migrationPath` to decide what to do next.
+ */
+type PrepareMigrateResponse = {
+    migrationPath: "HAPPY";
+    walletAddress: string;
+    onChainClassHash: string;
+    shhhClassHash: string;
+    shhhVerifierClassHash: string;
+    label: string;
+    auditLogId: string;
+} | {
+    migrationPath: "STRANDED";
+    walletAddress: string;
+    onChainClassHash: string;
+    shhhVerifierClassHash: string;
+    label: string;
+    auditLogId: string;
+} | {
+    migrationPath: "ALREADY_MIGRATED";
+    walletAddress: string;
+    onChainClassHash: string;
+    primaryKind: string;
+};
+/**
+ * Response shape from chipi-back's `execute-migrate-to-shhh`.
+ *
+ * On terminal success, the server returns the patched wallet shape.
+ * On PARTIAL failure (on-chain succeeded + DB patch failed) the
+ * server still returns 200 with `partial: true` — the migration tx
+ * landed but the calling dashboard should surface "we'll catch up on
+ * our end shortly" until the reconciler cron (task #30) patches the
+ * row.
+ */
+interface ExecuteMigrateResponse {
+    walletId: string;
+    walletType: "SHHH";
+    signerKind: "STARK";
+    classHash: string;
+    migratedFromClassHash: string;
+    transactionHash: string;
+    partial?: boolean;
+}
+/**
+ * Final result returned by `migrateChipiWalletToShhh`. Either a
+ * full migration completed end-to-end, OR an ALREADY_MIGRATED
+ * short-circuit where the server patched the DB row but no on-chain
+ * tx was needed. Both are terminal; both leave the wallet in SHHH
+ * state for subsequent SDK operations.
+ */
+type MigrationOutcome = (ExecuteMigrateResponse & {
+    kind: "MIGRATED";
+}) | {
+    kind: "ALREADY_MIGRATED";
+    walletAddress: string;
+    onChainClassHash: string;
+    primaryKind: string;
+};
+interface MigrateChipiWalletToShhhParams {
+    client: ChipiClient;
+    bearerToken: string;
+    /** Chipi-back wallet row id + the wallet's tenant scope. */
+    walletId: string;
+    externalUserId: string;
+    /** Wallet shape the SDK passes through from its `wallets.getWallet` cache. */
+    wallet: {
+        publicKey: string;
+        encryptedPrivateKey: string;
+    };
+    /** PIN or passkey-derived secret that decrypts `encryptedPrivateKey`. */
+    encryptKey: string;
+    /**
+     * @deprecated The pre-refactor orchestrator (sdks #282) used this to
+     * override the V8.4 SNIP-12 chain id. The new flow inherits chain
+     * config from `executePaymasterTransaction`'s RPC endpoint
+     * resolution, so this field is ignored. Kept for source-compat with
+     * any v14.5.0-rc callers that may have copied the older signature
+     * into their codebase before publish.
+     */
+    chainId?: bigint | string;
+}
+declare function migrateChipiWalletToShhh(params: MigrateChipiWalletToShhhParams): Promise<MigrationOutcome>;
+
+/**
+ * Wallet management utilities
+ */
+declare class ChipiWallets {
+    private client;
+    constructor(client: ChipiClient);
+    /**
+     * 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.
+     */
+    createWallet(params: CreateWalletParams & {
+        bearerToken: string;
+    }): Promise<CreateWalletResponse>;
+    /**
+     * Build constructor calldata based on wallet type
+     * - CHIPI: Simple OpenZeppelin account with just public_key
+     * - ARGENT: Argent X Account with owner/guardian structure
+     */
+    private buildConstructorCallData;
+    /**
+     * Create a custodial merchant wallet
+     */
+    createCustodialWallet({ params, bearerToken, }: {
+        params: Omit<CreateCustodialWalletParams, "orgId">;
+        bearerToken: string;
+    }): Promise<WalletData>;
+    getWallet(params: GetWalletParams, bearerToken: string): Promise<GetWalletResponse | null>;
+    /**
+     * Recover passkey credential metadata for a wallet.
+     * Used when localStorage is cleared — SDK recovers credentialId from backend.
+     */
+    getCredentialRecovery(params: {
+        externalUserId: string;
+    }, bearerToken: string): Promise<{
+        credentialId: string | null;
+        authMethod: string | null;
+        prfSupported: boolean | null;
+        deviceType: string | null;
+    }>;
+    updateWalletEncryption(params: UpdateWalletEncryptionParams, bearerToken: string): Promise<UpdateWalletEncryptionResponse>;
+    getPrivateKeyAX: () => string;
+    getTokenBalance({ params, bearerToken, }: {
+        params: GetTokenBalanceParams;
+        bearerToken: string;
+    }): Promise<GetTokenBalanceResponse>;
+    /**
+     * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+     * Returns typed data that must be signed by the wallet owner.
+     */
+    prepareWalletUpgrade(params: PrepareWalletUpgradeParams, bearerToken: string): Promise<PrepareWalletUpgradeResponse>;
+    /**
+     * Execute a wallet upgrade after the owner has signed the typed data.
+     */
+    executeWalletUpgrade(params: ExecuteWalletUpgradeParams, bearerToken: string): Promise<ExecuteWalletUpgradeResponse>;
+    /**
+     * 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).
+     */
+    migrateToShhh(params: Omit<MigrateChipiWalletToShhhParams, "client" | "bearerToken">, bearerToken: string): Promise<MigrationOutcome>;
+}
+
+export { ChipiWallets as C, type ExecuteMigrateResponse as E, type MigrateChipiWalletToShhhParams as M, type PrepareMigrateResponse as P, type MigrationOutcome as a, migrateChipiWalletToShhh as m };

package/dist/wallets.d.mts

@@ -1,56 +1,3 @@
-import { CreateWalletParams, CreateWalletResponse, CreateCustodialWalletParams, WalletData, GetWalletParams, GetWalletResponse, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, GetTokenBalanceParams, GetTokenBalanceResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse } from '@chipi-stack/types';
-import { C as ChipiClient } from './client-CqD_yGH0.mjs';
-
-/**
- * Wallet management utilities
- */
-declare class ChipiWallets {
-    private client;
-    constructor(client: ChipiClient);
-    createWallet(params: CreateWalletParams & {
-        bearerToken: string;
-    }): Promise<CreateWalletResponse>;
-    /**
-     * Build constructor calldata based on wallet type
-     * - CHIPI: Simple OpenZeppelin account with just public_key
-     * - ARGENT: Argent X Account with owner/guardian structure
-     */
-    private buildConstructorCallData;
-    /**
-     * Create a custodial merchant wallet
-     */
-    createCustodialWallet({ params, bearerToken, }: {
-        params: Omit<CreateCustodialWalletParams, "orgId">;
-        bearerToken: string;
-    }): Promise<WalletData>;
-    getWallet(params: GetWalletParams, bearerToken: string): Promise<GetWalletResponse | null>;
-    /**
-     * Recover passkey credential metadata for a wallet.
-     * Used when localStorage is cleared — SDK recovers credentialId from backend.
-     */
-    getCredentialRecovery(params: {
-        externalUserId: string;
-    }, bearerToken: string): Promise<{
-        credentialId: string | null;
-        authMethod: string | null;
-        prfSupported: boolean | null;
-        deviceType: string | null;
-    }>;
-    updateWalletEncryption(params: UpdateWalletEncryptionParams, bearerToken: string): Promise<UpdateWalletEncryptionResponse>;
-    getPrivateKeyAX: () => string;
-    getTokenBalance({ params, bearerToken, }: {
-        params: GetTokenBalanceParams;
-        bearerToken: string;
-    }): Promise<GetTokenBalanceResponse>;
-    /**
-     * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
-     * Returns typed data that must be signed by the wallet owner.
-     */
-    prepareWalletUpgrade(params: PrepareWalletUpgradeParams, bearerToken: string): Promise<PrepareWalletUpgradeResponse>;
-    /**
-     * Execute a wallet upgrade after the owner has signed the typed data.
-     */
-    executeWalletUpgrade(params: ExecuteWalletUpgradeParams, bearerToken: string): Promise<ExecuteWalletUpgradeResponse>;
-}
-
-export { ChipiWallets };
+import '@chipi-stack/types';
+import './client-CqD_yGH0.mjs';
+export { C as ChipiWallets } from './wallets-CYCLyyXY.mjs';

package/dist/wallets.d.ts

@@ -1,56 +1,3 @@
-import { CreateWalletParams, CreateWalletResponse, CreateCustodialWalletParams, WalletData, GetWalletParams, GetWalletResponse, UpdateWalletEncryptionParams, UpdateWalletEncryptionResponse, GetTokenBalanceParams, GetTokenBalanceResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse } from '@chipi-stack/types';
-import { C as ChipiClient } from './client-CqD_yGH0.js';
-
-/**
- * Wallet management utilities
- */
-declare class ChipiWallets {
-    private client;
-    constructor(client: ChipiClient);
-    createWallet(params: CreateWalletParams & {
-        bearerToken: string;
-    }): Promise<CreateWalletResponse>;
-    /**
-     * Build constructor calldata based on wallet type
-     * - CHIPI: Simple OpenZeppelin account with just public_key
-     * - ARGENT: Argent X Account with owner/guardian structure
-     */
-    private buildConstructorCallData;
-    /**
-     * Create a custodial merchant wallet
-     */
-    createCustodialWallet({ params, bearerToken, }: {
-        params: Omit<CreateCustodialWalletParams, "orgId">;
-        bearerToken: string;
-    }): Promise<WalletData>;
-    getWallet(params: GetWalletParams, bearerToken: string): Promise<GetWalletResponse | null>;
-    /**
-     * Recover passkey credential metadata for a wallet.
-     * Used when localStorage is cleared — SDK recovers credentialId from backend.
-     */
-    getCredentialRecovery(params: {
-        externalUserId: string;
-    }, bearerToken: string): Promise<{
-        credentialId: string | null;
-        authMethod: string | null;
-        prfSupported: boolean | null;
-        deviceType: string | null;
-    }>;
-    updateWalletEncryption(params: UpdateWalletEncryptionParams, bearerToken: string): Promise<UpdateWalletEncryptionResponse>;
-    getPrivateKeyAX: () => string;
-    getTokenBalance({ params, bearerToken, }: {
-        params: GetTokenBalanceParams;
-        bearerToken: string;
-    }): Promise<GetTokenBalanceResponse>;
-    /**
-     * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
-     * Returns typed data that must be signed by the wallet owner.
-     */
-    prepareWalletUpgrade(params: PrepareWalletUpgradeParams, bearerToken: string): Promise<PrepareWalletUpgradeResponse>;
-    /**
-     * Execute a wallet upgrade after the owner has signed the typed data.
-     */
-    executeWalletUpgrade(params: ExecuteWalletUpgradeParams, bearerToken: string): Promise<ExecuteWalletUpgradeResponse>;
-}
-
-export { ChipiWallets };
+import '@chipi-stack/types';
+import './client-CqD_yGH0.js';
+export { C as ChipiWallets } from './wallets-DxKnh21Q.js';