@cartridge/controller 0.3.45 → 0.4.0

package/src/presets.ts

@@ -0,0 +1,140 @@
+import { ControllerThemePresets } from "./types";
+
+export const defaultPresets: ControllerThemePresets = {
+  cartridge: {
+    id: "cartridge",
+    name: "Cartridge",
+    icon: "/whitelabel/cartridge/icon.svg",
+    cover: {
+      light: "/whitelabel/cartridge/cover-light.png",
+      dark: "/whitelabel/cartridge/cover-dark.png",
+    },
+  },
+  "force-prime": {
+    id: "force-prime",
+    name: "Force Prime",
+    icon: "/whitelabel/force-prime/icon.png",
+    cover: "/whitelabel/force-prime/cover.png",
+    colors: {
+      primary: "#E1CC89",
+    },
+  },
+  paved: {
+    id: "paved",
+    name: "Paved",
+    icon: "/whitelabel/paved/icon.svg",
+    cover: "/whitelabel/paved/cover.png",
+    colors: {
+      primary: "#B0CAF8",
+    },
+  },
+  pistols: {
+    id: "pistols",
+    name: "Pistols at Ten Blocks",
+    icon: "/whitelabel/pistols/icon.png",
+    cover: "/whitelabel/pistols/cover.png",
+    colors: {
+      primary: "#EF9758",
+    },
+  },
+  pixelaw: {
+    id: "pixelaw",
+    name: "Pixelaw",
+    icon: "/whitelabel/pixelaw/icon.svg",
+    cover: "/whitelabel/pixelaw/cover.png",
+    colors: {
+      primary: "#7C00B1",
+      primaryForeground: "white",
+    },
+  },
+  "dope-wars": {
+    id: "dope-wars",
+    name: "Dope Wars",
+    icon: "/whitelabel/dope-wars/icon.png",
+    cover: "/whitelabel/dope-wars/cover.png",
+    colors: {
+      primary: "#11ED83",
+    },
+  },
+  zkastle: {
+    id: "zkastle",
+    name: "zKastle",
+    icon: "/whitelabel/zkastle/icon.svg",
+    cover: "/whitelabel/zkastle/cover.png",
+    colors: {
+      primary: "#E50D2C",
+    },
+  },
+  "loot-survivor": {
+    id: "loot-survivor",
+    name: "Loot Survivor",
+    icon: "/whitelabel/loot-survivor/icon.png",
+    cover: "/whitelabel/loot-survivor/cover.png",
+    colors: {
+      primary: "#33FF33",
+    },
+  },
+  "tale-weaver": {
+    id: "tale-weaver",
+    name: "Tale Weaver",
+    icon: "/whitelabel/tale-weaver/icon.png",
+    cover: "/whitelabel/tale-weaver/cover.png",
+    colors: {
+      primary: "#fce377",
+    },
+  },
+  "realm-of-ra": {
+    id: "realm-of-ra",
+    name: "Realm of Ra",
+    icon: "/whitelabel/realm-of-ra/icon.png",
+    cover: "/whitelabel/realm-of-ra/cover.png",
+    colors: {
+      primary: "#de9534",
+    },
+  },
+  "jokers-of-neon": {
+    id: "jokers-of-neon",
+    name: "Jokers of Neon",
+    icon: "/whitelabel/jokers-of-neon/icon.png",
+    cover: "/whitelabel/jokers-of-neon/cover.png",
+    colors: {
+      primary: "#A144B2",
+    },
+  },
+  flippyflop: {
+    id: "flippyflop",
+    name: "FlippyFlop",
+    icon: "/whitelabel/flippyflop/icon.png",
+    cover: "/whitelabel/flippyflop/cover.png",
+    colors: {
+      primary: "#F38332",
+    },
+  },
+  "savage-summit": {
+    id: "savage-summit",
+    name: "Savage Summit",
+    icon: "/whitelabel/savage-summit/icon.png",
+    cover: "/whitelabel/savage-summit/cover.png",
+    colors: {
+      primary: "#fbf7da",
+    },
+  },
+  "dark-shuffle": {
+    id: "dark-shuffle",
+    name: "Dark Shuffle",
+    icon: "/whitelabel/dark-shuffle/icon.svg",
+    cover: "/whitelabel/dark-shuffle/cover.png",
+    colors: {
+      primary: "#F59100",
+    },
+  },
+  "blob-arena": {
+    id: "blob-arena",
+    name: "Blob Arena",
+    icon: "/whitelabel/blob-arena/icon.png",
+    cover: "/whitelabel/blob-arena/cover.png",
+    colors: {
+      primary: "#980f06",
+    },
+  },
+};

package/src/session.ts

@@ -0,0 +1,92 @@
+import { Policy } from "@cartridge/account-wasm";
+import { CartridgeSessionAccount } from "@cartridge/account-wasm/session";
+import {
+  Abi,
+  Account,
+  Call,
+  InvokeFunctionResponse,
+  RpcProvider,
+  Signature,
+  TypedData,
+  UniversalDetails,
+} from "starknet";
+import { SessionSigner } from "./signer";
+import { normalizeCalls } from "./utils";
+
+export * from "./errors";
+export * from "./types";
+export { defaultPresets } from "./presets";
+
+export default class SessionAccount extends Account {
+  public controller: CartridgeSessionAccount;
+
+  constructor({
+    rpcUrl,
+    privateKey,
+    address,
+    ownerGuid,
+    chainId,
+    expiresAt,
+    policies,
+  }: {
+    rpcUrl: string;
+    privateKey: string;
+    address: string;
+    ownerGuid: string;
+    chainId: string;
+    expiresAt: number;
+    policies: Policy[];
+  }) {
+    const controller = CartridgeSessionAccount.new_as_registered(
+      rpcUrl,
+      privateKey,
+      address,
+      ownerGuid,
+      chainId,
+      {
+        expiresAt,
+        policies,
+      },
+    );
+
+    super(
+      new RpcProvider({ nodeUrl: rpcUrl }),
+      address,
+      new SessionSigner(controller),
+    );
+
+    this.controller = controller;
+  }
+
+  /**
+   * Invoke execute function in account contract
+   *
+   * @param calls the invocation object or an array of them, containing:
+   * - contractAddress - the address of the contract
+   * - entrypoint - the entrypoint of the contract
+   * - calldata - (defaults to []) the calldata
+   * - signature - (defaults to []) the signature
+   * @param abis (optional) the abi of the contract for better displaying
+   *
+   * @returns response from addTransaction
+   */
+  async execute(
+    calls: Call | Call[],
+    _abisOrDetails?: Abi[] | UniversalDetails,
+    _transactionsDetail?: UniversalDetails,
+  ): Promise<InvokeFunctionResponse> {
+    return this.controller.execute(normalizeCalls(calls));
+  }
+
+  /**
+   * Sign an JSON object for off-chain usage with the starknet private key and return the signature
+   * This adds a message prefix so it cant be interchanged with transactions
+   *
+   * @param json - JSON object to be signed
+   * @returns the signature of the JSON object
+   * @throws {Error} if the JSON object is not a valid JSON
+   */
+  async signMessage(_typedData: TypedData): Promise<Signature> {
+    throw new Error("signMessage not implemented for SessionSigner");
+  }
+}

package/src/signer.ts

@@ -0,0 +1,144 @@
+import {
+  Abi,
+  BigNumberish,
+  Call,
+  DeclareSignerDetails,
+  DeployAccountSignerDetails,
+  InvocationsSignerDetails,
+  Signature,
+  SignerInterface,
+  TypedData,
+} from "starknet";
+
+import { Keychain, Modal } from "./types";
+import { AsyncMethodReturns } from "@cartridge/penpal";
+import { CartridgeSessionAccount } from "@cartridge/account-wasm/session";
+import { normalizeCalls } from "./utils";
+
+export class Signer implements SignerInterface {
+  private keychain: AsyncMethodReturns<Keychain>;
+  modal: Modal;
+  constructor(keychain: AsyncMethodReturns<Keychain>, modal: Modal) {
+    this.keychain = keychain;
+    this.modal = modal;
+  }
+
+  /**
+   * Method to get the public key of the signer
+   *
+   * @returns public key of signer as hex string with 0x prefix
+   */
+  public getPubKey(): Promise<string> {
+    return Promise.resolve("");
+  }
+
+  /**
+   * Sign an JSON object for off-chain usage with the starknet private key and return the signature
+   * This adds a message prefix so it cant be interchanged with transactions
+   *
+   * @param typedData - JSON object to be signed
+   * @param accountAddress - account
+   * @returns the signature of the JSON object
+   * @throws {Error} if the JSON object is not a valid JSON
+   */
+  public async signMessage(
+    typedData: TypedData,
+    account: string,
+  ): Promise<Signature> {
+    this.modal.open();
+    const res = await this.keychain.signMessage(typedData, account);
+    this.modal.close();
+    return res as Signature;
+  }
+
+  public async signTransaction(
+    transactions: Call[],
+    transactionsDetail: InvocationsSignerDetails,
+    abis?: Abi[],
+  ): Promise<Signature> {
+    this.modal.open();
+    const res = await this.keychain.signTransaction(
+      transactions,
+      transactionsDetail,
+      abis,
+    );
+    this.modal.close();
+    return res;
+  }
+
+  public async signDeployAccountTransaction(
+    transaction: DeployAccountSignerDetails,
+  ): Promise<Signature> {
+    this.modal.open();
+    const res = await this.keychain.signDeployAccountTransaction(transaction);
+    this.modal.close();
+    return res;
+  }
+
+  public async signDeclareTransaction(
+    transaction: DeclareSignerDetails,
+  ): Promise<Signature> {
+    this.modal.open();
+    const res = await this.keychain.signDeclareTransaction(transaction);
+    this.modal.close();
+    return res;
+  }
+}
+
+export class SessionSigner implements SignerInterface {
+  controller: CartridgeSessionAccount;
+
+  constructor(controller: CartridgeSessionAccount) {
+    this.controller = controller;
+  }
+
+  /**
+   * Method to get the public key of the signer
+   *
+   * @returns public key of signer as hex string with 0x prefix
+   */
+  public getPubKey(): Promise<string> {
+    return Promise.resolve("");
+  }
+
+  /**
+   * Sign an JSON object for off-chain usage with the starknet private key and return the signature
+   * This adds a message prefix so it cant be interchanged with transactions
+   *
+   * @param typedData - JSON object to be signed
+   * @param accountAddress - account
+   * @returns the signature of the JSON object
+   * @throws {Error} if the JSON object is not a valid JSON
+   */
+  public async signMessage(
+    _typedData: TypedData,
+    _account: string,
+  ): Promise<Signature> {
+    throw new Error("signMessage not implemented for SessionSigner");
+  }
+
+  public async signTransaction(
+    transactions: Call[],
+    transactionsDetail: InvocationsSignerDetails & { maxFee: BigNumberish },
+    _abis?: Abi[],
+  ): Promise<Signature> {
+    return this.controller.sign_transaction(
+      normalizeCalls(transactions),
+      transactionsDetail.maxFee,
+    );
+  }
+
+  public async signDeployAccountTransaction(
+    _transaction: DeployAccountSignerDetails,
+  ): Promise<Signature> {
+    throw new Error(
+      "signDeployAccountTransaction not implemented for SessionSigner",
+    );
+  }
+
+  public async signDeclareTransaction(
+    _transaction: DeclareSignerDetails,
+  ): Promise<Signature> {
+    throw new Error("signDeclareTransaction not implemented for SessionSigner");
+  }
+}

package/src/types.ts

@@ -0,0 +1,246 @@
+import {
+  constants,
+  Abi,
+  Call,
+  InvocationsDetails,
+  TypedData,
+  InvokeFunctionResponse,
+  Signature,
+  EstimateFeeDetails,
+  EstimateFee,
+  DeclareContractPayload,
+  BigNumberish,
+  InvocationsSignerDetails,
+  DeployAccountSignerDetails,
+  DeclareSignerDetails,
+} from "starknet";
+import { KeychainIFrame, ProfileIFrame } from "./iframe";
+import wasm from "@cartridge/account-wasm/controller";
+
+export type Session = {
+  chainId: constants.StarknetChainId;
+  policies: Policy[];
+  maxFee: BigNumberish;
+  expiresAt: bigint;
+  credentials: {
+    authorization: string[];
+    privateKey: string;
+  };
+};
+
+export type Policy = wasm.Policy & {
+  description?: string;
+};
+
+export enum ResponseCodes {
+  SUCCESS = "SUCCESS",
+  NOT_CONNECTED = "NOT_CONNECTED",
+  ERROR = "ERROR",
+  CANCELED = "CANCELED",
+  USER_INTERACTION_REQUIRED = "USER_INTERACTION_REQUIRED",
+}
+
+export type ConnectError = {
+  code: ResponseCodes;
+  message: string;
+  error?: ControllerError;
+};
+
+export type ControllerError = {
+  code: Number;
+  message: string;
+  data?: any;
+};
+
+export type ConnectReply = {
+  code: ResponseCodes.SUCCESS;
+  address: string;
+  policies: Policy[];
+};
+
+export type ExecuteReply =
+  | (InvokeFunctionResponse & {
+      code: ResponseCodes.SUCCESS;
+    })
+  | {
+      code: ResponseCodes.USER_INTERACTION_REQUIRED;
+    };
+
+export type ProbeReply = {
+  code: ResponseCodes.SUCCESS;
+  address: string;
+};
+
+export type DeployReply = {
+  code: ResponseCodes.SUCCESS;
+  transaction_hash: string;
+};
+
+export type IFrames = {
+  keychain: KeychainIFrame;
+  profile?: ProfileIFrame;
+};
+
+type ContractAddress = string;
+type CartridgeID = string;
+export type ControllerAccounts = Record<ContractAddress, CartridgeID>;
+
+export interface Keychain {
+  probe(rpcUrl: string): Promise<ProbeReply | ConnectError>;
+  connect(
+    policies: Policy[],
+    rpcUrl: string,
+  ): Promise<ConnectReply | ConnectError>;
+  disconnect(): void;
+
+  reset(): void;
+  revoke(origin: string): void;
+
+  deploy(): Promise<DeployReply | ConnectError>;
+  estimateDeclareFee(
+    payload: DeclareContractPayload,
+    details?: EstimateFeeDetails,
+  ): Promise<EstimateFee>;
+  estimateInvokeFee(
+    calls: Call | Call[],
+    estimateFeeDetails?: EstimateFeeDetails,
+  ): Promise<EstimateFee>;
+  execute(
+    calls: Call | Call[],
+    abis?: Abi[],
+    transactionsDetail?: InvocationsDetails,
+    sync?: boolean,
+    paymaster?: PaymasterOptions,
+    error?: ControllerError,
+  ): Promise<ExecuteReply | ConnectError>;
+  logout(): Promise<void>;
+  openSettings(): Promise<void | ConnectError>;
+  session(): Promise<Session>;
+  sessions(): Promise<{
+    [key: string]: Session;
+  }>;
+  signMessage(
+    typedData: TypedData,
+    account: string,
+  ): Promise<Signature | ConnectError>;
+  signTransaction(
+    transactions: Call[],
+    transactionsDetail: InvocationsSignerDetails,
+    abis?: Abi[],
+  ): Promise<Signature>;
+  signDeployAccountTransaction(
+    transaction: DeployAccountSignerDetails,
+  ): Promise<Signature>;
+  signDeclareTransaction(transaction: DeclareSignerDetails): Promise<Signature>;
+  delegateAccount(): string;
+  username(): string;
+  fetchControllers(contractAddresses: string[]): Promise<ControllerAccounts>;
+}
+
+export interface Profile {
+  navigate(tab: ProfileContextTypeVariant): void;
+}
+
+export interface Modal {
+  open: () => void;
+  close: () => void;
+}
+
+/**
+ * Options for configuring the controller
+ */
+export type ControllerOptions = KeychainOptions & ProfileOptions;
+
+export type TokenOptions = {
+  tokens: Tokens;
+};
+
+export type IFrameOptions = {
+  /** The ID of the starter pack to use */
+  starterPackId?: string;
+  /** The theme to use */
+  theme?: string;
+  /** The color mode to use */
+  colorMode?: ColorMode;
+  /** Additional configuration options */
+  config?: {
+    /** Preset themes for the controller */
+    presets?: ControllerThemePresets;
+  };
+};
+
+export type KeychainOptions = IFrameOptions & {
+  policies?: Policy[];
+  /** The URL of keychain */
+  url?: string;
+  /** The URL of the RPC */
+  rpc?: string;
+  /** The origin of keychain */
+  origin?: string;
+  /** Paymaster options for transaction fee management */
+  paymaster?: PaymasterOptions;
+  /** Propagate transaction errors back to caller instead of showing modal */
+  propagateSessionErrors?: boolean;
+};
+
+export type ProfileOptions = IFrameOptions & {
+  /** The URL of profile. Mainly for internal development purpose */
+  profileUrl?: string;
+  /** The URL of Torii indexer. Will be mandatory once profile page is in production */
+  indexerUrl?: string;
+  /** The tokens to be listed on Inventory modal */
+  tokens?: Tokens;
+};
+
+export type ProfileContextTypeVariant = "quest" | "inventory" | "history";
+
+/**
+ * Options for configuring a paymaster
+ */
+export type PaymasterOptions = {
+  /**
+   * The address of the account paying for the transaction.
+   * This should be a valid Starknet address or "ANY_CALLER" short string.
+   */
+  caller: string;
+  /**
+   * The URL of the paymaster. Currently not used.
+   */
+  url?: string;
+};
+
+export type ColorMode = "light" | "dark";
+
+export type ControllerTheme = {
+  id: string;
+  name: string;
+  icon: string;
+  cover: ThemeValue<string>;
+  colorMode: ColorMode;
+};
+
+export type ControllerThemePresets = Record<string, ControllerThemePreset>;
+
+export type ControllerThemePreset = Omit<ControllerTheme, "colorMode"> & {
+  colors?: ControllerColors;
+};
+
+export type ControllerColors = {
+  primary?: ControllerColor;
+  primaryForeground?: ControllerColor;
+};
+
+export type ControllerColor = ThemeValue<string>;
+
+export type ThemeValue<T> = T | { dark: T; light: T };
+
+export type Prefund = { address: string; min: string };
+
+export type Tokens = {
+  erc20?: ERC20[];
+};
+
+export type ERC20 = {
+  address: string;
+  logoUrl?: string;
+};

package/src/utils.ts

@@ -0,0 +1,21 @@
+import equal from "fast-deep-equal";
+import { Policy } from "./types";
+import { addAddressPadding, Call, CallData } from "starknet";
+
+export function diff(a: Policy[], b: Policy[]): Policy[] {
+  return a.reduce(
+    (prev, policyA) =>
+      b.some((policyB) => equal(policyB, policyA)) ? prev : [...prev, policyA],
+    [] as Policy[],
+  );
+}
+
+export function normalizeCalls(calls: Call | Call[]) {
+  return (Array.isArray(calls) ? calls : [calls]).map((call) => {
+    return {
+      entrypoint: call.entrypoint,
+      contractAddress: addAddressPadding(call.contractAddress),
+      calldata: CallData.toHex(call.calldata),
+    };
+  });
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@cartridge/tsconfig/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}