Repository Public
1# SPWalletCore — conventions23Shared Swift package of the native SP Wallet clients (iOS/iPadOS: `../SPWallet-iOS`, macOS: `../SPWallet`). Owner of this package:4the iOS session. Backend of reference: `~/Desktop/Cluster/projets/sp-wallet` (branch `v11` = production `52e513b`), READ-ONLY from here.56## Hard rules781. **No private key, no seed, no signing of transactions here.** The apps display, prepare and authorize; the isolated signer signs.92. **Passkey approvals go through `ApprovalBinding.verify`** (Signing/Approval.swift). For every object the backend has approved by a10 passkey, port its canonical serialization byte for byte (`PasskeyApprovable.canonicalBytes`), parse the served object STRICTLY11 (`StrictObject`: an unknown key is a refusal), and expose approve functions that only accept a `VerifiedApproval<…>`. If an12 object cannot be recomputed, the function must not exist — document it as unavailable instead.133. **Check what is approved against what was asked**: after a prepare call, compare the returned canonical object with the request14 (network, asset, amount, destination, minimum output, leverage, limits…) and throw `ApprovalError.inconsistent` on any difference.154. **Amounts are strings** (base units + the server's exact `…Display` text). `BaseUnits` for arithmetic. `Double` only for prices,16 percentages, chart points and fiat estimates.175. **Never invent data**: no default that looks like a real value, no placeholder balance, no success state inferred by the client.18 A state unknown to this code decodes to `.unknown`-style cases or stays a `String`, and is shown verbatim.196. Models decode leniently on optional/absent fields (the server evolves additively) but never coerce: a missing balance is `nil`, not 0.207. Every state-changing call that the server protects with `Idempotency-Key` takes the key from the caller (so a retry reuses it).218. Swift 6 language mode, complete concurrency checking, zero third-party dependency, every public type `Sendable`.229. Every file starts with the header (project, File, Description, Author: Simon-Pierre Boucher, Contact: contact@spboucher.ai).23 Code and comments in English.2425## Layout2627`Foundation/` JSON, exact amounts, encodings · `Crypto/` hashes and address codecs · `API/` client, errors, session token ·28`Auth/` WebAuthn JSON, login, passkey enrolment · `Signing/` approval binding, intent, transfers · `Wallet/` base models and reads ·29`Blockchain/` address validation, payment URIs · `Persistence/` offline snapshots · `Domains/<Name>/` one folder per backend domain30(models `…Models.swift`, endpoints `…API.swift` as a `public struct XxxAPI: Sendable { let client: APIClient; public init(_:) }`,31canonical objects `…Canonical.swift`).3233## Tests3435Swift Testing (`import Testing`). Per domain: `Tests/SPWalletCoreTests/<Name>Tests.swift`; JSON fixtures in `Tests/.../Fixtures/<name>-*.json`36(shape copied from the TS `view` functions / vitest expectations — say in the fixture's test where it comes from); canonical vectors in37`Tests/.../Vectors/<name>-*.json` as `[{name, domain, source, object, canonicalHex, hashHex}]`, GENERATED by running the backend's own38TypeScript (`cd ~/Desktop/Cluster/projets/sp-wallet && npx tsx /tmp/<script>.mts`), never typed by hand.39A scripted `HTTPTransport` (Tests/.../Support/MockTransport.swift) checks method, path, query, headers and body of each endpoint.40