From 90df2ccb3ddb619051dbbbf405a8f06987b097f8 Mon Sep 17 00:00:00 2001 From: "Sara Jane (SJ)" <127313669+Ganainmtech@users.noreply.github.com> Date: Thu, 22 Jan 2026 10:13:59 +0000 Subject: [PATCH] Update README.md --- README.md | 207 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 136 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 93f4f50..f03e09f 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,186 @@ # 🧱 RWA Tokenization Template (Algorand) -A **beginner-friendly, end-to-end template** for tokenizing real-world assets (RWAs) on **Algorand testnet** using **Algorand Standard Assets (ASAs)**. +A beginner-friendly, end-to-end template for tokenizing real-world assets (RWAs) on Algorand testnet using Algorand Standard Assets (ASAs). -This repository is designed for: -- Founders exploring **RWA proofs-of-concept** +**This repository is designed for:** +- Founders exploring RWA proofs-of-concept - Builders new to Algorand - Hackathons, demos, workshops, and early product experiments -No prior blockchain or smart contract experience required. By the end, you’ll have a working tokenized asset with a real Algorand Asset ID. +No prior blockchain or smart contract experience required. By the end, you'll have a working tokenized asset with a real Algorand Asset ID. + +--- ## ✨ What This Template Gives You -- ✅ Full-stack Algorand project (frontend + backend) -- ✅ Simple ASA creation flow for tokenizing assets -- ✅ Wallet connect (Pera, Defly, Exodus, Lute) -- ✅ Localnet and Testnet support +- ✅ Full-stack Algorand project +- ✅ Simple ASA creation and transferring flow for assets +- ✅ Web2 & Web3-style logins +- ✅ TestNet-ready setup - ✅ One-command setup using GitHub Codespaces -- ✅ Clean foundation you can extend with compliance, metadata, or DeFi +- ✅ Hosting capability with Vercel + Analytics enabled -## 🧠 What “RWA Tokenization” Means Here +--- + +## 🧠 What "RWA Tokenization" Means Here This template focuses on the **on-chain token layer** of RWA tokenization: - Each real-world asset is represented by an **Algorand Standard Asset (ASA)** - Ownership, supply, and transfers are handled on-chain -- The real-world linkage (documents, custody, legal structure) lives **off-chain** +- The real-world linkage (documents, custody, legal structure) lives off-chain -> ⚠️ This is a **technical proof-of-concept template**, not legal or financial advice. +> ⚠️ This is a technical proof-of-concept template, not legal or financial advice. + +--- ## 🚀 Getting Started (5 Minutes) ### Option 1: GitHub Codespaces (Recommended) -This is the **fastest and easiest** way to run the project. +This is the fastest and easiest way to run the project. -### 1️⃣ Fork the repository +#### 1️⃣ Fork the repository Click **Fork** (top-right of this page) to create your own copy. https://github.com/user-attachments/assets/92e746e1-3143-4769-8a5a-1339e4bd7a14 -### 2️⃣ Open in Codespaces +#### 2️⃣ Open in Codespaces 1. Go to your forked repository 2. Click **Code → Codespaces → Create codespace** -3. Wait for the environment to start +3. Wait for the environment to load and enter the workspace -> When the Codespace loads, you may see an **“Open Workspace?”** popup in the bottom-right — click **Yes**. +> When the Codespace loads, you may see an **"Open Workspace?"** popup in the bottom-right — click **Yes**. Or manually enter it like below: -image -### 3️⃣ Configure the frontend environment +Codespace workspace setup -1. Navigate to the `frontend` folder -2. Find the file: -`.env.template` -3. Copy **all** of its contents -4. Create a new file called: -`.env` -5. Paste the contents into `.env` and save - -### 4️⃣ Run the setup script +#### 3️⃣ Run the setup script In the Codespaces terminal, run: ```bash bash setup.sh ``` + This script will: - Install dependencies +- Automatically create required environment files - Launch the frontend automatically 👉 When it finishes, a web app link will open automatically in Codespaces. -## Pro Tip! -> GitHub Codespaces includes 60 free hours per month. -> Commit your changes regularly to avoid losing progress. +> ⚠️ You do not need to manually create `.env` files for the frontend. -https://github.com/user-attachments/assets/dd452ea1-3070-4718-af34-bea978e208ab +--- + +## 🔐 Required Frontend Configuration (Web3Auth) + +To enable email / social (Web2-style) login, you must configure Web3Auth. + +### Steps + +1. Go to the [Web3Auth Dashboard](https://dashboard.web3auth.io/) +2. Create a new project +3. Copy your **Client ID** + +### Where to paste it + +Open the file: + +``` +frontend/.env +``` + +Add (or update) the following value: + +```env +VITE_WEB3AUTH_CLIENT_ID=YOUR_CLIENT_ID_HERE +``` + +Save the file and restart the frontend if it's already running. + +> 🔑 **This is the only required manual environment step.** + +--- + +## 🖼 Optional: NFT Minting (IPFS / Pinata) + +NFT minting and metadata uploads are handled by a small backend server. + +> ⚠️ **ONLY required if you want NFT / metadata minting** +> If you're just creating and transferring ASAs, you can skip this section. + +### Backend path + +``` +projects/TokenizeRWATemplate-contracts/NFT_mint_server +``` + +### Steps + +1. Go to https://app.pinata.cloud/developers/api-keys +2. Create a new API key +3. Copy the **JWT token** + +### Where to paste it + +Open: + +``` +projects/TokenizeRWATemplate-contracts/NFT_mint_server/.env +``` + +Add: + +```env +PINATA_JWT=YOUR_PINATA_JWT_HERE +``` + +Save the file. + +--- ## 🌐 Running the Frontend Again -After running setup.sh once, you have two options whenever you open your codespace if you don't want to run the setup script again: +After running `setup.sh` once, you have two options whenever you open your Codespace if you don't want to run the setup script again: ### Option A: Terminal + ```bash cd frontend -``` -then, -```bash npm run dev ``` ### Option B: GitHub UI + You can also start the frontend directly using the GitHub Codespaces UI, which is useful for demos and workshops. +--- + +## 🧠 Final Note (Important for Learners) + +- ✅ Frontend setup is fully automated +- ✅ Web3Auth Client ID is **required** +- ✅ Pinata is **optional** + +**If something isn't working, it's almost always because of:** +- A missing Web3Auth Client ID +- No TestNet ALGO or USDC + +--- + ## 🪙 Tokenization Flow (High Level) -This template guides you through the core steps of tokenizing a real-world asset on Algorand using **Algorand Standard Assets (ASAs)**. +This template guides you through the core steps of tokenizing a real-world asset on Algorand using Algorand Standard Assets (ASAs). ### Basic Flow -1. **Connect a wallet** - Connect an Algorand wallet (e.g. Pera, Defly, Lute) to interact with the app. +1. **Connect with Algorand** + Use Pera, Defly, Lute, or Web3Auth to interact with the app. 2. **Define your asset parameters** Choose the asset name, unit name, total supply, decimals, and optional metadata. @@ -112,60 +189,48 @@ This template guides you through the core steps of tokenizing a real-world asset The asset is created on-chain and represents your real-world asset digitally. 4. **Receive an Asset ID** - Algorand assigns a unique **Asset ID**, which becomes the on-chain identifier for your tokenized asset. + Algorand assigns a unique Asset ID, which becomes the on-chain identifier for your tokenized asset. 5. **Use or extend the token as your RWA representation** The ASA can now be transferred, held, integrated into apps, or extended with additional logic. ### Advanced Asset Controls (Optional) -ASAs support **advanced management features** commonly used in RWA and compliance-focused setups: +ASAs support advanced management features commonly used in RWA and compliance-focused setups: -- **Manager** - Can update asset configuration or rotate control roles (useful for governance or upgrades). +| Role | Description | +|------|-------------| +| **Manager** | Can modify asset configuration | +| **Reserve** | Holds non-circulating supply | +| **Freeze** | Can freeze/unfreeze accounts | +| **Clawback** | Can revoke assets from accounts | -- **Reserve** - Holds uncirculated supply, enabling controlled distribution or staged issuance. +These controls are optional and depend on your use case and trust model. -- **Freeze** - Can freeze transfers for specific accounts (e.g. during compliance checks or disputes). - -- **Clawback** - Allows reclaiming tokens from accounts if required (often used for regulatory or recovery scenarios). - -> These controls are optional and can be enabled or disabled depending on your use case and trust model. - -### What This Enables - -This tokenization flow forms the foundation for: - -- Fractional ownership of real-world assets -- On-chain asset registries -- Access or entitlement tokens -- Membership or investment models -- Compliance-aware or permissioned asset designs - -This template focuses on giving you a **clean, flexible starting point** — you decide how advanced or permissioned your tokenization POC needs to be. +--- ## 🧪 Disclaimer -This repository is provided for **educational and experimental purposes only**. -It does **not** constitute legal, financial, or investment advice. +> This repository is provided for **educational and experimental purposes only**. +> It does not constitute legal, financial, or investment advice. + +--- + +## 📹 Video Guides Below are videos on: -- How to connect to Testnet on Pera +- How to connect to TestNet on Pera - How to use the Algo Dispenser - How to use the USDC Dispenser -**How to connect to testnet on Pera Wallet** +### How to connect to TestNet on Pera Wallet https://github.com/user-attachments/assets/31df8135-119e-4529-9539-4943de979719 -**How to use the Algo Dispenser** +### How to use the Algo Dispenser https://github.com/user-attachments/assets/643cae10-4673-4b68-8e95-4a3f16fbba60 -**How to use the USDC Dispenser** +### How to use the USDC Dispenser https://github.com/user-attachments/assets/a76e90fa-97f4-44f8-a7e8-a8ccabd24398 -