A Node.js/Express API for managing micro-donations on the Stellar blockchain network. Supports one-time donations, recurring donation schedules, wallet management, and donation analytics.

• Features
• Architecture
• Getting Started
• Runtime Configuration
• API Endpoints
• Database Schema
• Development
• Testing
• Troubleshooting
• Documentation

• One-Time Donations: Create and verify donations on Stellar testnet/mainnet
• Recurring Donations: Schedule automated recurring donations (daily, weekly, monthly)
• Wallet Management: Track wallets and query transaction history
• Analytics: Get donation statistics and summaries
• API Key Rotation: Zero-downtime key rotation with versioning and graceful deprecation
• Mock Mode: Development mode with simulated Stellar operations
• Debug Mode: Configurable verbose logging for local development troubleshooting
• Failure Simulation: Comprehensive network failure testing for robust error handling
• Automated Scheduler: Background service for executing recurring donations
• Rate Limiting: Protection against abuse with configurable request limits on donation endpoints
• Idempotency: Prevent duplicate transactions with idempotency key support
• Sensitive Data Masking: Automatic masking of secrets, API keys, and private values in all logs

                                     ┌─────────────┐
                                     │   Clients   │
                                     │ (Web/Mobile)│
                                     └──────┬──────┘
                                            │ HTTP/HTTPS
                                            ▼
                            ┌─────────────────────────────────┐
                            │      Express.js API Layer       │
                            │  /donations  /wallets  /stream  │
                            └──────┬──────────────────────────┘
                                            │
                                            ▼
                            ┌─────────────────────────────────┐
                            │       Service Layer             │
                            │  Stellar Service | Scheduler    │
                            └──────┬──────────────────────────┘
                                            │
                                ├──────────────┬────────────┐
                                ▼              ▼            ▼
                            ┌──────────┐   ┌──────────┐  ┌─────────┐
                            │ SQLite   │   │ Stellar  │  │ Horizon │
                            │ Database │   │ Network  │  │   API   │
                            └──────────┘   └──────────┘  └─────────┘

For detailed architecture documentation, see:

• Full Architecture Documentation - Comprehensive diagrams and component details
• Simple Architecture Diagram - ASCII art overview

• API Layer: Express.js routes handling HTTP requests
• Service Layer: Business logic and Stellar blockchain integration
• Data Layer: SQLite database for persistent storage
• Scheduler: Background service for recurring donations (runs every 60s)

• Node.js (v14 or higher)
• npm or yarn
• SQLite3

1. Clone the repository:

git clone https://github.com/yourusername/Stellar-Micro-Donation-API.git
cd Stellar-Micro-Donation-API

2. Install dependencies:

npm install

3. Initialize the database:

npm run init-db

4. Start the server:

npm start

The API will be available at http://localhost:3000

For development with auto-reload:

npm run dev

Enable verbose logging for troubleshooting:

# Add to .env file
DEBUG_MODE=true

# Start server with debug logging
npm start

See Debug Mode Documentation for details.

For comprehensive documentation of runtime environment assumptions, timeouts, retry logic, persistence requirements, background services, and operational procedures, see:

RUNTIME_ASSUMPTIONS.md - Complete runtime environment documentation

This document covers:

• Network Configuration: Timeouts, retry logic, external dependencies
• Persistence Layer: Database paths, storage requirements, backup strategies
• Background Services: Scheduler intervals, service behavior, lifecycle management
• Resource Requirements: Memory, disk, CPU, and network requirements by deployment scale
• Configuration Reference: All environment variables with validation rules
• Production Deployment: Warnings, readiness checklist, monitoring recommendations
• Operational Procedures: Graceful shutdown, troubleshooting guide

For detailed request/response examples with error handling, see the Complete API Examples Documentation.

• POST /donations - Create a new donation
• GET /donations - List all donations
• GET /donations/recent?limit=10 - Get recent donations
• GET /donations/:id - Get specific donation
• GET /donations/limits - Get donation amount limits
• POST /donations/verify - Verify transaction on blockchain
• PATCH /donations/:id/status - Update donation status

• POST /wallets - Create wallet metadata
• GET /wallets - List all wallets
• GET /wallets/:id - Get specific wallet
• GET /wallets/:publicKey/transactions - Get all transactions for a wallet
• PATCH /wallets/:id - Update wallet metadata

• POST /stream/create - Create recurring donation schedule
• GET /stream/schedules - List all schedules
• GET /stream/schedules/:id - Get specific schedule
• DELETE /stream/schedules/:id - Cancel schedule

• GET /stats/daily - Get daily donation statistics
• GET /stats/weekly - Get weekly donation statistics
• GET /stats/summary - Get summary analytics
• GET /stats/donors - Get donor statistics
• GET /stats/recipients - Get recipient statistics
• GET /stats/analytics-fees - Get analytics fee summary
• GET /stats/wallet/:walletAddress/analytics - Get wallet analytics

• GET /transactions - Get paginated transactions
• POST /transactions/sync - Sync wallet transactions from Stellar network

• GET /health - API health status

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    publicKey TEXT NOT NULL UNIQUE,
    createdAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE transactions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    senderId INTEGER NOT NULL,
    receiverId INTEGER NOT NULL,
    amount REAL NOT NULL,
    memo TEXT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (senderId) REFERENCES users(id),
    FOREIGN KEY (receiverId) REFERENCES users(id)
);

CREATE TABLE recurring_donations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    donorId INTEGER NOT NULL,
    recipientId INTEGER NOT NULL,
    amount REAL NOT NULL,
    frequency TEXT NOT NULL,
    nextExecutionDate DATETIME NOT NULL,
    status TEXT DEFAULT 'active',
    executionCount INTEGER DEFAULT 0,
    FOREIGN KEY (donorId) REFERENCES users(id),
    FOREIGN KEY (recipientId) REFERENCES users(id)
);

Stellar-Micro-Donation-API/
├── src/
│   ├── config/           # Configuration files
│   ├── middleware/       # Express middleware
│   ├── routes/           # API route handlers
│   │   ├── app.js
│   │   ├── donation.js
│   │   ├── wallet.js
│   │   ├── stream.js
│   │   ├── transaction.js
│   │   └── stats.js
│   ├── services/         # Business logic services
│   │   ├── StellarService.js
│   │   ├── MockStellarService.js
│   │   └── RecurringDonationScheduler.js
│   ├── scripts/          # Database scripts
│   │   └── initDB.js
│   └── utils/            # Utility functions
│       ├── database.js
│       └── permissions.js
├── data/                 # SQLite database files
├── docs/                 # Documentation
├── tests/                # Test files
└── package.json

The API uses role-based access control (RBAC) with three roles:

For detailed permission audit and security hardening, see API Key Permissions Audit.

Create a .env file in the project root:

STELLAR_NETWORK=testnet
HORIZON_URL=https://horizon-testnet.stellar.org
PORT=3000

For API key authentication, use the new database-backed system (recommended):

npm run keys:create -- --name "My Key" --role user --expires 365

Or use legacy environment-based keys (deprecated):

API_KEYS=your-api-key-here

Required at startup:

• API_KEYS (legacy method, or use database-backed keys)
• ENCRYPTION_KEY (required only when NODE_ENV=production)

Validated at startup (if provided):

• PORT must be an integer from 1 to 65535
• STELLAR_NETWORK must be one of testnet, mainnet, futurenet
• MOCK_STELLAR must be true or false
• HORIZON_URL must be a valid URL

The API supports zero-downtime key rotation. See:

• API Key Rotation Guide - Complete documentation
• Quick Start Guide - Common commands

Quick commands:

npm run keys:create -- --name "My Key" --role user --expires 365
npm run keys:list
npm run keys -- deprecate --id 1
npm run keys -- revoke --id 2

npm test

All tests are fully isolated and can run independently in any order:

# Run tests in random order to verify isolation
npm test -- --randomize

# Run with specific seed to reproduce order
npm test -- --randomize --seed=123456

For detailed information about test isolation, see Test Isolation Guide.

npm run test:coverage

This generates:

• Terminal coverage summary
• HTML report at coverage/lcov-report/index.html
• LCOV report for CI/CD integration
• JSON summary for programmatic access

npm run check-coverage

Validates that coverage meets minimum thresholds:

• Branches: 30%
• Functions: 30%
• Lines: 30%
• Statements: 30%

After running coverage, open the HTML report:

# macOS
open coverage/lcov-report/index.html

# Windows
start coverage/lcov-report/index.html

# Linux
xdg-open coverage/lcov-report/index.html

Coverage is automatically enforced in CI/CD:

• ✅ PRs must meet minimum 30% coverage thresholds
• ❌ Builds fail if coverage drops below thresholds
• 📊 Coverage reports uploaded as artifacts (30-day retention)

For detailed coverage documentation, see Coverage Guide.

npm test -- tests/integration.test.js

Comprehensive end-to-end tests for all donation endpoints:

npm test tests/donation-routes-integration.test.js

Coverage: 60+ test cases covering:

• All 7 donation endpoints
• Success and failure scenarios
• Validation, authentication, idempotency
• Rate limiting and error handling
• No live Stellar network required (uses MockStellarService)

For detailed information, see Donation Routes Integration Tests.

node test-recurring-donations.js

The project includes comprehensive failure simulation for testing network errors and retry logic:

# Run failure simulation tests
npm test tests/stellar-network-failures.test.js

# Run retry logic tests
npm test tests/stellar-retry-logic.test.js

Failure Types Tested:

• Timeouts and network errors
• Service unavailability
• Transaction failures (bad sequence, insufficient fee)
• Rate limiting
• Partial responses

For detailed information, see Stellar Failure Simulation Guide.

Having issues? We've got you covered!

• Server won't start? Check environment: npm run validate-env
• Tests failing? Clear cache: npx jest --clearCache
• Port in use? Kill process: kill -9 $(lsof -ti:3000)
• Dependencies broken? Fresh install: rm -rf node_modules package-lock.json && npm install

• Missing .env file → cp .env.example .env
• API keys required → Add API_KEYS=dev_key_123 to .env
• Use mock mode for development → MOCK_STELLAR=true

• Full Troubleshooting Guide - Comprehensive solutions
• Quick Reference - Fast fixes for common problems
• Check GitHub Issues for known problems
• Search Discussions for community help

Enable detailed logging for troubleshooting:

DEBUG_MODE=true LOG_VERBOSE=true npm start

The API can work with both Stellar testnet and mainnet. Configure via environment variables:

• Testnet (default): For development and testing
• Mainnet: For production use

The scheduler runs automatically when the server starts and checks for due donations every 60 seconds. It can be configured in src/services/RecurringDonationScheduler.js.

• API Examples - Complete request/response examples for all endpoints
• Quick Start Guide - Getting started quickly
• Troubleshooting Guide - Solutions for common issues
• Quick Reference - Fast fixes for common problems

• Architecture Documentation - Detailed system architecture
• Versioning Strategy - SemVer rules, release flow, and breaking change policy
• Stellar Failure Simulation - Network failure testing guide
• API Flow Diagram - API request flow
• Mock Stellar Guide - Using mock Stellar service

• Pre-Deployment Checklist - Production deployment verification
• CI Pipeline Documentation - Understanding CI/CD workflows
• Test Coverage Guide - Writing and maintaining tests

New to the project? Check out our Onboarding Checklist for a step-by-step guide to getting started!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run tests locally (npm test)
5. Check coverage (npm run test:coverage)
6. Ensure coverage thresholds are met (npm run check-coverage)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Note: All CI checks must pass before merge, including:

• ✅ All tests passing
• ✅ Coverage thresholds met (30% minimum)
• ✅ Linting checks passed
• ✅ Security checks passed

See Branch Protection and Coverage Guide for details.

This project is licensed under the MIT License.

• Stellar Development Foundation - Blockchain platform
• Stellar SDK - JavaScript SDK for Stellar

For issues and questions:

• Open an issue on GitHub
• Check the documentation
• Review the architecture guide

Built with ❤️ using Node.js and Stellar

For comprehensive documentation, see the Documentation Index.

• Pre-Deployment Checklist - Production deployment verification
• Quick Start Guide - Get started quickly
• API Examples - Complete API usage examples
• Coverage Guide - Test coverage documentation
• Mock Stellar Guide - Testing without network calls
• Versioning Strategy - SemVer rules, release flow, and breaking change policy