overview - saltict/Demo-Docs GitHub Wiki

SubWallet Services SDK Overview

The SubWallet Services SDK is a comprehensive TypeScript library that provides seamless integration with SubWallet's backend services, enabling developers to build applications with blockchain functionality including price tracking, balance detection, token swapping, cross-chain transfers, and Cardano operations.

📖 Navigation

Table of Contents

What is SubWallet Services SDK?

The SubWallet Services SDK is a unified TypeScript library designed to abstract the complexity of blockchain interactions through a clean, type-safe API. Built with a singleton pattern for optimal resource management, the SDK provides:

  • Unified Interface: Single point of access to multiple blockchain services
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • Platform Agnostic: Works across browser extensions, mobile apps, and web applications
  • Error Handling: Robust error handling with detailed error types
  • Configuration Management: Flexible configuration system for different environments

Core Capabilities

💰 Balance Detection

Real-time balance detection across multiple blockchain networks with support for:

  • Native tokens and custom assets
  • Multi-chain balance aggregation
  • Automatic token discovery
  • Balance change notifications

📊 Price History & Analytics

Comprehensive price data services featuring:

  • Historical price charts with multiple timeframes
  • Real-time price updates
  • Market analytics and trends
  • Chart-ready data format

🔄 Swap Operations

Advanced token swapping capabilities including:

  • Best route finding across DEXs
  • Slippage protection mechanisms
  • Cross-chain swap support
  • Transaction simulation

🌉 Cross-Chain Transfers (XCM)

Polkadot ecosystem cross-chain functionality:

  • Parachain asset transfers
  • Cross-consensus messaging
  • Fee estimation
  • Transfer status tracking

🃏 Cardano Integration

Specialized Cardano blockchain operations:

  • Native token handling
  • Staking operations
  • Transaction building
  • Metadata management

Architecture Principles

The SDK follows several key architectural principles:

Singleton Pattern

const sdk = SubWalletServiceSDK.getInstance();
  • Single instance ensures consistent state
  • Optimal resource utilization
  • Simplified configuration management

Service-Oriented Architecture

Each blockchain service is encapsulated in its own API class:

  • BalanceDetectionApi - Balance and token detection
  • PriceHistoryApi - Price data and analytics
  • SwapApi - Token swapping operations
  • XcmApi - Cross-chain transfers
  • CardanoApi - Cardano-specific functions

Configuration-Driven Design

sdk.updateConfig({
  platform: 'webapp',
  baseUrl: 'https://custom-endpoint.com',
  chainListVersion: '0.2.108'
});

SDK Components

%%{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[SubWalletServiceSDK] --> B[BalanceDetectionApi]
    A --> C[PriceHistoryApi]
    A --> D[SwapApi]
    A --> E[XcmApi]
    A --> F[CardanoApi]
    
    B --> G[BaseApi]
    C --> G
    D --> G
    E --> G
    F --> G
    
    G --> H[HTTP Client]
    G --> I[Error Handling]
    G --> J[Response Processing]
    
    A --> K[Configuration Manager]
    K --> L[Headers Management]
    K --> M[Platform Detection]
    K --> N[Version Control]

Core Components

  1. SubWalletServiceSDK - Main SDK class implementing singleton pattern
  2. BaseApi - Abstract base class for all service APIs
  3. Service APIs - Specialized APIs for different blockchain operations
  4. Configuration System - Centralized configuration management
  5. Error Handling - Comprehensive error types and handling

Platform Support

The SDK is designed to work across multiple platforms:

Browser Extensions

  • Optimized for Chrome/Firefox extensions
  • Manifest v3 compatibility
  • Background script support

Mobile Applications

  • React Native compatibility
  • iOS and Android support
  • Offline capability considerations

Web Applications

  • Modern browser support (ES2020+)
  • Server-side rendering compatibility
  • Progressive Web App support

Node.js Applications

  • Backend service integration
  • API server development
  • Batch processing operations

Use Cases

DeFi Applications

// Portfolio tracking
const balances = await sdk.balanceDetectionApi.getBalances({
  addresses: userAddresses,
  chains: ['polkadot', 'kusama']
});

// Price monitoring
const priceData = await sdk.priceHistoryApi.getPriceHistory('DOT', '1W');

Wallet Applications

// Cross-chain transfers
const xcmTransfer = await sdk.xcmApi.buildTransfer({
  from: 'polkadot',
  to: 'acala',
  token: 'DOT',
  amount: '10'
});

Trading Platforms

// Swap operations
const swapQuote = await sdk.swapApi.getQuote({
  tokenIn: 'DOT',
  tokenOut: 'USDT',
  amountIn: '100'
});

Analytics Dashboards

// Historical data analysis
const marketData = await sdk.priceHistoryApi.getPriceHistory('KSM', 'YTD');

Integration Benefits

Developer Experience

  • Type Safety: Full TypeScript support reduces runtime errors
  • IDE Support: IntelliSense and auto-completion
  • Documentation: Comprehensive inline documentation
  • Testing: Built-in testing utilities and mocks

Performance

  • Caching: Intelligent response caching
  • Rate Limiting: Built-in rate limit handling
  • Connection Pooling: Optimized HTTP connections
  • Error Recovery: Automatic retry mechanisms

Reliability

  • Error Handling: Comprehensive error types and recovery
  • Validation: Input validation and sanitization
  • Monitoring: Built-in logging and metrics
  • Testing: Extensive test coverage

Scalability

  • Configuration: Environment-specific settings
  • Extensibility: Plugin architecture for custom services
  • Versioning: Backward compatibility guarantees
  • Updates: Seamless SDK updates

🔗 Related Documentation