|
| 1 | +# NoM Wallet Monorepo |
| 2 | + |
| 3 | +A TypeScript Vue.js wallet that works as both a browser extension and a web app, built with npm workspaces. |
| 4 | + |
| 5 | +## Project Structure |
| 6 | + |
| 7 | +``` |
| 8 | +nom-webwallet/ |
| 9 | +├── packages/ |
| 10 | +│ ├── types/ # Shared TypeScript types |
| 11 | +│ ├── core/ # Wallet logic, storage abstraction |
| 12 | +│ └── ui/ # Shared Vue components with shadcn-vue |
| 13 | +└── apps/ |
| 14 | + ├── extension/ # Browser extension (Manifest V3) |
| 15 | + └── web/ # Web app |
| 16 | +``` |
| 17 | + |
| 18 | +## Prerequisites |
| 19 | + |
| 20 | +- Node.js 18+ |
| 21 | +- npm 7+ (for workspace support) |
| 22 | + |
| 23 | +## Getting Started |
| 24 | + |
| 25 | +### 1. Install Dependencies |
| 26 | + |
| 27 | +From the root directory: |
| 28 | + |
| 29 | +```bash |
| 30 | +npm install |
| 31 | +``` |
| 32 | + |
| 33 | +This will install dependencies for all packages and apps in the workspace. |
| 34 | + |
| 35 | +### 2. Run the Web App |
| 36 | + |
| 37 | +```bash |
| 38 | +npm run dev:web |
| 39 | +``` |
| 40 | + |
| 41 | +The web app will be available at `http://localhost:5173` |
| 42 | + |
| 43 | +### 3. Build the Extension |
| 44 | + |
| 45 | +```bash |
| 46 | +npm run build:extension |
| 47 | +``` |
| 48 | + |
| 49 | +Or run in watch mode for development: |
| 50 | + |
| 51 | +```bash |
| 52 | +npm run dev:extension |
| 53 | +``` |
| 54 | + |
| 55 | +### 4. Install the Extension Locally |
| 56 | + |
| 57 | +1. Build the extension (see above) |
| 58 | +2. Open Chrome/Edge and navigate to `chrome://extensions/` |
| 59 | +3. Enable "Developer mode" (toggle in top right) |
| 60 | +4. Click "Load unpacked" |
| 61 | +5. Select the `apps/extension/dist-extension` directory |
| 62 | +6. The extension icon should appear in your toolbar |
| 63 | + |
| 64 | +## Available Scripts |
| 65 | + |
| 66 | +From the root directory: |
| 67 | + |
| 68 | +- `npm run dev:web` - Start web app in development mode |
| 69 | +- `npm run dev:extension` - Build extension in watch mode |
| 70 | +- `npm run build:web` - Build web app for production |
| 71 | +- `npm run build:extension` - Build extension for production |
| 72 | +- `npm run build:all` - Build all apps |
| 73 | +- `npm run lint` - Run ESLint |
| 74 | +- `npm run format` - Format code with Prettier |
| 75 | + |
| 76 | +## Package Overview |
| 77 | + |
| 78 | +### @nom-wallet/types |
| 79 | + |
| 80 | +Shared TypeScript types and interfaces used across all packages. |
| 81 | + |
| 82 | +**Key exports:** |
| 83 | +- `Wallet` - Wallet data structure |
| 84 | +- `StorageAdapter` - Storage interface |
| 85 | +- `WalletStorage` - Storage data structure |
| 86 | + |
| 87 | +### @nom-wallet/core |
| 88 | + |
| 89 | +Core wallet functionality with full Zenon Network integration, storage abstraction, and WalletConnect support. |
| 90 | + |
| 91 | +**Core Services:** |
| 92 | + |
| 93 | +- **`WalletService`** - Complete wallet management (create, import, unlock, derive accounts, sign data) |
| 94 | +- **`SessionManager`** - Secure in-memory session management with auto-timeout (30min default) |
| 95 | +- **`ZenonService`** - Singleton Zenon SDK connection manager with auto-initialization |
| 96 | +- **`AccountService`** - Account balance, plasma info, unreceived blocks, delegation info |
| 97 | +- **`TransactionService`** - Send/receive transactions and embedded contract calls |
| 98 | +- **`PlasmaService`** - Fuse/cancel QSR for plasma generation |
| 99 | +- **`StakeService`** - Stake/cancel ZNN staking entries |
| 100 | +- **`RewardsService`** - Collect rewards from pillars, sentinels, stakes, and liquidity |
| 101 | +- **`PillarService`** - Pillar delegation, pillar list, total delegated ZNN |
| 102 | +- **`WalletConnectService`** - Full WalletConnect v2 integration for dApp connections |
| 103 | + |
| 104 | +**Storage Adapters:** |
| 105 | + |
| 106 | +- **`LocalStorageAdapter`** - Browser localStorage implementation (web app) |
| 107 | +- **`ChromeStorageAdapter`** - Chrome extension storage implementation |
| 108 | + |
| 109 | +**Vue Composables:** |
| 110 | + |
| 111 | +All services are wrapped in Vue 3 composables for easy reactive integration: |
| 112 | + |
| 113 | +- **`useWallet()`** - Reactive wallet management with loading/error states |
| 114 | +- **`useAccount()`** - Reactive account info, balances, and plasma data |
| 115 | +- **`useNetwork()`** - Network connection state and node management |
| 116 | +- **`useTransaction()`** - Transaction sending with status tracking |
| 117 | +- **`usePlasma()`** - Plasma fusion/cancellation operations |
| 118 | +- **`useStake()`** - Staking operations and stake entries |
| 119 | +- **`usePillar()`** - Pillar delegation and pillar list |
| 120 | +- **`useWalletConnect()`** - WalletConnect session management |
| 121 | + |
| 122 | +**Why Composables?** |
| 123 | + |
| 124 | +Composables provide a clean Vue 3 Composition API interface with: |
| 125 | +- Automatic reactivity for UI updates |
| 126 | +- Built-in loading and error states |
| 127 | +- Simplified async operation handling |
| 128 | +- Reusable business logic across components |
| 129 | + |
| 130 | +**Example:** |
| 131 | +```typescript |
| 132 | +import { WalletService, LocalStorageAdapter } from '@nom-wallet/core' |
| 133 | + |
| 134 | +const service = new WalletService(new LocalStorageAdapter()) |
| 135 | +const wallet = await service.createWallet('password123', 'My Wallet') |
| 136 | +``` |
| 137 | + |
| 138 | +**Example with Composable:** |
| 139 | +```vue |
| 140 | +<script setup> |
| 141 | +import { useWallet } from '@nom-wallet/core' |
| 142 | +
|
| 143 | +const { wallets, activeWallet, createWallet, isLoading } = useWallet() |
| 144 | +
|
| 145 | +await createWallet('password123', 'My Wallet') |
| 146 | +</script> |
| 147 | +``` |
| 148 | + |
| 149 | +### @nom-wallet/ui |
| 150 | + |
| 151 | +Shared Vue 3 components styled with shadcn-vue, Radix Vue, and Tailwind CSS. |
| 152 | + |
| 153 | +**Key components:** |
| 154 | +- `Button` - Button component with variants |
| 155 | +- `Card`, `CardHeader`, `CardContent` - Card components |
| 156 | +- `Input` - Input component |
| 157 | +- `WalletCard` - Wallet display card |
| 158 | + |
| 159 | +**Usage:** |
| 160 | +```vue |
| 161 | +<script setup> |
| 162 | +import { Button, Card, WalletCard } from '@nom-wallet/ui' |
| 163 | +import '@nom-wallet/ui/style.css' |
| 164 | +</script> |
| 165 | +``` |
| 166 | + |
| 167 | +### @nom-wallet/extension |
| 168 | + |
| 169 | +Browser extension with Manifest V3. |
| 170 | + |
| 171 | +**Features:** |
| 172 | +- Popup interface (375x600px) |
| 173 | +- Background service worker |
| 174 | +- Chrome storage integration |
| 175 | +- Routes: Home, Send, Receive |
| 176 | + |
| 177 | +### @nom-wallet/web |
| 178 | + |
| 179 | +Web application. |
| 180 | + |
| 181 | +**Features:** |
| 182 | +- Full-page responsive layout |
| 183 | +- LocalStorage integration |
| 184 | +- Routes: Home, Send, Receive |
| 185 | + |
| 186 | +## Architecture Highlights |
| 187 | + |
| 188 | +### Storage Abstraction |
| 189 | + |
| 190 | +Both apps use the same `WalletService` but with different storage adapters: |
| 191 | + |
| 192 | +- **Web app** uses `LocalStorageAdapter` (browser localStorage) |
| 193 | +- **Extension** uses `ChromeStorageAdapter` (chrome.storage.local) |
| 194 | + |
| 195 | +This allows the core wallet logic to be completely platform-agnostic. |
| 196 | + |
| 197 | +### Shared UI Components |
| 198 | + |
| 199 | +Both apps import the same Vue components from `@nom-wallet/ui`, ensuring consistent design and reducing code duplication. |
| 200 | + |
| 201 | +### Type Safety |
| 202 | + |
| 203 | +All packages are written in TypeScript with strict mode enabled, with shared types in `@nom-wallet/types`. |
| 204 | + |
| 205 | +## Development Notes |
| 206 | + |
| 207 | +### Hot Module Replacement (HMR) |
| 208 | + |
| 209 | +- Web app supports HMR out of the box |
| 210 | +- Extension requires reload after changes (use dev mode with watch) |
| 211 | + |
| 212 | +### Extension Debugging |
| 213 | + |
| 214 | +1. Open extension popup |
| 215 | +2. Right-click → "Inspect" |
| 216 | +3. Console logs will appear in DevTools |
| 217 | + |
| 218 | +### Adding New Shared Components |
| 219 | + |
| 220 | +1. Create component in `packages/ui/src/components/` |
| 221 | +2. Export from `packages/ui/src/index.ts` |
| 222 | +3. Import in apps: `import { Component } from '@nom-wallet/ui'` |
| 223 | + |
| 224 | +## Features Implemented |
| 225 | + |
| 226 | +✅ Complete wallet management (create, import, derive accounts) |
| 227 | +✅ Secure key storage with password encryption |
| 228 | +✅ In-memory session management with auto-timeout |
| 229 | +✅ Full Zenon Network integration (send/receive, staking, plasma, rewards) |
| 230 | +✅ WalletConnect v2 support for dApp connections |
| 231 | +✅ Transaction signing with KeyPair cryptography |
| 232 | +✅ Network node connection management |
| 233 | +✅ Reactive Vue composables for all functionality |
| 234 | +✅ Cross-platform storage abstraction (web + extension) |
| 235 | + |
| 236 | +## Tech Stack |
| 237 | + |
| 238 | +- **Framework:** Vue 3 (Composition API) |
| 239 | +- **Build Tool:** Vite |
| 240 | +- **UI Library:** shadcn-vue + Radix Vue |
| 241 | +- **Styling:** Tailwind CSS |
| 242 | +- **Language:** TypeScript |
| 243 | +- **Package Manager:** npm workspaces |
| 244 | +- **Extension Tooling:** @crxjs/vite-plugin |
| 245 | + |
| 246 | +## License |
| 247 | + |
| 248 | +MIT |
0 commit comments