Skip to content

docs(readme): restore comprehensive architecture details and position stellar integration lower in doc #154

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0dillon merged 1 commit into from
Sep 16, 2026
Merged

docs(readme): restore comprehensive architecture details and position stellar integration lower in doc #154

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 56 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,71 @@
# HaloPay API
<!-- Optional: replace with a banner image. Keep it plain — a wordmark, not a stock illustration. -->
<h1 align="center">HaloPay API</h1>

The dedicated transaction settlement engine and anchor integration gateway for the HaloPay offline-first payment protocol.
<p align="center">
The dedicated settlement backend for HaloPay — a self-custodied Point-of-Sale and merchant settlement protocol built for crisis zones and offline environments where traditional digital banking infrastructure does not exist.
</p>

[![CI Status](https://img.shields.io/github/actions/workflow/status/HaloPaye/halopay-api/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/HaloPaye/halopay-api/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green?style=flat-square&logo=node.js)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
<p align="center">
<a href="https://github.com/HaloPaye/halopay-api/actions"><img alt="CI Status" src="https://img.shields.io/github/actions/workflow/status/HaloPaye/halopay-api/ci.yml?branch=main&style=flat-square&label=CI"></a>
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square"></a>
<img alt="Node 20+" src="https://img.shields.io/badge/Node-20%2B-green?style=flat-square&logo=node.js">
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.0%2B-blue?style=flat-square&logo=typescript">
</p>

---

## Overview
## Core Architecture

HaloPay API serves as the high-throughput settlement backend connecting offline point-of-sale terminals, decentralized mesh relays, and on-chain liquidity rails. It bridges transactions conducted in network-constrained environments to digital asset settlement and local fiat off-ramping.
1. **SEP-10 Web Authentication**: Standardized Stellar challenge-response flow issuing JWTs for secure merchant interactions.
2. **SEP-12 KYC Ingestion**: Ingests merchant verification fields and binary government ID photos (`multipart/form-data`) to transmit to Stellar anchors (e.g. MoneyGram).
3. **SEP-24 Fiat Off-Ramp Orchestration**: Programmatically converts aggregated USDC daily sales into local fiat via anchor off-ramp quotes and withdrawals.
4. **On-Chain Webhook & WebSocket Broadcaster**: Listens to Stellar Horizon payment streams for incoming USDC aid payments and broadcasts instant payment confirmations to merchant POS devices over WebSockets.

The backend orchestrates non-custodial merchant authentication, KYC identity ingestion for regulated off-ramps, automated quote locking, and resilient WebSocket event broadcasting for incoming payments.

---

## System Architecture
### Architecture Diagram

```mermaid
graph TD
Client[HaloPay POS Client] -->|Authentication| API[HaloPay API]
Relay[Mesh Gateway] -->|Batched Vouchers| API
API -->|KYC & Off-Ramp| Anchor[Banking Anchor / MoneyGram]
Horizon[Ledger RPC / Horizon] -->|Payment Stream| API
API -->|WebSocket Confirmation| Client
Client[HaloPay POS Client] -->|SEP-10 Auth| API[HaloPay API]
API -->|KYC & Settlement| Anchor[Stellar Anchor / MoneyGram]
Horizon[Stellar Horizon] -->|Webhook| API
API -->|WebSocket| Client
```

### Core Responsibilities
### How the Settlement Engine Works

The HaloPay backend is entirely focused on providing a seamless bridge between a merchant who may have intermittent connectivity and the robust Stellar on-chain ecosystem.

1. **Cryptographic Session Authentication:** Verifies client challenge signatures to issue short-lived JWTs, ensuring the backend only processes actions authorized by valid account keys.
2. **KYC Document Ingestion:** Handles secure `multipart/form-data` uploads for merchant identification files, validating MIME types and sizes before passing payloads to compliance partners.
3. **Fiat Off-Ramp Orchestration:** Coordinates automated conversions from digital settlement balances (e.g. USDC) into local fiat currency bank transfers and mobile money payouts.
4. **Resilient Event Streaming:** Maintains active event listeners on the settlement ledger, pushing real-time confirmation receipts to merchant terminals via WebSockets the instant connectivity is active.
5. **Auditing & Telemetry:** Records tamper-evident cryptographic audit logs with SHA-256 hash chaining and exports Prometheus metrics for latency and throughput monitoring.
1. **Authentication (SEP-10):** Merchants sign an authentication challenge using their private Stellar key. The API verifies this signature and issues a JWT. This ensures that the backend only orchestrates fiat withdrawals for verifiable wallet owners.
2. **KYC Uploads (SEP-12):** To comply with local regulations and anchor requirements, merchants must upload their government ID. Since these files are often large binary images, the API implements a secure `multipart/form-data` ingestion route that validates file sizes and MIME types before forwarding the payload directly to a secure storage bucket and the Anchor.
3. **Fiat Off-Ramp (SEP-24):** When a merchant chooses to settle their USDC balance to local fiat (e.g., to their bank account or mobile money wallet), the API initiates the SEP-24 interactive withdrawal flow with an anchor like MoneyGram, abstracting away the complex Stellar network fees and reserve requirements.
4. **Resilient WebSocket Delivery:** Since POS terminals can drop connection at any time, the API maintains a constant listener on the Stellar Horizon network. When it detects a payment to a registered merchant, it broadcasts it. If the merchant reconnects later, the system will instantly push any missed payments so the UI always reflects the true ledger state.

---

## Technology Stack
## Stellar & Soroban Architecture Integration

- **Runtime**: Node.js 20+ (TypeScript)
- **Web Framework**: Express.js
- **Settlement SDK**: `@stellar/stellar-sdk`
- **Real-Time Layer**: `ws` (WebSockets)
- **Data & Telemetry**: Winston, Prometheus, Zod
- **Testing**: Jest, Supertest
HaloPay API implements the gold standard for Stellar Ecosystem Proposals (SEPs) and Soroban RPC settlement:

* **SEP-10 (Web Authentication):** Cryptographically binds merchant sessions using challenge-transaction signatures verified against Stellar Horizon.
* **SEP-12 (KYC Client API):** Manages merchant customer identity data collection and secure forwarding to licensed Stellar anchors.
* **SEP-24 (Hosted Deposit & Withdrawal):** Orchestrates interactive fiat off-ramping flows with global anchors (e.g., MoneyGram), turning digital USDC revenue into local physical cash.
* **SEP-38 (Anchor RFQ Quotes):** Provides programmatic access to real-time indicative and firm price quotes between stellar assets and fiat currencies.
* **Soroban RPC & Horizon Stream Listeners:** Real-time event streaming of payment ledger entries, broadcasting instant cryptographic confirmation to offline POS terminals the moment internet connectivity is restored.

---

## Quick Start
## Tech Stack

- **Language**: TypeScript (Node.js 20+)
- **Framework**: Express.js
- **Blockchain Core**: `@stellar/stellar-sdk`
- **File Ingestion**: `multer` (handling multipart binary government ID images)
- **Real-Time Communication**: `ws` (WebSockets)
- **Validation & Auth**: Zod, JSON Web Tokens

### Prerequisites
- Node.js v20 or higher
- npm v9 or higher
---

### Installation & Local Run
## Setup & Quick Start

```bash
# Clone the repository
Expand All @@ -65,32 +75,23 @@ cd halopay-api
# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Run development server with live reload
# Run dev environment
npm run dev

# Run comprehensive test suite
# Run unit tests
npm test

# Build for production
npm run build
```

---

## API Overview
## Maintainers & Contact

| Method | Endpoint | Description |
| Maintainer | Contact / Telegram | Role |
| :--- | :--- | :--- |
| `GET` | `/health` | Service liveness and dependency status |
| `GET` | `/api/v1/auth/challenge` | Generate authentication challenge transaction |
| `POST` | `/api/v1/auth/token` | Exchange signed challenge for session JWT |
| `POST` | `/api/v1/kyc/customer` | Ingest merchant verification data and documents |
| `POST` | `/api/v1/offramp/initiate` | Initiate interactive fiat withdrawal flow |
| `GET` | `/api/v1/quotes` | Retrieve indicative and firm exchange rate quotes |
| `WS` | `/events` | Real-time payment confirmation stream |
| HaloPay Team | [@HaloPayDev](https://t.me/HaloPayDev) | Core Protocol Engineering |
| Lead Engineer | security@halopay.io | Security & Operations |

## Contributors

[![Contributors](https://contrib.rocks/image?repo=HaloPaye/halopay-api)](https://github.com/HaloPaye/halopay-api/graphs/contributors)

---

Expand Down
Loading