feat: tx list nonce filter option (#2023)

* feat: tx list nonce filter option

* docs: tx nonce filter param

Author: zone117x

docs/openapi.yaml

@@ -268,6 +268,13 @@ paths:
           schema:
             type: string
             example: "delegate-stx"
+        - name: nonce
+          in: query
+          description: Filter by transactions with this nonce
+          required: false
+          schema:
+            type: integer
+            example: 123
         - name: order
           in: query
           description: Option to sort results in ascending or descending order

migrations/1718887498565_tx-nonce-index.js

@@ -0,0 +1,9 @@
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.up = pgm => {
+  pgm.createIndex('txs', 'nonce');
+};
+
+/** @param { import("node-pg-migrate").MigrationBuilder } pgm */
+exports.down = pgm => {
+  pgm.dropIndex('txs', 'nonce');
+};

src/api/routes/tx.ts

@@ -140,6 +140,17 @@ export function createTxRouter(db: PgStore): express.Router {
         functionName = req.query.function_name;
       }
 
+      let nonce: number | undefined;
+      if (typeof req.query.nonce === 'string') {
+        if (!/^\d{1,10}$/.test(req.query.nonce)) {
+          throw new InvalidRequestError(
+            `Invalid query parameter for "nonce": "${req.query.nonce}" is not a valid nonce`,
+            InvalidRequestErrorType.invalid_param
+          );
+        }
+        nonce = parseInt(req.query.nonce);
+      }
+
       let sortBy: 'block_height' | 'burn_block_time' | 'fee' | undefined;
       if (req.query.sort_by) {
         if (
@@ -166,6 +177,7 @@ export function createTxRouter(db: PgStore): express.Router {
         endTime,
         contractId,
         functionName,
+        nonce,
         order,
         sortBy,
       });

src/datastore/pg-store.ts

@@ -1422,6 +1422,7 @@ export class PgStore extends BasePgStore {
     endTime,
     contractId,
     functionName,
+    nonce,
     order,
     sortBy,
   }: {
@@ -1435,6 +1436,7 @@ export class PgStore extends BasePgStore {
     endTime?: number;
     contractId?: string;
     functionName?: string;
+    nonce?: number;
     order?: 'desc' | 'asc';
     sortBy?: 'block_height' | 'burn_block_time' | 'fee';
   }): Promise<{ results: DbTx[]; total: number }> {
@@ -1474,8 +1476,16 @@ export class PgStore extends BasePgStore {
       const contractFuncFilterSql = functionName
         ? sql`AND contract_call_function_name = ${functionName}`
         : sql``;
+      const nonceFilterSql = nonce ? sql`AND nonce = ${nonce}` : sql``;
       const noFilters =
-        txTypeFilter.length === 0 && !fromAddress && !toAddress && !startTime && !endTime;
+        txTypeFilter.length === 0 &&
+        !fromAddress &&
+        !toAddress &&
+        !startTime &&
+        !endTime &&
+        !contractId &&
+        !functionName &&
+        !nonce;
 
       const totalQuery: { count: number }[] = noFilters
         ? await sql<{ count: number }[]>`
@@ -1493,6 +1503,7 @@ export class PgStore extends BasePgStore {
         ${endTimeFilterSql}
         ${contractIdFilterSql}
         ${contractFuncFilterSql}
+        ${nonceFilterSql}
       `;
 
       const resultQuery: ContractTxQueryResult[] = await sql<ContractTxQueryResult[]>`
@@ -1506,6 +1517,7 @@ export class PgStore extends BasePgStore {
         ${endTimeFilterSql}
         ${contractIdFilterSql}
         ${contractFuncFilterSql}
+        ${nonceFilterSql}
         ${orderBySql}
         LIMIT ${limit}
         OFFSET ${offset}

src/tests/tx-tests.ts

@@ -2469,6 +2469,84 @@ describe('tx tests', () => {
     );
   });
 
+  test('tx list - filter by nonce', async () => {
+    const testSendertAddr = 'ST27W5M8BRKA7C5MZE2R1S1F4XTPHFWFRNHA9M04Y';
+    const block1 = new TestBlockBuilder({
+      block_height: 1,
+      index_block_hash: '0x01',
+      burn_block_time: 1710000000,
+    })
+      .addTx({
+        tx_id: '0x1234',
+        fee_rate: 1n,
+        sender_address: testSendertAddr,
+        nonce: 1,
+      })
+      .build();
+
+    await db.update(block1);
+
+    const block2 = new TestBlockBuilder({
+      block_height: 2,
+      index_block_hash: '0x02',
+      parent_block_hash: block1.block.block_hash,
+      parent_index_block_hash: block1.block.index_block_hash,
+      burn_block_time: 1720000000,
+    })
+      .addTx({
+        tx_id: '0x2234',
+        fee_rate: 3n,
+        sender_address: testSendertAddr,
+        nonce: 2,
+      })
+      .build();
+    await db.update(block2);
+
+    const block3 = new TestBlockBuilder({
+      block_height: 3,
+      index_block_hash: '0x03',
+      parent_block_hash: block2.block.block_hash,
+      parent_index_block_hash: block2.block.index_block_hash,
+      burn_block_time: 1730000000,
+    })
+      .addTx({
+        tx_id: '0x3234',
+        fee_rate: 2n,
+        sender_address: testSendertAddr,
+        nonce: 3,
+      })
+      .build();
+    await db.update(block3);
+
+    const txsReq1 = await supertest(api.server).get(
+      `/extended/v1/tx?from_address=${testSendertAddr}&nonce=${1}`
+    );
+    expect(txsReq1.status).toBe(200);
+    expect(txsReq1.body).toEqual(
+      expect.objectContaining({
+        results: [
+          expect.objectContaining({
+            tx_id: block1.txs[0].tx.tx_id,
+          }),
+        ],
+      })
+    );
+
+    const txsReq2 = await supertest(api.server).get(
+      `/extended/v1/tx?from_address=${testSendertAddr}&nonce=${2}`
+    );
+    expect(txsReq2.status).toBe(200);
+    expect(txsReq2.body).toEqual(
+      expect.objectContaining({
+        results: [
+          expect.objectContaining({
+            tx_id: block2.txs[0].tx.tx_id,
+          }),
+        ],
+      })
+    );
+  });
+
   test('fetch raw tx', async () => {
     const block: DbBlock = {
       block_hash: '0x1234',