components - saltict/Demo-Docs GitHub Wiki

Component Architecture

Detailed breakdown of the SubWallet Services SDK components, their relationships, and internal structure.

📖 Navigation

Table of Contents

Component Overview

The SDK is composed of several key components that work together to provide a unified blockchain services interface:

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
graph TB
    subgraph "SDK Core"
        A[SubWalletServiceSDK]
        B[Configuration Manager]
        C[Service Registry]
    end
    
    subgraph "Base Infrastructure"
        D[BaseApi]
        E[HTTP Client]
        F[Error Handler]
        G[Type System]
    end
    
    subgraph "Service Layer"
        H[BalanceDetectionApi]
        I[PriceHistoryApi]
        J[SwapApi]
        K[XcmApi]
        L[CardanoApi]
    end
    
    subgraph "Support Components"
        M[Constants]
        N[Validators]
        O[Formatters]
        P[Cache Manager]
    end
    
    A --> B
    A --> C
    C --> H
    C --> I
    C --> J
    C --> K
    C --> L
    
    H --> D
    I --> D
    J --> D
    K --> D
    L --> D
    
    D --> E
    D --> F
    D --> G
    
    B --> M
    E --> N
    E --> O
    E --> P
Loading

Core Components

SubWalletServiceSDK

Primary Responsibilities:

  • Singleton instance management
  • Service orchestration
  • Configuration coordination
  • Public API surface

Key Features:

export class SubWalletServiceSDK {
  // Service instances
  public balanceDetectionApi: BalanceDetectionApi;
  public cardanoApi: CardanoApi;
  public priceHistoryApi: PriceHistoryApi;
  public swapApi: SwapApi;
  public xcmApi: XcmApi;
  
  // Configuration management
  private config: SDKConfig;
  
  // Singleton pattern
  private static instance: SubWalletServiceSDK | null = null;
  static getInstance(): SubWalletServiceSDK;
  
  // Dynamic configuration
  updateConfig(newConfig: Partial<SDKOption>): void;
}

Configuration Manager

Primary Responsibilities:

  • Centralized configuration storage
  • Dynamic configuration updates
  • Header generation
  • Platform-specific settings

Configuration Structure:

interface SDKConfig {
  baseUrl: string;
  platform: 'extension' | 'mobile' | 'webapp';
  sdkVersion: string;
  chainListVersion: string;
}

interface ApiConfig {
  baseUrl: string;
  headers?: Record<string, string>;
}

BaseApi

Primary Responsibilities:

  • HTTP request/response handling
  • Error management
  • Configuration injection
  • Common API patterns

Key Methods:

export class BaseApi {
  // Core HTTP methods
  async request<T>(options: RequestOptions): Promise<T>;
  async get<T>(options: GetOptions): Promise<T>;
  async post<T>(options: PostOptions): Promise<T>;
  
  // Configuration management
  updateConfig(newConfig: Partial<ApiConfig>): void;
  
  constructor(protected config: ApiConfig);
}

Service Components

BalanceDetectionApi

Purpose: Real-time balance detection and token discovery across multiple chains.

Component Structure:

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
graph LR
    A[BalanceDetectionApi] --> B[Balance Queries]
    A --> C[Token Discovery]
    A --> D[Multi-chain Support]
    
    B --> E[Native Tokens]
    B --> F[Custom Assets]
    
    C --> G[Automatic Detection]
    C --> H[Manual Addition]
    
    D --> I[Polkadot]
    D --> J[Kusama]
    D --> K[Parachains]
Loading

PriceHistoryApi

Purpose: Historical and real-time price data with multiple timeframe support.

Features:

  • Multiple timeframes (1D, 1W, 1M, 3M, YTD, 1Y, ALL)
  • Chart-ready data format
  • Price change calculations
export class PriceHistoryApi extends BaseApi {
  async getPriceHistory(token: string, type: Timeframe): Promise<HistoryTokenPriceJSON> {
    return this.get<HistoryTokenPriceJSON>({
      params: { token, type },
      path: 'price-history'
    });
  }
}

SwapApi

Purpose: Token swapping operations with route optimization and error handling.

Component Features:

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
graph TB
    A[SwapApi] --> B[Quote Generation]
    A --> C[Route Optimization]
    A --> D[Transaction Building]
    A --> E[Error Handling]
    
    B --> F[Best Price Finding]
    B --> G[Slippage Calculation]
    
    C --> H[DEX Routing]
    C --> I[Fee Optimization]
    
    D --> J[Transaction Params]
    D --> K[Gas Estimation]
    
    E --> L[SwapError Types]
    E --> M[Recovery Strategies]
Loading

XcmApi

Purpose: Cross-chain message passing and asset transfers within the Polkadot ecosystem.

Capabilities:

  • Parachain-to-parachain transfers
  • Relay chain interactions
  • Fee estimation
  • Transfer status tracking

CardanoApi

Purpose: Cardano-specific blockchain operations and native token handling.

Features:

  • Native ADA operations
  • Custom token support
  • Staking functionality
  • Metadata handling

Support Components

Constants Module

Purpose: Centralized configuration constants and default values.

export const SDK_VERSION = pkgJson.version;
export const DEFAULT_BASE_URL = 'https://sw-services.subwallet.app';
export const DEFAULT_CHAIN_LIST_VERSION = '0.2.108';
export const DEFAULT_PLATFORM = 'extension';

Error System

Purpose: Comprehensive error handling with specific error types.

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
graph TD
    A[SdkError] --> B[NetworkError]
    A --> C[ValidationError]
    A --> D[APIError]
    A --> E[ConfigurationError]
    
    F[SwapError] --> A
    G[XcmError] --> A
    H[CardanoError] --> A
    
    B --> I[Connection Timeout]
    B --> J[DNS Resolution]
    
    C --> K[Parameter Validation]
    C --> L[Type Validation]
    
    D --> M[HTTP Status Errors]
    D --> N[API Response Errors]
Loading

Type System

Purpose: Comprehensive TypeScript type definitions for type safety.

Key Interfaces:

// API Response standardization
interface SWApiResponse<T> {
  status: 'error' | 'success' | 'fail';
  data: T;
  result: T;
  error?: {
    message: string;
    code: number;
  };
  message?: string;
}

// Request configuration
interface RequestOptions {
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  path: string;
  params?: Record<string, any>;
  data?: any;
  headers?: Record<string, string>;
}

Component Relationships

Dependency Flow

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
graph LR
    A[Constants] --> B[SDK Config]
    B --> C[Service APIs]
    C --> D[BaseApi]
    D --> E[HTTP Client]
    
    F[Type Definitions] --> C
    G[Error Classes] --> D
    H[Validators] --> D
Loading

Communication Patterns

  1. Configuration Cascade: Configuration flows from SDK → Services → BaseApi
  2. Error Bubbling: Errors bubble up from HTTP → BaseApi → Services → SDK
  3. Service Registration: Services register with SDK for lifecycle management
  4. Type Propagation: Types flow through all layers for compile-time safety

Lifecycle Management

Initialization Sequence

  1. SDK Instantiation: Singleton instance created
  2. Configuration Setup: Default configuration applied
  3. Service Creation: All service APIs instantiated
  4. Service Registration: Services added to service list
  5. Ready State: SDK ready for use

Configuration Updates

  1. Update Request: Client calls updateConfig()
  2. Configuration Merge: New config merged with existing
  3. Service Notification: All services receive updated config
  4. Header Regeneration: New headers generated if needed
  5. Ready State: SDK ready with new configuration

Service Lifecycle

%%{init: {'theme':'dark', 'themeVariables': { 
  'primaryColor': '#ff6b6b', 
  'primaryTextColor': '#fff', 
  'primaryBorderColor': '#ff6b6b', 
  'lineColor': '#ffa726', 
  'sectionBkColor': '#2d3748', 
  'altSectionBkColor': '#1a202c', 
  'gridColor': '#4a5568', 
  'secondaryColor': '#4a5568', 
  'tertiaryColor': '#2d3748'
}}}%%
stateDiagram-v2
    [*] --> Created
    Created --> Configured
    Configured --> Ready
    Ready --> Processing
    Processing --> Ready
    Ready --> Reconfigured
    Reconfigured --> Ready
    Ready --> [*]
Loading

🔗 Related Documentation

⚠️ **GitHub.com Fallback** ⚠️