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

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

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)

Docker (Recommended)

The fastest way to run the full stack locally:

docker compose up --build

This starts:

• Postgres database on port 5433
• Backend API on port 3001

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

Backend (Manual)

cd backend
npm install
npm run dev

Frontend

cd frontend
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 DEPLOYERSECRET="yoursecretkeyhere"
export ADMINADDRESS="youradminaddresshere"
export TREASURYADDRESS="yourtreasuryaddresshere"
export FEERATEBPS="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/streamcontract.optimized.wasm --source YOURSECRET_KEY --network https://soroban-testnet.stellar.org
Initialize
stellar contract invoke --id CONTRACTID --source YOURSECRETKEY --network https://soroban-testnet.stellar.org initialize --admin ADMINADDRESS --treasury TREASURYADDRESS --feerate_bps 25

API Documentation

The FlowFi backend API uses URL-based versioning. All endpoints are prefixed with a version (e.g., /v1/streams).

• Authentication: backend/docs/AUTHENTICATION.md
• API Versioning Guide: backend/docs/API_VERSIONING.md
• Deprecation Policy: backend/docs/DEPRECATION_POLICY.md
• Sandbox Mode: backend/docs/SANDBOX_MODE.md - Test without affecting production data
• Interactive API Docs: Available at http://localhost:3001/api-docs when backend is running
• Raw OpenAPI JSON: Available at http://localhost:3001/api-docs.json when backend is running

Sandbox Mode

FlowFi supports sandbox mode for safe testing. Enable it by:

• Setting SANDBOXMODEENABLED=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.

| File | Client | |---|---| | docs/api/flowfi.postman_collection.json | Postman | | docs/api/flowfi.hoppscotch_collection.json | Hoppscotch |

Environment files (import alongside the collection):

| File | Target | |---|---| | docs/api/local.postman_environment.json | Postman — local | | docs/api/test.postman_environment.json | Postman — test | | docs/api/local.hoppscotch_environment.json | Hoppscotch — local | | docs/api/test.hoppscotch_environment.json | Hoppscotch — test |

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.

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.

• 📖 Discussions Guide - Learn when to use Discussions vs Issues.

Contributors

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT.