@traittech/blockchain-api

Установка

Локальная разработка

# В вашем проекте (trevo-wallet, token-studio и т.д.)
yarn add file:../blockchain-api

NPM

yarn add @traittech/blockchain-api

Справочник API

Доступные APIs

| API | Назначение | Основные endpoints | |-----|-----------|-------------------| | balancesAPI | Балансы токенов с автоматической пагинацией | useBalancesQuery | | historyAPI | История операций с умным merge head/tail | useTokensOperationsQuery | | infoAPI | Метаданные сущностей (токены, NFT, приложения) | getEntityInfoSelector | | jsonMetadataAPI | JSON метаданные с rate limiting | useJSONFungiblesQuery, useJSONNftQuery | | transactionAPI | Проверка и отправка транзакций | useTxExamineNativeV2Mutation, useTxSubmitMutation |

Экспортируемые хуки

Balances API

import {
  useBalancesQuery,          // Query с подпиской
  useLazyBalancesQuery,      // Lazy query без автоподписки
  selectBalances,            // Selector для доступа к кэшу
} from '@traittech/blockchain-api';

History API

import {
  useTokensOperationsQuery,            // Query для истории операций
  useLazyTokensOperationsQuery,        // Lazy версия
  getTokensOperationsSelectorConstructor, // Constructor для селектора
} from '@traittech/blockchain-api';

Transaction API

import {
  // Query версии (с кэшированием)
  useTxExamineNativeQuery,
  useTxExamineFungibleQuery,
  useTxExamineNftQuery,
  
  // Lazy версии
  useLazyTxExamineNativeQuery,
  useLazyTxExamineFungibleQuery,
  useLazyTxExamineNftQuery,
  
  // Mutation версии (без кэша, для финальной отправки)
  useTxExamineNativeV2Mutation,
  useTxExamineFungibleV2Mutation,
  useTxExamineNftV2Mutation,
  useTxBuildInfoMutation,
  useTxSubmitMutation,
  
  // Селекторы
  getTxExamineFungibleSelector,
  getTxExamineNativeSelector,
} from '@traittech/blockchain-api';

Info API

import {
  getEntityInfoSelector,           // Selector для entity info
  usePrefetch,                     // Prefetch utility
  DEFAULT_NATIVE_TOKEN_DATA,       // Дефолтные данные нативного токена
  filterEntityInfoRequestForSaga,  // Утилита для фильтрации в сагах
  isEmptyArgs,                     // Проверка пустых аргументов
} from '@traittech/blockchain-api';

JSON Metadata API

import {
  // Query hooks
  useJSONFungiblesQuery,
  useJSONNftQuery,
  useJSONNftCollectionQuery,
  useJSONAppAgentsQuery,
  useJSONComplianceProvidersQuery,
  
  // Query state hooks
  useJSONFungiblesState,
  useJSONNftState,
  useJSONNftCollectionState,
  useJSONAppAgentsState,
  useJSONComplianceProvidersState,
  
  // Selectors
  getFungibleJsonMetadataSelector,
  getNftJsonMetadataSelector,
  getAppAgentJsonMetadataSelector,
  getNftCollectionJsonMetadataSelector,
} from '@traittech/blockchain-api';

Типы

Все TypeScript типы экспортируются из главного пакета:

import type {
  // Balances
  BalancesMappedResponse,
  TokenBalanceFungible,
  TokenBalanceNative,
  TokenNft,
  NormalizedTokensBalances,
  NormalizedNFTsBalances,
  
  // Operations/History
  OperationTransfersResponse,
  TokenOperation,
  TokenOperationBare,
  TokensOperationsPostApiArg,
  
  // Entity Info
  StateEntityInfoResponse,
  StateEntityInfoRequest,
  InfoWrapper,
  NormalizedBlockchainEntitiesInfo,
  
  // JSON Metadata
  FungibleJsonMetadata,
  NftJsonMetadata,
  NftCollectionJsonMetadata,
  AppJsonMetadata,
  ComplianceProviderJsonMetadata,
  
  // Transfers
  TokenTransferFungible,
  TokenTransferNative,
  TokenTransferNft,
  
  // Transaction Types
  Fee,
  TxBuildInfo,
  TxExaminePlayerTransferNativeResponse,
  TxExaminePlayerTransferFungibleResponse,
  TxExaminePlayerTransferNftResponse,
  
  // Codegen Types
  TokenType,
  NftItemFullId,
  FungibleTokenInfo,
  NativeTokenInfo,
  NftCollectionInfo,
  ComplianceVerificationDetails,
  EventReceiptSignedTx,
  
  // Common
  ResponseWithMetadata,
  BlockchainAddress,
} from '@traittech/blockchain-api';

Утилиты

import {
  normalizeTokensBalances,
  normalizeNFTsBalances,
  BASE_URL,
  BALANCES_POLLING_INTERVAL,
  ONE_DAY,
  ONE_WEEK,
} from '@traittech/blockchain-api';

Архитектура

User Request
    ↓
[1] balancesAPI - загрузка балансов
    └→ Нормализация: apps → tokens
    ↓
[2] infoAPI - метаданные сущностей (через вашу сагу)
    └→ Singleton cache + TTL filtering
    ↓
[3] jsonMetadataAPI - детальные JSON метаданные (через вашу сагу)
    └→ Rate limiting + size validation
    ↓
UI Components
    └→ Комбинирование данных из всех источников

Примечание: Cascade loading (шаги 2-3) реализуется через Redux Sagas в вашем проекте.

Конфигурация

Переменные окружения

# .env или process.env
BLOCKCHAIN_API_URL=https://chain.api.trevo.finance/

// Библиотека автоматически использует переменную окружения:
import { BASE_URL } from '@traittech/blockchain-api';
console.log(BASE_URL); // https://chain.api.trevo.finance/ (или из env)

Константы

import { BALANCES_POLLING_INTERVAL, ONE_DAY, ONE_WEEK } from '@traittech/blockchain-api';

// Рекомендуемые интервалы:
useBalancesQuery({ owner }, { 
  pollingInterval: BALANCES_POLLING_INTERVAL // 15 секунд
});

CORS ошибки в Web

Для разработки используйте Vite/Webpack proxy (см. выше) или настройте CORS на сервере.

Зависимости

Dependencies (устанавливаются автоматически)

• axios - HTTP клиент
• axios-rate-limit - Rate limiting для запросов
• @traittech/traits-validator - Валидация JSON metadata

Peer Dependencies (должны быть в проекте)

• @reduxjs/toolkit ^1.9.0 || ^2.0.0
• redux-saga ^1.2.0 || ^1.3.0
• redux-persist ^6.0.0

# Установите peer dependencies:
yarn add @reduxjs/toolkit redux-saga redux-persist

Дополнительная документация

• ARCHITECTURE.md - Детальная архитектура библиотеки
• OPEN_ISSUES.md - Известные проблемы и планы развития

Документация по API:

• src/apis/balances/ - Балансы токенов
• src/apis/history/ - История операций
• src/apis/jsonMetadata/ - JSON метаданные
• src/apis/entityInfo/ - Метаданные сущностей
• src/apis/tx/ - Транзакции

Лицензия

MIT

Контрибьютинг

См. ARCHITECTURE.md для понимания внутреннего устройства перед внесением изменений.