diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..133f5b8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Tokenized Fractional RWA Marketplace Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 5733983..f11dfe4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Tokenized Fractional Real-World Assets (RWA) Marketplace +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + A full-stack decentralized application (dApp) built on the **Stellar Network** using **Soroban Smart Contracts**. This marketplace allows administrators to tokenize real-world assets into fractional shares for users to purchase. ## Walkthrough Demo diff --git a/backend/cache.js b/backend/cache.js index f6de4bc..2d21718 100644 --- a/backend/cache.js +++ b/backend/cache.js @@ -1,3 +1,6 @@ +// Copyright (c) 2026 Tokenized Fractional RWA Marketplace Contributors +// SPDX-License-Identifier: MIT + import Redis from 'ioredis'; const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379'; diff --git a/backend/index.js b/backend/index.js index 15e7664..fb6bbcc 100644 --- a/backend/index.js +++ b/backend/index.js @@ -1,3 +1,6 @@ +// Copyright (c) 2026 Tokenized Fractional RWA Marketplace Contributors +// SPDX-License-Identifier: MIT + import 'dotenv/config'; import { randomUUID } from 'crypto'; import express from 'express'; diff --git a/contracts/src/lib.rs b/contracts/src/lib.rs index 9b2a35f..86ade2c 100644 --- a/contracts/src/lib.rs +++ b/contracts/src/lib.rs @@ -1,3 +1,6 @@ +// Copyright (c) 2026 Tokenized Fractional RWA Marketplace Contributors +// SPDX-License-Identifier: MIT + #![no_std] use soroban_sdk::{ contract, contractevent, contractimpl, contracttype, token, Address, Bytes, BytesN, Env, Vec, diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..31a1041 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,151 @@ +# Frequently Asked Questions & Troubleshooting Guide + +This guide compiles common issues encountered by developers and users of the Tokenized Fractional Real-World Assets (RWA) Marketplace, along with step-by-step instructions to resolve them. + +--- + +## Table of Contents +1. [Freighter Wallet & Connection Issues](#1-freighter-wallet--connection-issues) +2. [Transaction & Smart Contract Failures](#2-transaction--smart-contract-failures) +3. [Network & Configuration Problems](#3-network--configuration-problems) +4. [Backend API & Metadata Issues](#4-backend-api--metadata-issues) +5. [Advanced Operations (Vesting & Dividends)](#5-advanced-operations-vesting--dividends) + +--- + +## 1. Freighter Wallet & Connection Issues + +### Issue: Freighter Wallet Not Detected or Failed to Connect +* **Symptoms**: + * The frontend console displays: `[WalletStore] connect failed: Error` + * UI shows an alert: `"Failed to connect Freighter wallet. Ensure the extension is installed and unlocked."` + * Clicking "Connect Freighter" does nothing or displays a pending spinner infinitely. +* **Root Cause**: + * The Freighter browser extension is not installed. + * The Freighter extension is locked (requires entering password). + * The dApp does not have permission to connect to the extension. + * The user is using an unsupported browser or mobile device without Freighter support. +* **Solution**: + 1. **Install Freighter**: Ensure the extension is installed. Get it from the official [Freighter Wallet website](https://www.freighter.app/). + 2. **Unlock the Wallet**: Click the Freighter extension icon in your browser toolbar and enter your password. + 3. **Check Connection Settings**: Open Freighter -> Settings -> Connected Sites, and verify that `http://localhost:5173` is permitted. + 4. **Reload**: Refresh the page (`F5` or `Ctrl+R`) and try clicking the **Connect Freighter** button again. + +### Issue: Freighter Transaction Signing Failed / Rejected +* **Symptoms**: + * Console displays: `[useSorobanWrite] Error executing tx buy_shares: Error: Freighter transaction signing failed` + * UI displays: `Transaction buy_shares failed` or `Freighter transaction signing failed` +* **Root Cause**: + * The user rejected the transaction popup inside the Freighter extension. + * The extension timed out before the user signed the transaction. +* **Solution**: + 1. Open the Freighter popup and review the transaction parameters. + 2. Click **Sign** / **Approve** instead of Reject. + 3. If no popup appears, check if your browser blocked a popup or if the Freighter extension icon is flashing in the extension bar. + +--- + +## 2. Transaction & Smart Contract Failures + +### Issue: Transaction Failed — Check your token balance +* **Symptoms**: + * Buying shares results in a red alert: `"Transaction failed. Check your token balance and try again."` +* **Root Cause**: + * The buyer wallet does not have a sufficient balance of the required payment token (default Testnet token: `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC`). + * The buyer wallet does not have enough XLM to pay for transaction fees. +* **Solution**: + 1. **Check XLM balance**: Go to Freighter and ensure you have at least 2-5 XLM to cover base network reserves and gas/transaction fees. If on Testnet, you can fund your address via the [Stellar Laboratory Friendbot](https://laboratory.stellar.org/#account-creator?network=testnet). + 2. **Check Payment Token balance**: Verify that your Freighter account holds the configured payment token. If you need to mint/receive tokens, contact the admin or use the Stellar Asset Client to mint tokens to your address. + +### Issue: "Not enough shares available" Error +* **Symptoms**: + * An alert box pops up: `"Not enough shares available."` +* **Root Cause**: + * You are trying to buy more shares than the contract currently has left in its available pool (`AvailableShares`). +* **Solution**: + 1. Reduce your purchase quantity in the buy input to be less than or equal to the remaining available shares displayed in the marketplace. + 2. If you are the Administrator, you can increase the available share supply by invoking the `set_total_shares` function (or via the Admin panel). + +### Issue: "Marketplace is currently paused" Error +* **Symptoms**: + * Buying shares results in: `"Marketplace is currently paused. Try again later."` +* **Root Cause**: + * The smart contract is currently in a paused state. The admin has called the `pause` method on the contract. +* **Solution**: + * Wait for the administrator to unpause the marketplace. + * If you are the Administrator, invoke the `unpause` method on the contract using the CLI or the Admin interface: + ```bash + soroban contract invoke --id --source admin --network testnet -- unpause + ``` + +--- + +## 3. Network & Configuration Problems + +### Issue: "Set VITE_CONTRACT_ID in frontend/.env" Alert +* **Symptoms**: + * The top of the page displays a warning: `"Set VITE_CONTRACT_ID in frontend/.env to connect to a deployed contract."` +* **Root Cause**: + * The frontend development server is running, but the `frontend/.env` file is missing or `VITE_CONTRACT_ID` is set to the default placeholder `'C...'`. +* **Solution**: + 1. Ensure you have deployed the smart contract using `soroban contract deploy`. + 2. Copy the resulting contract ID (e.g., `CAS3...`). + 3. Create/edit `frontend/.env` and insert: + ```env + VITE_CONTRACT_ID=YOUR_COPIED_CONTRACT_ID + VITE_RPC_URL=https://soroban-testnet.stellar.org:443 + VITE_NETWORK_PASSPHRASE="Test SDF Network ; September 2015" + VITE_API_URL=http://localhost:3001 + ``` + 4. Restart your Vite development server (`npm run dev`). + +### Issue: RPC Timeout / Connection Mismatch +* **Symptoms**: + * Simulation fails with RPC errors or timeouts. + * Unable to fetch initial share balance or available shares. +* **Root Cause**: + * The RPC server (`https://soroban-testnet.stellar.org:443`) is temporarily down or rate-limited. + * Your Freighter wallet network settings are set to **Mainnet** instead of **Testnet**. +* **Solution**: + 1. Open Freighter, click the network selection dropdown at the top, and ensure **Testnet** is selected. + 2. Verify that your `frontend/.env` has the correct `VITE_NETWORK_PASSPHRASE` matching Freighter's network settings. + 3. Check the [Stellar Status Page](https://status.stellar.org/) to see if Testnet is undergoing maintenance. + +--- + +## 4. Backend API & Metadata Issues + +### Issue: "VITE_API_URL not reachable" or Missing Asset Grid +* **Symptoms**: + * "Available Assets" section shows a network error, is empty, or spins indefinitely. + * Browser console displays CORS errors or `fetch failed` to `http://localhost:3001`. +* **Root Cause**: + * The off-chain metadata Express API is not running. + * The frontend `VITE_API_URL` environment variable points to the wrong port. + * The backend `.env` has incorrect `CORS_ORIGINS` settings. +* **Solution**: + 1. **Start the backend**: Navigate to `/backend` and run `npm run dev`. Verify it outputs `Server running on port 3001`. + 2. **Verify CORS**: In `backend/.env`, ensure `CORS_ORIGINS` includes `http://localhost:5173`. + 3. **Check Frontend Config**: Confirm `frontend/.env` contains `VITE_API_URL=http://localhost:3001`. + +--- + +## 5. Advanced Operations (Vesting & Dividends) + +### Issue: Vested Shares "No vested shares available to claim" +* **Symptoms**: + * Claiming vested shares panics or shows a transaction execution error. +* **Root Cause**: + * The current ledger timestamp is prior to the vesting schedule's cliff or has not reached a point where new shares can be unlocked. +* **Solution**: + * Verify the vesting duration on your schedule. You can check the current claimable shares using the `get_claimable_vested_shares` method before submitting a claim transaction. + +### Issue: "Dividend amount must be positive" or "No holders registered" +* **Symptoms**: + * Admin dividend distribution transactions fail. +* **Root Cause**: + * Admin specified a `total_amount` of zero or negative. + * No users have purchased shares yet, so the contract's holders list is empty. +* **Solution**: + 1. Ensure the distribution amount is greater than zero. + 2. Verify that at least one user has successfully purchased shares (`buy_shares`) before attempting to distribute dividends. diff --git a/frontend/src/main.jsx b/frontend/src/main.jsx index b4d4bc2..876aaf1 100644 --- a/frontend/src/main.jsx +++ b/frontend/src/main.jsx @@ -1,3 +1,6 @@ +// Copyright (c) 2026 Tokenized Fractional RWA Marketplace Contributors +// SPDX-License-Identifier: MIT + import React from 'react'; import ReactDOM from 'react-dom/client'; import { BrowserRouter } from 'react-router-dom';