Skip to content
principlezerolabsPublic

About

Wizard: a self-custodial Zcash wallet for iOS and Android (testnet alpha)

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Wizard

Principle Zero Labs' self-custodial Zcash wallet. Testnet only for Phase 1. Product and plan: docs/overview.md and docs/specs/wizard-phase1-spec.md; look: docs/design/wizard-design-guide.md; flows and UX gaps: docs/design/wizard-user-flows.md; engine history: docs/research/spike-wallet-engine.md.

engine/          Rust crate `wizard-wallet`: librustzcash 0.25 + lz-client-uniffi in one library, UniFFI surface
wallet-native/   @wizard/wallet-native, the wallet core any UI can use (zspace#316):
  ios/, android/   Expo module over the engine: EngineHost, background sync, phrase storage,
                   and the native phrase and confirmation screens
  src/             the module's JS API, WalletProvider/useWallet, recipients, `.zcash` names,
                   the price, preferences, money and link formatting (unit tested)
mobile/          Expo app @wizard/mobile (SDK 56, RN 0.85.3, expo-router): Wizard's UI on wallet-native
  app/             screens: Welcome, Home, Pay (who, amount), Scan, Receive, Request, Sent, the transaction page, Me, Developer
  src/             design tokens, shared components, activity wording, navigation, the art
art/      build.py draws all the line art, the interface signs and the app icon (design guide §7): `python3 art/build.py --png`
          sheet.py shows the art while you draw it and checks it: `python3 art/sheet.py --measure`

Wizard was built in Principle Zero Labs' private monorepo until November 2026. This repo starts from that code; the earlier history is kept privately and is available to auditors on request. References written zspace#374 in comments are to that monorepo's issues and pull requests; this repo's own issues are new.

Rules the code keeps

  • The recovery phrase is generated, stored, shown, typed and used only in native code (Rust, Swift, Kotlin). No JavaScript function takes or returns it or any key; JavaScript starts each flow (create, back up, show, restore, wipe) and learns only how it ended.
  • Storage needs authentication on every read:
    • iOS: a Keychain item, WhenUnlockedThisDeviceOnly and not synced, with .userPresence (Face ID or Touch ID, falling back to the passcode).
    • Android: the phrase is encrypted with a Keystore AES key (StrongBox where present) that needs a strong biometric or the screen lock for each use, through BiometricPrompt (so Android 11+, minSdkVersion 30). The encrypted phrase is kept in no-backup storage.
  • Every send goes through that prompt.
  • Phrase screens:
    • Android: FLAG_SECURE blocks screenshots, screen recording and the recent-apps preview.
    • iOS: iOS can't block screenshots. The words are hidden while the screen is recorded or mirrored, and the user is warned after a screenshot.
    • Word entry: the restore field turns off keyboard suggestions and learning.
  • The wallet database holds viewing keys only.
  • One Rust library per app, containing both this crate and Lantern Zero's client.
  • No Sapling parameters: sends use the Ironwood (and Orchard) pools only; Sapling-only and transparent recipients are refused.
  • The engine refuses a server that isn't on testnet.

Engine (host)

Needs Rust 1.89+.

cd engine
cargo test
cargo run --release --example smoke -- info                       # server reports testnet?
cargo run --release --example smoke -- --wallet a new             # prints a utest1… address
cargo run --release --example smoke -- --wallet a sync
cargo run --release --example smoke -- --wallet a balance
cargo run --release --example smoke -- --wallet a send <utest1…> <zatoshis> "memo"
cargo run --release --example smoke -- --wallet a history
./scripts/swift-host-test.sh                                     # one library, Swift calls both crates

Host wallets live in engine/data/<name>/ (git-ignored). For the host tool only, the phrase is kept there in phrase.secret. Fund a testnet address from zcashfaucet.jinolabs.xyz.

Mobile libraries

cd engine
rustup target add aarch64-apple-ios aarch64-apple-ios-sim aarch64-linux-android x86_64-linux-android
cargo install cargo-ndk
./scripts/gen-bindings.sh      # Swift + Kotlin for both crates (UniFFI library mode)
./scripts/build-ios.sh         # target/ios/WizardWallet.xcframework + include/
./scripts/build-android.sh     # target/android/jniLibs/<abi>/libwizard_wallet.so

App

From the repo root, pnpm install once (pnpm 10, Node 22). Then:

cd mobile
pnpm engine                    # builds the engine for both platforms, copies it into wallet-native (~10 min cold)
npx expo prebuild              # generates ios/ and android/ (git-ignored)
pnpm ios                       # debug, simulator; needs `npx expo start --dev-client`
pnpm android                   # debug, emulator or USB phone

Android pushes need Firebase's google-services.json, which is not in the repo (Firebase advises against it for open-source apps). app.config.js uses WIZARD_GOOGLE_SERVICES_FILE or ~/.config/wizard/google-services.json when present. Without one the app still builds and runs; Lantern Zero alerts then arrive only while it's open. To get pushes in your own build, make a Firebase project, add an Android app with your application id, and point that variable at its file. Pushes also need a Lantern Zero gateway that can send to your Firebase project.

Release builds carry the JavaScript bundle, so they need no Metro:

  • iPhone: open ios/Wizardtestnet.xcworkspace in Xcode, check that Signing & Capabilities shows the Principle Zero Labs team (3QCP92DS3P, set by app.json), set Product → Scheme → Edit Scheme → Run → Build Configuration to Release, choose the phone, and press ▶. (Command-line signing with -allowProvisioningUpdates has failed on this Mac; the Xcode window works.)
  • Android: cd android && ./gradlew assembleRelease -PreactNativeArchitectures=arm64-v8a with JDK 17 (JAVA_HOME), then adb install app/build/outputs/apk/release/app-release.apk. Release is signed with the debug key for now; the Play upload key comes with M6.

Payments always end in the native confirmation sheet (ConfirmSheet.swift / ConfirmSheet.kt). It is drawn from Rust's proposal by id, not from anything JavaScript passes, and Send asks for Face ID or the fingerprint.

Background sync (spec §9): iOS BGAppRefreshTask and BGProcessingTask, and a 15-minute WorkManager job on Android. Both use the same engine as the app (EngineHost). Every sync goes into a log, sync-runs.sqlite, which the developer screen shows. On the host, smoke -- --wallet a syncs prints it.

The developer screen (Me → Developer screen) keeps the raw balance, sync, the sync log, a plain send form and checks. EXPO_PUBLIC_WIZARD_AUTORUN=1 makes it create a wallet if there is none, probe Lantern Zero and sync, logging each step, for runs without tapping.

About

Wizard: a self-custodial Zcash wallet for iOS and Android (testnet alpha)

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages