$ show unicity-sphere/sphere-sdk-connect-example
A comprehensive set of four self-contained example applications demonstrating the Sphere Connect protocol for integrating dApps with the Sphere wallet. The examples cover a browser dApp (React/Vite), a Node.js CLI dApp over WebSocket, an autonomous bot that runs its own wallet (direct SDK, no Connect), and a backend-auth flow where a frontend brokers a wallet signature and a backend verifies it cryptographically to issue a JWT. The codebase is a multi-package monorepo, each package pinned to the same SDK version (0.14.2), with extensive test coverage, CI/CD, and detailed documentation. The overall architecture is clean and well-structured, exhibiting high engineering craftsmanship in areas like money-safety (duck-typed detection of possibly-committed sends), exact string-based unit conversion, and byte-exact challenge reconstruction for signature verification.
The LLM identified 6 files worth highlighting for reuse:
Critical money-safety decision for sending tokens. Wraps the SDK's isPossiblyCommittedSendOutcome which uses instanceof SphereError (fragile across bundle copies) with a duck-typed fallback on the same error codes. This prevents double-pay scenarios by correctly classifying possibly-committed outcomes. The pattern is reusable for any bot or app that sends tokens and must avoid retrying a send whose outcome is uncertain.
Exact, string-based conversion between human-readable decimal amounts and integer base units for token amounts. Uses no Number/parseFloat, avoiding precision loss for high-decimal tokens. Includes toBaseUnits and fromBaseUnits with thorough validation and error handling. The resolveCoin function resolves symbols or coin IDs via the SDK's TokenRegistry. Clean, well-tested, and immediately reusable in any token-handling application.
Byte-exact challenge construction and reconstruction for wallet signature verification. The central safety property: the string the backend feeds into recoverPubkeyFromSignature on /verify must be byte-identical to the string the wallet signed on /challenge. Both directions funnel through the same formatChallenge function, preventing silent identity recovery drift. The function is pure, deterministic, and injects now/nonce externally for testability. Reusable for any 'sign-in with wallet' backend.
Robust error classification for Connect protocol requests. Discriminates on numeric error code (duck-typed, not instanceof) to handle WALLET_LOCKED (4009) correctly as a session-preserving lock, not a teardown. Separates INTENT_OUTCOME_UNKNOWN (4201) as a distinct kind to prevent automatic retry of possibly-committed intents. Falls back to message text only for codeless SDK failures. The describeConnectFailure function reads data.requiredSdk/actualSdk from handshake refusals to tell the developer which version is needed. Reusable for any Connect-based dApp.
Three-tier resolver for the aggregator API key: explicit env override → previously saved key on disk → auto-provision a fresh key from the SGW via challenge/sign/verify. Persists provisioned keys for reuse across restarts. The fallback chain is clean, well-tested, and handles corrupt/missing files gracefully. Reusable for any autonomous agent that needs an API key for transaction submission.
Headless in-process loopback test of the Connect 2.1 lock feature using real ConnectHost and ConnectClient. Creates an in-memory transport (no ports, no timers, no flakes) to assert WALLET_LOCKED (4009) responses, the locked allow-list, unlock semantics, and identity-change revocation. Tests the full lifecycle: setLocked, updateSphere, revokeSession, resume-while-locked. The loopback pattern is reusable for testing any Connect protocol interaction without network dependencies.