fix: use current circulating STX tokens for stx_supply endpoint, year 2050 estimate in new field

Author: zone117x

src/api/routes/stx-supply.ts

@@ -1,5 +1,5 @@
 import BigNumber from 'bignumber.js';
-import { microStxToStx, STACKS_DECIMAL_PLACES, TOTAL_STACKS } from '../../helpers';
+import { microStxToStx, STACKS_DECIMAL_PLACES, TOTAL_STACKS_YEAR_2050 } from '../../helpers';
 import { handleChainTipCache } from '../controllers/cache-controller';
 
 import { FastifyPluginAsync } from 'fastify';
@@ -23,18 +23,23 @@ export const StxSupplyRoutes: FastifyPluginAsync<
   ): Promise<{
     unlockedPercent: string;
     totalStx: string;
+    totalStxYear2050: string;
     unlockedStx: string;
     blockHeight: number;
   }> {
     const { stx: unlockedSupply, blockHeight } = await fastify.db.getUnlockedStxSupply(args);
-    const totalMicroStx = new BigNumber(TOTAL_STACKS).shiftedBy(STACKS_DECIMAL_PLACES);
+    const totalMicroStx = unlockedSupply;
+    const totalMicroStxYear2050 = new BigNumber(TOTAL_STACKS_YEAR_2050).shiftedBy(
+      STACKS_DECIMAL_PLACES
+    );
     const unlockedPercent = new BigNumber(unlockedSupply.toString())
-      .div(totalMicroStx)
+      .div(new BigNumber(totalMicroStx.toString()))
       .times(100)
       .toFixed(2);
     return {
       unlockedPercent,
       totalStx: microStxToStx(totalMicroStx),
+      totalStxYear2050: microStxToStx(totalMicroStxYear2050),
       unlockedStx: microStxToStx(unlockedSupply),
       blockHeight: blockHeight,
     };
@@ -47,8 +52,7 @@ export const StxSupplyRoutes: FastifyPluginAsync<
       schema: {
         operationId: 'get_stx_supply',
         summary: 'Get total and unlocked STX supply',
-        description: `Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/understand-stacks/stacking).
-        **Note:** This uses the estimated future total supply for the year 2050.`,
+        description: `Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/understand-stacks/stacking).`,
         tags: ['Info'],
         querystring: Type.Object({
           height: Type.Optional(
@@ -70,7 +74,11 @@ export const StxSupplyRoutes: FastifyPluginAsync<
                   'String quoted decimal number of the percentage of STX that have unlocked',
               }),
               total_stx: Type.String({
-                description: 'String quoted decimal number of the total possible number of STX',
+                description: 'String quoted decimal number of the total circulating number of STX',
+              }),
+              total_stx_year_2050: Type.String({
+                description:
+                  'The Stacks cryptocurrency has a predefined future supply that reaches approx 1,818M STX by year 2050',
               }),
               unlocked_stx: Type.String({
                 description:
@@ -98,6 +106,7 @@ export const StxSupplyRoutes: FastifyPluginAsync<
       await reply.send({
         unlocked_percent: supply.unlockedPercent,
         total_stx: supply.totalStx,
+        total_stx_year_2050: supply.totalStxYear2050,
         unlocked_stx: supply.unlockedStx,
         block_height: supply.blockHeight,
       });
@@ -111,8 +120,7 @@ export const StxSupplyRoutes: FastifyPluginAsync<
       schema: {
         operationId: 'get_stx_supply_total_supply_plain',
         summary: 'Get total STX supply in plain text format',
-        description: `Retrieves the total supply for STX tokens as plain text.
-        **Note:** this uses the estimated future total supply for the year 2050.`,
+        description: `Retrieves the total circulating STX token supply as plain text.`,
         tags: ['Info'],
         response: {
           200: {
@@ -165,8 +173,7 @@ export const StxSupplyRoutes: FastifyPluginAsync<
         operationId: 'get_total_stx_supply_legacy_format',
         summary:
           'Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API)',
-        description: `Retrieves total supply of STX tokens including those currently in circulation that have been unlocked.
-        **Note:** this uses the estimated future total supply for the year 2050.`,
+        description: `Retrieves total supply of STX tokens including those currently in circulation that have been unlocked.`,
         tags: ['Info'],
         querystring: Type.Object({
           height: Type.Optional(
@@ -188,11 +195,19 @@ export const StxSupplyRoutes: FastifyPluginAsync<
                   'String quoted decimal number of the percentage of STX that have unlocked',
               }),
               totalStacks: Type.String({
-                description: 'String quoted decimal number of the total possible number of STX',
+                description: 'String quoted decimal number of the total circulating number of STX',
               }),
               totalStacksFormatted: Type.String({
                 description: 'Same as `totalStacks` but formatted with comma thousands separators',
               }),
+              totalStacksYear2050: Type.String({
+                description:
+                  'The Stacks cryptocurrency has a predefined future supply that reaches approx 1,818M STX by year 2050',
+              }),
+              totalStacksYear2050Formatted: Type.String({
+                description:
+                  'Same as `totalStacksYear2050` but formatted with comma thousands separators',
+              }),
               unlockedSupply: Type.String({
                 description:
                   'String quoted decimal number of the STX that have been mined or unlocked',
@@ -224,6 +239,11 @@ export const StxSupplyRoutes: FastifyPluginAsync<
         unlockedPercent: supply.unlockedPercent,
         totalStacks: supply.totalStx,
         totalStacksFormatted: new BigNumber(supply.totalStx).toFormat(STACKS_DECIMAL_PLACES, 8),
+        totalStacksYear2050: supply.totalStxYear2050,
+        totalStacksYear2050Formatted: new BigNumber(supply.totalStxYear2050).toFormat(
+          STACKS_DECIMAL_PLACES,
+          8
+        ),
         unlockedSupply: supply.unlockedStx,
         unlockedSupplyFormatted: new BigNumber(supply.unlockedStx).toFormat(
           STACKS_DECIMAL_PLACES,

src/helpers.ts

@@ -149,7 +149,7 @@ export function formatMapToObject<TKey extends string, TValue, TFormatted>(
 //   > 500 STX/block for following 4 yrs;
 //   > 250 for the 4 yrs after that; and then 125 STX/block in perpetuity after that.
 // We are going to use the year 2050 projected supply because "125 STX/block in perpetuity" means the total supply is infinite.
-export const TOTAL_STACKS = new BigNumber(1_818_000_000n.toString());
+export const TOTAL_STACKS_YEAR_2050 = new BigNumber(1_818_000_000n.toString());
 
 const MICROSTACKS_IN_STACKS = 1_000_000n;
 export const STACKS_DECIMAL_PLACES = 6;