diff --git a/README.md b/README.md index 4134adc..4ada56f 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,8 @@ language, description, and tags to help you find what you need quickly. | [python/ai-wallet-reputation-nft](./python/ai-wallet-reputation-nft) | Python | AI-generated, soulbound reputation NFTs on BNB Chain | AI, NFT, Reputation | | [typescript/bnbchain-mcp](./typescript/bnbchain-mcp) | TypeScript | AI-powered blockchain assistant using Claude | AI, BSC, MCP | | [typescript/eliza-chatbot](./typescript/eliza-chatbot) | TypeScript | A chatbot example using Eliza plugin-bnb | AI, BSC, opBNB | - +| [typescript/safucard](./typescript/safucard) | Typescript | Safucard is a React-based decentralized application (dApp) that allows users to input their wallet address and receive a customized visual "SafuCard" scorecard based on their bep-20 token interactions. Users can optionally mint their SafuCard as an NFT to commemorate or showcase their on-chain profile. | BSC | +| [typescript/safucard](./typescript/safucard) | Typescript | Safucard is a React-based decentralized application (dApp) that allows users to input their wallet address and receive a customized visual "SafuCard" scorecard based on their bep-20 token interactions and other metrics. Users can optionally mint their SafuCard as an NFT to commemorate or showcase their on-chain profile. | BSC | More examples are coming soon—stay tuned for updates! ## How to Add a New Example diff --git a/typescript/safucard/README.md b/typescript/safucard/README.md new file mode 100644 index 0000000..fd5393c --- /dev/null +++ b/typescript/safucard/README.md @@ -0,0 +1,170 @@ +# Safucard + +This is a dApp project that showcases how to integrate Alchemy’s APIs to retrieve a wallet’s BEP-20 token data which includes the whale status, the first and most recent tokens held, and address age based on its first transaction on a Slick Card Design and is optionally minted as an NFT. + +--- + +## DEMO + +- Live Link: [SafuCard](https://scorecard-frontend-teal.vercel.app) +- Network: BNB Smart Chain Testnet +- Verified Contract: 0x2B20F646CEdB8D40f2a37358A3b712ced3D5B294 +- RPC URL: https://data-seed-prebsc-1-s1.binance.org:8545/ + +--- + +### TECH STACK/ PREREQUISITES + +- Node.js v18+ +- Express +- Hardhat +- React v19+ +- A wallet (e.g metamask) +- Wagmi +- AlchemySDK +- PinataSDK + +--- + +## How To Setup + +1. Clone The Repo + +```bash + git clone https://github.com/Domistro16/safucard.git + cd safucard +``` + +2. Install Dependencies + +```bash + cd SafuServer + npm install + cd ../Scorecard_NFT + npm install + cd ../scorecard-frontend + npm install + cd .. +``` + +3. Configure .env variables + + Copy .env.example variables to .env using the following command: + + ```bash + cp SafuServer/.env.example SafuServer/.env + cp Scorecard_NFT/.env.example Scorecard_NFT/.env + cp scorecard-frontend/.env.example scorecard-frontend/.env + ``` + + Then update your .env variables for each folder + + Scorecard_NFT: + + This includes your RPC_URL and your Deployer's Private key + + ```bash + API_URL= + DEPLOYER_KEY= + ``` + + SafuServer: + + This includes your Alchemy Key and your Pinata Gateway URL and Pinata JWT + + ```bash + ALCHEMY_KEY= + GATEWAY_URL= + JWT= + ``` + + scorecard-frontend: + + This includes the NFT Contract Address and the API Url to your Server + + ```bash + CONTRACT_ADDRESS=0x2B20F646CEdB8D40f2a37358A3b712ced3D5B294 + VITE_API_URL= + ``` + +4. Get Your Alchemy Key: + +- Go to https://www.alchemy.com/ +- Create an account +- Go to your Dashboard and create a new Project for BSC Testnet +- Copy Your API Key and update your .env variable + +5. Start the Express Server + + ```bash + cd SafuServer + npm run build + npm run dev + ``` + +6. Deploy/Use Already Deployed Testnet Contract + + You can choose to deply a new NFT contract: + + ```bash + cd Scorecard_NFT + npx hardhat compile + npx hardhat run ./scripts/deploy.ts + ``` + + Or Use the Already Deployed Contract: + + ```bash + CONTRACT_ADDRESS=0x2B20F646CEdB8D40f2a37358A3b712ced3D5B294 + ``` + +--- + +## How To Interact With Frontend + +1. Run the Development Server + ```bash + cd scorecard-frontend + npm run dev + ``` +2. Connect your Web3 wallet using the **Connect Wallet** button. +3. Enter your BNB wallet address in the input field. +4. Click **Search** to fetch scorecard data and generate your SafuCard. +5. Click **Download** or **Fullscreen** to preview or save the image. +6. Optionally, click **Mint NFT** to upload to IPFS and mint the card as an NFT. + +--- + +## Smart Contract + +- **Address:** `0x2B20F646CEdB8D40f2a37358A3b712ced3D5B294` +- **Function Used:** `mintNFT(tokenURI)` +- **Value Calculation:** Based on price feed (5 USD in native token) + +--- + +## 📡 API / Endpoints + +| Path | Method | Description | +| ------------------------- | ------ | --------------------------------------- | +| `/api/address/${address}` | GET | Returns the wallet's safu erc20 details | + +--- + +## Notes + +- Make sure your smart contract is deployed and funded. +- Backend must handle Pinata upload endpoints securely. +- This project uses Chainlink's price feeds for pricing NFT mint. + +--- + +## License + +This project is licensed under the MIT License. + +--- + +## Contact + +Email: desmondesih@gmail.com diff --git a/typescript/safucard/SafuServer b/typescript/safucard/SafuServer new file mode 160000 index 0000000..79cc190 --- /dev/null +++ b/typescript/safucard/SafuServer @@ -0,0 +1 @@ +Subproject commit 79cc190cb0f8be2149e23ad095e3f3ccb88feeaf diff --git a/typescript/safucard/Scorecard_NFT b/typescript/safucard/Scorecard_NFT new file mode 160000 index 0000000..3bbd484 --- /dev/null +++ b/typescript/safucard/Scorecard_NFT @@ -0,0 +1 @@ +Subproject commit 3bbd4842cc575f9479a0e27a4b56591e719371ec diff --git a/typescript/safucard/package-lock.json b/typescript/safucard/package-lock.json new file mode 100644 index 0000000..1421738 --- /dev/null +++ b/typescript/safucard/package-lock.json @@ -0,0 +1,13 @@ +{ + "name": "safucard", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "safucard", + "version": "1.0.0", + "license": "ISC" + } + } +} diff --git a/typescript/safucard/package.json b/typescript/safucard/package.json new file mode 100644 index 0000000..13951fb --- /dev/null +++ b/typescript/safucard/package.json @@ -0,0 +1,12 @@ +{ + "name": "safucard", + "version": "1.0.0", + "description": "Safucard is a React-based decentralized application (dApp) that allows users to input their wallet address and receive a customized visual \"SafuCard\" scorecard based on their bep-20 token interactions and other metrics. Users can optionally mint their SafuCard as an NFT to commemorate or showcase their on-chain profile.", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "keywords": [], + "author": "", + "license": "ISC" +} diff --git a/typescript/safucard/scorecard-frontend b/typescript/safucard/scorecard-frontend new file mode 160000 index 0000000..b4d830c --- /dev/null +++ b/typescript/safucard/scorecard-frontend @@ -0,0 +1 @@ +Subproject commit b4d830c755be3a2d18bad17e7c05092d4d97cf30 diff --git a/web/list.json b/web/list.json index e7be85f..0423804 100644 --- a/web/list.json +++ b/web/list.json @@ -160,5 +160,21 @@ "guide": "https://github.com/bnb-chain/example-hub/tree/main/typescript/4everland-hosting-mcp", "otherLink": "", "imgUrl": "https://cms-static.bnbchain.org/dcms/static/303d0c6a-af8f-4098-a2d0-a5b96ef964ba.png" + }, + { + "caseTitle": "Safucard", + "caseDesc": "This is a dApp project that showcases how to integrate Alchemy’s APIs to retrieve a wallet’s BEP-20 token data which includes the whale status, the first and most recent tokens held, and address age based on its first transaction which could be minted as an NFT.", + "tags": [ + "BSC" + ], + "github": "https://github.com/Domistro16/SafuCard", + "replit": "", + "video": { + "type": "youtube", + "link": "https://youtu.be/wsSTTIMe4jI" + }, + "guide": "", + "otherLink": "https://www.bnbchain.org/en/solutions", + "imgUrl": "https://cms-static.bnbchain.org/dcms/static/303d0c6a-af8f-4098-a2d0-a5b96ef964ba.png" } ]