Skip to content

chore: update production readiness roadmap, refresh contract details … #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kingscliq merged 1 commit into from
Apr 22, 2026
Merged

chore: update production readiness roadmap, refresh contract details … #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 37 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,17 +155,18 @@ You likely deployed an old Wasm artifact. Re-run:
This project fulfills all requirements for the FundStar Level 2 bounty.

### ✅ Submission Checklist
- [x] **3 error types handled**: `CampaignNotFound`, `GoalNotReached`, `InsufficientFunds` (Token-level).
- [x] **Contract deployed on testnet**: Live at `CAOAJBZA5JI5QSF3LY2QCVGHDIFQW5PQ7KBIE2JPUY6NBVWZYHDW4VCQ`.
- [x] **3 error cases handled**: `CampaignNotFound`, `GoalNotReached`, and token-level insufficient-balance failures surfaced through transaction simulation/submission.
- [x] **Contract deployed on testnet**: Live at `CDZIHKUBUJ3F6W6E2NRWP5JZXNBZP4O4PASBRQGW4FODFWK6I3PTDWE7`.
- [x] **Contract called from the frontend**: Integrated using `stellar-sdk` and signature-based transactions.
- [x] **Transaction status visible**: Real-time toast notifications for preparation, signing, submission, and finalization.
- [x] **Minimum 2+ meaningful commits**: Multiple logical commits covering contract logic, frontend integration, and multi-wallet support.
- [x] **Multi-wallet support**: Integrated both **Freighter** and **Albedo** wallet providers.
- [x] **Multi-wallet support**: Wallet selector includes both **Freighter** and **Albedo**, with Freighter wired as the primary signing flow.
- [x] **Real-time activity feed**: Implemented `getCampaignEvents` to stream contract events for live contribution updates.

### 📜 Contract Information
- **Contract ID**: `CAOAJBZA5JI5QSF3LY2QCVGHDIFQW5PQ7KBIE2JPUY6NBVWZYHDW4VCQ`
- **Deployment Hash**: [`87dca0cd31c52fff10a00e4f7e32bd493de6f231bd411bdb6edae744d61e3dee`](https://stellar.expert/explorer/testnet/tx/87dca0cd31c52fff10a00e4f7e32bd493de6f231bd411bdb6edae744d61e3dee)
- **Contract ID**: `CDZIHKUBUJ3F6W6E2NRWP5JZXNBZP4O4PASBRQGW4FODFWK6I3PTDWE7`
- **Reward Token (STAR):** `CBERWLOGNDQGNCAJIF44D46HQ3PP5LAKO3FXIGZQJODRS3RCC7CZKTRD`
- **Configured From:** `frontend/.env`
- **Network**: Stellar Testnet
- **Native XLM SAC**: `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC`
- **RPC Endpoint**: `https://soroban-testnet.stellar.org`
Expand Down Expand Up @@ -194,14 +195,14 @@ Proof of successful wallet connection (Freighter) and account authorization.
![Wallet Connected](./screenshots/reight-wallet-connected.png)

#### 6. Smart Contract Test Output
Verified results showing 14/14 automated tests passing in the Rust environment.
Verified results showing the Rust contract test suite passing in the local development environment.
![Smart Contract Test Output](./screenshots/test-screenshot.png)

### 🚀 Key Features
- **Zero-Lag Caching**: In-memory caching for instantaneous navigation and zero-lag transition between pages.
- **High-Fidelity Skeletons**: Standardized skeleton loaders for a smooth, professional loading experience.
- **Dynamic Activity Feed**: Real-time updates for on-chain contributions using contract events.
- **Smart Wallet Routing**: Automatic detection and choice between Freighter and Albedo.
- **Smart Wallet Routing**: Wallet chooser supports both Freighter and Albedo entry paths, with Freighter used for the main signed transaction flow.
- **Creator Controls**: Role-based access for campaign creators to withdraw funds once goals are reached.

## 🟠 Level 3 - Orange Belt Submission
Expand All @@ -210,10 +211,10 @@ FundStar has been upgraded to meet the high standards of the Level 3 (Orange Bel

### ✅ Level 3 Requirements
- [x] **Mini-dApp fully functional**: Deployed and tested on Stellar Testnet.
- [x] **Minimum 3 tests passing**: 14 comprehensive contract tests passing (see below).
- [x] **Minimum 3 tests passing**: 15 comprehensive contract tests passing (see below).
- [x] **Loading states and progress indicators**: Implemented high-fidelity **Skeleton Loaders** for all data grids and detail views.
- [x] **Basic caching implementation**: Integrated a **Zero-Lag Caching Layer** in the frontend for instantaneous navigation.
- [x] **README complete**: All documentation, test results, and demo placeholders included.
- [x] **README complete**: Documentation, test results, CI proof, and mobile screenshots included.

### 🎥 Demo Video
[Watch the 1-minute demo video](https://www.loom.com/share/695d03e93cc743b8b52e1d4bb752740c)
Expand Down Expand Up @@ -256,12 +257,35 @@ FundStar has been upgraded with advanced inter-contract patterns and production-
- [x] **Advanced event streaming**: Real-time contribution tracking via on-chain event indexing.

### ⛓️ Advanced Contract Details
- **Main Contract:** `CAOAJBZA5JI5QSF3LY2QCVGHDIFQW5PQ7KBIE2JPUY6NBVWZYHDW4VCQ`
- **Reward Token (STAR):** `ADD_TOKEN_ADDRESS_HERE`
- **Inter-Contract Minting TX:** `ADD_TX_HASH_HERE`
- **Main Contract:** `CDZIHKUBUJ3F6W6E2NRWP5JZXNBZP4O4PASBRQGW4FODFWK6I3PTDWE7`
- **Reward Token (STAR):** `CBERWLOGNDQGNCAJIF44D46HQ3PP5LAKO3FXIGZQJODRS3RCC7CZKTRD`
- **Native XLM SAC:** `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC`
- **Deployment Source of Truth:** `frontend/.env`
- **Reward Minting Proof:** Verified by the `test_reward_minting_on_funding` contract test and the frontend STAR balance integration.

### 📱 Mobile UI Proof
![Mobile Responsive View](./screenshots/mobile-responsive.png)

These mobile screenshots demonstrate that FundStar remains usable across key flows on a narrow viewport:

#### 1. Home Page
Responsive hero layout, CTA stacking, and mobile-safe stats card.
![Mobile Home Page](./screenshots/mobile-home.png)

#### 2. Create Campaign Flow
Mobile-friendly form spacing and adaptive input layout for campaign creation.
![Mobile Create Campaign](./screenshots/mobile-create-campaign.png)

#### 3. Wallet Selector Modal
Responsive wallet connection modal with touch-friendly actions.
![Mobile Wallet Modal](./screenshots/mobile-wallet-modal.png)

#### 4. Active Campaigns View
Scrollable card layout and campaign browsing optimized for smaller screens.
![Mobile Active Campaigns](./screenshots/mobile-active-campaigns.png)

#### 5. Campaign Detail View (Dark Mode)
Responsive campaign detail layout showing that the mobile experience also holds up in dark theme.
![Mobile Campaign Detail Dark Mode](./screenshots/mobile-campaign-detail-dark.png)

### 🚀 Key Features (Level 4)
- **Loyalty Reward System**: Automated inter-contract minting of STAR tokens for every backer.
Expand Down
115 changes: 75 additions & 40 deletions Recommendations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,104 @@
# 🚀 Production Readiness & Security Roadmap
# 🚀 FundStar Production Readiness & Security Roadmap

This document outlines the "Senior-level" improvements required to transition FundStar from a functional prototype to a mainnet-ready financial ecosystem. These are structured as GitHub-ready issues.
> A structured roadmap for moving FundStar from a functional prototype to a mainnet-ready financial ecosystem.
>
> The recommendations below preserve the original scope, but present it in a format that is easier to scan in GitHub, discuss in issues, and turn into implementation work.

---
## At a Glance

## 🔒 Security & Access Control
| ID | Area | Recommendation | Impact |
| --- | --- | --- | --- |
| #1 | Security & Access Control | Protect initialization from front-running | Critical |
| #2 | Security & Access Control | Implement an emergency circuit breaker | High |
| #3 | State & Lifecycle Management | Add automated rent bumping for storage persistence | High |
| #4 | State & Lifecycle Management | Support contract upgradeability via WASM hash update | Medium |
| #5 | Governance & Logic | Move admin control to multisig or DAO-style governance | Medium |
| #6 | Governance & Logic | Add price oracle support for reward calculation | Low |
| #7 | Observability & Performance | Expand event indexing for better external visibility | Medium |
| #8 | Observability & Performance | Introduce off-chain indexing and caching | High |

## 1. 🔒 Security & Access Control

### Issue #1: Protect Initialization from Front-Running
- **Problem**: The `init` functions are public and callable by anyone. A bot could see the contract deployment and call `init` before the deployer, seizing admin control.
- **Solution**: Implement a "Deployer Pattern" where the contract is initialized in the same transaction as deployment, or check that the caller is the contract's official creator.
- **Impact**: **Critical**. Prevents hostile takeovers of the contract.

| Field | Details |
| --- | --- |
| Problem | The `init` functions are public and callable by anyone. A bot could see the contract deployment and call `init` before the deployer, seizing admin control. |
| Solution | Implement a "Deployer Pattern" where the contract is initialized in the same transaction as deployment, or check that the caller is the contract's official creator. |
| Impact | **Critical**. Prevents hostile takeovers of the contract. |

### Issue #2: Implement an Emergency "Circuit Breaker"
- **Problem**: If an exploit is discovered in the funding or withdrawal logic, there is currently no way to stop transactions.
- **Solution**: Add a `is_paused` state variable and a `toggle_pause` function (Admin only). Ensure `fund_campaign` and `withdraw_funds` check this flag.
- **Impact**: **High**. Essential for damage control during a security incident.

---
| Field | Details |
| --- | --- |
| Problem | If an exploit is discovered in the funding or withdrawal logic, there is currently no way to stop transactions. |
| Solution | Add an `is_paused` state variable and a `toggle_pause` function (admin only). Ensure `fund_campaign` and `withdraw_funds` check this flag. |
| Impact | **High**. Essential for damage control during a security incident. |

## 2. 🏗️ State & Lifecycle Management

### Workstream 3: Campaign Management & Investor Protection

## 🏗️ State & Lifecycle Management
A production-grade DApp needs a graceful exit path for failed or disputed campaigns, not just creation and funding flows.

### 3. Campaign Management & Investor Protection
While the current system allows for creation and funding, a production-grade DApp requires a graceful "exit" strategy for failed or disputed campaigns.
| Recommendation | Details |
| --- | --- |
| Campaign Cancellation | Implement a `cancel_campaign` function restricted to the creator. This should change the campaign state to `Cancelled`, preventing further funding. |
| On-Chain Refund System | If a campaign is cancelled or fails to hit its goal by the deadline, a `claim_refund` function should be available. This requires tracking individual contributions in a `Map` or `Persistent` storage to ensure each user gets back exactly what they sent. |
| Admin Circuit Breaker | For extreme cases such as security issues, a contract admin should have the power to pause all funding and withdrawals globally. |

* **Campaign Cancellation**: Implement a `cancel_campaign` function restricted to the creator. This should change the campaign state to `Cancelled`, preventing further funding.
* **On-Chain Refund System**: If a campaign is cancelled or fails to hit its goal by the deadline, a `claim_refund` function should be available. This is more complex than it sounds, as it requires tracking individual contributions in a `Map` or `Persistent` storage to ensure each user gets back exactly what they sent.
* **Admin Circuit Breaker**: For extreme cases (security issues), a contract admin should have the power to pause all funding and withdrawals globally.
### Workstream 4: Storage & Performance (Version 2)

### 4. Storage & Performance (Version 2)
As the number of campaigns grows, the current `get_all_campaigns` loop will become expensive in terms of gas (XLM).

### Issue #3: Automated Rent Bumping (Storage Persistence)
- **Problem**: Soroban data has an expiration. If a campaign is long-lived and nobody interacts with it, its data will be archived, breaking the contract.
- **Solution**: Integrate `env.storage().persistent().extend_ttl()` inside the `fund_campaign` function to automatically extend the campaign's life every time it is interacted with.
- **Impact**: **High**. Ensures long-term data availability.

| Field | Details |
| --- | --- |
| Problem | Soroban data has an expiration. If a campaign is long-lived and nobody interacts with it, its data will be archived, breaking the contract. |
| Solution | Integrate `env.storage().persistent().extend_ttl()` inside the `fund_campaign` function to automatically extend the campaign's life every time it is interacted with. |
| Impact | **High**. Ensures long-term data availability. |

### Issue #4: Contract Upgradeability (WASM Hash Update)
- **Problem**: The contract address is currently tied to a specific version of the code. Bug fixes require a new address, which orphans existing data.
- **Solution**: Implement the `upgrade` function pattern. Allow an authorized admin to update the WASM code hash of the contract without changing the Contract ID.
- **Impact**: **Medium**. Allows for maintenance and bug fixes post-deployment.

---
| Field | Details |
| --- | --- |
| Problem | The contract address is currently tied to a specific version of the code. Bug fixes require a new address, which orphans existing data. |
| Solution | Implement the `upgrade` function pattern. Allow an authorized admin to update the WASM code hash of the contract without changing the Contract ID. |
| Impact | **Medium**. Allows for maintenance and bug fixes post-deployment. |

## ⚖️ Governance & Logic
## 3. ⚖️ Governance & Logic

### Issue #5: Decentralized Admin (Multisig)
- **Problem**: A single private key controls the entire ecosystem. If that key is lost or stolen, the project is dead.
- **Solution**: Transition the `admin` address to a Stellar **Multisig** account or a simple DAO contract.
- **Impact**: **Medium**. Removes the "Single Point of Failure."

| Field | Details |
| --- | --- |
| Problem | A single private key controls the entire ecosystem. If that key is lost or stolen, the project is dead. |
| Solution | Transition the `admin` address to a Stellar **Multisig** account or a simple DAO contract. |
| Impact | **Medium**. Removes the "Single Point of Failure." |

### Issue #6: Price Oracle Integration for Rewards
- **Problem**: The 10% reward is currently fixed. If the value of STAR vs XLM fluctuates wildly, the reward might become economically unsustainable.
- **Solution**: Integrate a price oracle (e.g., Pyth or Switchboard) to calculate the `reward_amount` based on real-time market value.
- **Impact**: **Low**. Improves the economic stability of the token.

---
| Field | Details |
| --- | --- |
| Problem | The 10% reward is currently fixed. If the value of STAR vs XLM fluctuates wildly, the reward might become economically unsustainable. |
| Solution | Integrate a price oracle such as **Pyth** or **Switchboard** to calculate the `reward_amount` based on real-time market value. |
| Impact | **Low**. Improves the economic stability of the token. |

## 📊 Observability & Performance
## 4. 📊 Observability & Performance

### Issue #7: Detailed Event Indexing
- **Problem**: Current events are basic. It's hard for external indexers to build a full history of the project.
- **Solution**: Expand events to include `campaign_updated`, `admin_changed`, and `reward_minted` with indexed topics for easier tracking by tools like Mercury or StellarExpert.
- **Impact**: **Medium**. Improves frontend transparency and data discoverability.

| Field | Details |
| --- | --- |
| Problem | Current events are basic. It's hard for external indexers to build a full history of the project. |
| Solution | Expand events to include `campaign_updated`, `admin_changed`, and `reward_minted` with indexed topics for easier tracking by tools like Mercury or StellarExpert. |
| Impact | **Medium**. Improves frontend transparency and data discoverability. |

### Issue #8: Off-Chain Indexing & Data Caching (Indexer Pattern)
- **Problem**: Querying the blockchain directly for large lists of campaigns is slow and gas-inefficient as the project scales. The frontend "wait time" increases with every new campaign.
- **Solution**: Implement an **Indexer** (using tools like **Mercury** or a custom Node.js service). The indexer listens for `campaign_created` and `fund_received` events and syncs them to a traditional database (e.g., PostgreSQL or Supabase). The frontend then queries this DB for lightning-fast list views.
- **Impact**: **High**. Drastically improves User Experience (UX) and reduces unnecessary load on the Stellar RPC.

| Field | Details |
| --- | --- |
| Problem | Querying the blockchain directly for large lists of campaigns is slow and gas-inefficient as the project scales. The frontend wait time increases with every new campaign. |
| Solution | Implement an **Indexer** using tools like **Mercury** or a custom Node.js service. The indexer listens for `campaign_created` and `fund_received` events and syncs them to a traditional database such as PostgreSQL or Supabase. The frontend then queries this database for lightning-fast list views. |
| Impact | **High**. Drastically improves user experience and reduces unnecessary load on the Stellar RPC. |
Loading
Loading