keyring.ts

import type { AccountId, JsonRpcRequest } from '@metamask/keyring-utils';
import type { Json } from '@metamask/utils';

import type { KeyringAccount } from './account';
import type { ResolvedAccountAddress } from './address';
import type { Balance } from './balance';
import type { CaipChainId, CaipAssetType, CaipAssetTypeOrId } from './caip';
import type { DiscoveredAccount } from './discovery';
import type { EntropySourceId } from './entropy';
import type { KeyringAccountData } from './export';
import type { MetaMaskOptions } from './options';
import type { Paginated, Pagination } from './pagination';
import type { KeyringRequest } from './request';
import type { KeyringResponse } from './response';
import type { Transaction } from './transaction';
import type { CreateAccountOptions } from './v2';

/**
 * Keyring interface.
 *
 * Represents the functionality and operations related to managing accounts and
 * handling requests.
 */
export type Keyring = {
  /**
   * List accounts.
   *
   * Retrieves an array of KeyringAccount objects representing the available
   * accounts.
   *
   * @returns A promise that resolves to an array of KeyringAccount objects.
   */
  listAccounts(): Promise<KeyringAccount[]>;

  /**
   * Get an account.
   *
   * Retrieves the KeyringAccount object for the given account ID.
   *
   * @param id - The ID of the account to retrieve.
   * @returns A promise that resolves to the KeyringAccount object if found, or
   * undefined otherwise.
   */
  getAccount(id: string): Promise<KeyringAccount | undefined>;

  /**
   * Create an account.
   *
   * Creates a new account with optional, keyring-defined, account options.
   *
   * @param options - Keyring-defined options for the account (optional). The
   * 'metamask' internal options needs to be re-emitted during `notify:*` events.
   * @returns A promise that resolves to the newly created KeyringAccount
   * object without any private information.
   */
  createAccount(
    options?: Record<string, Json> & MetaMaskOptions,
  ): Promise<KeyringAccount>;

  /**
   * Creates one or more new accounts according to the provided options.
   *
   * Deterministic account creation MUST be idempotent, meaning that for
   * deterministic algorithms, like BIP-44, calling this method with the same
   * options should always return the same accounts, even if the accounts
   * already exist in the keyring.
   *
   * @param options - Options describing how to create the account(s).
   * @returns A promise that resolves to an array of the created account objects.
   */
  createAccounts?(options: CreateAccountOptions): Promise<KeyringAccount[]>;

  /**
   * Lists the assets of an account (fungibles and non-fungibles) represented
   * by their respective CAIP-19:
   * - Asset types for fungibles assets.
   * - Asset IDs for non-fungible ones.
   *
   * @param id - The ID of the account to list the assets for.
   * @returns A promise that resolves to list of assets for that account.
   */
  listAccountAssets?(id: string): Promise<CaipAssetTypeOrId[]>;

  /**
   * Lists the transactions of an account, paginated and ordered by the most
   * recent first.
   *
   * The pagination options are used to limit the number of transactions in the
   * response and to iterate over the results.
   *
   * @param id - The ID of the account to list the transactions for.
   * @param pagination - The pagination options.
   * @returns A promise that resolves to the next page of transactions.
   */
  listAccountTransactions?(
    id: string,
    pagination: Pagination,
  ): Promise<Paginated<Transaction>>;

  /**
   * Discover accounts.
   *
   * This method is called by the client to allow the keyring to discover
   * existing accounts based on the provided scopes and entropy source ID. Are
   * considered existing accounts, accounts that have at least one transaction,
   * as per BIP-44.
   *
   * The `groupIndex` is used to group accounts with the same value. In
   * strictly BIP-44 wallets, it matches `account_index`, but in wallets that
   * deviate from BIP-44 recommendations, it may align with a different path
   * level for compatibility.
   *
   * @param scopes - The list of scopes for account discovery.
   * @param entropySource - The ID of the entropy source used to derive the accounts.
   * @param groupIndex - The group index that should be used to derive the accounts.
   * @returns A promise resolving to a list of discovered accounts.
   */
  discoverAccounts?(
    scopes: CaipChainId[],
    entropySource: EntropySourceId,
    groupIndex: number,
  ): Promise<DiscoveredAccount[]>;

  /**
   * Retrieve the balances of a given account.
   *
   * This method fetches the balances of specified assets for a given account
   * ID. It returns a promise that resolves to an object where the keys are
   * asset types and the values are balance objects containing the amount and
   * unit.
   *
   * @example
   * ```ts
   * await keyring.getAccountBalances(
   *   '43550276-c7d6-4fac-87c7-00390ad0ce90',
   *   ['bip122:000000000019d6689c085ae165831e93/slip44:0']
   * );
   * // Returns something similar to:
   * // {
   * //   'bip122:000000000019d6689c085ae165831e93/slip44:0': {
   * //     amount: '0.0001',
   * //     unit: 'BTC',
   * //   }
   * // }
   * ```
   * @param id - ID of the account to retrieve the balances for.
   * @param assets - Array of asset types (CAIP-19) to retrieve balances for.
   * @returns A promise that resolves to an object mapping asset types to their
   * respective balances.
   */
  getAccountBalances?(
    id: string,
    assets: CaipAssetType[],
  ): Promise<Record<CaipAssetType, Balance>>;

  /**
   * Resolves the address of an account from a signing request.
   *
   * This is required by the routing system of MetaMask to dispatch
   * incoming non-EVM dapp signing requests.
   *
   * @param scope - Request's scope (CAIP-2).
   * @param request - Signing request object.
   * @returns A Promise that resolves to the account address that must
   * be used to process this signing request, or null if none candidates
   * could be found.
   */
  resolveAccountAddress?(
    scope: CaipChainId,
    request: JsonRpcRequest,
  ): Promise<ResolvedAccountAddress | null>;

  /**
   * Set the selected accounts.
   *
   * @param accounts - The accounts to set as selected.
   */
  setSelectedAccounts?(accounts: AccountId[]): Promise<void>;

  /**
   * Filter supported chains for a given account.
   *
   * @param id - ID of the account to be checked.
   * @param chains - List of chains (CAIP-2) to be checked.
   * @returns A Promise that resolves to a filtered list of CAIP-2 IDs
   * representing the supported chains.
   */
  filterAccountChains(id: string, chains: string[]): Promise<string[]>;

  /**
   * Update an account.
   *
   * Updates the account with the given account object. Does nothing if the
   * account does not exist.
   *
   * @param account - The updated account object.
   * @returns A promise that resolves when the account is successfully updated.
   */
  updateAccount(account: KeyringAccount): Promise<void>;

  /**
   * Delete an account from the keyring.
   *
   * Deletes the account with the given ID from the keyring.
   *
   * @param id - The ID of the account to delete.
   * @returns A promise that resolves when the account is successfully deleted.
   */
  deleteAccount(id: string): Promise<void>;

  /**
   * Exports an account's private key.
   *
   * If the keyring cannot export a private key, this function should throw an
   * error.
   *
   * @param id - The ID of the account to export.
   * @returns A promise that resolves to the exported account.
   */
  exportAccount?(id: string): Promise<KeyringAccountData>;

  /**
   * List all submitted requests.
   *
   * Retrieves an array of KeyringRequest objects representing the submitted
   * requests.
   *
   * @returns A promise that resolves to an array of KeyringRequest objects.
   */
  listRequests?(): Promise<KeyringRequest[]>;

  /**
   * Get a request.
   *
   * Retrieves the KeyringRequest object for the given request ID.
   *
   * @param id - The ID of the request to retrieve.
   * @returns A promise that resolves to the KeyringRequest object if found, or
   * undefined otherwise.
   */
  getRequest?(id: string): Promise<KeyringRequest | undefined>;

  /**
   * Submit a request.
   *
   * Submits the given KeyringRequest object.
   *
   * @param request - The KeyringRequest object to submit.
   * @returns A promise that resolves to the request response.
   */
  submitRequest(request: KeyringRequest): Promise<KeyringResponse>;

  /**
   * Approve a request.
   *
   * Approves the request with the given ID and sets the response if provided.
   *
   * @param id - The ID of the request to approve.
   * @param data - The response to the request (optional).
   * @returns A promise that resolves when the request is successfully
   * approved.
   */
  approveRequest?(id: string, data?: Record<string, Json>): Promise<void>;

  /**
   * Reject a request.
   *
   * Rejects the request with the given ID.
   *
   * @param id - The ID of the request to reject.
   * @returns A promise that resolves when the request is successfully
   * rejected.
   */
  rejectRequest?(id: string): Promise<void>;
};