Backend SDK for ephemeral Stellar account management
The Bridgelet SDK is a NestJS-based backend service that manages the lifecycle of ephemeral Stellar accounts. It handles account creation, claim authentication, webhook notifications, and integration with the bridgelet-core smart contracts.
PLEASE READ THIS SECTION BEFORE DEVELOPMENT
The following services/imports are currently commented out to allow npm run start:dev to run without errors. These are NOT removed and MUST be restored once proper implementations exist.
- WebhooksService (referenced in
src/modules/claims/providers/claim-redemption.provider.ts)- Location:
src/modules/webhooks/(does not exist yet) - What was commented out:
- Constructor dependency injection (line ~25)
- Webhook trigger for
sweep.completedevent (line ~106) - Webhook trigger for
sweep.failedevent (line ~137)
- Why: Service implementation does not exist, causing TypeScript compilation errors
- Impact: Webhook notifications will NOT fire when claims are redeemed or when sweeps fail
- Restoration required: Once
WebhooksServiceis implemented insrc/modules/webhooks/, uncomment all marked sections
- Location:
Search the codebase for comments containing TEMPORARY: to locate all commented-out code that needs restoration.
This is a temporary stabilization to enable local development and onboarding until missing implementations are complete. No code was deleted - all logic remains in place as comments.
- Framework: NestJS (Node.js + TypeScript)
- Database: PostgreSQL
- ORM: TypeORM
- Blockchain: Stellar SDK + Soroban RPC
- API: REST api
- Account lifecycle management (create, claim, expire)
- Claim authentication via signed tokens
- Webhook system for payment events
- Integration with bridgelet-core contracts
- Admin dashboard API endpoints
src/
├── modules/
│ ├── accounts/ # Ephemeral account management
│ ├── claims/ # Claim authentication & processing
│ ├── sweeps/ # Fund sweep orchestration
│ ├── webhooks/ # Event notification system
│ └── stellar/ # Stellar/Soroban integration
├── common/
│ ├── guards/ # Auth guards
│ ├── interceptors/ # Logging, transform
│ └── filters/ # Exception filters
├── config/ # Environment configuration
└── database/ # Migrations, entities
# Install dependencies
npm install
# Setup environment
cp .env.example .env
# Edit .env with your configuration
# Run migrations
npm run migration:run
# Start development server
npm run start:devnpm test
## or to run specific tests
npm test -- test_Service_File_Name
##e.g
npm test -- sweeps.service.spec.tse.g
npm test -- sweeps.service.spec.ts --coverage# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=bridgelet
DATABASE_USER=postgres
DATABASE_PASSWORD=postgres
# Stellar
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# Security
JWT_SECRET=your-secret-key
CLAIM_TOKEN_EXPIRY=2592000 # 30 days
# Application
PORT=3000
NODE_ENV=developmentOnce running, access API docs at:
- Swagger:
http://localhost:3000/api/docs
POST /accounts # Create ephemeral account GET /accounts/:id # Get account details POST /claims/initiate # Generate claim token POST /claims/redeem # Redeem claim and sweep GET /webhooks # List webhook subscriptions POST /webhooks # Subscribe to events
See Database Schema Documentation
# Run tests
npm run test
# Run e2e tests
npm run test:e2e
# Lint
npm run lint
# Format
npm run formatSee Deployment Guide for production setup.
Visit http://localhost:3000/api/docs for API documentation.
See Getting Started Guide for full setup instructions.
(Nest)https://nestjs.com
UNLICENSED