From 51d85b9a445b1235fdb95b1d1cbe234b128285a2 Mon Sep 17 00:00:00 2001 From: iTinkerBell Date: Thu, 13 Nov 2025 15:38:18 -0500 Subject: [PATCH] Badging NFT Integration Draft --- Badging System/Badging NFT Workflow.md | 109 +++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 Badging System/Badging NFT Workflow.md diff --git a/Badging System/Badging NFT Workflow.md b/Badging System/Badging NFT Workflow.md new file mode 100644 index 0000000..1fc825d --- /dev/null +++ b/Badging System/Badging NFT Workflow.md @@ -0,0 +1,109 @@ +# Boost Badging System – NFT Integration + +## Overview + +This document outlines a Solana-based badging flow that mints directly to recipient wallets or stores badges in the token contract (when no wallet is provided), supports email-triggered claims, and records all badge lifecycle events. The token contract includes built-in vault functionality for storing unclaimed badges. The implementation window is estimated at three weeks. + +```mermaid +sequenceDiagram + autonumber + participant FE as Frontend + participant IPFS as IPFS Service + participant DB as Database + participant Admin as Admin Wallet + participant Sol as Token Contract
(with vault functionality) + participant Mail as Mailing Service + participant User as User (with email) + participant Claim as Claim Service + participant Wallet as User Wallet + + FE->>IPFS: Submit user + badge payload + IPFS-->>FE: Return URI + CID metadata + FE->>DB: Persist issuance record (user data, URI, flags) + Admin->>FE: Initiate mint (via frontend with admin wallet) + FE->>Admin: Request transaction signing (token IDs, URI, wallet) + Admin->>FE: Sign mint or batch mint transaction + FE->>Sol: Send mint transaction + Sol-->>Wallet: Mint badge to user wallet (if provided) + Sol-->>Sol: Store badge in contract (no wallet address) + Sol-->>DB: Emit confirmation event (tx signatures) + + Sol-->>Mail: Trigger notification payload (wallet vs stored in contract) + Mail-->>User: Send email (direct badge info or claim instructions) + + Note over Claim,DB: Claim service fetches record using URI
and retrieves registered email address + + User->>FE: Initiate claim request (via frontend) + FE->>Claim: Request verification code + Claim->>DB: Generate & store one-time verification code (email, URI, timestamp, expiry) + Claim->>Mail: Send verification code to mailing service + Mail-->>User: Send one-time verification code + User->>FE: Input verification code + FE->>Claim: Submit verification code + Claim->>DB: Retrieve stored code & validate (code, rate limits, eligibility) + Claim->>FE: Prompt for public wallet address + FE->>User: Display wallet address input + User->>FE: Provide new wallet address + FE->>Claim: Submit wallet address + Claim->>DB: Update claim intent, log timestamp + Claim->>Mail: Send claim request email to admin + Mail-->>Admin: Notify admin of claim request (URI, token ID, wallet) + Admin->>FE: Initiate transfer (via frontend with admin wallet) + FE->>Admin: Request transaction signing (from contract to wallet) + Admin->>FE: Sign transfer transaction + FE->>Sol: Send transfer transaction + Sol-->>Wallet: Deliver claimed badge to user wallet + Sol-->>DB: Record claim completion (tx signature, wallet) + Mail-->>User: Send claim confirmation email + + Note over DB: Maintain full lifecycle history
(metadata hash, issuance, claim attempts, completion) +``` + +--- + +## End-to-End Workflow + +1. **Preparation** + - Frontend retrieves token catalogue and recipient roster. + - Admin selects badge set (single or batch) and recipients. + +2. **Metadata & Persistence** + - Frontend submits badge issuance payload to the IPFS service. + - IPFS returns content URI plus derived metadata (hash, gateway URL). + - Application persists issuance record in the database, including user data, payload hash, claim eligibility flags, and URI references. + +3. **Minting** + - Admin initiates mint via frontend with admin wallet. Frontend requests transaction signing from admin. + - Admin signs mint or batch mint transaction (supplying recipient wallet if available, token IDs, and metadata URI). + - Frontend sends the signed transaction to the token contract. + - Token contract (with built-in vault functionality) validates call and mints tokens: + - **If wallet provided**: Routes tokens directly to user wallets. + - **If no wallet provided**: Stores tokens in the contract's internal storage (vault functionality). + +4. **Notification** + - Post-confirmation hook (webhook or listener) enqueues email template jobs. + - Mailing list service delivers: + - **Direct wallet recipients** – badge details and blockchain links. + - **Contract-stored recipients** – claim instructions, emphasizing security posture. + +5. **Claim (Contract-Stored Tokens Only)** + - User initiates claim request via frontend (using claim service link from email). Frontend requests verification code from claim service. + - Claim service looks up issuance by URI and extracts the registered email. + - Claim service generates and stores one-time verification code in database (with email, URI, timestamp, expiry) and sends it to mailing service. + - Mailing service sends one-time verification code to user via email and enforces rate limits. + - User inputs verification code through frontend. Frontend submits code to claim service. + - Claim service retrieves stored code from database and validates (code, rate limits, eligibility). + - On success, frontend prompts user for a self-custodial public wallet address. + - User provides wallet address through frontend. Frontend submits wallet address to claim service. + - Claim service updates claim intent in database and sends claim request email to Admin, including URI, token ID, and user's wallet address. + - Admin receives claim request notification via email. + - Admin initiates transfer via frontend with admin wallet. Frontend requests transaction signing from admin. + - Admin signs transfer transaction (from contract storage to user wallet). Frontend sends the signed transaction to token contract. + - System updates database with claim completion timestamp, destination wallet, and transaction signature. + - Confirmation email is sent to the claimant. + +6. **Auditing & Reporting** + - Dashboard surfaces mint/claim status, IPFS hashes, and notification delivery logs. + - Scheduled jobs reconcile on-chain state with database records. + +---