Switchain Services

Appearance

Admin Operations ​

This document describes the wallet operations available through the admin panel, their purposes, and how they integrate with the wallets package.

Overview ​

The admin panel provides a set of operations for managing wallets, addresses, and transactions. These operations are exposed through tRPC procedures in the admin router and call the corresponding controllers from the wallets package.

Available Operations ​

Wallet Management ​

getWallet ​

Purpose: Retrieves detailed information about a specific wallet.

Input:

typescript
{ id: string } // Wallet ID

Controller: WalletsControllers.getWallet

Use Case: View wallet details, balances, and settings.

updateWalletBalance ​

Purpose: Manually triggers a balance update for a wallet.

Input:

typescript
{ id: string } // Wallet ID

Controller: WalletsControllers.updateWalletBalance

Use Case: Force refresh wallet balance from blockchain when automatic updates fail.

scanWallet ​

Purpose: Performs a comprehensive scan of the entire wallet.

Input:

typescript
{ id: string } // Wallet ID

Controller: WalletsControllers.scanWallet

Use Case: Deep scan to find missing transactions or balance discrepancies.

updateWalletSettings ​

Purpose: Updates wallet configuration settings.

Input:

typescript
{
  id: string,
  settings: {
    depositsEnabled?: boolean,
    withdrawalsEnabled?: boolean
  }
}

Controller: WalletsControllers.updateWalletSettings

Use Case: Enable/disable deposits or withdrawals for maintenance or security.

Address Management ​

updateWalletAddress ​

Purpose: Updates balance for a specific wallet address.

Input:

typescript
{ id: string } // Address ID

Controller: WalletsControllers.updateWalletAddressBalance

Use Case: Refresh balance for a specific address when discrepancies are detected.

sweepWalletAddress ​

Purpose: Manually triggers a sweep operation for an address.

Input:

typescript
{ id: string } // Address ID

Controller: WalletsControllers.triggerSweepWalletAddress

Use Case: Force consolidation of funds from deposit addresses to main wallet.

unlockWalletAddress ​

Purpose: Unlocks a deposit address for reuse.

Input:

typescript
{
  coinId: string,
  blockchainId: string,
  address: string
}

Controller: WalletsControllers.unlockDepositAddress

Use Case: Make stuck or locked addresses available for new deposits.

Transaction Management ​

sendTransaction ​

Purpose: Manually sends a pending transaction.

Input:

typescript
{ id: string } // Transaction ID

Controller: WalletsControllers.sendTransaction

Use Case: Retry failed transactions or manually process stuck transactions.

updateTransaction ​

Purpose: Updates transaction status from blockchain.

Input:

typescript
{ id: string } // Transaction ID

Controller: WalletsControllers.updateTransaction

Use Case: Refresh transaction status when automatic updates fail.

cancelTransaction ​

Purpose: Cancels a pending transaction.

Input:

typescript
{ id: string } // Transaction ID

Controller: WalletsControllers.cancelTransaction

Use Case: Cancel transactions that are stuck or no longer needed.

utxoCPFPTransaction ​

Purpose: Accelerates UTXO transactions using Child-Pays-For-Parent.

Input:

typescript
{ id: string } // Transaction ID

Controller: WalletsControllers.utxoCPFPTransaction

Use Case: Speed up slow Bitcoin transactions by creating higher-fee child transactions.

Token Management ​

getWalletToken ​

Purpose: Retrieves information about a specific token in a wallet.

Input:

typescript
{
  walletId: string,
  tokenId: string
}

Controller: WalletsControllers.getWalletToken

Use Case: View token-specific balances and settings.

Operation Flow Diagram ​

Security Considerations ​

Authentication ​

All operations require authentication through the protectedProcedure wrapper.

Authorization ​

  • Operations are restricted to admin users
  • Sensitive operations (like transaction cancellation) should have additional checks

Audit Logging ​

All admin operations should be logged for audit purposes:

  • User who performed the operation
  • Timestamp
  • Operation type and parameters
  • Result

Error Handling ​

Common Error Scenarios ​

  1. Wallet Not Found: When wallet ID doesn't exist
  2. Address Not Found: When address ID doesn't exist
  3. Transaction Not Found: When transaction ID doesn't exist
  4. Invalid State: When operation cannot be performed in current state
  5. Blockchain Errors: When blockchain operations fail

Error Response Format ​

typescript
{
  error: {
    code: string,
    message: string,
    details?: any
  }
}

Monitoring and Alerts ​

Key Metrics to Monitor ​

  1. Operation Success Rate: Track failed operations
  2. Response Times: Monitor operation performance
  3. Error Patterns: Identify recurring issues
  4. Usage Patterns: Track which operations are used most
  • High error rate for any operation
  • Slow response times
  • Unusual usage patterns
  • Failed blockchain connections

Best Practices ​

When to Use Each Operation ​

Routine Maintenance ​

  • updateWalletBalance: Daily balance reconciliation
  • scanWallet: Weekly comprehensive checks
  • updateTransaction: For stuck transactions

Emergency Situations ​

  • cancelTransaction: For incorrect transactions
  • unlockWalletAddress: When addresses are stuck
  • utxoCPFPTransaction: For urgent Bitcoin transactions

Configuration Changes ​

  • updateWalletSettings: During maintenance windows
  • Enable/disable features based on operational needs

Operation Sequencing ​

Some operations should be performed in specific order:

  1. Before Maintenance: Disable deposits/withdrawals
  2. During Maintenance: Perform scans and updates
  3. After Maintenance: Re-enable operations

Bulk Operations ​

For operations on multiple items:

  • Process in batches to avoid overwhelming the system
  • Implement proper error handling for partial failures
  • Provide progress feedback for long-running operations

Integration with Monitoring ​

Dashboard Widgets ​

Recommended admin dashboard widgets:

  • Wallet balance summaries
  • Recent transaction status
  • Address utilization rates
  • Error rate trends

Real-time Updates ​

Operations that should trigger real-time updates:

  • Balance changes
  • Transaction status updates
  • Address state changes

Future Enhancements ​

Planned Features ​

  1. Bulk Operations: Support for batch processing
  2. Scheduled Operations: Automated maintenance tasks
  3. Advanced Filtering: Better search and filter capabilities
  4. Operation History: Track all admin actions
  5. Role-based Access: Different permission levels

API Improvements ​

  1. Pagination: For operations returning large datasets
  2. Sorting: Configurable result ordering
  3. Caching: Improve performance for read operations
  4. Rate Limiting: Prevent abuse of admin operations