# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview Dash Wallet is an iOS cryptocurrency wallet for the Dash network — a fork of breadwallet implementing SPV (Simplified Payment Verification) for fast mobile performance. Advanced features include DashPay (user-to-user transactions), CoinJoin (privacy), and integrations with external services such as Uphold and Coinbase. ## Build & Setup ```bash pod install # Install dependencies (run after Podfile changes; avoid `pod update` unless needed) open DashWallet.xcworkspace # Always open the workspace, not the .xcodeproj ``` - **Schemes**: `dashpay` (DashPay-enabled — **the working scheme during the SwiftDashSDK migration**), `dashwallet` (main app; not kept green on this branch) - **Configurations**: Debug, TestNet, Release, TestFlight - **Canonical build** — the SwiftDashSDK FFI xcframework ships an arm64-only simulator slice, so always force `ARCHS=arm64`: ```bash xcodebuild -workspace DashWallet.xcworkspace -scheme dashpay -sdk iphonesimulator \ -destination 'generic/platform=iOS Simulator' ARCHS=arm64 build ``` - **Tests**: `DashWalletTests` runs against the `dashpay` host app through the `dashwallet-dashpay` scheme, in the **Debug** configuration (the only one with `ENABLE_TESTABILITY`, which every `@testable import dashpay` needs). Cmd+U in Xcode, or: ```bash xcodebuild test -workspace DashWallet.xcworkspace -scheme dashwallet-dashpay -configuration Debug \ -destination 'platform=iOS Simulator,name=iPhone 17' ARCHS=arm64 ONLY_ACTIVE_ARCH=YES ``` Every test file must be in the target: files under `DashWalletTests/Notifications/` are picked up automatically (synchronized folder), everything else needs the four `project.pbxproj` entries. `scripts/ci/check_test_target_membership.py` fails CI on a forgotten file. The host app needs the gitignored `*-Info.plist` files in `DashWallet/`; without the real ones, `scripts/ci/make-placeholder-plists.sh` writes inert placeholders. CI runs the suite on every PR (`.github/workflows/unit-tests.yml`) against the platform commit pinned in `.platform-ref`. ### Required tools - Xcode 16+ - CocoaPods (`gem install cocoapods`) - iOS deployment target: **18.0** (raised from 14.0 during the migration — Podfile `platform :ios, '18.0'` + post_install) - Rust toolchain (builds the SwiftDashSDK FFI) ### Optional tools - `swiftformat`, `swiftlint`, `clang-format` (Objective-C), `bartycrouch` (localization) ### External repo dependencies (expected as sibling directories) ``` ../platform/ # dashpay/platform monorepo — SwiftDashSDK lives at packages/swift-sdk (local SPM dependency) ../dapi-grpc/ # gRPC API definitions ../dashwallet-ios/ # This repository ``` The SwiftDashSDK `DashSDKFFI.xcframework` is **gitignored** — after pulling `../platform`, rebuild it: ```bash cd ../platform/packages/swift-sdk && ./build_ios.sh --target ios --target sim ``` If the app fails with missing SDK symbols (e.g. "no member …"), verify the `../platform` checkout and rebuild both XCFramework slices. ## Figma Figma Dev Mode MCP setup and cleaning Figma-exported SVG assets for iOS are covered by the `figma-assets` skill (`.claude/skills/figma-assets/SKILL.md`). ## Architecture - `DashWallet/Sources/Infrastructure/SwiftDashSDK/` — the SwiftDashSDK adapter layer (host, wallet runtime/state, SPV coordinator, transaction sender, identity coordinators) — the app-side boundary to the Rust SDK ### Notable services & files - `WalletSendService.swift` — the send boundary: auth → build+sign (`SwiftDashSDKTransactionSender`) → user confirm → broadcast. `SendCoinsService.swift` is a thin programmatic wrapper over it. - `SwiftDashSDKHost.swift` / `SwiftDashSDKWalletRuntime.swift` / `SwiftDashSDKWalletState.swift` / `SwiftDashSDKSPVCoordinator.swift` — SDK lifecycle ownership, published wallet state (balance), and chain sync - `CurrencyExchanger.swift` — fiat currency conversion - `DatabaseConnection.swift` + `Migrations.bundle/` — SQLite (schema changes require a new timestamped migration) - `MainTabbarController.swift` — tab-based navigation - `UIHostingController+DashWallet.swift` — UIKit ↔ SwiftUI bridge ## SwiftDashSDK ownership and upgrade compatibility The DashSync dependency unlink is complete. The app and SwiftDashSDK own all live wallet behavior. `DASHSYNC_KEY_MIGRATION.md` remains the specification for the frozen upgrade-time mnemonic import contract. - **No DashSync runtime**: do not restore the pod, direct imports, `DWEnvironment`, or live `DS*` wallet/transaction/identity objects. Read wallet state through the app-owned SwiftDashSDK boundaries. - **Sync gating**: never gate on SPV `state == .synced` — dash-spv's steady state when fully synced is `waitForEvents` at progress ≈ 1.0 (`.synced` is a transient window). Gate on `SyncingActivityMonitor` (`.syncDone`). - **Sends**: every spend goes through `WalletSendService` (standard) or `SwiftDashSDKTransactionSender` (selected-input / sweep). Never call `CoreTransactionBuilder` from UI code. `prepare*` never broadcasts; broadcast happens only on explicit confirm. - **Mnemonic ownership**: stored as plain keychain bytes via SwiftDashSDK `WalletStorage` (the iOS keychain is the security boundary — there is no PIN-encryption layer). Creation/import/migration route through `SwiftDashSDKHost`; deletion routes through `SwiftDashSDKWalletWiper`. The migrator supports multiple wallets and never deletes DashSync-owned `org.dashfoundation.dash` entries. Don't add ad-hoc `WalletStorage()` readers or choose the first mnemonic — resolve the active wallet through `SwiftDashSDKHost` / `WalletEnvironment.activeWalletId(for:)`. - **CrowdNode release posture**: temporarily suspend/hide CrowdNode for the migration release. Its implementation is already app/SDK-owned, so it does not block DashSync teardown and must not regain a DashSync fallback. - **Platform release pin**: temporary local integration branches are development-only. Upstream all required changes and make the final migration/release build consume platform `v4.2-dev` (or an explicitly selected release SHA/tag). - **Mainnet is the fresh-install default**: `WalletEnvironment.networkKind` returns `.mainnet` when `CURRENT_CHAIN_TYPE_KEY` is absent, in ALL build configurations; testnet requires an explicit in-app switch, which writes the key. (This reverses the temporary testnet default of 2026-07-03, taken while mainnet Platform DAPI was unreachable — revisited by the owner 2026-08-07.) An install that never used the switcher moves to mainnet on its next launch. When touching this, verify mainnet Platform DAPI is actually reachable in the SDK build being shipped. ## UI Development — SwiftUI-First (Mandatory) All new UI MUST be built in SwiftUI with a ViewModel. Do **not** add new Storyboards, XIBs, or UIViewControllers containing UI logic. - Keep views lightweight; put business logic in `ObservableObject` ViewModels (`@MainActor`, `@Published` state). - Concretely banned inside SwiftUI `View` structs: FFI/SDK calls, fee math, direct auth calls (use `AuthenticationGate`), `DSChain`→network mapping, protocol constants. Those live in the ViewModel or a service. - When integrating with existing UIKit navigation, use a thin `UIHostingController` wrapper only. - Maintain existing UIKit code but don't extend it; migrate a screen to SwiftUI when substantially reworking it. ## Accessibility Icon-only controls must carry an `accessibilityLabel` — see `ACCESSIBILITY.md`. Check your work before committing: ```bash scripts/a11y_audit.py --check # what CI runs; fails only on NEW findings scripts/a11y_audit.py --path "DashWallet/Sources/UI/Payments" # one screen ``` `accessibilityIdentifier` is an XCUITest id and is never spoken — it does not count as a label. `.github/workflows/accessibility.yml` enforces this on every PR. ## Architecture Guardrails (check before every commit) Distilled from the 2026-07 branch review (`ARCH_REVIEW_2026-07-03.md`) — each rule exists because we shipped its violation: 1. **Never copy-then-adapt.** If a helper you need is `private`/`fileprivate` in another file (auth gate, main-thread trampoline, SwiftData lookup), promote it to `internal` and reuse it — do not paste a copy, even "temporarily". Copies drift: one clone silently lost the auth watchdog, another missed a cold-launch bug fix. Shared primitives to reuse by name: `AuthenticationGate` (WalletSendService.swift) for PIN/biometric prompts; `ScriptAddressCodec` for address↔script. 2. **Comments state what the code does, never what it should do.** Before writing "X does Y", verify Y's symbol exists and is called (grep it). A deferred behavior is written as `TODO(label): ` — never as present-tense description. (We shipped a comment claiming a method "does the mirror writes" that didn't exist, and a "confirmation with the real fee" that was neither.) 3. **No stub-and-assert.** A stubbed path must not report success: no UI copy claiming a check passed that never ran, no no-op methods that pretend to act, no silently discarded user input. Stubs throw, disable the control, or are compile-gated. Model unknown data as unknown (`nil` / `.unknown` case) — never fabricate plausible defaults (`.classic`, `.ok`, `[]`, `false`). 4. **New singletons need a reason.** Don't add another `static let shared` in `Sources/Infrastructure/` without a protocol seam or a written justification in the type doc; prefer injecting. One file = one responsibility — a "coordinator" that accumulates published UI counters, storage wipes, and money movement gets split. 5. **Never re-emit another system's notification names.** Re-posting `DS*` notification strings from new state poisons every future grep audit. New state gets a new typed publisher/notification; consumers migrate. 6. **No debug residue in commits:** no session tags in log lines (à la `CJTEST`), no plan-diary comments ("Row #17 stage A", "M5/M6"), no stale line-number cross-references in doc comments. Use `TODO(label)` and link docs instead. 7. **Legacy compatibility stays bounded and honest.** Do not restore staged DashSync/SDK paths. Only the frozen key migrator may read the old `org.dashfoundation.dash` keychain layout. A seam method's name must match its behavior (`prepare` must not spend; `broadcast` must broadcast). ## Code Style - **Swift**: SwiftFormat / SwiftLint (configs in `.swiftformat`, `.swiftlint.yml`). Avoid wholesale `@objcMembers` exposure (enforced by a custom SwiftLint rule). - **Objective-C**: NYTimes Objective-C Style Guide. - 4-space indentation, 180-character line limit (100 recommended). ## Feature Flags (conditional compilation) - `DASHPAY` — DashPay features (username registration, contacts, invitations, governance voting); built via the `dashpay` scheme. - `DASH_TESTNET` — defined only in the **dashwallet** target's Debug + TestNet configurations. The **dashpay** scheme's Debug build has `DEBUG` + `DASHPAY` but **not** `DASH_TESTNET` — so anything that must apply to dev builds of both schemes gates on `#if (DEBUG || DASH_TESTNET)`, never `DASH_TESTNET` alone. ## Security - Legacy surface: jailbreak detection, hardware encryption, Secure Enclave integration (DashSync-era). - Migration posture changes to keep in mind: the wallet mnemonic is plain keychain data (`WalletStorage`) — device passcode/keychain is the boundary, with no app-side PIN encryption of the seed; ChainLock/InstantSend status is trusted from SwiftDashSDK's context byte (the app no longer does local BLS quorum verification). ## Gotchas (read before touching these areas) ### Versioning — never hardcode versions All targets use `$(MARKETING_VERSION)`. Never edit version strings in `Info.plist` directly — update **Marketing Version** in Xcode target settings (General tab). When bumping for release, update **every** target (dashwallet, dashpay, TodayExtension, WatchApp, WatchApp Extension). Verify all entries agree: ```bash # Should print exactly 1 grep -o "MARKETING_VERSION = [^;]*" DashWallet.xcodeproj/project.pbxproj | sort -u | wc -l ``` ### DWUpholdMainnetConstants.m gets reformatted on build A "Run Script - clang-format" build phase adds a stray blank line to this file. If `git status` shows only-whitespace changes there, restore it before committing: ```bash git restore DashWallet/Sources/Models/Uphold/DWUpholdMainnetConstants.m ``` ### CocoaPods deployment targets (post_install) The Podfile `post_install` script must set deployment targets per platform — setting `IPHONEOS_DEPLOYMENT_TARGET` on watchOS targets breaks the build (CocoaPods 1.15.2+ is strict): ```ruby post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| if target.platform_name == :ios config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '18.0' elsif target.platform_name == :watchos config.build_settings['WATCHOS_DEPLOYMENT_TARGET'] = '4.0' end end end end ``` ### Localization file encoding differs by target — check before converting Encoding is **not** uniform across the repo, so never assume: - **`DashWallet/*.lproj/Localizable.strings` and `Localizable.stringsdict` (main app) — UTF-8, no BOM.** All 43 locales, both file types. Plain `grep` works. Do **not** run `iconv` on these and do **not** "restore" them to UTF-16 — that would break the plain-text tooling (bartycrouch, `plutil`, review diffs) the repo relies on. ```bash grep '"Spend"' DashWallet/de.lproj/Localizable.strings ``` - **`WatchApp/*.lproj/Interface.strings` — UTF-16LE with BOM** for 40 of 43 locales (`en`, `zh-Hans`, `zh-Hant-TW` are UTF-8). These are the files where `grep` reports "Binary file matches". They are storyboard-derived, so the keys are ObjectIDs rather than English text: ```bash iconv -f UTF-16LE -t UTF-8 WatchApp/de.lproj/Interface.strings | grep '.title' ``` Check first rather than trusting this list — and note `file` reports pure-ASCII UTF-8 as `us-ascii`, which is still UTF-8: ```bash head -c 4 DashWallet/de.lproj/Localizable.strings | xxd # 2f2a 204e -> "/* N" = UTF-8 head -c 4 WatchApp/de.lproj/Interface.strings | xxd # fffe ... = UTF-16LE BOM ``` Translations sync via Transifex: `tx push -s` (push source) / `tx pull -a` (pull all). Let Xcode and BartyCrouch manage the files, and keep each file in whatever encoding it already has. A Transifex pull can hand back UTF-16 or BOM-prefixed catalogs. `./scripts/convert_strings_to_utf8.sh` normalises them back — it is scoped to `DashWallet/*.lproj` on purpose and is idempotent, so it leaves already-correct files byte-identical. Keep that scope: a bare `find . -name '*.strings'` would also rewrite the UTF-16LE WatchApp catalogs and anything under `Pods/`.