Blocksmith-forge Backend

Node.js / Fastify API for Blocksmith-forge DeFi Protocol

Off-chain indexing and metrics API for tracking trading volume, liquidity, and pool statistics for the Blocksmith-forge DEX.

Overview

This backend service provides:

• Pool Metrics Tracking: Real-time monitoring of liquidity pool reserves
• Volume Indexing: 24h, 7d, and total trading volume tracking
• Stellar Integration: Direct integration with Stellar Horizon API
• RESTful API: Clean endpoints for frontend consumption

Architecture

Tech Stack

• Runtime: Node.js
• Framework: Fastify (high-performance web framework)
• Language: TypeScript
• Blockchain: Stellar SDK for Horizon integration
• CORS: Enabled for frontend integration

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/api/pools	GET	Get all pools
/api/pools/:poolId	GET	Get specific pool metrics
/api/pools/:poolId/volume	GET	Get volume metrics for pool
/api/volume/24h	GET	Get total 24h volume
/api/pools/:poolId/reserves	GET	Get pool reserves
/api/pools/:poolId/update	POST	Update pool metrics
/api/swaps/record	POST	Record a swap transaction
/api/accounts/:accountId	GET	Get Stellar account info

Project Structure

blocksmith-forge-Backend/
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── README.md              # This file
└── src/
    └── index.ts           # Main API server

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• TypeScript compiler

Installation

# Clone the repository
git clone https://github.com/blocksmith-forge/blocksmith-forge-Backend.git
cd blocksmith-forge-Backend

# Install dependencies
npm install

Configuration

Environment variables (optional):

# Horizon URL (defaults to testnet)
HORIZON_URL=https://horizon-testnet.stellar.org

# Server configuration
PORT=3000
HOST=0.0.0.0

Development

# Run in development mode with hot reload
npm run dev

# Build TypeScript
npm run build

# Run production build
npm start

API Usage Examples

Get All Pools

curl http://localhost:3000/api/pools

Response:

{
  "pools": [
    {
      "poolId": "GAMMPOOL123456789",
      "tokenA": "XLM",
      "tokenB": "USDC",
      "reserveA": 1000000,
      "reserveB": 500000,
      "totalLiquidity": 1500000,
      "lpTokenSupply": 707106,
      "lastUpdated": "2024-01-15T10:30:00.000Z"
    }
  ],
  "count": 1
}

Get Pool Reserves

curl http://localhost:3000/api/pools/GAMMPOOL123456789/reserves

Response:

{
  "reserveA": 1000000,
  "reserveB": 500000,
  "lastUpdated": "2024-01-15T10:30:00.000Z"
}

Get 24h Volume

curl http://localhost:3000/api/volume/24h

Response:

{
  "totalVolume24h": 250000,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Record a Swap

curl -X POST http://localhost:3000/api/swaps/record \
  -H "Content-Type: application/json" \
  -d '{
    "poolId": "GAMMPOOL123456789",
    "amountIn": 100000,
    "amountOut": 95000
  }'

Get Stellar Account

curl http://localhost:3000/api/accounts/GA5XED7QNBJHQB2PRZ7Z3HUIWZHX3G6EXH2AECH3Y2F7XXZALX5JF4RI

Data Models

PoolMetrics

interface PoolMetrics {
  poolId: string;
  tokenA: string;
  tokenB: string;
  reserveA: number;
  reserveB: number;
  totalLiquidity: number;
  lpTokenSupply: number;
  lastUpdated: Date;
}

VolumeMetrics

interface VolumeMetrics {
  poolId: string;
  volume24h: number;
  volume7d: number;
  totalVolume: number;
  lastUpdated: Date;
}

Production Considerations

Database Integration

Currently uses in-memory storage. For production, integrate with:

• PostgreSQL with Prisma ORM
• Redis for caching
• TimescaleDB for time-series metrics

Event Indexing

Implement blockchain event listeners:

• Use Stellar Horizon subscriptions
• Index transaction events in real-time
• Update metrics on each swap/liquidity event

Security

• Add API authentication (JWT tokens)
• Rate limiting per IP
• Input validation with Zod
• HTTPS only in production

Testing

# Run tests
npm test

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Contact

• Organization: blocksmith-forge
• Developer: Aesdecodes
• GitHub: https://github.com/blocksmith-forge