Skip to content

Commit cf89fa7

Browse files
tcheerictcheeric
authored
Merge branch 'develop' into codex/document-request-parameters-and-methods
2 parents ac3424a + 79d16d1 commit cf89fa7

10 files changed

Lines changed: 376 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
# Cashu Gateway
22

3-
Cashu Gateway is a collection of Java modules that provide a simple gateway service for creating and settling Lightning Network invoices. It exposes a Spring Boot REST API backed by PostgreSQL and includes optional integrations such as a Phoenixd implementation and a servlet based webhook.
3+
Cashu Gateway provides a RESTful service for creating and settling Lightning Network invoices. The project is organised as modular Maven components.
44

5-
## Project Structure
6-
7-
This project is organised as a multi-module Maven build. The root `pom.xml` aggregates the following modules:
5+
## Modules
86

97
| Module | Description |
108
| ------ | ----------- |
@@ -76,7 +74,7 @@ SPRING_DATASOURCE_PASSWORD=password
7674

7775
## API Overview
7876

79-
The REST layer is implemented using Spring Data REST. Once the service is running the following resources are available:
77+
The REST layer is implemented using Spring Data REST. A full description of each endpoint is available in the [API reference](docs/reference/api.md). Once the service is running the following resources are available:
8078

8179
* `GET /quote` – list quotes
8280
* `POST /quote` – create a quote
@@ -92,11 +90,11 @@ Likewise for payments:
9290
* `GET /payment/search/findByPaymentId?paymentId=...`
9391
* `GET /payment/search/findByQuoteId?quoteId=...`
9492

95-
The `cashu-gateway-client` module demonstrates basic interaction with these endpoints.
93+
The `cashu-gateway-client` module demonstrates basic interaction with these endpoints; see the [API reference](docs/reference/api.md) for payload details.
9694

9795
## Webhook Handler
9896

99-
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.
97+
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](docs/reference/api.md) for the underlying REST endpoints.
10098

10199
## Running Tests
102100

@@ -128,9 +126,27 @@ ENTRYPOINT ["java","-jar","/app/app.jar"]
128126

129127
## Configuration
130128

131-
Each module that implements the `Gateway` interface provides its own `app.properties` file containing configuration options. For example `cashu-gateway-phoenixd` defines settings for invoice expiry and webhook URLs, while `cashu-gateway-dummy` exposes simple dummy values. Adjust these files to suit your environment.
129+
| Module | Option / Variable | Description |
130+
| ------ | ----------------- | ----------- |
131+
| **cashu-gateway-rest** | `SPRING_DATASOURCE_URL` | JDBC connection string. |
132+
| | `SPRING_DATASOURCE_USERNAME` | Database user. |
133+
| | `SPRING_DATASOURCE_PASSWORD` | Database password. |
134+
| **cashu-gateway-phoenixd** | `phoenixd.currency` | Invoice currency unit. |
135+
| | `phoenixd.expiration` | Quote lifetime in seconds. |
136+
| | `phoenixd.fee.percent` | Percentage fee. |
137+
| | `phoenixd.fee.fixed` | Fixed fee. |
138+
| | `phoenixd.expiry` | Invoice expiry in seconds. |
139+
| | `phoenixd.lnaddress` | Enable LN address support. |
140+
| | `<wid>.wid` | Webhook identifier mapping. |
141+
| | `webhook.base_url` | Base URL for webhook callbacks. |
142+
| **cashu-gateway-dummy** | `dummy.payment_status` | Mock payment status. |
143+
| | `dummy.amount` | Dummy payment amount. |
144+
| | `dummy.expiry` | Quote expiry in seconds. |
145+
| | `dummy.fee_reserve` | Fee reserve amount. |
146+
| | `webhook.base_url` | Base URL for webhook callbacks. |
147+
148+
Each module reads configuration from its `app.properties` file or environment variables. See the guides in [docs](docs) for deployment details.
132149

133150
## License
134151

135-
This project currently does not include an explicit license file. If you plan to use it in production or as the basis of other work, please consult the repository owner.
136-
152+
This project currently does not include an explicit license. Contact the repository owner for usage terms.

‎cashu-gateway-client/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Cashu Gateway Client
2+
3+
This module provides a Java client for interacting with the Cashu Gateway REST API.
4+
5+
See the [API reference](../docs/reference/api.md) for details of the available endpoints.
6+

‎cashu-gateway-webhook/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Cashu Gateway Webhook
2+
3+
This module provides a servlet endpoint that processes incoming phoenixd webhook callbacks and updates payments through the REST client.
4+
5+
The REST endpoints used by this module are documented in the [API reference](../docs/reference/api.md).
6+

‎docs/building.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Building
2+
3+
Compile all modules from the project root:
4+
5+
```bash
6+
mvn package
7+
```
8+
9+
Build a specific module:
10+
11+
```bash
12+
mvn -pl <module> package
13+
```
14+
15+
See [requirements](requirements.md) for setup details.

‎docs/docker.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Docker Usage
2+
3+
The REST service includes a Dockerfile at `cashu-gateway-rest/Dockerfile`. Build the image:
4+
5+
```bash
6+
docker build -t cashu-gateway-rest cashu-gateway-rest
7+
```
8+
9+
`docker-compose.yml` can build and run all images:
10+
11+
```bash
12+
docker-compose build
13+
docker-compose up
14+
```

‎docs/reference/api.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# REST API Reference
2+
3+
This document describes the HTTP endpoints exposed by the Cashu Gateway REST service.
4+
5+
## Quote endpoints
6+
7+
### List quotes
8+
9+
`GET /quote`
10+
11+
Optional query parameters: `page`, `size`, `sort`.
12+
13+
Example request:
14+
15+
```bash
16+
curl http://localhost:8080/quote
17+
```
18+
19+
Example response:
20+
21+
```json
22+
{
23+
"_embedded": {
24+
"quotes": [
25+
{
26+
"id": 1,
27+
"quoteId": "Q123",
28+
"invoiceId": "INV1",
29+
"expiry": 3600,
30+
"description": "Example quote",
31+
"request": "lnbc1...",
32+
"amount": 1000,
33+
"unit": "sats",
34+
"state": "PENDING",
35+
"direction": "RECEIVE"
36+
}
37+
]
38+
},
39+
"page": {
40+
"size": 20,
41+
"totalElements": 1,
42+
"totalPages": 1,
43+
"number": 0
44+
}
45+
}
46+
```
47+
48+
### Create quote
49+
50+
`POST /quote`
51+
52+
Required JSON body fields: `quoteId`, `invoiceId`, `expiry`, `description`, `request`, `amount`, `unit`.
53+
54+
Example request:
55+
56+
```bash
57+
curl -X POST http://localhost:8080/quote \
58+
-H "Content-Type: application/json" \
59+
-d '{
60+
"quoteId": "Q123",
61+
"invoiceId": "INV1",
62+
"expiry": 3600,
63+
"description": "Example quote",
64+
"request": "lnbc1...",
65+
"amount": 1000,
66+
"unit": "sats"
67+
}'
68+
```
69+
70+
Example response (201 Created):
71+
72+
```json
73+
{
74+
"id": 1,
75+
"quoteId": "Q123",
76+
"invoiceId": "INV1",
77+
"expiry": 3600,
78+
"description": "Example quote",
79+
"request": "lnbc1...",
80+
"amount": 1000,
81+
"unit": "sats",
82+
"state": "PENDING",
83+
"direction": "RECEIVE"
84+
}
85+
```
86+
87+
### Get quote by id
88+
89+
`GET /quote/{id}`
90+
91+
Example request:
92+
93+
```bash
94+
curl http://localhost:8080/quote/1
95+
```
96+
97+
### Find quote by quoteId
98+
99+
`GET /quote/search/findByQuoteId?quoteId=<quote-id>`
100+
101+
Required query parameter: `quoteId`.
102+
103+
Example request:
104+
105+
```bash
106+
curl "http://localhost:8080/quote/search/findByQuoteId?quoteId=Q123"
107+
```
108+
109+
### Find quote by invoiceId
110+
111+
`GET /quote/search/findByInvoiceId?invoiceId=<invoice-id>`
112+
113+
Required query parameter: `invoiceId`.
114+
115+
Example request:
116+
117+
```bash
118+
curl "http://localhost:8080/quote/search/findByInvoiceId?invoiceId=INV1"
119+
```
120+
121+
## Payment endpoints
122+
123+
### List payments
124+
125+
`GET /payment`
126+
127+
Optional query parameters: `page`, `size`, `sort`.
128+
129+
Example request:
130+
131+
```bash
132+
curl http://localhost:8080/payment
133+
```
134+
135+
### Create payment
136+
137+
`POST /payment`
138+
139+
Required JSON body fields: `request`, `paymentId`, `quoteId`, `sourceCurrency`, `amount`, `lightningNetworkFee`, `totalAmount`, `paymentHash`, `paymentPreimage`.
140+
141+
Example request:
142+
143+
```bash
144+
curl -X POST http://localhost:8080/payment \
145+
-H "Content-Type: application/json" \
146+
-d '{
147+
"request": "lnbc1...",
148+
"paymentId": "P123",
149+
"quoteId": "Q123",
150+
"sourceCurrency": "sats",
151+
"amount": 1000,
152+
"lightningNetworkFee": 10,
153+
"totalAmount": 1010,
154+
"paymentHash": "hash",
155+
"paymentPreimage": "preimage"
156+
}'
157+
```
158+
159+
### Get payment by id
160+
161+
`GET /payment/{id}`
162+
163+
Example request:
164+
165+
```bash
166+
curl http://localhost:8080/payment/1
167+
```
168+
169+
### Find payment by paymentId
170+
171+
`GET /payment/search/findByPaymentId?paymentId=<payment-id>`
172+
173+
Required query parameter: `paymentId`.
174+
175+
Example request:
176+
177+
```bash
178+
curl "http://localhost:8080/payment/search/findByPaymentId?paymentId=P123"
179+
```
180+
181+
### Find payment by quoteId
182+
183+
`GET /payment/search/findByQuoteId?quoteId=<quote-id>`
184+
185+
Required query parameter: `quoteId`.
186+
187+
Example request:
188+
189+
```bash
190+
curl "http://localhost:8080/payment/search/findByQuoteId?quoteId=Q123"
191+
```
192+
193+
## Error codes
194+
195+
The API uses standard HTTP status codes:
196+
197+
* `201 Created` – resource created successfully.
198+
* `400 Bad Request` – missing or malformed data.
199+
* `404 Not Found` – resource does not exist.
200+
* `500 Internal Server Error` – unexpected server error.
201+
202+
Error responses follow the default [Spring Boot error format](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#web.error-handling).
203+

‎docs/reference/configuration.md‎

Lines changed: 59 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,62 @@
1-
# Configuration
1+
# Configuration Reference
22

3-
Modules supply `app.properties` files for custom settings. Common overrides for the REST service can be provided via environment variables:
3+
This document lists configuration properties and environment variables available across Cashu Gateway modules.
44

5-
```
6-
SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/cashu-gateway
7-
SPRING_DATASOURCE_USERNAME=postgres
8-
SPRING_DATASOURCE_PASSWORD=password
9-
```
5+
## REST module ([cashu-gateway-rest](../../cashu-gateway-rest))
106

11-
Set the system property `gateway.api.base_url` to change the base URL used by the client library.
7+
| Property | Default | Description |
8+
| --- | --- | --- |
9+
| `spring.application.name` | `cashu-gateway-spring` | Spring Boot application name. |
10+
| `spring.datasource.url` | `jdbc:postgresql://localhost:5432/cashu-gateway` | JDBC connection string. |
11+
| `spring.datasource.driverClassName` | `org.postgresql.Driver` | JDBC driver class. |
12+
| `spring.datasource.username` | `postgres` | Database username. |
13+
| `spring.datasource.password` | `password` | Database password. |
14+
| `spring.jpa.database-platform` | `org.hibernate.dialect.PostgreSQLDialect` | Hibernate dialect. |
15+
| `spring.jpa.hibernate.ddl-auto` | `create-drop` | JPA schema generation strategy (test). |
16+
| `server.port` | `8080` | HTTP port (test). |
17+
18+
### Environment Variables
19+
20+
| Variable | Default | Description |
21+
| --- | --- | --- |
22+
| `SPRING_DATASOURCE_URL` | `jdbc:postgresql://db:5432/cashu-gateway` | Overrides database URL in Docker. |
23+
| `SPRING_DATASOURCE_USERNAME` | `postgres` | Overrides database user in Docker. |
24+
| `SPRING_DATASOURCE_PASSWORD` | `password` | Overrides database password in Docker. |
25+
| `POSTGRES_DB` | `cashu-gateway` | Database name for the PostgreSQL container. |
26+
| `POSTGRES_USER` | `postgres` | Username for the PostgreSQL container. |
27+
| `POSTGRES_PASSWORD` | `password` | Password for the PostgreSQL container. |
28+
29+
## Dummy Gateway module ([cashu-gateway-dummy](../../cashu-gateway-dummy))
30+
31+
| Property | Default | Description |
32+
| --- | --- | --- |
33+
| `dummy.payment_status` | `80` | Simulated payment status. |
34+
| `dummy.amount` | `10` | Simulated invoice amount. |
35+
| `dummy.expiry` | `86400` | Invoice expiry in seconds. |
36+
| `dummy.fee_reserve` | `30` | Fee reserve amount. |
37+
| `webhook.base_url` | `http://localhost:9090/webhook` | Base URL for webhook callbacks. |
38+
39+
## Phoenixd Gateway module ([cashu-gateway-phoenixd](../../cashu-gateway-phoenixd))
40+
41+
| Property | Default | Description |
42+
| --- | --- | --- |
43+
| `phoenixd.currency` | `sat` | Currency unit for invoices. |
44+
| `phoenixd.expiration` | `86400` | Quote expiration in seconds. |
45+
| `phoenixd.fee.percent` | `0.004` | Percentage fee applied. |
46+
| `phoenixd.fee.fixed` | `4` | Fixed fee amount. |
47+
| `phoenixd.expiry` | `60` | Invoice expiry in seconds. |
48+
| `phoenixd.lnaddress` | `on` | Enable LN address support. |
49+
| `phoenixd.payee` | `398ja@strike.me` | LN address for payouts (test). |
50+
| `phoenixd.username` | *(empty)* | Basic auth username. |
51+
| `phoenixd.password` | `49c6311a099407885c1b161f57c5c0ea4cb7cb2636a99488b870ffd8090a453a` | Basic auth password. |
52+
| `phoenixd.base_url` | `http://localhost:9740` | Base URL of phoenixd node. |
53+
| `phoenixd.timeout` | `5000` | HTTP timeout in milliseconds. |
54+
| `phoenixd.webhook_secret` | *(empty)* | Secret for verifying webhooks. |
55+
| `A1b2C3d4.wid` | `phoenixd` | Webhook identifier. |
56+
| `webhook.base_url` | `http://localhost:9090/webhook` | Base URL for webhook callbacks. |
57+
58+
## Webhook module ([cashu-gateway-webhook](../../cashu-gateway-webhook))
59+
60+
| Property | Default | Description |
61+
| --- | --- | --- |
62+
| `A1b2C3d4.wid` | `phoenixd` | Webhook identifier expected by validator. |

‎docs/requirements.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Requirements
2+
3+
Cashu Gateway requires:
4+
5+
- Java 21 or newer
6+
- Maven 3.8+
7+
- Docker (optional, for provided containers)
8+
9+
Proceed to the [building guide](building.md) once these prerequisites are installed.

0 commit comments

Comments
 (0)