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