feat: events-only endpoint for address and tx_id (#1027)

* feat: wip- added api for events for address

* feat: added events query for tx and address

* docs: added docs for event endpoints

* test: update test builder to increase event index

* docs: fixed json typo

* docs: update examples

* refactor: cleanup

* feat: change event endpoint and ad txId and principal as query param

* docs: update docs for the endpoint

* perf: change query from multiple query to single union query

* fix: revert init.ts unnecessary changes

* fix: used tx_id instead of txId in query param

* refactor: use try catch only for relevant function

* fix: validate address and tx_id before sending to data layer

* fix: join tx to use micrblock sequence orderinging in events

* refactor: put 0x prefix on txId

* docs: update docs

* docs: update docs for transaction events endpoint

* refactor: refactor comments and test headers

* perf: added cache handler for tx/events endpoint

* fix: fixed conflicts

* style: change comment place

Author: asimm241

docs/api/transaction/get-transaction-events.example.json

@@ -0,0 +1,34 @@
+{
+  "limit": 96,
+  "offset": 0,
+  "events": [
+    {
+      "event_index": 0,
+      "event_type": "non_fungible_token_asset",
+      "tx_id": "0x05ccc123db703a2808afaaf88b6b3240f14391d14fde701bd20d7206c9133af6",
+      "asset": {
+        "asset_event_type": "transfer",
+        "asset_id": "ST000000000000000000002AMW42H.bns::names",
+        "sender": "STKVDRCTN8C81T22QHR9PG9GPD3V3WPQYBYFHPT4",
+        "recipient": "STRWN68C36Z7WTDD1TJERTAZ4SXDRMMDB29M4VNQ",
+        "value": {
+          "hex": "0x0c00000002046e616d65020000000a62696c616c7465737435096e616d6573706163650200000003627463",
+          "repr": "(tuple (name 0x62696c616c7465737435) (namespace 0x627463))"
+        }
+      }
+    },
+    {
+      "event_index": 1,
+      "event_type": "smart_contract_log",
+      "tx_id": "0x05ccc123db703a2808afaaf88b6b3240f14391d14fde701bd20d7206c9133af6",
+      "contract_log": {
+        "contract_id": "ST000000000000000000002AMW42H.bns",
+        "topic": "print",
+        "value": {
+          "hex": "0x0c000000010a6174746163686d656e740c00000003106174746163686d656e742d696e646578010000000000000000000000000000028304686173680200000014b472a266d0bd89c13706a4132ccfb16f7c3b9fcb086d657461646174610c00000004046e616d65020000000a62696c616c7465737435096e616d6573706163650200000003627463026f700d0000000d6e616d652d7472616e736665720974782d73656e646572051a27b6e19aaa1880e842bc709b4130b347b1f2d7f2",
+          "repr": "(tuple (attachment (tuple (attachment-index u643) (hash 0xb472a266d0bd89c13706a4132ccfb16f7c3b9fcb) (metadata (tuple (name 0x62696c616c7465737435) (namespace 0x627463) (op \"name-transfer\") (tx-sender STKVDRCTN8C81T22QHR9PG9GPD3V3WPQYBYFHPT4))))))"
+        }
+      }
+    }
+  ]
+}

docs/api/transaction/get-transaction-events.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "GET event for the given transaction",
+  "title": "TransactionEventsResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "results",
+    "limit",
+    "offset"
+  ],
+  "properties": {
+    "limit": {
+      "type": "integer"
+    },
+    "offset": {
+      "type": "integer"
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/transaction-events/transaction-event.schema.json"
+      }
+    }
+  }
+}

docs/generated.d.ts

@@ -101,6 +101,7 @@ export type SchemaMergeRootStub =
   | NonFungibleTokensMetadataList
   | MempoolTransactionListResponse
   | GetRawTransactionResult
+  | TransactionEventsResponse
   | TransactionResults
   | PostCoreNodeTransactionsError
   | AddressNonces
@@ -3402,6 +3403,14 @@ export interface GetRawTransactionResult {
   raw_tx: string;
   [k: string]: unknown | undefined;
 }
+/**
+ * GET event for the given transaction
+ */
+export interface TransactionEventsResponse {
+  limit: number;
+  offset: number;
+  results: TransactionEvent[];
+}
 /**
  * GET request that returns transactions
  */

docs/openapi.yaml

@@ -3296,3 +3296,59 @@ paths:
                 $ref: ./api/core-node/post-fee-transaction-response.schema.json
               example:
                 $ref: ./api/core-node/post-fee-transaction-response.example.json
+  /extended/v1/tx/events:
+    get:
+      summary: Transaction Events
+      description: Retrieves the list of events filtered by principal (STX address or Smart Contract ID), transaction id or event types.
+        The list of event types is ('smart_contract_log', 'stx_lock', 'stx_asset', 'fungible_token_asset', 'non_fungible_token_asset').
+      tags:
+        - Transactions
+      operationId: get_filtered_events
+      parameters:
+        - name: tx_id
+          in: query
+          description: Hash of transaction
+          required: false
+          schema:
+            type: string
+            example: '0x29e25515652dad41ef675bd0670964e3d537b80ec19cf6ca6f1dd65d5bc642c5'
+        - name: address
+          in: query
+          description: Stacks address or a Contract identifier
+          required: false
+          schema:
+            type: string
+            example: ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4
+        - name: limit
+          in: query
+          description: number of items to return
+          required: false
+          schema:
+            type: integer
+            example: 100
+        - name: offset
+          in: query
+          description: number of items to skip
+          required: false
+          schema:
+            type: integer
+            example: 50
+        - name: type
+          in: query
+          description: Filter the events on event type
+          required: false
+          schema:
+            type: array
+            items: 
+              type: string
+              enum: [smart_contract_log, stx_lock, stx_asset, fungible_token_asset, non_fungible_token_asset]
+              example: stx_lock
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/transaction/get-transaction-events.schema.json
+              example:
+                $ref: ./api/transaction/get-transaction-events.example.json

src/api/query-helpers.ts

@@ -1,7 +1,8 @@
 import { ClarityAbi } from '@stacks/transactions';
 import { NextFunction, Request, Response } from 'express';
-import { has0xPrefix, hexToBuffer, isValidPrincipal } from './../helpers';
+import { has0xPrefix, hexToBuffer, isValidPrincipal, parseEventTypeStrings } from './../helpers';
 import { InvalidRequestError, InvalidRequestErrorType } from '../errors';
+import { DbEventTypeId } from './../datastore/common';
 
 function handleBadRequest(res: Response, next: NextFunction, errorMessage: string): never {
   const error = new InvalidRequestError(errorMessage, InvalidRequestErrorType.bad_request);
@@ -222,3 +223,66 @@ export function validatePrincipal(stxAddress: string) {
     );
   }
 }
+
+export function parseAddressOrTxId(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): { address: string; txId: undefined } | { address: undefined; txId: string } | never {
+  const address = req.query.address;
+  const txId = req.query.tx_id;
+  if (!address && !txId) {
+    handleBadRequest(res, next, `can not find 'address' or 'tx_id' in the request`);
+  }
+  if (address && txId) {
+    //if mutually exclusive address and txId specified throw
+    handleBadRequest(res, next, `can't handle both 'address' and 'tx_id' in the same request`);
+  }
+  if (address) {
+    if (typeof address === 'string') {
+      validatePrincipal(address);
+      return { address, txId: undefined };
+    }
+    handleBadRequest(res, next, `invalid 'address'`);
+  }
+  if (typeof txId === 'string') {
+    const txIdHex = has0xPrefix(txId) ? txId : '0x' + txId;
+    validateRequestHexInput(txIdHex);
+    return { address: undefined, txId: txIdHex };
+  }
+  handleBadRequest(res, next, `invalid 'tx_id'`);
+}
+
+export function parseEventTypeFilter(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): DbEventTypeId[] {
+  const typeQuery = req.query.type;
+  let eventTypeFilter: DbEventTypeId[];
+  if (Array.isArray(typeQuery)) {
+    try {
+      eventTypeFilter = parseEventTypeStrings(typeQuery as string[]);
+    } catch (error) {
+      handleBadRequest(res, next, `invalid 'event type'`);
+    }
+  } else if (typeof typeQuery === 'string') {
+    try {
+      eventTypeFilter = parseEventTypeStrings([typeQuery]);
+    } catch (error) {
+      handleBadRequest(res, next, `invalid 'event type'`);
+    }
+  } else if (typeQuery) {
+    handleBadRequest(res, next, `invalid 'event type format'`);
+  } else {
+    eventTypeFilter = [
+      DbEventTypeId.SmartContractLog,
+      DbEventTypeId.StxAsset,
+      DbEventTypeId.FungibleTokenAsset,
+      DbEventTypeId.NonFungibleTokenAsset,
+      DbEventTypeId.StxLock,
+    ]; //no filter provided , return all types of events
+  }
+
+  return eventTypeFilter;
+}

src/api/routes/tx.ts

@@ -1,13 +1,14 @@
 import * as express from 'express';
 import { asyncHandler } from '../async-handler';
-import { DataStore, DbTx, DbMempoolTx } from '../../datastore/common';
+import { DataStore, DbTx, DbMempoolTx, DbEventTypeId } from '../../datastore/common';
 import {
   getTxFromDataStore,
   parseTxTypeStrings,
   parseDbMempoolTx,
   searchTx,
   searchTxs,
   parseDbTx,
+  parseDbEvent,
 } from '../controllers/db-controller';
 import {
   waiter,
@@ -18,12 +19,15 @@ import {
   bufferToHexPrefixString,
   isValidPrincipal,
   hexToBuffer,
+  parseEventTypeStrings,
 } from '../../helpers';
 import { InvalidRequestError, InvalidRequestErrorType } from '../../errors';
 import {
   isUnanchoredRequest,
   getBlockHeightPathParam,
   validateRequestHexInput,
+  parseAddressOrTxId,
+  parseEventTypeFilter,
 } from '../query-helpers';
 import { parseLimitQuery, parsePagingQueryInput } from '../pagination';
 import { validate } from '../validate';
@@ -259,6 +263,28 @@ export function createTxRouter(db: DataStore): express.Router {
     })
   );
 
+  router.get(
+    '/events',
+    cacheHandler,
+    asyncHandler(async (req, res, next) => {
+      const limit = parseTxQueryEventsLimit(req.query['limit'] ?? 96);
+      const offset = parsePagingQueryInput(req.query['offset'] ?? 0);
+
+      const principalOrTxId = parseAddressOrTxId(req, res, next);
+      const eventTypeFilter = parseEventTypeFilter(req, res, next);
+
+      const { results } = await db.getTransactionEvents({
+        addressOrTxId: principalOrTxId,
+        eventTypeFilter,
+        offset,
+        limit,
+      });
+      const response = { limit, offset, events: results.map(e => parseDbEvent(e)) };
+      setETagCacheHeaders(res);
+      res.status(200).json(response);
+    })
+  );
+
   // TODO: Add cache headers. Impossible right now since this tx might be from a block or from the mempool.
   router.get(
     '/:tx_id',

src/datastore/common.ts

@@ -690,6 +690,21 @@ export interface DataStore extends DataStoreEventEmitter {
     offset: number;
   }): Promise<{ results: DbEvent[] }>;
 
+  /**
+   * It retrieves filtered events from the db based on transaction, principal or event type. Note: It does not accept both principal and txId at the same time
+   * @param args - addressOrTxId: filter for either transaction id or address
+   * @param args - eventTypeFilter: filter based on event types ids
+   * @param args - limit: returned that many rows
+   * @param args - offset: skip that any rows
+   * @returns returns array of events
+   */
+  getTransactionEvents(args: {
+    addressOrTxId: { address: string; txId: undefined } | { address: undefined; txId: string };
+    eventTypeFilter: DbEventTypeId[];
+    limit: number;
+    offset: number;
+  }): Promise<{ results: DbEvent[] }>;
+
   getTxListDetails(args: { txIds: string[]; includeUnanchored: boolean }): Promise<DbTx[]>; // tx_id is returned for not found case
 
   getSmartContractList(contractIds: string[]): Promise<DbSmartContract[]>;