FnzeroSafe

FnzeroSafe is an open-source Solana wallet security workspace for encrypted keystores, desktop signing, mobile wallets, dApp signing, Pump trading, Squads multisig, bot integration, and advanced desktop-only Program workflows.

中文 | English | Website | Telegram | Discord

1. Project Overview
   1. What FnzeroSafe Is For
   2. Product Editions
   3. Capability Matrix
   4. Platform Matrix
2. Repository Layout
3. Development Environment
   1. Required Toolchains
   2. One-Time Setup
   3. Host Notes
4. Run In Development
   1. Desktop App
   2. iOS App
   3. Android App
   4. CLI
5. Package For Release
   1. Release Directory
   2. macOS Desktop
   3. Windows Desktop
   4. iOS
   5. Android
   6. All Platforms
6. Command Reference
7. Configuration
8. Security Model
9. Documentation
10. Before Submitting To GitHub
11. License

FnzeroSafe is a local-first Solana wallet and key-management workspace. It combines a Rust core crate, an interactive CLI, a local desktop API, a Next.js web interface, a Tauri desktop shell, and a Flutter mobile app for iOS and Android.

/
├─ Cargo.toml
├─ Makefile
├─ crates/
│  ├─ core/                      # Rust SDK and CLI binary: fnzero-safe
│  ├─ app-services/              # Shared wallet/assets/payments/dApp/Squads services
│  ├─ desktop-api/               # Local Axum API used by desktop/web
│  └─ mobile-bridge/             # flutter_rust_bridge FFI layer
├─ apps/
│  ├─ desktop/                   # Next.js UI and Tauri desktop shell
│  └─ mobile/                    # Flutter iOS/Android app
├─ packages/
│  └─ shared-contracts/          # Shared API contracts and interface notes
├─ examples/                     # Bot and keystore examples
├─ docs/                         # Internal testing and development notes
└─ release/                      # Package output directory, ignored by Git

The public product name is FnzeroSafe. Internal Cargo package names such as fnzero-safe-core, fnzero-safe-desktop-api, and fnzero-safe-mobile-bridge keep workspace crates unique.

rustup update
npm --version
flutter doctor -v
cargo install cargo-ndk
cargo install flutter_rust_bridge_codegen
npm --prefix apps/desktop install
cd apps/mobile && flutter pub get

Regenerate mobile bridge bindings after changing crates/mobile-bridge/src/api.rs:

cd apps/mobile
./tool/generate_bridge.sh

Run from the repository root:

npm --prefix apps/desktop install
make dev

make dev stops stale local development processes first, then starts:

The local API is designed for loopback use only. Do not expose 3841 through a public proxy, tunnel, or port forward.

cd apps/mobile
./tool/bootstrap_mobile.sh
flutter pub get
./tool/generate_bridge.sh
./tool/build_ios_native.sh
flutter run -d ios

iOS requirements:

1. Xcode command line tools are selected with xcode-select.
2. The matching iOS platform/runtime is installed in Xcode Components.
3. iOS deployment target is 15.0.
4. Physical devices and TestFlight require normal Xcode signing setup.

cd apps/mobile
./tool/bootstrap_mobile.sh
flutter pub get
./tool/generate_bridge.sh
./tool/build_android_native.sh
flutter run -d android

Android notes:

1. Android application id is dev.fnzero.safe.
2. Android minSdk is 26.
3. Rust bridge .so libraries are generated for arm64-v8a, armeabi-v7a, x86, and x86_64.
4. JDK 17 is recommended for Gradle.

cargo run -p fnzero-safe-core --features full -- start

Install the CLI locally from source:

cargo install --path crates/core --features full
fnzero-safe start

All package commands copy artifacts into the root release/ directory:

release/
├─ android/
│  ├─ app-release.apk
│  └─ app-release.aab
├─ ios/
│  └─ *.app or *.ipa
├─ macos/
│  ├─ FnzeroSafe.app
│  └─ FnzeroSafe_*.dmg
└─ windows/
   └─ *.msi and/or *.exe

release/ is ignored by Git.

make package-macos

This runs the desktop production build and copies .dmg and .app artifacts into release/macos/.

make package-windows

This builds the Tauri Windows package and copies .msi and/or .exe artifacts into release/windows/.

Recommended build environment: a Windows runner with Rust, Node.js, npm, and Microsoft Visual Studio build tools installed. Cross-building Windows installers from macOS requires extra toolchain setup.

Override the target when needed:

TAURI_WINDOWS_TARGET=x86_64-pc-windows-msvc make package-windows

Unsigned local .app build:

make package-ios

Signed IPA build:

IOS_CODESIGN=true IOS_EXPORT_OPTIONS_PLIST=/path/to/ExportOptions.plist make package-ios

The command first builds the Rust iOS FnzeroSafeMobileBridge.xcframework, then runs the Flutter iOS package step and copies artifacts into release/ios/.

make package-android

If JDK 17 is not auto-detected:

ANDROID_JAVA_HOME=/path/to/jdk17 make package-android

Android release signing:

cp apps/mobile/android/key.properties.example apps/mobile/android/key.properties
# Edit key.properties so storeFile, storePassword, keyAlias, and keyPassword point to your upload keystore.
make package-android

The command builds Rust Android native libraries, a release APK, and a release AAB, then copies artifacts into release/android/.

make package

This runs Android, iOS, macOS, and Windows package targets in sequence. For CI, run each platform on its native runner when possible.

Legacy SOL_SAFEKEY_* variables are still accepted as fallbacks for existing local setups.

1. Local-first API: the desktop API binds to loopback and requires a local API token for protected routes.
2. Encrypted sensitive requests: password and secret-bearing JSON requests are encrypted before crossing the local web/API boundary.
3. Keystore-first storage: saved wallets store encrypted keystore JSON, not plaintext private keys.
4. Mobile private storage: mobile keystore files stay in app private storage; wallet metadata and biometric settings use secure storage.
5. Biometric confirmation: mobile signing actions can be gated by platform biometrics; desktop Touch ID uses macOS Keychain access control.
6. Explicit signing confirmation: payments, dApp signing, transaction sending, and Squads actions go through a confirmation screen.
7. Plaintext export controls: plaintext private key and mnemonic export are intentionally gated and should be used only for migration or local debugging.
8. No mobile Program workflows: mobile builds do not expose Program deploy, upgrade, source build, or generic invoke APIs.

Always back up encrypted keystores before depositing funds. Passwords and seed phrases cannot be recovered by FnzeroSafe.

• Desktop UI README
• Mobile README
• Mobile Internal Test Checklist
• UI Wallet User Guide
• Bot Integration Guide
• CLI User Guide
• Interactive Tutorial
• Program Deployment Guide

Recommended validation:

cargo fmt --all -- --check
cargo check --workspace --all-features
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
npm --prefix apps/desktop run lint
npm --prefix apps/desktop run build
cd apps/mobile && flutter analyze
cd apps/mobile && flutter test --dart-define=FNZERO_MOBILE_DEV_BRIDGE=true

Package validation when release artifacts are needed:

make package-android
make package-macos
# Run package-ios on a macOS host with the required iOS platform/runtime installed.
# Run package-windows on a Windows host with MSVC build tools installed.

For security-sensitive changes, include the threat model and the validation commands you ran in the pull request.

MIT License. See LICENSE.