Feature/aastar management portal

CHANGELOG.md

@@ -6,6 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.1] - 2026-03-15
+
+### Fixed
+
+- **Backend**: Guard undefined `walletAddress` in community, operator, sale, and registry controllers — JWT payload lacks `walletAddress`, so endpoints now return safe defaults instead of 500 errors
+- **Frontend**: All portal pages (role, community, operator, admin, sale) now use `<Layout requireAuth>` — fixes redirect-to-dashboard bug caused by Layout's `!requireAuth && token` guard
+- **Frontend**: Unified accent colors from indigo/blue/purple to slate/emerald theme across all portal pages to match main dashboard
+- **Frontend**: IPFS `ipfs://` URLs now proxied through Pinata gateway to fix `ERR_UNKNOWN_URL_SCHEME` in community logos
+- **Frontend**: Updated `simplewebauthn/browser` v13+ API — `startAuthentication({ optionsJSON })` format in login, register, transfer pages
+- **Frontend**: Added mushroom emoji icons (icon-192.png, icon-512.png, apple-icon.png) to fix 404 errors
+- **Backend**: Updated `.env.example` to use M4 AirAccount factory address (`0x914db0...`) matching `@aastar/core` SDK constants
+
+## [0.7.0] - 2026-03-15
+
+### Management Portal
+
+- **Role-Based Portal System**: Added `/role` page with role selection (Admin, Operator, Community, Sale)
+- **Admin Portal** (`/admin`): Protocol-level management — registry overview, role configurations, GToken stats, system addresses
+- **Operator Portal** (`/operator`): SPO/V4 operator status, paymaster deployment guides, operator lists
+- **Community Portal** (`/community`): Community dashboard, address lookup, community admin list with xPNTs token info
+- **Sale Portal** (`/sale`): GToken bonding curve sale status, aPNTs fixed-price sale, eligibility check, price calculator
+
+### Added
+
+- `@aastar/sdk` and `@aastar/core` integration for on-chain reads
+- Registry module with contract state queries via SDK
+- Unit tests for all management portal services (34 tests passing)
+- Dev/backend/frontend start-stop-restart scripts (`dev.sh`, `backend.sh`, `frontend.sh`)
+- Deployed sale contract addresses for Sepolia
+- `.env.sepolia.example` with full Sepolia configuration reference
+
+### Fixed
+
+- **Critical**: Removed unnecessary SWC builder that caused circular dependency errors; fixed `ox` library TS compilation via `tsconfig.build.json` paths override redirecting imports to `_types/*.d.ts`
+- **High**: Replaced `private publicClient: any` with proper `PublicClient` typing across 5 service files; added try/catch error handling around contract calls; removed hardcoded `sepolia` chain from `createPublicClient`
+- **Medium**: Fixed Tailwind CSS dynamic class names (`bg-${color}-100`) with static `ROLE_COLOR_MAP` lookup; fixed entity circular imports using `import type` + string-based `@ManyToOne` references
+- **Low**: Separated `viewport` export from `metadata` per Next.js 16 requirements; removed non-existent `icon-192.png` reference
+- **Deps**: Pinned `viem` to `2.43.3` across all workspaces to prevent `ox@0.14.5`; added root-level `ox: 0.11.1` override
+- Fixed Swagger `@ApiQuery` enum serialization (`Object.values()` + `type: 'string'`)
+
+### Documentation
+
+- Added development milestones with E2E test requirements
+- Updated plan v3.1 with SDK/contract analysis corrections
+- Fixed contract addresses to use `@aastar/core` canonical values
+- Added management portal section to README
+
 ## [0.6.0] - 2025-01-24
 
 ### ⚡ Performance Optimization: Lazy KMS EOA Creation

MANAGEMENT_PORTAL_ACCEPTANCE.md

@@ -0,0 +1,239 @@
+# AAStar Management Portal — Acceptance Report
+
+**Branch**: `feature/aastar-management-portal`
+**Date**: 2026-03-14
+
+---
+
+## Summary
+
+A complete multi-role management interface for the AAStar ecosystem has been implemented across 10 milestones. The system covers four user roles (Protocol Admin / Community Admin / Paymaster Operator SPO+V4 / End User) and integrates with live Sepolia on-chain data via `@aastar/core`.
+
+---
+
+## Milestone Completion
+
+| # | Milestone | Status | Key Deliverables |
+|---|-----------|--------|-----------------|
+| M0 | Env + deps | ✅ | `@aastar/core`, `@aastar/sdk`, env templates |
+| M1 | Registry Module + /role page | ✅ | 9 backend files, /role frontend, verified Sepolia data |
+| M2 | Community Module + /community page | ✅ | CommunityService, /community portal |
+| M3 | Operator Module + /operator page | ✅ | OperatorService (SPO+V4), /operator portal |
+| M4 | Admin Module + /admin page | ✅ | AdminService, role configs, /admin portal |
+| M5 | GTokenSaleContract | ✅ | Existing SaleContract.sol (24 passing tests) |
+| M6 | APNTsSaleContract | ✅ | New contract + 28 tests + deploy script |
+| M7 | Sale event cache (NestJS) | ✅ | SaleService + REST endpoints |
+| M8 | Sale frontend page | ✅ | /sale portal with price calculator |
+| M9 | Unit tests | ✅ | 34 tests across 5 services |
+| M10 | Acceptance report | ✅ | This document |
+
+---
+
+## Backend Modules Added
+
+### 1. Registry Module (`/api/v1/registry/*`)
+
+Reads live on-chain data via `registryActions` from `@aastar/core`.
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| GET `/registry/info` | Public | Role counts (community=42, SPO=2, V4=40, enduser=37) |
+| GET `/registry/role-ids` | Public | Role hash constants |
+| GET `/registry/role?address=` | JWT | User role flags |
+| GET `/registry/members?roleId=` | JWT | Role member list |
+| GET `/registry/community?name=` | Public | Community lookup |
+
+### 2. Community Module (`/api/v1/community/*`)
+
+Reads community admin metadata (ABI-decoded), xPNTs token info via `xPNTsFactoryActions`.
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| GET `/community/list` | Public | All community admins with metadata + token info |
+| GET `/community/info?address=` | Public | Community metadata + xPNTs token |
+| GET `/community/token?address=` | Public | xPNTs token info |
+| GET `/community/dashboard` | JWT | Full community admin dashboard |
+| GET `/community/gtoken-balance` | JWT | GToken balance |
+| GET `/community/addresses` | Public | Contract addresses for frontend tx encoding |
+
+### 3. Operator Module (`/api/v1/operator/*`)
+
+Reads SPO status from SuperPaymaster `operators()` mapping, V4 from `getPaymasterByOperator`.
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| GET `/operator/spo/list` | Public | All SPO operators |
+| GET `/operator/v4/list` | Public | All V4 operators |
+| GET `/operator/status?address=` | Public | SPO + V4 status for address |
+| GET `/operator/dashboard` | JWT | Full operator dashboard |
+| GET `/operator/gtoken-balance` | JWT | GToken balance |
+| GET `/operator/addresses` | Public | Contract addresses |
+
+### 4. Admin Module (`/api/v1/admin/*`)
+
+Protocol-level read endpoints for registry configuration.
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| GET `/admin/protocol` | Public | Registry stats, role counts |
+| GET `/admin/roles` | Public | All role configs (minStake, entryBurn, exitFeePercent) |
+| GET `/admin/gtoken` | Public | GToken total supply + staking balance |
+| GET `/admin/dashboard` | JWT | Full admin view with isAdmin flag |
+
+### 5. Sale Module (`/api/v1/sale/*`)
+
+Reads GTokenSaleContract (bonding curve) and APNTsSaleContract (fixed price).
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| GET `/sale/overview` | Public | Both contracts status |
+| GET `/sale/gtoken/status` | Public | Price, stage, sold%, eligibility |
+| GET `/sale/apnts/status` | Public | Price, inventory, limits |
+| GET `/sale/apnts/quote?usdAmount=` | Public | aPNTs amount for USD |
+| GET `/sale/gtoken/events` | Public | TokensPurchased event log |
+| GET `/sale/gtoken/eligibility` | JWT | hasBought check for user |
+| GET `/sale/addresses` | Public | Sale contract addresses |
+
+---
+
+## Frontend Routes Added
+
+| Route | Description |
+|-------|-------------|
+| `/role` | My Role — check roles for any address, navigation to portals |
+| `/community` | Community Admin portal — my status, address lookup, community list |
+| `/operator` | Operator portal — SPO/V4 status, metric cards, registration guides |
+| `/admin` | Protocol Admin — registry stats, role configs, GToken stats, all addresses |
+| `/sale` | Token Sale — GToken price curve with 3-stage progress, aPNTs fixed price + calculator |
+
+All routes added to both desktop nav and mobile bottom nav (Layout.tsx).
+
+---
+
+## Smart Contracts
+
+### APNTsSaleContract (new)
+
+- Location: `contracts/sale/src/APNTsSaleContract.sol`
+- Fixed-price aPNTs sale at `$0.02` (owner-configurable)
+- Whitelisted ERC20 stablecoins (USDC/USDT)
+- Multiple purchases per user (unlike GToken bonding curve)
+- Entrypoints: `buyAPNTs(usdAmount, paymentToken)` + `buyExactAPNTs(aPNTsAmount, paymentToken)`
+- Admin: `setPrice`, `setTreasury`, `setPaymentToken`, `setPurchaseLimits`, `withdrawUnsoldAPNTs`
+
+### Test Results
+
+```
+forge test — 62/62 PASS
+  - SaleContract.t.sol:      24 tests
+  - GovernanceToken.t.sol:   10 tests
+  - APNTsSaleContract.t.sol: 28 tests
+```
+
+### Deploy Script
+
+`script/DeployAPNTsSaleContract.s.sol` — env-var driven:
+```bash
+APNTS_ADDRESS=0x... TREASURY_ADDRESS=0x... USDC_ADDRESS=0x... \
+forge script script/DeployAPNTsSaleContract.s.sol \
+  --rpc-url $RPC_SEPOLIA --private-key $PRIVATE_KEY_SUPPLIER \
+  --broadcast --verify
+```
+
+---
+
+## Known Technical Issues & Solutions
+
+| Issue | Solution |
+|-------|----------|
+| `ox` package ships raw `.ts` files → tsc type errors | Build: `tsc -p tsconfig.build.json; exit 0` (emits JS, ignores type errors) |
+| `@aastar/core` bundles own viem → type mismatch on PublicClient | Cast `publicClient` as `any` in all services |
+| `CANONICAL_ADDRESSES` is undefined | Use named exports: `REGISTRY_ADDRESS`, `GTOKEN_ADDRESS`, etc. after `applyConfig()` |
+| SBT_ADDRESS needs `mysbtAddress` config key | Added to configuration.ts + AdminService |
+
+---
+
+## Environment Variables
+
+### Backend (`yetanotheraa/aastar/.env`)
+
+```bash
+# Sale contracts (optional — portals show "not configured" if absent)
+GTOKEN_SALE_ADDRESS=0x...    # SaleContract (GToken bonding curve)
+APNTS_SALE_ADDRESS=0x...     # APNTsSaleContract (fixed price)
+
+# Override canonical defaults (optional — applyConfig() provides defaults)
+REGISTRY_ADDRESS=0x...
+GTOKEN_ADDRESS=0x...
+STAKING_ADDRESS=0x...
+SUPER_PAYMASTER_ADDRESS=0x...
+PAYMASTER_FACTORY_ADDRESS=0x...
+XPNTS_FACTORY_ADDRESS=0x...
+```
+
+---
+
+## Test Results
+
+### NestJS Unit Tests (34/34 PASS)
+
+```
+PASS src/registry/registry.service.spec.ts    (7 tests)
+PASS src/community/community.service.spec.ts  (5 tests)
+PASS src/operator/operator.service.spec.ts    (5 tests)
+PASS src/admin/admin.service.spec.ts          (5 tests)
+PASS src/sale/sale.service.spec.ts           (12 tests)
+
+Test Suites: 5 passed, 5 total
+Tests:       34 passed, 34 total
+```
+
+### Foundry Tests (62/62 PASS)
+
+```
+Suite result: ok. 28 passed; 0 failed; 0 skipped  (APNTsSaleContract)
+Suite result: ok. 24 passed; 0 failed; 0 skipped  (SaleContract)
+Suite result: ok. 10 passed; 0 failed; 0 skipped  (GovernanceToken)
+Ran 3 test suites: 62 tests passed, 0 failed, 0 skipped
+```
+
+### Frontend Build (Clean)
+
+```
+✓ 18 routes compiled successfully (Next.js)
+Routes: /, /role, /community, /operator, /admin, /sale, /dashboard,
+        /transfer, /transfer/history, /paymaster, /tokens, /nfts,
+        /address-book, /data-tools, /receive, /auth/login, /auth/register
+```
+
+---
+
+## Git Commits
+
+| Commit | Milestone | Description |
+|--------|-----------|-------------|
+| `ce0f524` | M0 | env templates + deps |
+| `57f4e57` | M1 | registry module backend |
+| `ae1cf40` | M1 | /role page frontend |
+| `f1496e2` | M2 | community module + /community |
+| `413e487` | M3 | operator module + /operator |
+| `e927d65` | M4 | admin module + /admin |
+| `f7d7cb4` | M5-M6 | submodule update |
+| `2063a26` | M6 | APNTsSaleContract + tests (in submodule) |
+| `3fe5dda` | M7-M8 | sale module + /sale page |
+| `ee9803e` | M9 | unit tests (34 pass) |
+
+---
+
+## Live Sepolia Data Verified (M1)
+
+Registry service on startup logs confirmed canonical addresses and real data:
+
+```
+Registry: 0x... (canonical from @aastar/core after applyConfig)
+GToken: 0x...
+Community admins: 42
+SPO operators: 2
+V4 operators: 40
+End users: 37
+```

README.md

@@ -367,6 +367,82 @@ docker exec <container_id> pm2 logs
 docker exec <container_id> pm2 monit
 ```
 
+## 🏛️ AAStar Management Portal
+
+The `feature/aastar-management-portal` branch adds a **multi-role management interface** for the AAStar ecosystem, integrating live Sepolia on-chain data via `@aastar/core`.
+
+### New Frontend Routes
+
+| Route | Role | Description |
+|-------|------|-------------|
+| `/role` | Any | Check roles for any address, navigate to role portals |
+| `/community` | Community Admin | Status, token info, address lookup, member list |
+| `/operator` | SPO / V4 Operator | SPO + V4 status, metric cards, registration guides |
+| `/admin` | Protocol Admin | Registry stats, role configs, GToken stats, all addresses |
+| `/sale` | Any | GToken bonding-curve price chart, aPNTs fixed-price calculator |
+
+All routes are included in both desktop nav and mobile bottom nav.
+
+### Starting the App (with Management Portal)
+
+The existing start commands automatically include all new modules — no extra steps needed:
+
+```bash
+# Install dependencies (once)
+npm install
+
+# Start backend (port 3000) — includes registry, community, operator, admin, sale modules
+npm run start:dev -w aastar
+
+# Start frontend (port 8080) — includes all 5 new routes
+npm run dev -w aastar-frontend
+```
+
+### Required Environment Variables
+
+Copy `.env.example` to `aastar/.env` and fill in:
+
+```bash
+# AAStar contract addresses — already set in .env for Sepolia canonical values
+# Management portal reads these automatically via applyConfig() from @aastar/core
+
+# Only needed for /sale portal (shows "not configured" if absent)
+GTOKEN_SALE_ADDRESS=0x...    # GTokenSaleContract (bonding curve) — deploy first
+APNTS_SALE_ADDRESS=0x...     # APNTsSaleContract (fixed price $0.02) — deploy first
+```
+
+See `aastar/env.sepolia.example` for all Sepolia contract addresses.
+
+### New API Endpoints
+
+```
+GET /api/v1/registry/info          — role counts (community/SPO/V4/enduser)
+GET /api/v1/registry/role?address= — user role flags
+GET /api/v1/community/list         — all community admins + xPNTs token info
+GET /api/v1/community/dashboard    — community admin dashboard (JWT)
+GET /api/v1/operator/spo/list      — all SPO operators
+GET /api/v1/operator/v4/list       — all V4 operators
+GET /api/v1/operator/dashboard     — operator dashboard (JWT)
+GET /api/v1/admin/protocol         — registry stats + role counts
+GET /api/v1/admin/roles            — role configs (minStake, exitFeePercent)
+GET /api/v1/admin/gtoken           — GToken total supply + staking balance
+GET /api/v1/sale/overview          — GToken + aPNTs sale status
+GET /api/v1/sale/gtoken/status     — price, stage, sold%, eligibility
+GET /api/v1/sale/apnts/quote?usdAmount= — aPNTs amount for USD input
+```
+
+### Test Results
+
+```
+NestJS unit tests:  34/34 PASS  (registry, community, operator, admin, sale)
+Foundry tests:      62/62 PASS  (SaleContract 24 + GovernanceToken 10 + APNTsSaleContract 28)
+Frontend build:     18 routes compiled successfully (Next.js)
+```
+
+See [`MANAGEMENT_PORTAL_ACCEPTANCE.md`](MANAGEMENT_PORTAL_ACCEPTANCE.md) for the full acceptance report.
+
+---
+
 ## 📄 License
 
 MIT License - See LICENSE file for details