@metamask-previews/sample-controllers 0.0.0-preview-37b05a4

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/core/

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

package/README.md

@@ -0,0 +1,15 @@
+# `@metamask/sample-controllers`
+
+This package is designed to illustrate best practices for controller packages and controller files, including tests.
+
+## Installation
+
+`yarn add @metamask/sample-controllers`
+
+or
+
+`npm install @metamask/sample-controllers`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

package/dist/tsconfig.build.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.2.2"}

package/dist/types/gas-prices-controller.cjs

@@ -0,0 +1,133 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _GasPricesController_gasPricesService;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GasPricesController = exports.getDefaultGasPricesControllerState = exports.controllerName = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+// === GENERAL ===
+/**
+ * The name of the {@link GasPricesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+exports.controllerName = 'GasPricesController';
+/**
+ * The metadata for each property in {@link GasPricesControllerState}.
+ */
+const gasPricesControllerMetadata = {
+    gasPricesByChainId: {
+        persist: true,
+        anonymous: false,
+    },
+};
+/**
+ * Constructs the default {@link GasPricesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GasPricesController} state.
+ */
+function getDefaultGasPricesControllerState() {
+    return {
+        gasPricesByChainId: {},
+    };
+}
+exports.getDefaultGasPricesControllerState = getDefaultGasPricesControllerState;
+// === CONTROLLER DEFINITION ===
+/**
+ * `GasPricesController` fetches and persists gas prices for various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import {
+ *   GasPricesController,
+ *   GasPricesService
+ * } from '@metamask/example-controllers';
+ * import type {
+ *   GasPricesControllerActions,
+ *   GasPricesControllerEvents
+ * } from '@metamask/example-controllers';
+ * import type { NetworkControllerGetStateAction } from '@metamask/network-controller';
+ *
+ * // Assuming that you're using this in the browser
+ * const gasPricesService = new GasPricesService({ fetch });
+ * const rootMessenger = new Messenger<
+ *  GasPricesControllerActions | NetworkControllerGetStateAction,
+ *  GasPricesControllerEvents
+ * >();
+ * const gasPricesMessenger = rootMessenger.getRestricted({
+ *   name: 'GasPricesController',
+ *   allowedActions: ['NetworkController:getState'],
+ *   allowedEvents: [],
+ * });
+ * const gasPricesController = new GasPricesController({
+ *   messenger: gasPricesMessenger,
+ *   gasPricesService,
+ * });
+ *
+ * // Assuming that `NetworkController:getState` returns an object with a
+ * // `chainId` of `0x42`...
+ * await gasPricesController.updateGasPrices();
+ * gasPricesController.state.gasPricesByChainId
+ * // => { '0x42': { low: 5, average: 10, high: 15, fetchedDate: '2024-01-02T00:00:00.000Z' } }
+ * ```
+ */
+class GasPricesController extends base_controller_1.BaseController {
+    /**
+     * Constructs a new {@link GasPricesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     * @param args.gasPricesService - The service object that will be used to
+     * obtain gas prices.
+     */
+    constructor({ messenger, state, gasPricesService, }) {
+        super({
+            messenger,
+            metadata: gasPricesControllerMetadata,
+            name: exports.controllerName,
+            state: {
+                ...getDefaultGasPricesControllerState(),
+                ...state,
+            },
+        });
+        /**
+         * The service object that is used to obtain gas prices.
+         */
+        _GasPricesController_gasPricesService.set(this, void 0);
+        __classPrivateFieldSet(this, _GasPricesController_gasPricesService, gasPricesService, "f");
+        this.messagingSystem.registerActionHandler(`${exports.controllerName}:updateGasPrices`, this.updateGasPrices.bind(this));
+    }
+    /**
+     * Fetches the latest gas prices for the current chain, persisting them to
+     * state.
+     */
+    async updateGasPrices() {
+        const { chainId } = this.messagingSystem.call('NetworkController:getState');
+        const gasPricesResponse = await __classPrivateFieldGet(this, _GasPricesController_gasPricesService, "f").fetchGasPrices(chainId);
+        this.update((state) => {
+            state.gasPricesByChainId[chainId] = {
+                ...gasPricesResponse,
+                fetchedDate: new Date().toISOString(),
+            };
+        });
+    }
+}
+exports.GasPricesController = GasPricesController;
+_GasPricesController_gasPricesService = new WeakMap();
+//# sourceMappingURL=gas-prices-controller.cjs.map

package/dist/types/gas-prices-controller.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas-prices-controller.cjs","sourceRoot":"","sources":["../../src/gas-prices-controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAMA,+DAA2D;AAM3D,kBAAkB;AAElB;;;;GAIG;AACU,QAAA,cAAc,GAAG,qBAAqB,CAAC;AAuCpD;;GAEG;AACH,MAAM,2BAA2B,GAAG;IAClC,kBAAkB,EAAE;QAClB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,KAAK;KACjB;CACgD,CAAC;AAiEpD;;;;;;;GAOG;AACH,SAAgB,kCAAkC;IAChD,OAAO;QACL,kBAAkB,EAAE,EAAE;KACvB,CAAC;AACJ,CAAC;AAJD,gFAIC;AAED,gCAAgC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAa,mBAAoB,SAAQ,gCAIxC;IAMC;;;;;;;;;OASG;IACH,YAAY,EACV,SAAS,EACT,KAAK,EACL,gBAAgB,GAKjB;QACC,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,2BAA2B;YACrC,IAAI,EAAE,sBAAc;YACpB,KAAK,EAAE;gBACL,GAAG,kCAAkC,EAAE;gBACvC,GAAG,KAAK;aACT;SACF,CAAC,CAAC;QAhCL;;WAEG;QACM,wDAA4C;QA+BnD,uBAAA,IAAI,yCAAqB,gBAAgB,MAAA,CAAC;QAE1C,IAAI,CAAC,eAAe,CAAC,qBAAqB,CACxC,GAAG,sBAAc,kBAAkB,EACnC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAChC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAC5E,MAAM,iBAAiB,GACrB,MAAM,uBAAA,IAAI,6CAAkB,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,GAAG;gBAClC,GAAG,iBAAiB;gBACpB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACtC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AA9DD,kDA8DC","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  RestrictedMessenger,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Hex } from '@metamask/utils';\n\nimport type { AbstractGasPricesService } from './gas-prices-service/abstract-gas-prices-service';\nimport type { NetworkControllerGetStateAction } from './network-controller-types';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link GasPricesController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'GasPricesController';\n\n// === STATE ===\n\n/**\n * The collection of gas price data fetched periodically.\n */\ntype GasPrices = {\n  /**\n   * The total estimated gas in the \"low\" bucket.\n   */\n  low: number;\n  /**\n   * The total estimated gas in the \"average\" bucket.\n   */\n  average: number;\n  /**\n   * The total estimated gas in the \"high\" bucket.\n   */\n  high: number;\n  /**\n   * The date/time (in ISO-8601 format) when prices were fetched.\n   */\n  fetchedDate: string;\n};\n\n/**\n * Describes the shape of the state object for {@link GasPricesController}.\n */\nexport type GasPricesControllerState = {\n  /**\n   * The registry of pet names, categorized by chain ID first and address\n   * second.\n   */\n  gasPricesByChainId: {\n    [chainId: Hex]: GasPrices;\n  };\n};\n\n/**\n * The metadata for each property in {@link GasPricesControllerState}.\n */\nconst gasPricesControllerMetadata = {\n  gasPricesByChainId: {\n    persist: true,\n    anonymous: false,\n  },\n} satisfies StateMetadata<GasPricesControllerState>;\n\n// === MESSENGER ===\n\n/**\n * The action which can be used to retrieve the state of the\n * {@link GasPricesController}.\n */\nexport type GasPricesControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  GasPricesControllerState\n>;\n\n/**\n * The action which can be used to update gas prices.\n */\nexport type GasPricesControllerUpdateGasPricesAction = {\n  type: `${typeof controllerName}:updateGasPrices`;\n  handler: GasPricesController['updateGasPrices'];\n};\n\n/**\n * All actions that {@link GasPricesController} registers, to be called\n * externally.\n */\nexport type GasPricesControllerActions =\n  | GasPricesControllerGetStateAction\n  | GasPricesControllerUpdateGasPricesAction;\n\n/**\n * All actions that {@link GasPricesController} calls internally.\n */\ntype AllowedActions = NetworkControllerGetStateAction;\n\n/**\n * The event that {@link GasPricesController} publishes when updating state.\n */\nexport type GasPricesControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  GasPricesControllerState\n>;\n\n/**\n * All events that {@link GasPricesController} publishes, to be subscribed to\n * externally.\n */\nexport type GasPricesControllerEvents = GasPricesControllerStateChangeEvent;\n\n/**\n * All events that {@link GasPricesController} subscribes to internally.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger which is restricted to actions and events accessed by\n * {@link GasPricesController}.\n */\nexport type GasPricesControllerMessenger = RestrictedMessenger<\n  typeof controllerName,\n  GasPricesControllerActions | AllowedActions,\n  GasPricesControllerEvents | AllowedEvents,\n  AllowedActions['type'],\n  AllowedEvents['type']\n>;\n\n/**\n * Constructs the default {@link GasPricesController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link GasPricesController} state.\n */\nexport function getDefaultGasPricesControllerState(): GasPricesControllerState {\n  return {\n    gasPricesByChainId: {},\n  };\n}\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * `GasPricesController` fetches and persists gas prices for various chains.\n *\n * @example\n *\n * ``` ts\n * import { Messenger } from '@metamask/base-controller';\n * import {\n *   GasPricesController,\n *   GasPricesService\n * } from '@metamask/example-controllers';\n * import type {\n *   GasPricesControllerActions,\n *   GasPricesControllerEvents\n * } from '@metamask/example-controllers';\n * import type { NetworkControllerGetStateAction } from '@metamask/network-controller';\n *\n * // Assuming that you're using this in the browser\n * const gasPricesService = new GasPricesService({ fetch });\n * const rootMessenger = new Messenger<\n *  GasPricesControllerActions | NetworkControllerGetStateAction,\n *  GasPricesControllerEvents\n * >();\n * const gasPricesMessenger = rootMessenger.getRestricted({\n *   name: 'GasPricesController',\n *   allowedActions: ['NetworkController:getState'],\n *   allowedEvents: [],\n * });\n * const gasPricesController = new GasPricesController({\n *   messenger: gasPricesMessenger,\n *   gasPricesService,\n * });\n *\n * // Assuming that `NetworkController:getState` returns an object with a\n * // `chainId` of `0x42`...\n * await gasPricesController.updateGasPrices();\n * gasPricesController.state.gasPricesByChainId\n * // => { '0x42': { low: 5, average: 10, high: 15, fetchedDate: '2024-01-02T00:00:00.000Z' } }\n * ```\n */\nexport class GasPricesController extends BaseController<\n  typeof controllerName,\n  GasPricesControllerState,\n  GasPricesControllerMessenger\n> {\n  /**\n   * The service object that is used to obtain gas prices.\n   */\n  readonly #gasPricesService: AbstractGasPricesService;\n\n  /**\n   * Constructs a new {@link GasPricesController}.\n   *\n   * @param args - The arguments to the controller.\n   * @param args.messenger - The messenger suited for this controller.\n   * @param args.state - The desired state with which to initialize this\n   * controller. Missing properties will be filled in with defaults.\n   * @param args.gasPricesService - The service object that will be used to\n   * obtain gas prices.\n   */\n  constructor({\n    messenger,\n    state,\n    gasPricesService,\n  }: {\n    messenger: GasPricesControllerMessenger;\n    state?: Partial<GasPricesControllerState>;\n    gasPricesService: AbstractGasPricesService;\n  }) {\n    super({\n      messenger,\n      metadata: gasPricesControllerMetadata,\n      name: controllerName,\n      state: {\n        ...getDefaultGasPricesControllerState(),\n        ...state,\n      },\n    });\n\n    this.#gasPricesService = gasPricesService;\n\n    this.messagingSystem.registerActionHandler(\n      `${controllerName}:updateGasPrices`,\n      this.updateGasPrices.bind(this),\n    );\n  }\n\n  /**\n   * Fetches the latest gas prices for the current chain, persisting them to\n   * state.\n   */\n  async updateGasPrices() {\n    const { chainId } = this.messagingSystem.call('NetworkController:getState');\n    const gasPricesResponse =\n      await this.#gasPricesService.fetchGasPrices(chainId);\n    this.update((state) => {\n      state.gasPricesByChainId[chainId] = {\n        ...gasPricesResponse,\n        fetchedDate: new Date().toISOString(),\n      };\n    });\n  }\n}\n"]}

package/dist/types/gas-prices-controller.d.cts

@@ -0,0 +1,157 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent, RestrictedMessenger } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Hex } from "@metamask/utils";
+import type { AbstractGasPricesService } from "./gas-prices-service/abstract-gas-prices-service.cjs";
+import type { NetworkControllerGetStateAction } from "./network-controller-types.cjs";
+/**
+ * The name of the {@link GasPricesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "GasPricesController";
+/**
+ * The collection of gas price data fetched periodically.
+ */
+type GasPrices = {
+    /**
+     * The total estimated gas in the "low" bucket.
+     */
+    low: number;
+    /**
+     * The total estimated gas in the "average" bucket.
+     */
+    average: number;
+    /**
+     * The total estimated gas in the "high" bucket.
+     */
+    high: number;
+    /**
+     * The date/time (in ISO-8601 format) when prices were fetched.
+     */
+    fetchedDate: string;
+};
+/**
+ * Describes the shape of the state object for {@link GasPricesController}.
+ */
+export type GasPricesControllerState = {
+    /**
+     * The registry of pet names, categorized by chain ID first and address
+     * second.
+     */
+    gasPricesByChainId: {
+        [chainId: Hex]: GasPrices;
+    };
+};
+/**
+ * The action which can be used to retrieve the state of the
+ * {@link GasPricesController}.
+ */
+export type GasPricesControllerGetStateAction = ControllerGetStateAction<typeof controllerName, GasPricesControllerState>;
+/**
+ * The action which can be used to update gas prices.
+ */
+export type GasPricesControllerUpdateGasPricesAction = {
+    type: `${typeof controllerName}:updateGasPrices`;
+    handler: GasPricesController['updateGasPrices'];
+};
+/**
+ * All actions that {@link GasPricesController} registers, to be called
+ * externally.
+ */
+export type GasPricesControllerActions = GasPricesControllerGetStateAction | GasPricesControllerUpdateGasPricesAction;
+/**
+ * All actions that {@link GasPricesController} calls internally.
+ */
+type AllowedActions = NetworkControllerGetStateAction;
+/**
+ * The event that {@link GasPricesController} publishes when updating state.
+ */
+export type GasPricesControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, GasPricesControllerState>;
+/**
+ * All events that {@link GasPricesController} publishes, to be subscribed to
+ * externally.
+ */
+export type GasPricesControllerEvents = GasPricesControllerStateChangeEvent;
+/**
+ * All events that {@link GasPricesController} subscribes to internally.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger which is restricted to actions and events accessed by
+ * {@link GasPricesController}.
+ */
+export type GasPricesControllerMessenger = RestrictedMessenger<typeof controllerName, GasPricesControllerActions | AllowedActions, GasPricesControllerEvents | AllowedEvents, AllowedActions['type'], AllowedEvents['type']>;
+/**
+ * Constructs the default {@link GasPricesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GasPricesController} state.
+ */
+export declare function getDefaultGasPricesControllerState(): GasPricesControllerState;
+/**
+ * `GasPricesController` fetches and persists gas prices for various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import {
+ *   GasPricesController,
+ *   GasPricesService
+ * } from '@metamask/example-controllers';
+ * import type {
+ *   GasPricesControllerActions,
+ *   GasPricesControllerEvents
+ * } from '@metamask/example-controllers';
+ * import type { NetworkControllerGetStateAction } from '@metamask/network-controller';
+ *
+ * // Assuming that you're using this in the browser
+ * const gasPricesService = new GasPricesService({ fetch });
+ * const rootMessenger = new Messenger<
+ *  GasPricesControllerActions | NetworkControllerGetStateAction,
+ *  GasPricesControllerEvents
+ * >();
+ * const gasPricesMessenger = rootMessenger.getRestricted({
+ *   name: 'GasPricesController',
+ *   allowedActions: ['NetworkController:getState'],
+ *   allowedEvents: [],
+ * });
+ * const gasPricesController = new GasPricesController({
+ *   messenger: gasPricesMessenger,
+ *   gasPricesService,
+ * });
+ *
+ * // Assuming that `NetworkController:getState` returns an object with a
+ * // `chainId` of `0x42`...
+ * await gasPricesController.updateGasPrices();
+ * gasPricesController.state.gasPricesByChainId
+ * // => { '0x42': { low: 5, average: 10, high: 15, fetchedDate: '2024-01-02T00:00:00.000Z' } }
+ * ```
+ */
+export declare class GasPricesController extends BaseController<typeof controllerName, GasPricesControllerState, GasPricesControllerMessenger> {
+    #private;
+    /**
+     * Constructs a new {@link GasPricesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     * @param args.gasPricesService - The service object that will be used to
+     * obtain gas prices.
+     */
+    constructor({ messenger, state, gasPricesService, }: {
+        messenger: GasPricesControllerMessenger;
+        state?: Partial<GasPricesControllerState>;
+        gasPricesService: AbstractGasPricesService;
+    });
+    /**
+     * Fetches the latest gas prices for the current chain, persisting them to
+     * state.
+     */
+    updateGasPrices(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=gas-prices-controller.d.cts.map

package/dist/types/gas-prices-controller.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas-prices-controller.d.cts","sourceRoot":"","sources":["../../src/gas-prices-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EAEpB,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,GAAG,EAAE,wBAAwB;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,6DAAyD;AACjG,OAAO,KAAK,EAAE,+BAA+B,EAAE,uCAAmC;AAIlF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAIpD;;GAEG;AACH,KAAK,SAAS,GAAG;IACf;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,kBAAkB,EAAE;QAClB,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,CAAC;KAC3B,CAAC;CACH,CAAC;AAcF;;;GAGG;AACH,MAAM,MAAM,iCAAiC,GAAG,wBAAwB,CACtE,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,GAAG,OAAO,cAAc,kBAAkB,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;CACjD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAClC,iCAAiC,GACjC,wCAAwC,CAAC;AAE7C;;GAEG;AACH,KAAK,cAAc,GAAG,+BAA+B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,0BAA0B,CAC1E,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,mCAAmC,CAAC;AAE5E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAC5D,OAAO,cAAc,EACrB,0BAA0B,GAAG,cAAc,EAC3C,yBAAyB,GAAG,aAAa,EACzC,cAAc,CAAC,MAAM,CAAC,EACtB,aAAa,CAAC,MAAM,CAAC,CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,IAAI,wBAAwB,CAI7E;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CACrD,OAAO,cAAc,EACrB,wBAAwB,EACxB,4BAA4B,CAC7B;;IAMC;;;;;;;;;OASG;gBACS,EACV,SAAS,EACT,KAAK,EACL,gBAAgB,GACjB,EAAE;QACD,SAAS,EAAE,4BAA4B,CAAC;QACxC,KAAK,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;QAC1C,gBAAgB,EAAE,wBAAwB,CAAC;KAC5C;IAmBD;;;OAGG;IACG,eAAe;CAWtB"}

package/dist/types/gas-prices-controller.d.mts

@@ -0,0 +1,157 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent, RestrictedMessenger } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Hex } from "@metamask/utils";
+import type { AbstractGasPricesService } from "./gas-prices-service/abstract-gas-prices-service.mjs";
+import type { NetworkControllerGetStateAction } from "./network-controller-types.mjs";
+/**
+ * The name of the {@link GasPricesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "GasPricesController";
+/**
+ * The collection of gas price data fetched periodically.
+ */
+type GasPrices = {
+    /**
+     * The total estimated gas in the "low" bucket.
+     */
+    low: number;
+    /**
+     * The total estimated gas in the "average" bucket.
+     */
+    average: number;
+    /**
+     * The total estimated gas in the "high" bucket.
+     */
+    high: number;
+    /**
+     * The date/time (in ISO-8601 format) when prices were fetched.
+     */
+    fetchedDate: string;
+};
+/**
+ * Describes the shape of the state object for {@link GasPricesController}.
+ */
+export type GasPricesControllerState = {
+    /**
+     * The registry of pet names, categorized by chain ID first and address
+     * second.
+     */
+    gasPricesByChainId: {
+        [chainId: Hex]: GasPrices;
+    };
+};
+/**
+ * The action which can be used to retrieve the state of the
+ * {@link GasPricesController}.
+ */
+export type GasPricesControllerGetStateAction = ControllerGetStateAction<typeof controllerName, GasPricesControllerState>;
+/**
+ * The action which can be used to update gas prices.
+ */
+export type GasPricesControllerUpdateGasPricesAction = {
+    type: `${typeof controllerName}:updateGasPrices`;
+    handler: GasPricesController['updateGasPrices'];
+};
+/**
+ * All actions that {@link GasPricesController} registers, to be called
+ * externally.
+ */
+export type GasPricesControllerActions = GasPricesControllerGetStateAction | GasPricesControllerUpdateGasPricesAction;
+/**
+ * All actions that {@link GasPricesController} calls internally.
+ */
+type AllowedActions = NetworkControllerGetStateAction;
+/**
+ * The event that {@link GasPricesController} publishes when updating state.
+ */
+export type GasPricesControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, GasPricesControllerState>;
+/**
+ * All events that {@link GasPricesController} publishes, to be subscribed to
+ * externally.
+ */
+export type GasPricesControllerEvents = GasPricesControllerStateChangeEvent;
+/**
+ * All events that {@link GasPricesController} subscribes to internally.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger which is restricted to actions and events accessed by
+ * {@link GasPricesController}.
+ */
+export type GasPricesControllerMessenger = RestrictedMessenger<typeof controllerName, GasPricesControllerActions | AllowedActions, GasPricesControllerEvents | AllowedEvents, AllowedActions['type'], AllowedEvents['type']>;
+/**
+ * Constructs the default {@link GasPricesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GasPricesController} state.
+ */
+export declare function getDefaultGasPricesControllerState(): GasPricesControllerState;
+/**
+ * `GasPricesController` fetches and persists gas prices for various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import {
+ *   GasPricesController,
+ *   GasPricesService
+ * } from '@metamask/example-controllers';
+ * import type {
+ *   GasPricesControllerActions,
+ *   GasPricesControllerEvents
+ * } from '@metamask/example-controllers';
+ * import type { NetworkControllerGetStateAction } from '@metamask/network-controller';
+ *
+ * // Assuming that you're using this in the browser
+ * const gasPricesService = new GasPricesService({ fetch });
+ * const rootMessenger = new Messenger<
+ *  GasPricesControllerActions | NetworkControllerGetStateAction,
+ *  GasPricesControllerEvents
+ * >();
+ * const gasPricesMessenger = rootMessenger.getRestricted({
+ *   name: 'GasPricesController',
+ *   allowedActions: ['NetworkController:getState'],
+ *   allowedEvents: [],
+ * });
+ * const gasPricesController = new GasPricesController({
+ *   messenger: gasPricesMessenger,
+ *   gasPricesService,
+ * });
+ *
+ * // Assuming that `NetworkController:getState` returns an object with a
+ * // `chainId` of `0x42`...
+ * await gasPricesController.updateGasPrices();
+ * gasPricesController.state.gasPricesByChainId
+ * // => { '0x42': { low: 5, average: 10, high: 15, fetchedDate: '2024-01-02T00:00:00.000Z' } }
+ * ```
+ */
+export declare class GasPricesController extends BaseController<typeof controllerName, GasPricesControllerState, GasPricesControllerMessenger> {
+    #private;
+    /**
+     * Constructs a new {@link GasPricesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     * @param args.gasPricesService - The service object that will be used to
+     * obtain gas prices.
+     */
+    constructor({ messenger, state, gasPricesService, }: {
+        messenger: GasPricesControllerMessenger;
+        state?: Partial<GasPricesControllerState>;
+        gasPricesService: AbstractGasPricesService;
+    });
+    /**
+     * Fetches the latest gas prices for the current chain, persisting them to
+     * state.
+     */
+    updateGasPrices(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=gas-prices-controller.d.mts.map

package/dist/types/gas-prices-controller.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas-prices-controller.d.mts","sourceRoot":"","sources":["../../src/gas-prices-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EAEpB,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,GAAG,EAAE,wBAAwB;AAE3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,6DAAyD;AACjG,OAAO,KAAK,EAAE,+BAA+B,EAAE,uCAAmC;AAIlF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAIpD;;GAEG;AACH,KAAK,SAAS,GAAG;IACf;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,kBAAkB,EAAE;QAClB,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS,CAAC;KAC3B,CAAC;CACH,CAAC;AAcF;;;GAGG;AACH,MAAM,MAAM,iCAAiC,GAAG,wBAAwB,CACtE,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,GAAG,OAAO,cAAc,kBAAkB,CAAC;IACjD,OAAO,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;CACjD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAClC,iCAAiC,GACjC,wCAAwC,CAAC;AAE7C;;GAEG;AACH,KAAK,cAAc,GAAG,+BAA+B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,0BAA0B,CAC1E,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,mCAAmC,CAAC;AAE5E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAC5D,OAAO,cAAc,EACrB,0BAA0B,GAAG,cAAc,EAC3C,yBAAyB,GAAG,aAAa,EACzC,cAAc,CAAC,MAAM,CAAC,EACtB,aAAa,CAAC,MAAM,CAAC,CACtB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,IAAI,wBAAwB,CAI7E;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CACrD,OAAO,cAAc,EACrB,wBAAwB,EACxB,4BAA4B,CAC7B;;IAMC;;;;;;;;;OASG;gBACS,EACV,SAAS,EACT,KAAK,EACL,gBAAgB,GACjB,EAAE;QACD,SAAS,EAAE,4BAA4B,CAAC;QACxC,KAAK,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;QAC1C,gBAAgB,EAAE,wBAAwB,CAAC;KAC5C;IAmBD;;;OAGG;IACG,eAAe;CAWtB"}

package/dist/types/gas-prices-controller.mjs

@@ -0,0 +1,128 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _GasPricesController_gasPricesService;
+import { BaseController } from "@metamask/base-controller";
+// === GENERAL ===
+/**
+ * The name of the {@link GasPricesController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export const controllerName = 'GasPricesController';
+/**
+ * The metadata for each property in {@link GasPricesControllerState}.
+ */
+const gasPricesControllerMetadata = {
+    gasPricesByChainId: {
+        persist: true,
+        anonymous: false,
+    },
+};
+/**
+ * Constructs the default {@link GasPricesController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GasPricesController} state.
+ */
+export function getDefaultGasPricesControllerState() {
+    return {
+        gasPricesByChainId: {},
+    };
+}
+// === CONTROLLER DEFINITION ===
+/**
+ * `GasPricesController` fetches and persists gas prices for various chains.
+ *
+ * @example
+ *
+ * ``` ts
+ * import { Messenger } from '@metamask/base-controller';
+ * import {
+ *   GasPricesController,
+ *   GasPricesService
+ * } from '@metamask/example-controllers';
+ * import type {
+ *   GasPricesControllerActions,
+ *   GasPricesControllerEvents
+ * } from '@metamask/example-controllers';
+ * import type { NetworkControllerGetStateAction } from '@metamask/network-controller';
+ *
+ * // Assuming that you're using this in the browser
+ * const gasPricesService = new GasPricesService({ fetch });
+ * const rootMessenger = new Messenger<
+ *  GasPricesControllerActions | NetworkControllerGetStateAction,
+ *  GasPricesControllerEvents
+ * >();
+ * const gasPricesMessenger = rootMessenger.getRestricted({
+ *   name: 'GasPricesController',
+ *   allowedActions: ['NetworkController:getState'],
+ *   allowedEvents: [],
+ * });
+ * const gasPricesController = new GasPricesController({
+ *   messenger: gasPricesMessenger,
+ *   gasPricesService,
+ * });
+ *
+ * // Assuming that `NetworkController:getState` returns an object with a
+ * // `chainId` of `0x42`...
+ * await gasPricesController.updateGasPrices();
+ * gasPricesController.state.gasPricesByChainId
+ * // => { '0x42': { low: 5, average: 10, high: 15, fetchedDate: '2024-01-02T00:00:00.000Z' } }
+ * ```
+ */
+export class GasPricesController extends BaseController {
+    /**
+     * Constructs a new {@link GasPricesController}.
+     *
+     * @param args - The arguments to the controller.
+     * @param args.messenger - The messenger suited for this controller.
+     * @param args.state - The desired state with which to initialize this
+     * controller. Missing properties will be filled in with defaults.
+     * @param args.gasPricesService - The service object that will be used to
+     * obtain gas prices.
+     */
+    constructor({ messenger, state, gasPricesService, }) {
+        super({
+            messenger,
+            metadata: gasPricesControllerMetadata,
+            name: controllerName,
+            state: {
+                ...getDefaultGasPricesControllerState(),
+                ...state,
+            },
+        });
+        /**
+         * The service object that is used to obtain gas prices.
+         */
+        _GasPricesController_gasPricesService.set(this, void 0);
+        __classPrivateFieldSet(this, _GasPricesController_gasPricesService, gasPricesService, "f");
+        this.messagingSystem.registerActionHandler(`${controllerName}:updateGasPrices`, this.updateGasPrices.bind(this));
+    }
+    /**
+     * Fetches the latest gas prices for the current chain, persisting them to
+     * state.
+     */
+    async updateGasPrices() {
+        const { chainId } = this.messagingSystem.call('NetworkController:getState');
+        const gasPricesResponse = await __classPrivateFieldGet(this, _GasPricesController_gasPricesService, "f").fetchGasPrices(chainId);
+        this.update((state) => {
+            state.gasPricesByChainId[chainId] = {
+                ...gasPricesResponse,
+                fetchedDate: new Date().toISOString(),
+            };
+        });
+    }
+}
+_GasPricesController_gasPricesService = new WeakMap();
+//# sourceMappingURL=gas-prices-controller.mjs.map