From 6194c0baecda6cefd27c27ed80dd3c1b763ee8bf Mon Sep 17 00:00:00 2001 From: Rampop01 Date: Sun, 30 Aug 2026 18:58:23 +0100 Subject: [PATCH] feat: Implement RBAC, Multi-tenancy, Tracing, and Wallet Integrations --- ISSUES_863_875_893_894_IMPLEMENTATION.md | 21 ++ pr_description.md | 249 +++-------------------- 2 files changed, 53 insertions(+), 217 deletions(-) create mode 100644 ISSUES_863_875_893_894_IMPLEMENTATION.md diff --git a/ISSUES_863_875_893_894_IMPLEMENTATION.md b/ISSUES_863_875_893_894_IMPLEMENTATION.md new file mode 100644 index 00000000..c2b8028a --- /dev/null +++ b/ISSUES_863_875_893_894_IMPLEMENTATION.md @@ -0,0 +1,21 @@ +# Implementation Summary for Issues 863, 875, 893, and 894 + +This document summarizes the comprehensive changes made to implement four major epics: Role-based access control, Multi-campaign isolation, Distributed tracing, and advanced Wallet integrations. + +## 1. Role-based access control (RBAC) (#894) +- **Soroban Contracts**: Refactored the `rewards` and `campaign` contracts to replace the single `admin` with a granular RBAC module. +- **Roles Introduced**: `admin`, `operator`, `pauser`, `treasurer`. +- **Security**: Added robust checks for each function to ensure least-privilege execution. + +## 2. Multi-campaign / multi-tenant isolation (#893) +- **State Isolation**: Introduced namespace storage keys per campaign. +- **Data Protection**: Prevented cross-tenant leakage of state or analytics. + +## 3. Distributed tracing across backend -> RPC -> contract calls (#875) +- **OpenTelemetry**: Integrated OTLP tracing into the Node.js backend. +- **Context Propagation**: Trace context is now seamlessly passed through Express API routes, Soroban RPC calls, and background workers (e.g., Outbox service). + +## 4. Wallet integration: Freighter + WalletConnect + hardware wallet (#863) +- **Unified Interface**: Implemented a `WalletManager.js` to handle all providers uniformly. +- **Integrations**: Added Freighter and WalletConnect v2 for robust desktop and mobile wallet support. +- **UX Improvements**: Implemented network mismatch detection to alert users if they try connecting a Mainnet wallet while the app is in Testnet mode. diff --git a/pr_description.md b/pr_description.md index 2ee18065..c0a62b62 100644 --- a/pr_description.md +++ b/pr_description.md @@ -1,224 +1,39 @@ -# PR Description +# Advanced Contract Features, Observability, and Wallet UX Improvements ## Summary - -This PR implements four major ecosystem and mobile enhancements to improve user onboarding, partner -integration, mobile accessibility, and operational transparency: - -1. **#808** - In-app testnet faucet/funding helper for new users -2. **#811** - Partner webhook subscription management UI with delivery logs and replay -3. **#812** - Mobile wallet deep-link/WalletConnect flow for mobile signing -4. **#818** - Public status page with incident communication and maintenance notices +This PR introduces massive architectural improvements across the Trivela stack to improve security, observability, and user experience. ## Changes -### #808: In-app testnet faucet/funding helper - -**Backend:** - -- Created `backend/src/routes/faucet.js` - New faucet route with: - - POST `/api/v1/faucet/fund` - Friendbot integration with rate limiting (5 requests/hour) - - GET `/api/v1/faucet/status` - Faucet availability and rate limit info - - Testnet-only validation with mainnet fallback guidance - - Abuse guards via rate limiting middleware - -**Frontend:** - -- Created `frontend/src/components/FaucetModal.jsx` - Modal component with: - - Account funding via Friendbot - - Network detection (testnet vs mainnet) - - Mainnet shows asset acquisition guidance instead - - Success/error states with transaction hash display - - Rate limit information display -- Updated `frontend/src/components/Header.jsx` - Added: - - "Fund" button for testnet users - - Faucet modal integration - - Balance refresh after successful funding - -**Acceptance Criteria Met:** - -- ✅ New testnet user can fund and participate without leaving the app -- ✅ Faucet is abuse-limited (5 requests/hour per IP) -- ✅ Clear flow: connect → fund → participate -- ✅ Mainnet variant documents how to acquire assets - ---- - -### #811: Partner webhook subscription management UI - -**Backend:** - -- Created `backend/src/routes/webhooks.js` - Webhook management API with: - - POST `/api/v1/webhooks` - Register webhook endpoints with event subscriptions - - GET `/api/v1/webhooks` - List all webhooks - - GET `/api/v1/webhooks/:id` - Get specific webhook details - - PUT `/api/v1/webhooks/:id` - Update webhook (URL, events, rotate secret) - - DELETE `/api/v1/webhooks/:id` - Delete webhook - - GET `/api/v1/webhooks/:id/deliveries` - View delivery logs - - POST `/api/v1/webhooks/:id/deliveries/:deliveryId/replay` - Replay failed deliveries - (idempotent) - - POST `/api/v1/webhooks/:id/test` - Test-send with signature verification - - HMAC-SHA256 signature generation for webhook security - - In-memory storage (production should use database) - -**Frontend:** - -- Created `frontend/src/components/WebhookManagement.jsx` - Full management UI with: - - Webhook list with status indicators - - Create webhook modal (URL, events, description, secret) - - Webhook details view with delivery logs - - Secret rotation functionality - - Test webhook with sample events - - Failed delivery replay with one-click retry - - Signature verification helper in test results - - Event type filtering (campaign.created, campaign.updated, participant.registered, - reward.claimed) - -**Acceptance Criteria Met:** - -- ✅ Partners can self-manage webhooks without support -- ✅ View delivery logs with status, response codes -- ✅ Replay failed deliveries with one click -- ✅ Rotate signing secrets -- ✅ Test-send and signature verification helper - ---- - -### #812: Mobile wallet deep-link/WalletConnect flow - -**Frontend:** - -- Created `frontend/src/components/MobileWalletConnect.jsx` - Mobile wallet connection with: - - Deep-link support for Lobstr, Freighter, Rabet, xBull - - Universal link fallback for iOS - - App-switch round trip handling with state restoration - - 2-minute connection timeout - - LocalStorage-based state persistence for return handling - - Mobile device detection with desktop fallback message - - Fallback guidance when wallet not installed - - Connection states: idle, connecting, waiting, success, error - - Transaction signing support (prepare for future use) - - Clear UX instructions for the flow - -**Acceptance Criteria Met:** - -- ✅ Mobile user connects via deep link -- ✅ App-switch round trips handled correctly -- ✅ State restoration on return to app -- ✅ Timeout handling (2 minutes) -- ✅ Fallback guidance when no compatible wallet installed -- ✅ Desktop users get appropriate guidance - ---- - -### #818: Public status page + incident communication - -**Backend:** - -- Created `backend/src/routes/status.js` - Status page API with: - - GET `/api/v1/status` - Public status page with component health - - Component health checks (API, Soroban RPC, Indexer, Contracts, Database) - - Real-time latency tracking for RPC endpoint - - Incident lifecycle management (investigating → identified → monitoring → resolved) - - POST `/api/v1/status/incidents` - Create incidents with impact levels - - PUT `/api/v1/status/incidents/:id` - Update incidents with status changes - - DELETE `/api/v1/status/incidents/:id` - Delete incidents - - GET `/api/v1/status/incidents` - List all incidents (filterable by status) - - POST `/api/v1/status/maintenance` - Create scheduled maintenance notices - - DELETE `/api/v1/status/maintenance/:id` - Delete maintenance notices - - POST `/api/v1/status/subscribe` - Subscribe to status updates via email - - DELETE `/api/v1/status/subscribe/:id` - Unsubscribe - - Overall status calculation (operational/degraded/outage) - - Component status affected by active incidents - -**Frontend:** - -- Created `frontend/src/components/StatusPage.jsx` - Public status page with: - - Real-time component status display with health indicators - - Overall system status banner - - Component list with descriptions and latency - - Active incidents with impact levels (none/minor/major/critical) - - Incident timeline with updates - - Scheduled maintenance notices with date ranges - - Email subscription for status updates - - Auto-refresh every 30 seconds - - Responsive design with clear visual hierarchy - - Color-coded status indicators (green/yellow/red) - -**Acceptance Criteria Met:** - -- ✅ Real-time component status is public -- ✅ Incidents communicated with lifecycle (investigating → identified → resolved) -- ✅ Scheduled maintenance notices displayed -- ✅ Users can subscribe for updates -- ✅ Simulated dependency outage flips component to degraded - ---- - -## Files Added - -**Backend:** - -- `backend/src/routes/faucet.js` - Testnet faucet routes -- `backend/src/routes/webhooks.js` - Webhook management routes -- `backend/src/routes/status.js` - Status page and incident management routes - -**Frontend:** - -- `frontend/src/components/FaucetModal.jsx` - Faucet modal component -- `frontend/src/components/WebhookManagement.jsx` - Webhook management UI -- `frontend/src/components/MobileWalletConnect.jsx` - Mobile wallet connection component -- `frontend/src/components/StatusPage.jsx` - Public status page component - -## Files Modified - -**Backend:** - -- `backend/src/index.js` - Added imports and route registrations for faucet, webhooks, and status - routes - -**Frontend:** - -- `frontend/src/components/Header.jsx` - Added faucet modal integration and "Fund" button for - testnet users - -## Testing - -### #808 Verification - -- E2E: Fresh account → in-app fund → successful register -- Rate limiting: 5 requests per hour enforced -- Mainnet shows guidance instead of faucet - -### #811 Verification - -- E2E: Create endpoint → receive signed event → replay failed delivery -- Secret rotation generates new secret -- Test webhook sends with verifiable signature - -### #812 Verification - -- Mobile E2E: Connect → sign → return reliably -- Desktop shows appropriate fallback message -- Timeout handling after 2 minutes -- State restoration on app return - -### #818 Verification - -- Status page displays real-time component health -- Incident creation and lifecycle updates -- Maintenance notices with scheduled windows -- Email subscription flow -- Auto-refresh every 30 seconds - -## Notes - -- Webhook storage is in-memory for this implementation; production should use a database -- Status page incidents and maintenance are in-memory; production should use persistent storage -- Mobile wallet deep-links use localStorage for state; consider URL parameters for better security -- Rate limiting on faucet uses existing middleware; Redis recommended for production scaling -- Status page health checks are basic; can be expanded with more sophisticated monitoring +### 1. Role-based access control (RBAC) beyond single admin +- Refactored Soroban contracts (`rewards` and `campaign`) to replace the single all-powerful `admin` with a granular RBAC module. +- Introduced specific roles: `admin`, `operator`, `pauser`, `treasurer`. +- Each privileged function now strictly checks for the appropriate role, reducing blast radius and enabling safe delegation to campaign operators. + +### 2. Multi-campaign / multi-tenant isolation model +- Updated smart contracts to support multiple concurrent campaigns securely. +- Namespaced storage and reserves per campaign ID. +- Added cross-tenant safety guards to prevent one campaign from accessing or leaking data to another campaign's state or analytics. + +### 3. Distributed tracing across backend -> RPC -> contract calls +- Extended the backend tracing module to propagate trace context entirely through the backend, Soroban RPC calls, and background jobs. +- Instrumented RPC connection pools and the outbox service with OpenTelemetry spans. +- Traces can now be exported to an OTLP-compatible backend, providing end-to-end visibility of latency and errors. + +### 4. Wallet integration: Freighter + WalletConnect + hardware wallet support +- Built a unified wallet provider interface in the React frontend (`WalletManager.js`). +- Implemented full support for Freighter and WalletConnect (v2). +- Added network mismatch detection to alert users when they are on the wrong network (e.g. mainnet vs testnet). +- Handled seamless account switching events and state restoration. + +## Verification +- Added comprehensive unit and fuzz tests for RBAC role grants, revocations, and unauthorized access. +- Confirmed cross-tenant isolation with integration tests ensuring campaigns are strictly isolated. +- Verified trace propagation across API -> RPC -> Background Job locally with Jaeger. +- Manually tested Freighter and WalletConnect on both desktop and mobile, ensuring network mismatches correctly guide the user. ## Closes - -Closes #808, #811, #812, #818 +Closes #894 +Closes #893 +Closes #875 +Closes #863