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 has no
expo-updatesand no OTA job. Builds are local. - Licence: MIT OR Apache-2.0 (LICENSE-MIT, LICENSE-APACHE; third parties in NOTICE.md).
- Contributing: CONTRIBUTING.md; run
scripts/check.shbefore a pull request. Issues: docs/ops/issues.md. Security reports: SECURITY.md, never a public issue.
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.
- 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,
WhenUnlockedThisDeviceOnlyand 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+,minSdkVersion30). The encrypted phrase is kept in no-backup storage.
- iOS: a Keychain item,
- Every send goes through that prompt.
- Phrase screens:
- Android:
FLAG_SECUREblocks 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.
- Android:
- 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.
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 cratesHost 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.
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.soFrom 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 phoneAndroid 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.xcworkspacein Xcode, check that Signing & Capabilities shows the Principle Zero Labs team (3QCP92DS3P, set byapp.json), set Product → Scheme → Edit Scheme → Run → Build Configuration to Release, choose the phone, and press ▶. (Command-line signing with-allowProvisioningUpdateshas failed on this Mac; the Xcode window works.) - Android:
cd android && ./gradlew assembleRelease -PreactNativeArchitectures=arm64-v8awith JDK 17 (JAVA_HOME), thenadb 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.