@cartridge/controller 0.12.2 → 0.13.3

package/dist/toast/types.d.ts

@@ -2,6 +2,8 @@ export type ToastPosition = "top-left" | "top-right" | "top-center" | "bottom-le
 export interface BaseToastOptions {
     duration?: number;
     position?: ToastPosition;
+    preset?: string;
+    safeToClose?: boolean;
     onClick?: () => void;
 }
 export interface ErrorToastOptions extends BaseToastOptions {
@@ -24,6 +26,7 @@ export interface AchievementToastOptions extends BaseToastOptions {
     title: string;
     subtitle?: string;
     xpAmount: number;
+    progress: number;
     isDraft?: boolean;
 }
 export interface QuestToastOptions extends BaseToastOptions {
@@ -33,8 +36,9 @@ export interface QuestToastOptions extends BaseToastOptions {
 }
 export interface MarketplaceToastOptions extends BaseToastOptions {
     variant: "marketplace";
-    itemName: string;
-    itemImage: string;
-    action: "purchased" | "sold";
+    itemNames: string[];
+    itemImages: string[];
+    collectionName: string;
+    action: "purchased" | "sold" | "sent" | "listed" | "unlisted";
 }
 export type ToastOptions = ErrorToastOptions | TransactionToastOptions | NetworkSwitchToastOptions | AchievementToastOptions | QuestToastOptions | MarketplaceToastOptions;

package/dist/types.d.ts

@@ -169,5 +169,7 @@ export type OpenOptions = {
 export type StarterpackOptions = {
     /** The preimage to use */
     preimage?: string;
+    /** Callback fired after the Play button closes the starterpack modal */
+    onPurchaseComplete?: () => void;
 };
 export {};

package/dist/utils.d.ts

@@ -9,6 +9,14 @@ export declare function normalizeCalls(calls: Call | Call[]): {
     calldata: import('starknet').HexCalldata;
 }[];
 export declare function toSessionPolicies(policies: Policies): SessionPolicies;
+/**
+ * Converts parsed session policies to WASM-compatible Policy objects.
+ *
+ * IMPORTANT: Policies are sorted canonically before hashing. Without this,
+ * Object.keys/entries reordering can cause identical policies to produce
+ * different merkle roots, leading to "session/not-registered" errors.
+ * See: https://github.com/cartridge-gg/controller/issues/2357
+ */
 export declare function toWasmPolicies(policies: ParsedSessionPolicies): Policy[];
 export declare function toArray<T>(val: T | T[]): T[];
 export declare function humanizeString(str: string): string;

package/package.json

@@ -1,10 +1,26 @@
 {
   "name": "@cartridge/controller",
-  "version": "0.12.2",
+  "version": "0.13.3",
   "description": "Cartridge Controller",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cartridge-gg/controller.git",
+    "directory": "packages/controller"
+  },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "scripts": {
+    "build:deps": "pnpm build",
+    "dev": "vite build --watch",
+    "build:browser": "vite build",
+    "build:node": "tsup --config tsup.node.config.ts",
+    "build": "pnpm build:browser && pnpm build:node",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "jest",
+    "version": "pnpm pkg get version"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -21,8 +37,8 @@
     }
   },
   "dependencies": {
-    "@cartridge/controller-wasm": "0.9.1",
-    "@cartridge/penpal": "^6.2.4",
+    "@cartridge/controller-wasm": "catalog:",
+    "@cartridge/penpal": "catalog:",
     "micro-sol-signer": "^0.5.0",
     "bs58": "^6.0.0",
     "ethers": "^6.13.5",
@@ -36,31 +52,20 @@
     "@walletconnect/ethereum-provider": "^2.20.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "@types/mocha": "^10.0.10",
-    "@types/node": "^18.0.6",
+    "@cartridge/tsconfig": "workspace:*",
+    "@types/jest": "catalog:",
+    "@types/mocha": "catalog:",
+    "@types/node": "catalog:",
     "jest": "^29.7.0",
-    "prettier": "^3.4.2",
+    "prettier": "catalog:",
     "rollup-plugin-visualizer": "^5.12.0",
     "ts-jest": "^29.2.5",
-    "tsup": "^8.0.1",
-    "typescript": "^5.7.3",
-    "vite": "^6.0.0",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
     "vite-plugin-dts": "^4.5.3",
     "vite-plugin-node-polyfills": "^0.23.0",
-    "vite-plugin-top-level-await": "^1.4.4",
-    "vite-plugin-wasm": "^3.4.1",
-    "@cartridge/tsconfig": "0.12.2"
-  },
-  "scripts": {
-    "build:deps": "pnpm build",
-    "dev": "vite build --watch",
-    "build:browser": "vite build",
-    "build:node": "tsup --config tsup.node.config.ts",
-    "build": "pnpm build:browser && pnpm build:node",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\"",
-    "test": "jest",
-    "version": "pnpm pkg get version"
+    "vite-plugin-top-level-await": "catalog:",
+    "vite-plugin-wasm": "catalog:"
   }
-}
+}

package/src/__tests__/controllerDefaults.test.ts

@@ -41,30 +41,30 @@ describe("ControllerProvider defaults", () => {
     );
   });
 
-  test("should throw error when using non-Cartridge RPC for mainnet", async () => {
-    const invalidChains = [
+  test("should allow non-Cartridge RPC for mainnet", async () => {
+    const customChains = [
       { rpcUrl: "https://some-other-provider.com/starknet/mainnet/rpc/v0_9" },
     ];
 
     expect(() => {
       new ControllerProvider({
-        chains: invalidChains,
+        chains: customChains,
         defaultChainId: constants.StarknetChainId.SN_MAIN,
       });
-    }).toThrow("Only Cartridge RPC providers are allowed for mainnet");
+    }).not.toThrow();
   });
 
-  test("should throw error when using non-Cartridge RPC for sepolia", async () => {
-    const invalidChains = [
+  test("should allow non-Cartridge RPC for sepolia", async () => {
+    const customChains = [
       { rpcUrl: "https://some-other-provider.com/starknet/sepolia/rpc/v0_9" },
     ];
 
     expect(() => {
       new ControllerProvider({
-        chains: invalidChains,
+        chains: customChains,
         defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
       });
-    }).toThrow("Only Cartridge RPC providers are allowed for sepolia");
+    }).not.toThrow();
   });
 
   test("should allow non-Cartridge RPC for custom chains", () => {

package/src/__tests__/parseChainId.test.ts

@@ -42,17 +42,25 @@ describe("parseChainId", () => {
     });
   });
 
+  describe("Non-Cartridge hosts", () => {
+    test("returns placeholder chainId in Node", () => {
+      expect(parseChainId(new URL("http://dl:123123"))).toBe(
+        shortString.encodeShortString("LOCALHOST"),
+      );
+    });
+  });
+
   describe("Error cases", () => {
     test("throws error for unsupported URL format", () => {
       expect(() =>
-        parseChainId(new URL("https://api.example.com/unsupported")),
-      ).toThrow("Chain https://api.example.com/unsupported not supported");
+        parseChainId(new URL("https://api.cartridge.gg/unsupported")),
+      ).toThrow("Chain https://api.cartridge.gg/unsupported not supported");
     });
 
     test("throws error for URLs without proper chain identifiers", () => {
       expect(() =>
-        parseChainId(new URL("https://api.example.com/v1/starknet")),
-      ).toThrow("Chain https://api.example.com/v1/starknet not supported");
+        parseChainId(new URL("https://api.cartridge.gg/v1/starknet")),
+      ).toThrow("Chain https://api.cartridge.gg/v1/starknet not supported");
     });
   });
 });

package/src/__tests__/toWasmPolicies.test.ts

@@ -0,0 +1,379 @@
+import { toWasmPolicies } from "../utils";
+import { ParsedSessionPolicies } from "../policies";
+
+describe("toWasmPolicies", () => {
+  describe("canonical ordering", () => {
+    test("sorts contracts by address regardless of input order", () => {
+      const policies1: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xAAA": {
+            methods: [{ entrypoint: "foo", authorized: true }],
+          },
+          "0xBBB": {
+            methods: [{ entrypoint: "bar", authorized: true }],
+          },
+        },
+      };
+
+      const policies2: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xBBB": {
+            methods: [{ entrypoint: "bar", authorized: true }],
+          },
+          "0xAAA": {
+            methods: [{ entrypoint: "foo", authorized: true }],
+          },
+        },
+      };
+
+      const result1 = toWasmPolicies(policies1);
+      const result2 = toWasmPolicies(policies2);
+
+      expect(result1).toEqual(result2);
+      // First policy should be for 0xAAA (sorted alphabetically)
+      expect(result1[0]).toHaveProperty("target", "0xAAA");
+      expect(result1[1]).toHaveProperty("target", "0xBBB");
+    });
+
+    test("sorts methods within contracts by entrypoint", () => {
+      const policies1: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xAAA": {
+            methods: [
+              { entrypoint: "zebra", authorized: true },
+              { entrypoint: "apple", authorized: true },
+              { entrypoint: "mango", authorized: true },
+            ],
+          },
+        },
+      };
+
+      const policies2: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xAAA": {
+            methods: [
+              { entrypoint: "mango", authorized: true },
+              { entrypoint: "zebra", authorized: true },
+              { entrypoint: "apple", authorized: true },
+            ],
+          },
+        },
+      };
+
+      const result1 = toWasmPolicies(policies1);
+      const result2 = toWasmPolicies(policies2);
+
+      expect(result1).toEqual(result2);
+    });
+
+    test("produces consistent output for complex policies", () => {
+      const policies1: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xCCC": {
+            methods: [
+              { entrypoint: "c_method", authorized: true },
+              { entrypoint: "a_method", authorized: true },
+            ],
+          },
+          "0xAAA": {
+            methods: [
+              { entrypoint: "z_method", authorized: true },
+              { entrypoint: "a_method", authorized: true },
+            ],
+          },
+          "0xBBB": {
+            methods: [{ entrypoint: "b_method", authorized: true }],
+          },
+        },
+      };
+
+      // Same policies in different order
+      const policies2: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xBBB": {
+            methods: [{ entrypoint: "b_method", authorized: true }],
+          },
+          "0xAAA": {
+            methods: [
+              { entrypoint: "a_method", authorized: true },
+              { entrypoint: "z_method", authorized: true },
+            ],
+          },
+          "0xCCC": {
+            methods: [
+              { entrypoint: "a_method", authorized: true },
+              { entrypoint: "c_method", authorized: true },
+            ],
+          },
+        },
+      };
+
+      const result1 = toWasmPolicies(policies1);
+      const result2 = toWasmPolicies(policies2);
+
+      expect(result1).toEqual(result2);
+
+      // Verify order: 0xAAA first, then 0xBBB, then 0xCCC
+      // Within 0xAAA: a_method before z_method
+      expect(result1[0]).toHaveProperty("target", "0xAAA");
+      expect(result1[2]).toHaveProperty("target", "0xBBB");
+      expect(result1[3]).toHaveProperty("target", "0xCCC");
+    });
+
+    test("handles case-insensitive address sorting", () => {
+      const policies1: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xaaa": {
+            methods: [{ entrypoint: "foo", authorized: true }],
+          },
+          "0xAAB": {
+            methods: [{ entrypoint: "bar", authorized: true }],
+          },
+        },
+      };
+
+      const policies2: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xAAB": {
+            methods: [{ entrypoint: "bar", authorized: true }],
+          },
+          "0xaaa": {
+            methods: [{ entrypoint: "foo", authorized: true }],
+          },
+        },
+      };
+
+      const result1 = toWasmPolicies(policies1);
+      const result2 = toWasmPolicies(policies2);
+
+      expect(result1).toEqual(result2);
+    });
+
+    test("handles empty policies", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {},
+        messages: [],
+      };
+
+      const result = toWasmPolicies(policies);
+      expect(result).toEqual([]);
+    });
+
+    test("handles undefined contracts and messages", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+      };
+
+      const result = toWasmPolicies(policies);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("ApprovalPolicy handling", () => {
+    test("creates ApprovalPolicy for approve methods with spender and amount", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              {
+                entrypoint: "approve",
+                spender: "0xSPENDER",
+                amount: "1000000000000000000",
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        target: "0xTOKEN",
+        spender: "0xSPENDER",
+        amount: "1000000000000000000",
+      });
+      // Should NOT have method or authorized fields
+      expect(result[0]).not.toHaveProperty("method");
+      expect(result[0]).not.toHaveProperty("authorized");
+    });
+
+    test("converts numeric amount to string in ApprovalPolicy", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              {
+                entrypoint: "approve",
+                spender: "0xSPENDER",
+                amount: 1000000000000000000,
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result[0]).toHaveProperty("amount", "1000000000000000000");
+    });
+
+    test("falls back to CallPolicy for approve without spender", () => {
+      const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              {
+                entrypoint: "approve",
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty("method");
+      expect(result[0]).toHaveProperty("authorized", true);
+      expect(result[0]).not.toHaveProperty("spender");
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[DEPRECATED]"),
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    test("falls back to CallPolicy for approve without amount", () => {
+      const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              {
+                entrypoint: "approve",
+                spender: "0xSPENDER",
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty("method");
+      expect(result[0]).not.toHaveProperty("spender");
+      expect(warnSpy).toHaveBeenCalled();
+
+      warnSpy.mockRestore();
+    });
+
+    test("creates CallPolicy for non-approve methods", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xCONTRACT": {
+            methods: [
+              {
+                entrypoint: "transfer",
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty("target", "0xCONTRACT");
+      expect(result[0]).toHaveProperty("method");
+      expect(result[0]).toHaveProperty("authorized", true);
+    });
+
+    test("handles mixed approve and non-approve methods", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              {
+                entrypoint: "approve",
+                spender: "0xSPENDER",
+                amount: "1000",
+                authorized: true,
+              },
+              {
+                entrypoint: "transfer",
+                authorized: true,
+              },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(2);
+
+      // First should be approve (sorted alphabetically)
+      const approvePolicy = result[0];
+      expect(approvePolicy).toHaveProperty("spender", "0xSPENDER");
+      expect(approvePolicy).toHaveProperty("amount", "1000");
+
+      // Second should be transfer
+      const transferPolicy = result[1];
+      expect(transferPolicy).toHaveProperty("method");
+      expect(transferPolicy).toHaveProperty("authorized", true);
+    });
+
+    test("sorts approve policies correctly among other methods", () => {
+      const policies: ParsedSessionPolicies = {
+        verified: false,
+        contracts: {
+          "0xTOKEN": {
+            methods: [
+              { entrypoint: "transfer", authorized: true },
+              {
+                entrypoint: "approve",
+                spender: "0xSPENDER",
+                amount: "1000",
+                authorized: true,
+              },
+              { entrypoint: "balance_of", authorized: true },
+            ],
+          },
+        },
+      };
+
+      const result = toWasmPolicies(policies);
+
+      expect(result).toHaveLength(3);
+      // Sorted order: approve, balance_of, transfer
+      expect(result[0]).toHaveProperty("spender"); // approve -> ApprovalPolicy
+      expect(result[1]).toHaveProperty("method"); // balance_of -> CallPolicy
+      expect(result[2]).toHaveProperty("method"); // transfer -> CallPolicy
+    });
+  });
+});

package/src/controller.ts

@@ -459,7 +459,14 @@ export default class ControllerProvider extends BaseProvider {
       return;
     }
 
-    await this.keychain.openStarterPack(id, options);
+    const { onPurchaseComplete, ...starterpackOptions } = options ?? {};
+    this.iframes.keychain.setOnStarterpackPlay(onPurchaseComplete);
+    const sanitizedOptions =
+      Object.keys(starterpackOptions).length > 0
+        ? (starterpackOptions as Omit<StarterpackOptions, "onPurchaseComplete">)
+        : undefined;
+
+    await this.keychain.openStarterPack(id, sanitizedOptions);
     this.iframes.keychain?.open();
   }
 
@@ -570,20 +577,6 @@ export default class ControllerProvider extends BaseProvider {
         const url = new URL(chain.rpcUrl);
         const chainId = parseChainId(url);
 
-        // Validate that mainnet and sepolia must use Cartridge RPC
-        const isMainnet = chainId === constants.StarknetChainId.SN_MAIN;
-        const isSepolia = chainId === constants.StarknetChainId.SN_SEPOLIA;
-        const isCartridgeRpc = url.hostname === "api.cartridge.gg";
-        const isLocalhost =
-          url.hostname === "localhost" || url.hostname === "127.0.0.1";
-
-        if ((isMainnet || isSepolia) && !(isCartridgeRpc || isLocalhost)) {
-          throw new Error(
-            `Only Cartridge RPC providers are allowed for ${isMainnet ? "mainnet" : "sepolia"}. ` +
-              `Please use: https://api.cartridge.gg/x/starknet/${isMainnet ? "mainnet" : "sepolia"}/rpc/v0_9`,
-          );
-        }
-
         this.chains.set(chainId, chain);
       } catch (error) {
         console.error(`Failed to parse chainId for ${chain.rpcUrl}:`, error);

package/src/iframe/keychain.ts

@@ -11,11 +11,15 @@ type KeychainIframeOptions = IFrameOptions<Keychain> &
     needsSessionCreation?: boolean;
     username?: string;
     onSessionCreated?: () => void;
+    onStarterpackPlay?: () => void;
     encryptedBlob?: string;
   };
 
+const STARTERPACK_PLAY_CALLBACK_DELAY_MS = 200;
+
 export class KeychainIFrame extends IFrame<Keychain> {
   private walletBridge: WalletBridge;
+  private onStarterpackPlay?: () => void;
 
   constructor({
     url,
@@ -32,11 +36,13 @@ export class KeychainIFrame extends IFrame<Keychain> {
     needsSessionCreation,
     username,
     onSessionCreated,
+    onStarterpackPlay,
     encryptedBlob,
     propagateSessionErrors,
     errorDisplayMode,
     ...iframeOptions
   }: KeychainIframeOptions) {
+    let onStarterpackPlayHandler: (() => Promise<void>) | undefined;
     const _url = new URL(url ?? KEYCHAIN_URL);
     const walletBridge = new WalletBridge();
 
@@ -118,10 +124,32 @@ export class KeychainIFrame extends IFrame<Keychain> {
             onSessionCreated();
           }
         },
+        onStarterpackPlay: (_origin: string) => async () => {
+          if (onStarterpackPlayHandler) {
+            await onStarterpackPlayHandler();
+          }
+        },
       },
     });
 
     this.walletBridge = walletBridge;
+    this.onStarterpackPlay = onStarterpackPlay;
+    onStarterpackPlayHandler = async () => {
+      this.close();
+      const callback = this.onStarterpackPlay;
+      this.onStarterpackPlay = undefined;
+      if (!callback) {
+        return;
+      }
+      await new Promise((resolve) =>
+        setTimeout(resolve, STARTERPACK_PLAY_CALLBACK_DELAY_MS),
+      );
+      try {
+        callback();
+      } catch (error) {
+        console.error("Failed to run starterpack play callback:", error);
+      }
+    };
 
     // Expose the wallet bridge instance globally for WASM interop
     if (typeof window !== "undefined") {
@@ -132,4 +160,8 @@ export class KeychainIFrame extends IFrame<Keychain> {
   getWalletBridge(): WalletBridge {
     return this.walletBridge;
   }
+
+  setOnStarterpackPlay(callback?: () => void) {
+    this.onStarterpackPlay = callback;
+  }
 }