Backend
The Mass Payout backend is a NestJS application that provides REST API, database management, and blockchain synchronization.
What the Backend Does
- REST API: HTTP endpoints for frontend operations
- Database Management: PostgreSQL storage for assets, distributions, and payouts
- Blockchain Sync: Polls Hedera for events and syncs on-chain state
- Scheduled Execution: Automatic execution of scheduled distributions
- Batch Processing: Manages large-scale payouts with retry logic
Security and Deployment
The Mass Payout backend does not authenticate callers or check what they are allowed to do. Any client that can reach its HTTP port can import assets, create, cancel and retry payouts, pause and unpause assets, change the blockchain listener configuration and start or stop polling. Payouts are executed with the service's own DFNS / Hedera credentials, so a request that reaches the backend is acted on with full authority.
Mass Payout is an open-source reference accelerator. Authentication is deliberately left to the adopter's own API gateway and identity layer. Never expose the backend directly to the internet.
Required deployment model
- Private network only. Run the backend (default port
3000) on a private network or cluster-internal interface with no public ingress. The PostgreSQL database must not be reachable from outside that network either. - Put your own API gateway / identity layer in front of it. Every request must pass through a component you control that:
- authenticates the caller (for example OIDC / OAuth 2.0, SSO, or mTLS for service-to-service calls);
- authorizes the route (see the table below) and, if several asset owners or tenants share one instance, restricts which
assetId/distributionIdvalues each caller may act on. The backend has no notion of ownership or tenants; - applies rate limits and request size limits;
- terminates TLS.
- Serve the frontend behind the same identity layer. The admin frontend calls the backend directly and sends no credentials of its own.
CORS_ORIGINSonly controls which browser origins may read responses; it is not an access control. - Forward the authenticated identity for the audit log. Set
AUDIT_ACTOR_HEADERto the header your gateway sets after authentication (for examplex-authenticated-user). Make the gateway overwrite that header on every request so clients cannot forge it. - Keep secrets out of files. Supply
POSTGRESQL_PASSWORD,DFNS_SERVICE_ACCOUNT_AUTHORIZATION_TOKEN,DFNS_SERVICE_ACCOUNT_PRIVATE_KEY_OR_PATHand the other DFNS values from a secrets manager.docker-compose.ymlis for a throwaway local database only. - Keep Swagger internal. Swagger UI is only mounted when
APP_ENV=local; do not set that in shared environments.
Suggested route policy for the gateway
| Access level | Routes |
|---|---|
| Read (operators) | GET /assets, GET /assets/:assetId, GET /assets/:hederaTokenAddress/metadata, GET /assets/:assetId/distributions, GET /distributions, GET /distributions/:distributionId, GET /distributions/:distributionId/holders, GET /blockchain/config |
| Payout operator | POST /assets/import, PATCH /assets/:assetId/pause, PATCH /assets/:assetId/unpause, PATCH /assets/:assetId/enable-sync, PATCH /assets/:assetId/disable-sync, POST /assets/:assetId/distributions/payout, PATCH /distributions/:distributionId/cancel, PATCH /distributions/:distributionId/retry |
| Administrator | POST /blockchain/config, PATCH /blockchain/polling/start, PATCH /blockchain/polling/stop |
POST /assets/import deploys a LifeCycleCashFlow contract paid for by the service account, and the payout routes move funds, so treat them as privileged.
What the backend does on its own
These are defence in depth. They do not replace the gateway.
- Request validation: every body and query is validated with
class-validator; unknown fields are rejected.limiton list endpoints is capped at 1000. - Mirror node allow-list: automated payouts are triggered by
Transferevents read from the mirror node, so the mirror node is the trust root for those payouts.POST /blockchain/configonly accepts anhttp/httpsmirror node URL whose host is inBLOCKCHAIN_MIRROR_NODE_ALLOWED_HOSTS(default: the public Hedera mirror nodes plus the host ofBLOCKCHAIN_MIRROR_NODE_URL), and the listener re-checks the stored URL before every poll. This stops the listener being pointed at internal services or at a server that returns forged events. - Bounded metadata lookups:
GET /assets/:hederaTokenAddress/metadataallows at most 10 concurrent on-chain lookups and answers429beyond that. - Generic error responses:
400,404and409responses carry a generic message and the error class name (for exampleAssetPausedError). Asset names, token addresses and other details are written to the server log only. - Audit log lines: every
POST,PUT,PATCHandDELETEwrites one JSON line with theAuditlogger context:action,method,route, pathparams, the names (not values) of the body fields,actor(fromAUDIT_ACTOR_HEADER, otherwiseunknown),sourceIp,outcomeanddurationMs. Ship these lines to your log store. - No infrastructure URLs in logs: mirror node requests are logged by host and path only.
Security-related environment variables
| Variable | Purpose |
|---|---|
CORS_ORIGINS | Comma-separated browser origins allowed to call the API (default http://localhost:5173). Not an access control. |
AUDIT_ACTOR_HEADER | Header set by your gateway with the authenticated caller; recorded as actor in audit lines. |
BLOCKCHAIN_MIRROR_NODE_ALLOWED_HOSTS | Comma-separated mirror node hosts the listener may poll. Empty: public Hedera mirror nodes plus the BLOCKCHAIN_MIRROR_NODE_URL host. |
APP_ENV | local mounts Swagger UI at /swagger; use another value outside local development. |
Available Guides
Architecture Overview
Learn about the Domain-Driven Design architecture and application layers.
Database Schema
Understand the PostgreSQL schema, entities, and relationships.
Blockchain Integration
How the backend syncs with Hedera and processes scheduled payouts.
Running & Testing
Development setup, deployment, and testing strategies.
Quick Start
# Start PostgreSQL
cd apps/mass-payout/backend
docker-compose up -d
# Configure environment
cp .env.example .env
# Edit .env with your configuration
# Run backend in development mode
npm run mass-payout:backend:dev
Backend runs on http://localhost:3000; with APP_ENV=local, Swagger docs are at http://localhost:3000/swagger. Before deploying anywhere other than your own machine, read Security and Deployment.
Next Steps
- SDK Integration - Integrate Mass Payout SDK
- Smart Contracts - LifeCycle Cash Flow contract
- API Documentation - REST API reference