feat(scripts): add exponential backoff retry logic and DLQ for keeper (#76)

.github/workflows/frontend.yml

@@ -2,31 +2,30 @@ name: Frontend
 
 on:
   push:
-    branches: [ "master" ]
+    branches: ["master"]
   pull_request:
-    branches: [ "master" ]
+    branches: ["master"]
 
 defaults:
   run:
     working-directory: frontend
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 20
-        cache: npm
-        cache-dependency-path: frontend/package-lock.json
-    - name: Install dependencies
-      run: npm ci
-    - name: Lint
-      run: npm run lint
-    - name: Format check
-      run: npx prettier --check .
-    - name: Build
-      run: npm run build
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Format check
+        run: npx prettier --check .
+      - name: Build
+        run: npm run build

.github/workflows/rust.yml

@@ -2,9 +2,9 @@ name: Backend (Rust)
 
 on:
   push:
-    branches: [ "master" ]
+    branches: ["master"]
   pull_request:
-    branches: [ "master" ]
+    branches: ["master"]
 
 env:
   CARGO_TERM_COLOR: always
@@ -15,19 +15,18 @@ defaults:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Install Rust target
-      run: rustup target add wasm32-unknown-unknown
-    - name: Clippy
-      run: cargo clippy -- -D warnings
-      working-directory: contract
-    - name: Build
-      run: cargo build --verbose
-      working-directory: contract
-    - name: Run tests
-      run: cargo test --verbose
-      working-directory: contract
+      - uses: actions/checkout@v4
+      - name: Install Rust target
+        run: rustup target add wasm32-unknown-unknown
+      - name: Clippy
+        run: cargo clippy -- -D warnings
+        working-directory: contract
+      - name: Build
+        run: cargo build --verbose
+        working-directory: contract
+      - name: Run tests
+        run: cargo test --verbose
+        working-directory: contract

AGENTS.md

@@ -5,14 +5,15 @@ PayFlow (also referred to as FlowPay) is a decentralized subscription and recurr
 ## Project Overview
 
 - **Core Technology:** Stellar Soroban (Rust), React + TypeScript (Frontend)
-- **Architecture:** 
+- **Architecture:**
   - **Smart Contract (`/contract`):** Handles subscription logic, charging, cancellations, and pay-per-use microtransactions.
   - **Frontend (`/frontend`):** A React-based dashboard for users to manage subscriptions and for merchants to view revenue/subscribers.
   - **Documentation (`/docs`):** Comprehensive guides on API, architecture, deployment, and testing.
 
 ## Key Components & Technologies
 
 ### Smart Contract (Rust/Soroban)
+
 - **Primary Contract:** `FlowPay` in `contract/src/lib.rs`.
 - **Key Functions:**
   - `initialize(token)`: Sets the primary SAC token (e.g., XLM).
@@ -24,6 +25,7 @@ PayFlow (also referred to as FlowPay) is a decentralized subscription and recurr
 - **Features:** Grace periods, merchant whitelisting, protocol fees, referral tracking, and subscription metadata.
 
 ### Frontend (React/TypeScript)
+
 - **Framework:** Vite + React + TypeScript.
 - **Blockchain Interaction:** `frontend/src/stellar.ts` uses `@stellar/stellar-sdk` and Soroban RPC.
 - **Wallet Support:** Freighter Wallet via `useWallet` hook.
@@ -32,21 +34,25 @@ PayFlow (also referred to as FlowPay) is a decentralized subscription and recurr
 ## Building and Running
 
 ### Prerequisites
+
 - Rust 1.70+ with `wasm32-unknown-unknown` target.
 - Soroban CLI.
 - Node.js 18+.
 
 ### Root Commands (using `package.json` scripts)
+
 - **Typecheck Frontend:** `npm run typecheck`
 - **Build Frontend:** `npm run build:frontend`
 - **Test Contract:** `npm run backend:test`
 - **Check Contract:** `npm run backend:typecheck`
 
 ### Contract (`/contract`)
+
 - **Build:** `cargo build --release --target wasm32-unknown-unknown`
 - **Test:** `cargo test`
 
 ### Frontend (`/frontend`)
+
 - **Install Dependencies:** `npm install`
 - **Development Server:** `npm run dev`
 - **Build:** `npm run build`
@@ -56,18 +62,22 @@ PayFlow (also referred to as FlowPay) is a decentralized subscription and recurr
 ## Development Conventions
 
 ### Coding Style
+
 - **Contract:** Idiomatic Rust using `soroban-sdk`. Strict use of `no_std`.
 - **Frontend:** Functional React components with TypeScript. Prefer Vanilla CSS for styling (as seen in `index.css`).
 
 ### Testing Practices
+
 - **Contract:** Comprehensive unit tests in `contract/src/test.rs`. Use `soroban-sdk`'s `testutils`.
 - **Frontend:** Vitest for unit and component testing. Smoke tests for main application entry points.
 
 ### Contribution Guidelines
+
 - Refer to `CONTRIBUTING.md` for detailed instructions.
 - Husky is used for pre-commit/pre-push hooks (linting and type-checking).
 
 ## Important Files
+
 - `contract/src/lib.rs`: Entry point for smart contract logic.
 - `frontend/src/stellar.ts`: Central hub for all Soroban/Stellar interactions.
 - `docs/API.md`: Detailed contract function documentation.

CONTRIBUTING.md

@@ -43,15 +43,15 @@ Be respectful. We welcome contributors of all experience levels. Harassment, gat
 
 These are well-scoped tasks that don't require deep knowledge of the whole codebase:
 
-| Task | Area | Difficulty |
-| --- | --- | --- |
-| Add USDC / custom SAC token support | Contract | Medium |
-| Build a Node.js keeper service that calls `charge()` on a schedule | Backend | Medium |
-| Add subscription pause/resume functions | Contract | Medium |
-| Improve frontend error messages with human-readable contract panics | Frontend | Easy |
-| Add `test_pay_per_use` unit test | Contract | Easy |
-| Add `test_double_initialize` unit test | Contract | Easy |
-| Display transaction history using contract events | Frontend | Hard |
+| Task                                                                | Area     | Difficulty |
+| ------------------------------------------------------------------- | -------- | ---------- |
+| Add USDC / custom SAC token support                                 | Contract | Medium     |
+| Build a Node.js keeper service that calls `charge()` on a schedule  | Backend  | Medium     |
+| Add subscription pause/resume functions                             | Contract | Medium     |
+| Improve frontend error messages with human-readable contract panics | Frontend | Easy       |
+| Add `test_pay_per_use` unit test                                    | Contract | Easy       |
+| Add `test_double_initialize` unit test                              | Contract | Easy       |
+| Display transaction history using contract events                   | Frontend | Hard       |
 
 ---
 
@@ -99,6 +99,7 @@ npm run dev
 5. Push your branch and open a Pull Request against `main`
 
 Branch naming conventions:
+
 - `feat/` — new feature
 - `fix/` — bug fix
 - `docs/` — documentation only
@@ -131,7 +132,6 @@ See the full guide: [`docs/CONTRIBUTING-FRONTEND.md`](docs/CONTRIBUTING-FRONTEND
 - Run `npm run format` to auto-format all source files with Prettier
 - Run `npm run build` to confirm there are no TypeScript errors before submitting
 
-
 ---
 
 ## Commit Style
@@ -180,6 +180,7 @@ npm run generate:types
 ```
 
 This invokes `scripts/generate-types.sh`, which requires either:
+
 - `CONTRACT_ID` env var pointing to a deployed contract, or
 - A compiled WASM artifact at `contract/target/wasm32-unknown-unknown/release/payflow.wasm`
 

Issues.md

@@ -68,4 +68,4 @@ Acceptance criteria
 
 Countdown appears on the subscription card
 Overdue state is visually distinct
-PR includes screenshot
+PR includes screenshot

README.md

@@ -53,15 +53,16 @@ pub fn get_daily_limit(env: Env, user: Address) -> Option<i128> {
 get_daily_limit(env: Env, user: Address) -> Option<i128>
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `user` | `Address` | The subscriber address to query |
+| Parameter | Type      | Description                     |
+| --------- | --------- | ------------------------------- |
+| `user`    | `Address` | The subscriber address to query |
 
 **Returns:** `Some(limit)` in stroops if a limit is set, `None` otherwise.  
 **Auth:** None required.  
 **Storage:** Reads `DataKey::DailyLimit(user)` from temporary storage.
 
 **CLI example:**
+
 ```bash
 soroban contract invoke \
   --id <CONTRACT_ID> \
@@ -139,6 +140,7 @@ cargo test daily_limit
 ```
 
 Expected output:
+
 ```
 test test::test_daily_limit_allows_spend_within_limit ... ok
 test test::test_daily_limit_accumulates_across_calls ... ok
@@ -202,11 +204,11 @@ Stellar's Soroban platform uses state archiving — persistent storage entries h
 
 ## Prerequisites
 
-| Tool | Version | Install |
-|------|---------|---------|
-| Rust | 1.70+ | `curl https://sh.rustup.rs -sSf \| sh` |
-| wasm32 target | — | `rustup target add wasm32-unknown-unknown` |
-| Soroban CLI | 21.x | `cargo install --locked soroban-cli` |
+| Tool          | Version | Install                                    |
+| ------------- | ------- | ------------------------------------------ |
+| Rust          | 1.70+   | `curl https://sh.rustup.rs -sSf \| sh`     |
+| wasm32 target | —       | `rustup target add wasm32-unknown-unknown` |
+| Soroban CLI   | 21.x    | `cargo install --locked soroban-cli`       |
 
 ---
 

SECURITY.md

@@ -5,23 +5,28 @@
 If you discover a security vulnerability in PayFlow, please report it responsibly:
 
 ### Preferred Method
+
 Use **GitHub Security Advisories** to report vulnerabilities privately:
+
 1. Go to the "Security" tab in this repository
 2. Click "Report a vulnerability"
 3. Fill out the advisory form
 
 ### Alternative Method
+
 Email: **security@payflow.dev**
 
 Subject: `[PayFlow Security] Brief description`
 
 ### What to Include
+
 - Description of the vulnerability
 - Steps to reproduce
 - Potential impact assessment
 - Suggested mitigations (if any)
 
 ### Response Timeline
+
 - **Acknowledgment:** Within 48 hours
 - **Fix timeline:** Within 14 days for critical issues (depending on complexity)
 - **Credit:** We will credit researchers in release notes unless you prefer anonymity
@@ -37,13 +42,15 @@ For the full threat model, auth matrix, and storage notes, see [docs/SECURITY.md
 ## Scope
 
 In scope for vulnerability reports:
+
 - Smart contract logic vulnerabilities
 - Authorization bypass issues
 - Fund loss or theft scenarios
 - Denial of service attacks
 - Integer overflow/underflow issues
 
 Out of scope:
+
 - Issues in third-party dependencies (report to upstream)
 - Social engineering attacks
 - Physical security issues

TODO.md

@@ -1,6 +1,7 @@
 # TODO (PayFlow)
 
 ## Frontend DX: Hook JSDoc coverage
+
 - [ ] Scan all files in `frontend/src/hooks/` and verify which exported hooks are missing/partial JSDoc.
 - [ ] Add/upgrade `/** ... */` JSDoc blocks for every hook to include:
   - purpose
@@ -9,4 +10,3 @@
   - side effects
   - `@example` usage
 - [ ] Run TypeScript compile/typecheck for `frontend` to ensure no errors.
-

UIDesign.md

@@ -1 +1 @@
-https://www.figma.com/design/bhHlIX6xxmzhwcGga6ocmR/SiLioLabs-PayFlow?node-id=0-1&t=AcUOdKr2iI2eOxgC-1
+https://www.figma.com/design/bhHlIX6xxmzhwcGga6ocmR/SiLioLabs-PayFlow?node-id=0-1&t=AcUOdKr2iI2eOxgC-1