Stashi Wallet

Stashi Wallet is a cross-platform Pirate Chain wallet with a Flutter user interface and a Rust core. The repository includes the application, the Rust wallet and sync crates, build scripts, and the project-owned documentation used for release and verification work.

This repository is under active development. Before distributing builds, review the release notes, the security notes, and the verification instructions in docs/.

User guide

The Stashi Wallet User Guide covers installation, recovery, payments, privacy, key management, release verification, and troubleshooting for desktop and mobile. Its source is maintained under docs/user-guide/, and GitHub Actions publishes the approved PDF after guide changes reach main.

Repository layout

• app/
  Flutter application code, desktop packaging hooks, generated localization files, and the desktop updater.
• crates/
  Rust wallet, storage, sync, service, CLI, native FFI, and supporting crates.
• bindings/ Native SDK and bridge wrappers for iOS, Android, and React Native on top of the repo-owned native FFI crate.
• docs/
  Project-owned documentation for security, build verification, and localization.
• scripts/
  Platform build, packaging, SBOM, provenance, and asset-fetch scripts.
• release-artifacts.toml Version manifest used to decide which backend deliverables should be published on release tags.
• generate_ffi_bindings.sh
  Generates Flutter Rust Bridge bindings for the app and Rust FFI layer.

Supported build outputs

Current build scripts produce the following release artifacts:

• Windows: installer .exe and portable .zip
• Linux: .AppImage, .flatpak, and .deb
• macOS: .dmg
• Android: split APKs and .aab
• iOS: .ipa

Linux AppImage and Debian releases support Ubuntu 22.04 and newer. Their ABI contract is glibc 2.35: release builds run on Ubuntu 22.04, Linux i2pd is built from its current immutable source revision on that same baseline, and CI scans every bundled ELF before packaging. Flatpak releases use their declared Freedesktop runtime but pass the same bundled-binary compatibility check.

Additional backend deliverables are built from the Rust workspace:

• piratewallet-cli under crates/piratewallet-cli/
• pirate-qortal-cli under crates/pirate-qortal-cli/
• Qortal desktop JNI library under crates/pirate-qortal-jni/
• pirate-ffi-native under crates/pirate-ffi-native/
• iOS SDK XCFramework inputs under bindings/ios-sdk/
• Android SDK module and AAR packaging inputs under bindings/android-sdk/
• React Native wrapper under bindings/react-native-pirate-wallet/ with exact-version Android and iOS binary packages alongside it

Backend architecture

The shared app-facing wallet backend now lives in:

• crates/pirate-wallet-service

The Flutter Rust Bridge crate:

• crates/pirate-ffi-frb

is now a thin wrapper surface over that backend for Flutter-specific FFI generation.

The architecture, performance work, and correctness guarantees behind the Supernova shielded-chain sync engine are documented in docs/sync-engine.md.

Platform packaging is handled by the scripts in scripts/. Use those scripts for release artifacts; they checksum-prefetch the platform KDF binary and the SDK-pinned coin snapshot, materialize only its configured JSON and icon paths, then disable the dependency transformer's network fetches.

For an unpackaged development build, run the same preflight after flutter pub get --enforce-lockfile and before Flutter. For example:

(cd app && flutter pub get --enforce-lockfile)
bash scripts/prepare-flutter-build.sh windows
(cd app && flutter build windows)

Replace windows with android, ios, linux, or macos. A raw flutter build without this preflight is unsupported: the upstream transformer may otherwise attempt network downloads or mutate its resolved build config. The preflight does not disable runtime coin updates.

Run Flutter unit and widget tests through the checked-in wrapper so the asset transformer is never invoked by the test bundle:

bash scripts/test-flutter.sh

Toolchain

The project is built and tested in CI with these pinned versions:

• Rust 1.90.0
• Flutter 3.47.2
• Dart 3.13.2 (bundled with Flutter)
• flutter_rust_bridge_codegen 2.11.1
• CocoaPods 1.17.0 for macOS and iOS builds

The Rust pin is defined in rust-toolchain.toml. CI pins are defined in .github/workflows/ci.yml.

To check local tools against the current pins:

FLUTTER_VERSION=3.47.2 \
DART_VERSION=3.13.2 \
COCOAPODS_VERSION=1.17.0 \
scripts/verify-toolchain.sh

Nix flake

The repository includes a checked-in flake that mirrors the committed native build scripts.

Development shells:

nix develop
nix develop .#ci
nix develop .#build

Native flake package outputs:

• Linux hosts:
  • .#linux-appimage
  • .#linux-flatpak
  • .#linux-deb
  • .#android-apk
  • .#android-bundle
• macOS hosts:
  • .#macos-dmg
  • .#ios-ipa

Windows packaging is not exposed through the flake. Use scripts/build-windows.sh for Windows release artifacts.

Build prerequisites

Common requirements:

• Rust toolchain with rustfmt and clippy
• Flutter stable SDK
• flutter_rust_bridge_codegen
• protoc

Platform-specific requirements:

• Windows:
  • Visual Studio 2022 C++ build tools
  • OpenSSL
  • PowerShell
  • Inno Setup if you want the installer artifact
• Linux:
  • Flutter Linux desktop dependencies
  • flatpak-builder for Flatpak output
  • dpkg-deb and dpkg-scanpackages for Debian and APT output
  • appimagetool or pinned APPIMAGETOOL_URL and APPIMAGETOOL_SHA256
  • pinned APPIMAGE_RUNTIME_URL and APPIMAGE_RUNTIME_SHA256 values for AppImage output
• macOS:
  • Xcode and CocoaPods
  • Apple signing and notarization credentials for signed distribution
• Android:
  • Android SDK and NDK
  • Java runtime compatible with your Android toolchain
• iOS:
  • macOS
  • Xcode
  • CocoaPods
  • Apple signing configuration for signed IPA export

Getting started

1. Fetch Flutter dependencies:

cd app
flutter pub get --enforce-lockfile
cd ..

2. Generate Flutter Rust Bridge bindings:

bash generate_ffi_bindings.sh

3. Build the target you need.

Release build commands

Windows:

bash scripts/build-windows.sh

Linux:

bash scripts/build-linux.sh appimage
bash scripts/build-linux.sh flatpak
bash scripts/build-linux.sh deb

macOS:

bash scripts/build-macos.sh

Android:

bash scripts/build-android.sh apk
bash scripts/build-android.sh bundle

Android SDK packaging for release distribution:

bash scripts/build-android-sdk.sh

iOS:

bash scripts/build-ios.sh false

The desktop build scripts fetch and verify the pinned Tor Browser and i2pd assets before packaging. If you intentionally want to skip that step for a local build, set SKIP_TOR_I2P_FETCH=1.

Development notes

• The generated Flutter FFI files live under app/lib/core/ffi/generated/.
• The app loads translations from app/assets/i18n/.
• Rust quality checks:

cd crates
cargo fmt --all
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features --locked

Documentation index

• Stashi Wallet user guide: docs/user-guide/README.md
• Supernova sync engine architecture and performance: docs/sync-engine.md
• Build verification: docs/verify-build.md
• Security notes: docs/security.md
• Key import and sync debug telemetry: docs/debug-key-telemetry.md
• Release process: docs/release-process.md
• CLI guide: docs/cli.md
• Qortal integration handoff: docs/qortal-handoff.md
• Qortal CLI test adapter: docs/qortal-cli.md
• iOS SDK notes: docs/native-sdk-ios.md
• iOS SDK API reference: docs/native-sdk-ios-api.md
• Android SDK notes: docs/native-sdk-android.md
• Android SDK API reference: docs/native-sdk-android-api.md
• React Native plugin notes: docs/react-native-plugin.md
• Audit report: docs/audit-2026-03-31.md
• Migration notes: docs/migration.md
• Translation workflow: docs/localization/TRANSLATION_WORKFLOW.md
• Contribution guide: CONTRIBUTING.md
• Flutter app notes: app/README.md
• UI structure: app/DESIGN_SYSTEM.md

Release and verification outputs

Project scripts also generate or consume:

• SHA-256 checksum files for release artifacts
• SBOMs via scripts/generate-sbom.sh
• provenance files via scripts/generate-provenance.sh

For verification and release handling details, use the documents under docs/ rather than this README.