SPB Git

Repository Public

CONVENTIONS.md 3.3 KB

# 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

  1. No private key, no seed, no signing of transactions here. The apps display, prepare and authorize; the isolated signer signs.
  2. 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 a VerifiedApproval<…>. If an object cannot be recomputed, the function must not exist — document it as unavailable instead.
  3. 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.inconsistent on any difference.
  4. Amounts are strings (base units + the server's exact …Display text). BaseUnits for arithmetic. Double only for prices, percentages, chart points and fiat estimates.
  5. 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 a String, and is shown verbatim.
  6. Models decode leniently on optional/absent fields (the server evolves additively) but never coerce: a missing balance is nil, not 0.
  7. Every state-changing call that the server protects with Idempotency-Key takes the key from the caller (so a retry reuses it).
  8. Swift 6 language mode, complete concurrency checking, zero third-party dependency, every public type Sendable.
  9. 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.

Files main
Menu

Theme