Fabric SaaS API (peerpay-saas-fabric-api)

The peerpay-saas-fabric-api repository hosts the Node.js REST API. It is the bridge between external applications (notably the Blockchain Explorer) and the underlying Hyperledger Fabric network.

At a Glance

Property Value
Role Control / integration plane (REST API, business logic, Fabric client)
Stack Node.js 20+, Express.js, fabric-network SDK, PostgreSQL, Kafka
Default port 5000 (or 8080, depending on Compose setup)
Auth JWT Bearer tokens
State PostgreSQL (off-chain metadata, users, cached views)

Purpose

The API provides a clean MVC architecture for interacting with the blockchain securely. It exposes endpoints for:

  • Authentication — JWT-based access.
  • Blockchain transactions — invoking the bankloan and p2ptransfer chaincodes.
  • Network exploration — retrieving blocks, transaction history, and node status.
  • System administration — managing peers, channels, and organisation data.
  • Remote-peer onboarding — generating crypto bundles consumed by peerpay-enterprise-blockchain.

Prerequisites

  • The Main Fabric Network is up and reachable (orderer, peers, CAs).
  • A reachable PostgreSQL instance (local Docker container is fine for development).
  • A populated .env with at minimum:
    • JWT_SECRET
    • PostgreSQL credentials (PG_HOST, PG_USER, PG_PASSWORD, PG_DATABASE)
    • Fabric connection profile path and wallet path
    • Kafka and SMTP settings (only if those features are enabled)

How It Runs Independently

The API is a standard Express.js application. It can be run as a container or natively for development.

# Container (recommended for production-like setups)
docker compose up -d fabric-api
# Local development with hot reload
npm install
npm run dev

It maintains its own state in PostgreSQL, which is used for caching and off-chain metadata so that explorer endpoints stay responsive without round-tripping to Fabric for every request.

Communication

  • Blockchain integration — uses the fabric-network Node.js SDK to establish a secure gRPC + TLS connection to the Main Fabric Network. It reads connection profiles and wallet identities from the host machine to authenticate transactions.
  • Frontend interaction — accepts HTTP REST requests from the Blockchain Explorer. CORS allows only the configured frontend origin(s).
  • Event streaming — connects to an external Kafka broker to publish and subscribe to domain events (e.g. dev.blockchain.record.loan). This enables asynchronous workflows such as sending emails or updating external systems when a loan is approved on chain.
  • Notifications — sends emails through the configured SMTP server.
  • Metrics & logging — automatically pushes logs to Grafana Loki when configured, allowing centralised observability.