Add LockingApi.getLeaderBoardV2 (safe-global#1550)

Adds LockingApi.getLeaderBoardV2 datasource function.
Adds Holder entity.

Author: hectorgomezv

src/datasources/locking-api/locking-api.service.spec.ts

@@ -14,6 +14,7 @@ import {
 import { getAddress } from 'viem';
 import { rankBuilder } from '@/domain/locking/entities/__tests__/rank.builder';
 import { campaignBuilder } from '@/domain/locking/entities/__tests__/campaign.builder';
+import { holderBuilder } from '@/domain/locking/entities/__tests__/holder.builder';
 
 const networkService = {
   get: jest.fn(),
@@ -264,6 +265,78 @@ describe('LockingApi', () => {
     });
   });
 
+  describe('getLeaderboardV2', () => {
+    it('should get leaderboard v2', async () => {
+      const campaignId = faker.string.uuid();
+      const leaderboardV2Page = pageBuilder()
+        .with('results', [holderBuilder().build(), holderBuilder().build()])
+        .build();
+      mockNetworkService.get.mockResolvedValueOnce({
+        data: leaderboardV2Page,
+        status: 200,
+      });
+
+      const result = await service.getLeaderboardV2({ campaignId });
+
+      expect(result).toEqual(leaderboardV2Page);
+      expect(mockNetworkService.get).toHaveBeenCalledWith({
+        url: `${lockingBaseUri}/api/v2/leaderboard/${campaignId}`,
+        networkRequest: {
+          params: {
+            limit: undefined,
+            offset: undefined,
+          },
+        },
+      });
+    });
+
+    it('should forward pagination queries', async () => {
+      const limit = faker.number.int();
+      const offset = faker.number.int();
+      const campaignId = faker.string.uuid();
+      const leaderboardV2Page = pageBuilder()
+        .with('results', [holderBuilder().build(), holderBuilder().build()])
+        .build();
+      mockNetworkService.get.mockResolvedValueOnce({
+        data: leaderboardV2Page,
+        status: 200,
+      });
+
+      await service.getLeaderboardV2({ campaignId, limit, offset });
+
+      expect(mockNetworkService.get).toHaveBeenCalledWith({
+        url: `${lockingBaseUri}/api/v2/leaderboard/${campaignId}`,
+        networkRequest: {
+          params: {
+            limit,
+            offset,
+          },
+        },
+      });
+    });
+
+    it('should forward error', async () => {
+      const status = faker.internet.httpStatusCode({ types: ['serverError'] });
+      const campaignId = faker.string.uuid();
+      const error = new NetworkResponseError(
+        new URL(`${lockingBaseUri}/api/v2/leaderboard/${campaignId}`),
+        {
+          status,
+        } as Response,
+        {
+          message: 'Unexpected error',
+        },
+      );
+      mockNetworkService.get.mockRejectedValueOnce(error);
+
+      await expect(service.getLeaderboardV2({ campaignId })).rejects.toThrow(
+        new DataSourceError('Unexpected error', status),
+      );
+
+      expect(mockNetworkService.get).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('getLockingHistory', () => {
     it('should get locking history', async () => {
       const safeAddress = getAddress(faker.finance.ethereumAddress());

src/datasources/locking-api/locking-api.service.ts

@@ -7,6 +7,7 @@ import {
 import { Page } from '@/domain/entities/page.entity';
 import { ILockingApi } from '@/domain/interfaces/locking-api.interface';
 import { Campaign } from '@/domain/locking/entities/campaign.entity';
+import { Holder } from '@/domain/locking/entities/holder.entity';
 import { LockingEvent } from '@/domain/locking/entities/locking-event.entity';
 import { Rank } from '@/domain/locking/entities/rank.entity';
 import { Inject } from '@nestjs/common';
@@ -87,6 +88,28 @@ export class LockingApi implements ILockingApi {
     }
   }
 
+  async getLeaderboardV2(args: {
+    campaignId: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<Page<Holder>> {
+    try {
+      const url = `${this.baseUri}/api/v2/leaderboard/${args.campaignId}`;
+      const { data } = await this.networkService.get<Page<Holder>>({
+        url,
+        networkRequest: {
+          params: {
+            limit: args.limit,
+            offset: args.offset,
+          },
+        },
+      });
+      return data;
+    } catch (error) {
+      throw this.httpErrorFactory.from(error);
+    }
+  }
+
   async getLockingHistory(args: {
     safeAddress: `0x${string}`;
     limit?: number;

src/domain/locking/entities/__tests__/holder.builder.ts

@@ -0,0 +1,13 @@
+import { Builder, IBuilder } from '@/__tests__/builder';
+import { Holder } from '@/domain/locking/entities/holder.entity';
+import { faker } from '@faker-js/faker';
+import { getAddress } from 'viem';
+
+export function holderBuilder(): IBuilder<Holder> {
+  return new Builder<Holder>()
+    .with('holder', getAddress(faker.finance.ethereumAddress()))
+    .with('position', faker.number.int())
+    .with('boost', faker.string.numeric())
+    .with('points', faker.string.numeric())
+    .with('boostedPoints', faker.string.numeric());
+}

src/domain/locking/entities/holder.entity.ts

@@ -0,0 +1,16 @@
+import { buildPageSchema } from '@/domain/entities/schemas/page.schema.factory';
+import { AddressSchema } from '@/validation/entities/schemas/address.schema';
+import { NumericStringSchema } from '@/validation/entities/schemas/numeric-string.schema';
+import { z } from 'zod';
+
+export const HolderSchema = z.object({
+  holder: AddressSchema,
+  position: z.number(),
+  boost: NumericStringSchema,
+  points: NumericStringSchema,
+  boostedPoints: NumericStringSchema,
+});
+
+export const HolderPageSchema = buildPageSchema(HolderSchema);
+
+export type Holder = z.infer<typeof HolderSchema>;

src/domain/locking/entities/schemas/__tests__/holder.schema.spec.ts

@@ -0,0 +1,76 @@
+import { holderBuilder } from '@/domain/locking/entities/__tests__/holder.builder';
+import { HolderSchema } from '@/domain/locking/entities/holder.entity';
+import { faker } from '@faker-js/faker';
+import { getAddress } from 'viem';
+import { ZodError } from 'zod';
+
+describe('HolderSchema', () => {
+  it('should validate a valid holder', () => {
+    const holder = holderBuilder().build();
+
+    const result = HolderSchema.safeParse(holder);
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should checksum the holder address', () => {
+    const nonChecksummedAddress = faker.finance
+      .ethereumAddress()
+      .toLowerCase() as `0x${string}`;
+    const holder = holderBuilder()
+      .with('holder', nonChecksummedAddress)
+      .build();
+
+    const result = HolderSchema.safeParse(holder);
+
+    expect(result.success && result.data.holder).toBe(
+      getAddress(nonChecksummedAddress),
+    );
+  });
+
+  it('should not validate an invalid holder', () => {
+    const holder = { invalid: 'holder' };
+
+    const result = HolderSchema.safeParse(holder);
+
+    expect(!result.success && result.error).toStrictEqual(
+      new ZodError([
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          received: 'undefined',
+          path: ['holder'],
+          message: 'Required',
+        },
+        {
+          code: 'invalid_type',
+          expected: 'number',
+          received: 'undefined',
+          path: ['position'],
+          message: 'Required',
+        },
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          received: 'undefined',
+          path: ['boost'],
+          message: 'Required',
+        },
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          received: 'undefined',
+          path: ['points'],
+          message: 'Required',
+        },
+        {
+          code: 'invalid_type',
+          expected: 'string',
+          received: 'undefined',
+          path: ['boostedPoints'],
+          message: 'Required',
+        },
+      ]),
+    );
+  });
+});