Revert "chore!: remove deprecated /nft_events endpoint (#1329)" (#1343)

This reverts commit 65bb4e5.

Author: rafaelcr

docs/api/address/get-address-nft-events.example.json

@@ -0,0 +1,13 @@
+{
+  "limit": 20,
+  "offset": 0,
+  "total": 1,
+  "nft_events": [
+    {
+      "sender": "none",
+      "recipient": "ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4",
+      "asset_identifier": "some-asset",
+      "value": { "hex": "0x00", "repr": "0" }
+    }
+  ]
+}

docs/api/address/get-address-nft-events.schema.json

@@ -0,0 +1,28 @@
+{
+  "type": "object",
+  "title": "AddressNftListResponse",
+  "additionalProperties": false,
+  "required": [
+    "limit",
+    "offset",
+    "total",
+    "nft_events"
+  ],
+  "properties": {
+    "limit": {
+      "type": "integer"
+    },
+    "offset": {
+      "type": "integer"
+    },
+    "total": {
+      "type": "integer"
+    },
+    "nft_events": {
+      "type": "array",
+      "items": {
+        "$ref": "../../entities/nft-events/nft-event.schema.json"
+      }
+    }
+  }
+}

docs/openapi.yaml

@@ -1643,6 +1643,63 @@ paths:
               example:
                 $ref: ./api/address/get-address-stx-inbound.example.json
 
+  /extended/v1/address/{principal}/nft_events:
+    get:
+      summary: Get nft events
+      deprecated: true
+      description: |
+        **NOTE:** This endpoint is deprecated in favor of [Non-Fungible Token holdings](#operation/get_nft_holdings).
+
+        Retrieves a list of all nfts owned by an address, contains the clarity value of the identifier of the nft.
+      tags:
+        - Accounts
+      operationId: get_account_nft
+      parameters:
+        - name: principal
+          in: path
+          description: Stacks address or a Contract identifier
+          required: true
+          schema:
+            type: string
+            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
+        - name: limit
+          in: query
+          description: number of items to return
+          required: false
+          schema:
+            type: integer
+        - name: offset
+          in: query
+          description: number of items to skip
+          required: false
+          schema:
+            type: integer
+            example: 42000
+        - name: unanchored
+          in: query
+          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
+          required: false
+          schema:
+            type: boolean
+            example: true
+            default: false
+        - name: until_block
+          in: query
+          description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
+          required: false
+          schema:
+            type: string
+            example: 60000
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/address/get-address-nft-events.schema.json
+              example:
+                $ref: ./api/address/get-address-nft-events.example.json
+
   /v2/accounts/{principal}:
     get:
       summary: Get account info

src/api/routes/address.ts

@@ -476,6 +476,59 @@ export function createAddressRouter(db: PgStore, chainId: ChainID): express.Rout
     })
   );
 
+  /**
+   * @deprecated Use `/extended/v1/tokens/nft/holdings` instead.
+   */
+  router.get(
+    '/:stx_address/nft_events',
+    cacheHandler,
+    asyncHandler(async (req, res, next) => {
+      // get recent asset event associated with address
+      const stxAddress = req.params['stx_address'];
+      validatePrincipal(stxAddress);
+
+      const untilBlock = parseUntilBlockQuery(req, res, next);
+      const blockHeight = await getBlockHeight(untilBlock, req, res, next, db);
+      const limit = parseAssetsQueryLimit(req.query.limit ?? 20);
+      const offset = parsePagingQueryInput(req.query.offset ?? 0);
+      const includeUnanchored = isUnanchoredRequest(req, res, next);
+
+      const response = await db.getAddressNFTEvent({
+        stxAddress,
+        limit,
+        offset,
+        blockHeight,
+        includeUnanchored,
+      });
+      const nft_events = response.results.map(row => {
+        const parsedClarityValue = decodeClarityValueToRepr(row.value);
+        const r: NftEvent = {
+          sender: row.sender,
+          recipient: row.recipient,
+          asset_identifier: row.asset_identifier,
+          value: {
+            hex: row.value,
+            repr: parsedClarityValue,
+          },
+          tx_id: row.tx_id,
+          block_height: row.block_height,
+          event_index: row.event_index,
+          asset_event_type: getAssetEventTypeString(row.asset_event_type_id),
+          tx_index: row.tx_index,
+        };
+        return r;
+      });
+      const nftListResponse: AddressNftListResponse = {
+        nft_events: nft_events,
+        total: response.total,
+        limit: limit,
+        offset: offset,
+      };
+      setETagCacheHeaders(res);
+      res.json(nftListResponse);
+    })
+  );
+
   router.get(
     '/:address/mempool',
     mempoolCacheHandler,

src/datastore/pg-store.ts

@@ -3066,6 +3066,56 @@ export class PgStore {
     return { found: true, result: result[0] } as const;
   }
 
+  /**
+   * @deprecated Use `getNftHoldings` instead.
+   */
+  async getAddressNFTEvent(args: {
+    stxAddress: string;
+    limit: number;
+    offset: number;
+    blockHeight: number;
+    includeUnanchored: boolean;
+  }): Promise<{ results: AddressNftEventIdentifier[]; total: number }> {
+    // Join against `nft_custody` materialized view only if we're looking for canonical results.
+    const result = await this.sql<(AddressNftEventIdentifier & { count: number })[]>`
+      WITH address_transfers AS (
+        SELECT asset_identifier, value, sender, recipient, block_height, microblock_sequence, tx_index, event_index, tx_id, asset_event_type_id
+        FROM nft_events
+        WHERE canonical = true AND microblock_canonical = true
+        AND recipient = ${args.stxAddress} AND block_height <= ${args.blockHeight}
+      ),
+      last_nft_transfers AS (
+        SELECT DISTINCT ON(asset_identifier, value) asset_identifier, value, recipient
+        FROM nft_events
+        WHERE canonical = true AND microblock_canonical = true
+        AND block_height <= ${args.blockHeight}
+        ORDER BY asset_identifier, value, block_height DESC, microblock_sequence DESC, tx_index DESC, event_index DESC
+      )
+      SELECT sender, recipient, asset_identifier, value, event_index, asset_event_type_id, address_transfers.block_height, address_transfers.tx_id, (COUNT(*) OVER())::INTEGER AS count
+      FROM address_transfers
+      INNER JOIN ${args.includeUnanchored ? this.sql`last_nft_transfers` : this.sql`nft_custody`}
+        USING (asset_identifier, value, recipient)
+      ORDER BY block_height DESC, microblock_sequence DESC, tx_index DESC, event_index DESC
+      LIMIT ${args.limit} OFFSET ${args.offset}
+    `;
+
+    const count = result.length > 0 ? result[0].count : 0;
+
+    const nftEvents = result.map(row => ({
+      sender: row.sender,
+      recipient: row.recipient,
+      asset_identifier: row.asset_identifier,
+      value: row.value,
+      block_height: row.block_height,
+      tx_id: row.tx_id,
+      event_index: row.event_index,
+      asset_event_type_id: row.asset_event_type_id,
+      tx_index: row.tx_index,
+    }));
+
+    return { results: nftEvents, total: count };
+  }
+
   async getTxListDetails({
     txIds,
     includeUnanchored,