FlowFi
DeFi Payment Streaming on Stellar
Programmable, real-time payment streams and recurring subscriptions.
Overview
FlowFi allows users to create continuous payment streams and recurring subscriptions using stablecoins on the Stellar network. By leveraging Soroban smart contracts, FlowFi enables autonomous accurate-to-the-second distribution of funds.
Features
- Real-time Streaming: Pay by the second for services or salaries.
- Recurring Subscriptions: Automate monthly or weekly payments.
- Soroban Powered: Secure and efficient execution on Stellar's smart contract platform.
Project Structure
flowfi/
├── backend/ # Express.js + TypeScript backend
├── contracts/ # Soroban smart contracts
│ ├── stream_contract/ # Core streaming logic
├── frontend/ # Next.js + Tailwind CSS frontend
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # Architecture overview
│ ├── DEVELOPMENT.md # Local development guide
│ └── TROUBLESHOOTING.md # FAQ: wallet, Friendbot, Soroban RPC
For full step-by-step instructions, see our Development Guide.
Prerequisites
- Node.js & npm
- Rust & Cargo
- Stellar CLI (optional but recommended)
- Docker & Docker Compose (for containerized setup)
Architecture
FlowFi consists of three main components that work together:
- Soroban Smart Contracts: Handle on-chain payment stream logic.
- Backend API: Indexes on-chain events, provides REST API, and streams real-time updates via SSE
- Frontend: User interface for creating and managing payment streams
For a detailed explanation of how these components interact, where event indexing happens, and the overall system architecture, see the Architecture Documentation.
For full local setup and contributor onboarding, see the Development Guide.
Getting Started
New here? Stuck on wallet setup? See the Troubleshooting & FAQ guide for switching Freighter between Testnet/Futurenet, funding test accounts with Stellar Friendbot, and resolving Soroban RPC rate-limit or simulation-timeout errors.
Docker (Recommended)
The fastest way to run the full stack locally:
docker compose up --build
This starts six services:
| Service |
Host port |
Purpose |
postgres |
5433 |
PostgreSQL 16 database |
pgbouncer |
6432 |
Transaction-pooling proxy in front of Postgres; the backend connects through it |
redis |
6379 |
SSE pub/sub fan-out and shared rate-limit state |
mock-soroban-rpc |
8000 |
Local JSON-RPC stub returning well-formed Soroban responses, so the indexer and simulation endpoints work without a live testnet |
backend |
3001 |
Backend API (runs with SANDBOX_MODE_ENABLED=true against the mock RPC) |
frontend |
3000 |
Next.js frontend, built and run in production mode |
Make sure these host ports are free before starting, or remap them in docker-compose.yml.
Minimal invocation — if you only need the API (for example, you run the frontend with npm run dev), start just the backend. Compose also starts the services it depends on (postgres, pgbouncer, redis, mock-soroban-rpc), but skips the frontend:
docker compose up --build backend
For a database only (e.g. running the backend directly on your machine):
docker compose up -d postgres
To run in detached mode:
docker compose up -d --build
To stop the services:
docker compose down
To reset the database:
docker compose down -v
Frontend
cd frontend
npm install
npm run dev
Backend (Manual)
cd backend
npm install
npm run dev
Deployment
Contract Deployment
The FlowFi smart contracts can be deployed to both testnet and mainnet using the automated deployment script.
Prerequisites
- Stellar CLI installed and configured
- Sufficient XLM in the deployment account for network fees
- Required environment variables set
Environment Variables
Before deploying, set the following environment variables:
export DEPLOYER_SECRET="your_secret_key_here"
export ADMIN_ADDRESS="your_admin_address_here"
export TREASURY_ADDRESS="your_treasury_address_here"
export FEE_RATE_BPS="25" # 0.25% fee rate
Deploy to Testnet
chmod +x scripts/deploy.sh
./scripts/deploy.sh --network testnet
Deploy to Mainnet
chmod +x scripts/deploy.sh
./scripts/deploy.sh --network mainnet
Deployment Process
The deployment script automates the following steps:
- Build WASM: Compiles the Rust contract to WebAssembly
- Optimize WASM: Optimizes the WASM for deployment size
- Deploy Contract: Deploys the contract to the specified network
- Initialize Contract: Sets up admin, treasury, and fee rate parameters
- Save Deployment Info: Stores contract details in
deployment-info.json
Deployment Information
After successful deployment, contract details are saved to deployment-info.json:
{
"testnet": {
"network": "testnet",
"contractId": "CD...ID",
"deployedAt": "2024-01-01T00:00:00.000Z",
"adminAddress": "G...ADMIN",
"treasuryAddress": "G...TREASURY",
"feeRateBps": 25,
"transactionHash": "TX...HASH"
},
"mainnet": {
"network": "mainnet",
"contractId": "CD...ID",
"deployedAt": "2024-01-01T00:00:00.000Z",
"adminAddress": "G...ADMIN",
"treasuryAddress": "G...TREASURY",
"feeRateBps": 25,
"transactionHash": "TX...HASH"
},
"lastUpdated": "2024-01-01T00:00:00.000Z"
}
Manual Deployment
If you prefer to deploy manually, you can use the Stellar CLI directly:
# Build and optimize
cd contracts
cargo build --target wasm32-unknown-unknown --release
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/stream_contract.wasm
# Deploy
stellar contract deploy --wasm target/wasm32-unknown-unknown/release/stream_contract.optimized.wasm --source YOUR_SECRET_KEY --network https://soroban-testnet.stellar.org
# Initialize
stellar contract invoke --id CONTRACT_ID --source YOUR_SECRET_KEY --network https://soroban-testnet.stellar.org initialize --admin ADMIN_ADDRESS --treasury TREASURY_ADDRESS --fee_rate_bps 25
API Documentation
The FlowFi backend API uses URL-based versioning. All endpoints are prefixed with a version (e.g., /v1/streams).
Sandbox Mode
FlowFi supports sandbox mode for safe testing. Enable it by:
- Setting
SANDBOX_MODE_ENABLED=true in your .env file
- Adding
X-Sandbox-Mode: true header or ?sandbox=true query parameter to requests
Sandbox mode uses a separate database and clearly labels all responses. See Sandbox Mode Documentation for details.
API Collections
Pre-built collections for exploring all endpoints without any manual setup.
Environment files (import alongside the collection):
Quick start
Postman
- Import → select
flowfi.postman_collection.json.
- Import → select the matching
*.postman_environment.json.
- Pick the environment from the top-right dropdown and send requests.
Hoppscotch
- Collections → Import / Export → Import from JSON → select
flowfi.hoppscotch_collection.json.
- Environments → Import → select the matching
*.hoppscotch_environment.json.
- Activate the environment and send requests.
SSE note
GET /events/subscribe streams text/event-stream data and keeps the connection open. Postman buffers the response — use Send and Download to capture it, or test interactively with:
curl -N --no-buffer 'http://localhost:3001/events/subscribe?all=true'
Or open backend/test-sse-client.html directly in a browser.
Contributing
Contributions are welcome! Please see our Contributing Guide for:
- Local development setup instructions
- Code style and commit guidelines
- Pull request process
- Development scripts and CI workflows
Before your first change, run through the Development Guide and review Architecture Documentation.
For architecture details, see docs/ARCHITECTURE.md.
Architecture Decisions & Threat Model (auditor entry points)
- Architecture Decision Records: docs/adr/ — TTL strategy, keeper-key deprecation, indexer cursor/dead-letter, SSE/WebSocket coexistence.
- STRIDE Threat Model: docs/security/STRIDE_THREAT_MODEL.md — trust boundaries, threat matrix, mitigations, residual risks.
- Batch Withdrawal Flow: docs/architecture/BATCH_WITHDRAWAL.md — end-to-end sequence diagram for batch claims across frontend, SDK, contract, indexer, and SSE.
- TypeScript SDK (client-side signing): packages/flowfi-sdk/ — standalone
FlowFiClient for direct ledger access without the backend API.
- Preview environments: every PR gets an ephemeral full-stack preview (migrated + seeded DB) via
.github/workflows/pr-preview.yml; resources are torn down by pr-preview-cleanup.yml on close.
- Troubleshooting & FAQ: docs/TROUBLESHOOTING.md — Freighter network switching, Friendbot funding, and Soroban RPC errors.
Security
If you discover a security vulnerability, please see our Security Policy for information on how to report it responsibly.
Community & Support
Review the discussions guide before opening an issue or looking for community support.
Contributors
This project follows the all-contributors specification. Contributions of any kind welcome!
License
MIT.
ci fix