{"id":22709568,"url":"https://github.com/mento-protocol/mento-analytics-api","last_synced_at":"2025-03-29T21:22:09.185Z","repository":{"id":265297924,"uuid":"852800108","full_name":"mento-protocol/mento-analytics-api","owner":"mento-protocol","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-21T20:57:42.000Z","size":335,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T21:24:31.796Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mento-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-05T12:56:45.000Z","updated_at":"2025-03-21T13:26:26.000Z","dependencies_parsed_at":"2024-11-28T20:18:50.005Z","dependency_job_id":"0043b683-cc5e-4dbf-b0a0-3d049bc29d5c","html_url":"https://github.com/mento-protocol/mento-analytics-api","commit_stats":null,"previous_names":["mento-protocol/mento-analytics-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fmento-analytics-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fmento-analytics-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fmento-analytics-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fmento-analytics-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mento-protocol","download_url":"https://codeload.github.com/mento-protocol/mento-analytics-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246244437,"owners_count":20746440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-10T11:10:23.707Z","updated_at":"2025-03-29T21:22:09.170Z","avatar_url":"https://github.com/mento-protocol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mento Analytics API\n\nThe 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.\n\nThe API can be used by consumers to fetch information about the Mento Stables, the Reserve and it's composition.\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v21+)\n- pnpm\n\n### Installation\n\n```bash\n# Install dependencies\npnpm install\n\n# Start development server\npnpm run start:dev\n\n# Build for production\npnpm run build\n\n# Start production server\npnpm run start:prod\n```\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n``` bash\ncp .env.example .env\n```\n\nYou'll need to obtain API keys for the Coinmarket cap \u0026 exchange rates API then add them to your env file\n\n## Key Features\n\n- **Stablecoin Analytics:** Tracks the total supply of all Mento stables\n- **Multi-Chain Reserve Tracking:** Monitors reserve assets across Celo, Ethereum and Bitcoin networks\n- **Reserve Composition Analysis:** Detailed breakdown of reserve holdings and their USD values\n- **Collateralization Metrics**: Real-time tracking of reserve-to-stablecoin ratios\n- **Automated Cache Management**: Optimized data delivery with cache warming\n- **Health Monitoring**: System health checks across all integrated services\n\n## Project Structure\n\nBelow is the project structure:\n\n```bash\nsrc/\n├── app.module.ts            # Root module\n├── main.ts                  # Entry point\n├── api/                     # API features\n│   ├── stablecoins/         # Stablecoin-related endpoints\n│   ├── reserve/             # Reserve-related endpoints\n│   └── health/              # Health check endpoints\n├── common/                      \n│   └── services/            # Shared services   \n├── types/                   # Shared types/interfaces\n└── utils/                   # Utility functions\n```\n\n## System Architecture\n\nThe 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:\n\n![Mento Analytics API Overview](docs/architecture.png)\n\n## API Documentation\n\nDetailed documentaion for the API endpoints is available at `/docs` when running the application.\n\n## Data Sources \u0026 Updates\n\n### Data Sources\n\n- On-chain data from multiple networks:\n  - Celo: Mento SDK beta + Infura\n  - Ethereum: Mento SDK beta + Infura\n  - Bitcoin: Blockchain.info \u0026 Blockstream\n- Price feeds: CoinmarketCap API for real-time asset pricing\n- Exchange rate data: API Layer exchange rates API\n\n### Data Update Frequency\n\nData provided by the API will be \u003c 1 hour old. Data is only updated on an hourly schedule.\n\n### Cache Management\n\nThe API implements a cache warming strategy to ensure data availability:\n\n1. Initial warmup on service start\n2. Scheduled refreshes every hour\n3. Manual invalidation via admin endpoints - To Be Added\n\n## Configuration Guide\n\n### Adding New Stablecoins\n\nStablecoins are fetched directly from the blockchain using the Mento SDK. Additional information is requred for the price and image.\n\n1. Add a fiat ticker for the stablecoin in the [SDK repo](https://github.com/mento-protocol/mento-sdk/blob/7656050794eef5609193cbafd53ea23f04df4d09/src/constants/stableTokenMetadata.ts#L13)\n2. Publish the new sdk package version and update the verion in the API repo\n3. Add an svg image for the stablecoin to the [tokens directory](https://github.com/mento-protocol/mento-analytics-api/tree/main/public/tokens), ensuring the filename matches the symbol.\n4. Deploy changes and verify in `/stablecoins` endpoint\n\n### Managing Reserve Addresses\n\n1. Update addresses in `api/reserve/config/addresses.config.ts`\n2. Deploy changes and verify in `/reserve` endpoints\n\n### Adding Reserve Assets\n\nReserve 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.\n\n1. Add asset configuration to `api/reserve/config/assets.config.ts`\n2. Deploy changes and verify in `/reserve` endpoints\n\n## Deployment\n\nThe Mento Analytics API is automatically deployed to Google Cloud Run when changes are committed to the `main` branch.\n\n### Deployment Process\n\n1. When code is pushed or merged to the `main` branch, a CI/CD pipeline is triggered\n2. The pipeline builds a Docker container using the Dockerfile in the repository\n3. The container is pushed to Google Container Registry\n4. The new container is deployed to Cloud Run, replacing the previous version\n5. Deployment status can be monitored in the Google Cloud Console\n\n## Monitoring \u0026 Logs\n\n### Application Logs\n\n- Get logs from the command line: `npm run logs` (which is just a shortcut for `./bin/get-logs.sh`)\n- GCP Cloud Logging: [View Logs](https://console.cloud.google.com/run/detail/us-central1/mento-analytics-api/logs?invt=AbmVMA\u0026project=mento-prod)\n- Log levels:\n  - INFO: Regular operation events\n  - WARN: Potential issues requiring attention\n  - ERROR: Critical issues affecting operation\n  - DEBUG: Detailed information for development\n\n### Monitoring Dashboard\n\n- System metrics: [Cloud Monitoring](https://console.cloud.google.com/run/detail/us-central1/mento-analytics-api/metrics?invt=AbmVMA\u0026project=mento-prod)\n- Sentry error tracking: [View Issues](https://mento-labs.sentry.io/issues/?project=4508518701268992\u0026statsPeriod=14d)\n- Health checks: `/health` endpoint\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmento-protocol%2Fmento-analytics-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmento-protocol%2Fmento-analytics-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmento-protocol%2Fmento-analytics-api/lists"}