SPB Git

Repository Public

FEATURE_GUIDE.md 7.5 KB 79 lines markdown

1# SP Wallet macOS — guide for writing a feature23Native macOS client (Swift 6, SwiftUI, AppKit where needed, macOS 15+) of the SP Wallet backend. **No web view, ever.**4The engine room is the shared Swift package `../SPWalletCore` (owned by another session: READ-ONLY for you — never edit it; report5what is missing or wrong instead). Backend reference (READ-ONLY): `~/Desktop/Cluster/projets/sp-wallet-native` (TypeScript; web screens6in `apps/web/src/screens/*.tsx` show what the product does; `services/api/src` is the truth about what is really operational).78## Non-negotiable rules (a financial app)9101. **Never invent data.** No placeholder balance, price, position, PnL or status. Unknown = "—" or an explicit "Indisponible" state.11   A value read from a failed source is shown as unavailable, never as zero.122. **Never infer success.** Only the server's state is shown, with its exact meaning. "broadcast"/"sent"/"submitted" is not13   "confirmed". A bridge is done only when the destination network confirmed. Use `ErrorText.state` / `StatusPill` for proposals.143. **Every operation that moves funds or grants authority goes through the Core's verified approval path**: prepare → the Core15   verifies that the WebAuthn challenge is the SHA-256 of the canonical object (`VerifiedApproval`) → a REVIEW SHEET that renders the16   fields OF THAT VERIFIED OBJECT (not the server's summary) in full (full addresses, exact amounts, fees, minimum received, slippage,17   contracts called, spend approvals, expiry) + `BindingProof(digest:expiry:)` → an explicit button → `model.authenticator` (passkey).18   If the Core throws `ApprovalError.unsupported` the UI says the operation cannot be verified and offers NO way around it.19   Nothing is ever triggered by merely viewing a quote, a market or a screen. No auto-approve, no default-max leverage.204. **Simulation / paper / testnet / real are visually distinct** (colour + label on every figure and every button). Never add figures21   across modes. Labels: `ProvenanceTag(p: .simulated)`, `.estimate`, `.verified`, `.stale`, `.unavailable`, `.ai`.225. **Capabilities come from the server** (execution endpoints, capability lists, locks). A feature the server reports as off is shown23   as off WITH the server's reason; do not hide it and do not pretend it works. Never hard-code a list of networks/markets/venues.246. Risk is spelled out before any leveraged or automated action: notional, leverage, margin, estimated liquidation price, fees,25   funding, loss risk, collateral at stake. Never promise profitability. Backtests and AI analyses are labelled as such.267. Offline / signed-out (`!model.canOperate`): reads may show cached data with its date; every operation control is disabled.278. Remote content (NFT media, metadata, names) is untrusted: images only through the backend's media proxy when the Core offers it,28   decode with ImageIO/NSImage, never execute, never render HTML/SVG scripts, never open non-https links, show unknown/unsafe flags.299. No secret in logs, UserDefaults or files. API keys shown once are never persisted by the app.3010. UI text in **French** (code, identifiers and comments in English). File header on every file:31    `// Author: Simon-Pierre Boucher — contact@spboucher.ai` / `// File: <path>` / `// Description: <what and why>`.3233## App conventions3435- Screens receive `let model: AppModel` **as a parameter** (never `@Environment(AppModel.self)`: it crashes on macOS 27 inside36  Table cells, sheets, menus, toolbars). Pass it explicitly to every sub-view and sheet.37- `model.client` (`APIClient`) → build the Core APIs yourself: e.g. `SwapAPI(model.client)`. `model.authenticator` is the passkey.38  `model.canOperate`, `model.isOffline`, `model.networks?.value`, `model.portfolio?.value`, `model.accounts?.value`,39  `model.network(id)`, `model.address(on:)`, `model.price(symbol)`, `model.currency`, `model.settings`, `model.describe(error)`40  (French error text; always use it for errors), `await model.refreshAll()` after an operation changes balances.41- Building blocks in `Components/`: `Page(title, subtitle:) { }`, `Card(title, trailing:) { }`, `Field(label:value:mono:)`,42  `Banner(.info/.warning/.danger/.ok, text)`, `ProvenanceTag`, `EmptyState`, `AssetBadge`, `StatusPill(raw:)`, `ReviewLines(lines:)`43  with `ReviewLine(label:value:style:)`, `TransactionReview(intent:digest:network:ownAddresses:warnings:extra:)` (any `Intent`-based44  operation: transfer, swap, bridge, xswap, venue deposit, GMX), `BindingProof(digest:expiry:)`, `ProposalStatusView(proposal:)`,45  `NetworkPicker`, `AssetPicker`, `Fmt.amount/fiat/price/percent/date/relative/short/chunked`, `Theme.positive/negative/warning`,46  `copyToPasteboard`, `Notifier.post(title:body:)` (terminal outcomes only), `SnapshotStore.shared.save/load` (offline cache of47  read-only answers), `JSONValue.displayText`.48- Reference implementation of a complete operation flow: `Features/Send/SendFlow.swift` (state machine, idempotency key kept while49  the form does not change, lost-answer recovery without signing twice, tracking until terminal) and `Features/Send/SendView.swift`50  (form, review sheet, tracking). Follow that shape: an `@MainActor @Observable final class XxxFlow` + views.51- State: `@Observable` classes, `@State`/`@Bindable`. Swift 6 strict concurrency (`complete`): no data race warnings, no `@unchecked`52  shortcuts; network calls off the main thread via the Core's async APIs. No polling faster than needed; stop polling when the view53  disappears (`.task` cancellation) and when `!AppActivity.isActive`. Prefer the Core's streams (SSE / QuoteStream websocket) for54  live market data where they exist.55- Charts: Swift Charts. Tables: SwiftUI `Table` for long lists (virtualized); never build a 500-row `VStack`.56- Development-only code is inside `#if SPW_DEV` (never compiled in Release).57- Your files live ONLY in your feature folder(s) under `Features/<Name>/`. Do not edit `App/`, `Components/`, `Core/`, other58  features, `project.yml`, `Scripts/`. If you need a change there, describe it in your report. Your entry view replaces the stub in59  `Features/_Pending.swift`: delete ONLY your own stub line(s) from that file, keep the exact entry signature60  (`struct XxxView: View { let model: AppModel … }`).6162## Build and check6364`Scripts/build.sh Debug <your-suffix>` (own DerivedData; prints errors only; exit code 0 = success). Other agents work in parallel in65other feature folders: an error in a folder that is not yours is not yours to fix — re-run a little later. Zero warnings in your files.66A local throwaway backend runs at http://localhost:8760 (random test keys, Base = local anvil fork with 1 fake ETH, every live67trading lock OFF, real public market data). The owner session is created by the dev app. To see real response shapes, read the68Core's models/fixtures (`../SPWalletCore/Tests/SPWalletCoreTests/Fixtures/`) and the backend source rather than guessing.69Do NOT start/stop the stack, do NOT launch the app (one shared instance), do NOT contact production (wallet.spboucher.ai), do NOT70run git commit/push, do NOT run `pkill`.7172## Report (what I need back)7374- files written; the feature's capabilities and, for EACH, its real status in the backend as you verified it by reading the code:75  operational in production / behind a server lock (which) / paper or testnet only / read-only / not available — with the file:line76  that proves it;77- every place where the Core lacks something or seems wrong (exact symbol and what you expected);78- what you verified by compiling vs. what remains unverified (nothing was run against a backend unless you say how).79
Files main
Menu

Theme