Add SVM Token Holders by Mint endpoint

- Get token holders by `mint`
- Only recent active holders (less than 1 month) are considered

Author: 0237h

src/routes/token/holders/index.ts

@@ -1,9 +1,10 @@
 import { Hono } from 'hono';
 import evm from './evm.js';
+import svm from './svm.js';
 
 const router = new Hono();
 
 router.route('/evm', evm);
-// router.route('/svm', svm)
+router.route('/svm', svm);
 
 export default router;

src/routes/token/holders/svm.ts

@@ -5,26 +5,16 @@ import { z } from 'zod';
 import { config } from '../../../config.js';
 import { handleUsageQueryError, makeUsageQueryJson } from '../../../handleQuery.js';
 import { sqlQueries } from '../../../sql/index.js';
-import {
-    apiUsageResponse,
-    orderBySchemaValue,
-    orderDirectionSchema,
-    paginationQuery,
-    SVM_networkIdSchema,
-    svmAddressSchema,
-    WSOL,
-} from '../../../types/zod.js';
+import { apiUsageResponse, paginationQuery, SVM_networkIdSchema, svmAddressSchema, WSOL } from '../../../types/zod.js';
 import { validatorHook, withErrorResponses } from '../../../utils.js';
 
 const paramSchema = z.object({
-    contract: WSOL,
+    mint: WSOL,
 });
 
 const querySchema = z
     .object({
         network_id: SVM_networkIdSchema,
-        orderBy: orderBySchemaValue.optional(),
-        orderDirection: orderDirectionSchema.optional(),
     })
     .extend(paginationQuery.shape);
 
@@ -57,8 +47,8 @@ const responseSchema = apiUsageResponse.extend({
 
 const openapi = describeRoute(
     withErrorResponses({
-        summary: 'Token Holders',
-        description: 'Returns token holders ranked by balance with holdings and supply percentage.',
+        summary: 'Solana Token Holders by Mint',
+        description: 'Returns token holders ranked by balance with holdings.',
 
         tags: ['SVM'],
         security: [{ bearerAuth: [] }],
@@ -96,7 +86,7 @@ const openapi = describeRoute(
 const route = new Hono<{ Variables: { validatedData: z.infer<typeof querySchema> } }>();
 
 route.get(
-    '/:contract',
+    '/:mint',
     openapi,
     validator('param', paramSchema, validatorHook),
     validator('query', querySchema, validatorHook),

src/sql/holders_for_contract/svm.sql

@@ -1,16 +1,62 @@
+WITH filtered_balances AS
+(
+    SELECT
+        max(block_num) AS block_num,
+        max(timestamp) AS timestamp,
+        program_id,
+        account,
+        argMax(amount, b.block_num) AS amount,
+        mint,
+        any(decimals) AS decimals,
+        {network_id:String} as network_id
+    FROM balances AS b
+    WHERE
+        mint = {mint:String}
+        AND b.timestamp > now() - INTERVAL 1 MONTH
+    GROUP BY program_id, mint, account
+    ORDER BY amount DESC
+    LIMIT   {limit:UInt64}
+    OFFSET  {offset:UInt64}
+),
+owners AS
+(
+    SELECT
+        account,
+        owner
+    FROM owner_state_latest AS o
+    WHERE account IN (SELECT account FROM filtered_balances)
+),
+metadata AS
+(
+    SELECT
+        mint,
+        if(empty(name), NULL, name) AS name,
+        if(empty(symbol), NULL, symbol) AS symbol,
+        if(empty(uri), NULL, uri) AS uri
+    FROM metadata_view
+    WHERE metadata IN (
+        SELECT metadata
+        FROM metadata_mint_state_latest
+        WHERE mint IN (SELECT mint FROM filtered_balances)
+        GROUP BY metadata
+    )
+)
 SELECT
-    block_num,
-    timestamp as last_balance_update,
-    toString(owner) AS owner,
-    amount,
-    toString(b.amount / pow(10, decimals)) as value,
+    b.timestamp                         AS last_update,
+    block_num                           AS last_update_block_num,
+    toUnixTimestamp(b.timestamp)        AS last_update_timestamp,
+    toString(program_id)                AS program_id,
+    toString(owner)                     AS owner,
+    toString(account)                   AS token_account,
+    toString(mint)                      AS mint,
+    toString(b.amount)                  AS amount,
+    b.amount / pow(10, decimals)        AS value,
     decimals,
-    'TO IMPLEMENT' as symbol,
-    {network_id: String} as network_id
-FROM balances_by_mint AS b
-FINAL
-WHERE
-    mint = {contract: String} AND amount > 0
-ORDER BY value DESC
-LIMIT   {limit:UInt64}
-OFFSET  {offset:UInt64}
+    name,
+    symbol,
+    uri,
+    {network_id:String}     AS network_id
+FROM filtered_balances AS b
+LEFT JOIN metadata USING mint
+LEFT JOIN owners USING account
+ORDER BY value DESC