{"id":30719765,"url":"https://github.com/fireblocks/ew-backend-demo","last_synced_at":"2025-09-03T10:41:58.696Z","repository":{"id":306759612,"uuid":"1010581724","full_name":"fireblocks/ew-backend-demo","owner":"fireblocks","description":"Push Notification System for Embedded Wallet","archived":false,"fork":false,"pushed_at":"2025-07-07T08:58:44.000Z","size":173,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-27T13:28:11.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fireblocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T11:35:00.000Z","updated_at":"2025-07-07T08:58:48.000Z","dependencies_parsed_at":"2025-07-27T13:38:29.811Z","dependency_job_id":null,"html_url":"https://github.com/fireblocks/ew-backend-demo","commit_stats":null,"previous_names":["fireblocks/ew-backend-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fireblocks/ew-backend-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Few-backend-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Few-backend-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Few-backend-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Few-backend-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fireblocks","download_url":"https://codeload.github.com/fireblocks/ew-backend-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireblocks%2Few-backend-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273431361,"owners_count":25104491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T10:41:57.952Z","updated_at":"2025-09-03T10:41:58.679Z","avatar_url":"https://github.com/fireblocks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Push Notification System for Embedded Wallet\n\nA demo implementation showcasing push notifications for transaction status updates in Embedded Wallets, replacing the traditional polling-based approach with an efficient push-based model. Each notification is associated with a specific walletId, enabling accurate delivery of transaction updates to the corresponding wallet instance.\n\n## Overview\n\nThis backend service enables real-time transaction status notifications across multiple platforms:\n\n- Android (Firebase Cloud Messaging)\n- iOS (Apple Push Notification Service)\n- Web Browsers (FCM / Web Push API with VAPID)\n\n### Key Benefits\n\n- Eliminates constant polling for transaction status\n- Reduces server load and API calls\n- Provides immediate status updates\n- Supports multiple platforms with a unified API\n\n## Architecture\n\n### Components\n\n1. **Client Applications**\n\n   - Register devices for push notifications\n   - Send push tokens to backend during authentication\n   - Handle incoming notifications and trigger UI updates\n\n2. **Backend Server**\n\n   - Manages device tokens and subscriptions\n   - Processes Fireblocks webhooks\n   - Distributes notifications to relevant devices\n   - Handles cross-platform notification delivery\n\n3. **Push Services**\n\n   - Firebase Cloud Messaging (FCM) for Android/Web\n   - APNs for iOS\n   - Web Push API with VAPID for browsers\n\n4. **Fireblocks Integration**\n   - Webhook processing for transaction lifecycle events\n   - Status change detection and notification triggering\n\n### Workflow\n\n1. **Device Registration**\n\n   ```mermaid\n   sequenceDiagram\n      Client-\u003e\u003eBackend: Register device token\n      Backend-\u003e\u003eDatabase: Store token \u0026 platform info\n      Backend-\u003e\u003eClient: Registration confirmed\n   ```\n\n2. **Transaction Updates**\n   ```mermaid\n   sequenceDiagram\n      Fireblocks-\u003e\u003eBackend: Transaction status webhook\n      Backend-\u003e\u003eDatabase: Look up user devices\n      Backend-\u003e\u003ePush Service: Send notifications\n      Push Service-\u003e\u003eClient: Deliver notification\n   ```\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js ≥ 20\n- SQL database\n- Firebase project (for FCM)\n- VAPID keys (for Web Push)\n\n### Installation\n\n1. Clone the repository\n\n   ```bash\n   git clone git@github.com:fireblocks/ew-backend-demo.git\n   cd ew-backend-demo\n   ```\n\n2. Install dependencies\n\n   ```bash\n   yarn install\n   ```\n\n3. Configure environment variables\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n4. Run database migrations\n\n   ```bash\n   yarn migration:run\n   ```\n\n5. Start the server\n   ```bash\n   yarn dev\n   ```\n\n### Configuration\n\nRequired environment variables:\n\n```env\n##### Server #####\nPORT=3000\nNODE_ENV=development\n\n##### Database #####\nDB_HOST=localhost\nDB_PORT=3306\nDB_USERNAME=db_user\nDB_PASSWORD=db_pwd\nDB_NAME=ew_demo\n\n##### Authentication #####\nJWKS_URI=your-jwks-uri\nISSUER=your-issuer\nAUDIENCE=your-audience\n\n##### Fireblocks Webhook Public Key #####\nFIREBLOCKS_WEBHOOK_PUBLIC_KEY= \"-----BEGIN PUBLIC KEY-----\\nMII...\"\"\n\n##### Firebase Service Account #####\nFIREBASE_SERVICE_ACCOUNT_PATH=path-to-yor-service-account-file\n\n##### Push Notifications #####\nVAPID_SUBJECT=mailto:your-email@example.com\nVAPID_PUBLIC_KEY=your-vapid-public-key\nVAPID_PRIVATE_KEY=your-vapid-private-key\n\n##### CORS Origins #####\nORIGIN_WEB_SDK=http://localhost:3000, https://your-domain.com\n```\n\n### Firebase Service Account File\n\nThe `FIREBASE_SERVICE_ACCOUNT_PATH` environment variable should point to a Firebase service account JSON file. This file is required for the backend to authenticate with Firebase Cloud Messaging (FCM) and send push notifications to Android and web clients.\n\n**How to obtain the service account file:**\n1. Go to the [Firebase Console](https://console.firebase.google.com/) and select your project.\n2. Navigate to **Project Settings** (gear icon) \u003e **Service Accounts**.\n3. Click **Generate new private key** under the Firebase Admin SDK section.\n4. Download the generated JSON file and save it securely (e.g., `firebase-service-account.json`).\n5. Set the `FIREBASE_SERVICE_ACCOUNT_PATH` variable in your `.env` file to the path of this JSON file (relative to the project root or as an absolute path).\n\n**Example:**\n```env\nFIREBASE_SERVICE_ACCOUNT_PATH=./firebase-service-account.json\n```\n\n**Security Best Practices:**\n- **Never commit your service account file to version control.** Add it to your `.gitignore`.\n- Store the file securely and restrict access to only trusted team members.\n- Rotate the key if you suspect it has been compromised.\n\n### VAPID Keys Configuration\n\nVAPID (Voluntary Application Server Identification) keys are required for Web Push notifications. These keys allow push services to identify your application server and ensure that only your server can send push notifications to your users.\n\n**How to generate VAPID keys:**\n\n1. **Using the web-push library (recommended):**\n   ```bash\n   npx web-push generate-vapid-keys\n   ```\n\n2. **Using Firebase CLI:**\n   ```bash\n   firebase login\n   firebase projects:list\n   firebase use \u003cyour-project-id\u003e\n   firebase messaging:generate-vapid-key\n   ```\n\n3. **Using the Firebase Console:**\n   - Go to the [Firebase Console](https://console.firebase.google.com/) and select your project\n   - Navigate to **Project Settings** (gear icon) \u003e **Cloud Messaging**\n   - Under the **Web configuration** section, click **Generate key pair**\n   - Copy the generated key pair\n\n**Setting up VAPID keys in your environment:**\n\n```env\nVAPID_SUBJECT=mailto:your-email@example.com\nVAPID_PUBLIC_KEY=your-vapid-public-key\nVAPID_PRIVATE_KEY=your-vapid-private-key\n```\n\n**Important notes:**\n- The `VAPID_SUBJECT` should be a valid email address or URL that identifies your application\n- The public key will be used by client applications to subscribe to push notifications\n- The private key is used by your server to sign push messages\n- **Never expose your VAPID private key** in client-side code or commit it to version control\n- The same VAPID key pair should be used consistently across your application\n\n**Client-side usage:**\nYour web clients will need the public key to register for push notifications. The backend exposes this via the `/api/notifications/vapid-public-key` endpoint.\n\n## Project Structure\n\n```\nsrc/\n├── controllers/      # Request handlers\n├── middleware/       # Auth and webhook middleware\n├── migrations/       # Database migrations\n├── model/            # Database models\n├── routes/           # API route definitions\n├── services/         # Business logic\n├── types/            # TypeScript type definitions\n└── util/             # Utility functions\n\nclient/\n├── examples/\n│   ├── react/        # React integration examples\n│   └── web/          # Web worker examples\n```\n\n## API Endpoints\n\n### Push Notification Registration\n\n```http\nPOST /api/notifications/register-token\nContent-Type: application/json\nAuthorization: Bearer your-token\n\n{\n  \"token\": \"firebase-device-token\",\n  \"platform\": \"android|ios|web-fcm\",\n  \"walletId\": \"your-embedded-wallet-id\",\n  \"deviceId\": \"optional-device-id\"\n}\n```\n\n```http\nPOST /api/notifications/register-subscription\nContent-Type: application/json\nAuthorization: Bearer your-token\n\n{\n  \"subscription\": {\n    \"endpoint\": \"https://push-service.url\",\n    \"keys\": {\n      \"auth\": \"auth-secret\",\n      \"p256dh\": \"public-key\"\n    }\n  },\n  \"walletId\": \"your-embedded-wallet-id\"\n}\n```\n\n### Web Push Setup\n\n```http\nGET /api/notifications/vapid-public-key\n```\n\n## Security Considerations\n\n- All endpoints require JWT authentication\n- Push tokens are tied to authenticated sessions\n- Notification payloads contain minimal data\n- Rate limiting prevents abuse\n- CORS is configured for allowed origins only\n- HTTPS required for web push\n\n## Development\n\n### Running Tests\n\n```bash\nyarn test\n```\n\n### Code Quality\n\n```bash\nyarn lint\nyarn format\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireblocks%2Few-backend-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffireblocks%2Few-backend-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireblocks%2Few-backend-demo/lists"}