$ show unicity-sphere/sphere
Unicity Sphere is a self-custodial Web3 wallet and agent platform implemented as a React 19 single-page application. It provides wallet creation/restore (with mnemonic backup, password, and file import), direct messaging and group chat (via Nostr relays), a marketplace for agents and apps with reviews and quests, dApp connectivity through the Sphere Connect protocol (iframe agents and popup), and subscription-based quota management for aggregator API access. The architecture is a client-side SPA with a desktop-like shell (tabs, taskbar, wallet panel) using TanStack Query for server state, Framer Motion for animations, and Tailwind CSS for styling. Key entry points include the onboarding flow (CreateWalletFlow), the main wallet panel (WalletPanel), the Connect provider (ConnectProvider), and the desktop layout (DesktopLayout). External dependencies include the @unicitylabs/sphere-sdk for core wallet operations, a local @unicitylabs/sphere-ui package, REST APIs for marketplace and subscription gateway, and Sentry for error monitoring. The codebase has extensive unit and e2e test coverage with a strong focus on security invariants (duplicate send guards, settle shields, origin verification), though a security audit identified 131 findings including unencrypted seed storage and phishing risks. The project is actively maintained with frequent commits and issue triage, but exhibits tight coupling to the SDK and complex state machines that pose maintenance risks.
The LLM identified 4 files worth highlighting for reuse:
Implements in-place re-encryption of the stored mnemonic with a read-back verification step and automatic rollback on failure. This ensures that a password change does not corrupt the wallet seed even if the write or verification fails. The module is self-contained, uses only the SDK's crypto primitives, and can be extracted for any application requiring safe credential rotation.
Provides an imperative quota check function that inspects subscription gateway utilization to allow, warn, or block send operations. Designed to be independent of React Query to avoid stale cache issues, with fail-open behavior on network errors. The logic is pure and testable, making it reusable in any payment flow that needs proactive rate-limit enforcement.
A shared module that detects duplicate pending transfers by matching recipient address, amount, and token identifier. Used across send modals to prevent double-sends caused by rapid clicks or network retries. The guard is pure logic with no UI dependencies, making it extractable for any payment system that needs idempotency enforcement.
A re-entrancy guard for asynchronous initialization that ensures only one instance of a resource is created. Subsequent calls either adopt the existing instance or discard it if initialization failed. This pattern is useful for any singleton initialization (e.g., wallet, WebSocket, SDK) and is implemented with minimal dependencies.