feat: add BRC-20 event history endpoint (#191)

* feat: add BRC-20 event history/activity ingestion and endpoint * refactor: switch to concat for a single activity subplan for transfers * refactor: rename prepare_transfer to transfer * test: fix faulty test due to duplicate inscription numbers * refactor: switch to postgres enum type * refactor: merge multiple queries using CTEs * test: add test with multiple participants * refactor: add updates from pr * test: add block height test * refactor: merge event inserts using CTEs * fix: use correct ids for events * fix: migrate into events with queries --------- Co-authored-by: janniks <janniks@users.noreply.github.com> Co-authored-by: Rafael Cardenas <rafael@rafaelcr.com>
hirosystems · Aug 31, 2023 · d9967b1 · d9967b1
1 parent 85f5ed0
commit d9967b1
Show file tree

Hide file tree

Showing 9 changed files with 1,236 additions and 164 deletions.
diff --git a/migrations/1692891772000_brc20-events-types.ts b/migrations/1692891772000_brc20-events-types.ts
@@ -0,0 +1,67 @@
+/* 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.createType('brc20_operation', ['deploy', 'mint', 'transfer', 'transfer_send']);
+  pgm.addColumns('brc20_events', {
+    genesis_location_id: {
+      type: 'bigint',
+      references: '"locations"',
+      onDelete: 'CASCADE',
+      notNull: true,
+      unique: true, // only one event exists per location
+    },
+    operation: {
+      type: 'brc20_operation',
+      notNull: true,
+    },
+  });
+
+  pgm.createIndex('brc20_events', ['genesis_location_id']);
+  pgm.createIndex('brc20_events', ['operation']);
+
+  pgm.createIndex('brc20_events', ['brc20_deploy_id']);
+  pgm.createIndex('brc20_events', ['transfer_id']);
+  pgm.createIndex('brc20_events', ['mint_id']);
+
+  pgm.sql(`
+    INSERT INTO brc20_events (operation, inscription_id, genesis_location_id, brc20_deploy_id, deploy_id) (
+      SELECT 'deploy', d.inscription_id, g.location_id, d.id, d.id
+      FROM brc20_deploys AS d
+      INNER JOIN genesis_locations AS g ON g.inscription_id = d.inscription_id
+    )
+  `);
+  pgm.sql(`
+    INSERT INTO brc20_events (operation, inscription_id, genesis_location_id, brc20_deploy_id, mint_id) (
+      SELECT 'mint', m.inscription_id, g.location_id, m.brc20_deploy_id, m.id
+      FROM brc20_mints AS m
+      INNER JOIN genesis_locations AS g ON g.inscription_id = m.inscription_id
+    )
+  `);
+  pgm.sql(`
+    INSERT INTO brc20_events (operation, inscription_id, genesis_location_id, brc20_deploy_id, transfer_id) (
+      SELECT 'transfer', t.inscription_id, g.location_id, t.brc20_deploy_id, t.id
+      FROM brc20_transfers AS t
+      INNER JOIN genesis_locations AS g ON g.inscription_id = t.inscription_id
+    )
+  `);
+  pgm.sql(`
+    INSERT INTO brc20_events (operation, inscription_id, genesis_location_id, brc20_deploy_id, transfer_id) (
+      SELECT 'transfer_send', inscription_id, location_id, brc20_deploy_id, inscription_id
+      FROM brc20_balances
+      WHERE type = 3
+    )
+  `);
+}
+
+export function down(pgm: MigrationBuilder): void {
+  pgm.dropIndex('brc20_events', ['genesis_location_id']);
+  pgm.dropIndex('brc20_events', ['operation']);
+  pgm.dropColumns('brc20_events', ['genesis_location_id', 'operation']);
+  pgm.dropIndex('brc20_events', ['brc20_deploy_id']);
+  pgm.dropIndex('brc20_events', ['transfer_id']);
+  pgm.dropIndex('brc20_events', ['mint_id']);
+  pgm.dropType('brc20_operation');
+}
diff --git a/src/api/init.ts b/src/api/init.ts
@@ -1,15 +1,15 @@
 import FastifyCors from '@fastify/cors';
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import { PINO_LOGGER_CONFIG, isProdEnv } from '@hirosystems/api-toolkit';
 import Fastify, { FastifyPluginAsync } from 'fastify';
 import FastifyMetrics, { IFastifyMetrics } from 'fastify-metrics';
 import { Server } from 'http';
 import { PgStore } from '../pg/pg-store';
+import { Brc20Routes } from './routes/brc20';
 import { InscriptionsRoutes } from './routes/inscriptions';
 import { SatRoutes } from './routes/sats';
 import { StatsRoutes } from './routes/stats';
 import { StatusRoutes } from './routes/status';
-import { PINO_LOGGER_CONFIG, isProdEnv } from '@hirosystems/api-toolkit';
-import { Brc20Routes } from './routes/brc20';
 
 export const Api: FastifyPluginAsync<
   Record<never, never>,

diff --git a/src/api/routes/brc20.ts b/src/api/routes/brc20.ts
@@ -1,12 +1,15 @@
 import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
 import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
 import { FastifyPluginCallback } from 'fastify';
 import { Server } from 'http';
 import {
   AddressParam,
   BlockHeightParam,
+  Brc20ActivityResponseSchema,
   Brc20BalanceResponseSchema,
   Brc20HolderResponseSchema,
+  Brc20OperationsParam,
   Brc20TickerParam,
   Brc20TickersParam,
   Brc20TokenDetailsSchema,
@@ -16,15 +19,15 @@ import {
   OffsetParam,
   PaginatedResponse,
 } from '../schemas';
+import { handleInscriptionTransfersCache } from '../util/cache';
 import {
   DEFAULT_API_LIMIT,
+  parseBrc20Activities,
   parseBrc20Balances,
   parseBrc20Holders,
   parseBrc20Supply,
   parseBrc20Tokens,
 } from '../util/helpers';
-import { Value } from '@sinclair/typebox/value';
-import { handleInscriptionTransfersCache } from '../util/cache';
 
 export const Brc20Routes: FastifyPluginCallback<
   Record<never, never>,
@@ -195,5 +198,45 @@ export const Brc20Routes: FastifyPluginCallback<
     }
   );
 
+  fastify.get(
+    '/brc-20/activity',
+    {
+      schema: {
+        operationId: 'getBrc20Activity',
+        summary: 'BRC-20 Activity',
+        description: 'Retrieves BRC-20 activity',
+        tags: ['BRC-20'],
+        querystring: Type.Object({
+          ticker: Type.Optional(Brc20TickersParam),
+          block_height: Type.Optional(BlockHeightParam),
+          operation: Type.Optional(Brc20OperationsParam),
+          // Pagination
+          offset: Type.Optional(OffsetParam),
+          limit: Type.Optional(LimitParam),
+        }),
+        response: {
+          200: PaginatedResponse(Brc20ActivityResponseSchema, 'Paginated BRC-20 Activity Response'),
+        },
+      },
+    },
+    async (request, reply) => {
+      const limit = request.query.limit ?? DEFAULT_API_LIMIT;
+      const offset = request.query.offset ?? 0;
+      const balances = await fastify.db.brc20.getActivity({
+        limit,
+        offset,
+        ticker: request.query.ticker,
+        block_height: request.query.block_height ? parseInt(request.query.block_height) : undefined,
+        operation: request.query.operation,
+      });
+      await reply.send({
+        limit,
+        offset,
+        total: balances.total,
+        results: parseBrc20Activities(balances.results),
+      });
+    }
+  );
+
   done();
 };
diff --git a/src/api/schemas.ts b/src/api/schemas.ts
@@ -1,8 +1,8 @@
 import { SwaggerOptions } from '@fastify/swagger';
+import { SERVER_VERSION } from '@hirosystems/api-toolkit';
 import { Static, TSchema, Type } from '@sinclair/typebox';
 import { TypeCompiler } from '@sinclair/typebox/compiler';
-import { SatoshiRarity, SAT_SUPPLY } from './util/ordinal-satoshi';
-import { SERVER_VERSION } from '@hirosystems/api-toolkit';
+import { SAT_SUPPLY, SatoshiRarity } from './util/ordinal-satoshi';
 
 export const OpenApiSchemaOptions: SwaggerOptions = {
   openapi: {
@@ -198,6 +198,23 @@ export const LimitParam = Type.Integer({
   description: 'Results per page',
 });
 
+export const Brc20OperationParam = Type.Union(
+  [
+    Type.Literal('deploy'),
+    Type.Literal('mint'),
+    Type.Literal('transfer'),
+    Type.Literal('transfer_send'),
+  ],
+  {
+    title: 'Operation',
+    description:
+      'BRC-20 token operation. Note that a BRC-20 transfer is a two step process `transfer` (creating the inscription, which makes funds transferrable) and `transfer_send` (sending the inscription to a recipient, which moves the funds)',
+    examples: ['deploy', 'mint', 'transfer', 'transfer_send'],
+  }
+);
+
+export const Brc20OperationsParam = Type.Array(Brc20OperationParam);
+
 export enum OrderBy {
   number = 'number',
   genesis_block_height = 'genesis_block_height',
@@ -371,6 +388,62 @@ export const Brc20BalanceResponseSchema = Type.Object({
 });
 export type Brc20BalanceResponse = Static<typeof Brc20BalanceResponseSchema>;
 
+export const Brc20ActivityResponseSchema = Type.Object({
+  operation: Type.Union([
+    Type.Literal('deploy'),
+    Type.Literal('mint'),
+    Type.Literal('transfer'),
+    Type.Literal('transfer_send'),
+  ]),
+  ticker: Type.String({ examples: ['PEPE'] }),
+  inscription_id: Type.String({
+    examples: ['1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218i0'],
+  }),
+  block_height: Type.Integer({ examples: [778921] }),
+  block_hash: Type.String({
+    examples: ['0000000000000000000452773967cdd62297137cdaf79950c5e8bb0c62075133'],
+  }),
+  tx_id: Type.String({
+    examples: ['1463d48e9248159084929294f64bda04487503d30ce7ab58365df1dc6fd58218'],
+  }),
+  address: Type.String({
+    examples: ['bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8'],
+  }),
+  timestamp: Type.Integer({ examples: [1677733170000] }),
+  mint: Type.Optional(
+    Type.Object({
+      amount: Nullable(Type.String({ examples: ['1000000'] })),
+    })
+  ),
+  deploy: Type.Optional(
+    Type.Object({
+      max_supply: Type.String({ examples: ['21000000'] }),
+      mint_limit: Nullable(Type.String({ examples: ['100000'] })),
+      decimals: Type.Integer({ examples: [18] }),
+    })
+  ),
+  transfer: Type.Optional(
+    Type.Object({
+      amount: Type.String({ examples: ['1000000'] }),
+      from_address: Type.String({
+        examples: ['bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8'],
+      }),
+    })
+  ),
+  transfer_send: Type.Optional(
+    Type.Object({
+      amount: Type.String({ examples: ['1000000'] }),
+      from_address: Type.String({
+        examples: ['bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8'],
+      }),
+      to_address: Type.String({
+        examples: ['bc1pvwh2dl6h388x65rqq47qjzdmsqgkatpt4hye6daf7yxvl0z3xjgq247aq8'],
+      }),
+    })
+  ),
+});
+export type Brc20ActivityResponse = Static<typeof Brc20ActivityResponseSchema>;
+
 export const Brc20TokenResponseSchema = Type.Object(
   {
     id: Type.String({

diff --git a/src/api/util/helpers.ts b/src/api/util/helpers.ts
@@ -1,4 +1,10 @@
-import { DbBrc20Token, DbBrc20Supply, DbBrc20Balance, DbBrc20Holder } from '../../pg/brc20/types';
+import {
+  DbBrc20Activity,
+  DbBrc20Balance,
+  DbBrc20Holder,
+  DbBrc20Supply,
+  DbBrc20Token,
+} from '../../pg/brc20/types';
 import {
   DbFullyLocatedInscriptionResult,
   DbInscriptionLocationChange,
@@ -8,6 +14,7 @@ import {
   BlockHashParamCType,
   BlockHeightParamCType,
   BlockInscriptionTransfer,
+  Brc20ActivityResponse,
   Brc20BalanceResponse,
   Brc20HolderResponse,
   Brc20Supply,
@@ -130,6 +137,50 @@ export function parseBrc20Balances(items: DbBrc20Balance[]): Brc20BalanceRespons
   }));
 }
 
+export function parseBrc20Activities(items: DbBrc20Activity[]): Brc20ActivityResponse[] {
+  return items.map(i => {
+    const activity = {
+      operation: i.operation,
+      ticker: i.ticker,
+      address: i.address,
+      tx_id: i.tx_id,
+      inscription_id: i.inscription_id,
+      block_hash: i.block_hash,
+      block_height: parseInt(i.block_height),
+      timestamp: i.timestamp.valueOf(),
+    };
+
+    switch (i.operation) {
+      case 'deploy': {
+        return {
+          ...activity,
+          deploy: {
+            max_supply: i.deploy_max,
+            mint_limit: i.deploy_limit,
+            decimals: i.deploy_decimals,
+          },
+        };
+      }
+      case 'mint': {
+        return {
+          ...activity,
+          mint: {
+            amount: i.mint_amount,
+          },
+        };
+      }
+      case 'transfer': {
+        const [amount, from_address] = i.transfer_data.split(';');
+        return { ...activity, transfer: { amount, from_address } };
+      }
+      case 'transfer_send': {
+        const [amount, from_address, to_address] = i.transfer_data.split(';');
+        return { ...activity, transfer_send: { amount, from_address, to_address } };
+      }
+    }
+  });
+}
+
 export function parseBrc20Holders(items: DbBrc20Holder[]): Brc20HolderResponse[] {
   return items.map(i => ({
     address: i.address,