Skip to content

1. Introduction.md

Latest commit

 

History

History
348 lines (267 loc) · 12.7 KB

1. Introduction.md

File metadata and controls

348 lines (267 loc) · 12.7 KB

Introduction

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

The EVAA SDK is a TypeScript-based software development kit designed to facilitate seamless integration with the EVAA DeFi lending protocol on the TON (The Open Network) blockchain. It abstracts complex smart contract interactions into developer-friendly methods, enabling operations such as supplying assets, withdrawing funds, initiating liquidations, and retrieving price oracle data with minimal boilerplate code. The SDK's core value proposition lies in its ability to simplify blockchain interactions while maintaining type safety, modular design, and high testability.

The SDK supports dual oracle systems—Classic and Pyth—allowing developers to choose between centralized and decentralized price feeds. It also features subaccount functionality, enabling users to manage multiple isolated positions under a single wallet. Integration with @tonconnect/sdk ensures secure wallet connectivity, while modular architecture promotes extensibility and maintainability.

Key benefits of the EVAA SDK include:

  • Type Safety: Built with TypeScript, ensuring compile-time type checking.
  • Modular Design: Components are decoupled for easy reuse and testing.
  • Testability: Comprehensive test suite covering supply, withdraw, and price operations.
  • Dual Oracle Support: Compatibility with both Classic and Pyth oracle systems.
  • Subaccount Management: Support for multiple user positions via subaccount IDs.

The main architectural components include:

  • Master Contracts: Entry points for protocol interactions (e.g., ClassicMaster, PythMaster).
  • PricesCollector: Aggregates and validates price data from multiple sources.
  • UserContract: Represents a user's position and state within the protocol.
  • Jetton: Standard for fungible tokens on TON, used for asset transfers.

A simple code example demonstrates SDK initialization and price fetching:

import { TonClient } from '@ton/ton';
import { Evaa, MAINNET_POOL_CONFIG } from './src';

const client = new TonClient({ endpoint: 'https://toncenter.com/api/v2/jsonRPC' });
const evaa = client.open(new Evaa({ poolConfig: MAINNET_POOL_CONFIG }));
const prices = await evaa.getPrices();
console.log(prices.dict);

The SDK operates on the TON blockchain, leveraging asynchronous message passing and cell-based data structures for state management. Common use cases include DeFi dashboards, automated trading bots, and analytics tools that require real-time access to lending protocol data.

Section sources

  • README.md
  • src/index.ts

Project Structure

The EVAA SDK follows a modular, feature-based organization, separating concerns into distinct directories for contracts, APIs, prices, rewards, and utilities. This structure enhances maintainability and enables focused development.

graph TB
subgraph "src"
A[src] --> B[api]
A --> C[constants]
A --> D[contracts]
A --> E[prices]
A --> F[rewards]
A --> G[types]
A --> H[utils]
A --> I[index.ts]
end
B --> B1[parsers]
B --> B2[feeds.ts]
B --> B3[liquidation.ts]
B --> B4[math.ts]
B --> B5[parser.ts]
B --> B6[prices.ts]
B --> B7[pyth.ts]
C --> C1[assets]
C --> C2[general]
C --> C3[pools]
D --> D1[AbstractMaster.ts]
D --> D2[ClassicMaster.ts]
D --> D3[PythMaster.ts]
D --> D4[UserContract.ts]
D --> D5[JettonWallet.ts]
E --> E1[sources]
E --> E2[PricesCollector.ts]
E --> E3[PythCollector.ts]
E --> E4[Oracle.interface.ts]
F --> F1[EvaaRewards.ts]
F --> F2[JettonMinter.ts]
F --> F3[JettonWallet.ts]
F --> F4[RewardMaster.ts]
F --> F5[RewardUser.ts]
H --> H1[tonConnectSender.ts]
H --> H2[userJettonWallet.ts]
subgraph "tests"
J[tests] --> K[address]
J --> L[math]
J --> M[parseContractData]
J --> N[parseUserData]
J --> O[prices]
J --> P[rewards]
J --> Q[sw]
J --> R[utils]
end
Loading

Diagram sources

  • src/index.ts
  • src/contracts/index.ts

Section sources

  • src/index.ts
  • src/contracts/index.ts

Core Components

The EVAA SDK's functionality is built around several core components that handle protocol interaction, price aggregation, and user state management.

Master Contracts

The AbstractEvaaMaster class serves as the base for all master contract implementations, encapsulating shared logic for supply, withdraw, and liquidation operations. Concrete implementations include ClassicMaster and PythMaster, which differ in their oracle integration strategies.

classDiagram
class AbstractEvaaMaster {
+Address address
+PoolConfig poolConfig
+MasterData data
+getSync(provider) Promise~void~
+sendSupply(via, value, params) Promise~void~
+sendWithdraw(via, value, params) Promise~void~
+openUserContract(userAddress, subaccountId) EvaaUser
}
class ClassicMaster {
+getSync(provider) Promise~void~
+createPriceCollector() PricesCollector
}
class PythMaster {
+getSync(provider) Promise~void~
+createPriceCollector() PythCollector
}
AbstractEvaaMaster <|-- ClassicMaster
AbstractEvaaMaster <|-- PythMaster
Loading

Diagram sources

  • src/contracts/AbstractMaster.ts
  • src/contracts/AbstractMaster.ts

User Contract

The UserContract class represents a user's position in the lending protocol, storing principals, health factors, and liquidation data. It synchronizes state from the blockchain using price data from the PricesCollector.

classDiagram
class UserContract {
+Address address
+UserData data
+getSync(provider, assetsData, assetsConfig, prices) Promise~void~
+isLiquidable() boolean
}
Loading

Diagram sources

  • src/contracts/UserContract.ts

Prices Collector

The PricesCollector class aggregates price data from multiple sources, validates timestamps, and computes median prices. The PythCollector extends this functionality to support Pyth Network's price feeds.

classDiagram
class PricesCollector {
+getPrices() Promise~Prices~
+getPricesForWithdraw(principals, asset, applyDust) Promise~Prices~
}
class PythCollector {
+getPrices() Promise~Prices~
}
PricesCollector <|-- PythCollector
Loading

Diagram sources

  • src/prices/PricesCollector.ts
  • src/prices/PythCollector.ts

Section sources

  • src/contracts/AbstractMaster.ts
  • src/contracts/AbstractMaster.ts
  • src/contracts/UserContract.ts
  • src/prices/PricesCollector.ts
  • src/prices/PythCollector.ts

Architecture Overview

The EVAA SDK follows a layered architecture with clear separation between blockchain interaction, business logic, and data aggregation.

graph TB
A[Application] --> B[EVAA SDK]
B --> C[Master Contract]
B --> D[Prices Collector]
B --> E[User Contract]
C --> F[TON Blockchain]
D --> G[Price Sources]
E --> F
G --> H[Backend API]
G --> I[Pyth Network]
F --> J[Smart Contracts]
Loading

Diagram sources

  • src/contracts/AbstractMaster.ts
  • src/prices/PricesCollector.ts
  • src/prices/sources/Backend.ts
  • src/prices/PythCollector.ts

Detailed Component Analysis

Master Contract Initialization and Synchronization

The AbstractEvaaMaster class provides a foundation for protocol interaction, with synchronization logic centralized in the syncMasterData method. This method parses contract state from Base64-encoded BOC (Bag of Cells) data and validates the master code version.

sequenceDiagram
participant App as Application
participant Master as AbstractEvaaMaster
participant Provider as ContractProvider
participant Parser as OracleParser
App->>Master : getSync()
Master->>Provider : getState()
Provider-->>Master : ContractState
Master->>Master : parseMasterData(state.data)
Master->>Parser : parseOracleData()
Master-->>App : Update this._data
Loading

Diagram sources

  • src/contracts/AbstractMaster.ts
  • src/api/parser.ts

Subaccount Management

The SDK supports subaccounts through deterministic address calculation. The calculateUserSCAddr method generates unique user contract addresses based on wallet address and subaccount ID.

flowchart TD
Start([User Address + Subaccount ID]) --> Hash["Hash with lendingCode"]
Hash --> StateInit["Create StateInit"]
StateInit --> Address["Compute Address from StateInit"]
Address --> Result([User Contract Address])
Loading

Diagram sources

  • src/contracts/AbstractMaster.ts
  • tests/address/SubaccountCalculation.test.ts

Price Data Aggregation

The PricesCollector fetches and validates price data from multiple sources, ensuring reliability through redundancy and median calculation.

flowchart TD
A[Fetch Raw Prices] --> B{Validate Timestamp}
B --> |Valid| C[Extract Price Dict]
B --> |Invalid| D[Throw Error]
C --> E[Compute Median]
E --> F[Return Prices]
Loading

Diagram sources

  • src/prices/PricesCollector.ts
  • src/prices/sources/Backend.ts

Section sources

  • src/contracts/AbstractMaster.ts
  • src/api/parser.ts
  • src/contracts/AbstractMaster.ts
  • tests/address/SubaccountCalculation.test.ts
  • src/prices/PricesCollector.ts
  • src/prices/sources/Backend.ts

Dependency Analysis

The EVAA SDK has well-defined dependencies between components, with minimal circular references.

graph LR
A[index.ts] --> B[AbstractMaster]
A --> C[UserContract]
A --> D[PricesCollector]
B --> E[parser.ts]
D --> F[PriceSource]
B --> G[UserContract]
C --> H[PricesCollector]
Loading

Diagram sources

  • src/index.ts
  • src/contracts/AbstractMaster.ts
  • src/prices/PricesCollector.ts

Section sources

  • src/index.ts
  • src/contracts/AbstractMaster.ts
  • src/prices/PricesCollector.ts

Performance Considerations

The SDK is optimized for efficient blockchain interaction:

  • Caching: Master and user data are cached after synchronization.
  • Batching: Price requests are batched when possible.
  • Validation: Price timestamps are verified to prevent stale data usage.
  • Error Handling: Network retries with exponential backoff are implemented.

Troubleshooting Guide

Common issues and solutions:

  • Outdated Master Code Version: Ensure SDK version matches contract version.
  • Invalid Subaccount ID: Subaccount IDs must be in range [0, 32767].
  • Stale Prices: Verify price timestamps and source availability.
  • Insufficient Balance: Check wallet and jetton balances before operations.

Section sources

  • src/contracts/AbstractMaster.ts
  • tests/address/SubaccountCalculation.test.ts

Conclusion

The EVAA SDK provides a robust, type-safe interface for interacting with the EVAA DeFi lending protocol on TON. Its modular architecture, dual oracle support, and subaccount functionality make it suitable for a wide range of DeFi applications. The comprehensive test suite and clear separation of concerns ensure reliability and maintainability.