8112223054

Committed 01 Mar 2024 01:36PM UTC coverage: 93.903% (+0.04%) from 93.868%

Build # 8112223054

Build Type

Pull #1228

github

Committed by

hectorgomezv

Commit Message

Add ZerionBalancesApi rate limiter

Pull Request Pull Request #1228: Add Zerion API rate limit

Run Details

1699 of 2026 branches covered (83.86%)

Branch coverage included in aggregate %.

21 of 23 new or added lines in 3 files covered. (91.3%)

3 existing lines in 1 file now uncovered.

6218 of 6405 relevant lines covered (97.08%)

353.38 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

82.8

/src/datasources/balances-api/zerion-balances-api.service.ts

import { IConfigurationService } from '@/config/configuration.service.interface';
import { ChainAttributes } from '@/datasources/balances-api/entities/provider-chain-attributes.entity';
import {
  ZerionAttributes,
  ZerionBalance,
  ZerionBalances,
} from '@/datasources/balances-api/entities/zerion-balance.entity';
import {
  ZerionCollectible,
  ZerionCollectibles,
} from '@/datasources/balances-api/entities/zerion-collectible.entity';
import { LimitReachedError } from '@/datasources/network/entities/errors/limit-reached.error';
import { CacheFirstDataSource } from '@/datasources/cache/cache.first.data.source';
import { CacheRouter } from '@/datasources/cache/cache.router';
import {
  CacheService,
  ICacheService,
} from '@/datasources/cache/cache.service.interface';
import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';
import {
  Balance,
  Erc20Balance,
  NativeBalance,
} from '@/domain/balances/entities/balance.entity';
import { Collectible } from '@/domain/collectibles/entities/collectible.entity';
import { getNumberString } from '@/domain/common/utils/utils';
import { Page } from '@/domain/entities/page.entity';
import { DataSourceError } from '@/domain/errors/data-source.error';
import { IBalancesApi } from '@/domain/interfaces/balances-api.interface';
import { LoggingService, ILoggingService } from '@/logging/logging.interface';
import { Inject, Injectable } from '@nestjs/common';

export const IZerionBalancesApi = Symbol('IZerionBalancesApi');

@Injectable()
export class ZerionBalancesApi implements IBalancesApi {
  private static readonly collectiblesSorting = '-floor_price';
  private readonly apiKey: string | undefined;
  private readonly baseUri: string;
  private readonly chainsConfiguration: Record<number, ChainAttributes>;
  private readonly defaultExpirationTimeInSeconds: number;
  private readonly defaultNotFoundExpirationTimeSeconds: number;
  private readonly fiatCodes: string[];

  // Number of seconds for each rate-limit cycle
  private readonly limitPeriodSeconds: number;
  // Number of allowed calls on each rate-limit cycle
  private readonly limitCalls: number;

  constructor(
    @Inject(CacheService) private readonly cacheService: ICacheService,
    @Inject(LoggingService) private readonly loggingService: ILoggingService,
    @Inject(IConfigurationService)
    private readonly configurationService: IConfigurationService,
    private readonly dataSource: CacheFirstDataSource,
    private readonly httpErrorFactory: HttpErrorFactory,
  ) {
    this.apiKey = this.configurationService.get<string>(
      'balances.providers.zerion.apiKey',
    );
    this.baseUri = this.configurationService.getOrThrow<string>(
      'balances.providers.zerion.baseUri',
    );
    this.defaultExpirationTimeInSeconds =
      this.configurationService.getOrThrow<number>(
        'expirationTimeInSeconds.default',
      );
    this.defaultNotFoundExpirationTimeSeconds =
      this.configurationService.getOrThrow<number>(
        'expirationTimeInSeconds.notFound.default',
      );
    this.chainsConfiguration = this.configurationService.getOrThrow<
      Record<number, ChainAttributes>
    >('balances.providers.zerion.chains');
    this.fiatCodes = this.configurationService
      .getOrThrow<string[]>('balances.providers.zerion.currencies')
      .map((currency) => currency.toUpperCase());
    this.limitPeriodSeconds = configurationService.getOrThrow(
      'balances.providers.zerion.limitPeriodSeconds',
    );
    this.limitCalls = configurationService.getOrThrow(
      'balances.providers.zerion.limitCalls',
    );
  }

  async getBalances(args: {
    chainId: string;
    safeAddress: string;
    fiatCode: string;
  }): Promise<Balance[]> {
    try {
      const isRateLimited = await this._isRateLimited();
      const cacheDir = CacheRouter.getZerionBalancesCacheDir(args);
      const chainName = this._getChainName(args.chainId);
      const currency = args.fiatCode.toLowerCase();
      const url = `${this.baseUri}/v1/wallets/${args.safeAddress}/positions`;
      const { data } = await this.dataSource.get<ZerionBalances>({
        cacheDir,
        url,
        notFoundExpireTimeSeconds: this.defaultNotFoundExpirationTimeSeconds,
        networkRequest: {
          headers: { Authorization: `Basic ${this.apiKey}` },
          params: {
            'filter[chain_ids]': chainName,
            currency: currency,
            sort: 'value',
          },
        },
        expireTimeSeconds: this.defaultExpirationTimeInSeconds,
        isRateLimited: isRateLimited,
      });
      return this._mapBalances(chainName, data);
    } catch (error) {
      if (error instanceof LimitReachedError) {
        throw new DataSourceError(error.message, 429);
      }
      throw this.httpErrorFactory.from(error);
    }
  }

  /**
   * NOTE: Zerion does not support limit & offset parameters.
   * Documentation: https://developers.zerion.io/reference/listwalletnftpositions
   *
   * It uses a "size" query param for the page size, and an "after" parameter for the offset.
   * "size" is an integer which could be mapped to "limit", but "after" is a base64-encoded string.
   *
   * Since this setup does not align well with the CGW API, it is needed to encode/decode these parameters.
   */
  async getCollectibles(args: {
    chainId: string;
    safeAddress: string;
    limit?: number;
    offset?: number;
  }): Promise<Page<Collectible>> {
    try {
      const cacheDir = CacheRouter.getZerionCollectiblesCacheDir(args);
      const chainName = this._getChainName(args.chainId);
      const url = `${this.baseUri}/v1/wallets/${args.safeAddress}/nft-positions`;
      const pageAfter = this._encodeZerionPageOffset(args.offset);
      const params = {
        'filter[chain_ids]': chainName,
        sort: ZerionBalancesApi.collectiblesSorting,
        'page[size]': args.limit,
        ...(pageAfter && { 'page[after]': pageAfter }),
      };

      const zerionCollectibles = await this.dataSource.get<ZerionCollectibles>({
        cacheDir,
        url,
        notFoundExpireTimeSeconds: this.defaultNotFoundExpirationTimeSeconds,
        networkRequest: {
          headers: { Authorization: `Basic ${this.apiKey}` },
          params,
        },
        expireTimeSeconds: this.defaultExpirationTimeInSeconds,
      });

      // Zerion does not provide the items count.
      // Zerion does not provide a "previous" cursor.
      return {
        count: null,
        next: this._decodeZerionPagination(zerionCollectibles.links.next ?? ''),
        previous: null,
        results: this._mapCollectibles(zerionCollectibles.data),
      };
    } catch (error) {
      throw this.httpErrorFactory.from(error);
    }
  }

  async clearCollectibles(args: {
    chainId: string;
    safeAddress: string;
  }): Promise<void> {
    const key = CacheRouter.getZerionCollectiblesCacheKey(args);
    await this.cacheService.deleteByKey(key);
  }

  private _mapBalances(
    chainName: string,
    zerionBalances: ZerionBalance[],
  ): Balance[] {
    return zerionBalances
      .filter((zb) => zb.attributes.flags.displayable)
      .map((zb) => {
        const implementation = zb.attributes.fungible_info.implementations.find(
          (implementation) => implementation.chain_id === chainName,
        );
        if (!implementation)
          throw Error(
            `Zerion error: ${chainName} implementation not found for balance ${zb.id}`,
          );
        const { value } = zb.attributes;
        const fiatBalance = value ? getNumberString(value) : null;
        const fiatConversion = getNumberString(zb.attributes.price);

        return {
          ...(implementation.address === null
            ? this._mapNativeBalance(zb.attributes)
            : this._mapErc20Balance(zb.attributes, implementation.address)),
          fiatBalance,
          fiatConversion,
        };
      });
  }

  async getFiatCodes(): Promise<string[]> {
    return this.fiatCodes;
  }

  private _mapErc20Balance(
    zerionBalanceAttributes: ZerionAttributes,
    tokenAddress: string,
  ): Erc20Balance {
    const { fungible_info, quantity } = zerionBalanceAttributes;
    return {
      tokenAddress,
      token: {
        name: fungible_info.name ?? '',
        symbol: fungible_info.symbol ?? '',
        decimals: quantity.decimals,
        logoUri: fungible_info.icon.url ?? '',
      },
      balance: quantity.int,
    };
  }

  private _mapNativeBalance(
    zerionBalanceAttributes: ZerionAttributes,
  ): NativeBalance {
    return {
      tokenAddress: null,
      token: null,
      balance: zerionBalanceAttributes.quantity.int,
    };
  }

  async clearBalances(args: {
    chainId: string;
    safeAddress: string;
  }): Promise<void> {
    const key = CacheRouter.getZerionBalancesCacheKey(args);
    await this.cacheService.deleteByKey(key);
  }

  private _getChainName(chainId: string): string {
    const chainName = this.chainsConfiguration[Number(chainId)]?.chainName;
    if (!chainName)
      throw Error(
        `Chain ${chainId} balances retrieval via Zerion is not configured`,
      );
    return chainName;
  }

  private _mapCollectibles(
    zerionCollectibles: ZerionCollectible[],
  ): Collectible[] {
    return zerionCollectibles.map(
      ({ attributes: { nft_info, collection_info } }) => ({
        address: nft_info.contract_address,
        tokenName: nft_info.name ?? '',
        tokenSymbol: nft_info.name ?? '',
        logoUri: collection_info?.content?.icon.url ?? '',
        id: nft_info.token_id,
        uri: nft_info.content?.detail?.url ?? null,
        name: collection_info?.name ?? null,
        description: collection_info?.description ?? null,
        imageUri: nft_info.content?.preview?.url ?? '',
        metadata: nft_info.content,
      }),
    );
  }

  /**
   * Zerion represents cursor offsets by base64 string
   * contained within double quotation marks.
   *
   * @param offset number representing the offset
   * @returns base64 string representing the offset
   */
  private _encodeZerionPageOffset(offset?: number): string | null {
    return offset
      ? Buffer.from(`"${offset}"`, 'utf8').toString('base64')
      : null;
  }

  /**
   * Zerion uses page[size] as pagination limit.
   * Zerion uses page[after] as pagination offset, which is a
   * base64 string contained within double quotation marks.
   *
   * @param url Zerion-formatted string representing an URL
   * @returns URL string optionally containing "limit" and "offset" query params
   */
  private _decodeZerionPagination(url: string): string {
    const zerionUrl = new URL(url);
    const size = zerionUrl.searchParams.get('page[size]');
    const after = zerionUrl.searchParams.get('page[after]');

    if (size) zerionUrl.searchParams.set('limit', size);
    if (after) {
      zerionUrl.searchParams.set(
        'offset',
        Buffer.from(after ?? '0', 'base64')
          .toString('utf8')
          .replace(/"/g, ''),
      );
    }
    return zerionUrl.toString();
  }

  private async _isRateLimited(): Promise<boolean> {
    const current = await this.cacheService.increment(
      CacheRouter.getZerionRateLimitCacheKey(),
      this.limitPeriodSeconds,
    );
    return current > this.limitCalls;
  }
}

1	import { IConfigurationService } from '@/config/configuration.service.interface';	92✔
2	import { ChainAttributes } from '@/datasources/balances-api/entities/provider-chain-attributes.entity';
3	import {
4	ZerionAttributes,
5	ZerionBalance,
6	ZerionBalances,
7	} from '@/datasources/balances-api/entities/zerion-balance.entity';
8	import {
9	ZerionCollectible,
10	ZerionCollectibles,
11	} from '@/datasources/balances-api/entities/zerion-collectible.entity';
12	import { LimitReachedError } from '@/datasources/network/entities/errors/limit-reached.error';	92✔
13	import { CacheFirstDataSource } from '@/datasources/cache/cache.first.data.source';	92✔
14	import { CacheRouter } from '@/datasources/cache/cache.router';	92✔
15	import {	92✔
16	CacheService,
17	ICacheService,
18	} from '@/datasources/cache/cache.service.interface';
19	import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';	92✔
20	import {
21	Balance,
22	Erc20Balance,
23	NativeBalance,
24	} from '@/domain/balances/entities/balance.entity';
25	import { Collectible } from '@/domain/collectibles/entities/collectible.entity';
26	import { getNumberString } from '@/domain/common/utils/utils';	92✔
27	import { Page } from '@/domain/entities/page.entity';
28	import { DataSourceError } from '@/domain/errors/data-source.error';	92✔
29	import { IBalancesApi } from '@/domain/interfaces/balances-api.interface';
30	import { LoggingService, ILoggingService } from '@/logging/logging.interface';	92✔
31	import { Inject, Injectable } from '@nestjs/common';	92✔
32
33	export const IZerionBalancesApi = Symbol('IZerionBalancesApi');	92✔
34
35	@Injectable()
36	export class ZerionBalancesApi implements IBalancesApi {	92✔
37	private static readonly collectiblesSorting = '-floor_price';	92✔
38	private readonly apiKey: string \| undefined;
39	private readonly baseUri: string;
40	private readonly chainsConfiguration: Record<number, ChainAttributes>;
41	private readonly defaultExpirationTimeInSeconds: number;
42	private readonly defaultNotFoundExpirationTimeSeconds: number;
43	private readonly fiatCodes: string[];
44
45	// Number of seconds for each rate-limit cycle
46	private readonly limitPeriodSeconds: number;
47	// Number of allowed calls on each rate-limit cycle
48	private readonly limitCalls: number;
49
50	constructor(
51	@Inject(CacheService) private readonly cacheService: ICacheService,	1,068✔
52	@Inject(LoggingService) private readonly loggingService: ILoggingService,	1,068✔
53	@Inject(IConfigurationService)
54	private readonly configurationService: IConfigurationService,	1,068✔
55	private readonly dataSource: CacheFirstDataSource,	1,068✔
56	private readonly httpErrorFactory: HttpErrorFactory,	1,068✔
57	) {
58	this.apiKey = this.configurationService.get<string>(	1,068✔
59	'balances.providers.zerion.apiKey',
60	);
61	this.baseUri = this.configurationService.getOrThrow<string>(	1,068✔
62	'balances.providers.zerion.baseUri',
63	);
64	this.defaultExpirationTimeInSeconds =	1,068✔
65	this.configurationService.getOrThrow<number>(
66	'expirationTimeInSeconds.default',
67	);
68	this.defaultNotFoundExpirationTimeSeconds =	1,068✔
69	this.configurationService.getOrThrow<number>(
70	'expirationTimeInSeconds.notFound.default',
71	);
72	this.chainsConfiguration = this.configurationService.getOrThrow<	1,068✔
73	Record<number, ChainAttributes>
74	>('balances.providers.zerion.chains');
75	this.fiatCodes = this.configurationService	1,068✔
76	.getOrThrow<string[]>('balances.providers.zerion.currencies')
77	.map((currency) => currency.toUpperCase());	8,120✔
78	this.limitPeriodSeconds = configurationService.getOrThrow(	1,068✔
79	'balances.providers.zerion.limitPeriodSeconds',
80	);
81	this.limitCalls = configurationService.getOrThrow(	1,068✔
82	'balances.providers.zerion.limitCalls',
83	);
84	}
85
86	async getBalances(args: {
87	chainId: string;
88	safeAddress: string;
89	fiatCode: string;
90	}): Promise<Balance[]> {
91	try {	22✔
92	const isRateLimited = await this._isRateLimited();	22✔
93	const cacheDir = CacheRouter.getZerionBalancesCacheDir(args);	22✔
94	const chainName = this._getChainName(args.chainId);	22✔
95	const currency = args.fiatCode.toLowerCase();	22✔
96	const url = `${this.baseUri}/v1/wallets/${args.safeAddress}/positions`;	22✔
97	const { data } = await this.dataSource.get<ZerionBalances>({	22✔
98	cacheDir,
99	url,
100	notFoundExpireTimeSeconds: this.defaultNotFoundExpirationTimeSeconds,
101	networkRequest: {
102	headers: { Authorization: `Basic ${this.apiKey}` },
103	params: {
104	'filter[chain_ids]': chainName,
105	currency: currency,
106	sort: 'value',
107	},
108	},
109	expireTimeSeconds: this.defaultExpirationTimeInSeconds,
110	isRateLimited: isRateLimited,
111	});
112	return this._mapBalances(chainName, data);	18✔
113	} catch (error) {
114	if (error instanceof LimitReachedError) {	4✔
115	throw new DataSourceError(error.message, 429);	2✔
116	}
117	throw this.httpErrorFactory.from(error);	2✔
118	}
119	}
120
121	/**
122	* NOTE: Zerion does not support limit & offset parameters.
123	* Documentation: https://developers.zerion.io/reference/listwalletnftpositions
124	*
125	* It uses a "size" query param for the page size, and an "after" parameter for the offset.
126	* "size" is an integer which could be mapped to "limit", but "after" is a base64-encoded string.
127	*
128	* Since this setup does not align well with the CGW API, it is needed to encode/decode these parameters.
129	*/
130	async getCollectibles(args: {
131	chainId: string;
132	safeAddress: string;
133	limit?: number;
134	offset?: number;
135	}): Promise<Page<Collectible>> {
136	try {	10✔
137	const cacheDir = CacheRouter.getZerionCollectiblesCacheDir(args);	10✔
138	const chainName = this._getChainName(args.chainId);	10✔
139	const url = `${this.baseUri}/v1/wallets/${args.safeAddress}/nft-positions`;	10✔
140	const pageAfter = this._encodeZerionPageOffset(args.offset);	10✔
141	const params = {	10✔
142	'filter[chain_ids]': chainName,
143	sort: ZerionBalancesApi.collectiblesSorting,
144	'page[size]': args.limit,
145	...(pageAfter && { 'page[after]': pageAfter }),	7✔
146	};
147
148	const zerionCollectibles = await this.dataSource.get<ZerionCollectibles>({	10✔
149	cacheDir,
150	url,
151	notFoundExpireTimeSeconds: this.defaultNotFoundExpirationTimeSeconds,
152	networkRequest: {
153	headers: { Authorization: `Basic ${this.apiKey}` },
154	params,
155	},
156	expireTimeSeconds: this.defaultExpirationTimeInSeconds,
157	});
158
159	// Zerion does not provide the items count.
160	// Zerion does not provide a "previous" cursor.
161	return {	8✔
162	count: null,
163	next: this._decodeZerionPagination(zerionCollectibles.links.next ?? ''),	12!
164	previous: null,
165	results: this._mapCollectibles(zerionCollectibles.data),
166	};
167	} catch (error) {
168	throw this.httpErrorFactory.from(error);	2✔
169	}
170	}
171
172	async clearCollectibles(args: {
173	chainId: string;
174	safeAddress: string;
175	}): Promise<void> {
NEW 176	const key = CacheRouter.getZerionCollectiblesCacheKey(args);	×
NEW 177	await this.cacheService.deleteByKey(key);	×
178	}
179
180	private _mapBalances(
181	chainName: string,
182	zerionBalances: ZerionBalance[],
183	): Balance[] {
184	return zerionBalances	18✔
185	.filter((zb) => zb.attributes.flags.displayable)	32✔
186	.map((zb) => {
187	const implementation = zb.attributes.fungible_info.implementations.find(	20✔
188	(implementation) => implementation.chain_id === chainName,	24✔
189	);
190	if (!implementation)	20!
191	throw Error(	×
192	`Zerion error: ${chainName} implementation not found for balance ${zb.id}`,
193	);
194	const { value } = zb.attributes;	20✔
195	const fiatBalance = value ? getNumberString(value) : null;	20!
196	const fiatConversion = getNumberString(zb.attributes.price);	20✔
197
198	return {	20✔
199	...(implementation.address === null	10✔
200	? this._mapNativeBalance(zb.attributes)
201	: this._mapErc20Balance(zb.attributes, implementation.address)),
202	fiatBalance,
203	fiatConversion,
204	};
205	});
206	}
207
208	async getFiatCodes(): Promise<string[]> {
209	return this.fiatCodes;	6✔
210	}
211
212	private _mapErc20Balance(
213	zerionBalanceAttributes: ZerionAttributes,
214	tokenAddress: string,
215	): Erc20Balance {
216	const { fungible_info, quantity } = zerionBalanceAttributes;	16✔
217	return {	16✔
218	tokenAddress,
219	token: {
220	name: fungible_info.name ?? '',	24!
221	symbol: fungible_info.symbol ?? '',	24!
222	decimals: quantity.decimals,
223	logoUri: fungible_info.icon.url ?? '',	24!
224	},
225	balance: quantity.int,
226	};
227	}
228
229	private _mapNativeBalance(
230	zerionBalanceAttributes: ZerionAttributes,
231	): NativeBalance {
232	return {	4✔
233	tokenAddress: null,
234	token: null,
235	balance: zerionBalanceAttributes.quantity.int,
236	};
237	}
238
239	async clearBalances(args: {
240	chainId: string;
241	safeAddress: string;
242	}): Promise<void> {
UNCOV 243	const key = CacheRouter.getZerionBalancesCacheKey(args);	×
UNCOV 244	await this.cacheService.deleteByKey(key);	×
245	}
246
247	private _getChainName(chainId: string): string {
248	const chainName = this.chainsConfiguration[Number(chainId)]?.chainName;	32!
249	if (!chainName)	32!
UNCOV 250	throw Error(	×
251	`Chain ${chainId} balances retrieval via Zerion is not configured`,
252	);
253	return chainName;	32✔
254	}
255
256	private _mapCollectibles(
257	zerionCollectibles: ZerionCollectible[],
258	): Collectible[] {
259	return zerionCollectibles.map(	8✔
260	({ attributes: { nft_info, collection_info } }) => ({	18✔
261	address: nft_info.contract_address,
262	tokenName: nft_info.name ?? '',	27!
263	tokenSymbol: nft_info.name ?? '',	27!
264	logoUri: collection_info?.content?.icon.url ?? '',	81!
265	id: nft_info.token_id,
266	uri: nft_info.content?.detail?.url ?? null,	81!
267	name: collection_info?.name ?? null,	54!
268	description: collection_info?.description ?? null,	54!
269	imageUri: nft_info.content?.preview?.url ?? '',	81!
270	metadata: nft_info.content,
271	}),
272	);
273	}
274
275	/**
276	* Zerion represents cursor offsets by base64 string
277	* contained within double quotation marks.
278	*
279	* @param offset number representing the offset
280	* @returns base64 string representing the offset
281	*/
282	private _encodeZerionPageOffset(offset?: number): string \| null {
283	return offset	10✔
284	? Buffer.from(`"${offset}"`, 'utf8').toString('base64')
285	: null;
286	}
287
288	/**
289	* Zerion uses page[size] as pagination limit.
290	* Zerion uses page[after] as pagination offset, which is a
291	* base64 string contained within double quotation marks.
292	*
293	* @param url Zerion-formatted string representing an URL
294	* @returns URL string optionally containing "limit" and "offset" query params
295	*/
296	private _decodeZerionPagination(url: string): string {
297	const zerionUrl = new URL(url);	8✔
298	const size = zerionUrl.searchParams.get('page[size]');	8✔
299	const after = zerionUrl.searchParams.get('page[after]');	8✔
300
301	if (size) zerionUrl.searchParams.set('limit', size);	8✔
302	if (after) {	8✔
303	zerionUrl.searchParams.set(	6✔
304	'offset',
305	Buffer.from(after ?? '0', 'base64')	9!
306	.toString('utf8')
307	.replace(/"/g, ''),
308	);
309	}
310	return zerionUrl.toString();	8✔
311	}
312
313	private async _isRateLimited(): Promise<boolean> {
314	const current = await this.cacheService.increment(	22✔
315	CacheRouter.getZerionRateLimitCacheKey(),
316	this.limitPeriodSeconds,
317	);
318	return current > this.limitCalls;	22✔
319	}
320	}

safe-global / safe-client-gateway / 8112223054

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous