assetx/webapp-back/lending/README.md

# Lending API Implementation

## Overview
This directory contains the backend implementation for the AssetX Lending Market system.

## API Endpoints

### Query Endpoints (Public)

#### Get User Position
```
GET /api/lending/position/:address
```
Returns user's lending position including:
- Supplied USDC balance
- Borrowed USDC balance
- Collateral balances (YT-A, YT-B, YT-C)
- Health Factor
- LTV (Loan-to-Value) ratio
- Supply/Borrow APY

**Response:**
```json
{
  "success": true,
  "data": {
    "user_address": "0x...",
    "wallet_address": "0x...",
    "supplied_balance": "10000.00",
    "supplied_balance_usd": 10000.00,
    "borrowed_balance": "1000.00",
    "borrowed_balance_usd": 1000.00,
    "collateral_balances": {
      "YT-A": {
        "token_symbol": "YT-A",
        "balance": "1000.00",
        "balance_usd": 2000000.00,
        "collateral_value": 1400000.00
      }
    },
    "health_factor": 14.0,
    "ltv": 10.0,
    "supply_apy": 6.1,
    "borrow_apy": 9.1
  }
}
```

#### Get Lending Stats
```
GET /api/lending/stats
```
Returns lending market statistics:
- Total supplied/borrowed USD
- Total collateral USD
- Utilization rate
- Average APYs
- User counts
- Total TVL

**Response:**
```json
{
  "success": true,
  "data": {
    "total_supplied_usd": 50000000.00,
    "total_borrowed_usd": 30000000.00,
    "total_collateral_usd": 80000000.00,
    "utilization_rate": 60.0,
    "avg_supply_apy": 6.1,
    "avg_borrow_apy": 9.1,
    "total_users": 1250,
    "active_borrowers": 450,
    "total_tvl": 130000000.00
  }
}
```

#### Get Lending Markets
```
GET /api/lending/markets
```
Returns lending market configuration from `lending_markets` table.

#### Get All Tokens Info
```
GET /api/lending/tokens
```
Returns information about all supported tokens (USDC + YT tokens from `assets` table).

**Response:**
```json
{
  "success": true,
  "data": {
    "stablecoins": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "contract_address_arb": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "contract_address_bsc": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
      }
    ],
    "yt_tokens": [
      {
        "symbol": "YT-A",
        "name": "YT-A",
        "decimals": 18,
        "contract_address_arb": "0x...",
        "contract_address_bsc": "0x...",
        "asset_code": "YT-A"
      }
    ]
  }
}
```

#### Get Token Info
```
GET /api/lending/tokens/:assetCode
```
Returns information about a specific token (USDC or YT-A/YT-B/YT-C).

### Transaction Endpoints

#### Supply USDC
```
POST /api/lending/supply
Content-Type: application/json

{
  "amount": "1000.00",
  "tx_hash": "0x..."
}
```

#### Withdraw USDC
```
POST /api/lending/withdraw
Content-Type: application/json

{
  "amount": "500.00",
  "tx_hash": "0x..."
}
```

#### Supply Collateral
```
POST /api/lending/supply-collateral
Content-Type: application/json

{
  "asset": "YT-A",
  "amount": "100.00",
  "tx_hash": "0x..."
}
```

#### Withdraw Collateral
```
POST /api/lending/withdraw-collateral
Content-Type: application/json

{
  "asset": "YT-A",
  "amount": "50.00",
  "tx_hash": "0x..."
}
```

#### Borrow USDC
```
POST /api/lending/borrow
Content-Type: application/json

{
  "amount": "1000.00",
  "tx_hash": "0x..."
}
```

#### Repay USDC
```
POST /api/lending/repay
Content-Type: application/json

{
  "amount": "500.00",
  "tx_hash": "0x..."
}
```

## Files

- `models.go` - Data models and request/response structures
- `handlers.go` - HTTP request handlers
- `helpers.go` - Helper functions (token info, calculations, validation)
- `tokens.go` - Token information endpoints
- `routers.go` - Route documentation (routes registered in main.go)
- `README.md` - This file

## Current Implementation Status

### ✅ Completed
- API endpoint structure
- Request/response models
- Basic validation
- Mock data responses
- Database integration for token information
- USDC configuration (hardcoded as per frontend)
- YT token information from `assets` table
- Token validation against database
- Health factor and LTV calculation formulas
- Token info query endpoints

### ⏳ TODO
1. **Blockchain Integration**
   - Connect to smart contracts
   - Verify transactions on-chain
   - Query real-time balances
   - Calculate health factor from chain data

2. **Database Integration**
   - Store transaction records
   - Update lending_markets table
   - Track user positions
   - Generate statistics

3. **Authentication**
   - Add wallet signature verification
   - Implement user session management

4. **Business Logic**
   - Interest accrual calculations
   - Health factor monitoring
   - Liquidation logic
   - APY calculations

## Database Schema

The lending system uses the following tables from `database-schema-v1.1-final.sql`:

- `lending_markets` - Lending market configuration
- `transactions` - Transaction records
- `protocol_stats` - Protocol-level statistics

Note: User position data is primarily read from blockchain, with caching in database.

## Integration with Frontend

Frontend components that use these APIs:

- `/lending/supply/SupplyPanel.tsx` - Supply USDC
- `/lending/supply/WithdrawPanel.tsx` - Withdraw USDC
- `/lending/repay/RepayBorrowDebt.tsx` - Borrow/Repay USDC
- `/lending/repay/RepaySupplyCollateral.tsx` - Supply/Withdraw Collateral
- `/lending/BorrowMarket.tsx` - Display lending positions

## Testing

```bash
# Start the server
go run main.go

# Test endpoints
curl http://localhost:8080/api/lending/stats
curl http://localhost:8080/api/lending/position/0x1234...

# Test transactions (requires auth)
curl -X POST http://localhost:8080/api/lending/supply \
  -H "Content-Type: application/json" \
  -d '{"amount": "1000", "tx_hash": "0x..."}'
```

## Next Steps

1. Implement blockchain RPC integration
2. Add real transaction verification
3. Implement health factor calculations
4. Add liquidation monitoring
5. Integrate with frontend
6. Add comprehensive tests
7. Deploy to testnet