How cypherock/cypherock-cysync works
1. This is a pnpm monorepo for Cypherock’s “cySync” product, centered on a desktop wallet app plus a CLI, with most domain logic split into shared packages. The repo is organized so UI shells are thin and most wallet/coin behavior lives in reusable packages.
2. The desktop application is an Electron app in apps/desktop, split into a main process and a renderer. The main process owns app lifecycle, IPC handlers, auto-update, device/system integrations, logging, and database access. The renderer is a Vite/React entry that hosts the product UI.
3. packages/cysync-core is the main product layer for the desktop UI. It contains pages, dialogs, components, hooks, store slices, and feature-specific services. In architecture terms, it sits between the renderer and the lower-level service packages, orchestrating screens, background tasks, and app state.
4. The desktop data flow is typically: React page/dialog in cysync-core -> hook/store/service -> package-level service or IPC call -> database/device/network operation -> state update back to the UI. This is where onboarding, wallet actions, send/receive, inheritance, swap, buy/sell, notifications, and wallet-connect flows are coordinated.
5. packages/database is the concrete persistence implementation. It defines entities for accounts, wallets, transactions, price history/info, devices, inheritance plans, notifications, and migrations, plus an encrypted database layer. packages/db-interfaces mirrors the database shapes and errors so higher layers can depend on stable contracts without importing the implementation directly.
6. Coin-specific behavior is isolated into many packages/coin-support-* packages. Each package exposes a common set of operations such as create account, receive, initialize/prepare/sign/broadcast transaction, validate address, sync account, and price sync. They differ by chain requirements and external API usage: for example Bitcoin uses Blockbook, EVM uses web3/ethers and transaction helpers, ICP uses Dfinity utilities, Solana uses SPL/token helpers, Tron uses TronWeb, Starknet has deploy-account flows, and Canton has extra transaction variants.
7. The coin support packages form the blockchain integration boundary. They translate generic wallet actions into chain-specific derivation, formatting, fee calculation, history fetching, signing, and broadcasting logic, and they reach out to chain APIs or explorers as needed. This is the main place where external blockchain infrastructure enters the system.
8. packages/coins is the static asset and metadata catalog for supported assets. It aggregates coin/token definitions per chain, including special token lists and JSON metadata, and is used by support packages and UI logic to identify assets consistently.
9. packages/coin-support-utils and packages/coin-support-interfaces provide shared building blocks for the chain packages. The former contains common DB/account/receive/sign/sync helpers and CoinGecko integration; the latter defines shared operation interfaces such as create account, receive, send, sign, explorer link, and sync operations. These packages are the abstraction layer that keeps all chain modules aligned.
10. packages/cysync-core also has substantial background processing. Its bgTask area handles recurring syncs for accounts, wallets, prices, notifications, network status, device handling, DB listening, and version checks. There is also a graph worker hook, which indicates some heavy UI computation is offloaded from the main thread.
11. The CLI app in apps/cli is a command-driven interface for wallet/device/account operations. It has command modules and matching service modules for account/device/wallet/transaction/send/receive/sign/reset flows, plus shared utilities for prompts, spinners, DB access, and device communication. Architecturally it reuses the same domain concepts as the desktop app, but without the Electron shell.
12. packages/ui is the shared design system and component library. It contains the low-level atoms/molecules, theming, layouts, icons, storybook, and common UI helpers used by the desktop/core product screens. packages/desktop-ui provides the renderer bootstrap and routing layer for the desktop app.
13. packages/interfaces, packages/core-services, and packages/coins are cross-cutting support libraries. core-services focuses on higher-level wallet/account/portfolio/transaction logic built over the database, while interfaces contains shared app-level types such as electron APIs and feature flags. cysync-core-constants centralizes error models, routes, locales, and core constants used across the UI and services.
14. The build and release system reinforces the modular architecture. The repo uses Turborepo, PNPM workspaces, changesets, GitHub Actions, and many package-level test configs. There is also a submodules/sdk dependency for hardware-wallet communication, which is intentionally externalized and built separately when modified.
15. Overall, the diagram should show two top-level clients — desktop and CLI — both depending on shared domain packages, coin support modules, database/interfaces, utilities, and the hardware SDK submodule. The desktop path additionally includes Electron main-process IPC and a React renderer/UI layer, while the CLI path is command/service driven and much thinner.
Main entry points: src/index.ts Chain packages · src/index.ts cysync-core · main/index.ts Main process · src/index.ts Core services
Components 27
Desktop app
Electron wallet shell with main-process services and React renderer.
- Main process · Owns lifecycle, IPC, updates, device/system integration, logging, and database access.
apps/desktop/src/main/index.ts - Renderer · Vite/React entry that bootstraps the product UI.
apps/desktop/renderer/index.tsx - IPC layer · Handlers that bridge renderer requests to app, device, DB, logs, reset, wallet-connect, and updater flows.
apps/desktop/src/main/ipc/index.ts - Preload · Exposes a controlled renderer-to-main API surface.
apps/desktop/src/preload/index.ts
CLI app
Command-driven wallet interface built on shared domain services.
- CLI app · Command-driven wallet and device interface with thin orchestration over shared services.
apps/cli/src/index.ts - Commands · Account, device, onboarding, portfolio, receive, reset, send, sign, transaction, and wallet commands.
apps/cli/src/commands/onboarding/index.ts - CLI services · Service modules that implement account, device, wallet, send/receive, sign, transaction, portfolio, and reset flows.
apps/cli/src/services/index.ts
Shared packages
Reusable domain, blockchain, persistence, and UI libraries.
- cysync-core · Desktop product layer coordinating pages, dialogs, hooks, store, and feature services.
packages/cysync-core/src/index.ts - Background tasks · Recurring account, wallet, price, notification, device, network, DB, and version jobs.
packages/cysync-core/src/bgTask/index.tsx - Core UI · Pages, dialogs, and components for onboarding, wallet actions, inheritance, swap, buy/sell, and wallet-connect.
packages/cysync-core/src/pages/index.ts - Store · Central application state slices for wallet, account, device, dialog, notification, network, and transaction data.
packages/cysync-core/src/store/store.ts - Core services · Higher-level wallet, portfolio, transaction, swap, buy/sell, and inheritance services built over persistence.
packages/core-services/src/index.ts - Coin utils · Common create-account, receive, sign, sync, DB, and CoinGecko helpers used by chain packages.
packages/coin-support-utils/src/index.ts - Coin interfaces · Shared chain operation interfaces and explorer/address/sign/sync contracts.
packages/coin-support-interfaces/src/index.ts - Coins catalog · Static coin/token definitions and chain-specific metadata used for consistent asset identification.
packages/coins/src/index.ts - Database · Concrete encrypted database, entities, repositories, migrations, and key-value storage implementation.
packages/database/src/index.ts - DB contracts · Interface layer mirroring entity shapes and database errors for higher-level consumers.
packages/db-interfaces/src/index.ts - Chain packages · Coin-specific operation modules that adapt generic wallet actions to each chain and its APIs.
packages/coin-support-btc/src/index.ts - BTC support · Bitcoin integration with Blockbook, fee helpers, UTXO history, signing, broadcasting, and sync.
packages/coin-support-btc/src/index.ts - EVM support · Ethereum-compatible integration with web3/ethers helpers, address formatting, transaction helpers, and sync.
packages/coin-support-evm/src/index.ts - ICP support · Internet Computer integration with Dfinity utilities, address derivation, and transaction flows.
packages/coin-support-icp/src/index.ts - Solana support · Solana and SPL token integration with web3, SPL helpers, and transaction helpers.
packages/coin-support-solana/src/index.ts - Tron support · Tron integration with TronWeb, trigger-constant-contract support, and transaction helpers.
packages/coin-support-tron/src/index.ts - Starknet support · Starknet integration with deploy-account flows and chain-specific transaction preparation/signing.
packages/coin-support-starknet/src/index.ts - Canton support · Canton integration with extra broadcast variants and transaction preparation paths.
packages/coin-support-canton/src/index.ts
Tooling
Repo-wide build, release, and workspace infrastructure.
- Hardware SDK · External SDK submodule for hardware-wallet communication, built separately when changed.
submodules/sdk - Workspace tooling · Turborepo, pnpm workspace, changesets, CI workflows, and release/build scripts.
turbo.json
Connections 21
- Renderer → cysync-core: hosts UI · Renderer mounts the product layer and its screens.
- Preload → IPC layer: bridges · Preload exposes a safe API surface to the renderer.
- IPC layer → Main process: routes to main · IPC handlers execute lifecycle, update, DB, device, and system work in the main process.
- Main process → Database: persists · Desktop main process reads and writes encrypted app data.
- Main process → Hardware SDK: uses SDK · Main process integrates with the hardware-wallet communication submodule.
- cysync-core → Background tasks: schedules tasks · Core UI coordinates recurring background jobs and listeners.
- cysync-core → Store: updates state · Hooks, dialogs, and services drive application state transitions.
- cysync-core → Core services: orchestrates flows · Product actions delegate wallet, portfolio, swap, and inheritance work.
- Background tasks → Core services: runs sync · Background tasks invoke higher-level sync and maintenance services.
- Core services → Database: reads/writes · Service logic persists and queries wallet and portfolio data.
- Core services → Chain packages: delegates chain ops · Higher-level services use chain modules for blockchain-specific work.
- Chain packages → Coin utils: shares helpers · Chain packages reuse common account, receive, sign, sync, and price helpers.
- Chain packages → Coin interfaces: implements contracts · Each chain module conforms to common operation interfaces.
- Chain packages → Coins catalog: resolves assets · Chain logic uses the metadata catalog to identify coins and tokens.
- Chain packages → DB contracts: targets contracts · Chain support modules depend on stable DB shapes and error contracts.
- CLI app → Commands: dispatches · CLI entrypoint maps commands to feature modules.
- Commands → CLI services: invokes · Commands call service modules for the actual wallet operations.
- CLI services → Chain packages: reuses chain ops · CLI service flows reuse the same blockchain integration boundary.
- CLI services → Database: persists · CLI flows use the shared database for account and wallet state.
- Workspace tooling → Main process: builds · Repo tooling drives packaging, test, and release pipelines for the desktop app.
- Workspace tooling → CLI app: builds · Repo tooling also packages and tests the CLI application.