@traittech/blockchain-api

Установка

$3

``bash


В вашем проекте (trevo-wallet, token-studio и т.д.)


yarn add file:../blockchain-api
`

$3

`bash
yarn add @traittech/blockchain-api
`

---

Справочник API

$3

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

---

$3

#### 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';
`

---

$3

Все 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';
`

---

$3

`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 в вашем проекте.

---

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

$3

`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)
`

$3

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

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

---

$3

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

---

Зависимости

$3

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

$3

- @reduxjs/toolkit ^1.9.0 || ^2.0.0
- redux-saga ^1.2.0 || ^1.3.0
- redux-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 для понимания внутреннего устройства перед внесением изменений.