admojo-protocol · AnonO6 · Apr 5, 2025 · Apr 5, 2025
diff --git a/.cursor/rules/Metal_documentation.mdc b/.cursor/rules/Metal_documentation.mdc
@@ -0,0 +1,204 @@
+---
+description: Referring to the documentation
+globs: 
+alwaysApply: false
+---
+# Metal Token Cloud API Documentation
+
+## Overview
+Metal is the simplest way to tokenize your app. Create and distribute tokens to your users in a few lines of code. We manage all the crypto complexity behind a set of simple APIs, so you can focus on building amazing user experiences.
+
+## Why Tokenize?
+
+### Benefits
+- **Increase Engagement**: Use tokens to incentivize active user engagement
+- **Distribute Tokens**: Encourage higher quality user-generated content
+- **Increase Retention**: Users that earn while using your app are more likely to return
+- **Earn Fees**: Earn a 0.5% fee every time tokens are bought and sold
+
+## API Endpoints
+
+### Merchant API
+
+#### Create Token
+**Endpoint**: `POST api.metal.build/merchant/create-token`
+
+##### Required Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | string | The name for your token (e.g., "Test Token") |
+| `symbol` | string | The ticker symbol for your token (e.g., "TEST") |
+
+##### Optional Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `canDistribute` | boolean | Enable distribution functionality for this token |
+| `canLP` | boolean | Enable liquidity pool creation for this token |
+| `merchantAddress` | string | Address to receive merchant token allocation (fixed at 5% of total supply) |
+
+##### Example Request
+```javascript
+const response = await fetch('https://api.metal.build/merchant/create-token', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'x-api-key': 'YOUR-API-KEY',
+  },
+  body: JSON.stringify({
+    name: 'Test Token',
+    symbol: 'TEST',
+    merchantAddress: '0x1234567890abcdef1234567890abcdef12345678',
+    canDistribute: true,
+    canLP: true
+  }),
+})
+
+const token = await response.json()
+```
+
+##### Check Token Creation Status
+**Endpoint**: `GET api.metal.build/merchant/create-token/status/:jobId`
+
+### Token API
+
+#### Get Token with Holders
+**Endpoint**: `GET api.metal.build/token/:address`
+
+##### Response Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | string | Token ID |
+| `address` | string | Contract address |
+| `name` | string | Token name |
+| `symbol` | string | Ticker symbol |
+| `totalSupply` | number | Total token supply |
+| `price` | number | Current token price in USD |
+| `holders` | array | List of token holders |
+
+#### Distribute Tokens
+Distribute tokens to your users on Base. This endpoint allows you to distribute tokens from your app balance to specified addresses.
+**Endpoint**: `POST api.metal.build/token/:address/distribute`
+
+##### Required Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `sendTo` | string | Recipient address |
+| `amount` | number | Number of tokens to distribute |
+
+##### Example Request
+```javascript
+const response = await fetch(
+  'https://api.metal.build/token/0x1234567890abcdef1234567890abcdef12345678/distribute',
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': 'YOUR-API-KEY',
+    },
+    body: JSON.stringify({
+      sendTo: '0xabcdef1234567890abcdef1234567890abcdef12',
+      amount: 100
+    }),
+  }
+)
+
+const distribute = await response.json()
+```
+
+### Holder API
+
+#### Get Holder
+This endpoint returns all token balances and related information for a specific holder.
+**Endpoint**: `GET api.metal.build/holder/:id?publicKey=:publicKey`
+
+##### Response Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `id` | string | Holder ID |
+| `address` | string | Holder's address |
+| `totalValue` | number | Total value of token holdings in USD |
+| `tokens` | array | List of token holdings |
+
+#### Get or Create Holder
+Get Or Create a holder for your organization. Holder wallets can be created for your customers with an external id of your choice.
+**Endpoint**: `PUT api.metal.build/holder/:userId`
+##### Example Request
+```javascript
+const response = await fetch(`https://api.metal.build/holder/${userId}`, {
+method: 'PUT',
+headers: {
+  'Content-Type': 'application/json',
+  'x-api-key': 'YOUR-API-KEY',
+  },
+})
+
+const holder = await response.json()
+```
+
+#### Withdraw Tokens
+This endpoint allows you to withdraw tokens from a holders account to a specified address.
+**Endpoint**: `POST api.metal.build/holder/:userId/withdraw`
+
+##### Required Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `tokenAddress` | string | Token contract address |
+| `amount` | number | Amount to withdraw |
+| `toAddress` | string | Destination address |
+
+##### Example Request
+```javascript
+const response = await fetch(
+  `https://api.metal.build/holder/${userId}/withdraw`,
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': 'YOUR-API-KEY',
+    },
+    body: JSON.stringify({
+        tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',
+        amount: 123,
+        toAddress: '0x191d25c061C081583E616d8978eA670f45A12345',
+      }),
+  }
+)
+
+const withdraw = await response.json()
+```
+
+#### Spend Tokens
+This endpoint allows you to spend tokens from a holders account.
+**Endpoint**: `POST api.metal.build/holder/:userId/spend`
+
+##### Required Attributes
+| Name | Type | Description |
+|------|------|-------------|
+| `tokenAddress` | string | Token contract address |
+| `amount` | number | Amount to spend |
+##### Example Request
+```javascript
+const response = await fetch(
+  `https://api.metal.build/holder/${userId}/spend`,
+  {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': 'YOUR-API-KEY',
+    },
+    body: JSON.stringify({
+      tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',
+      amount: 123,
+    }),
+  }
+)
+
+const spend = await response.json()
+```
+## Authentication
+- Use the `x-api-key` header with your API key for all requests
+- API keys can be obtained from Metal
+
+## Notes
+- All examples use placeholder addresses and should be replaced with actual values
+- Ensure you have the necessary permissions and API key before making requests
diff --git a/.cursor/rules/coding-preferences.mdc b/.cursor/rules/coding-preferences.mdc
@@ -0,0 +1,18 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Coding pattern preferences
+
+– Always prefer simple solutions  
+– Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality  
+– Write code that takes into account the different environments: dev, test, and prod  
+– You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested  
+– When fixing an issue or bug, do not introduce a new pattern or technology without first exhausting all options for the existing implementation. And if you finally do this, make sure to remove the old implementation afterwards so we don’t have duplicate logic.  
+– Keep the codebase very clean and organized  
+– Avoid writing scripts in files if possible, especially if the script is likely only to be run once  
+– Avoid having files over 200–300 lines of code. Refactor at that point.  
+– Mocking data is only needed for tests, never mock data for dev or prod  
+– Never add stubbing or fake data patterns to code that affects the dev or prod environments  
+– Never overwrite my .env file without first asking and confirming
diff --git a/.cursor/rules/description.mdc b/.cursor/rules/description.mdc
@@ -0,0 +1,30 @@
+---
+description: Project Overview
+globs: 
+alwaysApply: false
+---
+# AdNet Protocol
+
+AdNet Protocol is a decentralized, IoT-enabled Web3 advertising platform bridging Advertising Companies (AC) and Ad Service Providers (ASP), leveraging blockchain technology and verifiable ad analytics.
+
+## Overview
+
+The platform provides IoT-based **Proof-of-View (PoV)** via ESP32-CAM modules and **Proof-of-Tap (PoT)** via NFC-enabled (PN532) IoT devices. It ensures transparent, accountable, and performance-based distribution of advertising funds (ADC tokens) using **Metal APIs**, secure identity verification via **Self Protocol**, and real-time blockchain event handling via **Nodit** integrations.
+
+## Key Features
+
+- **ASP & AC Portals:** Separate web dashboards with seamless wallet management via Privy and Metal API.
+- **IoT Modules (ESP32-CAM & PN532 NFC):** Real-time ad analytics capturing viewer impressions (PoV) and direct user engagements (PoT).
+- **Automated Token Distribution:** Nodit Webhooks trigger automatic payouts through Metal API, ensuring timely and accurate payments based on verified metrics.
+- **Privacy-Preserving Verification:** Self Protocol enables zero-knowledge identity verification, ensuring regulatory compliance without compromising user privacy.
+
+## Technologies Integrated
+
+- **Metal:** Dynamic wallet creation, token management, automated reward distribution.
+- **Self Protocol:** Regulatory-compliant, zero-knowledge-based identity verification.
+- **Nodit:** Real-time frontend updates via blockchain event webhooks and automated backend payment triggers.
+- **Privy Wallet:** Smooth user onboarding, wallet management, and secure transactions.
+
+## Objective
+
+AdNet Protocol optimizes ad spend, increases transparency, reduces fraud, and enhances consumer engagement—transforming traditional advertising through verifiable, blockchain-based interactions.
diff --git a/.cursor/rules/project-flow.mdc b/.cursor/rules/project-flow.mdc
@@ -0,0 +1,93 @@
+---
+description: Project flow
+globs: 
+alwaysApply: false
+---
+# ✅ **AdNet Protocol User Flows
+
+## **1. Ad Service Provider (ASP) Flow**
+
+**Step 1: Registration & Verification**
+- **Action:** Signs in via **Privy Wallet**.
+- **Backend:** Privy creates user session → **Metal API** dynamically creates custodial wallet → **Self Protocol** for verification (age/country/OFAC).
+
+**Step 2: Adding Ad Locations**
+- **Action:** ASP submits new location details.
+- **Backend:** Unique ASP Location ID assigned → IoT module registered → IoT device keys securely stored for oracle verification.
+
+**Step 3: IoT Module Activation**
+- **Action:** ASP sets up ESP32-CAM & ESP32+PN532 at location.
+- **Backend:** Modules connect via MQTT → begin sending Proof-of-View (PoV) and Proof-of-Tap (PoT) data.
+
+**Step 4: Earnings Accumulation**
+- **Action:** ASP monitors earnings dashboard.
+- **Backend:** Oracle receives IoT events, writes verified data on-chain → **Nodit** listens for these on-chain events, triggers backend webhook instantly → backend calculates earnings → uses **Metal API** to credit ASP wallets automatically.
+
+**Step 5: Withdraw Earnings**
+- **Action:** ASP initiates withdrawal.
+- **Backend:** **Metal API** securely transfers ADC from custodial wallet to ASP’s external wallet.
+
+---
+
+## **2. Advertising Company (AC) Flow**
+
+**Step 1: Registration & Verification**
+- **Action:** AC signs in via **Privy Wallet**.
+- **Backend:** Privy session created → **Metal API** dynamically creates wallet → **Self Protocol** verifies AC identity.
+
+**Step 2: Fund Wallet (USDC → ADC)**
+- **Action:** AC funds wallet with USDC.
+- **Backend:** Funds deposited → backend uses **Metal API** to auto-exchange USDC into ADC tokens.
+
+**Step 3: Create Ad Campaign**
+- **Action:** AC defines campaign parameters, selects ASP locations, uploads custom URLs for airdrop/rewards.
+- **Backend:** Smart contract via **Metal API** escrow-locks ADC tokens → backend assigns IoT modules, schedules URL pushes via MQTT to PN532 NFC writer.
+
+**Step 4: Campaign Monitoring**
+- **Action:** AC views real-time analytics dashboard.
+- **Backend:** IoT events verified by oracle, written on-chain → **Nodit Webhooks** instantly notify backend → dashboard state updates in real-time.
+
+**Step 5: Campaign Completion & Settlement**
+- **Action:** Campaign ends or budget exhausted.
+- **Backend:** Final analytics via **Nodit** aggregated → backend auto-calculates payouts → triggers **Metal API** to release ADC to ASP wallets based on verified data.
+
+---
+
+## **3. Customer Flow**
+
+**Step 1: Ad Interaction**
+- **Action:** Customer views ad, taps NFC module.
+- **Backend:** PN532 module (ESP32) reveals URL → URL directs to customer engagement page.
+
+**Step 2: Identity Verification (Optional Reward Claim)**
+- **Action:** Customer performs quick verification via **Self Protocol**.
+- **Backend:** Self Protocol returns verification status (ZKP).
+
+**Step 3: Reward Distribution**
+- **Action:** Customer claims reward (ADC tokens or incentives).
+- **Backend:** Reward claim verified → **Metal API** dynamically credits tokens from AC escrow directly to customer wallet.
+
+**Step 4: Engagement & Analytics**
+- **Action:** Customer optionally continues engaging via app.
+- **Backend:** Engagement metrics anonymized, recorded → future reward offers dynamically personalized (off-chain).
+
+---
+
+## ⚙️ **Concise Backend Integration Recap**
+
+- **Privy:** User onboarding, wallet/session management.
+- **Metal:** Token creation, wallet management, escrow, automated reward distribution.
+- **Self Protocol:** Identity verification (age/country/OFAC).
+- **Nodit:**  
+  - **Trigger Payments:** Instantly triggers backend webhooks upon oracle recording new Proof-of-View/Tap on-chain events → backend calls Metal API to initiate payouts.  
+  - **Real-time Dashboard:** Webhook events from Nodit immediately update frontend dashboards with latest PoV & PoT analytics.
+- **ESP32-CAM + PN532 NFC:** IoT modules capture and verify ad interactions (PoV & PoT).
+- **ThingSpeak/MQTT/Oracle:** IoT data relay & verification pipeline.
+
+---
+
+This clearly emphasizes Nodit’s critical role:  
+- **Real-time payment triggers** (Metal API).  
+- **Instant frontend dashboard updates** (webhook-driven UI state management).  
+
+Your implementation now accurately reflects the important Web3 integrations and IoT interactions in a practical, scalable, and robust manner.
diff --git a/package.json b/package.json
@@ -27,14 +27,15 @@
     "@radix-ui/react-switch": "^1.1.3",
     "@radix-ui/react-tabs": "^1.1.3",
     "@radix-ui/react-tooltip": "^1.1.8",
-    "@selfxyz/core": "^0.0.19",
-    "@selfxyz/qrcode": "^0.0.17",
+    "@selfxyz/core": "^0.0.24",
+    "@selfxyz/qrcode": "^0.0.19",
     "@types/nprogress": "^0.2.3",
     "@wagmi/core": "^2.16.7",
     "abitype": "^1.0.8",
     "axios": "^1.6.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "core@latest": "link:selfxyz/core@latest",
     "dotenv": "^16.4.5",
     "leaflet": "^1.9.4",
     "lucide-react": "^0.483.0",