From d1556697cd51222d89df07d585c44b581e25ae03 Mon Sep 17 00:00:00 2001
From: Bobo <bobo.kovacevic@gmail.com>
Date: Thu, 24 Jul 2025 09:51:00 +0200
Subject: [PATCH] Add period block range endpoint

---
 public/swagger.json                         | 34 +++++++++++++++++++++
 src/controllers/DappsStakingV3Controller.ts | 30 ++++++++++++++++++
 src/services/DappsStakingEvents.ts          | 31 +++++++++++++++++++
 3 files changed, 95 insertions(+)

diff --git a/public/swagger.json b/public/swagger.json
index ac7ae87..4894a30 100644
--- a/public/swagger.json
+++ b/public/swagger.json
@@ -1335,6 +1335,40 @@
         }
       }
     },
+    "/api/v3/{network}/dapps-staking/get-period-range/{period}": {
+      "get": {
+        "tags": [
+          "Dapps Staking"
+        ],
+        "description": "Retreives the start and end block numbers for the given dApp staking period.",
+        "parameters": [
+          {
+            "name": "network",
+            "in": "path",
+            "required": true,
+            "type": "string",
+            "description": "The network name. Supported networks: astar",
+            "enum": [
+              "astar",
+              "shiden",
+              "shibuya"
+            ]
+          },
+          {
+            "name": "period",
+            "in": "path",
+            "required": true,
+            "type": "string",
+            "description": "dApp staking period."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
     "/api/v1/{network}/node/tx-perblock/total": {
       "get": {
         "tags": [
diff --git a/src/controllers/DappsStakingV3Controller.ts b/src/controllers/DappsStakingV3Controller.ts
index 78f7696..8d6e6c1 100644
--- a/src/controllers/DappsStakingV3Controller.ts
+++ b/src/controllers/DappsStakingV3Controller.ts
@@ -498,5 +498,35 @@ export class DappsStakingV3Controller extends ControllerBase implements IControl
                 }
             },
         );
+
+        app.route('/api/v3/:network/dapps-staking/get-period-range/:period').get(
+            async (req: Request, res: Response) => {
+                /*
+                    #swagger.description = 'Retreives the start and end block numbers for the given dApp staking period.'
+                    #swagger.tags = ['Dapps Staking']
+                    #swagger.parameters['network'] = {
+                        in: 'path',
+                        description: 'The network name. Supported networks: astar',
+                        required: true,
+                        enum: ['astar', 'shiden', 'shibuya']
+                    }
+                    #swagger.parameters['period'] = {
+                        in: 'path',
+                        description: 'dApp staking period.',
+                        required: true,
+                    }
+                */
+                try {
+                    res.json(
+                        await this._dappsStakingEvents.getPeriodBlockRange(
+                            req.params.network as NetworkType,
+                            Number(req.params.period),
+                        ),
+                    );
+                } catch (err) {
+                    this.handleError(res, err as Error);
+                }
+            },
+        );
     }
 }
diff --git a/src/services/DappsStakingEvents.ts b/src/services/DappsStakingEvents.ts
index 35e3966..125d8d7 100644
--- a/src/services/DappsStakingEvents.ts
+++ b/src/services/DappsStakingEvents.ts
@@ -42,6 +42,7 @@ export interface IDappsStakingEvents {
     getAggregatedPeriodData(network: NetworkType, period: number): Promise<PeriodDataResponse[]>;
     getAggregatedStakerData(network: NetworkType, stakerAddress: string): Promise<StakerPeriodDataResponse[]>;
     getTotalAggregatedStakerData(network: NetworkType, stakerAddress: string): Promise<StakerPeriodTotalResponse>;
+    getPeriodBlockRange(network: NetworkType, period: number): Promise<{ start: number; end?: number }>;
 }
 
 export type RewardEventType = 'Reward' | 'BonusReward' | 'DAppReward';
@@ -616,4 +617,34 @@ export class DappsStakingEvents extends DappStakingV3IndexerBase implements IDap
 
         return total;
     }
+
+    public async getPeriodBlockRange(network: NetworkType, period: number): Promise<{ start: number; end?: number }> {
+        this.GuardNetwork(network);
+        if (period <= 0) {
+            throw new Error('Period must be greater than 0');
+        }
+
+        try {
+            const result = await axios.post(this.getApiUrl(network), {
+                query: `query {
+                    subperiods(orderBy: timestamp_ASC, where: {type_eq: Voting}) {
+                        blockNumber
+                    }
+                }`,
+            });
+
+            const subperiods = result.data.data.subperiods;
+            if (period > subperiods.length) {
+                throw new Error(`Season ${period} not found`);
+            }
+
+            return {
+                start: subperiods[period - 1].blockNumber,
+                end: subperiods[period]?.blockNumber - 1,
+            };
+        } catch (e) {
+            console.error(e);
+            throw new Error('Unable to fetch season block range from a node.');
+        }
+    }
 }