luxfi/wallet
1
0
Fork 0
mirror of https://github.com/luxfi/wallet.git synced 2026-07-27 03:37:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: LEGACY.md, LLM.md, ship SCREENS.md spec freeze

Browse Source 
LEGACY.md — sibling repos to archive after canonical absorption:
  - wallet-legacy (OneKey-fork) → BRAND_PACKAGE pattern absorbed via pkgs/brand
  - wwallet (bespoke SDK)        → superseded by @l.x/api npm-published
  - xwallet (OKX-fork)           → hardware-wallet code already removed upstream
  - dwallet                      → independent desktop product, NOT folded in

LLM.md — single source of truth for AI assistants on this repo. Documents:
  - canonical structure (apps/{web,mobile,extension} + pkgs/{wallet,brand,analytics})
  - what builds today (web clean; ext/mobile pending app refactor)
  - white-label brand pattern, analytics pattern, bootnode RPC pattern
  - the @l.x/* upstream publishing bug (~5000 type errors from raw .ts shipping)
  - rules: no datadog/amplitude/uniswap direct deps, no Quicknode, no Tamagui
           name in source, BIP44 9000 path preserved.

SCREENS.md — UX spec freeze 2025-12-15 (already written; now tracked).

Downstream consumption: ~/work/liquidity/wallet pins UPSTREAM_REF against
luxfi/wallet@<sha>, same pattern as ~/work/liquidity/swap shimming
luxfi/exchange.
This commit is contained in:
Hanzo AI
2026-04-30 11:47:38 -07:00
parent bf5972ffe3
commit ba7b2dac3e
3 changed files with 770 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LEGACY.md
+98
View File
@@ -0,0 +1,98 @@
# Legacy Wallet Repos — Superseded by `@luxfi/wallet`
This document lists the sibling wallet repositories under `~/work/lux/` that
are superseded by this canonical monorepo (`luxfi/wallet`). They should be
archived (move to `archive/luxfi/wallet-*` GitHub orgs or set archived=true).
The canonical product is `@luxfi/wallet` (this repo, `pkgs/wallet`) consumed
by `apps/{web,mobile,extension}`. White-label users (Liquidity, Zoo, Pars)
pin a stable `UPSTREAM_REF` against `luxfi/wallet@<sha>` instead of forking.
## Status of each sibling repo
### `~/work/lux/wallet-legacy/` — `@luxwallet/monorepo`
- **Lineage**: Fork of OneKey wallet (`@onekeyhq/*` workspace names visible in
`package.json` scripts).
- **What was unique**: The `BRAND_PACKAGE` env-var pattern (commit `2805c90b`)
that fetches `brand.json` from a published npm brand package at container
startup. **This pattern is now canonical** — implemented as `pkgs/brand/`
and wired into `apps/web` via `loadBrandConfig()`. White-label deployments
override `/brand.json` via K8s ConfigMap — same surface as the legacy
`BRAND_PACKAGE` env var, with cleaner dev ergonomics.
- **Other features**: TEE/GPU support for regenesis (commit `4faa58f9`).
Out of scope for the wallet — that work belongs in `~/work/lux/genesis`.
- **Verdict**: Archive. Brand pattern absorbed.
### `~/work/lux/wwallet/` — `luxfi/wwallet`
- **Lineage**: Bespoke Lux wallet line — `apps/{app,web}` + `components/` +
a standalone `sdk/` (rollup-built TypeScript SDK).
- **What was unique**: A standalone TS SDK with `audits/`, `typedoc.json`,
rollup build, and Cypress E2E. Recent commits trended toward purging
PostHog and porting analytics to `@hanzo/insights`.
- **Why not absorbed**: The canonical wallet uses the `@l.x/api` (npm-published)
for SDK surface and the new `pkgs/analytics` driver abstraction supersedes
the PostHog/Insights wiring. The SDK in `wwallet/sdk/` is older and
duplicates what's now in the published `@l.x/*` packages.
- **Verdict**: Archive.
### `~/work/lux/xwallet/` — `@luxwallet/x`
- **Lineage**: Fork of OKX wallet extension (commits reference `OK-29867`,
`OK-29384` ticket numbers — that's OKX's internal Jira).
- **What was unique**: BitBox02 hardware-wallet pairing and Matomo tracking
vendor files (commit `0edeb2f` removed them as unused). Lux mainnet/testnet
chain configs (`8287b50`).
- **Why not absorbed**: BitBox02 + Matomo are explicitly removed in the most
recent commit. Chain configs are now consumed from `@luxfi/wallet-brand`'s
`brand.json:rpc` map, not hardcoded constants. The OKX-fork lineage diverges
too far from the canonical `@luxfi/wallet` bones.
- **Verdict**: Archive.
### `~/work/lux/dwallet/` — `lux-desktop`
- **Out of scope** for this wallet repo. Desktop is a separate product line
(Electron/Tauri). Kept independent.
- **Verdict**: Keep as separate product, do NOT fold in.
## What this repo IS canonical for
```
luxfi/wallet (this repo)
├── apps/
│ ├── web/ — Vite SPA. Builds clean.
│ ├── extension/ — Chrome/Firefox MV3 (upstream-shaped, requires app refactor)
│ └── mobile/ — React Native + Expo (upstream-shaped, requires app refactor)
├── pkgs/
│ ├── wallet/ — `@luxfi/wallet` — canonical wallet feature bones
│ ├── brand/ — `@luxfi/wallet-brand` — runtime white-label config
│ └── analytics/ — `@luxfi/wallet-analytics` — provider-pluggable analytics
└── SCREENS.md — UX spec freeze (2025-12-15)
```
## Downstream consumption
White-label deployments pin `UPSTREAM_REF` to a `luxfi/wallet@<sha>`:
```dockerfile
# In ~/work/liquidity/wallet/Dockerfile (in-flight elsewhere)
ARG UPSTREAM_REF=<sha-from-this-repo>
RUN git clone --depth 1 https://github.com/luxfi/wallet.git \
&& cd wallet \
&& git fetch --depth 1 origin "$UPSTREAM_REF" \
&& git checkout "$UPSTREAM_REF"
```
The same pattern as `~/work/liquidity/swap` shimming `luxfi/exchange`.
## Archival action items (NOT performed by this Blue)
The CTO/user makes the call on archival. Suggested actions:
1. `gh repo archive luxfi/wallet-legacy`
2. `gh repo archive luxfi/wwallet`
3. `gh repo archive luxfi/xwallet`
All three remain as GitHub repos with full git history — archival is
non-destructive and reversible.
LLM.md
+130
View File
@@ -0,0 +1,130 @@
# `@luxfi/wallet` — AI Assistant Knowledge Base
**Project**: `luxfi/wallet` — canonical Lux Wallet upstream (web + mobile + extension).
**Org**: Lux Industries Inc. (`luxfi`).
**Status**: `apps/web` builds clean. `apps/{extension,mobile}` retain upstream-shaped
src that requires an app-level refactor to compile against current `@l.x/*` npm
packages. The canonical bones (`pkgs/{wallet,brand,analytics}`) are stable.
## Canonical structure
```
luxfi/wallet/
├── apps/
│ ├── web/ — Vite 8 SPA, React 19, brand-aware. Builds in <100ms.
│ ├── extension/ — Chrome/Firefox MV3 (upstream-shaped; app-refactor pending).
│ └── mobile/ — React Native + Expo (upstream-shaped; app-refactor pending).
├── pkgs/
│ ├── wallet/ — `@luxfi/wallet` — canonical wallet feature bones.
│ ├── brand/ — `@luxfi/wallet-brand` — runtime white-label config.
│ └── analytics/ — `@luxfi/wallet-analytics` — provider-pluggable analytics.
├── SCREENS.md — UX spec freeze (2025-12-15).
└── LEGACY.md — Sibling repos (wallet-legacy, wwallet, xwallet) to archive.
```
## Build commands (verified working)
```bash
pnpm install --no-frozen-lockfile
pnpm --dir apps/web build # Vite SPA — clean. Output in apps/web/dist/.
```
`apps/{extension,mobile}` build via Nx targets that depend on workspace
packages still upstream-shaped (`@universe/*`, `wallet/*` direct paths) and
will not type-check or build until refactored to consume the npm-published
`@l.x/*` and the workspace `@luxfi/wallet`. Track in this file when fixed.
## White-label brand pattern (canonical)
Brand config flows at runtime, not build time. Same pattern as
`~/work/lux/exchange/pkgs/config/src/brand.ts`.
```
@luxfi/wallet-brand/brand.json ─copy→ apps/web/dist/brand.json
│
↓
K8s ConfigMap mount overlays
│
↓
loadBrandConfig() fetches /brand.json
│
↓
mutates `brand` singleton + CSS vars
│
↓
React renders against final brand
```
White-labels (Liquidity, Zoo, Pars) override `/brand.json` via a K8s
ConfigMap — no source fork required. Theme tokens are CSS custom properties
(`--accent1`, `--surface1`, etc.) so the same DOM tree renders any brand.
## Analytics pattern (canonical)
`@luxfi/wallet-analytics` provides a provider-pluggable `AnalyticsDriver`
interface. No third-party SDK loaded by default. Hanzo Insights is the
intended default driver (registered at app bootstrap). White-labels swap
drivers at boot via `setAnalyticsDriver(...)`. Surface matches what wallet
call sites expect (`init`/`track`/`identify`/`Identify`/...).
## RPC pattern (canonical)
`getBootnodeRpcUrl(chainId)` from `@luxfi/wallet-brand` is the **only** way
to resolve an RPC endpoint. Default is `https://<gatewayDomain>/v1/rpc/<chainId>`
with `runtimeConfig.rpc[<chainId>]` overrides honored first. No Quicknode,
no Alchemy direct. White-labels point at their own gateway (e.g.,
`gw.lux.exchange/v1/rpc/96369`).
## Direct dependency hygiene
- **Zero `@datadog/*` direct deps** in any app `package.json` or `pkgs/*`.
(Transitive deps via `@l.x/utils` and `@l.x/lx` remain — those are upstream
packages and will be cleaned in their own pkg releases.)
- **Zero `@amplitude/*` direct deps**.
- **Zero `@uniswap/*` direct deps** (forked to `@luxamm/*` per commit `81b2ba3e`).
- **Zero `getQuicknodeEndpointUrl` references** in our source — only the
string literal `'quicknode'` exists in error-matching test fixtures.
## Workspace catalog (`pnpm-workspace.yaml`)
`@hanzogui/*-fork.1` aliases for React Native packages. The `@hanzogui` prefix
is the internal umbrella name (NEVER write "Tamagui" — see
`feedback_no_tamagui_brand.md`). Product brand for the GUI library is
`@hanzo/gui`.
## Known transitive type errors (NOT our bug)
`@l.x/api`, `@l.x/lx`, `@l.x/utils`, `@l.x/config` ship as raw `.ts` files
and reference a rootless `utilities/src/*` module that doesn't exist on disk.
This means `tsc --noEmit` against `pkgs/wallet/` traces into `node_modules/.pnpm/@l.x+*`
and produces ~5000 errors. **These are upstream-publishing bugs in the `@l.x/*`
packages** — they need to ship `.d.ts` artifacts and self-resolved imports.
Filed as a follow-up; lux/wallet does not patch upstream packages.
The web SPA builds because Vite tree-shakes — only used surface is touched.
## Sibling repos (see LEGACY.md)
- `~/work/lux/wallet-legacy` — OneKey-fork lineage. BRAND_PACKAGE pattern absorbed → archive.
- `~/work/lux/wwallet` — bespoke SDK line. Superseded by `@l.x/api` → archive.
- `~/work/lux/xwallet` — OKX-fork lineage. Hardware support already removed → archive.
- `~/work/lux/dwallet` — Desktop product. **Independent**, do not fold in.
## Rules for AI Assistants
1. **NEVER** write random summary files — update `LLM.md` only.
2. **NEVER** commit symlinked files (.AGENTS.md, CLAUDE.md, etc.) — they're in `.gitignore`.
3. **NEVER** introduce direct `@datadog/*`/`@amplitude/*`/`@uniswap/*` deps —
use the abstractions in `pkgs/analytics` and `@luxamm/*`.
4. **NEVER** reference `getQuicknodeEndpointUrl` — use `getBootnodeRpcUrl`.
5. **NEVER** hardcode brand strings (`"Lux Wallet"`, `"lux.network"`) in app code —
read from the `brand` singleton in `@luxfi/wallet-brand`.
6. **NEVER** write "Tamagui" — use "@hanzo/gui" / `@hanzogui/*` umbrella.
7. **ALWAYS** preserve BIP44 path 9000 for Lux P/X chain addresses in any
key derivation (60 for EVM C-chain).
8. **ALWAYS** keep the GPL-3.0-or-later license header — wallet inherits it.
---
**Single source of truth** for AI assistants on `luxfi/wallet`. Update this file
when behavior changes; never spawn parallel `.md` documents.
SCREENS.md
+542
View File
@@ -0,0 +1,542 @@
# Lux Wallet — Screen Specifications
**Status**: Authoritative UX reference for Lux Wallet 3.0 (mobile, desktop, browser extension).
**Spec freeze**: 2025-12-15.
**Activation**: 2025-12-25 alongside Zoo 3.0 launch and Lux Quasar 3.0 mainnet upgrade.
**Form factors**: browser extension, iOS, Android, Lux Desktop app.
The Lux Wallet is the canonical signing surface for the Lux ecosystem. Zoo L1 appears as a chain target alongside Lux P/C/X/Q/Z/A/B/M/F-Chains. This document specifies every screen with text mockups, flow descriptions, edge cases, and the chain-routing logic.
Cross-references:
- `zoo-3-0-launch` paper §10 (Lux Wallet and Desktop)
- `zoo-per-llm-chains` paper (per-LLM tokens displayed in portfolio)
- LP-020 (Quasar 3.0 triple-consensus finality display)
- LP-013 (F-Chain FHE confidential mode)
- LP-063 (Z-Chain ZKP selective disclosure)
- LP-134 (chain topology — chain selector contents)
---
## 1. Account / Portfolio View
### Purpose
Top-level dashboard. Aggregates balances across all Lux ecosystem chains and Zoo-specific assets. Default landing screen on app open.
### Mockup (mobile-first; desktop expands columns)
```
┌─────────────────────────────────────────┐
│ Lux Wallet 🔒 ⚙ │
├─────────────────────────────────────────┤
│ Account: zach.lux │
│ 0xA1B2…3F4E [copy] [QR] │
├─────────────────────────────────────────┤
│ Total value (USD) │
│ $42,718.93 ▲ 2.4% 24h │
├─────────────────────────────────────────┤
│ Assets Privacy: ○ off │
│ │
│ $LUX 1,250.00 │
│ P-Chain stake 800.00 │
│ C-Chain 450.00 │
│ │
│ $AI 18,432.10 │
│ A-Chain rewards 1,432.10 │
│ Hanzo earnings 17,000.00 │
│ │
│ $ZOO 100,000.00 │
│ Zoo L1 native 95,000.00 │
│ Bridged (Eth) 5,000.00 │
│ │
│ Per-LLM tokens │
│ ZEN4-NANO 8,250 │
│ ZEN4-MINI 4,120 │
│ ZEN4-LARGE 340 │
│ │
│ NFTs 12 items │
│ [thumb] [thumb] [thumb] [+9 more] │
│ │
│ Confidential (F-Chain) 2 assets │
│ ●●●●●● $ZOO [unwrap] │
│ ●●●●●● ZEN4-ULTRA [unwrap] │
├─────────────────────────────────────────┤
│ [Send] [Receive] [Swap] [Stake] [Bridge]│
└─────────────────────────────────────────┘
```
### Flow
1. App launch authenticates against OS keychain or PIN.
2. Wallet pulls balances per chain in parallel; renders in priority order ($LUX, $AI, $ZOO, per-LLM, NFTs, confidential).
3. Privacy toggle in header re-routes future signing actions through F-Chain or Z-Chain (see §7).
4. Tap any asset row to open the asset detail screen (history, send, receive).
5. NFT thumbnails open the NFT detail flow with provenance chain.
6. Confidential balances show ciphertext indicators; tap unwrap to decrypt locally.
### Edge cases
- Empty wallet: full-screen onboarding card with "Create" / "Import" CTAs.
- Network failure on one chain: that asset row shows "—" with a retry icon; other rows render normally.
- New per-LLM token detected in chain emit: surfaces as "New asset detected" toast at top.
---
## 2. Send / Receive
### Purpose
Sign and broadcast outbound transactions; show receive address with QR.
### Mockup — Send
```
┌─────────────────────────────────────────┐
│ ← Send │
├─────────────────────────────────────────┤
│ From: $ZOO on Zoo L1 │
│ Balance: 95,000 ZOO │
│ │
│ To: │
│ [0xC4D5…7A8B ] [📷 QR] │
│ │
│ Amount: │
│ [ 1,000.00 ZOO ▼] │
│ ≈ $245.00 USD │
│ │
│ Network fee: 0.0042 ZOO (~$0.001) │
│ │
│ Privacy: ○ off │
│ Finality: │
│ ✓ BLS classical fast-path │
│ ⏱ Corona PQ threshold │
│ ⏱ ML-DSA identity │
│ │
│ [ Sign & Send ] │
└─────────────────────────────────────────┘
```
### Flow
1. User selects source asset (default: most recent or current portfolio focus).
2. Address entry: paste, scan QR, pick from contacts, or resolve a `*.lux` name.
3. Amount entry with USD quote.
4. Privacy toggle (re-routes via F-Chain Confidential ERC-20 if enabled).
5. Tap Sign & Send: local signing, broadcast, show progress modal.
6. Progress modal shows triple-consensus state: BLS first (~50ms), Corona second (~200ms), ML-DSA third (~500ms). Three checkmarks = full QuasarCert.
### Mockup — Receive
```
┌─────────────────────────────────────────┐
│ ← Receive │
├─────────────────────────────────────────┤
│ Account: zach.lux │
│ │
│ ┌───────────────────────┐ │
│ │ [QR code] │ │
│ │ │ │
│ └───────────────────────┘ │
│ │
│ 0xA1B2C3D4E5F6…7890ABCDEF │
│ │
│ [Copy address] [Share] │
│ │
│ Chain: Zoo L1 ▼ │
│ ↳ tap to switch chain │
└─────────────────────────────────────────┘
```
### Flow
Chain selector at bottom changes the QR's encoded chain prefix (e.g., `lux:zoo-l1:0x…`). Default to currently focused chain in portfolio.
### Edge cases
- Insufficient balance → Sign button disabled, error inline.
- Unknown destination chain → warning banner with chain ID lookup.
- Address checksum mismatch → block submission, show error.
---
## 3. DEX Swap
### Purpose
Token-for-token swap with chain selector for routing across Lux C-Chain (Lux DEX) and Zoo L1 (Zoo DEX V2/V3/V4).
### Mockup
```
┌─────────────────────────────────────────┐
│ ← Swap │
├─────────────────────────────────────────┤
│ Route: Zoo L1 (Zoo DEX V3) ▼ │
│ ▸ Lux C-Chain (Lux DEX) │
│ ▸ Zoo L1 (Zoo DEX V2) │
│ ▸ Zoo L1 (Zoo DEX V3) │
│ ▸ Cross (Zoo V4 → Lux DEX) │
│ │
│ From: │
│ [ 1,000.00 ] $ZOO ▼ │
│ Balance 95,000 [Max] │
│ │
│ ⇅ │
│ │
│ To: │
│ [ 245.10 ] $LUX ▼ │
│ ≈ $245.00 USD │
│ │
│ Slippage: 0.5% Price impact: 0.02% │
│ │
│ Pool fee tier: 30 bps │
│ Network fee: 0.012 ZOO │
│ │
│ [ Review swap ] │
└─────────────────────────────────────────┘
```
### Flow
1. User picks From/To assets (any ZRC-20 / Lux native asset).
2. Router auto-suggests best route across the four routing options.
3. User can override route via the selector.
4. Slippage + price impact shown inline.
5. Review modal shows full path (e.g., "Zoo V4 → B-Chain hop → Lux DEX") with fee breakdown.
6. Sign and broadcast.
### Routing rules
| Source asset | Destination asset | Default route |
|---|---|---|
| ZOO L1 native | ZOO L1 native | Zoo DEX V2 or V3 |
| Lux C-Chain native | Lux C-Chain native | Lux DEX |
| Zoo L1 ↔ Lux C-Chain | cross-chain | Zoo DEX V4 (precompile to Lux DEX) |
| Per-LLM token ↔ ZOO | Zoo L1 | Zoo DEX V3 |
| NFT fractional ↔ ZOO | Zoo L1 | Zoo DEX V3 |
### Edge cases
- No liquidity on any route → blocking modal with explanation.
- Cross-chain route: separate progress states for source-chain swap, B-Chain hop, destination-chain delivery.
- Price moves > slippage tolerance during signing → fail safely with refund (no partial fills).
---
## 4. Staking
### Purpose
Delegate `$LUX` to Lux validators (P-Chain) or `$ZOO` / `$AI` to Zoo L1 validators.
### Mockup
```
┌─────────────────────────────────────────┐
│ ← Staking │
├─────────────────────────────────────────┤
│ Network: Zoo L1 ▼ │
│ ▸ Lux P-Chain │
│ ▸ Zoo L1 │
├─────────────────────────────────────────┤
│ Your stake │
│ 12,500 ZOO ↳ 3 validators │
│ Pending rewards: 142 ZOO [Claim] │
├─────────────────────────────────────────┤
│ Active validators (Zoo L1) │
│ │
│ [v01] zen-validator-1 │
│ Stake: 8.2M ZOO • Uptime 99.97% │
│ Reward 8.4% APR • Slash risk: low │
│ [Delegate] │
│ │
│ [v02] conservation-node │
│ Stake: 5.1M ZOO • Uptime 99.91% │
│ Reward 8.7% APR • Slash risk: low │
│ [Delegate] │
│ │
│ [v03] hanzo-mining-pool │
│ Stake: 12.3M ZOO • Uptime 99.99% │
│ Reward 8.1% APR • Slash risk: low │
│ [Delegate] │
└─────────────────────────────────────────┘
```
### Flow
1. Network selector switches between Lux P-Chain and Zoo L1.
2. Stake summary shows current delegations and unclaimed rewards.
3. Validator list sorted by reward APR with uptime / slash risk shown.
4. Delegate flow: pick amount, confirm lock period, sign delegation transaction.
5. Slashing history pulled from A-Chain attestation feed for each validator.
### Edge cases
- Validator at capacity → grayed out with "At capacity" badge.
- Slashed validator → red banner; cannot delegate.
- Lock period not yet elapsed for unstake → countdown display.
---
## 5. Bridge
### Purpose
Move assets between Zoo L1 and external chains via Zoo Bridge (B-Chain).
### Mockup
```
┌─────────────────────────────────────────┐
│ ← Bridge │
├─────────────────────────────────────────┤
│ From: Zoo L1 ▼ │
│ To: Lux C-Chain ▼ │
│ │
│ Supported destinations: │
│ • Lux C/X/B/Z-Chain │
│ • Ethereum mainnet │
│ • Polygon │
│ • BSC (inbound only — legacy) │
│ • Arbitrary EVM (generic adapter) │
│ │
│ Asset: │
│ [ ZOO ▼ ] [ 1,000.00 ] │
│ │
│ Recipient: same wallet ▼ │
│ 0xA1B2…3F4E │
│ │
│ Bridge route │
│ 1. Lock on Zoo L1 │
│ 2. M-Chain threshold sign (2-of-3) │
│ 3. Mint on Lux C-Chain │
│ ETA: ~30 seconds │
│ │
│ Bridge fee: 0.5 ZOO │
│ │
│ [ Confirm bridge ] │
└─────────────────────────────────────────┘
```
### Flow
1. Source / destination chain selectors. Default source = current chain focus; default destination = remembered last destination.
2. Asset selector filtered to bridge-supported assets.
3. Recipient defaults to "same wallet" but can be changed (with warning).
4. Route preview shows the full lock → threshold-sign → mint pipeline with ETA.
5. Confirm: signs lock TX on source, polls bridge committee, surfaces threshold ceremony progress, finalises mint event.
### Edge cases
- Unsupported asset for chosen destination → asset selector grays out unsupported entries.
- BSC outbound → blocked with "BSC inbound only — legacy migration" message.
- Threshold ceremony stalls > 5 minutes → escalation to manual review with support link.
---
## 6. AI Inference
### Purpose
Send inference queries to local Zoo AI Desktop, Zoo Cloud, or Hanzo Marketplace.
### Mockup
```
┌─────────────────────────────────────────┐
│ ← AI │
├─────────────────────────────────────────┤
│ Mode: │
│ ● Local (free, on-device) │
│ ○ Zoo Cloud (pay $AI per token) │
│ ○ Hanzo Marketplace (HMM routing) │
│ ○ Confidential (F-Chain FHE) │
│ │
│ Model: │
│ zen4-mini (eligible: device VRAM 8GB) │
│ ▸ zen4-nano │
│ ▸ zen4-mini ✓ │
│ ▸ zen4-small │
│ ▸ zen4-medium (Zoo Cloud only) │
│ ▸ zen4-large (Zoo Cloud only) │
│ │
│ Prompt: │
│ ┌─────────────────────────────────┐ │
│ │ Summarise the latest A-Chain │ │
│ │ attestation feed for ZEN4-LARGE.│ │
│ └─────────────────────────────────┘ │
│ │
│ Cost: free (local) │
│ │
│ [ Send query ] │
├─────────────────────────────────────────┤
│ Response │
│ ┌─────────────────────────────────┐ │
│ │ [streaming model output…] │ │
│ └─────────────────────────────────┘ │
│ │
│ Provenance: A-Chain receipt 0xF… ✓ │
└─────────────────────────────────────────┘
```
### Flow
1. Mode selector picks the routing path.
2. Model selector filters by mode (Local mode lists device-eligible models; Cloud lists all).
3. Prompt entry; cost preview updates inline (free for Local; per-token for Cloud / Marketplace).
4. Send query: local mode runs immediately on-device; Cloud mode signs a payment TX and dispatches to A-Chain attested worker; Marketplace mode signs a HMM contract invocation.
5. Response streams back; provenance receipt link opens A-Chain explorer.
### Confidential mode
When Confidential mode is selected, the prompt is encrypted under the F-Chain key before submission; the response arrives encrypted and decrypts locally. Worker never sees plaintext.
### Edge cases
- Model exceeds device VRAM in Local mode → auto-suggest Zoo Cloud upgrade.
- Cloud / Marketplace insufficient $AI balance → block submission with top-up CTA.
- Confidential mode requires F-Chain reachability; if F-Chain unreachable, fall back to standard Cloud mode with explicit user re-confirmation.
---
## 7. Privacy Mode Toggle
### Purpose
Single global toggle that re-routes future signing actions through F-Chain (FHE) or Z-Chain (ZKP) based on intent.
### Mockup
```
┌─────────────────────────────────────────┐
│ ← Privacy │
├─────────────────────────────────────────┤
│ Privacy mode: ● off ○ on │
│ │
│ When privacy mode is on: │
│ │
│ Transfers │
│ → routed through F-Chain │
│ Confidential ERC-20 (LP-067) │
│ • Balances and amounts encrypted │
│ • Validator never sees plaintext │
│ │
│ Identity proofs │
│ → routed through Z-Chain │
│ Selective disclosure (LP-063) │
│ • Prove "I hold ≥ X" without │
│ revealing actual balance │
│ • Prove "I am over 18" without │
│ revealing date of birth │
│ │
│ Display │
│ • Balances in portfolio show as ●●●● │
│ • Tap to decrypt locally │
│ │
│ Cost │
│ • Higher per-op cost than non-private │
│ • F-Chain ~10× standard transfer cost │
│ • Z-Chain ~3× standard transfer cost │
│ │
│ [ Apply changes ] │
└─────────────────────────────────────────┘
```
### Flow
1. Toggle privacy mode on/off.
2. Apply changes signs a wallet config update (local only, not on-chain).
3. Future Send / Swap / Bridge / Staking flows route through the privacy chain when privacy mode is on.
4. Portfolio view displays ciphertext indicators on confidential balances.
### Edge cases
- F-Chain or Z-Chain unreachable → privacy mode degrades to "warn before sending in cleartext" rather than silently disabling.
- Pre-existing non-private balances coexist with new private balances; toggle does not auto-migrate.
- Privacy off → previously confidential balances remain encrypted on-chain; only newly signed transactions go cleartext.
---
## 8. Form-factor parity
| Screen | Browser ext | iOS | Android | Desktop |
|---|---|---|---|---|
| Portfolio | ✓ | ✓ | ✓ | ✓ |
| Send / Receive | ✓ | ✓ | ✓ | ✓ |
| DEX Swap | ✓ | ✓ | ✓ | ✓ |
| Staking | ✓ | ✓ | ✓ | ✓ |
| Bridge | ✓ | ✓ | ✓ | ✓ |
| AI Inference | ✓ | limited (Cloud only — no local model runtime) | limited | ✓ (full local model runtime) |
| Privacy Mode | ✓ | ✓ | ✓ | ✓ |
| Validator Operator Pane | — | — | — | ✓ (desktop only) |
---
## 9. Validator Operator Pane (Desktop only)
### Purpose
For users running their own Zoo or Lux validator. Surfaces block production stats, slashing exposure, threshold-ceremony participation.
### Mockup
```
┌──────────────────────────────────────────────────────────┐
│ Validator: zen-validator-1 │
├──────────────────────────────────────────────────────────┤
│ Stake: 8,200,000 ZOO Uptime (24h): 99.97% │
│ Active set: ✓ Last block: #3,142,887 │
├──────────────────────────────────────────────────────────┤
│ Block production (last 100 epochs) │
│ [████████████████████████████░] 92.3% │
│ │
│ Triple-consensus participation │
│ BLS: ████████████████████ 99.99% │
│ Corona: ████████████████████ 99.97% │
│ ML-DSA: ████████████████████ 99.98% │
│ │
│ Threshold ceremonies (M-Chain) │
│ 24h: 142 / 142 signed │
│ 7d: 984 / 985 signed (1 missed at epoch 1247) │
├──────────────────────────────────────────────────────────┤
│ Slashing risk: low │
│ Recent attestations: 24h ✓ 100% │
│ Pending slashes: 0 │
└──────────────────────────────────────────────────────────┘
```
### Flow
Read-only display. Tapping any metric drills into A-Chain explorer for the underlying attestation.
---
## 10. Settings
Standard settings tree; non-load-bearing for the launch.
- Account management (add, remove, rename, biometric unlock)
- Network endpoints (RPC overrides per chain)
- Theme (light / dark / auto)
- Telemetry (off by default)
- Backup (BIP-39 export, hardware wallet pairing)
- About / version / open source licenses
---
## 11. Activation checklist (for engineering)
- [ ] Portfolio screen renders all 9 chains in topology
- [ ] Per-LLM token detection wired to Zoo L1 chain emit feed
- [ ] DEX Swap chain selector includes Zoo L1 + Lux C-Chain + Zoo V4 cross-chain route
- [ ] Send finality progress shows triple-consensus three-step UI
- [ ] Bridge supports BSC inbound migration adapter
- [ ] AI inference Local mode auto-spawns zoo-node runtime
- [ ] Privacy mode toggle integrated with F-Chain and Z-Chain precompiles
- [ ] Validator operator pane visible only when local node detected
- [ ] All flows compatible with browser extension, mobile, and desktop form factors
- [ ] All chains in chain selector match LP-134 canonical taxonomy
---
**Owner**: Lux Wallet team. Update via PR; cross-link to `zoo-3-0-launch` paper §10.