refactor: add confirmation refresher (#74)

## Explanation

This PR refactors confirmation-dialog background updates into a single
“confirmation context refresh” cronjob that orchestrates one or more
pluggable refreshers (starting with token spot prices), and wires it
into the confirmation UX controller and snap cronjob dispatch.

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

Author: stanleyyconsensys

packages/snap/src/context.ts

@@ -16,7 +16,10 @@ import { OnAmountInputHandler } from './handlers/clientRequest/onAmountInput';
 import { SignAndSendTransactionHandler } from './handlers/clientRequest/signAndSendTransaction';
 import type { ICronjobRequestHandler } from './handlers/cronjob/api';
 import { BackgroundEventMethod } from './handlers/cronjob/api';
-import { RefreshConfirmationPricesHandler } from './handlers/cronjob/refreshConfirmationPrices';
+import {
+  ConfirmationPriceRefresher,
+  RefreshConfirmationContextHandler,
+} from './handlers/cronjob/refreshConfirmationContext';
 import { SyncAccountsHandler } from './handlers/cronjob/syncAccounts';
 import { TrackTransactionHandler } from './handlers/cronjob/trackTransaction';
 import type { IKeyringRequestHandler } from './handlers/keyring';
@@ -161,13 +164,19 @@ const userInputHandler = new UserInputHandler({
 });
 
 /** ------------------------------ Cronjob Handler ------------------------------ */
-
-const refreshConfirmationPricesHandler = new RefreshConfirmationPricesHandler({
+const confirmationPriceRefresher = new ConfirmationPriceRefresher({
   logger,
   priceService,
-  confirmationUIController,
 });
 
+const refreshConfirmationContextHandler = new RefreshConfirmationContextHandler(
+  {
+    logger,
+    confirmationUIController,
+    refreshers: [confirmationPriceRefresher],
+  },
+);
+
 const trackTransactionHandler = new TrackTransactionHandler({
   logger,
   networkService,
@@ -186,8 +195,8 @@ const cronjobMethodHandlers: Record<
   BackgroundEventMethod,
   ICronjobRequestHandler
 > = {
-  [BackgroundEventMethod.RefreshConfirmationPrices]:
-    refreshConfirmationPricesHandler,
+  [BackgroundEventMethod.RefreshConfirmationContext]:
+    refreshConfirmationContextHandler,
   [BackgroundEventMethod.TrackTransaction]: trackTransactionHandler,
   [BackgroundEventMethod.SynchronizeAccounts]: syncAccountsHandler,
 };

packages/snap/src/handlers/cronjob/api.test.ts

@@ -4,7 +4,7 @@ import {
   BackgroundEventMethod,
   BackgroundEventMethodStruct,
   CronjobJsonRpcRequestStruct,
-  RefreshConfirmationPricesJsonRpcRequestStruct,
+  RefreshConfirmationContextJsonRpcRequestStruct,
   SyncAccountJsonRpcRequestStruct,
   SyncAccountParamsStruct,
   TrackTransactionJsonRpcRequestStruct,
@@ -126,25 +126,27 @@ describe('Cronjob API structs', () => {
     });
   });
 
-  describe('RefreshConfirmationPricesJsonRpcRequestStruct', () => {
-    it('accepts refresh confirmation prices requests', () => {
+  describe('RefreshConfirmationContextJsonRpcRequestStruct', () => {
+    it('accepts refresh confirmation context requests', () => {
       const value = {
         ...jsonRpcBase,
-        method: BackgroundEventMethod.RefreshConfirmationPrices,
+        method: BackgroundEventMethod.RefreshConfirmationContext,
         params: {
           scope: KnownCaip2ChainId.Mainnet,
           interfaceId: 'interface-id',
           interfaceKey: ConfirmationInterfaceKey.SignTransaction,
+          refresherKeys: ['prices'],
         },
       };
-      assert(value, RefreshConfirmationPricesJsonRpcRequestStruct);
+      assert(value, RefreshConfirmationContextJsonRpcRequestStruct);
       expect(value).toStrictEqual({
         ...jsonRpcBase,
-        method: BackgroundEventMethod.RefreshConfirmationPrices,
+        method: BackgroundEventMethod.RefreshConfirmationContext,
         params: {
           scope: KnownCaip2ChainId.Mainnet,
           interfaceId: 'interface-id',
           interfaceKey: ConfirmationInterfaceKey.SignTransaction,
+          refresherKeys: ['prices'],
         },
       });
     });

packages/snap/src/handlers/cronjob/api.ts

@@ -21,6 +21,7 @@ import {
   KnownCaip2ChainIdStruct,
   UuidStruct,
 } from '../../api';
+import { ConfirmationContextRefresherKeyStruct } from './refreshConfirmationContext/api';
 import { ConfirmationInterfaceKeyStruct } from '../../ui/confirmation/api';
 
 /**
@@ -32,20 +33,30 @@ export type ICronjobRequestHandler = {
 
 export enum BackgroundEventMethod {
   SynchronizeAccounts = 'synchronizeAccounts',
-  RefreshConfirmationPrices = 'refreshConfirmationPrices',
   TrackTransaction = 'trackTransaction',
+  RefreshConfirmationContext = 'refreshConfirmationContext',
 }
 
 export const BackgroundEventMethodStruct = enums(
   Object.values(BackgroundEventMethod),
 );
 
-export const RefreshConfirmationPricesParamsStruct = type({
+export const RefreshConfirmationContextParamsStruct = type({
   scope: KnownCaip2ChainIdStruct,
   interfaceId: nonempty(string()),
   interfaceKey: ConfirmationInterfaceKeyStruct,
+  /** Refresher keys to run; omitted keys are skipped for this cycle. */
+  refresherKeys: nonempty(array(ConfirmationContextRefresherKeyStruct)),
 });
 
+export const RefreshConfirmationContextJsonRpcRequestStruct = assign(
+  JsonRpcRequestStruct,
+  object({
+    method: literal(BackgroundEventMethod.RefreshConfirmationContext),
+    params: RefreshConfirmationContextParamsStruct,
+  }),
+);
+
 export const TrackTransactionParamsStruct = type({
   txId: nonempty(string()),
   scope: KnownCaip2ChainIdStruct,
@@ -61,14 +72,6 @@ export const SyncAccountParamsStruct = object({
   ),
 });
 
-export const RefreshConfirmationPricesJsonRpcRequestStruct = assign(
-  JsonRpcRequestStruct,
-  object({
-    method: literal(BackgroundEventMethod.RefreshConfirmationPrices),
-    params: RefreshConfirmationPricesParamsStruct,
-  }),
-);
-
 export const TrackTransactionJsonRpcRequestStruct = assign(
   JsonRpcRequestStruct,
   object({
@@ -93,14 +96,6 @@ export const CronjobJsonRpcRequestStruct = object({
 
 export type CronjobJsonRpcRequest = Infer<typeof CronjobJsonRpcRequestStruct>;
 
-export type RefreshConfirmationPricesJsonRpcRequest = Infer<
-  typeof RefreshConfirmationPricesJsonRpcRequestStruct
->;
-
-export type RefreshConfirmationPricesParams = Infer<
-  typeof RefreshConfirmationPricesParamsStruct
->;
-
 export type TrackTransactionJsonRpcRequest = Infer<
   typeof TrackTransactionJsonRpcRequestStruct
 >;
@@ -112,3 +107,11 @@ export type SyncAccountJsonRpcRequest = Infer<
 >;
 
 export type SyncAccountParams = Infer<typeof SyncAccountParamsStruct>;
+
+export type RefreshConfirmationContextJsonRpcRequest = Infer<
+  typeof RefreshConfirmationContextJsonRpcRequestStruct
+>;
+
+export type RefreshConfirmationContextParams = Infer<
+  typeof RefreshConfirmationContextParamsStruct
+>;

packages/snap/src/handlers/cronjob/refreshConfirmationContext/__fixtures__/context.fixtures.ts

@@ -0,0 +1,43 @@
+import { KnownCaip2ChainId } from '../../../../api';
+import {
+  ConfirmationInterfaceKey,
+  type ContextWithPrices,
+  FetchStatus,
+} from '../../../../ui/confirmation/api';
+import { getSlip44AssetId } from '../../../../utils';
+import type { RefreshConfirmationContextParams } from '../../api';
+import {
+  ConfirmationContextRefresherKey,
+  type ConfirmationDataContext,
+} from '../api';
+
+const scope = KnownCaip2ChainId.Testnet;
+const nativeAssetId = getSlip44AssetId(scope);
+
+export const confirmationContextRequestParams: RefreshConfirmationContextParams =
+  {
+    scope,
+    interfaceId: 'interface-id-1',
+    interfaceKey: ConfirmationInterfaceKey.SignTransaction,
+    refresherKeys: [ConfirmationContextRefresherKey.Prices],
+  };
+
+/**
+ * Builds a valid confirmation refresh context for tests.
+ *
+ * @param overrides - Partial fields to override on the default context.
+ * @returns A context that satisfies {@link ContextWithPricesStruct}.
+ */
+export function createConfirmationDataContext(
+  overrides: Partial<ConfirmationDataContext> = {},
+): ConfirmationDataContext {
+  return {
+    tokenPrices: {
+      [nativeAssetId]: null,
+    } as ContextWithPrices['tokenPrices'],
+    tokenPricesFetchStatus: FetchStatus.Fetching,
+    currency: 'usd',
+    preferences: { useExternalPricingData: true },
+    ...overrides,
+  };
+}

packages/snap/src/handlers/cronjob/refreshConfirmationContext/api.ts

@@ -0,0 +1,65 @@
+import { enums } from '@metamask/superstruct';
+import type { Json } from '@metamask/utils';
+
+import type { ContextWithPrices } from '../../../ui/confirmation/api';
+
+/** Identifies which confirmation context refreshers to run for a cron cycle. */
+export enum ConfirmationContextRefresherKey {
+  Prices = 'prices',
+  /** TODO: Reserved for security scan; wire in context when implemented. */
+  Scan = 'scan',
+}
+
+export const ConfirmationContextRefresherKeyStruct = enums(
+  Object.values(ConfirmationContextRefresherKey),
+);
+
+/**
+ * Context the handler passes to refreshers.
+ */
+export type ConfirmationDataContext = Record<string, Json> & ContextWithPrices;
+
+/** Outcome of one refresher cycle. `null` means no work was needed. */
+export type ConfirmationContextRefreshResult = {
+  result: Record<string, Json>;
+  reschedule: boolean;
+} | null;
+
+/**
+ * Contract for a single background data source (prices, security scan, …).
+ */
+export type IConfirmationContextRefresher = {
+  /** Stable id used in cron params to select this refresher. */
+  readonly key: ConfirmationContextRefresherKey;
+
+  /**
+   * Returns whether this cycle should call.
+   * When false, the handler uses {@link IConfirmationContextRefresher.recoveryResult} instead.
+   */
+  shouldFetch: (ctx: ConfirmationDataContext) => boolean;
+
+  /**
+   * Patch applied when {@link IConfirmationContextRefresher.shouldFetch} is false
+   * (e.g. clear a stuck loading state). Return `null` when the context is already settled.
+   */
+  recoveryResult: (
+    ctx: ConfirmationDataContext,
+  ) => ConfirmationContextRefreshResult;
+
+  /**
+   * Fetches fresh data when {@link IConfirmationContextRefresher.shouldFetch} is true.
+   */
+  refresh: (
+    ctx: ConfirmationDataContext,
+  ) => Promise<ConfirmationContextRefreshResult>;
+
+  /**
+   * Returns false when this refresher cannot safely read `ctx` (missing or
+   * malformed fields). Only enabled refreshers (by key) are validated and run.
+   */
+  isValidContext: (ctx: Record<string, Json>) => boolean;
+};
+
+/** Composed refreshers passed into the confirmation context handler. */
+export type ConfirmationContextRefreshers =
+  readonly IConfirmationContextRefresher[];