feat: add token minimum balance calculation and response type (#7269)

## Explanation

<!--
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?
-->

This PR
- Add `minBillingCyclesForBalance` to `ProductPrice` type
- Add `getTokenMinimumBalanceAmount` method to `SubscriptionController`

## 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

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Add `minBillingCyclesForBalance` and `getTokenMinimumBalanceAmount` to
compute minimum token balance, with tests and minor docs updates.
> 
> - **Subscription Controller**:
> - Add `#getSubscriptionBalanceAmount(price)` and public
`getTokenMinimumBalanceAmount(price, tokenPaymentInfo)` to compute
minimum token balance using conversion rates; throws on missing rate.
>   - Clarify approval amount JSDoc for `#getSubscriptionPriceAmount`.
> - **Types**:
>   - Extend `ProductPrice` with `minBillingCyclesForBalance`.
> - **Tests**:
>   - Update mock pricing to include `minBillingCyclesForBalance`.
> - Add unit tests for `getTokenMinimumBalanceAmount`, including error
on missing conversion rate.
>   - Adjust existing tests to pass new pricing field where applicable.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
6e482ee. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: tuna1207

packages/subscription-controller/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added `minBillingCyclesForBalance` property to `ProductPrice` type ([#7269](https://github.com/MetaMask/core/pull/7269))
+- Added `getTokenMinimumBalanceAmount` method to `SubscriptonController` ([#7269](https://github.com/MetaMask/core/pull/7269))
+
 ### Changed
 
 - Bump `@metamask/transaction-controller` from `^62.3.0` to `^62.3.1` ([#7257](https://github.com/MetaMask/core/pull/7257))

packages/subscription-controller/src/SubscriptionController.test.ts

@@ -94,6 +94,7 @@ const MOCK_PRODUCT_PRICE: ProductPricing = {
       unitDecimals: 2,
       trialPeriodDays: 0,
       minBillingCycles: 12,
+      minBillingCyclesForBalance: 1,
     },
     {
       interval: 'year',
@@ -102,6 +103,7 @@ const MOCK_PRODUCT_PRICE: ProductPricing = {
       currency: 'usd',
       trialPeriodDays: 14,
       minBillingCycles: 1,
+      minBillingCyclesForBalance: 1,
     },
   ],
 };
@@ -1114,6 +1116,7 @@ describe('SubscriptionController', () => {
                       unitDecimals: 18,
                       trialPeriodDays: 0,
                       minBillingCycles: 1,
+                      minBillingCyclesForBalance: 1,
                     },
                   ],
                 },
@@ -1258,6 +1261,45 @@ describe('SubscriptionController', () => {
     });
   });
 
+  describe('getTokenMinimumBalanceAmount', () => {
+    it('returns correct minimum balance amount for token', async () => {
+      await withController(async ({ controller }) => {
+        const [price] = MOCK_PRODUCT_PRICE.prices;
+        const { chains } = MOCK_PRICING_PAYMENT_METHOD;
+        if (!chains || chains.length === 0) {
+          throw new Error('Mock chains not found');
+        }
+        const [tokenPaymentInfo] = chains[0].tokens;
+
+        const result = controller.getTokenMinimumBalanceAmount(
+          price,
+          tokenPaymentInfo,
+        );
+
+        expect(result).toBe('9000000000000000000');
+      });
+    });
+
+    it('throws when conversion rate not found', async () => {
+      await withController(async ({ controller }) => {
+        const price = MOCK_PRODUCT_PRICE.prices[0];
+        const tokenPaymentInfoWithoutRate = {
+          address: '0xtoken' as const,
+          decimals: 18,
+          symbol: 'USDT',
+          conversionRate: {} as { usd: string },
+        };
+
+        expect(() =>
+          controller.getTokenMinimumBalanceAmount(
+            price,
+            tokenPaymentInfoWithoutRate,
+          ),
+        ).toThrow('Conversion rate not found');
+      });
+    });
+  });
+
   describe('triggerAuthTokenRefresh', () => {
     it('should trigger auth token refresh', async () => {
       await withController(async ({ controller, mockPerformSignOut }) => {

packages/subscription-controller/src/SubscriptionController.ts

@@ -757,7 +757,7 @@ export class SubscriptionController extends StaticIntervalPollingController()<
   }
 
   /**
-   * Calculate total subscription price amount from price info
+   * Calculate total subscription price amount (approval amount) from price info
    * e.g: $8 per month * 12 months min billing cycles = $96
    *
    * @param price - The price info
@@ -772,6 +772,21 @@ export class SubscriptionController extends StaticIntervalPollingController()<
     return amount;
   }
 
+  /**
+   * Calculate minimum subscription balance amount from price info
+   *
+   * @param price - The price info
+   * @returns The balance amount
+   */
+  #getSubscriptionBalanceAmount(price: ProductPrice) {
+    // no need to use BigInt since max unitDecimals are always 2 for price
+    const amount = new BigNumber(price.unitAmount)
+      .div(10 ** price.unitDecimals)
+      .multipliedBy(price.minBillingCyclesForBalance)
+      .toString();
+    return amount;
+  }
+
   /**
    * Calculate token approve amount from price info
    *
@@ -800,6 +815,35 @@ export class SubscriptionController extends StaticIntervalPollingController()<
     return tokenAmount.toFixed(0);
   }
 
+  /**
+   * Calculate token minimum balance amount from price info
+   *
+   * @param price - The price info
+   * @param tokenPaymentInfo - The token price info
+   * @returns The token balance amount
+   */
+  getTokenMinimumBalanceAmount(
+    price: ProductPrice,
+    tokenPaymentInfo: TokenPaymentInfo,
+  ): string {
+    const conversionRate =
+      tokenPaymentInfo.conversionRate[
+        price.currency as keyof typeof tokenPaymentInfo.conversionRate
+      ];
+    if (!conversionRate) {
+      throw new Error('Conversion rate not found');
+    }
+    const balanceAmount = new BigNumber(
+      this.#getSubscriptionBalanceAmount(price),
+    );
+
+    const tokenDecimal = new BigNumber(10).pow(tokenPaymentInfo.decimals);
+    const tokenAmount = balanceAmount
+      .multipliedBy(tokenDecimal)
+      .div(conversionRate);
+    return tokenAmount.toFixed(0);
+  }
+
   /**
    * Triggers an access token refresh.
    */

packages/subscription-controller/src/types.ts

@@ -171,7 +171,10 @@ export type ProductPrice = {
   /** only usd for now */
   currency: Currency;
   trialPeriodDays: number;
+  /** min billing cycles for approval */
   minBillingCycles: number;
+  /** min billing cycles for account balance check */
+  minBillingCyclesForBalance: number;
 };
 
 export type ProductPricing = {