Merge branch 'main' into feature/1255-rollbackup-fix

Author: meem08

.github/workflows/ci.yml

@@ -89,6 +89,17 @@ jobs:
         working-directory: backend
 
 
+      - name: OpenAPI spec & API types drift check
+        run: |
+          cd backend
+          npm run codegen:openapi
+          cd ../frontend
+          npm run codegen:api-types
+          cd ..
+          git diff --exit-code -- backend/swagger/flowfi.openapi.json frontend/src/lib/api-types.generated.ts
+
+      - name: Install Rollup Native Binding
+        run: npm install @rollup/rollup-linux-x64-gnu --no-save
 
       - name: Run Backend Tests
         run: |
@@ -189,8 +200,16 @@ jobs:
         run: cargo test
         working-directory: contracts
 
+      - name: Cache cargo-tarpaulin
+        id: tarpaulin-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cargo/bin/cargo-tarpaulin
+          key: cargo-tarpaulin-${{ runner.os }}-0.37.2
+
       - name: Install cargo-tarpaulin
-        run: cargo install cargo-tarpaulin --locked
+        if: steps.tarpaulin-cache.outputs.cache-hit != 'true'
+        run: cargo install cargo-tarpaulin@0.37.2 --locked
 
       - name: Run Contract Coverage
         run: cargo tarpaulin --workspace --out Xml --output-dir coverage --fail-under 70

.github/workflows/deploy-contracts.yml

@@ -0,0 +1,146 @@
+# Contract Deployment Workflow for FlowFi
+#
+# Compiles the Soroban stream contract to optimized WASM, runs contract tests,
+# and deploys + initializes the contract on Stellar Testnet on demand (or on
+# Mainnet for release tags). The resulting contract ID is surfaced in the job
+# summary and published as a release artifact.
+name: Deploy Soroban Contracts
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      network:
+        description: "Target network (testnet|mainnet)"
+        required: true
+        default: "testnet"
+        type: choice
+        options:
+          - testnet
+          - mainnet
+
+concurrency:
+  group: ${{ github.workflow }}-${{ inputs.network || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build & Deploy stream_contract
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'release' && 'production' || 'staging' }}
+
+    env:
+      NETWORK: ${{ inputs.network || (github.event_name == 'release' && 'mainnet' || 'testnet') }}
+      DEPLOYER_SECRET: ${{ secrets.DEPLOYER_SECRET }}
+      ADMIN_ADDRESS: ${{ secrets.ADMIN_ADDRESS }}
+      TREASURY_ADDRESS: ${{ secrets.TREASURY_ADDRESS }}
+      FEE_RATE_BPS: ${{ secrets.FEE_RATE_BPS }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: stable
+          targets: wasm32-unknown-unknown
+          components: rustfmt, clippy
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspace: "contracts -> target"
+
+      - name: Install Stellar CLI
+        run: |
+          curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh -s -- --install-deps
+          echo "$HOME/.stellar-cli/bin" >> $GITHUB_PATH
+
+      - name: Run Contract Tests
+        run: cargo test --package stream_contract
+        working-directory: contracts
+
+      - name: Build & Optimize WASM
+        run: |
+          set -euo pipefail
+          cd contracts
+          cargo build --target wasm32-unknown-unknown --release
+          RELEASE_DIR="target/wasm32-unknown-unknown/release"
+          for w in "$RELEASE_DIR"/stream_contract.wasm; do
+            stellar contract optimize --wasm "$w" --wasm-out "$RELEASE_DIR/stream_contract.optimized.wasm"
+          done
+          ls -la "$RELEASE_DIR"/*.wasm
+
+      - name: Inspect Contract Interface & WASM Size
+        run: |
+          set -euo pipefail
+          WASM=contracts/target/wasm32-unknown-unknown/release/stream_contract.optimized.wasm
+          stellar contract inspect --wasm "$WASM"
+          SIZE=$(stat -c%s "$WASM")
+          echo "Optimized WASM size: $SIZE bytes"
+          if [ "$SIZE" -ge 65536 ]; then
+            echo "ERROR: optimized WASM exceeds 64KB budget ($SIZE bytes)"
+            exit 1
+          fi
+          echo "WASM_WASM_PATH=$WASM" >> $GITHUB_ENV
+
+      - name: Deploy & Initialize Contract
+        run: ./scripts/deploy.sh --network "$NETWORK"
+
+      - name: Read Deployed Contract ID
+        id: contract
+        run: |
+          set -euo pipefail
+          CONTRACT_ID=$(jq -r --arg net "$NETWORK" '.[$net].contractId' deployment-info.json)
+          echo "contract_id=$CONTRACT_ID" >> $GITHUB_OUTPUT
+          echo "deployment-json=$(jq -c . deployment-info.json)" >> $GITHUB_OUTPUT
+
+      - name: Emit Deployment Summary
+        if: always()
+        run: |
+          {
+            echo "## Deployment Summary"
+            echo ""
+            echo "- **Network**: \`$NETWORK\`"
+            echo "- **Contract ID**: \`${{ steps.contract.outputs.contract_id }}\`"
+            echo "- **WASM**: \`${{ env.WASM_WASM_PATH }}\`"
+            echo "- **Deployment info**: "
+            echo '```json'
+            echo "${{ steps.contract.outputs.deployment-json }}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload Optimized WASM Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: stream-contract-${{ env.NETWORK }}
+          path: contracts/target/wasm32-unknown-unknown/optimized/*.wasm
+          if-no-files-found: error
+
+      - name: Upload Deployment Info
+        uses: actions/upload-artifact@v4
+        with:
+          name: deployment-info-${{ env.NETWORK }}
+          path: deployment-info.json
+          if-no-files-found: error
+
+      - name: Commit Deployment Info
+        if: github.event_name == 'release'
+        env:
+          NETWORK: ${{ env.NETWORK }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add deployment-info.json
+          if git diff --cached --quiet; then
+            echo "No deployment-info.json changes to commit"
+            exit 0
+          fi
+          git commit -m "chore(contracts): record $NETWORK contract deployment"
+          git push

.github/workflows/security.yml

@@ -8,7 +8,7 @@ on:
   push:
     branches: [ main, develop ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, develop ]
   schedule:
     - cron: '0 2 * * 0'
 
@@ -41,6 +41,24 @@ jobs:
     - name: Check for known vulnerabilities in backend (production dependencies)
       run: npm audit --workspace=backend --omit=dev --audit-level=critical
 
+    - name: Setup Rust toolchain for contract audit
+      uses: dtolnay/rust-toolchain@stable
+
+    - name: Cache cargo-audit
+      id: cargo-audit-cache
+      uses: actions/cache@v4
+      with:
+        path: ~/.cargo/bin/cargo-audit
+        key: cargo-audit-${{ runner.os }}
+
+    - name: Install cargo-audit
+      if: steps.cargo-audit-cache.outputs.cache-hit != 'true'
+      run: cargo install cargo-audit --locked
+
+    - name: Check for known vulnerabilities in smart contracts (cargo audit)
+      run: cargo audit
+      working-directory: contracts
+
     - name: Verify security setup
       run: npm run verify-security
 
@@ -55,19 +73,40 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'javascript', 'typescript' ]
+        language: [ 'javascript', 'typescript', 'rust' ]
 
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
 
+    - name: Setup Rust toolchain
+      if: matrix.language == 'rust'
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        toolchain: stable
+        targets: wasm32-unknown-unknown
+        components: clippy
+
+    - name: Rust Cache
+      if: matrix.language == 'rust'
+      uses: Swatinem/rust-cache@v2
+      with:
+        workspace: "contracts -> target"
+
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
 
+    - name: Build Rust contracts for CodeQL
+      if: matrix.language == 'rust'
+      run: cargo check --workspace --all-targets
+      working-directory: contracts
+
     - name: Autobuild
+      if: matrix.language != 'rust'
       uses: github/codeql-action/autobuild@v3
 
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@v3
+

backend/.env.example

@@ -88,6 +88,11 @@ REDIS_URL=
 # Time in milliseconds between periodic sweeps to prune expired memory cache entries (default: 60000)
 MEMORY_CACHE_SWEEP_MS=60000
 
+# Maximum number of entries kept in the in-memory cache. When exceeded, the
+# least-recently-used entries are evicted immediately so memory stays bounded
+# even between sweeps (default: 10000)
+MEMORY_CACHE_MAX_ITEMS=10000
+
 # Cache time-to-live (TTL) for claimable amount calculations in milliseconds (default: 5000)
 CLAIMABLE_CACHE_TTL_MS=5000
 

backend/docs/SSE_ARCHITECTURE.md

@@ -3,27 +3,27 @@
 ## System Flow
 
 ```
-┌─────────────────┐
-│  Blockchain     │
-│  Indexer        │
-│  (Stellar)      │
-└────────┬────────┘
-         │ Events
-         ▼
+┌─────────────────────────────────────────────────────────┐
+│              Stellar Blockchain / Soroban                │
+│  - On-chain stream contract executions & ledger events   │
+└────────────────────────────┬────────────────────────────┘
+                             │ On-Chain Events (via Soroban RPC poll)
+                             ▼
 ┌─────────────────────────────────────────────────────────┐
 │                    Backend Server                        │
 │                                                          │
 │  ┌──────────────────────────────────────────────────┐  │
-│  │  Stream Controller                                │  │
-│  │  - Creates/updates streams                        │  │
-│  │  - Calls sseService.broadcast()                   │  │
+│  │  Soroban Event Worker (Indexer)                  │  │
+│  │  - Polls Soroban RPC for confirmed events        │  │
+│  │  - Persists stream state & events to Database    │  │
+│  │  - Calls sseService.broadcastToStream/Admin()     │  │
 │  └──────────────┬───────────────────────────────────┘  │
-│                 │                                        │
+│                 │ Dispatch events (indexer-driven)       │
 │                 ▼                                        │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │  SSE Service                                      │  │
 │  │  - Manages client connections                     │  │
-│  │  - Filters by subscription                        │  │
+│  │  - Filters by subscription (stream/user/admin)    │  │
 │  │  - Broadcasts to matching clients                 │  │
 │  └──────────────┬───────────────────────────────────┘  │
 │                 │                                        │
@@ -40,6 +40,8 @@
     └─────────────────────────────────────┘
 ```
 
+> **Note on Indexer-Driven Event Origin**: SSE broadcast events originate asynchronously from the background indexer worker (`SorobanEventWorker`) only after transaction confirmation on the Stellar ledger, not synchronously from HTTP API controllers (`stream.controller.ts`, etc.). When a user submits an action (create, pause, withdraw, top-up, cancel), API controllers do not broadcast SSE events directly; events are dispatched once the Soroban event is polled and confirmed on-chain. Additionally, background workers like `StreamRunwayWorker` may dispatch computed alerts (e.g. `STREAM_LOW_BALANCE`).
+
 ## Connection Flow
 
 ```
@@ -72,7 +74,7 @@ Client                          Server
   │  [Auto Reconnect - 1s]        │
   │                               │
   │  GET /events/subscribe        │
-  ├──────────────────────────────>│
+  │  ├──────────────────────────────>│
   │                               │
   │  200 OK                       │
   │<──────────────────────────────┤
@@ -122,30 +124,37 @@ Client                          Server
                     └─────────────────┘
 
 Flow:
-1. Backend 1 receives stream creation
+1. Backend 1 (SorobanEventWorker) indexes confirmed on-chain event
 2. Backend 1 publishes to Redis: "stream-events"
-3. All backends (1, 2, 3) receive message
+3. All backends (1, 2, 3) receive message via Redis subscriber
 4. Each backend broadcasts to its connected clients
 5. Total: 33 clients receive the event
 ```
 
 ## Event Broadcasting Logic
 
 ```typescript
-// Broadcast to specific stream
+// Broadcast to specific stream (called by SorobanEventWorker / StreamRunwayWorker)
 sseService.broadcastToStream("123", "stream.created", data)
   ↓
   Filter clients: subscription includes "123" or "*"
   ↓
   Send to matching clients
 
-// Broadcast to user
-sseService.broadcastToUser("GABC...", "stream.created", data)
+// Broadcast to user (called by StreamRunwayWorker)
+sseService.broadcastToUser("GABC...", "STREAM_LOW_BALANCE", data)
   ↓
   Filter clients: subscription includes "user:GABC..." or "*"
   ↓
   Send to matching clients
 
+// Broadcast to admin (called by SorobanEventWorker for admin/fee events)
+sseService.broadcastToAdmin("stream.fee_config_updated", data)
+  ↓
+  Filter clients: admin subscribers ("admin" or "*")
+  ↓
+  Send to matching clients
+
 // Broadcast to all
 sseService.broadcast("stream.created", data)
   ↓

backend/docs/SSE_IMPLEMENTATION.md

@@ -193,7 +193,7 @@ import Redis from 'ioredis';
 const redis = new Redis(process.env.REDIS_URL);
 const subscriber = new Redis(process.env.REDIS_URL);
 
-// Publisher (in stream controller)
+// Publisher (in Soroban event worker / indexer)
 redis.publish('stream-events', JSON.stringify({
   event: 'stream.created',
   data: mockStream,

backend/package.json

@@ -6,6 +6,7 @@
   "main": "index.js",
   "scripts": {
     "prebuild": "prisma generate",
+    "pretest": "prisma generate",
     "test": "vitest run",
     "test:unit": "vitest run --exclude='tests/integration/**'",
     "test:integration": "vitest run tests/integration",
@@ -17,7 +18,8 @@
     "prisma:migrate": "prisma migrate dev",
     "prisma:deploy": "prisma migrate deploy",
     "prisma:seed": "prisma db seed",
-    "prisma:studio": "prisma studio"
+    "prisma:studio": "prisma studio",
+    "codegen:openapi": "tsx scripts/export-openapi.mts"
   },
   "prisma": {
     "seed": "tsx prisma/seed.ts"