@ledgerhq/cryptoassets 13.32.0-nightly.1 → 13.32.0-nightly.2

package/src/cal-client/MIGRATION_GUIDE.md

@@ -0,0 +1,276 @@
+# CAL Client Migration Guide
+
+## Overview
+
+Migrate from `listTokens()` and `listTokensForCryptoCurrency()` to the CAL Client API.
+
+> **Remove CAL Initiative ([LIVE-21487](https://ledgerhq.atlassian.net/browse/LIVE-21487))**: Replace static token lists with dynamic, server-managed asset data. This guide is for the usecases where we still need to list tokens dynamically.
+
+### useTokensData
+
+```typescript
+const { data, isLoading, isSuccess, isError, loadNext, error, refetch } = useTokensData({
+  networkFamily?: string[], // Filter by network families (e.g., ["ethereum", "polygon"])
+  output?: string[], // Specify output fields (e.g., ["id", "name", "ticker", "units", "delisted"])
+  limit?: number, // Maximum number of assets to return
+  pageSize?: number, // Number of items per page (default: 100, options: 10, 100, 1000)
+  ref?: string, // CAL reference (default: "branch:main", can be tag or commit)
+  isStaging?: boolean, // Use staging or production environment
+});
+```
+
+**Data Structure:**
+
+```typescript
+data: {
+  tokens: TokenCurrency[], // Array of token currencies
+  pagination: {
+    nextCursor?: string, // Cursor for next page (if available)
+  }
+}
+```
+
+## Integration on LLD
+
+**Pagination:** Use `react-window`'s `InfiniteLoader` + `FixedSizeList` with `loadMoreItems` callback, or implement scroll detection to call `loadNext`
+
+## Integration on LLM
+
+**Pagination:** Use `BottomSheetVirtualizedList` or `FlatList` with `onEndReached={loadNext}`
+
+## Migration Examples
+
+### 1. Basic Token Lists
+
+**Before:**
+
+```typescript
+import { listTokens } from "@ledgerhq/cryptoassets";
+
+function TokenList() {
+  const tokens = listTokens();
+  return (
+    <div>
+      {tokens.map(token => <div key={token.id}>{token.name}</div>)}
+    </div>
+  );
+}
+```
+
+**After:**
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+
+function TokenList() {
+  const { data, isLoading, loadNext } = useTokensData({
+    pageSize: 100, // Optional: default is 100
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  const tokens = data?.tokens || [];
+
+  return (
+    <SomethingThatManagesInfiniteScrollList
+      data={tokens}
+      renderItem={(token) => (
+        <div key={token.id}>{token.name}</div>
+      )}
+      onScrollEnd={loadNext}
+    />
+  );
+}
+```
+
+### 2. Currency-Specific Tokens (by Network Family)
+
+**Before:**
+
+```typescript
+import { listTokensForCryptoCurrency } from "@ledgerhq/cryptoassets";
+
+function EthereumTokens({ currency }) {
+  const tokens = listTokensForCryptoCurrency(currency);
+  return (
+    <select>
+      {tokens.map(token => (
+        <option key={token.id} value={token.id}>{token.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+**After:**
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+
+function EthereumTokens({ networkFamily }) {
+  const { data, isLoading, loadNext } = useTokensData({
+    networkFamily: [networkFamily], // e.g., ["ethereum"] or ["polygon"]
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  const tokens = data?.tokens || [];
+
+  return (
+    <select>
+      {tokens.map(token => (
+        <option key={token.id} value={token.id}>{token.name}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+**Note:** If you need to filter by a specific parent currency within a network family, you'll need to do client-side filtering:
+
+```typescript
+const tokens = (data?.tokens || []).filter(token => token.parentCurrency?.id === currency.id);
+```
+
+### 3. Search (Client-Side Filtering)
+
+**Before:**
+
+```typescript
+import { listTokens } from "@ledgerhq/cryptoassets";
+
+function SearchableTokens({ searchQuery }) {
+  const allTokens = listTokens();
+  const filteredTokens = allTokens.filter(token =>
+    token.name.toLowerCase().includes(searchQuery.toLowerCase())
+  );
+  return (
+    <div>
+      {filteredTokens.map(token => <div key={token.id}>{token.name}</div>)}
+    </div>
+  );
+}
+```
+
+**After:**
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+import { useMemo } from "react";
+
+function SearchableTokens({ searchQuery }) {
+  const { data, isLoading, loadNext } = useTokensData({
+    pageSize: 100,
+  });
+
+  const filteredTokens = useMemo(() => {
+    if (!data?.tokens) return [];
+    if (!searchQuery) return data.tokens;
+
+    const query = searchQuery.toLowerCase();
+    return data.tokens.filter(token =>
+      token.name.toLowerCase().includes(query) ||
+      token.ticker.toLowerCase().includes(query)
+    );
+  }, [data?.tokens, searchQuery]);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <SomethingThatManagesInfiniteScrollList
+      data={filteredTokens}
+      renderItem={(token) => <div key={token.id}>{token.name}</div>}
+      onScrollEnd={loadNext}
+    />
+  );
+}
+```
+
+## Advanced Usage
+
+### 4. Optimizing Performance with Specific Output Fields
+
+If you only need certain fields from the token data, you can specify them to reduce payload size:
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+
+function TokenDropdown() {
+  const { data, isLoading } = useTokensData({
+    output: ["id", "name", "ticker"], // Only fetch what you need
+    networkFamily: ["ethereum"],
+    pageSize: 100,
+  });
+
+  if (isLoading) return <select disabled>Loading...</select>;
+
+  return (
+    <select>
+      {data?.tokens.map(token => (
+        <option key={token.id} value={token.id}>
+          {token.name} ({token.ticker})
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### 5. Using a Specific CAL Version
+
+To ensure consistent data across deployments, you can specify a particular CAL version:
+
+```typescript
+const { data, isLoading } = useTokensData({
+  ref: "tag:tokens-1.11.12", // Use a specific tag
+  // ref: "branch:main", // Default: latest main branch
+  // ref: "commit:48188c6ca2888a9c50a0466d2442ec2f24cc2852", // Specific commit
+});
+```
+
+### 6. Limiting Total Results
+
+For use cases where you only need a subset of tokens (e.g., displaying top tokens):
+
+```typescript
+const { data, isLoading } = useTokensData({
+  limit: 50, // Only fetch first 50 tokens
+  pageSize: 50, // Match page size to limit for single request
+  networkFamily: ["ethereum"],
+});
+```
+
+### 7. Using Staging Environment
+
+For testing with staging data:
+
+```typescript
+const { data, isLoading, isError } = useTokensData({
+  isStaging: true, // Use staging API
+  networkFamily: ["ethereum"],
+});
+```
+
+## Future Evolution
+
+The CAL Client is actively evolving and will be enhanced based on real-world usage and requirements. As we gather feedback from implementations across LLD and LLM, we plan to add:
+
+- **Server-side search capabilities** - To optimize search performance for large datasets
+- **Additional filtering options** - More granular filtering based on specific use cases
+- **Caching strategies** - Improved caching mechanisms for better performance
+- **Additional hooks** - Specialized hooks for common patterns (e.g., `useTokensByNetwork`, `useTokenSearch`)
+- **Enhanced error handling** - More detailed error types and recovery strategies
+
+**Have a specific use case or need?** Feel free to reach out to the team or create an issue. We're committed to evolving the API based on your needs while maintaining backward compatibility where possible.
+
+## Migration Checklist
+
+- [ ] Replace `listTokens()` calls with `useTokensData({})`
+- [ ] Replace `listTokensForCryptoCurrency()` with `useTokensData({ networkFamily: [...] })`
+- [ ] Update component to handle async loading state
+- [ ] Implement pagination if displaying large lists
+- [ ] Update data access from flat array to `data?.tokens`
+- [ ] Add client-side filtering if search functionality is needed
+- [ ] Consider using `output` parameter to optimize payload size
+- [ ] Test with different network families
+- [ ] Verify error handling is in place

package/src/cal-client/README.md

@@ -0,0 +1,125 @@
+# CAL Client
+
+**CAL** stands for **Crypto Assets List** - a data management system for fetching and managing token data across different blockchain networks.
+
+## Installation
+
+The CAL client is included in `@ledgerhq/cryptoassets`
+
+## Usage Examples
+
+### Basic Usage with React
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+
+// Fetch tokens data
+const TokensList = () => {
+  const { data, isLoading, error, loadNext, isSuccess } = useTokensData({
+    networkFamily: ["ethereum", "polygon"],
+    pageSize: 100,
+    isStaging: false,
+  });
+
+  if (isLoading) return <div>Loading tokens...</div>;
+  if (error) return <div>Error loading tokens</div>;
+
+  return (
+    <div>
+      {data?.tokens.map(token => (
+        <div key={token.id}>
+          <span>{token.name} ({token.ticker})</span>
+          <span>Contract: {token.contractAddress}</span>
+          <span>Network: {token.parentCurrency.name}</span>
+        </div>
+      ))}
+      {loadNext && <button onClick={() => loadNext()}>Load More</button>}
+    </div>
+  );
+};
+```
+
+### Desktop Integration (Redux)
+
+```typescript
+import { cryptoAssetsApi } from "@ledgerhq/cryptoassets/cal-client/state-manager/api";
+
+// Configure Redux store
+const store = configureStore({
+  reducer: {
+    // ... other reducers
+    [cryptoAssetsApi.reducerPath]: cryptoAssetsApi.reducer,
+  },
+  middleware: getDefaultMiddleware => getDefaultMiddleware().concat(cryptoAssetsApi.middleware),
+});
+```
+
+### Advanced Usage with Pagination
+
+```typescript
+import { useTokensData } from "@ledgerhq/cryptoassets/cal-client/hooks/useTokensData";
+
+const InfiniteTokensList = () => {
+  const {
+    data,
+    isLoading,
+    loadNext,
+    refetch
+  } = useTokensData({
+    networkFamily: ["ethereum"],
+    pageSize: 100,
+    output: ["id", "name", "ticker", "contract_address"],
+  });
+
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+      {data?.tokens.map(token => (
+        <TokenCard key={token.id} token={token} />
+      ))}
+      {loadNext && <button onClick={() => loadNext()}>Load More</button>}
+    </div>
+  );
+};
+```
+
+## API Reference
+
+### Hooks
+
+- `useTokensData(params)` - Fetch paginated tokens data with infinite scroll support
+  - **Parameters:**
+    - `networkFamily?: string[]` - Filter by network families (e.g., ["ethereum", "polygon"])
+    - `pageSize?: number` - Number of items per page (default: 100, options: 10, 100, 1000)
+    - `isStaging?: boolean` - Use staging environment
+    - `output?: string[]` - Specify output fields (default: all fields)
+  - **Returns:**
+    - `data: TokensDataWithPagination` - Token data with pagination info
+    - `isLoading: boolean` - Initial loading state
+    - `error: any` - Error object if request failed
+    - `loadNext?: () => void` - Function to load next page (undefined if no more pages)
+    - `isSuccess: boolean` - Whether the request succeeded
+    - `isError: boolean` - Whether the request failed
+    - `refetch: () => void` - Function to refetch data
+
+### Types
+
+```typescript
+interface TokensDataWithPagination {
+  tokens: TokenCurrency[];
+  pagination: {
+    nextCursor?: string;
+  };
+}
+
+interface GetTokensDataParams {
+  networkFamily?: string[];
+  isStaging?: boolean;
+  pageSize?: number;
+  output?: string[];
+}
+```
+
+## Integration
+
+For custom implementations, ensure you include the `cryptoAssetsApi` reducer and middleware in your Redux store configuration. The CAL client uses RTK Query for efficient data fetching and caching.

package/src/cal-client/entities/index.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for token unit
+ */
+export const TokenUnitSchema = z.object({
+  /** Code identifier for the unit */
+  code: z.string(),
+  /** Display name of the unit */
+  name: z.string(),
+  /** Magnitude (number of decimals) */
+  magnitude: z.number(),
+});
+
+export type TokenUnit = z.infer<typeof TokenUnitSchema>;
+
+/**
+ * Zod schema for API token response
+ */
+export const ApiTokenResponseSchema = z.object({
+  /** Type of asset (token or currency) */
+  type: z.string(),
+  /** Unique identifier for the token */
+  id: z.string(),
+  /** Smart contract address */
+  contract_address: z.string(),
+  /** Token standard (e.g., erc20, bep20, spl) */
+  standard: z.string(),
+  /** Number of decimals */
+  decimals: z.number(),
+  /** Network identifier (e.g., arbitrum, ethereum) */
+  network: z.string(),
+  /** Network family (e.g., ethereum, solana) */
+  network_family: z.string(),
+  /** Whether the token is delisted */
+  delisted: z.boolean(),
+  /** Full name of the token */
+  name: z.string(),
+  /** Ticker symbol */
+  ticker: z.string(),
+  /** Array of unit representations */
+  units: z.array(TokenUnitSchema).min(1),
+  /** Symbol */
+  symbol: z.string(),
+  /** Chain ID */
+  chain_id: z.string(),
+  /** Token identifier */
+  token_identifier: z.string(),
+  /** Network type */
+  network_type: z.string(),
+  /** Meta currency ID */
+  meta_currency_id: z.string(),
+  /** Blockchain name */
+  blockchain_name: z.string(),
+  /** Live signature */
+  live_signature: z.string(),
+});
+
+export type ApiTokenResponse = z.infer<typeof ApiTokenResponseSchema>;

package/src/cal-client/hooks/__tests__/useTokensData.test.ts

@@ -0,0 +1,222 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { renderHook } from "@testing-library/react";
+import { useTokensData } from "../useTokensData";
+import { useGetTokensDataInfiniteQuery } from "../../state-manager/api";
+
+jest.mock("../../state-manager/api", () => ({
+  useGetTokensDataInfiniteQuery: jest.fn(),
+}));
+
+const mockUseGetTokensDataInfiniteQuery = jest.mocked(useGetTokensDataInfiniteQuery);
+
+const defaultMockValues = {
+  data: undefined,
+  isLoading: false,
+  error: undefined,
+  fetchNextPage: jest.fn(),
+  isSuccess: true,
+  isFetching: false,
+  isError: false,
+  fetchPreviousPage: jest.fn(),
+  isFetchingPreviousPage: false,
+  refetch: jest.fn(),
+  status: "success",
+};
+
+describe("useAssetsData", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should return loading state when API is loading", () => {
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+      isLoading: true,
+      status: "pending",
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.data).toBe(undefined);
+  });
+
+  it("should return combined data from multiple pages", () => {
+    const mockPages = [
+      {
+        tokens: [
+          {
+            id: "token-1",
+            name: "Token 1",
+            ticker: "T1",
+            contractAddress: "0x123",
+            parentCurrency: { id: "currency-1", name: "Currency 1" },
+          },
+          {
+            id: "token-2",
+            name: "Token 2",
+            ticker: "T2",
+            contractAddress: "0x456",
+            parentCurrency: { id: "currency-2", name: "Currency 2" },
+          },
+        ],
+        pagination: { nextCursor: "cursor-2" },
+      },
+      {
+        tokens: [
+          {
+            id: "token-3",
+            name: "Token 3",
+            ticker: "T3",
+            contractAddress: "0x789",
+            parentCurrency: { id: "currency-3", name: "Currency 3" },
+          },
+        ],
+        pagination: { nextCursor: undefined },
+      },
+    ];
+
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+      data: { pages: mockPages, pageParams: [{ cursor: "" }, { cursor: "cursor-2" }] },
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.data).toEqual({
+      tokens: [
+        {
+          id: "token-1",
+          name: "Token 1",
+          ticker: "T1",
+          contractAddress: "0x123",
+          parentCurrency: { id: "currency-1", name: "Currency 1" },
+        },
+        {
+          id: "token-2",
+          name: "Token 2",
+          ticker: "T2",
+          contractAddress: "0x456",
+          parentCurrency: { id: "currency-2", name: "Currency 2" },
+        },
+        {
+          id: "token-3",
+          name: "Token 3",
+          ticker: "T3",
+          contractAddress: "0x789",
+          parentCurrency: { id: "currency-3", name: "Currency 3" },
+        },
+      ],
+      pagination: { nextCursor: undefined },
+    });
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("should return error when API has error", () => {
+    const mockError = new Error("API Error");
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+      data: undefined,
+      error: mockError,
+      isSuccess: false,
+      isError: true,
+      status: "error",
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.error).toBe(mockError);
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("should provide loadNext function when there's a nextCursor", () => {
+    const mockFetchNextPage = jest.fn();
+    const mockPages = [
+      {
+        tokens: [],
+        pagination: { nextCursor: "next-cursor-456" },
+      },
+    ];
+
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+      data: { pages: mockPages, pageParams: [{ cursor: "" }] },
+      fetchNextPage: mockFetchNextPage,
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.loadNext).toBeDefined();
+    result.current.loadNext?.();
+
+    expect(mockFetchNextPage).toHaveBeenCalled();
+  });
+
+  it("should not provide loadNext function when there's no nextCursor", () => {
+    const mockPages = [
+      {
+        tokens: [],
+        pagination: { nextCursor: undefined },
+      },
+    ];
+
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+      data: { pages: mockPages, pageParams: [{ cursor: "" }] },
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.loadNext).toBeUndefined();
+  });
+
+  it("should return undefined data when no pages exist", () => {
+    mockUseGetTokensDataInfiniteQuery.mockReturnValue({
+      ...defaultMockValues,
+    });
+
+    const { result } = renderHook(() =>
+      useTokensData({
+        networkFamily: ["ethereum"],
+        pageSize: 100,
+        output: ["id", "name", "ticker", "contract_address"],
+      }),
+    );
+
+    expect(result.current.data).toBeUndefined();
+    expect(result.current.loadNext).toBeUndefined();
+  });
+});

package/src/cal-client/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./useTokensData";