feat: show asset_identifier in ft list response, add filter by valid metadata (#298)

* feat: show asset_identifier in ft list response

* feat: valid metadata filter

Author: rafaelcr

migrations/1744225682001_ft-lower-index.ts

@@ -0,0 +1,20 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { MigrationBuilder, ColumnDefinitions } from 'node-pg-migrate';
+
+export const shorthands: ColumnDefinitions | undefined = undefined;
+
+export function up(pgm: MigrationBuilder): void {
+  pgm.dropIndex('tokens', ['type', 'name']);
+  pgm.createIndex('tokens', ['type', 'LOWER(name)'], { where: "type = 'ft'" });
+
+  pgm.dropIndex('tokens', ['type', 'symbol']);
+  pgm.createIndex('tokens', ['type', 'LOWER(symbol)'], { where: "type = 'ft'" });
+}
+
+export function down(pgm: MigrationBuilder): void {
+  pgm.dropIndex('tokens', ['type', 'LOWER(name)']);
+  pgm.createIndex('tokens', ['type', 'name'], { where: "type = 'ft'" });
+
+  pgm.dropIndex('tokens', ['type', 'LOWER(symbol)']);
+  pgm.createIndex('tokens', ['type', 'symbol'], { where: "type = 'ft'" });
+}

src/api/routes/ft.ts

@@ -38,6 +38,11 @@ const IndexRoutes: FastifyPluginCallback<Record<never, never>, Server, TypeBoxTy
           name: Type.Optional(Type.String()),
           symbol: Type.Optional(Type.String()),
           address: Type.Optional(StacksAddressParam),
+          valid_metadata_only: Type.Optional(
+            Type.Boolean({
+              description: 'If enabled, only tokens with valid SIP-016 metadata will be returned',
+            })
+          ),
           // Pagination
           offset: Type.Optional(OffsetParam),
           limit: Type.Optional(LimitParam),
@@ -59,6 +64,7 @@ const IndexRoutes: FastifyPluginCallback<Record<never, never>, Server, TypeBoxTy
           name: request.query.name,
           symbol: request.query.symbol,
           address: request.query.address,
+          valid_metadata_only: request.query.valid_metadata_only,
         },
         order: {
           order_by: request.query.order_by ?? FtOrderBy.name,
@@ -78,6 +84,7 @@ const IndexRoutes: FastifyPluginCallback<Record<never, never>, Server, TypeBoxTy
           description: t.description,
           tx_id: t.tx_id,
           sender_address: t.principal?.split('.')[0],
+          asset_identifier: `${t.principal}::${t.fungible_token_name}`,
           image_uri: t.cached_image,
           image_canonical_uri: t.image,
           image_thumbnail_uri: t.cached_thumbnail_image,

src/api/schemas.ts

@@ -301,6 +301,10 @@ export const FtBasicMetadataResponse = Type.Object(
       examples: ['0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0'],
     }),
     sender_address: Type.String({ examples: ['ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA'] }),
+    asset_identifier: Type.String({
+      examples: ['SPZA22A4D15RKH5G8XDGQ7BPC20Q5JNMH0VQKSR6.token-ststx-earn-v1::stSTXearn'],
+      description: 'Clarity asset identifier',
+    }),
     contract_principal: Type.String({
       examples: ['SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.miamicoin-token-v2'],
     }),

src/pg/pg-store.ts

@@ -370,14 +370,15 @@ export class PgStore extends BasePgStore {
     order?: DbFungibleTokenOrder;
   }): Promise<DbPaginatedResult<DbFungibleTokenMetadataItem>> {
     return await this.sqlTransaction(async sql => {
+      const validMetadataOnly = args.filters?.valid_metadata_only ?? false;
       // `ORDER BY` statement
       let orderBy: PgSqlQuery;
       switch (args.order?.order_by) {
         case FtOrderBy.symbol:
-          orderBy = sql`t.symbol`;
+          orderBy = sql`LOWER(t.symbol)`;
           break;
         default:
-          orderBy = sql`t.name`;
+          orderBy = sql`LOWER(t.name)`;
           break;
       }
       // `ORDER` statement
@@ -392,11 +393,12 @@ export class PgStore extends BasePgStore {
           m.description,
           s.principal,
           s.tx_id,
+          s.fungible_token_name,
           m.image,
           m.cached_image,
           COUNT(*) OVER() as total
         FROM tokens AS t
-        LEFT JOIN metadata AS m ON t.id = m.token_id
+        ${validMetadataOnly ? sql`INNER` : sql`LEFT`} JOIN metadata AS m ON t.id = m.token_id
         INNER JOIN smart_contracts AS s ON t.smart_contract_id = s.id
         WHERE t.type = 'ft'
           ${

src/pg/types.ts

@@ -228,6 +228,7 @@ export type DbFungibleTokenFilters = {
   name?: string;
   symbol?: string;
   address?: string;
+  valid_metadata_only?: boolean;
 };
 
 export type DbFungibleTokenOrder = {
@@ -250,6 +251,7 @@ export type DbFungibleTokenMetadataItem = {
   tx_id: string;
   principal: string;
   image?: string;
+  fungible_token_name?: string;
   cached_image?: string;
   cached_thumbnail_image?: string;
 };

tests/api/ft.test.ts

@@ -378,6 +378,7 @@ describe('FT routes', () => {
         image_uri: 'http://img.com/meme.jpg',
         name: 'Meme token',
         sender_address: 'SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1',
+        asset_identifier: 'SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1.meme-token::ft-token',
         symbol: 'MEME',
         token_uri: 'https://ipfs.io/abcd.json',
         total_supply: '200000',
@@ -391,6 +392,7 @@ describe('FT routes', () => {
         image_uri: 'https://cdn.citycoins.co/logos/miamicoin.png',
         name: 'miamicoin',
         sender_address: 'SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R',
+        asset_identifier: 'SP1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.miamicoin-token-v2::ft-token',
         symbol: 'MIA',
         token_uri: 'https://cdn.citycoins.co/metadata/miamicoin.json',
         total_supply: '5586789829000000',
@@ -404,6 +406,7 @@ describe('FT routes', () => {
         image_uri: 'https://app.stackswap.org/icon/stsw.svg',
         name: 'STACKSWAP',
         sender_address: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
+        asset_identifier: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275.stsw-token-v4a::ft-token',
         symbol: 'STSW',
         token_uri: 'https://app.stackswap.org/token/stsw.json',
         total_supply: '1000000000000000',
@@ -447,7 +450,7 @@ describe('FT routes', () => {
           symbol: 'rstSTX',
           decimals: 5,
           tx_id: '0xbdc41843d5e0cd4a70611f6badeb5c87b07b12309e77c4fbaf2334c7b4cee89b',
-          principal: 'SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1.meme-token',
+          principal: 'SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1.scam-token',
           total_supply: '200000',
         },
         true
@@ -462,6 +465,37 @@ describe('FT routes', () => {
       expect(json4.results[0].symbol).toBe('rstSTX');
     });
 
+    test('filters by valid metadata', async () => {
+      await insertFtList();
+      await insertFt(
+        {
+          name: 'Scam token',
+          symbol: 'rstSTX',
+          decimals: 5,
+          tx_id: '0xbdc41843d5e0cd4a70611f6badeb5c87b07b12309e77c4fbaf2334c7b4cee89b',
+          principal: 'SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1.scam-token',
+          total_supply: '200000',
+        },
+        true
+      );
+
+      const response = await fastify.inject({
+        method: 'GET',
+        url: '/metadata/ft',
+      });
+      expect(response.statusCode).toBe(200);
+      const json = response.json();
+      expect(json.total).toBe(4);
+
+      const response2 = await fastify.inject({
+        method: 'GET',
+        url: '/metadata/ft?valid_metadata_only=true',
+      });
+      expect(response2.statusCode).toBe(200);
+      const json2 = response2.json();
+      expect(json2.total).toBe(3);
+    });
+
     test('filters by symbol', async () => {
       await insertFtList();
       const response = await fastify.inject({