Initial commit
This commit is contained in:
michilis
479
README.md
Normal file
479
README.md
Normal file
@@ -0,0 +1,479 @@
|
||||
# Cashu Redeem API 🪙⚡
|
||||
|
||||
A production-grade API for redeeming Cashu tokens (ecash) to Lightning addresses using the cashu-ts library and LNURLp protocol.
|
||||
|
||||
## 🚀 Features
|
||||
|
||||
- **Decode Cashu tokens** - Parse and validate token content
|
||||
- **Redeem to Lightning addresses** - Convert ecash to Lightning payments via LNURLp
|
||||
- **Real-time status tracking** - Monitor redemption progress with unique IDs
|
||||
- **Security features** - Domain restrictions, rate limiting, input validation
|
||||
- **Robust error handling** - Comprehensive error messages and status codes
|
||||
- **In-memory caching** - Fast mint and wallet instances with connection pooling
|
||||
- **Interactive API Documentation** - Complete Swagger/OpenAPI documentation at `/docs`
|
||||
|
||||
## 📖 API Documentation
|
||||
|
||||
**Interactive Swagger Documentation**: Visit `/docs` when running the server for a complete, interactive API reference.
|
||||
|
||||
Example: `http://localhost:3000/docs`
|
||||
|
||||
The documentation includes:
|
||||
- Complete endpoint specifications
|
||||
- Request/response schemas
|
||||
- Try-it-out functionality
|
||||
- Example requests and responses
|
||||
- Authentication requirements
|
||||
- Error code documentation
|
||||
|
||||
## 📡 API Endpoints
|
||||
|
||||
### 1. `POST /api/decode`
|
||||
Decode a Cashu token and return its content. Supports both v1 and v3 token formats.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "cashuAeyJhbGciOi..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"decoded": {
|
||||
"mint": "https://mint.azzamo.net",
|
||||
"totalAmount": 21000,
|
||||
"numProofs": 3,
|
||||
"denominations": [1000, 10000, 10000],
|
||||
"format": "cashuA"
|
||||
},
|
||||
"mint_url": "https://mint.azzamo.net"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. `POST /api/redeem`
|
||||
Redeem a Cashu token to a Lightning address. Lightning address is optional - if not provided, uses the default address from configuration.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "cashuAeyJhbGciOi...",
|
||||
"lightningAddress": "user@ln.tips"
|
||||
}
|
||||
```
|
||||
|
||||
**Request (using default address):**
|
||||
```json
|
||||
{
|
||||
"token": "cashuAeyJhbGciOi..."
|
||||
}
|
||||
```
|
||||
|
||||
**Success Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"redeemId": "8e99101e-d034-4d2e-9ccf-dfda24d26762",
|
||||
"paid": true,
|
||||
"amount": 21000,
|
||||
"to": "user@ln.tips",
|
||||
"fee": 1000,
|
||||
"actualFee": 420,
|
||||
"netAmount": 20000,
|
||||
"mint_url": "https://mint.azzamo.net",
|
||||
"format": "cashuA",
|
||||
"preimage": "abc123..."
|
||||
}
|
||||
```
|
||||
|
||||
**Success Response (using default address):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"redeemId": "8e99101e-d034-4d2e-9ccf-dfda24d26762",
|
||||
"paid": true,
|
||||
"amount": 21000,
|
||||
"to": "admin@your-domain.com",
|
||||
"fee": 1000,
|
||||
"actualFee": 420,
|
||||
"netAmount": 20000,
|
||||
"mint_url": "https://mint.azzamo.net",
|
||||
"format": "cashuA",
|
||||
"usingDefaultAddress": true,
|
||||
"message": "Redeemed to default Lightning address: admin@your-domain.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. `POST /api/status`
|
||||
Check redemption status using redeemId.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"redeemId": "8e99101e-d034-4d2e-9ccf-dfda24d26762"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"status": "paid",
|
||||
"details": {
|
||||
"amount": 21000,
|
||||
"to": "user@ln.tips",
|
||||
"paid": true,
|
||||
"paidAt": "2025-01-14T12:00:00Z",
|
||||
"fee": 1000,
|
||||
"createdAt": "2025-01-14T11:59:30Z",
|
||||
"updatedAt": "2025-01-14T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. `GET /api/status/:redeemId`
|
||||
Same as above, but via URL parameter for frontend polling.
|
||||
|
||||
### 5. `GET /api/health`
|
||||
Health check endpoint.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"timestamp": "2025-01-14T12:00:00Z",
|
||||
"uptime": 3600,
|
||||
"memory": {...},
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. `POST /api/validate-address`
|
||||
Validate a Lightning address without redemption.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"lightningAddress": "user@ln.tips"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"valid": true,
|
||||
"domain": "ln.tips",
|
||||
"minSendable": 1,
|
||||
"maxSendable": 100000000,
|
||||
"commentAllowed": 144
|
||||
}
|
||||
```
|
||||
|
||||
### 7. `GET /api/stats`
|
||||
Get redemption statistics (admin endpoint).
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"stats": {
|
||||
"total": 150,
|
||||
"paid": 142,
|
||||
"failed": 8,
|
||||
"processing": 0,
|
||||
"totalAmount": 2500000,
|
||||
"totalFees": 15000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 8. `POST /api/check-spendable`
|
||||
Check if a Cashu token is spendable at its mint before attempting redemption.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "cashuAeyJhbGciOi..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"spendable": [true, true, false],
|
||||
"pending": [],
|
||||
"mintUrl": "https://mint.azzamo.net",
|
||||
"totalAmount": 21000,
|
||||
"message": "Token is spendable"
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠 Setup & Installation
|
||||
|
||||
### Prerequisites
|
||||
- Node.js >= 18.0.0
|
||||
- npm or yarn
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Clone and install dependencies:**
|
||||
```bash
|
||||
git clone <your-repo>
|
||||
cd cashu-redeem-api
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Setup environment variables:**
|
||||
```bash
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` file:
|
||||
```bash
|
||||
# Server Configuration
|
||||
PORT=3000
|
||||
NODE_ENV=development
|
||||
|
||||
# Security Configuration
|
||||
ALLOW_REDEEM_DOMAINS=ln.tips,getalby.com,wallet.mutinywallet.com
|
||||
API_SECRET=your-secret-key-here
|
||||
|
||||
# Default Lightning Address (used when no address is provided in redeem requests)
|
||||
DEFAULT_LIGHTNING_ADDRESS=admin@your-domain.com
|
||||
|
||||
# Rate Limiting (requests per minute)
|
||||
RATE_LIMIT=100
|
||||
|
||||
# CORS Configuration
|
||||
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
|
||||
```
|
||||
|
||||
3. **Start the server:**
|
||||
```bash
|
||||
# Development
|
||||
npm run dev
|
||||
|
||||
# Production
|
||||
npm start
|
||||
```
|
||||
|
||||
The API will be available at `http://localhost:3000`
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default | Required |
|
||||
|----------|-------------|---------|----------|
|
||||
| `PORT` | Server port | `3000` | No |
|
||||
| `NODE_ENV` | Environment | `development` | No |
|
||||
| `ALLOW_REDEEM_DOMAINS` | Comma-separated allowed domains | All allowed | No |
|
||||
| `DEFAULT_LIGHTNING_ADDRESS` | Default Lightning address for redemptions | None | No |
|
||||
| `RATE_LIMIT` | Requests per minute per IP | `100` | No |
|
||||
| `ALLOWED_ORIGINS` | CORS allowed origins | `http://localhost:3000` | No |
|
||||
|
||||
### Domain Restrictions
|
||||
|
||||
To restrict redemptions to specific Lightning address domains, set:
|
||||
```bash
|
||||
ALLOW_REDEEM_DOMAINS=ln.tips,getalby.com,wallet.mutinywallet.com
|
||||
```
|
||||
|
||||
If not set, all domains are allowed.
|
||||
|
||||
### Default Lightning Address
|
||||
|
||||
To set a default Lightning address that will be used when no address is provided in redemption requests:
|
||||
```bash
|
||||
DEFAULT_LIGHTNING_ADDRESS=admin@your-domain.com
|
||||
```
|
||||
|
||||
This allows users to redeem tokens without specifying a Lightning address - the tokens will automatically be sent to your configured default address. If no default is set, Lightning address becomes required for all redemption requests.
|
||||
|
||||
## 🏗 Architecture
|
||||
|
||||
### Services
|
||||
|
||||
#### `services/cashu.js`
|
||||
- Manages Cashu token parsing and validation
|
||||
- Handles mint connections and wallet instances
|
||||
- Performs token melting operations
|
||||
- Caches mint/wallet connections for performance
|
||||
|
||||
#### `services/lightning.js`
|
||||
- Validates Lightning address formats
|
||||
- Resolves LNURLp endpoints
|
||||
- Generates Lightning invoices
|
||||
- Handles domain restrictions
|
||||
|
||||
#### `services/redemption.js`
|
||||
- Coordinates the complete redemption process
|
||||
- Manages redemption status tracking
|
||||
- Handles duplicate token detection
|
||||
- Provides statistics and cleanup
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. **Token Validation** - Parse and validate Cashu token structure
|
||||
2. **Address Resolution** - Resolve Lightning address to LNURLp endpoint
|
||||
3. **Invoice Generation** - Create Lightning invoice for the amount
|
||||
4. **Token Melting** - Use cashu-ts to melt token and pay invoice
|
||||
5. **Status Tracking** - Store and update redemption status with UUID
|
||||
|
||||
## 🔒 Security Features
|
||||
|
||||
- **Input validation** - All inputs are sanitized and validated
|
||||
- **Rate limiting** - 100 requests per minute per IP (configurable)
|
||||
- **Domain restrictions** - Limit allowed Lightning address domains
|
||||
- **CORS protection** - Configurable allowed origins
|
||||
- **Error handling** - Comprehensive error messages without data leaks
|
||||
- **Token deduplication** - Prevent double-spending with hash tracking
|
||||
|
||||
## 🚦 Status Codes
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `processing` | Redemption is in progress |
|
||||
| `parsing_token` | Validating and parsing the token |
|
||||
| `resolving_invoice` | Resolving Lightning address to invoice |
|
||||
| `melting_token` | Performing the melt operation |
|
||||
| `paid` | Successfully paid and completed |
|
||||
| `failed` | Redemption failed (see error details) |
|
||||
| `checking_spendability` | Verifying token is spendable at mint |
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
### Statistics
|
||||
```bash
|
||||
curl http://localhost:3000/api/stats
|
||||
```
|
||||
|
||||
### Logs
|
||||
The server logs all requests and errors to console. In production, consider using a proper logging solution like Winston.
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Interactive Testing with Swagger
|
||||
|
||||
The easiest way to test the API is using the interactive Swagger documentation at `/docs`:
|
||||
- Visit `http://localhost:3000/docs`
|
||||
- Click "Try it out" on any endpoint
|
||||
- Fill in the request parameters
|
||||
- Execute the request directly from the browser
|
||||
|
||||
### Example cURL commands
|
||||
|
||||
**Decode a token:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/decode \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token":"your-cashu-token-here"}'
|
||||
```
|
||||
|
||||
**Check if token is spendable:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/check-spendable \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token":"your-cashu-token-here"}'
|
||||
```
|
||||
|
||||
**Redeem a token to specific address:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/redeem \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"token": "your-cashu-token-here",
|
||||
"lightningAddress": "user@ln.tips"
|
||||
}'
|
||||
```
|
||||
|
||||
**Redeem a token to default address:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/redeem \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"token": "your-cashu-token-here"
|
||||
}'
|
||||
```
|
||||
|
||||
**Check status:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/status \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"redeemId":"your-redeem-id-here"}'
|
||||
```
|
||||
|
||||
## 🚀 Production Deployment
|
||||
|
||||
### Recommendations
|
||||
|
||||
1. **Use a process manager** (PM2, systemd)
|
||||
2. **Set up reverse proxy** (nginx, Apache)
|
||||
3. **Enable HTTPS** with SSL certificates
|
||||
4. **Use Redis** for persistent storage instead of in-memory
|
||||
5. **Set up monitoring** (Prometheus, Grafana)
|
||||
6. **Configure logging** (Winston, structured logs)
|
||||
7. **Set resource limits** and health checks
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
Create a `Dockerfile`:
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
### Environment-specific configs
|
||||
|
||||
**Production `.env`:**
|
||||
```bash
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
ALLOW_REDEEM_DOMAINS=ln.tips,getalby.com
|
||||
DEFAULT_LIGHTNING_ADDRESS=admin@your-domain.com
|
||||
RATE_LIMIT=200
|
||||
ALLOWED_ORIGINS=https://yourdomain.com
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests if applicable
|
||||
5. Submit a pull request
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT License - see LICENSE file for details.
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
For issues and questions:
|
||||
- Create an issue on GitHub
|
||||
- Check the logs for detailed error messages
|
||||
- Verify your environment configuration
|
||||
- Test with the health endpoint first
|
||||
|
||||
## 🔮 Roadmap
|
||||
|
||||
- [ ] Add Redis/database persistence
|
||||
- [ ] Implement webhook notifications
|
||||
- [ ] Add batch redemption support
|
||||
- [ ] Enhanced monitoring and metrics
|
||||
- [ ] WebSocket real-time status updates
|
||||
- [ ] Multi-mint support optimization
|
||||
Reference in New Issue
Block a user