From bad1d084d6c3ddc9efdfbb829a8c9f7664020eb6 Mon Sep 17 00:00:00 2001 From: bbkenny Date: Wed, 10 Jun 2026 22:49:05 +0100 Subject: [PATCH 1/2] docs: overhaul README with full EpochSend documentation --- README.md | 330 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 299 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 6b08c35..87b698c 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,335 @@ -# EpochSend - Frontend Client +# EpochSend โ€” Frontend Client -![EpochSend Banner](./frontend/public/epochsend-banner.png) +

+ EpochSend Banner +

-> **The Next.js user interface for the EpochSend Protocol on Stellar.** +

+ The programmable financial layer for Stellar โ€” turning intent into automated, trustless execution. +

-**Live Demo:** [https://epochsend.vercel.app/](https://epochsend.vercel.app/) +

+ + Live App + + Stellar Soroban + Next.js + MIT License + CI Status +

-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Built on Stellar](https://img.shields.io/badge/Built%20on-Stellar%20Soroban-purple)](https://soroban.stellar.org) +--- + +## ๐Ÿง  What Is EpochSend? + +EpochSend is an **intent-based payment protocol** on the Stellar Network. + +> *"Don't just send money. Define what money does."* + +Instead of transferring funds immediately, users define **conditions** โ€” the money only moves when those conditions are provably met. Built on Soroban smart contracts, EpochSend converts payment intent into enforceable, automated, on-chain execution with zero third-party custody. -## ๐Ÿ’ก Overview +**The core insight:** Every real-world payment has a condition attached to it โ€” a delivery, a milestone, a date, an approval. Today, humans enforce those conditions manually and trust each other to be honest. EpochSend moves that enforcement on-chain. -This repository contains the interactive Next.js application that allows users to seamlessly interact with the EpochSend conditional escrow smart contracts. +--- + +## ๐ŸŽฏ The Problem + +Modern payments are fundamentally broken for conditional transactions: -Users can connect their Freighter wallets, define their payment intents (e.g., "Send 100 USDC on Friday"), and cryptographically sign the transactions that safely lock their funds on the Stellar blockchain. +| Problem | Reality | +|---|---| +| **Trust-based** | Paying upfront means trusting the seller. Delivering first means trusting the buyer. | +| **Manual** | Recurring or milestone payments require calendar reminders and manual intervention. | +| **Irreversible** | Once money is sent, it's gone โ€” no programmable fallback if conditions aren't met. | +| **Expensive escrow** | Third-party escrow services charge massive fees for basic dispute resolution. | --- -## ๐Ÿ›  Tech Stack +## ๐Ÿ’ก The EpochSend Solution + +Users define a **Payment Intent**: +- **Recipient** โ€” destination Stellar/Soroban address +- **Asset** โ€” USDC, XLM, or any SAC token +- **Amount** โ€” how much to lock +- **Condition** โ€” Time-based unlock, Manual arbiter approval, or Off-chain Oracle webhook + +The protocol then: +1. **Locks** the funds safely in a Soroban escrow contract (non-custodial) +2. **Monitors** the defined condition passively or actively +3. **Executes** the payment automatically when the condition is met, **OR** +4. **Refunds** the sender automatically if a dispute timeout is reached -* **Framework:** Next.js (React) -* **Language:** TypeScript -* **Styling:** Tailwind CSS (EpochSend Design System: Deep Green & Identity Teal) -* **Wallet Integration:** Freighter Wallet -* **Blockchain Integration:** `@stellar/stellar-sdk` +No middlemen. No manual intervention. No trust required. + +--- + +## ๐Ÿ—๏ธ Architecture + +``` +User + โ”‚ + โ”œโ”€โ”€โ”€ Connect Freighter Wallet + โ”‚ + โ”œโ”€โ”€โ”€ Create Payment Intent + โ”‚ โ”‚ + โ”‚ โ–ผ + โ”‚ EpochSend Frontend (Next.js) + โ”‚ โ”‚ + โ”‚ โ”‚ invoke create_intent() + โ”‚ โ–ผ + โ”‚ Soroban Escrow Contract + โ”‚ โ”‚ + โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ” + โ”‚ โ”‚ Conditions โ”‚ + โ”‚ โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ + โ”‚ โ”‚ Time-Lock โ”‚ + โ”‚ โ”‚ Arbiter โ”‚ + โ”‚ โ”‚ Oracle โ”‚ + โ”‚ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ + โ”‚ โ”‚ + โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ” + โ”‚ โ”‚ โ”‚ + โ”‚ โ–ผ โ–ผ + โ”‚ Execute Refund + โ”‚ (โ†’ Recipient) (โ†’ Sender) +``` + +--- + +## ๐Ÿงฉ Core Features + +### Phase 1 โ€” MVP (Current) +| Feature | Status | +|---|---| +| Freighter Wallet Integration | โœ… Implemented | +| Time-Locked Escrow (Unix timestamp unlock) | ๐Ÿ”จ In Progress | +| Manual Arbiter Approval | ๐Ÿ”จ In Progress | +| Create Intent Form (UI) | โœ… Built | +| Active Intents Dashboard | ๐Ÿ”จ In Progress | +| Automated Refunds | ๐Ÿ”จ In Progress | +| Onboarding Modal | โœ… Implemented | + +### Phase 2 โ€” Automation & Oracles +| Feature | Status | +|---|---| +| Backend Oracle Node (Express + Stellar SDK) | ๐Ÿ”œ Planned | +| API Webhook triggers (FedEx, Zapier, etc.) | ๐Ÿ”œ Planned | +| Email / SMS notifications on escrow events | ๐Ÿ”œ Planned | +| Recurring subscription payment scheduling | ๐Ÿ”œ Planned | + +### Phase 3 โ€” Developer Ecosystem +| Feature | Status | +|---|---| +| EpochSend SDK for third-party dApp integration | ๐Ÿ”œ Planned | +| Multi-signature arbiter approvals | ๐Ÿ”œ Planned | +| Stellar fiat off-ramp integration (MoneyGram) | ๐Ÿ”œ Planned | +| Public developer documentation | ๐Ÿ”œ Planned | + +--- + +## ๐Ÿ› ๏ธ Tech Stack + +| Category | Technology | Version | +|---|---|---| +| **Framework** | Next.js (App Router) | 16.1.1 | +| **Language** | TypeScript | ^5.0 | +| **UI Library** | React | 19.2.3 | +| **Styling** | Tailwind CSS | v4 | +| **Animations** | Framer Motion | ^12 | +| **Icons** | Lucide React | ^0.300 | +| **Wallet** | Freighter API (`@stellar/freighter-api`) | ^2.0 | +| **Blockchain** | Stellar SDK (`@stellar/stellar-sdk`) | ^12.0 | +| **Network** | Stellar Testnet / Soroban RPC | โ€” | +| **Deployment** | Vercel | โ€” | + +--- + +## ๐Ÿ“ Project Structure + +``` +EpochSend-frontend/ +โ”œโ”€โ”€ docs/ +โ”‚ โ”œโ”€โ”€ PRD.md # Full Product Requirements Document +โ”‚ โ”œโ”€โ”€ ISSUES.md # Frontend feature roadmap & issue tracker +โ”‚ โ””โ”€โ”€ FRONTEND_GUIDE.md # Stellar/Soroban integration technical guide +โ”‚ +โ”œโ”€โ”€ frontend/ # Next.js app root +โ”‚ โ”œโ”€โ”€ app/ +โ”‚ โ”‚ โ”œโ”€โ”€ layout.tsx # Root layout โ€” metadata, global providers +โ”‚ โ”‚ โ”œโ”€โ”€ page.tsx # Home / main application view +โ”‚ โ”‚ โ”œโ”€โ”€ globals.css # Design system: tokens, utilities, themes +โ”‚ โ”‚ โ”œโ”€โ”€ dashboard/ # Active intents dashboard (in progress) +โ”‚ โ”‚ โ””โ”€โ”€ vaults/ # Future: asset management (planned) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ components/ +โ”‚ โ”‚ โ”œโ”€โ”€ Navbar.tsx # Top navigation bar with wallet button +โ”‚ โ”‚ โ”œโ”€โ”€ WalletConnectButton.tsx # Freighter wallet connect/disconnect +โ”‚ โ”‚ โ”œโ”€โ”€ OnboardingModal.tsx # 4-slide first-visit onboarding carousel +โ”‚ โ”‚ โ”œโ”€โ”€ HeroIllustration.tsx # Animated landing page banner +โ”‚ โ”‚ โ”œโ”€โ”€ LaunchButton.tsx # Wallet-gated app entry button +โ”‚ โ”‚ โ”œโ”€โ”€ SecurityNotice.tsx # Dismissible security/beta warning +โ”‚ โ”‚ โ””โ”€โ”€ Toast.tsx # Notification system +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ lib/ +โ”‚ โ”‚ โ”œโ”€โ”€ hooks.ts # Custom hooks: useWallet, useCreateEscrow, etc. +โ”‚ โ”‚ โ””โ”€โ”€ constants.ts # Network config, contract IDs, enums +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ types/ +โ”‚ โ”‚ โ””โ”€โ”€ global.d.ts # Global TypeScript declarations +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ public/ +โ”‚ โ”œโ”€โ”€ epochsend-banner.png # Hero illustration asset +โ”‚ โ”œโ”€โ”€ epochsend-logo.png # App logo +โ”‚ โ””โ”€โ”€ epochsend.svg # Favicon / SVG logo +โ”‚ +โ”œโ”€โ”€ .github/ +โ”‚ โ””โ”€โ”€ workflows/ci.yml # GitHub Actions CI (build + lint) +โ”‚ +โ”œโ”€โ”€ README.md # This file +โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines +โ”œโ”€โ”€ CODE_OF_CONDUCT.md # Community standards +โ”œโ”€โ”€ MAINTAINERS.md # Maintainer roster +โ””โ”€โ”€ STYLE.md # Code style guide +``` --- ## ๐Ÿš€ Getting Started -### 1. Prerequisites -* Node.js v18+ -* npm or yarn -* Freighter Wallet installed in your browser +### Prerequisites + +- **Node.js** v20+ ([download](https://nodejs.org/)) +- **npm** v9+ +- **Freighter Wallet** browser extension ([install](https://www.freighter.app/)) +- A Stellar **Testnet** account funded via [Friendbot](https://laboratory.stellar.org/#account-creator?network=test) -### 2. Local Setup +### 1. Clone & Install ```bash -cd frontend +git clone https://github.com/StacksTrench/EpochSend-frontend.git +cd EpochSend-frontend/frontend +npm install --legacy-peer-deps +``` + +### 2. Configure Environment -# Install dependencies -npm install +```bash +cp .env.example .env.local +``` -# Run the development server +Edit `.env.local`: + +```env +# Stellar Network +NEXT_PUBLIC_STELLAR_NETWORK=TESTNET +NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org +NEXT_PUBLIC_NETWORK_PASSPHRASE="Test SDF Network ; September 2015" + +# EpochSend Soroban Contract +NEXT_PUBLIC_ESCROW_CONTRACT_ID=C... # Deploy and paste address here +``` + +### 3. Run Development Server + +```bash npm run dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the application. +Open [http://localhost:3000](http://localhost:3000) in your browser. + +### 4. Connect Your Wallet + +1. Click **"Connect Wallet"** in the top-right corner +2. Freighter will prompt for permission โ€” approve it +3. Make sure Freighter is set to **Testnet** mode +4. Fund your testnet wallet via [Stellar Friendbot](https://laboratory.stellar.org/#account-creator?network=test) if needed + +--- + +## ๐Ÿ”ง Available Scripts + +```bash +npm run dev # Start development server (hot reload) +npm run build # Compile production bundle +npm run start # Run production server locally +npm run lint # Run ESLint code checks +``` + +--- + +## ๐ŸŒ Network Configuration + +EpochSend currently targets **Stellar Testnet** for development. To deploy on mainnet: + +1. Update `NEXT_PUBLIC_STELLAR_NETWORK` to `MAINNET` +2. Update `NEXT_PUBLIC_SOROBAN_RPC_URL` to `https://mainnet.sorobanrpc.com` +3. Update `NEXT_PUBLIC_NETWORK_PASSPHRASE` to `Public Global Stellar Network ; September 2015` +4. Update `NEXT_PUBLIC_ESCROW_CONTRACT_ID` to your mainnet contract address + +--- + +## ๐Ÿ” Security Model + +| Property | Implementation | +|---|---| +| **Non-custodial** | EpochSend developers have zero access to locked funds | +| **Auth enforcement** | Only the defined trigger authority can execute or refund a contract | +| **Reentrancy protection** | Soroban contract follows Checks-Effects-Interactions pattern | +| **Timeout safety** | Funds can never be permanently frozen โ€” sender can always retrieve after `dispute_timeout` | +| **Simulation-first** | All transactions are simulated before prompting user to sign | + +--- + +## ๐Ÿ“Š Success Metrics + +| Metric | Description | +|---|---| +| **Total Value Locked (TVL)** | USDC/XLM actively held in escrow across all intents | +| **Execution Rate** | Percentage of escrows successfully executed vs refunded | +| **Active Unique Wallets** | Number of distinct wallet connections per month | +| **Transaction Volume** | Total dollar value processed through the protocol | +| **Oracle Uptime** | Backend oracle availability for webhook-triggered escrows | --- -## ๐Ÿ“š Documentation & Task Tracking +## ๐Ÿ“š Documentation -* ๐ŸŽจ **[Frontend Issues Tracker](./docs/ISSUES-FRONTEND.md)** -* ๐ŸŒ **[Frontend Integration Guide](./docs/FRONTEND_GUIDE.md)** -* ๐Ÿ“„ **[Product Requirements Document](./docs/PRD.md)** +| Document | Description | +|---|---| +| [๐Ÿ“„ PRD](./docs/PRD.md) | Full Product Requirements Document โ€” vision, architecture, roadmap | +| [๐Ÿ—‚๏ธ Issues & Roadmap](./docs/ISSUES.md) | Granular frontend feature tracker with module breakdown | +| [๐ŸŒ Frontend Integration Guide](./docs/FRONTEND_GUIDE.md) | Technical guide: Freighter, Soroban SDK, XDR encoding | +| [๐Ÿค Contributing](./CONTRIBUTING.md) | How to contribute to EpochSend | +| [๐ŸŽจ Style Guide](./STYLE.md) | Code style, naming conventions, and formatting rules | +| [๐Ÿ“œ Code of Conduct](./CODE_OF_CONDUCT.md) | Community standards and expectations | --- ## ๐Ÿค Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE.md](STYLE.md). +Contributions are welcome and actively encouraged. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR. + +**Quick workflow:** +1. Fork the repository +2. Create a feature branch: `git checkout -b feat/your-feature-name` +3. Make your changes and write tests where applicable +4. Push and open a Pull Request against `main` +5. A maintainer will review and merge + +--- + +## ๐Ÿ‘ฅ Maintainers + +See [MAINTAINERS.md](./MAINTAINERS.md) for the full list of project maintainers. + +--- + +## ๐Ÿ“„ License + +[MIT](./LICENSE) โ€” free to use, fork, and build on top of. --- -*Project maintained by @babalola & contributors.* +

+ Built with โšก on Stellar ยท Deployed on Vercel +

From 930f619a68dc9787bbc0935dae251e53d7496efb Mon Sep 17 00:00:00 2001 From: bbkenny Date: Wed, 10 Jun 2026 22:49:05 +0100 Subject: [PATCH 2/2] docs: expand ISSUES.md to comprehensive 44-issue frontend roadmap --- docs/ISSUES.md | 629 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 595 insertions(+), 34 deletions(-) diff --git a/docs/ISSUES.md b/docs/ISSUES.md index 7178e7b..dd8df8e 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -1,58 +1,619 @@ -# EpochSend Frontend Issues & Roadmap +# EpochSend Frontend โ€” Issues & Roadmap ๐Ÿ—‚๏ธ **Live App:** [https://epochsend.vercel.app/](https://epochsend.vercel.app/) -This document outlines the current state of the EpochSend frontend, capturing architectural debt inherited from previous iterations and charting the roadmap to a production-ready Stellar-native application. +This document is the authoritative tracker for all frontend engineering tasks on the EpochSend protocol. It captures what has been shipped, what is actively being built, and the full roadmap to a production-grade Stellar-native application. Issues are grouped into logical modules and numbered sequentially. -## ๐Ÿ”ด Critical Architectural Debt & Refactoring +> **Standards:** Every issue follows the format โ€” priority, labels, description, and granular sub-tasks with assignable checkboxes. Status: โœ… COMPLETED | ๐Ÿ”จ IN PROGRESS | โŒ PENDING | ๐Ÿ”œ FUTURE -### Issue #1: Excise EVM Dependencies (Wagmi / Reown / Viem) +--- + +## ๐Ÿ—๏ธ Module 1: Foundation & Configuration (FE-01 โ†’ FE-06) + +### Issue #FE-01: Project Scaffold & Next.js App Router Setup +**Status:** โœ… COMPLETED | **Priority:** CRITICAL +**Labels:** `foundation`, `config` +**Description:** Initialize the Next.js 16 app with App Router, TypeScript, Tailwind CSS v4, and EpochSend project metadata. +- **Tasks:** + - [x] Bootstrap project with `create-next-app` (App Router, TypeScript, Tailwind) + - [x] Configure `next.config.ts` with strict mode + - [x] Set root layout metadata: title, description, favicon (`epochsend.svg`) + - [x] Configure `postcss.config.mjs` for Tailwind v4 + - [x] Add `vercel.json` for deployment configuration + +--- + +### Issue #FE-02: Design System & Global CSS Tokens +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** CRITICAL +**Labels:** `foundation`, `ui`, `design` +**Description:** Define the full EpochSend design system โ€” colour palette, typography, spacing, and reusable utility classes โ€” as CSS variables and Tailwind tokens in `globals.css`. +- **Tasks:** + - [x] Set dark background tokens (`--color-background: #050505`, `--color-foreground: #ffffff`) + - [x] Define glassmorphism utility class (`.glass`, `.glass-hover`) + - [x] Define gradient text utility (`.text-gradient`) + - [x] Set custom dark scrollbar + - [ ] Load Inter font via `next/font/google` (currently referenced but not loaded) + - [ ] Define full colour palette as CSS variables (primary, secondary, accent, muted, destructive) + - [ ] Define `.btn`, `.btn-primary`, `.btn-outline`, `.btn-retro` classes (currently referenced in components but missing from CSS โ€” causes unstyled buttons) + - [ ] Add light mode token set under `@media (prefers-color-scheme: light)` or `[data-theme="light"]` + - [ ] Wire `next-themes` ThemeProvider in root layout (package installed but unused) + +--- + +### Issue #FE-03: Environment Configuration & Constants +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** CRITICAL +**Labels:** `foundation`, `config`, `blockchain` +**Description:** Centralise all network configuration, contract addresses, and environment variables so that switching between Testnet and Mainnet is a single `.env` change. +- **Tasks:** + - [x] Create `lib/constants.ts` with `STELLAR_NETWORK`, `SOROBAN_RPC_URL`, `SOROBAN_NETWORK_PASSPHRASE`, `ConditionType` enum + - [x] Create `.env.example` with all required variables + - [ ] Update `.env.example` to remove irrelevant `WALLETCONNECT_PROJECT_ID` variable + - [ ] Import and consume `constants.ts` inside `lib/hooks.ts` (currently defined but never imported anywhere) + - [ ] Add `NEXT_PUBLIC_ESCROW_CONTRACT_ID` env variable and wire it into the hook layer + - [ ] Add environment validation on app startup (throw clear error if contract ID is missing) + +--- + +### Issue #FE-04: Project Cleanup โ€” Remove Legacy Artefacts +**Status:** โŒ PENDING | **Priority:** HIGH +**Labels:** `foundation`, `cleanup` +**Description:** Remove all stale copy and incorrect references inherited from the previous ForgeX project iteration. +- **Tasks:** + - [ ] Remove or replace `TODO.md` (currently the ForgeX TODO โ€” references VaultCard, AIChat, useVaultFactory) + - [ ] Clean up `types/global.d.ts` โ€” remove AppKit web component declarations (irrelevant to Stellar/Freighter stack) + - [ ] Fix `SecurityNotice.tsx` โ€” component copy reads "ForgeX is still under development" instead of EpochSend + - [ ] Update `frontend/README.md` to EpochSend content (currently refers to wrong tech stack) + - [ ] Integrate `clsx` and `tailwind-merge` into a `cn()` utility helper in `lib/utils.ts` (installed but never used) + +--- + +### Issue #FE-05: CI/CD Pipeline +**Status:** โœ… COMPLETED | **Priority:** HIGH +**Labels:** `devops`, `ci` +**Description:** Set up GitHub Actions to run build and lint checks on every push and pull request. +- **Tasks:** + - [x] Create `.github/workflows/ci.yml` with `frontend-build` job + - [x] Pin Node.js to v20 in CI (required for Next.js 16+) + - [x] Use `npm ci --legacy-peer-deps` to handle peer dependency conflicts + - [x] Run `npm run build` to validate production bundle on every push + +--- + +### Issue #FE-06: Gitignore & Artifact Management +**Status:** โœ… COMPLETED | **Priority:** MEDIUM +**Labels:** `devops`, `config` +**Description:** Ensure build outputs, local env files, and OS artefacts are excluded from version control. +- **Tasks:** + - [x] Ignore `.next/`, `out/`, `dist/`, `build/` directories + - [x] Ignore `.env`, `.env.local`, `.env.*.local` + - [x] Ignore `node_modules/`, `*.log`, `.DS_Store`, `*.pem` + +--- + +## ๐Ÿ‘› Module 2: Wallet & Blockchain Integration (FE-07 โ†’ FE-11) + +### Issue #FE-07: Freighter Wallet Hook +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** CRITICAL +**Labels:** `wallet`, `blockchain`, `hooks` +**Description:** Implement a robust, production-grade `useWallet()` custom hook that handles all Freighter wallet lifecycle events. +- **Tasks:** + - [x] Check if Freighter extension is installed on mount + - [x] Auto-reconnect if wallet was previously connected (on page refresh) + - [x] Expose `address` and `connect()` from the hook + - [ ] Handle `disconnect()` gracefully โ€” clear address state and local session + - [ ] Detect and handle network mismatch (user on wrong Stellar network) + - [ ] Expose `isInstalled` boolean so UI can show "Install Freighter" CTA if extension missing + - [ ] Expose `networkType` so components can show the active network (Testnet / Mainnet) + - [ ] Add error state handling (`walletError`) for rejected connection requests + +--- + +### Issue #FE-08: Global Wallet Context Provider **Status:** โŒ PENDING | **Priority:** CRITICAL -- **Description:** The current codebase contains legacy dependencies tied to EVM chains (Wagmi, Viem, Reown AppKit). Since EpochSend is a Stellar-native protocol, these must be completely removed. +**Labels:** `wallet`, `state-management` +**Description:** Lift wallet state into a React Context provider so any component in the tree can access the connected address without prop drilling. - **Tasks:** - - Uninstall `wagmi`, `viem`, and any Reown packages. - - Delete `config/wagmi.ts` and associated EVM contexts. - - Remove EVM-specific hooks and replace them with native Stellar implementations. + - [ ] Create `contexts/WalletContext.tsx` with `WalletProvider` and `useWalletContext()` hook + - [ ] Wrap the root layout in `WalletProvider` + - [ ] Migrate `page.tsx`, `WalletConnectButton.tsx`, and `LaunchButton.tsx` to use context instead of individual hook calls + - [ ] Add `isConnected` derived boolean to context + +--- -### Issue #2: Integrate Freighter Wallet & Stellar SDK +### Issue #FE-09: Soroban RPC Client & Transaction Builder **Status:** โŒ PENDING | **Priority:** CRITICAL -- **Description:** Replace EVM wallet connections with `@stellar/freighter-api` and `@stellar/stellar-sdk`. +**Labels:** `blockchain`, `soroban`, `rpc` +**Description:** Build the core Stellar/Soroban integration layer: RPC server initialisation, account loading, and the transaction simulation + submission pipeline. +- **Tasks:** + - [ ] Create `lib/stellar.ts` โ€” initialise `SorobanRpc.Server` from env constants + - [ ] Implement `getAccount(address)` helper โ€” fetch the account sequence number from RPC + - [ ] Implement `simulateTransaction(tx)` wrapper โ€” always simulate before signing + - [ ] Implement `submitTransaction(signedXdr)` โ€” submit to RPC and handle response codes + - [ ] Handle `PENDING`, `SUCCESS`, `ERROR`, `NOT_FOUND` RPC response states + - [ ] Implement XDR encoding helpers for common types: `Address`, `i128`, `u64`, `Symbol` + +--- + +### Issue #FE-10: WalletConnectButton โ€” Polish & States +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** HIGH +**Labels:** `wallet`, `ui` +**Description:** The current button renders unstyled (CSS class `btn-retro` is undefined). Implement all required visual states. +- **Tasks:** + - [ ] Define `.btn-retro` CSS class in `globals.css` (currently missing โ€” button is completely unstyled) + - [ ] Show truncated address when connected (`GXXXXX...XXXX`) + - [ ] Add a green pulse indicator dot when connected + - [ ] Add a dropdown or popover on connected state: show full address, copy address, disconnect + - [ ] Add loading state while connection request is in progress + - [ ] Show "Install Freighter" link if extension is not detected + +--- + +### Issue #FE-11: Network Switcher Component +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `wallet`, `config`, `ui` +**Description:** Allow users to switch between Stellar Testnet and Mainnet directly from the UI, with the contract and RPC updating accordingly. +- **Tasks:** + - [ ] Create `components/NetworkBadge.tsx` โ€” pill badge showing active network + - [ ] Show "TESTNET" badge prominently in Navbar when on testnet (safety indicator) + - [ ] Implement network change trigger โ€” update RPC URL and network passphrase in context + - [ ] Display warning modal when switching to Mainnet ("Real funds will be used") + +--- + +## ๐Ÿ”’ Module 3: Core Escrow โ€” Create Intent Flow (FE-12 โ†’ FE-18) + +### Issue #FE-12: Intent Creation Form โ€” Full Validation +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** CRITICAL +**Labels:** `feature`, `form`, `validation` +**Description:** The create-escrow form UI exists but has minimal validation. Implement comprehensive client-side validation before any transaction is built. - **Tasks:** - - Create a new `StellarProvider` context to manage wallet connection state. - - Update `Navbar.tsx` and `LaunchButton.tsx` to trigger Freighter wallet connection. - - Implement network switching (Testnet / Mainnet) using Freighter's API. + - [x] Build multi-step form: Recipient, Asset/Amount, Condition Type, Condition Data + - [x] Implement condition toggle: "Time Lock" (datetime) vs "Arbiter" (address input) + - [ ] Validate recipient is a valid Stellar address (starts with `G`, 56 chars) + - [ ] Validate arbiter is a valid Stellar address and differs from sender + - [ ] Validate amount is positive and does not exceed connected wallet balance + - [ ] Validate unlock timestamp is in the future + - [ ] Disable submit button until all fields pass validation + - [ ] Show inline field-level error messages (not just blocked submission) + - [ ] Show a pre-confirmation summary before the user signs: "You are locking X USDC until [date] with [recipient]" -## ๐ŸŸก Core Feature Implementation +--- -### Issue #3: Intent Creation UI (Conditional Escrow) +### Issue #FE-13: `useCreateEscrow` โ€” Real Soroban Implementation +**Status:** โŒ PENDING | **Priority:** CRITICAL +**Labels:** `blockchain`, `soroban`, `hooks` +**Description:** Replace the current `console.log` stub with a real Soroban transaction that calls `create_intent()` on the EpochSend smart contract. +- **Tasks:** + - [ ] Import `SorobanRpc`, `Contract`, `TransactionBuilder`, `xdr` from `@stellar/stellar-sdk` + - [ ] Load sender account from RPC using `getAccount(address)` + - [ ] Build `InvokeHostFunctionOperation` calling `create_intent(sender, recipient, asset, amount, expiration, oracle_id)` + - [ ] Encode all arguments as XDR `ScVal` types (Address โ†’ scvAddress, i128 โ†’ scvI128, u64 โ†’ scvU64) + - [ ] Simulate the transaction and verify simulation success before proceeding + - [ ] Prompt user to sign via `signTransaction()` from `@stellar/freighter-api` + - [ ] Submit the signed XDR to Soroban RPC + - [ ] Return the `intent_id` from the contract response + - [ ] Handle errors: simulation failure, user rejection, submission failure, timeout + +--- + +### Issue #FE-14: `useExecuteEscrow` โ€” Real Soroban Implementation +**Status:** โŒ PENDING | **Priority:** CRITICAL +**Labels:** `blockchain`, `soroban`, `hooks` +**Description:** Replace the `console.log` stub with a real `execute()` call on the contract, signed by the arbiter or triggered automatically for time-based conditions. +- **Tasks:** + - [ ] Build transaction calling `execute(intent_id)` on the escrow contract + - [ ] Determine caller authority: arbiter (for Manual mode) or any caller (for Timestamp mode) + - [ ] Simulate โ†’ Sign โ†’ Submit pipeline (same pattern as `useCreateEscrow`) + - [ ] Update local escrow state to `Executed` on confirmed success + - [ ] Handle "Condition not met" error from contract (timestamp not reached) with user-facing message + +--- + +### Issue #FE-15: `useRefundEscrow` โ€” Real Soroban Implementation +**Status:** โŒ PENDING | **Priority:** CRITICAL +**Labels:** `blockchain`, `soroban`, `hooks` +**Description:** Replace the `console.log` stub with a real `refund()` call signed by the original sender. +- **Tasks:** + - [ ] Build transaction calling `refund(intent_id)` on the escrow contract + - [ ] Enforce sender-only auth (only the original sender can trigger refund) + - [ ] Simulate โ†’ Sign โ†’ Submit pipeline + - [ ] Update local escrow state to `Refunded` on confirmed success + - [ ] Handle "Already executed" and "Already refunded" errors gracefully + +--- + +### Issue #FE-16: Toast Notification System **Status:** โŒ PENDING | **Priority:** HIGH -- **Description:** Build the primary interface where users can lock funds (USDC/XLM) with specific conditions. +**Labels:** `ux`, `feedback` +**Description:** The current `useToast()` is a `console.log` stub โ€” zero UI feedback is shown to users. Implement a real, styled toast notification system. +- **Tasks:** + - [ ] Build `components/ToastProvider.tsx` โ€” maintains a queue of active toasts in state + - [ ] Wrap root layout in `` + - [ ] Design toast variants: `success` (green), `error` (red), `warning` (amber), `info` (teal) + - [ ] Add entry/exit animations via Framer Motion (`AnimatePresence`) + - [ ] Auto-dismiss after 4 seconds with progress bar indicator + - [ ] Allow manual dismiss via X button + - [ ] Update `useToast()` hook to push to the provider queue + - [ ] Replace all `console.log` toast calls in `page.tsx` with real `showToast()` calls + +--- + +### Issue #FE-17: Transaction Signing Overlay +**Status:** โŒ PENDING | **Priority:** HIGH +**Labels:** `ux`, `feedback` +**Description:** When the user is waiting for Freighter to sign a transaction, the UI should show a clear, full-experience overlay preventing interaction. +- **Tasks:** + - [ ] Create `components/SigningOverlay.tsx` โ€” full-screen blur overlay + - [ ] Show animated spinner with message: "Waiting for Freighter signature..." + - [ ] Show follow-up state: "Submitting to Stellar network..." + - [ ] Show success state with transaction hash and Stellar Explorer link + - [ ] Show failure state with clear error description and retry option + - [ ] Trigger overlay during `isCreating`, `isExecuting`, `isRefunding` states + +--- + +### Issue #FE-18: On-chain Intent Fetching (`useGetIntents`) +**Status:** โŒ PENDING | **Priority:** CRITICAL +**Labels:** `blockchain`, `soroban`, `hooks`, `data` +**Description:** Replace the two hardcoded mock escrow entries in `page.tsx` with real data fetched from the Soroban contract. - **Tasks:** - - Create a multi-step form for defining a payment intent. - - Implement fields for: Recipient Address, Asset Type, Amount, Time-Lock duration, and Oracle Webhook URL. - - Build the Soroban transaction submission logic via Freighter. + - [ ] Implement `useGetIntents(address)` hook โ€” queries `get_intent(id)` on the contract for the connected address + - [ ] Implement intent counter query to know how many intents exist + - [ ] Parse `ScVal` contract response into the `EscrowItem` TypeScript interface + - [ ] Handle empty state: "You have no active intents" with CTA to create one + - [ ] Implement polling (every 15 seconds) to refresh intent status without full page reload + - [ ] Remove the two hardcoded mock entries from `page.tsx` + +--- -### Issue #4: Active Intents Dashboard +## ๐Ÿ“Š Module 4: Active Intents Dashboard (FE-19 โ†’ FE-24) + +### Issue #FE-19: Intents Dashboard Page (`/dashboard`) **Status:** โŒ PENDING | **Priority:** HIGH -- **Description:** A dashboard for users to view and manage their active and historical payment intents. +**Labels:** `feature`, `page`, `routing` +**Description:** Build out the currently-empty `/dashboard` directory into a fully functional Active Intents management page. +- **Tasks:** + - [ ] Create `app/dashboard/page.tsx` โ€” requires wallet connection to access + - [ ] Redirect unauthenticated users to home with "Connect your wallet to continue" message + - [ ] Layout: summary stats header (Total Locked Value, Active Count, Executed Count, Refunded Count) + - [ ] Filter tabs: All | Locked | Executed | Refunded + - [ ] Render intent cards using real contract data from `useGetIntents()` + - [ ] Add Navbar link to `/dashboard` for connected users + +--- + +### Issue #FE-20: Intent Detail Card Component +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** HIGH +**Labels:** `ui`, `component` +**Description:** The current escrow card is basic. Build a rich intent card that shows all relevant information clearly. +- **Tasks:** + - [x] Show condition type label ("Time Lock" / "Arbiter") + - [x] Show status badge with colour coding (Locked=amber, Executed=green, Refunded=red) + - [x] Show amount, asset type, and recipient address + - [ ] Show intent ID from contract + - [ ] Show time remaining until unlock (formatted countdown for Timestamp mode) + - [ ] Show arbiter address for Manual mode + - [ ] Show "View on Stellar Explorer" link using the transaction hash + - [ ] Show creation timestamp + - [ ] Improve address display: truncate with copy-to-clipboard button + +--- + +### Issue #FE-21: Escrow Status Badge & Real-Time Updates +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `ui`, `data`, `real-time` +**Description:** Status badges should reflect live on-chain state, not just local React state. - **Tasks:** - - Fetch active escrows from the Soroban smart contract. - - Display status indicators: "Locked", "Ready", "Executed", "Refunded". - - Implement a "Refund" button for expired intents. + - [ ] Differentiate between "Locked โ€” Condition Pending", "Locked โ€” Condition Met (Ready to Execute)", "Executed", "Refunded" + - [ ] Poll contract state every 15s and update badge without full page reload + - [ ] Animate badge transition when status changes (e.g., Locked โ†’ Executed) + - [ ] Show a "Ready to Release" pulse animation when a time-based condition has been met + +--- -### Issue #5: Oracle Webhook Management +### Issue #FE-22: Empty & Loading States **Status:** โŒ PENDING | **Priority:** MEDIUM -- **Description:** An interface for users to register and manage their off-chain conditions via the EpochSend backend. +**Labels:** `ux`, `ui` +**Description:** Every data-fetching view needs proper loading skeletons and empty states. - **Tasks:** - - Connect the frontend to the Express backend API. - - Allow users to test webhook endpoints before locking funds. + - [ ] Build `components/IntentCardSkeleton.tsx` โ€” animated shimmer placeholder + - [ ] Show 2โ€“3 skeleton cards while intents are loading from RPC + - [ ] Design empty state: illustration + "No active intents yet" + "Create your first intent โ†’" CTA + - [ ] Handle error state: RPC failure message with retry button -## ๐ŸŸข UI/UX Polish +--- -### Issue #6: EpochSend Brand Alignment +### Issue #FE-23: Intent Creation Success Flow **Status:** โŒ PENDING | **Priority:** MEDIUM -- **Description:** Ensure all copy, SVGs, and brand colors perfectly align with the new EpochSend identity. +**Labels:** `ux`, `flow` +**Description:** After successfully creating an intent, guide the user clearly rather than just resetting the form silently. - **Tasks:** - - Replace any remaining legacy copy in components. - - Ensure the dark-mode-first aesthetic matches the new `epochsend-logo.svg`. - - Add micro-animations to the Intent Creation flow using Framer Motion. + - [ ] Show a full success screen / modal after intent is confirmed on-chain + - [ ] Display: intent ID, locked amount, condition type, Stellar Explorer transaction link + - [ ] Offer "Copy Intent ID" and "Share Intent" actions + - [ ] Auto-navigate user to the dashboard to see their new intent in the list + - [ ] Show toast: "Intent created โ€” X USDC locked until [date]" + +--- + +### Issue #FE-24: Transaction History Feed +**Status:** ๐Ÿ”œ FUTURE | **Priority:** MEDIUM +**Labels:** `data`, `feature` +**Description:** Show a chronological log of all past transactions (creates, executes, refunds) associated with the connected wallet. +- **Tasks:** + - [ ] Research indexer options: Stellar Horizon API, Mercury indexer, or custom backend events + - [ ] Fetch all `create_intent`, `execute`, `refund` events by sender address + - [ ] Render paginated list: date, type, amount, counterparty address, status + - [ ] Add "Export to CSV" button for the full transaction history + +--- + +## ๐ŸŒ Module 5: Oracle & Backend Integration (FE-25 โ†’ FE-29) + +### Issue #FE-25: Backend API Client +**Status:** โŒ PENDING | **Priority:** HIGH +**Labels:** `feature`, `backend`, `api` +**Description:** Connect the frontend to the EpochSend backend Express API for oracle-triggered conditions. +- **Tasks:** + - [ ] Create `lib/api.ts` โ€” base fetch client pointing to `NEXT_PUBLIC_BACKEND_URL` + - [ ] Add `NEXT_PUBLIC_BACKEND_URL` to `.env.example` + - [ ] Implement `GET /health` check โ€” show backend connection status in UI + - [ ] Implement `POST /api/webhooks/trigger` โ€” submit oracle trigger requests + - [ ] Handle API errors with typed error responses + - [ ] Add request/response TypeScript types for all API endpoints + +--- + +### Issue #FE-26: Oracle Webhook Registration UI +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `feature`, `oracle`, `form` +**Description:** When a user creates an oracle-condition intent, they need to register and test their webhook URL before locking funds. +- **Tasks:** + - [ ] Add "Oracle Webhook URL" field to the create intent form (shown when Oracle condition selected) + - [ ] Implement `POST /api/webhooks/test` โ€” send a test ping to the user's URL and verify it responds 200 + - [ ] Show webhook test result inline: โœ… Reachable / โŒ Unreachable + - [ ] Only allow form submission if webhook URL has been verified + - [ ] Display registered webhook URL on the intent detail card + +--- + +### Issue #FE-27: Oracle Condition Type in Form +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `feature`, `ui`, `oracle` +**Description:** The current form only shows two condition types (Time Lock / Arbiter). Add the Oracle/Webhook condition type. +- **Tasks:** + - [ ] Add "Oracle" as a third tab in the condition toggle + - [ ] Show: Webhook URL input, description field (e.g., "FedEx delivery confirmation"), oracle ID + - [ ] Update `ConditionType` enum in `constants.ts` and contract interface to include Oracle + - [ ] Pass oracle address to `create_intent()` call + +--- + +### Issue #FE-28: Oracle Status Tracker +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `feature`, `oracle`, `real-time` +**Description:** For oracle-triggered intents, show the current status of the oracle listener so users know the system is active. +- **Tasks:** + - [ ] Show "Oracle listening..." status on intent cards with oracle condition + - [ ] Display last webhook ping timestamp + - [ ] Allow user to manually trigger execution after confirming oracle condition is met + +--- + +### Issue #FE-29: Backend Health Indicator +**Status:** โŒ PENDING | **Priority:** LOW +**Labels:** `ux`, `backend` +**Description:** Show a subtle system status indicator so users know if the backend oracle service is online. +- **Tasks:** + - [ ] Add a small status dot in the footer or navbar area + - [ ] Poll `GET /health` every 60 seconds + - [ ] Green = backend online, Red = backend offline + - [ ] Show tooltip: "Oracle Service: Online / Offline" + +--- + +## โœจ Module 6: UX Polish & Feedback (FE-30 โ†’ FE-36) + +### Issue #FE-30: Error Boundary Implementation +**Status:** โŒ PENDING | **Priority:** HIGH +**Labels:** `stability`, `ux` +**Description:** Prevent the entire app from crashing when an unexpected JavaScript error occurs in a component subtree. +- **Tasks:** + - [ ] Create `components/ErrorBoundary.tsx` React class component + - [ ] Wrap the main content area in `` + - [ ] Design fallback UI: branded error screen with "Something went wrong" + "Reload" button + - [ ] Log errors to console (and later: error tracking service) + +--- + +### Issue #FE-31: Mobile Responsiveness Audit +**Status:** โŒ PENDING | **Priority:** HIGH +**Labels:** `ui`, `responsive` +**Description:** The current 2-column grid layout is desktop-first. Audit and fix the layout for mobile viewports. +- **Tasks:** + - [ ] Audit all breakpoints: 375px (mobile), 768px (tablet), 1280px (desktop) + - [ ] Make the 2-column grid stack vertically on mobile (`grid-cols-1` below md) + - [ ] Make the Navbar hamburger-friendly (or hide secondary links on mobile) + - [ ] Ensure all form inputs and buttons have minimum 44px touch target size + - [ ] Test Freighter wallet connection flow on mobile browser + +--- + +### Issue #FE-32: Performance Optimisation +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `performance`, `optimisation` +**Description:** Optimise rendering performance as data fetching and component count grows. +- **Tasks:** + - [ ] Wrap heavy components in `React.memo` to prevent unnecessary re-renders + - [ ] Use `useCallback` for event handlers passed as props + - [ ] Optimise public images with `next/image` (currently using raw `` tags) + - [ ] Add lazy loading for the `OnboardingModal` (not needed on first byte) + - [ ] Audit and reduce bundle size โ€” remove unused installed packages (`next-themes` if not used, `clsx` if not wired up) + +--- + +### Issue #FE-33: Accessibility (a11y) Pass +**Status:** โŒ PENDING | **Priority:** MEDIUM +**Labels:** `accessibility`, `a11y` +**Description:** Ensure the application is usable with keyboard navigation and screen readers. +- **Tasks:** + - [ ] Add `aria-label` to all icon-only buttons + - [ ] Ensure modal (`OnboardingModal`) traps focus while open + - [ ] Implement `role="status"` on toast notifications for screen reader announcement + - [ ] Add `aria-live="polite"` region for dynamic content updates (intent status changes) + - [ ] Verify keyboard tab order through the create-intent form is logical + +--- + +### Issue #FE-34: Dark Mode Refinement +**Status:** โŒ PENDING | **Priority:** LOW +**Labels:** `ui`, `theming` +**Description:** Wire the installed `next-themes` package and add a usable theme toggle to the Navbar. +- **Tasks:** + - [ ] Add `ThemeProvider` from `next-themes` to root layout + - [ ] Create `components/ThemeToggle.tsx` โ€” icon button (Sun/Moon) using Lucide icons + - [ ] Add `ThemeToggle` to the Navbar + - [ ] Define light mode CSS tokens in `globals.css` โ€” surface backgrounds, card borders, text contrast + - [ ] Test all components render correctly in both light and dark mode + +--- + +### Issue #FE-35: Micro-Animations & Interaction Polish +**Status:** ๐Ÿ”จ IN PROGRESS | **Priority:** MEDIUM +**Labels:** `ui`, `animation`, `ux` +**Description:** Use Framer Motion (already installed) to add purposeful micro-animations throughout the intent creation flow. +- **Tasks:** + - [x] Navbar entry animation (slide-down from top) + - [x] Hero illustration fade-in and hover scale + - [x] Onboarding modal slide transitions between cards + - [ ] Add staggered entry animation to intent card grid (cards appear one-by-one, not all at once) + - [ ] Animate condition toggle tab switch (slide indicator) + - [ ] Animate form field appearance when switching condition type (Time Lock โ†” Arbiter) + - [ ] Add "success" particle or confetti burst on intent creation confirmation + +--- + +### Issue #FE-36: SEO & Open Graph +**Status:** โŒ PENDING | **Priority:** LOW +**Labels:** `seo`, `marketing` +**Description:** Ensure EpochSend is discoverable and shareable with proper metadata. +- **Tasks:** + - [ ] Set `` and `<meta name="description">` per page in `layout.tsx` + - [ ] Add Open Graph tags: `og:title`, `og:description`, `og:image` (use `epochsend-banner.png`) + - [ ] Add Twitter/X card tags + - [ ] Add `robots.txt` and `sitemap.xml` + - [ ] Verify all pages have a single `<h1>` with proper heading hierarchy + +--- + +## ๐Ÿš€ Module 7: Advanced Features & Phase 2 (FE-37 โ†’ FE-44) + +### Issue #FE-37: Recurring Payment Scheduling UI +**Status:** ๐Ÿ”œ FUTURE | **Priority:** MEDIUM +**Labels:** `feature`, `phase-2` +**Description:** Allow users to schedule recurring payments (subscriptions) โ€” "Send 50 USDC to [address] every Friday". +- **Tasks:** + - [ ] Add "Recurring" as a fourth condition type in the create intent form + - [ ] Build frequency selector: Daily, Weekly, Monthly, Custom interval + - [ ] Display recurring intents separately in the dashboard with "Next execution" timestamp + - [ ] Show total value committed over the full subscription period + +--- + +### Issue #FE-38: Multi-Signature Arbiter Flow +**Status:** ๐Ÿ”œ FUTURE | **Priority:** MEDIUM +**Labels:** `feature`, `phase-2`, `security` +**Description:** Allow multiple arbiters to be required for execution (M-of-N multi-sig release). +- **Tasks:** + - [ ] Add M-of-N arbiter configuration to create intent form + - [ ] Show approval progress bar on intent cards: "2 of 3 arbiters approved" + - [ ] Allow each arbiter to sign independently from their own connected wallet + - [ ] Auto-execute when threshold is reached + +--- + +### Issue #FE-39: Intent Sharing & Deep Links +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `feature`, `ux` +**Description:** Allow users to share a specific intent with the recipient or arbiter via a direct link. +- **Tasks:** + - [ ] Generate shareable URL: `epochsend.vercel.app/intent/[intent_id]` + - [ ] Build `app/intent/[id]/page.tsx` โ€” public view of an intent (no wallet needed to view) + - [ ] Show: sender, recipient, amount, condition, current status + - [ ] Allow arbiter to connect wallet and sign directly from the shared URL + +--- + +### Issue #FE-40: Analytics Dashboard +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `feature`, `analytics`, `phase-3` +**Description:** Protocol-level stats page showing aggregate EpochSend usage. +- **Tasks:** + - [ ] Create `app/stats/page.tsx` + - [ ] Display: Total Value Locked (TVL), total intents created, execution rate (%), most used condition type + - [ ] Fetch aggregate data from contract state or backend indexer + - [ ] Render area chart of TVL over time using a charting library (e.g., `recharts`) + +--- + +### Issue #FE-41: Internationalisation (i18n) Readiness +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `i18n`, `phase-3` +**Description:** Prepare the codebase for multi-language support, prioritising markets where Stellar is highly adopted (Nigeria, SE Asia, LatAm). +- **Tasks:** + - [ ] Audit all hardcoded English strings in components + - [ ] Extract strings to translation files (`/locales/en.json`) + - [ ] Set up `next-intl` or equivalent library + - [ ] Add locale switcher component to Navbar + +--- + +### Issue #FE-42: EpochSend SDK Export Layer +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `sdk`, `phase-3`, `developer` +**Description:** Package the core escrow hooks and Soroban helpers as a reusable SDK that third-party dApps can import. +- **Tasks:** + - [ ] Extract `useCreateEscrow`, `useExecuteEscrow`, `useRefundEscrow`, `useGetIntents` into a publishable package + - [ ] Create `packages/epochsend-sdk/` directory with its own `package.json` + - [ ] Write developer documentation with usage examples + - [ ] Publish to npm under `@epochsend/sdk` + +--- + +### Issue #FE-43: MoneyGram Off-Ramp Integration +**Status:** ๐Ÿ”œ FUTURE | **Priority:** LOW +**Labels:** `feature`, `phase-3`, `fiat` +**Description:** Allow recipients to cash out their received USDC via MoneyGram's Stellar integration. +- **Tasks:** + - [ ] Research MoneyGram's Stellar Circle API for off-ramp flows + - [ ] Add "Cash Out" button on executed intent cards for recipients + - [ ] Build off-ramp flow: initiate โ†’ KYC check โ†’ receive cash reference code + +--- + +### Issue #FE-44: Stellar Expert / Explorer Deep Links +**Status:** โŒ PENDING | **Priority:** LOW +**Labels:** `ux`, `transparency` +**Description:** Every on-chain transaction should have a direct link to a block explorer so users can independently verify. +- **Tasks:** + - [ ] Determine explorer URL pattern: `https://stellar.expert/explorer/testnet/tx/[hash]` + - [ ] Add "View on Stellar Expert" link to: intent creation confirmation, intent detail cards, transaction history items + - [ ] Switch explorer URL dynamically based on active network (Testnet vs Mainnet) + +--- + +## ๐Ÿ“Œ Issue Numbering Reference + +| Range | Module | +|---|---| +| FE-01 โ€“ FE-06 | Foundation & Configuration | +| FE-07 โ€“ FE-11 | Wallet & Blockchain Integration | +| FE-12 โ€“ FE-18 | Core Escrow โ€” Create Intent Flow | +| FE-19 โ€“ FE-24 | Active Intents Dashboard | +| FE-25 โ€“ FE-29 | Oracle & Backend Integration | +| FE-30 โ€“ FE-36 | UX Polish & Feedback | +| FE-37 โ€“ FE-44 | Advanced Features & Phase 2 | + +--- + +*EpochSend โ€” Programmable payments for the Stellar Network. Building in public.*