@cartridge/controller 0.3.46 → 0.4.0

package/src/controller.ts

@@ -0,0 +1,271 @@
+import { AccountInterface, addAddressPadding } from "starknet";
+import { AsyncMethodReturns } from "@cartridge/penpal";
+
+import DeviceAccount from "./device";
+import {
+  Keychain,
+  Policy,
+  ResponseCodes,
+  ConnectReply,
+  ProbeReply,
+  ControllerOptions,
+  ConnectError,
+  Profile,
+  IFrames,
+  ProfileContextTypeVariant,
+} from "./types";
+import { KeychainIFrame, ProfileIFrame } from "./iframe";
+import { NotReadyToConnect, ProfileNotReady } from "./errors";
+import { RPC_SEPOLIA } from "./constants";
+
+export * from "./errors";
+export * from "./types";
+export { defaultPresets } from "./presets";
+
+export default class Controller {
+  private policies: Policy[];
+  private keychain?: AsyncMethodReturns<Keychain>;
+  private profile?: AsyncMethodReturns<Profile>;
+  private options: ControllerOptions;
+  private iframes: IFrames;
+  public rpc: URL;
+  public account?: AccountInterface;
+
+  constructor({
+    policies,
+    url,
+    rpc,
+    paymaster,
+    ...options
+  }: ControllerOptions = {}) {
+    this.iframes = {
+      keychain: new KeychainIFrame({
+        ...options,
+        url,
+        paymaster,
+        onClose: this.keychain?.reset,
+        onConnect: (keychain) => {
+          this.keychain = keychain;
+        },
+      }),
+    };
+
+    this.rpc = new URL(rpc || RPC_SEPOLIA);
+
+    // TODO: remove this on the next major breaking change. pass everthing by url
+    this.policies =
+      policies?.map((policy) => ({
+        ...policy,
+        target: addAddressPadding(policy.target),
+      })) || [];
+
+    this.options = options;
+  }
+
+  async openSettings() {
+    if (!this.keychain || !this.iframes.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return null;
+    }
+    this.iframes.keychain.open();
+    const res = await this.keychain.openSettings();
+    this.iframes.keychain.close();
+    if (res && (res as ConnectError).code === ResponseCodes.NOT_CONNECTED) {
+      return false;
+    }
+    return true;
+  }
+
+  ready() {
+    return this.probe().then(
+      (res) => !!res,
+      () => false,
+    );
+  }
+
+  async probe() {
+    try {
+      await this.waitForKeychain();
+
+      if (!this.keychain) {
+        console.error(new NotReadyToConnect().message);
+        return null;
+      }
+
+      const response = (await this.keychain.probe(
+        this.rpc.toString(),
+      )) as ProbeReply;
+
+      this.account = new DeviceAccount(
+        this.rpc.toString(),
+        response.address,
+        this.keychain,
+        this.options,
+        this.iframes.keychain,
+      ) as AccountInterface;
+    } catch (e) {
+      console.log(e);
+      console.error(new NotReadyToConnect().message);
+      return;
+    }
+
+    if (
+      this.options.profileUrl &&
+      this.options.indexerUrl &&
+      !this.iframes.profile
+    ) {
+      const username = await this.keychain.username();
+      this.iframes.profile = new ProfileIFrame({
+        profileUrl: this.options.profileUrl,
+        indexerUrl: this.options.indexerUrl,
+        address: this.account.address,
+        username,
+        rpcUrl: this.rpc.toString(),
+        tokens: this.options.tokens,
+        onConnect: (profile) => {
+          this.profile = profile;
+        },
+      });
+    }
+
+    return !!this.account;
+  }
+
+  async connect() {
+    if (this.account) {
+      return this.account;
+    }
+
+    if (!this.keychain || !this.iframes.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return;
+    }
+
+    if (!!document.hasStorageAccess) {
+      const ok = await document.hasStorageAccess();
+      if (!ok) {
+        await document.requestStorageAccess();
+      }
+    }
+
+    this.iframes.keychain.open();
+
+    try {
+      let response = await this.keychain.connect(
+        this.policies,
+        this.rpc.toString(),
+      );
+      if (response.code !== ResponseCodes.SUCCESS) {
+        throw new Error(response.message);
+      }
+
+      response = response as ConnectReply;
+      this.account = new DeviceAccount(
+        this.rpc.toString(),
+        response.address,
+        this.keychain,
+        this.options,
+        this.iframes.keychain,
+      ) as AccountInterface;
+
+      return this.account;
+    } catch (e) {
+      console.log(e);
+    } finally {
+      this.iframes.keychain.close();
+    }
+  }
+
+  openProfile(tab: ProfileContextTypeVariant = "inventory") {
+    if (!this.options.indexerUrl) {
+      console.error("`indexerUrl` option is required to open profile");
+      return;
+    }
+    if (!this.profile || !this.iframes.profile) {
+      console.error(new ProfileNotReady().message);
+      return;
+    }
+
+    this.profile.navigate(tab);
+    this.iframes.profile.open();
+  }
+
+  async disconnect() {
+    if (!this.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return;
+    }
+
+    if (!!document.hasStorageAccess) {
+      const ok = await document.hasStorageAccess();
+      if (!ok) {
+        await document.requestStorageAccess();
+      }
+    }
+
+    this.account = undefined;
+    return this.keychain.disconnect();
+  }
+
+  revoke(origin: string, _policy: Policy[]) {
+    if (!this.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return null;
+    }
+
+    return this.keychain.revoke(origin);
+  }
+
+  username() {
+    if (!this.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return;
+    }
+
+    return this.keychain.username();
+  }
+
+  fetchControllers(
+    contractAddresses: string[],
+  ): Promise<Record<string, string>> {
+    if (!this.keychain) {
+      throw new NotReadyToConnect().message;
+    }
+
+    return this.keychain.fetchControllers(contractAddresses);
+  }
+
+  async delegateAccount() {
+    if (!this.keychain) {
+      console.error(new NotReadyToConnect().message);
+      return null;
+    }
+
+    return await this.keychain.delegateAccount();
+  }
+
+  private waitForKeychain({
+    timeout = 5000,
+    interval = 100,
+  }:
+    | {
+        timeout?: number;
+        interval?: number;
+      }
+    | undefined = {}) {
+    return new Promise<void>((resolve, reject) => {
+      const startTime = Date.now();
+      const id = setInterval(() => {
+        if (Date.now() - startTime > timeout) {
+          clearInterval(id);
+          reject(new Error("Timeout waiting for keychain"));
+          return;
+        }
+        if (!this.keychain) return;
+
+        clearInterval(id);
+        resolve();
+      }, interval);
+    });
+  }
+}

package/src/device.ts

@@ -0,0 +1,162 @@
+import {
+  Account,
+  Abi,
+  Call,
+  EstimateFeeDetails,
+  Signature,
+  InvokeFunctionResponse,
+  EstimateFee,
+  DeclareContractPayload,
+  RpcProvider,
+  TypedData,
+  InvocationsDetails,
+} from "starknet";
+
+import {
+  ConnectError,
+  Keychain,
+  KeychainOptions,
+  Modal,
+  ResponseCodes,
+} from "./types";
+import { Signer } from "./signer";
+import { AsyncMethodReturns } from "@cartridge/penpal";
+
+class DeviceAccount extends Account {
+  address: string;
+  private keychain: AsyncMethodReturns<Keychain>;
+  private modal: Modal;
+  private options?: KeychainOptions;
+
+  constructor(
+    rpcUrl: string,
+    address: string,
+    keychain: AsyncMethodReturns<Keychain>,
+    options: KeychainOptions,
+    modal: Modal,
+  ) {
+    super(
+      new RpcProvider({ nodeUrl: rpcUrl }),
+      address,
+      new Signer(keychain, modal),
+    );
+    this.address = address;
+    this.keychain = keychain;
+    this.options = options;
+    this.modal = modal;
+  }
+
+  /**
+   * Estimate Fee for a method on starknet
+   *
+   * @param calls the invocation object containing:
+   * - contractAddress - the address of the contract
+   * - entrypoint - the entrypoint of the contract
+   * - calldata - (defaults to []) the calldata
+   * - signature - (defaults to []) the signature
+   *
+   * @returns response from addTransaction
+   */
+  async estimateInvokeFee(
+    calls: Call | Call[],
+    details?: EstimateFeeDetails,
+  ): Promise<EstimateFee> {
+    return this.keychain.estimateInvokeFee(calls, {
+      ...details,
+    });
+  }
+
+  async estimateDeclareFee(
+    payload: DeclareContractPayload,
+    details?: EstimateFeeDetails,
+  ): Promise<EstimateFee> {
+    return this.keychain.estimateDeclareFee(payload, {
+      ...details,
+    });
+  }
+
+  /**
+   * 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
+   */
+  // @ts-expect-error TODO: fix overload type mismatch
+  async execute(
+    calls: Call | Call[],
+    abis?: Abi[],
+    transactionsDetail: InvocationsDetails = {},
+  ): Promise<InvokeFunctionResponse> {
+    return new Promise(async (resolve, reject) => {
+      const sessionExecute = await this.keychain.execute(
+        calls,
+        abis,
+        transactionsDetail,
+        false,
+        this.options?.paymaster,
+      );
+
+      // Session call succeeded
+      if (sessionExecute.code === ResponseCodes.SUCCESS) {
+        resolve(sessionExecute as InvokeFunctionResponse);
+        return;
+      }
+
+      // Propagates session txn error back to caller
+      if (this.options?.propagateSessionErrors) {
+        reject((sessionExecute as ConnectError).error);
+        return;
+      }
+
+      // Session call or Paymaster flow failed.
+      // Session not avaialble, manual flow fallback
+      this.modal.open();
+      const manualExecute = await this.keychain.execute(
+        calls,
+        abis,
+        transactionsDetail,
+        true,
+        this.options?.paymaster,
+        (sessionExecute as ConnectError).error,
+      );
+
+      // Manual call succeeded
+      if (manualExecute.code === ResponseCodes.SUCCESS) {
+        resolve(manualExecute as InvokeFunctionResponse);
+        this.modal.close();
+        return;
+      }
+
+      reject((manualExecute as ConnectError).error);
+      return;
+    });
+  }
+
+  /**
+   * 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> {
+    try {
+      this.modal.open();
+      const res = await this.keychain.signMessage(typedData, this.address);
+      this.modal.close();
+      return res as Signature;
+    } catch (e) {
+      console.error(e);
+      throw e;
+    }
+  }
+}
+
+export default DeviceAccount;

package/src/errors.ts

@@ -0,0 +1,15 @@
+export class NotReadyToConnect extends Error {
+  constructor() {
+    super("Not ready to connect");
+
+    Object.setPrototypeOf(this, NotReadyToConnect.prototype);
+  }
+}
+
+export class ProfileNotReady extends Error {
+  constructor() {
+    super("Profile is not ready");
+
+    Object.setPrototypeOf(this, NotReadyToConnect.prototype);
+  }
+}

package/src/iframe/base.ts

@@ -0,0 +1,140 @@
+import { AsyncMethodReturns, connectToChild } from "@cartridge/penpal";
+import { defaultPresets } from "../presets";
+import { ControllerOptions, Modal } from "../types";
+
+export type IFrameOptions<CallSender> = Omit<
+  ConstructorParameters<typeof IFrame>[0],
+  "id" | "url" | "onConnect"
+> & {
+  url?: string;
+  onConnect: (child: AsyncMethodReturns<CallSender>) => void;
+};
+
+export class IFrame<CallSender extends {}> implements Modal {
+  private iframe?: HTMLIFrameElement;
+  private container?: HTMLDivElement;
+  private onClose?: () => void;
+
+  constructor({
+    id,
+    url,
+    theme,
+    config,
+    colorMode,
+    onClose,
+    onConnect,
+    methods = {},
+  }: Pick<ControllerOptions, "theme" | "config" | "colorMode"> & {
+    id: string;
+    url: URL;
+    onClose?: () => void;
+    onConnect: (child: AsyncMethodReturns<CallSender>) => void;
+    methods?: { [key: string]: (...args: any[]) => void };
+  }) {
+    if (typeof document === "undefined") {
+      return;
+    }
+
+    url.searchParams.set(
+      "theme",
+      encodeURIComponent(
+        JSON.stringify(
+          config?.presets?.[theme ?? "cartridge"] ?? defaultPresets.cartridge,
+        ),
+      ),
+    );
+
+    if (colorMode) {
+      url.searchParams.set("colorMode", colorMode);
+    }
+
+    const iframe = document.createElement("iframe");
+    iframe.src = url.toString();
+    iframe.id = id;
+    iframe.style.border = "none";
+    iframe.sandbox.add("allow-forms");
+    iframe.sandbox.add("allow-popups");
+    iframe.sandbox.add("allow-scripts");
+    iframe.sandbox.add("allow-same-origin");
+    iframe.allow =
+      "publickey-credentials-create *; publickey-credentials-get *; clipboard-write";
+    if (!!document.hasStorageAccess) {
+      iframe.sandbox.add("allow-storage-access-by-user-activation");
+    }
+
+    const container = document.createElement("div");
+    container.style.position = "fixed";
+    container.style.height = "100%";
+    container.style.width = "100%";
+    container.style.top = "0";
+    container.style.left = "0";
+    container.style.zIndex = "10000";
+    container.style.backgroundColor = "rgba(0,0,0,0.6)";
+    container.style.display = "flex";
+    container.style.alignItems = "center";
+    container.style.justifyContent = "center";
+    container.style.visibility = "hidden";
+    container.style.opacity = "0";
+    container.style.transition = "opacity 0.2s ease";
+    container.appendChild(iframe);
+
+    this.iframe = iframe;
+    this.container = container;
+
+    connectToChild<CallSender>({
+      iframe: this.iframe,
+      methods: { close: () => this.close(), ...methods },
+    }).promise.then(onConnect);
+
+    this.resize();
+    window.addEventListener("resize", () => this.resize());
+
+    if (
+      document.readyState === "complete" ||
+      document.readyState === "interactive"
+    ) {
+      this.append();
+    } else {
+      document.addEventListener("DOMContentLoaded", this.append);
+    }
+
+    this.onClose = onClose;
+  }
+
+  open() {
+    if (!this.container) return;
+    document.body.style.overflow = "hidden";
+
+    this.container.style.visibility = "visible";
+    this.container.style.opacity = "1";
+  }
+
+  close() {
+    if (!this.container) return;
+    this.onClose?.();
+
+    document.body.style.overflow = "auto";
+
+    this.container.style.visibility = "hidden";
+    this.container.style.opacity = "0";
+  }
+
+  private append() {
+    if (!this.container) return;
+    document.body.appendChild(this.container);
+  }
+
+  private resize() {
+    if (!this.iframe) return;
+    if (window.innerWidth < 768) {
+      this.iframe.style.height = "100%";
+      this.iframe.style.width = "100%";
+      this.iframe.style.borderRadius = "0";
+      return;
+    }
+
+    this.iframe.style.height = "600px";
+    this.iframe.style.width = "432px";
+    this.iframe.style.borderRadius = "8px";
+  }
+}

package/src/iframe/index.ts

@@ -0,0 +1,3 @@
+export * from "./base";
+export * from "./keychain";
+export * from "./profile";

package/src/iframe/keychain.ts

@@ -0,0 +1,34 @@
+import { KEYCHAIN_URL } from "../constants";
+import { Keychain, KeychainOptions } from "../types";
+import { IFrame, IFrameOptions } from "./base";
+
+type KeychainIframeOptions = IFrameOptions<Keychain> & KeychainOptions;
+
+export class KeychainIFrame extends IFrame<Keychain> {
+  constructor({
+    url,
+    paymaster,
+    policies,
+    ...iframeOptions
+  }: KeychainIframeOptions) {
+    const _url = new URL(url ?? KEYCHAIN_URL);
+    if (paymaster) {
+      _url.searchParams.set(
+        "paymaster",
+        encodeURIComponent(JSON.stringify(paymaster)),
+      );
+    }
+    if (policies) {
+      _url.searchParams.set(
+        "policies",
+        encodeURIComponent(JSON.stringify(policies)),
+      );
+    }
+
+    super({
+      ...iframeOptions,
+      id: "controller-keychain",
+      url: _url,
+    });
+  }
+}

package/src/iframe/profile.ts

@@ -0,0 +1,42 @@
+import { PROFILE_URL } from "../constants";
+import { Profile, ProfileOptions } from "../types";
+import { IFrame, IFrameOptions } from "./base";
+
+export type ProfileIFrameOptions = IFrameOptions<Profile> &
+  ProfileOptions & {
+    address: string;
+    username: string;
+    indexerUrl: string;
+    rpcUrl: string;
+  };
+
+export class ProfileIFrame extends IFrame<Profile> {
+  constructor({
+    profileUrl,
+    address,
+    username,
+    indexerUrl,
+    rpcUrl,
+    tokens,
+    ...iframeOptions
+  }: ProfileIFrameOptions) {
+    const _url = new URL(profileUrl ?? PROFILE_URL);
+    _url.searchParams.set("address", encodeURIComponent(address));
+    _url.searchParams.set("username", encodeURIComponent(username));
+    _url.searchParams.set("indexerUrl", encodeURIComponent(indexerUrl));
+    _url.searchParams.set("rpcUrl", encodeURIComponent(rpcUrl));
+
+    if (tokens?.erc20) {
+      _url.searchParams.set(
+        "erc20",
+        encodeURIComponent(JSON.stringify(tokens.erc20)),
+      );
+    }
+
+    super({
+      ...iframeOptions,
+      id: "controller-profile",
+      url: _url,
+    });
+  }
+}