Unified control plane for wallet, mining, validation, and deployment.

GXQS is not a wallet app. It is an enterprise blockchain operating platform that combines:

• 🔐 Universal Identity Layer – one cryptographic root controlling wallet signing, mining authentication, validator authorization, and enterprise deployment permissions
• ⚡ Runtime Supervisor – Kubernetes-style daemon orchestration (walletd, minerd, validatord, telemetryd, deployerd)
• 🦀 Rust Crypto Core – AES-256-GCM vault, memory-safe (zeroize-on-drop), WASM-capable
• 🐹 Go Protocol Bridge – walletd JSON-RPC server, GXQS address derivation, transaction builder
• 🌐 Web Dashboard – Next.js + Tailwind + Zustand enterprise monitoring UI (#00ffe1 glow system)
• 🧠 Smart Wallet Flow (walletd-mediated placeholders):
  • one-click onboarding UX and registration/import/export request surfaces
  • network/RPC profile toggles and auth onboarding placeholders
  • secret material remains inside walletd
• 📱 Mobile App – React Native + Expo cross-platform client (apps/mobile)
• 📋 Policy Engine – YAML-driven enterprise policy enforcement (compute limits, validator rules, fleet policies)
• 🐳 Production Infrastructure – Docker, Kubernetes (Kustomize), Prometheus, Grafana

┌─────────────────────────────────────────────────────────────────────────────┐
│                              GXQS/Wallet                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   walletd   │  │   minerd    │  │  validatord │  │     telemetryd      │ │
│  │ (Go bridge) │  │ (mining)    │  │ (validator) │  │     (metrics)       │ │
│  └──────┬──────┘  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│         │                                                                   │
│  ┌──────▼──────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Rust Vault  │  │   Policy    │  │  Runtime    │  │      Deployerd      │ │
│  │(AES-256-GCM)│  │   Engine    │  │ Supervisor  │  │    (deployment)     │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│         │                                                                   │
│  ┌──────▼──────┐                                                           │
│  │   Core      │  ← Protocol authority (github.com/GXQS/core)              │
│  │  (gRPC)     │                                                           │
│  └─────────────┘                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

wallet/
├── apps/
│   ├── web/                   # Next.js 16 enterprise dashboard
│   └── mobile/                # React Native + Expo mobile app
├── packages/
│   ├── sdk/                   # TypeScript SDK (@gxqs/sdk)
│   └── ui/                    # Shared UI components (@gxqs/ui)
├── runtime/
│   ├── gxqs-runtime/          # Runtime supervisor (watchdog)
│   ├── protocol/
│   │   └── go-rpc-bridge/     # Go JSON-RPC walletd (Core integration)
│   ├── policy-engine/         # YAML enterprise policy engine
│   └── crypto/
│       └── gxqs-wallet-core-rs/  # Rust: AES-256-GCM vault + WASM
├── infra/
│   ├── docker/                # Dockerfiles + Docker Compose
│   ├── kubernetes/            # Kustomize base manifests
│   └── observability/         # Prometheus + Grafana configs
├── api/                       # OpenAPI spec (walletd)
├── scripts/                   # bootstrap.sh / bootstrap.ps1
└── .github/workflows/         # CI: Go, Rust, TypeScript, WASM

Linux / macOS:

# Verifies prerequisites, syncs/fetches dependencies, and installs audit tools
bash scripts/bootstrap.sh
make build

Windows (PowerShell):

# Run from repo root
.\scripts\bootstrap.ps1
make build

Prerequisites: Go 1.24+, Rust 1.94.1+, Node.js 24+, pnpm 11+

# 1 — TypeScript packages
pnpm install

# 2 — Start web dashboard (dev)
pnpm --filter @gxqs/web dev

# 3 — Validate frontend quality gates
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test

# 4 — Run walletd (Go)
cd runtime/protocol/go-rpc-bridge && go run ./cmd/walletd

# 5 — Verify
curl http://localhost:8545/healthz
curl http://localhost:8545/rpc/v1/version

Pre-commit checks are enforced with Lefthook in strict order:

1. pnpm generated:guard – removes non-material generated-file drift from staging
2. pnpm format:staged – runs prettier --write on staged files only
3. pnpm format:check:staged – strict prettier --check on staged files
4. pnpm lint and pnpm typecheck – static quality gates

For generated file classification and commit behavior, see:

• docs/GENERATED_FILE_POLICY.md
• docs/CONTRIBUTOR_WORKFLOW.md

# Format only staged files (same behavior as pre-commit step)
pnpm format:staged

# Strictly verify formatting on staged files
pnpm format:check:staged

# Format full repository
pnpm format

# Verify formatting without writing changes
pnpm format:check

Enterprise dashboard featuring:

• Real-time telemetry – Live TPS, block height, finality, validator count
• Neon glow system – #00ffe1 primary glow with state-driven animations
• Glassmorphism UI – Frosted glass effects with depth levels
• Responsive design – Mobile-first adaptive layout with bottom navigation
• Live charts – Collapsible TPS chart with auto-refresh
• Block stream – Real-time block updates with SSE streaming
• Mempool monitor – Priority-based transaction visualization

Note: This is a representative SVG mockup. The actual dashboard is fully interactive with live Core gRPC data.

• docs/architecture/MOBILE_FIRST_ADAPTIVE_UI.md
• docs/RESPONSIVE_STORYBOOK_DOCS.md

cd infra/docker
docker compose up -d
# Web dashboard → http://localhost:3000
# walletd RPC   → http://localhost:8545
# Grafana       → http://localhost:3001  (admin / changeme)
# Prometheus    → http://localhost:9090

All pull requests must pass required CI gates. govulncheck currently runs as report-only (non-blocking):

CI runs on Ubuntu, Windows, and macOS for all language stacks.

Wallet v0.1.0 consumes Core as the protocol authority:

• ✅ Canonical Protobuf schemas from github.com/GXQS/core (proto/ in Core repo)
• ✅ Hybrid post-quantum signing (Ed25519 + Dilithium2)
• ✅ gRPC client wrapper for WalletService
• ✅ Deterministic event sourcing support

Apache-2.0 © GXQS Platform Team