Cowrie-Remit Backend ⚡

Stellar Drips Wave · Off-chain FX Rate Oracle & Transaction Indexer
Organization: Cowrie-Labs · Maintainer: @Alhaji-naira

---

Overview

cowrie-remit-backend is a high-performance Fastify API server (TypeScript) that acts as the off-chain intelligence layer for the Cowrie-Remit protocol:

• FX Oracle — Serves real-time (mock → production: live feed) conversion rates for supported currency corridors.
• Transfer Indexer — Tracks pending, settled, and refunded cross-border transfer records synced from on-chain Soroban events.
• Stellar Horizon Bridge — Queries the Stellar network for the latest ledger sequence used by the settlement contract.

---

API Endpoints

Method	Route	Description
GET	/health	Health check + latest Stellar ledger
GET	/fx/rate?from=NGN&to=USD	Single FX rate lookup
GET	/fx/rates	All supported FX pairs
GET	/transfers	List all indexed transfers
GET	/transfers/:id	Get single transfer by ID
POST	/transfers	Index a new transfer (event listener)
PATCH	/transfers/:id/status	Update transfer status

Interactive docs available at http://localhost:4000/docs (Swagger UI)

---

Supported Currency Corridors

Pair	Rate (approx.)
NGN/USD	0.00065
GHS/USD	0.073
KES/USD	0.0077
ZAR/USD	0.055
EUR/USD	1.085
GBP/USD	1.270

---

Getting Started (API Contributors)

Prerequisites

• Node.js ≥ 20
• npm ≥ 10

Install & Run

cd Cowrie-Remit-Backend
npm install

# Development (hot-reload)
npm run dev

# Production build
npm run build && npm start

Environment Variables

Create a .env file:

PORT=4000
HOST=0.0.0.0
STELLAR_NETWORK=testnet          # testnet | mainnet
ALLOWED_ORIGINS=http://localhost:3000
API_BASE_URL=http://localhost:4000

---

Project Structure

Cowrie-Remit-Backend/
├── package.json
├── tsconfig.json
└── src/
    └── index.ts          # Fastify app, routes, FX oracle, Horizon client

---

Contributing (Drips Wave)

This repository is part of the Stellar Drips Wave program.

1. Fork under Cowrie-Labs
2. Create a branch: git checkout -b feat/live-fx-feed
3. Replace mock FX rates in src/index.ts with a live data source (e.g. ExchangeRate-API, CoinGecko)
4. Add unit tests in src/__tests__/
5. Open a PR — describe the data source, rate-limiting strategy, and caching approach

Good First Issues for Drips Contributors

• Integrate a live FX rate provider (ExchangeRate-API / Open Exchange Rates)
• Add PostgreSQL persistence for transfer records (replace in-memory Map)
• Add a Soroban event listener to auto-index on-chain contract events
• Add JWT-based API key authentication for the POST/PATCH endpoints
• Set up Redis caching for FX rates (TTL: 60s)

---

License

MIT © Cowrie-Labs