@www.hyperlinks.space/program-kit 1.2.3 → 1.2.91881

package/README.md

@@ -1,17 +1,18 @@
 # Program Kit
 
-Program Kit is a production-ready cross-platform starter published from `app/`.
+Program Kit is a production-ready cross-platform starter published from repository root.
 It is built around React Native + Expo and is designed to be quickly tested, scaled,
 and deployed across popular platforms.
 
 ## What You Get
 
 - Expo + React Native app foundation
-- Telegram bot support (webhook + local bot scripts)
+- Telegram bot support (webhook + local bot scripts) with AI functionality
 - Telegram Mini App-ready client structure
-- Android and iOS workflow scripts
+- Android and iOS clients
 - Windows desktop packaging (`.exe`) with Electron Builder
 - CI-oriented release workflow and deployment helpers
+- OpenAI functionality and Swap.Coffee for blockchain data retrievement
 
 ## Install
 
@@ -38,7 +39,7 @@ npm install
 npm run start
 ```
 
-Then open the project `README.md` for full setup details (env vars, bot setup, build
+Then open the project **`fullREADME.md`** for details (env vars, bot setup, build
 and release commands).
 
 ## Release Channels
@@ -50,4 +51,3 @@ and release commands).
 
 - Published directly from the `app/` folder.
 - Package tarball is filtered to include only required project files.
-- **`fullREADME.md`** in the package is the full in-repo developer guide (Expo setup, scripts, and the rest of the project readme).

package/app/_layout.tsx

@@ -2,12 +2,11 @@ import "../global.css";
 import { View, StyleSheet, Platform, KeyboardAvoidingView, AppState, Alert } from "react-native";
 import { Stack } from "expo-router";
 import * as Updates from "expo-updates";
-import { TelegramProvider } from "./components/Telegram";
-import { GlobalLogoBarWithFallback } from "./components/GlobalLogoBarWithFallback";
-import { GlobalBottomBar } from "./components/GlobalBottomBar";
-import { GlobalBottomBarWeb } from "./components/GlobalBottomBarWeb";
-import { useColors } from "./theme";
-import { useTelegram } from "./components/Telegram";
+import { TelegramProvider, useTelegram } from "../ui/components/Telegram";
+import { GlobalLogoBarWithFallback } from "../ui/components/GlobalLogoBarWithFallback";
+import { GlobalBottomBar } from "../ui/components/GlobalBottomBar";
+import { GlobalBottomBarWeb } from "../ui/components/GlobalBottomBarWeb";
+import { useColors } from "../ui/theme";
 import { useEffect, useRef } from "react";
 
 /**

package/app/index.tsx

@@ -1,5 +1,5 @@
 import { Text, View } from "react-native";
-import { useTelegram } from "./components/Telegram";
+import { useTelegram } from "../ui/components/Telegram";
 
 export default function Index() {
   const { status, telegramUsername, error, debug } = useTelegram();

package/database/start.ts

@@ -5,9 +5,7 @@ import path from "path";
 // In Vercel Lambdas these files don't exist, so these calls are harmless no-ops.
 const cwd = process.cwd();
 dotenv.config({ path: path.join(cwd, ".env") });
-dotenv.config({ path: path.join(cwd, "app", ".env") });
 dotenv.config({ path: path.join(cwd, ".env.local") });
-dotenv.config({ path: path.join(cwd, "app", ".env.local") });
 import { neon } from "@neondatabase/serverless";
 
 const connectionString = process.env.DATABASE_URL;
@@ -15,7 +13,7 @@ const connectionString = process.env.DATABASE_URL;
 if (!connectionString) {
   // Fail fast on the server side so misconfiguration is obvious in logs.
   throw new Error(
-    "DATABASE_URL is not set. Configure it in ./app/.env for the current Neon branch.",
+    "DATABASE_URL is not set. Configure it in ./.env for the current Neon branch.",
   );
 }
 

package/docs/build_and_install.md

@@ -5,14 +5,14 @@ This doc describes the Windows Electron build and install flow and how to speed
 Exe creating example:
 
 ```
-cd /d C:\1\1\1\1\1\HyperlinksSpaceProgram\app
+cd /d C:\1\1\1\1\1\HyperlinksSpaceProgram
 npm run build:win:verbose
 ```
 
 Exe bash run example:
 
 ```
-powershell -NoProfile -Command "Start-Process -FilePath 'C:/1/1/1/1/1/HyperlinksSpaceBot/app/releases/builder/build_03252026_1449/HyperlinksSpaceProgramInstaller_03252026_1449.exe'"
+powershell -NoProfile -Command "Start-Process -FilePath 'C:/1/1/1/1/1/HyperlinksSpaceBot/releases/builder/build_03252026_1449/HyperlinksSpaceProgramInstaller_03252026_1449.exe'"
 ```
 
 ---
@@ -33,7 +33,7 @@ powershell -NoProfile -Command "Start-Process -FilePath 'C:/1/1/1/1/1/Hyperlinks
 
 | Goal | What to do |
 |------|------------|
-| **Skip Expo when only Electron changed** | Use `npm run pack:win` when `dist/` is already up to date (no app/Expo changes). Saves the full Expo/Metro run (often 30–60+ s). |
+| **Skip Expo when only Electron changed** | Use `npm run pack:win` when `dist/` is already up to date (no Expo app changes). Saves the full Expo/Metro run (often 30–60+ s). |
 | **Skip native rebuild** | In `package.json` → `build`, add `"npmRebuild": false`. The packaged app only runs the web bundle; native rebuild can often be skipped. Try it; if the app runs, keep it. Saves time every build. |
 | **Avoid building the installer when iterating** | Use `npm run build:win:dir` when you only need the unpacked app (e.g. quick runs from `release/win-unpacked/app.exe`). Skips NSIS and clean; faster and no “file locked” risk. |
 | **Keep caches** | Don’t clear Metro/Expo cache unless needed. Electron and electron-builder caches (e.g. under `%LOCALAPPDATA%\electron-builder\Cache`) are reused; leave them. |
@@ -43,7 +43,7 @@ powershell -NoProfile -Command "Start-Process -FilePath 'C:/1/1/1/1/1/Hyperlinks
 ### Rebuilding only what changed
 
 - **Caches:** Expo/Metro and electron-builder already use caches. A full `build:win` reuses cached transforms and packed files where nothing changed, so rebuilds are partly incremental by default.
-- **Skip the web build when only Electron changed:** If you only changed `windows/build.cjs` or other files in `windows/`, the icon, or `package.json` build config (not the React/app code), run **`npm run pack:win`** instead of `build:win`. That runs only electron-builder + clean and reuses the existing `dist/`. Ensure `dist/` is up to date (run `npm run build` once, or after any app/Expo changes).
+- **Skip the web build when only Electron changed:** If you only changed `windows/build.cjs` or other files in `windows/`, the icon, or `package.json` build config (not the React app code), run **`npm run pack:win`** instead of `build:win`. That runs only electron-builder + clean and reuses the existing `dist/`. Ensure `dist/` is up to date (run `npm run build` once, or after any Expo app changes).
 
 ---
 
@@ -89,8 +89,8 @@ User runs **`HyperlinksSpaceProgramInstaller.exe`**. NSIS extracts the app (e.g.
 
 ## 5. File layout after build
 
-- **After `build:win` or `pack:win`:** `app/releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` and `app/releases/builder/build_MMDDYYYY_HHMM/dev/` (portable zip, yml, win-unpacked, blockmap, builder-debug.yml, builder-effective-config.yaml).
-- **After `build:win:dir`:** `app/release/win-unpacked/` (run `app.exe` from there).
+- **After `build:win` or `pack:win`:** `releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` and `releases/builder/build_MMDDYYYY_HHMM/dev/` (portable zip, yml, win-unpacked, blockmap, builder-debug.yml, builder-effective-config.yaml).
+- **After `build:win:dir`:** `release/win-unpacked/` (run `app.exe` from there).
 - **Build inputs:** `dist/` (Expo export), `windows/` (build.cjs, app-shell.html, preload-log.cjs), `assets/icon.ico`, and files listed under `build.files` in `package.json`.
 
 ---

package/docs/npm-release.md

@@ -0,0 +1,46 @@
+# Milestone snapshot package (npm)
+
+This repository includes a publishable snapshot package for fast developer bootstrap:
+
+- package source: repository root (published directly)
+- **npmjs (public):** `@www.hyperlinks.space/program-kit` — manage org and tokens: [www.hyperlinks.space on npm](https://www.npmjs.com/settings/www.hyperlinks.space/packages)
+- **GitHub Packages:** `@hyperlinksspace/program-kit` (same version; GitHub requires the package scope to match this repo's owner)
+
+## Verify publish payload locally
+
+The npm package page uses `README.md` from the published tarball, not `npmReadMe.md`. The published package also includes **`fullREADME.md`**, a copy of the developer readme (saved before the npm readme replaces `README.md`). Match CI before `npm pack`, then restore:
+
+```bash
+cp README.md fullREADME.md
+cp npmReadMe.md README.md
+npm pack --dry-run
+git checkout -- README.md
+rm -f fullREADME.md
+```
+
+## Install snapshot as a developer
+
+```bash
+npx @www.hyperlinks.space/program-kit ./my-hsp-app
+```
+
+The CLI materializes the bundled package payload into your target folder, then you run:
+
+```bash
+cd my-hsp-app
+npm install
+```
+
+## Release channels
+
+- `latest`: immutable stable snapshots (tag workflow `snapshot-vX.Y.Z`)
+- `next`: rolling snapshots from manual workflow dispatch
+
+In the output, you'll find options to open the app in:
+
+- [a development build](https://docs.expo.dev/develop/development-builds/introduction/)
+- [an Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
+- [an iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
+- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+
+You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).

package/docs/releases.md

@@ -12,7 +12,7 @@ This document defines the production plan for release detection, deduped GitHub
 ## Source of Truth
 
 - The **GitHub Release tag** is the release identity (`release_id`), for example `build_03252026_1929`.
-- Locally, `windows/cleanup.cjs` moves the built installer to `app/releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other artifacts under `dev/`). In CI you can set `RELEASE_BUILD_ID` to match a chosen tag, or leave it unset so the folder name comes from build time.
+- Locally, `windows/cleanup.cjs` moves the built installer to `releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other artifacts under `dev/`). In CI you can set `RELEASE_BUILD_ID` to match a chosen tag, or leave it unset so the folder name comes from build time.
 
 ## Workflow Trigger
 
@@ -51,7 +51,7 @@ Recommended extra safety:
 
 ## Endpoint Contract
 
-- Webhook endpoint path: `app/api/releases.ts`
+- Webhook endpoint path: `api/releases.ts`
 - Route URL: `POST /api/releases`
 - Purpose: accept release-published events from GitHub Actions and fan out update notifications to app clients.
 
@@ -89,7 +89,7 @@ If auth fails:
 }
 ```
 
-## Endpoint Behavior (`app/api/releases.ts`)
+## Endpoint Behavior (`api/releases.ts`)
 
 1. Accept only `POST`.
 2. Validate auth token/signature.
@@ -184,7 +184,7 @@ Client behavior:
 
 ## Rollout Plan
 
-1. Deploy `app/api/releases.ts` in staging.
+1. Deploy `api/releases.ts` in staging.
 2. Run workflow in dry-run mode to validate folder parsing and dedupe checks.
 3. Enable real release creation for test folder.
 4. Enable webhook call to staging endpoint.
@@ -193,7 +193,7 @@ Client behavior:
 
 ## Acceptance Criteria
 
-- A new `app/releases/builder/build_.../` folder produces exactly one GitHub Release.
+- A new `releases/builder/build_.../` folder produces exactly one GitHub Release.
 - Re-running workflow for the same `release_id` does not create duplicates.
 - Webhook is called only for newly created releases.
 - `POST /api/releases` rejects unauthorized requests.

package/docs/releases_github_actions.md

@@ -12,7 +12,7 @@ This document defines the production plan for release detection, deduped GitHub
 ## Source of Truth
 
 - The **GitHub Release tag** is the release identity (`release_id`), for example `build_03252026_1929`.
-- Locally and in CI, `windows/cleanup.cjs` places the installer under `app/releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other files under `dev/`). In CI, set `RELEASE_BUILD_ID` to pin the folder/tag, or omit it to use the timestamp from build time.
+- Locally and in CI, `windows/cleanup.cjs` places the installer under `releases/builder/build_MMDDYYYY_HHMM/HyperlinksSpaceProgramInstaller_<stamp>.exe` (other files under `dev/`). In CI, set `RELEASE_BUILD_ID` to pin the folder/tag, or omit it to use the timestamp from build time.
 
 ## When You Must Make a New Installer Release
 
@@ -78,7 +78,7 @@ Recommended extra safety:
 
 ## Endpoint Contract
 
-- Webhook endpoint path: `app/api/releases.ts`
+- Webhook endpoint path: `api/releases.ts`
 - Route URL: `POST /api/releases`
 - Purpose: accept release-published events from GitHub Actions and fan out update notifications to app clients.
 
@@ -116,7 +116,7 @@ If auth fails:
 }
 ```
 
-## Endpoint Behavior (`app/api/releases.ts`)
+## Endpoint Behavior (`api/releases.ts`)
 
 1. Accept only `POST`.
 2. Validate auth token/signature.
@@ -171,7 +171,7 @@ Client behavior:
 
 ## Rollout Plan
 
-1. Deploy `app/api/releases.ts` in staging.
+1. Deploy `api/releases.ts` in staging.
 2. Run workflow in dry-run mode to validate folder parsing and dedupe checks.
 3. Enable real release creation for test folder.
 4. Enable webhook call to staging endpoint.
@@ -180,7 +180,7 @@ Client behavior:
 
 ## Acceptance Criteria
 
-- A new `app/releases/builder/build_.../` folder produces exactly one GitHub Release.
+- A new `releases/builder/build_.../` folder produces exactly one GitHub Release.
 - Re-running workflow for the same `release_id` does not create duplicates.
 - Webhook is called only for newly created releases.
 - `POST /api/releases` rejects unauthorized requests.

package/docs/security_plan_raw.md

@@ -1,6 +1,6 @@
 # Security Implementation Plan (Telegram-First Wallet)
 
-This file describes a practical implementation plan for the security model defined in `security.md`, focused on the `./app` (Expo / Vercel) codebase and a serverless backend.
+This file describes a practical implementation plan for the security model defined in `security.md`, focused on the repository-root Expo/Vercel codebase and a serverless backend.
 
 ---
 
@@ -13,7 +13,7 @@ This file describes a practical implementation plan for the security model defin
   - Confirm `telegram-web-app.js` is loaded in the Mini App shell.
 
 - **0.2. Serverless backend basics**
-  - Use existing Vercel project (`./app`) API routes:
+  - Use existing Vercel project (repository root) API routes:
     - Create a shared util for **Telegram initData validation** (WebApp) in `api/_lib/telegram.ts`:
       - `validateInitData(initData: string): { username: string }`.
     - Create a shared util for **Telegram Login widget validation** (web/native) in `api/_lib/telegram_login.ts`:
@@ -101,7 +101,7 @@ This file describes a practical implementation plan for the security model defin
 
 ## Phase 2 – iOS/Android App Flow (Single App)
 
-(All implemented inside `./app` using Expo Router / React Native.)
+(All implemented in the repository root app using Expo Router / React Native.)
 
 - **2.1. Local state**
   - Add a simple secure storage wrapper (e.g. `expo-secure-store`):
@@ -123,7 +123,7 @@ This file describes a practical implementation plan for the security model defin
         - Opens a WebView or browser to hosted login page (e.g. `/login/telegram`).
 
 - **2.3. Telegram Login for Websites (web page + API)**
-  - Create a web page (static route in `./app` or separate) that:
+  - Create a web page (static route in repository root or separate) that:
     - Embeds the Telegram Login widget configured for your bot & domain.
     - On success, posts the payload (via `data-onauth` callback) to `POST /api/login/telegram`.
   - `POST /api/login/telegram`:

package/docs/security_raw.md

@@ -129,7 +129,7 @@ For platforms outside Telegram (web, desktop app, native mobile app not running
 
 ## IV. Android / iOS (Single App, Telegram‑Centric Flow)
 
-We ship **one app** (the current `./app` Expo app) to iOS/Android stores. On mobile, the app acts as a shell that:
+We ship **one app** (the current Expo app at repository root) to iOS/Android stores. On mobile, the app acts as a shell that:
 
 - Explains why wallet creation happens in Telegram.
 - Sends the user into the Telegram Mini App to actually create the wallet.
@@ -212,7 +212,7 @@ For a user who already has a Telegram wallet (created earlier in the Mini App):
 
 **Key points of this model**
 
-- There is **one app** (`./app`), not a separate companion; mobile just has a Telegram‑centric onboarding path.
+- There is **one app** (repository root), not a separate companion; mobile just has a Telegram-centric onboarding path.
 - All wallet creation and key material remain in the Telegram Mini App and its SecureStorage/CloudStorage environment.
 - The iOS/Android app uses:
   - **Telegram Login for Websites** to learn “who is this user?” (via `username`),

package/docs/timing_raw.md

@@ -4,11 +4,11 @@
 
 **Important:** The app will not be sent to platforms (store/listing) before it is fully finished. So **MVP launch = full product launch**, and the realistic estimate is **3 months**.
 
-## Transfer layout to `./app` (TypeScript) — build on new architecture
+## Transfer layout to repository root (TypeScript) — build on new architecture
 
-The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app in `front/` is the **reference layout** (web pages, flows, structure). The work is to **transfer that layout and flows into `./app` in TypeScript** and make everything work there, with **security plan compliance** (see `docs/security_plan.md`). The production Mini App is the TS app in `./app` (Expo/React), backed by the same repo’s API and DB.
+The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app in `front/` is the **reference layout** (web pages, flows, structure). The work is to **transfer that layout and flows into the repository root app in TypeScript** and make everything work there, with **security plan compliance** (see `docs/security_plan.md`). The production Mini App is the TS app at repository root (Expo/React), backed by the same repo’s API and DB.
 
-### Pages to implement in `./app` (TS) — from `front/` reference
+### Pages to implement in repository root (TS) — from `front/` reference
 
 - **Bootstrap** – initData auth, config from API, wallet warm-up.
 - **Main** – home / hub after bootstrap.
@@ -23,7 +23,7 @@ The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app i
 - **Mnemonics** – mnemonic display/backup (security plan).
 - **Wallet panel** – wallet panel page.
 
-### Services / wiring in `./app` (TS)
+### Services / wiring in repository root (TS)
 
 | Concern | Role | Backend / compliance |
 |--------|------|-----------------------|
@@ -31,7 +31,7 @@ The goal is **not** to finish the Flutter app in `front/`. The **Flutter** app i
 | **AI** | Chat with AI via same-origin `/api/ai` (or app’s AI route). | Already in `app`; ensure config, keys, and error handling in prod. |
 | **Wallet** | Mnemonic generation, storage, key derivation (client-side). | Security plan: SecureStorage/CloudStorage, wallet registration (`POST /api/wallet/register`), device auth flow; optional TonConnect later. |
 
-### API surface (in `./app`)
+### API surface (in repository root)
 
 - **`/api/telegram`** (or init) – initData validation, user upsert.
 - **`/api/ai`** – AI proxy; used by the TS app.
@@ -56,8 +56,8 @@ Completion order and stages:
 | Stage | Scope | Estimate | Notes |
 |-------|--------|----------|--------|
 | **1** | **Security plan implementation** | **~3 weeks** | Phase 0 (validation, DB), Phase 1 (wallet creation, device auth, register), Phase 2 (pending tx, confirmations). |
-| **2** | **App (TS) – pages & UX** | **~3 weeks** | Transfer layout from `front/` and implement all pages in `./app` (send, swap, wallets, apps, AI, get, trade, creators, mnemonics, wallet panel); layout and navigation solid. |
-| **3** | **App (TS) – services & wiring** | **~3 weeks** | Auth, AI, and wallet flows in `./app`; backend alignment; errors and edge cases. |
+| **2** | **App (TS) – pages & UX** | **~3 weeks** | Transfer layout from `front/` and implement all pages in repository root app (send, swap, wallets, apps, AI, get, trade, creators, mnemonics, wallet panel); layout and navigation solid. |
+| **3** | **App (TS) – services & wiring** | **~3 weeks** | Auth, AI, and wallet flows in repository root app; backend alignment; errors and edge cases. |
 | **4** | **Integration, testing, finishing** | **~3 weeks** | E2E, platform checks, store/listing readiness, app/plan and root plan items (formatting, theme, bugs, features). |
 
 **MVP launch (full finish, platform-ready):** **~3 months** (12 weeks).

package/docs/update.md

@@ -10,7 +10,7 @@ This plan defines how to deliver near-instant updates for the app with minimal u
   - Target latency: minutes or less after publish.
 - **Lane B: Binary releases (slow path)**
   - Use installer/store release only when native/runtime changes are required.
-  - Triggered through `app/releases/**` and GitHub Release workflow.
+  - Triggered through `releases/**` and GitHub Release workflow.
 
 Decision rule:
 
@@ -21,9 +21,9 @@ Decision rule:
 
 Already configured:
 
-- `app/app.json` has `updates.url`.
-- `app/app.json` has `runtimeVersion.policy = appVersion`.
-- `app/eas.json` has channels:
+- `app.json` has `updates.url`.
+- `app.json` has `runtimeVersion.policy = appVersion`.
+- `eas.json` has channels:
   - preview profile -> `main`
   - production profile -> `production`
 
@@ -40,7 +40,7 @@ Implication:
 
 For binary-only updates:
 
-1. `app/releases/builder/build_MMDDYYYY_HHMM/` (or Forge under `app/releases/forge/...`) changes.
+1. `releases/builder/build_MMDDYYYY_HHMM/` (or Forge under `releases/forge/...`) changes.
 2. GitHub workflow dedupes and creates Release if new.
 3. Workflow calls `POST /api/releases` webhook.
 4. Backend notifies clients that binary update is available.
@@ -64,11 +64,11 @@ Create workflow `.github/workflows/eas-update.yml`:
   - Optional `workflow_dispatch`
 - Path filters to avoid unnecessary publishes (example):
   - include app source and config paths
-  - exclude `app/releases/**`
+  - exclude `releases/**`
 - Steps:
   1. checkout
   2. setup node
-  3. install deps (`npm ci` in `app/`)
+  3. install deps (`npm ci` in repository root)
   4. publish OTA:
      - branch `main` for preview/internal
      - branch `production` for production
@@ -80,7 +80,7 @@ Recommended publish command:
 
 ### 4.3 Binary Workflow (Already Planned)
 
-Keep `app/releases/**` workflow with dedupe:
+Keep `releases/**` workflow with dedupe:
 
 - If release exists, skip.
 - If new, create GitHub Release and upload assets.
@@ -170,7 +170,7 @@ Phase 3 - Hardening:
 
 ### Publish OTA update
 
-From `app/`:
+From repository root:
 
 - `npx eas update --branch main --message "fix: ..."`
 - for production:
@@ -178,7 +178,7 @@ From `app/`:
 
 ### Publish binary update
 
-1. Create `app/releases/builder/build_MMDDYYYY_HHMM/` with installer at root and supporting files under `dev/`.
+1. Create `releases/builder/build_MMDDYYYY_HHMM/` with installer at root and supporting files under `dev/`.
 2. Push changes.
 3. Workflow creates (or skips duplicate) GitHub Release and calls `/api/releases`.
 
@@ -198,7 +198,7 @@ From `app/`:
 
 ## 12) Next Implementation Tasks
 
-1. Create `app/api/releases.ts` endpoint.
+1. Create `api/releases.ts` endpoint.
 2. Add `.github/workflows/eas-update.yml`.
 3. Add client update service wrapper (`check/fetch/apply` policy).
 4. Add docs section in `build_and_install.md` linking OTA vs binary rules.

package/docs/wallet_telegram_standalone_multichain_proposal.md

@@ -0,0 +1,192 @@
+# Unified Wallet Model: Telegram, Standalone, Multi-Chain & DLLR (TON)
+
+This document proposes a single coherent setup for the tensions between:
+
+- A **Telegram-first** experience (Mini App, bot confirmations, CloudStorage-assisted UX).
+- **Standalone operation** when Telegram is unavailable, blocked, or the user simply prefers not to use it.
+- **Non-custodial** custody: keys and mnemonics never held by our servers.
+- **DLLR** and core product flows anchored on **TON**, where issuance and program logic are expected to live.
+- **Multiple chains** where users may hold assets or use bridges, without fragmenting identity or safety.
+
+It complements `wallets_hosting_architecture.md`, `security_raw.md`, and `security_plan_raw.md` by resolving “which path wins when” and how they fit together.
+
+---
+
+## 1. Core idea: one logical wallet, three *surfaces*
+
+Think in terms of **one user-owned root of trust** (mnemonic for the primary TON wallet, and optional additional key material for other chains), and **three ways to use it**:
+
+| Surface | What it is | Best for |
+|--------|------------|----------|
+| **A. Telegram-hosted (TMA)** | Same non-custodial keys; encrypted material split between Telegram `SecureStorage` + `CloudStorage` (ciphertext only), identity via `initData`. | Smoothest UX inside Telegram, bot-driven tx confirmation, push-to-sign. |
+| **B. Unhosted / standalone** | Keys only on device OS keystore / WebCrypto; no Telegram APIs required to open the app or sign. | Telegram outage, privacy preference, store-review-friendly “works without Telegram”. |
+| **C. Connected** | External wallets via **TON Connect** (TON) and, later, analogous **WalletConnect** / chain-specific SDKs for other networks. | Power users, hardware wallets, assets already elsewhere. |
+
+**Important:** Surfaces are **not** different custodial models. They differ only in **where keys live** and **which transport** is used for identity and sync. The backend stores **public** data (addresses, `telegram_username` ↔ address mapping when the user opts in), never mnemonics.
+
+---
+
+## 2. Why Telegram alone is not enough (and how we fix it)
+
+Telegram can be unreachable (outage, censorship, user choice). A product that *only* creates or signs inside the Mini App forces a hard dependency on Telegram for custody and signing.
+
+**Proposal:**
+
+1. **Default recommended path** remains: create primary **TON** wallet in TMA (best onboarding, aligns with bot + DLLR messaging).
+2. **Mandatory parallel capability:** the same app build supports **Create / Restore wallet locally** (standalone) with **no Telegram account** and **no bot call** for key generation.
+3. **Linking layer (optional):** if the user *has* Telegram, they can **link** `telegram_username` ↔ `wallet_address` so CloudStorage sync and bot confirmations work. If they never link, they remain fully standalone; DLLR/Ton features still work on-chain by address.
+4. **Degraded mode:** if Telegram is down but the user already has keys on device, the app runs **full local signing** for TON (and any chain we have implemented client-side). Features that *require* the bot (e.g. push approval via Telegram) show a clear “Unavailable while Telegram is unreachable” with fallback: open pending items in TMA later, or confirm via standalone signing if the flow allows.
+
+This matches non-custodial rules: the server never becomes the signing authority.
+
+---
+
+## 3. DLLR on TON as the canonical product wallet
+
+**Clarification to remove confusion:**
+
+- **Primary app wallet** = **TON** address derived from the user’s main mnemonic (or from a TON Connect wallet they set as default).
+- **DLLR** is treated as a **TON jetton / program** (or locked-state construct per your issuance design). Balances, locks, and allocations are **read and signed on TON**.
+- “Multi-chain” does **not** mean DLLR exists on every chain. It means:
+  - **User may connect other addresses** for portfolio view, bridges, or future features.
+  - **Product-critical flows** (rewards, locks, compliance hooks tied to DLLR) stay **TON-first**.
+
+**UI rule:** always show a clear **“Primary (TON + DLLR)”** section, then **“Other networks”** as secondary, so expectations stay aligned with issuance on TON.
+
+---
+
+## 4. Multi-chain matrix (recommended model)
+
+Use a single **wallet registry** in the client and the `wallets` table (as in `security_plan_raw.md`), with explicit `blockchain`, `net`, and `type`:
+
+| Type | Example | Custody |
+|------|---------|--------|
+| `internal` | App-generated TON keypair | Non-custodial; keys in device/TMA storage |
+| `tonconnect` | Tonkeeper, MyTonWallet | User’s external wallet; we only hold address + session |
+| `walletconnect` / `evm` / `solana` (future) | MetaMask, Phantom, … | Same: address + connection state |
+
+**Telegram-hosted vs unhosted** applies only to **`internal`** wallets:
+
+- In TMA, `internal` wallet uses SecureStorage + CloudStorage ciphertext split.
+- In standalone app, `internal` wallet uses only OS secure storage (same cryptography, different storage adapters).
+
+**Connected** wallets are **always** “hosted” by the third-party provider, not by Telegram and not by us.
+
+---
+
+## 5. Identity: Telegram as optional glue, not a single gate
+
+Today’s docs lean **Telegram-first** for onboarding. The unified model adds:
+
+| User state | Can use app? | DLLR / TON actions |
+|------------|--------------|--------------------|
+| Standalone, never linked Telegram | Yes (after local create/restore) | Yes, if keys on device |
+| Telegram user, wallet only in TMA | Yes in TMA; on mobile/web after Telegram Login | Signing in TMA; read-only elsewhere unless mnemonic imported locally (optional advanced) |
+| Linked Telegram + local keys | Yes everywhere | Full: bot confirmations where implemented + local signing fallback |
+
+**Backend:**
+
+- `users.telegram_username` is **nullable** for standalone-only users, or use a separate **account id** (emailless) keyed by device-chosen identifier only for analytics—not for custody.
+- Linking Telegram is a **deliberate** step: “Connect Telegram for notifications and faster sync.”
+
+---
+
+## 6. First run and subsequent runs (program behavior)
+
+This section describes what the **client program** does on **cold start** (first launch or fresh install) versus **later launches** on the same install, for each major surface. It aligns with the state machine in `wallets_hosting_architecture.md` (e.g. `awallet_v1`, deploy status).
+
+### 6.1 Shared startup sequence (all surfaces)
+
+1. **Bootstrap UI shell** — Router loads; global providers start (network, wallet context).
+2. **Detect environment** — `TMA` (Telegram WebApp present) vs **standalone** (Expo native / open web) vs **web + Telegram Login** (widget session).
+3. **Resolve wallet presence** — Read local secure storage keys (`awallet_v1` or equivalent): encrypted blob for `internal` wallet, plus any **connected** wallet session handles (TON Connect).
+4. **Branch:**
+   - **No wallet record** → onboarding (Section 6.2).
+   - **Wallet record present** → main app (Section 6.3).
+
+Balances and DLLR/TON state are **always** refreshed asynchronously after UI is usable (do not block first paint on RPC unless product requires it).
+
+---
+
+### 6.2 First run (no wallet on this install)
+
+| Entry | What the user sees | What the program does |
+|--------|--------------------|------------------------|
+| **Telegram Mini App** | Intro → **Create wallet** / **Restore wallet** (optional **Connect Tonkeeper** if offered). | Generates mnemonic locally; stores **wallet master key** in Telegram `SecureStorage`; stores **seed ciphertext** in `CloudStorage`; registers **public** `wallet_address` (+ `telegram_username` from `initData`) with backend. Shows address and QR immediately; may show **Deploying** for SMC/jetton setup; nudges **backup seed**. |
+| **Standalone (native / web, no Telegram)** | Same choice: **Create** / **Restore** / **Connect** external wallet. | Generates or imports keys using **only** OS keystore / WebCrypto; **no** `initData`, **no** CloudStorage unless user later links Telegram. Optional backend call with a **non-Telegram** account id or anonymous mode until linked. |
+| **Store mobile app (Telegram-centric onboarding)** | Per `security_raw.md`: “Create wallet in Telegram” vs “I already have a wallet” + **Log in with Telegram**. | First path deep-links to TMA; second uses **Telegram Login** to fetch **public** linkage (`username` → `wallet_address`) for **read-only** until user imports mnemonic on device (if you add that flow). |
+
+**First run, new Telegram device (TMA):** `CloudStorage` may already hold **ciphertext** from another device, but **SecureStorage** is empty → program shows **Authorize this device** and asks for **mnemonic once**, then writes local master key and proceeds as normal.
+
+**First run, connected wallet only (TON Connect):** No internal blob; program stores connection session + address; primary balance flows use that address until user adds an `internal` wallet.
+
+---
+
+### 6.3 Subsequent runs (wallet already on this device)
+
+| Condition | Program behavior |
+|-----------|------------------|
+| **Encrypted blob + device key present** | **Silent load:** decrypt wallet, navigate to **home / wallet** without asking for seed. Poll `/wallet/status` or chain APIs for **deploy status**, **TON balance**, **DLLR** state. If deploy was **pending**, **retry deploy** in background (same as `wallets_hosting_architecture.md`). |
+| **TMA + CloudStorage ciphertext + SecureStorage OK** | Same silent path; CloudStorage may sync updates from other Telegram clients. |
+| **Standalone + keys in local secure storage** | Same as row 1; **no** Telegram dependency for open or sign. |
+| **User opened “Log in with Telegram” on mobile** | After verified login, app loads **cached** `telegram_username` + **addresses** from API; UI is **read-first** until local signing is enabled (mnemonic import), matching your phased plan. |
+| **Telegram unavailable (outage / blocked)** | If keys exist locally: **full app** for signing and reads that do not need the bot. If keys exist **only** in TMA on a device that cannot open Telegram: user must use **restore** on standalone build or wait for Telegram. Features that need the bot show **degraded / queue** messaging. |
+| **App update** | Same storage keys (`awallet_v1` versioning); run **migration** if blob format bumps. Wallet survives update if paths are stable. |
+
+**Subsequent run UX expectations:** back up seed remains **dismissible** until acknowledged; high-value actions may still route through **pending tx + bot confirmation** when Telegram is linked and the flow requires it.
+
+---
+
+### 6.4 Summary table
+
+| | First run | Subsequent runs |
+|---|-----------|-----------------|
+| **Typical path** | Onboarding → create / restore / connect | Silent unlock → home → background balance/deploy sync |
+| **Telegram required?** | Only for TMA path or Telegram-login shell | No, if standalone keys exist; yes for TMA-specific features |
+| **Seed prompt** | At creation (show once) or restore; optional “authorize device” on new TMA device | Only if blob missing, storage wiped, or user hits **Restore** |
+
+---
+
+## 7. “Perfect setup” summary (one paragraph)
+
+**Ship one Expo app** with three entry modes: (1) **Telegram Mini App** for best-in-class onboarding, CloudStorage-backed ciphertext sync, and bot-mediated confirmations; (2) **standalone** create/restore so the app **always launches** and can sign TON (and DLLR) without Telegram; (3) **TON Connect + future multi-chain connectors** for imported liquidity and power users. Treat **TON + DLLR** as the single source of truth for product economics; treat other chains as **attached accounts**. Keep **mnemonic / keys** only on the client, **ciphertext** in CloudStorage when Telegram is used, and **public addresses + optional Telegram link** on the server. When Telegram is down, **degrade gracefully**: local signing and read paths keep working; Telegram-only steps queue or hide with clear messaging.
+
+---
+
+## 8. Implementation phases (aligned with existing roadmap)
+
+1. **Phase A — Standalone parity (minimum viable resilience)**  
+   - Unhosted TON create/restore in **Expo web + native** without Telegram.  
+   - Same `WalletService` abstraction as in `wallets_hosting_architecture.md`; storage backend switches on environment (TMA vs native).  
+   - Optional “Link Telegram” after the fact.
+
+2. **Phase B — Linking & DB**  
+   - Nullable Telegram on `users`; `wallets` rows for `internal` + `tonconnect`.  
+   - Telegram Login only for users who want cross-surface sync.
+
+3. **Phase C — Bot confirmations + queue**  
+   - Pending tx from any client; confirmation in TMA when available; standalone users complete via **local sign** without bot where the protocol allows.
+
+4. **Phase D — Multi-chain read + selective write**  
+   - Add connected chains for **display** first; add signing per chain as product requires.
+
+---
+
+## 9. Security notes (unchanged principles)
+
+- No mnemonic on server; CloudStorage holds **ciphertext only**; device-bound keys decrypt.  
+- Telegram Login proves **identity**, not possession of keys.  
+- Standalone users rely on **seed backup** exactly as in self-custody best practice.  
+- DLLR issuance rules remain **on-chain** on TON; our app is a **client**, not an issuer.
+
+---
+
+## 10. Open decisions (to refine with product/legal)
+
+- Whether standalone users get **full** DLLR program participation or **subset** until KYC/Telegram link (if required by issuance policy).  
+- Exact **jetton master** and **wallet v4/v5** choices for DLLR display and deploy flows.  
+- Whether **one mnemonic** derives only TON or also other chains (prefer **separate mnemonics** per chain unless using a documented multi-chain HD profile).
+
+---
+
+*Proposal doc; iterate with team and adjust table/column names to match the actual migration from `security_plan_raw.md`.*