Blockchain API client for Trait ecosystem (RTK Query + Redux Saga)
npm install @traittech/blockchain-api``bash`В вашем проекте (trevo-wallet, token-studio и т.д.)
yarn add file:../blockchain-api
`bash`
yarn add @traittech/blockchain-api
---
| API | Назначение | Основные endpoints |
|-----|-----------|-------------------|
| balancesAPI | Балансы токенов с автоматической пагинацией | useBalancesQuery |useTokensOperationsQuery
| historyAPI | История операций с умным merge head/tail | |getEntityInfoSelector
| infoAPI | Метаданные сущностей (токены, NFT, приложения) | |useJSONFungiblesQuery
| jsonMetadataAPI | JSON метаданные с rate limiting | , useJSONNftQuery |useTxExamineNativeV2Mutation
| transactionAPI | Проверка и отправка транзакций | , useTxSubmitMutation |
---
#### Balances API
`typescript`
import {
useBalancesQuery, // Query с подпиской
useLazyBalancesQuery, // Lazy query без автоподписки
selectBalances, // Selector для доступа к кэшу
} from '@traittech/blockchain-api';
#### History API
`typescript`
import {
useTokensOperationsQuery, // Query для истории операций
useLazyTokensOperationsQuery, // Lazy версия
getTokensOperationsSelectorConstructor, // Constructor для селектора
} from '@traittech/blockchain-api';
#### Transaction API
`typescript`
import {
// Query версии (с кэшированием)
useTxExamineNativeQuery,
useTxExamineFungibleQuery,
useTxExamineNftQuery,
// Lazy версии
useLazyTxExamineNativeQuery,
useLazyTxExamineFungibleQuery,
useLazyTxExamineNftQuery,
// Mutation версии (без кэша, для финальной отправки)
useTxExamineNativeV2Mutation,
useTxExamineFungibleV2Mutation,
useTxExamineNftV2Mutation,
useTxBuildInfoMutation,
useTxSubmitMutation,
// Селекторы
getTxExamineFungibleSelector,
getTxExamineNativeSelector,
} from '@traittech/blockchain-api';
#### Info API
`typescript`
import {
getEntityInfoSelector, // Selector для entity info
usePrefetch, // Prefetch utility
DEFAULT_NATIVE_TOKEN_DATA, // Дефолтные данные нативного токена
filterEntityInfoRequestForSaga, // Утилита для фильтрации в сагах
isEmptyArgs, // Проверка пустых аргументов
} from '@traittech/blockchain-api';
#### JSON Metadata API
`typescript`
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 типы экспортируются из главного пакета:
`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';
---
`typescript`
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 в вашем проекте.
---
`bash`.env или process.env
BLOCKCHAIN_API_URL=https://chain.api.trevo.finance/
`typescript`
// Библиотека автоматически использует переменную окружения:
import { BASE_URL } from '@traittech/blockchain-api';
console.log(BASE_URL); // https://chain.api.trevo.finance/ (или из env)
`typescript
import { BALANCES_POLLING_INTERVAL, ONE_DAY, ONE_WEEK } from '@traittech/blockchain-api';
// Рекомендуемые интервалы:
useBalancesQuery({ owner }, {
pollingInterval: BALANCES_POLLING_INTERVAL // 15 секунд
});
`
---
Для разработки используйте Vite/Webpack proxy (см. выше) или настройте CORS на сервере.
---
- axios - HTTP клиентaxios-rate-limit
- - Rate limiting для запросов@traittech/traits-validator
- - Валидация JSON metadata
- @reduxjs/toolkit ^1.9.0 || ^2.0.0redux-saga
- ^1.2.0 || ^1.3.0redux-persist
- ^6.0.0
`bash``Установите 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 для понимания внутреннего устройства перед внесением изменений.