LW-12083 feat(cardano-services-client): restore KoraLabsHandleProvider

.github/workflows/continuous-integration-unit-tests.yaml

@@ -42,5 +42,6 @@ jobs:
       - name: 🔬 Test
         run: |
           yarn test --forceExit
+          yarn test:handle
         env:
           NODE_OPTIONS: '--max_old_space_size=8192'

packages/cardano-services-client/package.json

@@ -60,6 +60,7 @@
     "@cardano-sdk/core": "workspace:~",
     "@cardano-sdk/crypto": "workspace:~",
     "@cardano-sdk/util": "workspace:~",
+    "@koralabs/handles-public-api-interfaces": "^2.13.0",
     "axios": "^1.7.4",
     "class-validator": "^0.14.0",
     "isomorphic-ws": "^5.0.0",

packages/cardano-services-client/src/HandleProvider/KoraLabsHandleProvider.ts

@@ -0,0 +1,100 @@
+import {
+  Asset,
+  Cardano,
+  HandleProvider,
+  HandleResolution,
+  HealthCheckResponse,
+  ProviderError,
+  ProviderFailure,
+  ResolveHandlesArgs
+} from '@cardano-sdk/core';
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { IHandle } from '@koralabs/handles-public-api-interfaces';
+import axios, { AxiosAdapter, AxiosInstance } from 'axios';
+
+/** The KoraLabsHandleProvider endpoint paths. */
+const paths = {
+  handles: '/handles',
+  healthCheck: '/health'
+};
+
+export interface KoraLabsHandleProviderDeps {
+  serverUrl: string;
+  adapter?: AxiosAdapter;
+  policyId: Cardano.PolicyId;
+}
+
+export const toHandleResolution = ({
+  apiResponse,
+  policyId
+}: {
+  apiResponse: IHandle;
+  policyId: Cardano.PolicyId;
+}): HandleResolution => ({
+  backgroundImage: apiResponse.bg_image ? Asset.Uri(apiResponse.bg_image) : undefined,
+  cardanoAddress: Cardano.PaymentAddress(apiResponse.resolved_addresses.ada),
+  handle: apiResponse.name,
+  hasDatum: apiResponse.has_datum,
+  image: apiResponse.image ? Asset.Uri(apiResponse.image) : undefined,
+  policyId,
+  profilePic: apiResponse.pfp_image ? Asset.Uri(apiResponse.pfp_image) : undefined
+});
+
+/**
+ * Creates a KoraLabs Provider instance to resolve Standard Handles
+ *
+ * @param KoraLabsHandleProviderDeps The configuration object fot the KoraLabs Handle Provider.
+ */
+export class KoraLabsHandleProvider implements HandleProvider {
+  private axiosClient: AxiosInstance;
+  policyId: Cardano.PolicyId;
+
+  constructor({ serverUrl, adapter, policyId }: KoraLabsHandleProviderDeps) {
+    this.axiosClient = axios.create({
+      adapter,
+      baseURL: serverUrl
+    });
+    this.policyId = policyId;
+  }
+
+  resolveHandles({ handles }: ResolveHandlesArgs): Promise<Array<HandleResolution | null>> {
+    // eslint-disable-next-line unicorn/consistent-function-scoping
+    const resolveHandle = async (handle: string) => {
+      try {
+        const { data } = await this.axiosClient.get<IHandle>(`${paths.handles}/${handle}`);
+
+        return toHandleResolution({ apiResponse: data, policyId: this.policyId });
+      } catch (error) {
+        if (error instanceof ProviderError) throw error;
+        if (axios.isAxiosError(error)) {
+          if (error.response?.status === 404) return null;
+          if (error.request) throw new ProviderError(ProviderFailure.ConnectionFailure, error, error.code);
+
+          throw new ProviderError(
+            ProviderFailure.Unhealthy,
+            error,
+            `Failed to resolve handles due to: ${error.message}`
+          );
+        }
+
+        throw new ProviderError(ProviderFailure.Unknown, error, 'Failed to resolve handles');
+      }
+    };
+
+    return Promise.all(handles.map((handle) => resolveHandle(handle)));
+  }
+
+  async healthCheck(): Promise<HealthCheckResponse> {
+    try {
+      await this.axiosClient.get(`${paths.healthCheck}`);
+      return { ok: true };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  async getPolicyIds(): Promise<Cardano.PolicyId[]> {
+    return [this.policyId];
+  }
+}

packages/cardano-services-client/src/HandleProvider/index.ts

@@ -1 +1,2 @@
+export * from './KoraLabsHandleProvider';
 export * from './handleHttpProvider';

packages/cardano-services-client/test/HandleProvider/KoraLabsHandleProvider.test.ts

@@ -0,0 +1,110 @@
+/* eslint-disable no-magic-numbers */
+/* eslint-disable camelcase */
+import { Cardano, ProviderError } from '@cardano-sdk/core';
+import { KoraLabsHandleProvider } from '../../src';
+import {
+  getAliceHandleAPIResponse,
+  getAliceHandleProviderResponse,
+  getBobHandleAPIResponse,
+  getBobHandleProviderResponse
+} from '../util';
+import MockAdapter from 'axios-mock-adapter';
+import axios from 'axios';
+
+const config = {
+  policyId: Cardano.PolicyId('50fdcdbfa3154db86a87e4b5697ae30d272e0bbcfa8122efd3e301cb'),
+  serverUrl: 'http://some-hostname:3000'
+};
+
+describe('KoraLabsHandleProvider', () => {
+  let axiosMock: MockAdapter;
+  let provider: KoraLabsHandleProvider;
+
+  beforeAll(() => {
+    axiosMock = new MockAdapter(axios);
+    provider = new KoraLabsHandleProvider(config);
+  });
+
+  afterEach(() => {
+    axiosMock.reset();
+  });
+
+  afterAll(() => {
+    axiosMock.restore();
+  });
+
+  describe('resolveHandles', () => {
+    test('HandleProvider should resolve a single handle', async () => {
+      axiosMock.onGet().replyOnce(200, getAliceHandleAPIResponse);
+      const args = {
+        handles: ['alice']
+      };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([getAliceHandleProviderResponse]);
+    });
+
+    test('HandleProvider should resolve multiple handles', async () => {
+      axiosMock.onGet().replyOnce(200, getAliceHandleAPIResponse).onGet().replyOnce(200, getBobHandleAPIResponse);
+      const args = {
+        handles: ['alice', 'bob']
+      };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([
+        getAliceHandleProviderResponse,
+        getBobHandleProviderResponse
+      ]);
+    });
+  });
+
+  describe('error checks', () => {
+    test('HandleProvider should throw ProviderError with ConnectionFailure on request error', async () => {
+      axiosMock.onGet('/handles/alice').networkError();
+      const args = { handles: ['alice'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should return null for 404 response from API', async () => {
+      axiosMock.onGet('/handles/alice').reply(404);
+      const args = { handles: ['alice'] };
+      await expect(provider.resolveHandles(args)).resolves.toEqual([null]);
+    });
+    test('HandleProvider should throw ProviderError with Unhealthy on other Axios error', async () => {
+      axiosMock.onGet('/handles/bob').reply(500);
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should throw ProviderError', async () => {
+      axiosMock.onGet('/handles/bob').networkError();
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+    test('HandleProvider should throw ProviderError with Unknown, unable to resolve handle', async () => {
+      axiosMock.onGet().replyOnce(304, getAliceHandleAPIResponse);
+      const args = { handles: ['bob'] };
+      await expect(provider.resolveHandles(args)).rejects.toThrowError(ProviderError);
+    });
+  });
+
+  describe('health checks', () => {
+    test('HandleProvider should get ok health check', async () => {
+      axiosMock.onGet().replyOnce(200, {});
+      const result = await provider.healthCheck();
+      expect(result.ok).toEqual(true);
+    });
+
+    test('HandleProvider should get not ok health check', async () => {
+      const providerWithBadConfig = new KoraLabsHandleProvider({
+        policyId: Cardano.PolicyId('50fdcdbfa3154db86a87e4b5697ae30d272e0bbcfa8122efd3e301cb'),
+        serverUrl: ''
+      });
+      const result = await providerWithBadConfig.healthCheck();
+      expect(result.ok).toEqual(false);
+    });
+  });
+
+  describe('get policy ids', () => {
+    test('HandleProvider should get handle policy ids', async () => {
+      const policyIds = await provider.getPolicyIds();
+
+      expect(policyIds.length).toEqual(1);
+      expect(policyIds).toEqual([config.policyId]);
+    });
+  });
+});

packages/cardano-services-client/test/util.ts

@@ -1,5 +1,6 @@
 import { Asset, Cardano, ProviderError, ProviderFailure } from '@cardano-sdk/core';
 import { AxiosError, AxiosResponse } from 'axios';
+import { IHandle, Rarity } from '@koralabs/handles-public-api-interfaces';
 import { logger } from '@cardano-sdk/util-dev';
 import { toSerializableObject } from '@cardano-sdk/util';
 
@@ -61,6 +62,50 @@ export const getBobHandleProviderResponse = {
   profilePic: Asset.Uri('ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd1')
 };
 
+export const getAliceHandleAPIResponse: Partial<IHandle> = {
+  characters: 'rljm7n/23455',
+  created_slot_number: 33,
+  default_in_wallet: 'alice_default_hndle',
+  has_datum: false,
+  hex: '0f3abbc8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe0e78f19d9d5',
+  holder: 'stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw',
+  image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasd',
+  length: 123,
+  name: 'alice',
+  numeric_modifiers: '-12.9',
+  og_number: 5,
+  rarity: Rarity.rare,
+  resolved_addresses: {
+    ada: 'addr_test1qqk4sr4f7vtqzd2w90d5nfu3n59jhhpawyphnek2y7er02nkrezryq3ydtmkg0e7e2jvzg443h0ffzfwd09wpcxy2fuqmcnecd'
+  },
+  standard_image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasdfasd',
+  updated_slot_number: 22,
+  utxo: 'rljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0'
+};
+
+export const getBobHandleAPIResponse: Partial<IHandle> = {
+  bg_image: 'ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd',
+  characters: 'rljm7n/23455',
+  created_slot_number: 33,
+  default_in_wallet: 'bob_default_handle',
+  has_datum: false,
+  hex: '0f3abbc8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe0e78f19d9d5',
+  holder: 'stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw',
+  image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56fe',
+  length: 123,
+  name: 'bob',
+  numeric_modifiers: '-12.9',
+  og_number: 5,
+  pfp_image: 'ipfs://zrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3yd1',
+  rarity: Rarity.rare,
+  resolved_addresses: {
+    ada: 'addr_test1qzrljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0e7e2jvzg443h0ffzfwd09wpcxy2fuql9tk0g'
+  },
+  standard_image: 'ipfs://c8fc19c2e61bab6059bf8a466e6e754833a08a62a6c56feasdfasd',
+  updated_slot_number: 22,
+  utxo: 'rljm7nskakjydxlr450ktsj08zuw6aktvgfkmmyw9semrkrezryq3ydtmkg0'
+};
+
 export const mockResponses = (request: jest.Mock, responses: [string | RegExp, unknown][]) => {
   request.mockImplementation(async (endpoint: string) => {
     for (const [match, response] of responses) {

packages/e2e/jest.config.js

@@ -27,6 +27,7 @@ module.exports = {
   projects: [
     { ...project('blockfrost'), globalSetup: './test/blockfrost/setup.ts' },
     project('blockfrost-providers'),
+    project('handle'),
     project('local-network'),
     project('long-running'),
     project('ogmios'),

packages/e2e/package.json

@@ -24,6 +24,7 @@
     "test": "echo 'test' command not implemented yet",
     "test:blockfrost": "jest -c jest.config.js --forceExit --selectProjects blockfrost --runInBand --verbose",
     "test:utils": "jest -c jest.config.js --forceExit --selectProjects utils --verbose",
+    "test:handle": "jest -c jest.config.js --forceExit --selectProjects handle --runInBand --verbose",
     "test:long-running": "jest -c jest.config.js --forceExit --selectProjects long-running --runInBand --verbose",
     "test:local-network": "jest -c jest.config.js --forceExit --selectProjects local-network --runInBand --verbose",
     "test:projection": "jest -c jest.config.js --forceExit --selectProjects projection --runInBand --verbose",

packages/e2e/test/handle/KoraLabsHandleProvider.test.ts

@@ -0,0 +1,73 @@
+/* eslint-disable no-magic-numbers */
+/* eslint-disable camelcase */
+import { Cardano, HandleResolution } from '@cardano-sdk/core';
+import { KoraLabsHandleProvider } from '@cardano-sdk/cardano-services-client';
+
+const handlePolicyId = 'f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a';
+
+const config = {
+  policyId: Cardano.PolicyId(handlePolicyId),
+  serverUrl: 'https://preprod.api.handle.me/'
+};
+
+const checkHandleResolution = (source: string, result: unknown) => {
+  expect(typeof result).toBe('object');
+
+  const { backgroundImage, cardanoAddress, handle, hasDatum, image, policyId, profilePic } = result as HandleResolution;
+
+  expect(['string', 'undefined']).toContain(typeof backgroundImage);
+  expect(typeof cardanoAddress).toBe('string');
+  expect(cardanoAddress.startsWith('addr_')).toBe(true);
+  expect(handle).toBe(source);
+  expect(typeof hasDatum).toBe('boolean');
+  expect(typeof image).toBe('string');
+  expect(policyId).toBe(handlePolicyId);
+  expect(['string', 'undefined']).toContain(typeof profilePic);
+};
+
+describe('KoraLabsHandleProvider', () => {
+  let provider: KoraLabsHandleProvider;
+
+  beforeAll(() => {
+    provider = new KoraLabsHandleProvider(config);
+  });
+
+  describe('resolveHandles', () => {
+    test('HandleProvider should resolve a single handle', async () => {
+      const [result] = await provider.resolveHandles({ handles: ['test_handle_1'] });
+
+      checkHandleResolution('test_handle_1', result);
+    });
+
+    test('HandleProvider should resolve multiple handles', async () => {
+      const [result2, result3] = await provider.resolveHandles({ handles: ['test_handle_2', 'test_handle_3'] });
+
+      checkHandleResolution('test_handle_2', result2);
+      checkHandleResolution('test_handle_3', result3);
+    });
+
+    test('HandleProvider should return null for for not found handle', async () => {
+      const [resultN, result1] = await provider.resolveHandles({ handles: ['does_not_exists', 'test_handle_1'] });
+
+      expect(resultN).toBe(null);
+      checkHandleResolution('test_handle_1', result1);
+    });
+  });
+
+  describe('health checks', () => {
+    test('HandleProvider should get ok health check', async () => {
+      const result = await provider.healthCheck();
+
+      expect(result.ok).toEqual(true);
+    });
+  });
+
+  describe('get policy ids', () => {
+    test('HandleProvider should get handle policy ids', async () => {
+      const policyIds = await provider.getPolicyIds();
+
+      expect(policyIds.length).toEqual(1);
+      expect(policyIds).toEqual([config.policyId]);
+    });
+  });
+});

yarn-project.nix

@@ -493,6 +493,7 @@ cacheEntries = {
 "@jridgewell/trace-mapping@npm:0.3.25" = { filename = "@jridgewell-trace-mapping-npm-0.3.25-c076fd2279-9d3c40d225.zip"; sha512 = "9d3c40d225e139987b50c48988f8717a54a8c994d8a948ee42e1412e08988761d0754d7d10b803061cc3aebf35f92a5dbbab493bd0e1a9ef9e89a2130e83ba34"; };
 "@jridgewell/trace-mapping@npm:0.3.9" = { filename = "@jridgewell-trace-mapping-npm-0.3.9-91625cd7fb-d89597752f.zip"; sha512 = "d89597752fd88d3f3480845691a05a44bd21faac18e2185b6f436c3b0fd0c5a859fbbd9aaa92050c4052caf325ad3e10e2e1d1b64327517471b7d51babc0ddef"; };
 "@jsdevtools/ono@npm:7.1.3" = { filename = "@jsdevtools-ono-npm-7.1.3-cb2313543b-2297fcd472.zip"; sha512 = "2297fcd472ba810bffe8519d2249171132844c7174f3a16634f9260761c8c78bc0428a4190b5b6d72d45673c13918ab9844d706c3ed4ef8f62ab11a2627a08ad"; };
+"@koralabs/handles-public-api-interfaces@npm:2.13.0" = { filename = "@koralabs-handles-public-api-interfaces-npm-2.13.0-33d8afa484-b28895a70e.zip"; sha512 = "b28895a70ecdb1b4643953dd0af11b406970a5388b79889050f19ef01335c7da29fb8696d26e80f645fd435ca8cc90f13b5fed0c4a5ceb0ac0d2447aad5e3e06"; };
 "@ledgerhq/devices@npm:8.4.4" = { filename = "@ledgerhq-devices-npm-8.4.4-9331403bf0-370fb38d48.zip"; sha512 = "370fb38d484665c92165580e285cc792e7af0bf114a5d1e855aec602c6e39592090d0de7a43addeb4c13622f734ddd4f25be82f07507e14550753ce5473eea66"; };
 "@ledgerhq/errors@npm:6.19.1" = { filename = "@ledgerhq-errors-npm-6.19.1-4837ba7170-f4e1cf0d6a.zip"; sha512 = "f4e1cf0d6a5808c58235c54e2a1565556de8e683552bd94d97609f790e8c25226114bfa2af9914bb329c3e7c314585b60c66ddac8d8f8f1d072b7e791a889ad8"; };
 "@ledgerhq/hw-transport-node-hid-noevents@npm:6.30.5" = { filename = "@ledgerhq-hw-transport-node-hid-noevents-npm-6.30.5-19d7e6c1d0-013d7d6745.zip"; sha512 = "013d7d674573b838b3e2d6a750a8e48a1f1722d986c272513de28f68c5a203576e2b39beea1f0ea7ca5e348421b50f79d8af1a30774068479b1fa6526662eae1"; };