{"id":31556142,"url":"https://github.com/jongan69/demo-lightning-app","last_synced_at":"2025-10-04T22:49:14.484Z","repository":{"id":307779783,"uuid":"1030676417","full_name":"jongan69/demo-lightning-app","owner":"jongan69","description":"A starting point for a react native lightning mobile app","archived":false,"fork":false,"pushed_at":"2025-08-02T05:19:48.000Z","size":882,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T08:16:20.988Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jongan69.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-02T04:56:43.000Z","updated_at":"2025-08-02T05:19:49.000Z","dependencies_parsed_at":"2025-08-02T08:16:32.546Z","dependency_job_id":"c221b616-c4f8-4348-84b5-1bdb97323d02","html_url":"https://github.com/jongan69/demo-lightning-app","commit_stats":null,"previous_names":["jongan69/demo-lightning-app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jongan69/demo-lightning-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2Fdemo-lightning-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2Fdemo-lightning-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2Fdemo-lightning-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2Fdemo-lightning-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jongan69","download_url":"https://codeload.github.com/jongan69/demo-lightning-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jongan69%2Fdemo-lightning-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278386116,"owners_count":25978109,"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-10-04T02:00:05.491Z","response_time":63,"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-10-04T22:49:12.605Z","updated_at":"2025-10-04T22:49:14.473Z","avatar_url":"https://github.com/jongan69.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lightning Taproot Assets Mobile App\n\nA complete Lightning Network Taproot Assets mobile application built with React Native and Rust, featuring a unified backend that combines Lightning wallet functionality with Taproot Assets gateway capabilities.\n\n## 🏗️ System Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Mobile App (React Native)\"\n        A[Dashboard] --\u003e B[LNC Service]\n        A --\u003e C[Taproot Service]\n        D[Settings] --\u003e B\n        E[Asset Management] --\u003e C\n        F[Transaction History] --\u003e C\n        B --\u003e G[Lightning Node Connect]\n        C --\u003e H[REST API Client]\n    end\n    \n    subgraph \"Unified Rust Backend\"\n        H --\u003e I[Axum Router]\n        I --\u003e J[/api/* - Lightning Wallet API]\n        I --\u003e K[/v1/taproot-assets/* - Gateway API]\n        I --\u003e L[/health - Health Checks]\n        \n        J --\u003e M[API Handlers]\n        K --\u003e N[Gateway Handlers]\n        \n        M --\u003e O[TapdClient]\n        N --\u003e O\n        O --\u003e P[Taproot Assets Daemon]\n        \n        M --\u003e Q[Database Layer]\n        N --\u003e Q\n        Q --\u003e R[(PostgreSQL)]\n    end\n    \n    subgraph \"Lightning Infrastructure\"\n        G -.-\u003e S[Lightning Node]\n        P --\u003e S\n        S --\u003e T[Bitcoin Network]\n    end\n    \n    style A fill:#e1f5fe\n    style I fill:#fff3e0\n    style S fill:#f3e5f5\n    style T fill:#e8f5e8\n```\n\n## 📋 Backend Architecture Deep Dive\n\n### 🔧 Module Structure\n\n```mermaid\ngraph LR\n    subgraph \"src/\"\n        A[main.rs] --\u003e B[Axum Router Setup]\n        \n        subgraph \"API Layer\"\n            C[api/] --\u003e D[handlers.rs]\n            C --\u003e E[routes.rs]\n            D --\u003e F[Lightning Wallet Endpoints]\n        end\n        \n        subgraph \"Gateway Layer\"\n            G[gateway/] --\u003e H[health.rs]\n            G --\u003e I[assets.rs]\n            G --\u003e J[addresses.rs]\n            G --\u003e K[wallet.rs]\n            G --\u003e L[info.rs]\n            G --\u003e M[routes.rs]\n        end\n        \n        subgraph \"Core Services\"\n            N[taproot/] --\u003e O[client.rs - TapdClient]\n            P[storage/] --\u003e Q[database.rs]\n            R[types.rs] --\u003e S[Shared Types]\n        end\n        \n        subgraph \"Support Modules\"\n            T[config.rs] --\u003e U[Configuration]\n            V[crypto.rs] --\u003e W[Cryptographic Utils]\n            X[error.rs] --\u003e Y[Error Handling]\n        end\n        \n        B --\u003e C\n        B --\u003e G\n        O --\u003e Z[Taproot Assets Daemon]\n        Q --\u003e AA[(PostgreSQL)]\n    end\n```\n\n### 🚀 API Endpoints\n\n#### Lightning Wallet API (`/api/*`)\n```bash\nGET  /api/assets                 # List all Taproot assets\nGET  /api/assets/balance         # Get asset balances  \nPOST /api/assets/send            # Send assets\nPOST /api/assets/address         # Create asset address\nPOST /api/assets/mint            # Mint new assets\nGET  /api/transactions           # Transaction history\n```\n\n#### Taproot Assets Gateway API (`/v1/taproot-assets/*`)\n```bash\n# Asset Management\nGET  /v1/taproot-assets/assets/list    # List assets from daemon\nPOST /v1/taproot-assets/assets/mint    # Mint assets via daemon\n\n# Address Management  \nGET  /v1/taproot-assets/addresses/list # List addresses\nPOST /v1/taproot-assets/addresses/new  # Create new address\n\n# Information \u0026 Health\nGET  /v1/taproot-assets/info           # Daemon info\nGET  /v1/taproot-assets/wallet/balance # Wallet balance\nGET  /health                           # Health check\nGET  /readiness                        # Readiness check\n```\n\n### 🔄 Data Flow Architecture\n\n```mermaid\nsequenceDiagram\n    participant MA as Mobile App\n    participant BE as Backend Router\n    participant AH as API Handler\n    participant GH as Gateway Handler\n    participant TC as TapdClient\n    participant TAD as Taproot Assets Daemon\n    participant DB as PostgreSQL\n    \n    Note over MA,TAD: Asset Transfer Flow\n    \n    MA-\u003e\u003eBE: POST /api/assets/send\n    BE-\u003e\u003eAH: Route to API Handler\n    AH-\u003e\u003eTC: Call TapdClient.send_asset()\n    TC-\u003e\u003eTAD: gRPC: SendAsset Request\n    TAD--\u003e\u003eTC: Asset Transfer Response\n    TC--\u003e\u003eAH: Transfer Details\n    AH-\u003e\u003eDB: Store Transaction\n    AH--\u003e\u003eMA: Success Response\n    \n    Note over MA,TAD: Gateway API Flow\n    \n    MA-\u003e\u003eBE: GET /v1/taproot-assets/assets/list\n    BE-\u003e\u003eGH: Route to Gateway Handler\n    GH-\u003e\u003eTC: Call TapdClient.list_assets()\n    TC-\u003e\u003eTAD: HTTP: List Assets Request\n    TAD--\u003e\u003eTC: Assets Data\n    TC--\u003e\u003eGH: Parsed Assets\n    GH--\u003e\u003eMA: JSON Response\n```\n\n## 📱 Frontend Architecture\n\n### 🧩 Component Hierarchy\n\n```mermaid\ngraph TD\n    A[App.tsx] --\u003e B[Navigation]\n    B --\u003e C[Dashboard]\n    B --\u003e D[Settings]\n    B --\u003e E[Asset Management]\n    \n    C --\u003e F[WalletBalance]\n    C --\u003e G[ChannelStatus]\n    C --\u003e H[NodeInfo]\n    \n    D --\u003e I[LNCConnection]\n    D --\u003e J[NodeConfiguration]\n    \n    E --\u003e K[AssetList]\n    E --\u003e L[AssetTransfer]\n    E --\u003e M[TransactionHistory]\n    \n    subgraph \"Services\"\n        N[LNCService]\n        O[TaprootService] \n        P[SecureStorage]\n    end\n    \n    F --\u003e N\n    G --\u003e N\n    H --\u003e N\n    K --\u003e O\n    L --\u003e O\n    M --\u003e O\n    I --\u003e P\n```\n\n### 🔐 Security Architecture\n\n```mermaid\ngraph LR\n    subgraph \"Mobile App Security\"\n        A[User Input] --\u003e B[SecureStore Encryption]\n        B --\u003e C[Encrypted Storage]\n        A --\u003e D[LNC Pairing]\n        D --\u003e E[End-to-End Encryption]\n    end\n    \n    subgraph \"Backend Security\"\n        F[CORS Protection] --\u003e G[Axum Router]\n        G --\u003e H[Request Validation]\n        H --\u003e I[Authenticated Requests]\n    end\n    \n    subgraph \"Network Security\"\n        E --\u003e J[WSS/HTTPS Only]\n        I --\u003e J\n        J --\u003e K[Lightning Network]\n        J --\u003e L[Taproot Assets Daemon]\n    end\n    \n    style B fill:#ffebee\n    style E fill:#ffebee\n    style F fill:#e8f5e8\n    style J fill:#fff3e0\n```\n\n## 🛠 Development Setup\n\n### Prerequisites\n- **Node.js 18+** and npm\n- **Rust 1.70+** and Cargo\n- **Expo CLI** (`npm install -g @expo/cli`)\n- **PostgreSQL** (optional for development)\n\n### Quick Start\n\n1. **Clone and setup:**\n   ```bash\n   git clone \u003crepository\u003e\n   cd lightning-app-mvp\n   ```\n\n2. **Start the unified backend:**\n   ```bash\n   cd backend\n   cargo run\n   ```\n   🚀 Backend runs on http://localhost:3000\n\n3. **Start the mobile app:**\n   ```bash\n   cd lightning-wallet-app\n   npm install\n   npm run dev\n   ```\n   📱 Access via Expo Go app or simulator\n\n### Lightning Node Setup\n\n```mermaid\ngraph LR\n    A[Lightning Terminal] --\u003e B[Generate Pairing Phrase]\n    B --\u003e C[litcli sessions add]\n    C --\u003e D[Enter in Mobile App]\n    D --\u003e E[Secure Connection]\n    E --\u003e F[Real Lightning Data]\n```\n\nTo connect to a real Lightning node:\n\n1. **Set up Lightning Terminal (litd)** with LNC enabled\n2. **Generate a pairing phrase:**\n   ```bash\n   litcli sessions add --label=\"Mobile App\" --type admin\n   ```\n3. **Enter credentials** in the app Settings → Connection\n\n## 🔧 Configuration\n\n### Backend Environment Variables\n```bash\n# Database\nDATABASE_URL=postgresql://postgres:password@localhost:5432/taproot_assets\n\n# Taproot Assets Integration\nTAPROOT_GATEWAY_URL=http://127.0.0.1:8080\n\n# Server Configuration  \nSERVER_HOST=0.0.0.0\nSERVER_PORT=3000\n\n# Logging\nRUST_LOG=info\n```\n\n### Frontend Configuration\n```typescript\n// App configuration in lightning-wallet-app/\nconst config = {\n  BACKEND_URL: 'http://localhost:3000',\n  LNC_WEBSOCKET: 'wss://your-node.com:8080',\n  DEFAULT_TIMEOUT: 30000\n};\n```\n\n## 🏗️ Database Schema\n\n```mermaid\nerDiagram\n    TRANSACTIONS {\n        uuid id PK\n        string tx_type\n        string asset_id\n        bigint amount\n        string status\n        timestamp created_at\n        timestamp updated_at\n    }\n    \n    ASSET_BALANCES {\n        string asset_id PK\n        bigint balance\n        timestamp updated_at\n    }\n    \n    TAPROOT_ASSETS {\n        string asset_id PK\n        string name\n        bigint balance\n        int decimals\n        string asset_type\n        json meta_data\n    }\n    \n    TRANSACTIONS ||--o{ TAPROOT_ASSETS : references\n    ASSET_BALANCES ||--|| TAPROOT_ASSETS : tracks\n```\n\n## 📋 Current Status\n\n### ✅ Completed Features\n\n#### Backend Infrastructure\n- [x] **Unified Rust Backend** - Combined Lightning wallet + Taproot gateway APIs\n- [x] **Axum Web Framework** - High-performance async web server\n- [x] **PostgreSQL Integration** - Database layer with SQLx\n- [x] **CORS Configuration** - Mobile app communication\n- [x] **Health Check Endpoints** - Service monitoring\n- [x] **Error Handling** - Comprehensive error types and responses\n\n#### Mobile Application\n- [x] **React Native Foundation** - Cross-platform mobile app\n- [x] **Lightning Node Connect** - Secure node connection via @lightninglabs/lnc-rn\n- [x] **Real-time Dashboard** - Live Lightning node data display\n- [x] **Secure Storage** - Encrypted credential management with Expo SecureStore  \n- [x] **Professional UI** - Dark theme and responsive design\n- [x] **Settings Management** - LNC pairing and configuration\n\n#### Integration Layer\n- [x] **TapdClient** - Taproot Assets daemon communication\n- [x] **REST API Structure** - Complete endpoint definitions\n- [x] **Type Definitions** - Shared Rust types for consistency\n- [x] **Configuration Management** - Environment-based config\n\n### 🚧 Integration Ready\n\n#### Taproot Assets Features\n- [ ] **Asset Minting** - Create new Taproot assets\n- [ ] **Asset Transfers** - Send/receive via Lightning Network\n- [ ] **Address Generation** - Create Taproot asset addresses\n- [ ] **Transaction History** - Complete audit trail\n- [ ] **Balance Tracking** - Real-time asset balances\n\n#### Enhanced Features\n- [ ] **Database Migrations** - Schema version management\n- [ ] **gRPC Integration** - Direct Taproot Assets daemon communication\n- [ ] **WebSocket Support** - Real-time updates\n- [ ] **Advanced Error Handling** - User-friendly error messages\n- [ ] **Testing Suite** - Comprehensive test coverage\n\n## 🧪 Testing\n\n### Backend API Testing\n```bash\n# Health checks\ncurl http://localhost:3000/health\ncurl http://localhost:3000/readiness\n\n# Lightning Wallet API\ncurl http://localhost:3000/api/assets\ncurl http://localhost:3000/api/transactions\n\n# Taproot Gateway API  \ncurl http://localhost:3000/v1/taproot-assets/info\ncurl http://localhost:3000/v1/taproot-assets/assets/list\n```\n\n### Mobile App Testing\n```bash\ncd lightning-wallet-app\nnpm run dev    # Start development server\nnpm test       # Run test suite (when implemented)\n```\n\n## 🔐 Security Features\n\n### Multi-Layer Security\n\n```mermaid\ngraph TD\n    A[User Authentication] --\u003e B[Secure Credential Storage]\n    B --\u003e C[End-to-End Encryption]\n    C --\u003e D[Network Security]\n    D --\u003e E[Backend Validation]\n    \n    A1[Password Protection] --\u003e A\n    A2[Biometric Auth] --\u003e A\n    \n    B1[Expo SecureStore] --\u003e B\n    B2[Device Keychain] --\u003e B\n    \n    C1[Lightning Node Connect] --\u003e C\n    C2[TLS/SSL] --\u003e C\n    \n    D1[HTTPS/WSS Only] --\u003e D\n    D2[Certificate Pinning] --\u003e D\n    \n    E1[Input Validation] --\u003e E\n    E2[Request Authentication] --\u003e E\n    \n    style A fill:#ffebee\n    style C fill:#e8f5e8\n    style E fill:#fff3e0\n```\n\n- **🔐 End-to-end encryption** via Lightning Node Connect\n- **🗝️ Encrypted credential storage** with user password protection\n- **🚫 No plaintext sensitive data** storage on device\n- **🔒 HTTPS/WSS communications** for all network requests\n- **🧹 Secure pairing phrase handling** with automatic cleanup\n- **✅ Input validation** and sanitization on all endpoints\n- **🛡️ CORS protection** and request rate limiting\n\n## 🚀 Deployment\n\n### Backend Deployment\n```bash\n# Production build\ncargo build --release\n\n# Docker deployment (create Dockerfile)\ndocker build -t lightning-backend .\ndocker run -p 3000:3000 lightning-backend\n```\n\n### Mobile App Deployment\n```bash\n# Build for app stores\ncd lightning-wallet-app\nexpo build:android\nexpo build:ios\n```\n\n## 📚 API Documentation\n\n### Response Formats\n\nAll API responses follow this structure:\n\n```typescript\ninterface ApiResponse\u003cT\u003e {\n  success: boolean;\n  data?: T;\n  error?: string;\n  message?: string;\n}\n```\n\n### Error Codes\n\n| Code | Description |\n|------|-------------|\n| 200  | Success |\n| 400  | Bad Request - Invalid input |\n| 401  | Unauthorized - Authentication required |\n| 404  | Not Found - Resource doesn't exist |\n| 500  | Internal Server Error |\n| 503  | Service Unavailable - Taproot daemon unreachable |\n\n---\n\n**Built with ❤️ for the Lightning Network community**\n\n*This project demonstrates the power of combining Lightning Network infrastructure with Taproot Assets for next-generation Bitcoin applications.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongan69%2Fdemo-lightning-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjongan69%2Fdemo-lightning-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjongan69%2Fdemo-lightning-app/lists"}