Switchain Services

Appearance

Wallets Package ​

The @sws/wallets package is the core of Switchain's wallet management system. It handles all operations related to custodial wallets, deposit addresses, transactions, and balances.

Overview ​

This package implements a hexagonal architecture (Clean Architecture) with Domain-Driven Design (DDD) to manage:

  • Custodial wallets for multiple blockchains
  • Dynamic deposit addresses for users
  • Inbound and outbound transactions
  • Real-time balances
  • Automated sweep operations

Architecture ​

Core Entities ​

Wallet ​

Represents a custodial wallet that can hold multiple tokens across different blockchains.

WalletAddress ​

Specific addresses of a wallet to receive funds. Can be:

  • WalletNativeAddress: For native tokens (ETH, BTC, SOL, etc.)
  • WalletTokenAddress: For specific tokens (USDT, USDC, etc.)

Transaction ​

Represents a transaction in the system, with information about source, destination, amount, and status.

WalletToken ​

Represents the holding of a specific token in a wallet.

Main Controllers ​

The package exposes multiple controllers organized by functionality:

API Controllers (For external applications) ​

  • getWalletDepositAddress: Gets deposit addresses
  • getWallet: Retrieves wallet information
  • getWalletToken: Gets specific token information
  • retrieveWalletBalance: Queries balances
  • initiateWithdrawalTransaction: Initiates withdrawals

Worker Controllers (For background processing) ​

  • sendTransaction: Sends transactions
  • updateTransaction: Updates transaction status
  • updateWalletBalance: Updates balances
  • sweepWalletAddress: Executes sweep operations
  • detectWalletAddressDeposit: Detects deposits

Admin Controllers (For administration panel) ​

  • updateWalletSettings: Configures wallets
  • cancelTransaction: Cancels transactions
  • scanWallet: Scans complete wallets
  • utxoCPFPTransaction: Accelerates UTXO transactions

Supported Blockchains ​

The system supports multiple blockchains:

  • Bitcoin (UTXO)
  • Ethereum (EVM)
  • Solana
  • Tron
  • Cosmos/Atom

Each blockchain has its own adapters and specific logic in the infrastructure layer.

Main Flows ​

Fund Deposits ​

  1. User requests deposit address
  2. System generates specific address for the token
  3. User sends funds to the address
  4. Worker detects the deposit
  5. Funds are credited to the wallet

Fund Withdrawals ​

  1. User requests withdrawal
  2. System validates available funds
  3. Outbound transaction is created
  4. Worker processes and sends the transaction
  5. Balance is updated

Sweep Operations ​

  1. Worker detects funds in deposit addresses
  2. Consolidates funds to main wallets
  3. Optimizes fees and manages gas

Directory Structure ​

packages/wallets/
├── domain/                 # Pure business logic
│   ├── entities/          # Domain entities
│   ├── valueObjects/      # Value objects
│   ├── repositories/      # Repository interfaces
│   ├── services/          # Domain services
│   └── events/           # Domain events
├── application/           # Application services
│   ├── wallet/           # Wallet application services
│   ├── walletAddress/    # Address application services
│   ├── transaction/      # Transaction application services
│   ├── services/         # Complex application services
│   ├── utxo/            # UTXO-specific services
│   ├── tron/            # Tron-specific services
│   └── solana/          # Solana-specific services
└── infrastructure/       # Technical implementations
    ├── controllers/      # HTTP/API controllers
    ├── repositories/     # Repository implementations
    ├── adapters/         # Blockchain adapters
    └── factories/        # Dependency injection factories

Next Steps ​