Mento Analytics API

The Mento Analytics API is a service designed to provide real-time analytics for the Mento Protocol's stablecoins and reserve assets across multiple blockchains (Celo, Ethereum, and Bitcoin). It serves as the data backbone for the Mento Reserve dashboard, offering insights into reserve holdings and stablecoin metrics.

The API can be used by consumers to fetch information about Mento Stables, the Reserve and its composition.

• Getting Started
  • Prerequisites
  • Installation
• Key Features
• Project Structure
• System Architecture
• API Documentation
• Data Sources & Updates
  • Data Sources
  • Data Update Frequency
  • Cache Management
• Configuration Guide
  • Adding New Stablecoins
  • Managing Reserve Addresses
  • Adding Reserve Assets
• Deployment
  • Production Deployment
  • Preview Deployments
• Monitoring & Logs
  • Application Logs
  • Monitoring Dashboard
  • Sentry Releases
• Contributing
• License

Getting Started

Prerequisites

• Node.js
• pnpm

Installation

# 1. Install dependencies
pnpm install

# 2. Copy and populate .env
cp .env.example .env

# 3. Fill in all missing env vars in .env

# 4. Start development server
pnpm run start:dev

# 5. Build for production
pnpm run build

# 6. Start production server
pnpm run start:prod

Key Features

• Stablecoin Analytics: Tracks the total supply of all Mento stables
• Multi-Chain Reserve Tracking: Monitors reserve assets across Celo, Ethereum and Bitcoin networks
• Reserve Composition Analysis: Detailed breakdown of reserve holdings and their USD values
• Collateralization Metrics: Real-time tracking of reserve-to-stablecoin ratios
• Automated Cache Management: Optimized data delivery with cache warming
• Health Monitoring: System health checks across all integrated services

Project Structure

Below is the project structure:

src/
├── app.module.ts            # Root module
├── main.ts                  # Entry point
├── api/                     # API features
│   ├── stablecoins/         # Stablecoin-related endpoints
│   ├── reserve/             # Reserve-related endpoints
│   └── health/              # Health check endpoints
├── common/                      
│   └── services/            # Shared services   
├── types/                   # Shared types/interfaces
└── utils/                   # Utility functions

System Architecture

The Mento Analytics API is hosted on Google Cloud Platform (GCP) using Cloud Run with logging handled by Cloud Logging. The diagram below illustrates the high-level architecture and data flow:

API Documentation

Detailed documentaion for the API endpoints is available at /docs when running the application.

Data Sources & Updates

Data Sources

• On-chain data from multiple networks:
  • Celo: Mento SDK beta + Infura
  • Ethereum: Mento SDK beta + Infura
  • Bitcoin: Blockchain.info & Blockstream
• Price feeds: CoinmarketCap API for real-time asset pricing
• Exchange rate data: API Layer exchange rates API

Data Update Frequency

Data provided by the API will be < 1 hour old. Data is only updated on an hourly schedule.

Cache Management

The API implements a cache warming strategy to ensure data availability:

1. Initial warmup on service start
2. Scheduled refreshes every hour
3. Manual invalidation via admin endpoints - To Be Added

Configuration Guide

Adding New Stablecoins

Stablecoins are fetched directly from the blockchain using the Mento SDK. Additional information is requred for the price and image.

1. Add a fiat ticker for the stablecoin in the SDK repo
2. Publish the new sdk package version and update the verion in the API repo
3. Add an svg image for the stablecoin to the tokens directory, ensuring the filename matches the symbol.
4. Deploy changes and verify in /stablecoins endpoint

Managing Reserve Addresses

1. Update addresses in api/reserve/config/addresses.config.ts
2. Deploy changes and verify in /reserve endpoints

Adding Reserve Assets

Reserve assets are fetched directly from the blockchain using the Mento SDK. However the metadata is needed to enrich the data. This is hardcoded to reduce the number of external calls.

1. Add asset configuration to api/reserve/config/assets.config.ts
2. Deploy changes and verify in /reserve endpoints

Deployment

The Mento Analytics API is automatically deployed to Google Cloud Run when PRs are merged into the main branch.

Production Deployment

1. When code is pushed or merged to the main branch, a CI/CD pipeline is triggered
2. The pipeline builds a Docker container using the Dockerfile
3. The container is pushed to the Google Artifact Registry
4. The new container is deployed to Cloud Run, replacing the previous version
5. Deployment status can be monitored in Google Cloud Build

Preview Deployments

Opening or updating a pull request automatically creates a preview deployment:

• Automatic: Each PR gets its own isolated Cloud Run service
• PR Integration: Pull requests receive comments with preview URLs
• Auto-cleanup: Preview deployments are deleted when PRs are merged or closed

See Preview Deployments Documentation for setup and usage details.

Monitoring & Logs

Application Logs

• Get logs from the command line: npm run logs (which is just a shortcut for ./scripts/get-logs.sh)
• Cloud Console Service Logs

Monitoring

• Google Cloud Run Service Monitoring
• Sentry error tracking
• Health checks: /health endpoint

Sentry Releases

The Analytics API integrates with Sentry for enhanced error tracking:

• Automatic source map uploads during deployment
• Release tracking for issue resolution
• Deployment tracking in Sentry

See Sentry Releases Documentation for setup and usage details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.