Skip to content

README.md

Latest commit

 

History

History
163 lines (118 loc) · 6.33 KB

README.md

File metadata and controls

163 lines (118 loc) · 6.33 KB
Raw

Cashu Gateway

Cashu Gateway provides a RESTful service for creating and settling Lightning Network invoices. The project is organised as modular Maven components.

Modules

Module Description
cashu-gateway-model Domain entities and Spring Data JPA configuration.
cashu-gateway-rest Spring Boot application exposing REST endpoints for GatewayQuote and GatewayPayment entities.
cashu-gateway-client Small Java client for interacting with the REST service.
cashu-gateway-phoenixd Implementation of the Gateway interface that communicates with a phoenixd node.
cashu-gateway-webhook Servlet application for processing incoming webhook callbacks.
cashu-gateway-dummy Simple mock implementation of the Gateway interface used for testing.
cashu-gateway-test Integration tests that exercise the phoenixd gateway and REST API. 
/ cashu-gateway-model      Domain model and JPA entities
/ cashu-gateway-rest       Spring Boot REST service
/ cashu-gateway-client     REST client library
/ cashu-gateway-phoenixd   phoenixd integration of Gateway
/ cashu-gateway-webhook    Servlet webhook handler
/ cashu-gateway-dummy      Dummy Gateway implementation
/ cashu-gateway-test       Integration tests

Requirements

  • Java 21 or newer
  • Maven 3.8+ (or use the included Maven Wrapper ./mvnw)
  • Docker (for running the provided containers)

Building

To build all modules run the standard Maven build using the wrapper:

./mvnw package

Individual modules can be built with the -pl flag, for example:

./mvnw -pl cashu-gateway-rest package

Running the REST Service

A docker-compose.yml file is provided to start PostgreSQL, phoenixd and the REST service. After Docker and Docker Compose are installed, simply run:

docker-compose up

This will start the following containers:

  • cashu-gateway-db – PostgreSQL database on port 5432.
  • phoenixd – phoenixd Lightning node on port 9740.
  • cashu-gateway-rest – Spring Boot application exposing HTTP on port 8080.

The REST application can also be launched directly using Maven:

./mvnw -pl cashu-gateway-rest spring-boot:run

Database connection properties can be overridden via environment variables. In docker-compose.yml these are set as:

SPRING_DATASOURCE_URL=jdbc:postgresql://cashu-gatewaw-db:5432/cashu-gateway
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=password

API Overview

The REST layer is implemented using Spring Data REST. A full description of each endpoint is available in the API reference. Once the service is running the following resources are available:

  • GET /quote – list quotes
  • POST /quote – create a quote
  • GET /quote/{id} – fetch a quote by its numeric id
  • GET /quote/search/findByQuoteId?quoteId=... – fetch a quote using its external quote id
  • GET /quote/search/findByInvoiceId?invoiceId=... – find a quote by the Lightning invoice id

Likewise for payments:

  • GET /payment – list payments
  • POST /payment – create a payment
  • GET /payment/{id} – fetch a payment by id
  • GET /payment/search/findByPaymentId?paymentId=...
  • GET /payment/search/findByQuoteId?quoteId=...

The cashu-gateway-client module demonstrates basic interaction with these endpoints; see the API reference for payload details.

Webhook Handler

The cashu-gateway-webhook module provides a simple servlet mapped at /webhook. PhoenixWebhookValidator validates requests originating from phoenixd and updates payments through the REST client. Requests must include a wid parameter which identifies the type of webhook request to validate. See the API reference for the underlying REST endpoints.

Running Tests

Integration tests reside in the cashu-gateway-test module and require a running phoenixd instance as well as the REST service. Execute them with:

./mvnw -pl cashu-gateway-test test

Running ./mvnw test at the project root will also produce an aggregated JaCoCo coverage report under target/site/jacoco-aggregate/index.html.

Dockerfile

A Dockerfile for the REST service is available under cashu-gateway-rest/Dockerfile. It performs a two-stage build using the Maven base image and produces a runnable JAR:

FROM maven:3.9.6-eclipse-temurin-21 AS build
WORKDIR /app
COPY . .
RUN ./mvnw -pl cashu-gateway-rest -am package -DskipTests

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/cashu-gateway-rest/target/cashu-gateway-rest-*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/app.jar"]

Container Publishing

The cashu-gateway-rest module uses the Jib Maven plugin to build and publish a Docker image. Running:

./mvnw deploy

builds all modules and pushes docker.398ja.xyz/cashu-gateway-rest tagged with both the project version and latest, so consumers can pull the most recent build without specifying a version.

Configuration

Module Option / Variable Description
cashu-gateway-rest SPRING_DATASOURCE_URL JDBC connection string.
SPRING_DATASOURCE_USERNAME Database user.
SPRING_DATASOURCE_PASSWORD Database password.
cashu-gateway-phoenixd phoenixd.currency Invoice currency unit.
phoenixd.expiration Quote lifetime in seconds.
phoenixd.fee.percent Percentage fee.
phoenixd.fee.fixed Fixed fee.
phoenixd.expiry Invoice expiry in seconds.
phoenixd.lnaddress Enable LN address support.
<wid>.wid Webhook identifier mapping.
webhook.base_url Base URL for webhook callbacks.
cashu-gateway-dummy dummy.payment_status Mock payment status.
dummy.amount Dummy payment amount.
dummy.expiry Quote expiry in seconds.
dummy.fee_reserve Fee reserve amount.
webhook.base_url Base URL for webhook callbacks.

Each module reads configuration from its app.properties file or environment variables. See the guides in docs for deployment details.

License

This project currently does not include an explicit license. Contact the repository owner for usage terms.