Repository Public
1<div align="center">23<img src="docs/brand/logo.svg" alt="SP Wallet for macOS logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="SP Wallet for macOS icon" width="112" height="112">89# SP Wallet for macOS1011**The native macOS client of the private multi-chain wallet wallet.spboucher.ai — it displays, prepares and12carries the owner's passkey approvals, and verifies by itself what every approval signs. It never holds a private13key or a recovery phrase. Swift 6, SwiftUI and AppKit, no web view.**1415**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1617[](https://wallet.spboucher.ai)18-5b8cff?style=for-the-badge)1920212223242526272829-F05138?style=flat-square&logo=swift&logoColor=white)3031323334[](https://git.spboucher.ai/sp-wallet-macos/commits)35[](https://git.spboucher.ai/sp-wallet-macos/commits)36[](https://git.spboucher.ai/sp-wallet-macos/insights)37[](https://git.spboucher.ai/sp-wallet-macos)38[](https://git.spboucher.ai/sp-wallet-macos/insights)39[](https://git.spboucher.ai/sp-wallet-macos)40[](https://git.spboucher.ai/sp-wallet-macos/branches)41[](https://git.spboucher.ai/sp-wallet-macos/tags)42[](https://git.spboucher.ai/sp-wallet-macos)4344454647484950515253545556575859606162</div>6364---6566## Table of contents6768- [Overview](#-overview)69- [Features](#-features)70- [Architecture](#-architecture)71- [Stack](#-stack)72- [Repository layout](#-repository-layout)73- [Build, test, release](#-build-test-release)74- [Configuration](#-configuration)75- [Screens](#-screens)76- [Local data](#-local-data)77- [Security and privacy](#-security-and-privacy)78- [Testing](#-testing)79- [Release](#-release)80- [Writing a feature](#-writing-a-feature)81- [Troubleshooting and gotchas](#-troubleshooting-and-gotchas)82- [Known limitations](#-known-limitations)83- [Documentation](#-documentation)84- [Author](#-author)85- [License](#-license)8687---8889## 🎯 Overview9091Native macOS client (Swift 6, SwiftUI, AppKit — no web view) of the private multi-chain wallet92**wallet.spboucher.ai**. The isolated signer of the MacLustr cluster remains the only holder of the keys: this app93displays, prepares and carries the owner's passkey approvals; it never holds a private key or a recovery phrase.9495- Bundle `ai.spboucher.spwallet`, macOS 15+, universal, App Sandbox + Hardened Runtime, Developer ID, notarized.96- Development variant **SP Wallet Dev** (`ai.spboucher.spwallet.dev`): local throwaway stack only, software passkey,97 self-test. None of that code exists in the Release binary.98- Engine room: the shared Swift package `../SPWalletCore` (models, API client, canonical objects and passkey99 binding, address validation), also used by the iOS app. It lives next to this repository, not inside it.100- The interface is in French; code, identifiers and comments are in English.101102### Family103104| App | Platform | Repository | Role |105|---|---|---|---|106| **SP Wallet** | Web + API — `wallet.spboucher.ai` | [git.spboucher.ai/sp-wallet](https://git.spboucher.ai/sp-wallet) | Backend, web app and isolated signer (the only holder of the keys) |107| **SP Wallet for macOS** (this repository) | macOS 15+ native | [git.spboucher.ai/sp-wallet-macos](https://git.spboucher.ai/sp-wallet-macos) | Native client: display, preparation, verified passkey approvals |108| **SP Wallet for iOS / iPadOS** | iOS · iPadOS native | [git.spboucher.ai/sp-wallet-ios](https://git.spboucher.ai/sp-wallet-ios) | Native iPhone and iPad client |109| **SPWalletCore** | Shared Swift package | [git.spboucher.ai/sp-wallet-core](https://git.spboucher.ai/sp-wallet-core) | Models, API client, canonical objects and approval binding shared by the macOS and iOS apps |110111---112113## ✨ Features114115The full parity matrix — 38 features, each with the backend status, the production status and what was really116verified in the native app — is [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md). Verification levels used there:117**E2E** (exercised by the signed development variant against a throwaway stack), **Seen** (screen observed loading118live data), **Built** (compiled, flow not executed), **Prod** (observed against production). Nothing was executed119with real funds.120121### Wallet122123| Feature | Native app | Verification |124|---|---|---|125| **Networks** — 23: 8 EVM, BTC/LTC/DOGE/BCH, Solana, TRON, XRPL, Stellar, Cosmos, Sui, Aptos, NEAR, TON, Cardano, Polkadot Asset Hub | Portfolio: id, native coin, address, balances, RPC state, capabilities; registry-driven | E2E (23 networks, 23 addresses) |126| **Tokens** — 84 symbols, server-side verified registry | Assets list and detail, contract, decimals, price chart; states that custom tokens are not supported | E2E / Seen |127| **Balances and prices** | Exact on-chain amounts; fiat always "≈ estimation"; stale / divergent / unavailable flags | E2E |128| **Send** (all networks) | Form → draft → verified intent → review → passkey → tracking to finality | E2E incl. finalization, tampered intent, cancelled passkey, replay |129| **Receive** | Addresses, local QR, payment URI | Seen |130| **Activity** | Table, search, filters, CSV + PDF export, explorer links | E2E (history) / Built (exports) |131| **Audit journal** (hash chain) | Displayed with the server's integrity verdict | Seen |132| **Offline mode** | Read-only consultation of the last snapshots, dated, behind the Mac owner's authentication; no operation | E2E |133| **Portfolio value history** | Local series of this Mac's own observations, labelled (not served by the backend) | Seen |134135### Operations136137| Feature | Native app | Verification |138|---|---|---|139| **Swaps** — KyberSwap (8 EVM), Jupiter (Solana) | Quotes stream, executable vs comparison-only routes, verified intent review, tracking | Seen (quotes UI); execution Built |140| **Native cross-chain swaps** (THORChain) | Integrated in Swap; failure-closed explained | Built |141| **Bridge** — Circle CCTP V2 (7 EVM + Solana) | Both speeds, two legs, recovery (finish / retry-mint / reclaim / token account) with verified objects | Built |142| **Any-to-any plans** (≤ 3 legs) | DeFi → plan flow, one passkey per leg | Built |143| **NFT** inventory, item pages, media proxy | Gallery, collections, item page, ImageIO decoding, proxy-only media | Seen |144| **NFT transfers** (ERC-721/1155, 4 Solana standards) | Verdict → verified NFT intent → passkey → tracking | Built |145| **NFT market read** | Started by a button, labelled observed data | Built |146| DeFi lending / staking / LP / dApp connection | Stated as not available; no placeholder | — |147148### Trading149150| Feature | Native app | Verification |151|---|---|---|152| **Derivatives market data** (Hyperliquid, GMX, dYdX, edgeX) | Markets table, instrument page, book, funding, live quote stream | Seen (235 instruments, live stream) |153| **Paper accounts** | Separate SIMULATION mode | Built |154| **Hyperliquid live** (manual, passkey per order) | Account, authorization, pre-trade risk panel, verified order object, collateral | Built — not validated end to end |155| **GMX v2** | Read + reduce / halt / revoke only; opening absent | Built |156| **Risk engine, limits, kill switch** | View, engage (no passkey), release / loosen by passkey over verified objects | Built; kill-switch bar Seen |157| **Spot trading agents** (research / paper / real by mandate) | List, detail, create, lifecycle, mandate approval with risk acknowledgements, revoke, vault | Seen (list, engine status); flows Built |158| **Perp agents** | Paper + live by mandate | Built |159| **Market making** | Paper, evidence, pull / flatten; live approval not offered | Built |160| **Trading API** (keys, webhooks, usage) | Keys with passkey approvals, one-time secret sheet, webhooks, usage | Built |161| **Research** — markets explorer, candles, data quality | Explorer, local indicators labelled derived | Seen (911 markets) |162| **Automated research jobs** | Create with budgets, live log, results labelled AI analysis | Built |163164### Monitoring and security165166| Feature | Native app | Verification |167|---|---|---|168| **Alerts** (66 kinds), settings, webhook | List, live stream, macOS notifications, settings | Seen (live stream) |169| **Monitoring** (capital, PnL, exposure, health, capabilities) | Per-section failure states, three books apart | Built |170| **Passkey authentication** (WebAuthn) | System passkey sheet (AuthenticationServices) | Prod: Touch ID passkey sign-in confirmed by the owner (2026-11-18) |171| **App lock** (Touch ID) | Optional, authorizes nothing | Built |172| **Isolated signer, limits, anti-replay, expiry** | Never bypassed; limits and key id displayed read-only | E2E |173| **Emergency halt** | Confirmation dialog, one-way explained | Built |174| Owner setup, recovery phrase | Not in the app, by design (signer CLI only) | — |175176---177178## 🏗 Architecture179180```mermaid181flowchart LR182 subgraph MAC["SP Wallet.app — sandboxed, hardened runtime"]183 subgraph APP["App target"]184 SH["App/<br/>SPWalletApp · AppModel · Navigator · Notifier"]185 FE["Features/<br/>17 folders · 16 sidebar sections"]186 CO["Components/<br/>design system · TransactionReview"]187 AD["Core/<br/>PasskeyPresenter · AppLock · SnapshotStore · Formatting"]188 end189 CORE["SPWalletCore — shared Swift package<br/>models · API client · canonical objects · ApprovalBinding · address validation"]190 KC[("Keychain<br/>session token")]191 SN[("Sandbox container<br/>read-only snapshots")]192 PK["System passkey<br/>Touch ID · Secure Enclave"]193 end194 API["SP Wallet API<br/>wallet.spboucher.ai"]195 SG["Isolated signer<br/>the only holder of the keys"]196 CH["Blockchains<br/>23 networks"]197 SH --> FE --> CO198 FE --> CORE199 AD --> KC200 AD --> SN201 AD --> PK202 CORE -->|HTTPS| API203 API --> SG204 SG --> CH205```206207### The authorization path208209```mermaid210sequenceDiagram211 participant U as Owner212 participant A as SP Wallet.app213 participant S as API214 participant G as Isolated signer215 U->>A: fills the form (network, asset, amount, destination)216 A->>S: prepare the operation217 S-->>A: canonical object + WebAuthn options218 A->>A: recompute SHA-256 of the canonical serialization219 Note over A: refuses unless challenge = hash, relying party = wallet.spboucher.ai, user verification required220 A->>A: check the object is the operation that was asked221 A->>U: review sheet rendered from the verified object222 U->>A: explicit approval223 A->>U: system passkey sheet (Touch ID)224 A->>S: assertion225 S->>G: forward the assertion226 G->>G: verify against its own pinned passkeys, rebuild the transaction, apply limits227 G-->>S: signed and broadcast228 S-->>A: tracking broadcast → confirming → finalized229 Note over A: success is shown only at finalized230```231232- A compromised API or network path cannot make this app ask the passkey to sign something other than what is on233 screen. An object the app cannot recompute is never approved (`ApprovalError.unsupported` → the UI states it,234 with no bypass).235- Screens receive `let model: AppModel` as a parameter (never `@Environment(AppModel.self)`: it crashes on macOS 27236 inside Table cells, sheets, menus, toolbars).237- Capabilities come from the server: a feature the server reports as off is shown as off with the server's reason.238 No list of networks, markets or venues is hard-coded.239- Reference implementation of a complete operation flow: `Features/Send/SendFlow.swift` (state machine,240 idempotency key, lost-answer recovery without signing twice, tracking until terminal).241242---243244## 🧱 Stack245246| Layer | Technology | Version / setting | Role |247|---|---|---|---|248| Language | Swift | 6.0, `SWIFT_STRICT_CONCURRENCY: complete` | Everything |249| UI | SwiftUI (+ AppKit where needed) | `@Observable`, SwiftUI `Table` for long lists | Shell, 16 sections |250| Charts | Swift Charts | — | Prices, value history, research |251| Auth | AuthenticationServices | — | System passkey sheet |252| Lock | LocalAuthentication (Touch ID) | optional | Local app lock, authorizes nothing |253| Images | ImageIO / NSImage | — | NFT media, never executed |254| Shared core | `SPWalletCore` (local Swift package `../SPWalletCore`) | — | Models, API client, canonical serializations, approval binding, address validation |255| Tests | Swift Testing | hosted in the development variant | App unit tests |256| Project | XcodeGen (`project.yml`) | — | Generates the Xcode project |257| Minimum system | macOS | 15.0 | — |258259---260261## 🗂 Repository layout262263```264sp-wallet-macos/265├── project.yml # XcodeGen: app SPWallet (Release "SP Wallet", Debug "SP Wallet Dev") + SPWalletTests266├── App/ # 9 files · 754 lines — shell and state267│ ├── SPWalletApp.swift, AppDelegate.swift, RootView.swift268│ ├── AppModel.swift, AppEnvironment.swift, Navigator.swift, Notifier.swift269│ └── DevHarness.swift, DevSelfTest.swift # development variant only (#if SPW_DEV)270├── Core/ # 7 files · 416 lines — app-side adapters271│ ├── Authentication/ # PasskeyPresenter, DevPasskey272│ ├── Security/AppLock.swift273│ ├── Persistence/ # SnapshotStore, ValueHistory274│ └── Models/ # ErrorText, Formatting275├── Components/ # 7 files · 643 lines — design system and the transaction review276│ └── Theme, BalanceCard, AssetRow, TransactionRow, NetworkPicker, SecurityIndicator, TransactionReview277├── Features/ # 80 files · 19 375 lines — one folder per sidebar section278│ ├── Dashboard/, Portfolio/, Assets/, Send/, Receive/279│ ├── Swap/, Bridge/, NFTs/ (8 files), DeFi/280│ ├── Futures/ (13 files), TradingAgents/ (17 files), Research/ (12 files)281│ ├── Alerts/ (11 files), Activity/, Security/, Settings/282│ ├── Gate/ # sign-in screen283│ └── _Pending.swift284├── Resources/ # Info.plist, Info-Dev.plist, entitlements (Release / Dev), Assets.xcassets285├── Scripts/ # provision, build, tests, dev run, release, verification, notarization286├── Tests/FormattingTests.swift287└── docs/ # FEATURE_MATRIX, SECURITY_AUDIT, TEST_REPORT, FEATURE_GUIDE, brand/288```289290---291292## 🛠 Build, test, release293294```bash295python3 Scripts/provision.py # bundle ids, Associated Domains, Developer ID profiles (existing certificate and API key)296Scripts/build.sh Debug # development variant297Scripts/t.sh # unit tests298SPW_NATIVE_PORT=8760 ../SPWalletCore/Scripts/dev-stack.sh up-fork # throwaway backend (test keys, Base = local fork)299Scripts/run-dev.sh --selftest # end-to-end checks of the signed app (--section <name> --shot out.png for a capture)300Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh # dist/SP Wallet.app, dist/SPWallet-<version>.dmg301```302303| Script | Purpose |304|---|---|305| `Scripts/provision.py`, `Scripts/asc.py` | Register the bundle identifiers (release and development variants), the Associated Domains capability and the Developer ID provisioning profiles with the existing App Store Connect API key. Idempotent; no certificate is ever created; nothing secret is printed |306| `Scripts/build.sh [Debug\|Release] [derived-data-suffix]` | Generates the Xcode project and builds (errors only on the console). Products go outside `~/Desktop`. Several builds may run at once when each uses its own suffix; project generation is serialized |307| `Scripts/t.sh [derived-data-suffix]` | App unit tests (Swift Testing, hosted in the development variant), signed ad hoc without the hardened runtime |308| `Scripts/run-dev.sh [--section <name>] [--selftest] [--halt] [--shot out.png] [--keep]` | Launches **SP Wallet Dev** against the local throwaway stack. The app is copied out of DerivedData to `~/Applications/SPWalletDev` so that it never runs from `~/Desktop` |309| `Scripts/release.sh` | Release archive signed with the existing Developer ID Application identity and profiles → `dist/SP Wallet.app` |310| `Scripts/verify-release.sh` | 23 checks on the signed application |311| `Scripts/notarize.sh` | Notarizes and staples the app, then builds, signs, notarizes and staples the DMG |312| `Scripts/make-icon.sh` · `window-shot.swift` | Renders the icon SVG into the AppIcon set (needs `rsvg-convert`) · window capture helper |313314---315316## ⚙️ Configuration317318| Setting | Where | Meaning |319|---|---|---|320| Bundle identifiers | `project.yml` | Release `ai.spboucher.spwallet` ("SP Wallet") · Debug `ai.spboucher.spwallet.dev` ("SP Wallet Dev") · tests `ai.spboucher.spwallet.tests` |321| `SPW_DEV` | compilation condition, Debug only | Guards every development-only code path; `verify-release.sh` fails the release if any of its strings is found in the Release binary |322| `SPW_NATIVE_PORT` | environment | Port of the local throwaway stack (`8760` in the documented recipe) |323| `NOTARY_PROFILE` | environment | Existing `notarytool` keychain profile used by `Scripts/notarize.sh` |324| Entitlements (Release) | `Resources/SPWallet.entitlements` | App Sandbox, outgoing network, user-selected read-write files, Associated Domains `webcredentials:wallet.spboucher.ai`, Keychain access group |325| Info.plist | `Resources/Info.plist`, `Resources/Info-Dev.plist` | Category `public.app-category.finance`; Touch ID usage description |326| Signing | `project.yml` | Manual, Developer ID Application, `--timestamp`, hardened runtime |327328---329330## 🖥 Screens33133216 sidebar sections in four groups (`App/Navigator.swift`); titles are those of the French interface.333334| Group | Section | Title in the app | Read-only (available offline) |335|---|---|---|---|336| Portefeuille | `dashboard` | Tableau de bord | yes |337| Portefeuille | `portfolio` | Portefeuille | yes |338| Portefeuille | `assets` | Actifs | yes |339| Portefeuille | `send` | Envoyer | — |340| Portefeuille | `receive` | Recevoir | yes |341| Opérations | `swap` | Échanger | — |342| Opérations | `bridge` | Pont inter-chaînes | — |343| Opérations | `nfts` | NFT | yes |344| Opérations | `defi` | DeFi | — |345| Trading | `futures` | Contrats à terme | — |346| Trading | `agents` | Agents de trading | — |347| Trading | `research` | Recherche | — |348| Suivi | `alerts` | Alertes | — |349| Suivi | `activity` | Activité | yes |350| Suivi | `security` | Sécurité | — |351| Suivi | `settings` | Réglages | — |352353Plus the sign-in screen (`Features/Gate/GateView.swift`).354355---356357## 🗄 Local data358359| Item | Where | Protection |360|---|---|---|361| Private keys, seed, recovery phrase | **nowhere** — the app has no code path to them; the API exposes no route | — |362| Session token | Keychain (data-protection keychain, `WhenUnlockedThisDeviceOnly`, not synchronized) | Erased at sign-out and when the server refuses it |363| Read-only snapshots (balances, public addresses, history, NFT lists), value history | Sandbox container, complete file protection, excluded from backups | Erased by "Se déconnecter et effacer" |364| Passkey | The system (iCloud Keychain / Secure Enclave) — never visible to the app | System |365| Trading-API secrets shown once | Memory only, for the lifetime of the sheet | Never written |366367---368369## 🔐 Security and privacy370371Full review: [`docs/SECURITY_AUDIT.md`](docs/SECURITY_AUDIT.md). No independent audit or penetration test has been372performed on this client.373374- **The app verifies what it asks the passkey to sign.** It recomputes SHA-256 of the canonical serialization375 itself (`SPWalletCore`: byte-for-byte ports verified against 100 vectors generated by the backend's own376 TypeScript for 28 domains) and refuses to continue unless the challenge equals that hash, the relying party is377 `wallet.spboucher.ai` and user verification is required (`ApprovalBinding.verify`).378- **The review sheet renders the fields of the verified object**, never the server's summary: full addresses,379 exact base-unit amounts, fee ceiling, contracts called and spend approvals (`Components/TransactionReview.swift`).380- **The signer stays the last line**: it verifies the assertion against the passkeys it pinned itself, rebuilds381 the transaction from the same fields and applies its limits.382- **The local app lock (Touch ID) authorizes nothing.**383- **Platform hardening**: App Sandbox (outgoing network + user-selected files only), Hardened Runtime, no JIT /384 unsigned-memory / library-validation exception, no web engine linked, ATS without exception in Release, redirects385 not followed by the API client, CSRF header + exact `Origin` on every state-changing call, associated domain386 limited to `webcredentials:wallet.spboucher.ai`, explorer links restricted to `https`, CSV export neutralizes387 formula injection, logs carry no token, address or amount at public privacy level.388- **Remote content is untrusted**: NFT media only through the backend's media proxy, decoded with ImageIO, never389 executed.390- **Product rules** ([`docs/FEATURE_GUIDE.md`](docs/FEATURE_GUIDE.md)): never invent data (unknown is shown as391 unavailable, never as zero); never infer success ("broadcast" is not "confirmed"); simulation / paper / testnet /392 real are visually distinct and never added together; risk is spelled out before any leveraged or automated action.393394Known limits: the passkey sheet of macOS shows the domain, not the transaction (the binding is verified by the app,395not displayed by the system); a swapped app binary defeats client-side verification — distribution is Developer ID396signed and notarized, and the signer's limits remain the last line.397398---399400## 🧪 Testing401402| Suite | Result | How |403|---|---|---|404| App unit tests (`Tests/FormattingTests.swift`) | 8 / 8 | `Scripts/t.sh` |405| End-to-end self-test of the **signed, sandboxed** development variant against a throwaway stack (real API, real isolated-signer process, random test keys, Base = local fork) | **25 / 25** | `Scripts/run-dev.sh --selftest` |406| Release verification | 23 checks pass | `Scripts/verify-release.sh` |407| Notarization | App and DMG Accepted, stapled; `spctl`: Notarized Developer ID | `Scripts/notarize.sh` |408| Touch ID passkey sign-in against production (installed 1.0.0) | Works — confirmed by the owner on 2026-11-18 | owner |409410<details>411<summary><b>The 25 end-to-end checks</b></summary>412413Session · 23 networks · 23 signer addresses · portfolio without invented balance · signer reachable / not halted ·414session token in the keychain · bad checksum / own address / excess decimals refused locally · transfer prepared and415verified · intent equals the form · challenge equals the intent hash · tampered intent refused · cancelled passkey416signs nothing · approval · tracking `broadcast → confirming → finalized` read from the chain · no success before417`finalized` · replay refused · snapshot written · sign-out closes the session and removes the token · offline data418kept · API refuses after sign-out · sign-in again.419420</details>421422Measured on the development variant: idle CPU 0.0 %, resident memory ≈ 137 MB with the dashboard open.423424**Not verified** ([`docs/TEST_REPORT.md`](docs/TEST_REPORT.md)): every operation flow outside transfers (swap,425bridge, cross-chain swap, plans, NFT transfer, derivative orders, authorizations, collateral, mandates, API keys,426research jobs) is compiled and its screens were seen loading live data, but none was executed; nothing with real427funds or on a real venue account; the emergency-halt scripted check, macOS notifications delivery, PDF/CSV exports428through the save panel, the app lock, VoiceOver, an Intel Mac, macOS 15, a second Mac. No XCUITest suite exists; the429UI was checked by window captures of 13 sections.430431---432433## 📦 Release434435| Item | Value |436|---|---|437| Version | 1.0.0 (1) — tag `v1.0.0` |438| Bundle identifier | `ai.spboucher.spwallet` |439| Signing | Developer ID Application, manual, provisioning profile "SP Wallet Developer ID", `--timestamp` |440| Notarization | Application and disk image **Accepted**, stapled |441| Artifacts | `dist/SP Wallet.app`, `dist/SPWallet-<version>.dmg` (not tracked in git) |442| Architecture | Universal (`ONLY_ACTIVE_ARCH: NO` in Release) |443444`Scripts/verify-release.sh` checks the signed application: signature, hardened runtime, sandbox and entitlements,445embedded profile, no web engine, no debug entitlement, no development code or test server, no secret in the bundle.446The release scripts never create, print or modify credentials.447448---449450## 🧩 Writing a feature451452[`docs/FEATURE_GUIDE.md`](docs/FEATURE_GUIDE.md) holds the conventions. In short:453454- Every operation that moves funds or grants authority goes through the Core's verified approval path: prepare →455 `VerifiedApproval` → review sheet rendering the verified object + `BindingProof` → explicit button → passkey.456 Nothing is ever triggered by merely viewing a quote, a market or a screen. No auto-approve.457- Building blocks in `Components/`: `Page`, `Card`, `Field`, `Banner`, `ProvenanceTag`, `EmptyState`, `StatusPill`,458 `ReviewLines`, `TransactionReview`, `BindingProof`, `ProposalStatusView`, `NetworkPicker`, `Fmt.*`.459- State: `@Observable` classes; network calls through the Core's async APIs; polling stops when the view460 disappears; streams are preferred for live market data.461- Development-only code is inside `#if SPW_DEV`. File header on every file (author, path, description).462463---464465## 🩺 Troubleshooting and gotchas466467| Topic | Explanation |468|---|---|469| **`../SPWalletCore` missing** | The shared package is a sibling directory of this repository; the project does not build without it |470| **Hosted unit tests** | The test build is signed ad hoc without the hardened runtime: an injected test bundle is refused by a hardened Developer ID host |471| **Never run from `~/Desktop`** | Build products go to `~/Library/Developer/SPWallet/`; the development app is copied to `~/Applications/SPWalletDev` |472| **Parallel builds** | Use one DerivedData suffix per build (`Scripts/build.sh Debug <suffix>`); project generation is serialized |473| **`@Environment(AppModel.self)`** | Crashes on macOS 27 inside Table cells, sheets, menus, toolbars: pass `model` explicitly |474| **An operation "cannot be verified"** | The Core threw `ApprovalError.unsupported`: the app cannot recompute the object and offers no way around it, by design |475| **Self-test `--halt`** | It halts the throwaway signer for good (the halt is one-way from clients): do not run it on a shared stack |476| **Web Push** | Subscriptions are a browser feature: listed and removable here, not creatable from a native app |477478---479480## 🧭 Known limitations481482Not built in 1.0.0 (documented, no placeholder in the app): market-making live approval · mandate creation for an483API key · API-key expiry editing · editing spot agent limits after creation · GMX opening orders and GMX484authorization · editing keyed risk limits · NFT floor-estimate opt-in · offline cache of derivatives / monitoring /485research data · automatic update of the app.486487Not available on the backend, and stated as such in the app: DeFi lending / staking / LP / dApp connection · NFT488market write, item valuation, Ordinals transfer · dYdX and edgeX trading (market data only) · custom tokens.489490---491492## 📚 Documentation493494| Document | Content |495|---|---|496| [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) | Parity with the backend, feature by feature, with what was really verified |497| [`docs/SECURITY_AUDIT.md`](docs/SECURITY_AUDIT.md) | What the client holds, the authorization path, hardening, known limits |498| [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) | What was run, results, what was not verified |499| [`docs/FEATURE_GUIDE.md`](docs/FEATURE_GUIDE.md) | Conventions for writing a feature |500501---502503## 👤 Author504505<div align="center">506<img src="docs/brand/icon.png" width="64" height="64" alt=""><br>507508**Simon-Pierre Boucher** — design, development, operations<br>509[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai510511</div>512513---514515## 📄 License516517All rights reserved © 2026 Simon-Pierre Boucher.518