@metamask-previews/transaction-controller 8.0.1-preview.d32a7cc

package/dist/TransactionController.d.ts

@@ -0,0 +1,327 @@
+/// <reference types="node" />
+import { Hardfork } from '@ethereumjs/common';
+import type { TypedTransaction } from '@ethereumjs/tx';
+import type { AddApprovalRequest } from '@metamask/approval-controller';
+import type { BaseConfig, BaseState, RestrictedControllerMessenger } from '@metamask/base-controller';
+import { BaseController } from '@metamask/base-controller';
+import type { BlockTracker, NetworkState, Provider } from '@metamask/network-controller';
+import { EventEmitter } from 'events';
+import type { Transaction, TransactionMeta, WalletDevice } from './types';
+export declare const HARDFORK = Hardfork.London;
+/**
+ * @type Result
+ * @property result - Promise resolving to a new transaction hash
+ * @property transactionMeta - Meta information about this new transaction
+ */
+export interface Result {
+    result: Promise<string>;
+    transactionMeta: TransactionMeta;
+}
+/**
+ * @type Fetch All Options
+ * @property fromBlock - String containing a specific block decimal number
+ * @property etherscanApiKey - API key to be used to fetch token transactions
+ */
+export interface FetchAllOptions {
+    fromBlock?: string;
+    etherscanApiKey?: string;
+}
+export interface GasPriceValue {
+    gasPrice: string;
+}
+export interface FeeMarketEIP1559Values {
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+}
+/**
+ * @type TransactionConfig
+ *
+ * Transaction controller configuration
+ * @property interval - Polling interval used to fetch new currency rate
+ * @property provider - Provider used to create a new underlying EthQuery instance
+ * @property sign - Method used to sign transactions
+ */
+export interface TransactionConfig extends BaseConfig {
+    interval: number;
+    sign?: (transaction: Transaction, from: string) => Promise<any>;
+    txHistoryLimit: number;
+}
+/**
+ * @type MethodData
+ *
+ * Method data registry object
+ * @property registryMethod - Registry method raw string
+ * @property parsedRegistryMethod - Registry method object, containing name and method arguments
+ */
+export interface MethodData {
+    registryMethod: string;
+    parsedRegistryMethod: Record<string, unknown>;
+}
+/**
+ * @type TransactionState
+ *
+ * Transaction controller state
+ * @property transactions - A list of TransactionMeta objects
+ * @property methodData - Object containing all known method data information
+ */
+export interface TransactionState extends BaseState {
+    transactions: TransactionMeta[];
+    methodData: {
+        [key: string]: MethodData;
+    };
+    lastFetchedBlockNumbers: {
+        [key: string]: number;
+    };
+}
+/**
+ * Multiplier used to determine a transaction's increased gas fee during cancellation
+ */
+export declare const CANCEL_RATE = 1.5;
+/**
+ * Multiplier used to determine a transaction's increased gas fee during speed up
+ */
+export declare const SPEED_UP_RATE = 1.1;
+/**
+ * The name of the {@link TransactionController}.
+ */
+declare const controllerName = "TransactionController";
+/**
+ * The external actions available to the {@link TransactionController}.
+ */
+declare type AllowedActions = AddApprovalRequest;
+/**
+ * The messenger of the {@link TransactionController}.
+ */
+export declare type TransactionControllerMessenger = RestrictedControllerMessenger<typeof controllerName, AllowedActions, never, AllowedActions['type'], never>;
+/**
+ * Controller responsible for submitting and managing transactions.
+ */
+export declare class TransactionController extends BaseController<TransactionConfig, TransactionState> {
+    private ethQuery;
+    private readonly nonceTracker;
+    private registry;
+    private readonly provider;
+    private handle?;
+    private readonly mutex;
+    private readonly getNetworkState;
+    private readonly messagingSystem;
+    private readonly incomingTransactionHelper;
+    private failTransaction;
+    private registryLookup;
+    /**
+     * EventEmitter instance used to listen to specific transactional events
+     */
+    hub: EventEmitter;
+    /**
+     * Name of this controller used during composition
+     */
+    name: string;
+    /**
+     * Method used to sign transactions
+     */
+    sign?: (transaction: TypedTransaction, from: string) => Promise<TypedTransaction>;
+    /**
+     * Creates a TransactionController instance.
+     *
+     * @param options - The controller options.
+     * @param options.blockTracker - The block tracker used to poll for new blocks data.
+     * @param options.getNetworkState - Gets the state of the network controller.
+     * @param options.getSelectedAddress - Gets the address of the currently selected account.
+     * @param options.incomingTransactions - Configuration options for incoming transaction support.
+     * @param options.incomingTransactions.apiKey - An optional API key to use when fetching remote transaction data.
+     * @param options.incomingTransactions.includeTokenTransfers - Whether or not to include ERC20 token transfers.
+     * @param options.incomingTransactions.isEnabled - Whether or not incoming transaction retrieval is enabled.
+     * @param options.incomingTransactions.updateTransactions - Whether or not to update local transactions using remote transaction data.
+     * @param options.messenger - The controller messenger.
+     * @param options.onNetworkStateChange - Allows subscribing to network controller state changes.
+     * @param options.provider - The provider used to create the underlying EthQuery instance.
+     * @param config - Initial options used to configure this controller.
+     * @param state - Initial state to set on this controller.
+     */
+    constructor({ blockTracker, getNetworkState, getSelectedAddress, incomingTransactions, messenger, onNetworkStateChange, provider, }: {
+        blockTracker: BlockTracker;
+        getNetworkState: () => NetworkState;
+        getSelectedAddress: () => string;
+        incomingTransactions: {
+            apiKey?: string;
+            includeTokenTransfers?: boolean;
+            isEnabled?: () => boolean;
+            updateTransactions?: boolean;
+        };
+        messenger: TransactionControllerMessenger;
+        onNetworkStateChange: (listener: (state: NetworkState) => void) => void;
+        provider: Provider;
+    }, config?: Partial<TransactionConfig>, state?: Partial<TransactionState>);
+    /**
+     * Starts a new polling interval.
+     *
+     * @param interval - The polling interval used to fetch new transaction statuses.
+     */
+    poll(interval?: number): Promise<void>;
+    /**
+     * Handle new method data request.
+     *
+     * @param fourBytePrefix - The method prefix.
+     * @returns The method data object corresponding to the given signature prefix.
+     */
+    handleMethodData(fourBytePrefix: string): Promise<MethodData>;
+    /**
+     * Add a new unapproved transaction to state. Parameters will be validated, a
+     * unique transaction id will be generated, and gas and gasPrice will be calculated
+     * if not provided. If A `<tx.id>:unapproved` hub event will be emitted once added.
+     *
+     * @param transaction - The transaction object to add.
+     * @param opts - Additional options to control how the transaction is added.
+     * @param opts.deviceConfirmedOn - An enum to indicate what device confirmed the transaction.
+     * @param opts.origin - The origin of the transaction request, such as a dApp hostname.
+     * @param opts.requireApproval - Whether the transaction requires approval by the user, defaults to true unless explicitly disabled.
+     * @returns Object containing a promise resolving to the transaction hash if approved.
+     */
+    addTransaction(transaction: Transaction, { deviceConfirmedOn, origin, requireApproval, }?: {
+        deviceConfirmedOn?: WalletDevice;
+        origin?: string;
+        requireApproval?: boolean | undefined;
+    }): Promise<Result>;
+    startIncomingTransactionPolling(): void;
+    stopIncomingTransactionPolling(): void;
+    updateIncomingTransactions(): Promise<void>;
+    /**
+     * Creates approvals for all unapproved transactions persisted.
+     */
+    initApprovals(): void;
+    /**
+     * Attempts to cancel a transaction based on its ID by setting its status to "rejected"
+     * and emitting a `<tx.id>:finished` hub event.
+     *
+     * @param transactionID - The ID of the transaction to cancel.
+     * @param gasValues - The gas values to use for the cancellation transaction.
+     */
+    stopTransaction(transactionID: string, gasValues?: GasPriceValue | FeeMarketEIP1559Values): Promise<void>;
+    /**
+     * Attempts to speed up a transaction increasing transaction gasPrice by ten percent.
+     *
+     * @param transactionID - The ID of the transaction to speed up.
+     * @param gasValues - The gas values to use for the speed up transation.
+     */
+    speedUpTransaction(transactionID: string, gasValues?: GasPriceValue | FeeMarketEIP1559Values): Promise<void>;
+    /**
+     * Estimates required gas for a given transaction.
+     *
+     * @param transaction - The transaction to estimate gas for.
+     * @returns The gas and gas price.
+     */
+    estimateGas(transaction: Transaction): Promise<{
+        gas: string;
+        gasPrice: any;
+        estimateGasError?: undefined;
+    } | {
+        gas: string;
+        gasPrice: any;
+        estimateGasError: string | undefined;
+    }>;
+    /**
+     * Check the status of submitted transactions on the network to determine whether they have
+     * been included in a block. Any that have been included in a block are marked as confirmed.
+     */
+    queryTransactionStatuses(): Promise<void>;
+    /**
+     * Updates an existing transaction in state.
+     *
+     * @param transactionMeta - The new transaction to store in state.
+     */
+    updateTransaction(transactionMeta: TransactionMeta): void;
+    /**
+     * Removes all transactions from state, optionally based on the current network.
+     *
+     * @param ignoreNetwork - Determines whether to wipe all transactions, or just those on the
+     * current network. If `true`, all transactions are wiped.
+     * @param address - If specified, only transactions originating from this address will be
+     * wiped on current network.
+     */
+    wipeTransactions(ignoreNetwork?: boolean, address?: string): void;
+    startIncomingTransactionProcessing(): void;
+    stopIncomingTransactionProcessing(): void;
+    private processApproval;
+    /**
+     * Approves a transaction and updates it's status in state. If this is not a
+     * retry transaction, a nonce will be generated. The transaction is signed
+     * using the sign configuration property, then published to the blockchain.
+     * A `<tx.id>:finished` hub event is fired after success or failure.
+     *
+     * @param transactionID - The ID of the transaction to approve.
+     */
+    private approveTransaction;
+    /**
+     * Cancels a transaction based on its ID by setting its status to "rejected"
+     * and emitting a `<tx.id>:finished` hub event.
+     *
+     * @param transactionID - The ID of the transaction to cancel.
+     */
+    private cancelTransaction;
+    /**
+     * Trim the amount of transactions that are set on the state. Checks
+     * if the length of the tx history is longer then desired persistence
+     * limit and then if it is removes the oldest confirmed or rejected tx.
+     * Pending or unapproved transactions will not be removed by this
+     * operation. For safety of presenting a fully functional transaction UI
+     * representation, this function will not break apart transactions with the
+     * same nonce, created on the same day, per network. Not accounting for transactions of the same
+     * nonce, same day and network combo can result in confusing or broken experiences
+     * in the UI. The transactions are then updated using the BaseController update.
+     *
+     * @param transactions - The transactions to be applied to the state.
+     * @returns The trimmed list of transactions.
+     */
+    private trimTransactionsForState;
+    /**
+     * Determines if the transaction is in a final state.
+     *
+     * @param status - The transaction status.
+     * @returns Whether the transaction is in a final state.
+     */
+    private isFinalState;
+    /**
+     * Whether the transaction has at least completed all local processing.
+     *
+     * @param status - The transaction status.
+     * @returns Whether the transaction is in a final state.
+     */
+    private isLocalFinalState;
+    /**
+     * Method to verify the state of a transaction using the Blockchain as a source of truth.
+     *
+     * @param meta - The local transaction to verify on the blockchain.
+     * @returns A tuple containing the updated transaction, and whether or not an update was required.
+     */
+    private blockchainTransactionStateReconciler;
+    /**
+     * Method to check if a tx has failed according to their receipt
+     * According to the Web3 docs:
+     * TRUE if the transaction was successful, FALSE if the EVM reverted the transaction.
+     * The receipt is not available for pending transactions and returns null.
+     *
+     * @param txHash - The transaction hash.
+     * @returns Whether the transaction has failed.
+     */
+    private checkTxReceiptStatusIsFailed;
+    private requestApproval;
+    private getTransaction;
+    private getApprovalId;
+    private isTransactionCompleted;
+    private getChainAndNetworkId;
+    private prepareUnsignedEthTx;
+    /**
+     * `@ethereumjs/tx` uses `@ethereumjs/common` as a configuration tool for
+     * specifying which chain, network, hardfork and EIPs to support for
+     * a transaction. By referencing this configuration, and analyzing the fields
+     * specified in txParams, @ethereumjs/tx is able to determine which EIP-2718
+     * transaction type to use.
+     *
+     * @returns common configuration object
+     */
+    private getCommonConfiguration;
+    private onIncomingTransactions;
+    private onUpdatedLastFetchedBlockNumbers;
+}
+export default TransactionController;
+//# sourceMappingURL=TransactionController.d.ts.map

package/dist/TransactionController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransactionController.d.ts","sourceRoot":"","sources":["../src/TransactionController.ts"],"names":[],"mappings":"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"}