account-options.ts

import { exactOptional, selectiveUnion, type } from '@metamask/keyring-utils';
import type { Infer } from '@metamask/superstruct';
import {
  boolean,
  intersection,
  literal,
  number,
  object,
  record,
  string,
} from '@metamask/superstruct';
import { isPlainObject, JsonStruct } from '@metamask/utils';

/**
 * Keyring account entropy valid types.
 */
export enum KeyringAccountEntropyTypeOption {
  /**
   * Indicates that the account was created from a mnemonic phrase.
   */
  Mnemonic = 'mnemonic',

  /**
   * Indicates that the account was imported from a private key.
   */
  PrivateKey = 'private-key',

  /**
   * Indicates that the account was created from a hardware wallet.
   */
  Hardware = 'hardware',

  /**
   * Indicates that the account was created with custom, keyring-specific entropy.
   * This is an opaque type where the entropy source is managed internally by the keyring.
   */
  Custom = 'custom',
}

/**
 * Keyring account options struct for mnemonics (BIP-44).
 */
export const KeyringAccountEntropyMnemonicOptionsStruct = object({
  /**
   * Indicates that the account was created from a mnemonic phrase.
   */
  type: literal(`${KeyringAccountEntropyTypeOption.Mnemonic}`),

  /**
   * The ID of the entropy source.
   */
  id: string(), // TODO: Define a struct for entropy source.

  /**
   * The BIP-44 derivation path used to derive the account.
   */
  derivationPath: string(),

  /**
   * Index used to group accounts in the UI.
   *
   * Accounts sharing the same `groupIndex` are displayed together as a
   * multichain account group.
   */
  groupIndex: number(),
});

/**
 * Keyring account options for mnemonics (BIP-44) {@link KeyringAccountEntropyMnemonicOptionsStruct}.
 */
export type KeyringAccountEntropyMnemonicOptions = Infer<
  typeof KeyringAccountEntropyMnemonicOptionsStruct
>;

/**
 * Keyring account options struct for private keys.
 */
export const KeyringAccountEntropyPrivateKeyOptionsStruct = object({
  /**
   * Indicates that the account was imported from a private key.
   */
  type: literal(`${KeyringAccountEntropyTypeOption.PrivateKey}`),
});

/**
 * Keyring account options for private keys {@link KeyringAccountEntropyPrivateKeyOptionsStruct}.
 */
export type KeyringAccountEntropyPrivateKeyOptions = Infer<
  typeof KeyringAccountEntropyPrivateKeyOptionsStruct
>;

/**
 * Keyring account options struct for custom entropy.
 *
 * This is an opaque type where the entropy source is managed internally by the keyring.
 * It behaves similarly to a private key import but allows keyrings to define their own
 * entropy management strategy.
 */
export const KeyringAccountEntropyCustomOptionsStruct = object({
  /**
   * Indicates that the account was created with custom, keyring-specific entropy.
   */
  type: literal(`${KeyringAccountEntropyTypeOption.Custom}`),
});

/**
 * Keyring account options for custom entropy {@link KeyringAccountEntropyCustomOptionsStruct}.
 */
export type KeyringAccountEntropyCustomOptions = Infer<
  typeof KeyringAccountEntropyCustomOptionsStruct
>;

/**
 * Keyring account entropy options struct.
 */
export const KeyringAccountEntropyOptionsStruct = selectiveUnion(
  (value: any) => {
    if (!isPlainObject(value)) {
      return KeyringAccountEntropyMnemonicOptionsStruct;
    }

    switch (value.type) {
      case KeyringAccountEntropyTypeOption.PrivateKey:
        return KeyringAccountEntropyPrivateKeyOptionsStruct;
      case KeyringAccountEntropyTypeOption.Custom:
        return KeyringAccountEntropyCustomOptionsStruct;
      case KeyringAccountEntropyTypeOption.Mnemonic:
        return KeyringAccountEntropyMnemonicOptionsStruct;
      default:
        return KeyringAccountEntropyMnemonicOptionsStruct;
    }
  },
);

/**
 * Keyring account entropy options {@link KeyringAccountEntropyOptionsStruct}.
 */
export type KeyringAccountEntropyOptions = Infer<
  typeof KeyringAccountEntropyOptionsStruct
>;

/**
 * Keyring options struct. This represents various options for a Keyring account object.
 *
 * See {@link KeyringAccountEntropyMnemonicOptionsStruct},
 * {@link KeyringAccountEntropyPrivateKeyOptionsStruct}, and
 * {@link KeyringAccountEntropyCustomOptionsStruct}.
 *
 * @example
 * ```ts
 * {
 *   entropy: {
 *     type: 'mnemonic',
 *     id: '01K0BX6VDR5DPDPGGNA8PZVBVB',
 *     derivationPath: "m/44'/60'/0'/0/0",
 *     groupIndex: 0,
 *   },
 * }
 * ```
 *
 * @example
 * ```ts
 * {
 *   entropy: {
 *     type: 'private-key',
 *   },
 *   exportable: true,
 * }
 * ```
 *
 * @example
 * ```ts
 * {
 *   entropy: {
 *     type: 'custom',
 *   },
 * }
 * ```
 *
 * @example
 * ```ts
 * {
 *   some: {
 *     untyped: 'options',
 *     something: true,
 *   },
 * }
 * ```
 */
export const KeyringAccountOptionsStruct = intersection([
  // Non-Typed options (retro-compatibility):
  record(string(), JsonStruct),

  // Typed options. We use `type` instead of `object` here, to allow
  // extra properties. Also, since we use `record` + `intersection` we
  // are guaranteed that all field values will match the `JsonStruct`.
  //
  // READ THIS CAREFULLY:
  // Previous options that can be matched by this struct will be breaking
  // existing keyring account options.
  type({
    /**
     * Entropy options.
     */
    entropy: exactOptional(KeyringAccountEntropyOptionsStruct),

    /**
     * Indicates whether the account can be exported.
     */
    exportable: exactOptional(boolean()),
  }),
]);

/**
 * Keyring account options {@link KeyringAccountOptionsStruct}.
 */
export type KeyringAccountOptions = Infer<typeof KeyringAccountOptionsStruct>;