sphere-sdk: Instructions file for Claude Code

CLAUDE.md - Sphere SDK Project Context

This file provides context for Claude Code when working with the Sphere SDK project.

⚡ wallet-api program — current work (read first)

This repo is part of the wallet-api program (process: ../wallet-api/docs/development-workflow.md).

• Branch topology (updated 2026-07-31): all work branches from and PRs back to main — the feat/wallet-api-integration era ended when the integration branches merged (releases ship from main; wallet-api#119 records this in the process doc). Every PR links a GitHub issue (Closes #N, docs-only changes exempt); squash-merge after green CI (.github/workflows/ci.yml: verify:version + typecheck + typecheck:tests + lint + build + test:run on Node 22 and 24, plus test:mutation, sharded across 8 parallel jobs by MUTATION_SHARD=i/n and summed up in one test-mutation check).
• The normative spec for the program's SDK work is ../wallet-api/docs/sdk-changes.md — Part E (recoverable engine), then S1–S7 (thin wallet, ports, wallet-api providers). It was adversarially verified; build it, don't redesign it. Spec-first: contract changes land in the spec in the same PR, before code. The payments vertical (P11 flip landed) is the ONLY money path — design record + build history: docs/PAYMENTS-V2-DESIGN.md (read it for the why before touching modules/payments-v2/ or impl/wallet-api-v2/; the code and docs/API.md are normative for the current API). Migration guide for consumers: docs/MIGRATION-PAYMENTS-V2.md.
• Resume is status-agnostic (sdk-changes E.2): never key engine resume off a submit status — submit, always getInclusionProof, match-verify (OK = mine, TRANSACTION_HASH_MISMATCH = TransferConflictError). That stays the ONLY conflict signal under 3.x: a null inclusionProof means "not certified YET", and the time-dependent statuses the bump added — REQUEST_EXPIRED and REFERENCE_TIME_AFTER_ROUND on verify, REQUEST_EXPIRED and SERVICE_NOT_READY on submit — each report only that THIS attempt was not admitted, never that no earlier attempt certified, so none of them is a clean reject. The STATE_ID_EXISTS aggregator lag is OVER (M7 live e2e observed 2026-06-12: the gateway answers SUCCESS for duplicate AND conflicting submits — the status carries no conflict signal; see the dated OBSERVED note in ../wallet-api/docs/sdk-changes.md E.2); tolerant parsing shipped via state-transition-sdk-js#125 and stays.
• Sphere sets no request deadline, ANYWHERE (#760): every mint / transfer / split burn / split mint leg omits expiresAt, so the Unicity Service assigns one from consensus time and does not record it. The reason is not determinism — a deadline persisted on the durable intent would rebuild byte-identically — it is (a) an untrusted browser clock, where one skewed wallet pinning a past deadline is a wallet-wide payment outage, and (b) unrecoverability across downtime longer than the window: every resume would rebuild an already-expired transaction and the intent would sit open forever with its sources reserved, and there is currently NO attempt budget on the certify/resume path at all. What makes the policy load-bearing rather than cosmetic: expiresAt is committed by the transaction HASH but is NOT part of the StateId, so two attempts that disagree about it address the SAME leaf with DIFFERENT hashes — and InclusionProofVerificationRule compares the hash BEFORE the certification data, so the disagreement surfaces as TRANSACTION_HASH_MISMATCH, i.e. as a foreign spend, which token-engine/certification-outcome.ts maps to TransferConflictError (abort + re-plan). A clock-derived deadline would therefore make every crash-resume abort an intent whose spend is already on chain. Pinned by tests/unit/token-engine/expires-at.test.ts, including a 24-hour clock jump between two attempts.
• Ports rule (design §10 / covenant): the money ports are StoragePort and DeliveryPort (modules/payments-v2/ports.ts) — independent, swappable, contract-test-enforced (tests/unit/payments-v2/contracts/); the Sphere frontend is a view — no provider-specific logic outside implementations; custody (intoInventory) is a composition-time property, never a per-call flag.
• Never weaken a test to make it pass; no .skip/.only. (#487, the old pre-existing-failure tracker, is closed: it covered tests of modules that have since been deleted.)
• Releases: npm versions publish via publish.yml (workflow_dispatch, version input) — the workflow runs npm version itself, so package.json on a branch still reads the PREVIOUS version; never hand-edit the field. Publishing from main takes dist-tag latest, any other branch takes dev (line <next version>-dev.#). Consumers (wallet-api backend, sphere frontend) pin exact versions. The backend consumes ONLY the ./token-engine subpath (must stay browser/Nostr-free — keep token-engine/ clean).
• The 3.x bump was a fleet-wide flag day (#760, shipped in 0.15.0). The forcing function is aggregator-go, whose main already carries CertificationDataVersion = 2 with a hard reject of version 1 — nothing can straddle the gateway cutover. wallet-api must bump in LOCKSTEP: both repos pin @unicitylabs/state-transition-sdk EXACTLY, so bumping sphere-sdk alone makes npm dedupe impossible and runs both wire realms live; they cross at ../wallet-api/src/validation/verifier.ts. A testnet + wallet-api backend reset accompanied that release.
• Pinned base SDK: @unicitylabs/[email protected] (exact pin; bump only via PR). What 3.x is: every transaction now carries expiresAt — an exclusive request deadline in Unix seconds — and every inclusion proof carries the referenceTime of the round that certified it; the sparse-Merkle leaf value became H(transactionHash, referenceTime) instead of the bare transaction hash. The Token / MintTransaction / TransferTransaction / CertificationData wire versions all moved with it: nothing written by 2.x decodes, and nothing 2.x writes is accepted by the upgraded aggregator — in either direction, no exceptions. The lost-abort hang in waitInclusionProof that 2.0.3 fixed (state-transition-sdk-js#140/#141) is still fixed in 3.0.1: its poll loop checks aborted before subscribing, races each poll against the signal, and cancels the in-flight request. tests/unit/token-engine/proof-deadline.test.ts is the guard that it keeps doing so — do not delete it on a future bump.