Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Koniverse/SubWallet-Extension/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The ChainService is the core service responsible for managing blockchain network connections, chain metadata, asset registries, and API instances across all supported networks. It provides a unified interface for interacting with Substrate, EVM, Ton, Cardano, and Bitcoin chains.
Key Features
- Multi-chain connection management
- Chain and asset metadata storage
- Dynamic provider switching
- API instance management (Substrate, EVM, Ton, Cardano, Bitcoin)
- Chain health monitoring
- Custom chain and token support
- Cross-chain asset references (XCM)
Class: ChainService
Constructor
constructor(
dbService: DatabaseService,
eventService: EventService
)
Database service for persisting chain data
Event service for chain state changes
Initialization Methods
init()
Initializes the chain service, loads chain data, and connects to active chains.
async init(): Promise<void>
const chainService = new ChainService(dbService, eventService);
await chainService.init();
getChainInfoMap()
Retrieves all chain information.
getChainInfoMap(): Record<string, _ChainInfo>
Record<string, _ChainInfo>
Map of chain slugs to chain information
getChainInfoByKey()
Retrieves chain information by slug.
getChainInfoByKey(key: string): _ChainInfo
Chain slug (e.g., ‘polkadot’, ‘ethereum’, ‘kusama’)
Chain information objectHuman-readable chain name
Chain status (ACTIVE, INACTIVE, STOPPED)
Substrate-specific information
Cardano-specific information
Bitcoin-specific information
Whether this is a testnet
const polkadot = chainService.getChainInfoByKey('polkadot');
console.log(polkadot.name); // "Polkadot"
console.log(polkadot.chainStatus); // "ACTIVE"
getActiveChains()
Retrieves all active chain slugs.
getActiveChains(): string[]
Array of active chain slugs
getActiveChainInfoMap()
Retrieves information for all active chains.
getActiveChainInfoMap(): Record<string, _ChainInfo>
Chain State Methods
getChainStateByKey()
Retrieves chain state (active status, current provider).
getChainStateByKey(key: string): _ChainState
Chain state objectWhether chain is currently active
Currently selected provider key
Whether user manually disabled the chain
enableChain()
Enables a chain and connects to it.
async enableChain(chainSlug: string): Promise<boolean>
true if chain was enabled successfully
const success = await chainService.enableChain('moonbeam');
if (success) {
console.log('Moonbeam enabled and connected');
}
disableChain()
Disables a chain and disconnects from it.
disableChain(chainSlug: string, preventManualTurnOff?: boolean): boolean
If true, doesn’t mark as manually turned off
enableChains()
Enables multiple chains at once.
async enableChains(chainSlugs: string[]): Promise<boolean>
Array of chain slugs to enable
API Access Methods
getSubstrateApi()
Retrieves Substrate API instance for a chain.
getSubstrateApi(slug: string): _SubstrateApi | undefined
Substrate API wrapperPromise resolving when API is ready
const api = chainService.getSubstrateApi('polkadot');
if (api) {
await api.isReady;
const chainName = await api.api.rpc.system.chain();
console.log('Chain name:', chainName.toString());
}
getEvmApi()
Retrieves EVM API instance (Web3) for a chain.
getEvmApi(slug: string): _EvmApi | undefined
const evmApi = chainService.getEvmApi('ethereum');
if (evmApi) {
const blockNumber = await evmApi.api.eth.getBlockNumber();
console.log('Block number:', blockNumber);
}
getTonApi()
Retrieves TON API instance.
getTonApi(slug: string): _TonApi | undefined
getCardanoApi()
Retrieves Cardano API instance.
getCardanoApi(slug: string): _CardanoApi | undefined
getBitcoinApi()
Retrieves Bitcoin API instance.
getBitcoinApi(slug: string): _BitcoinApi | undefined
Asset Registry Methods
getAssetRegistry()
Retrieves all registered assets.
getAssetRegistry(): Record<string, _ChainAsset>
Record<string, _ChainAsset>
Map of asset slugs to asset information
getAssetBySlug()
Retrieves asset information by slug.
getAssetBySlug(slug: string): _ChainAsset
Asset slug (e.g., ‘polkadot-NATIVE-DOT’, ‘ethereum-ERC20-USDT’)
Asset informationChain where asset originates
Asset symbol (e.g., DOT, USDT)
Asset type (NATIVE, ERC20, PSP22, etc.)
Asset-specific metadata (contract address, etc.)
const dot = chainService.getAssetBySlug('polkadot-NATIVE-DOT');
console.log(`${dot.symbol}: ${dot.decimals} decimals`);
getNativeTokenInfo()
Retrieves the native token for a chain.
getNativeTokenInfo(chainSlug: string): _ChainAsset
const nativeToken = chainService.getNativeTokenInfo('polkadot');
console.log('Native token:', nativeToken.symbol); // "DOT"
getFungibleTokensByChain()
Retrieves all fungible tokens for a specific chain.
getFungibleTokensByChain(
chainSlug: string,
checkActive?: boolean
): Record<string, _ChainAsset>
Only return visible/active assets
Asset Settings Methods
getAssetSettings()
Retrieves asset visibility settings.
async getAssetSettings(): Promise<Record<string, AssetSetting>>
Record<string, AssetSetting>
Map of asset slugs to settingsWhether asset is visible in UI
setAssetSettings()
Updates asset settings.
setAssetSettings(settings: Record<string, AssetSetting>): void
subscribeAssetSettings()
Subscribes to asset settings changes.
subscribeAssetSettings(): BehaviorSubject<Record<string, AssetSetting>>
Custom Chain Methods
upsertCustomToken()
Adds or updates a custom token.
upsertCustomToken(token: _ChainAsset): string
const tokenSlug = chainService.upsertCustomToken({
slug: '', // Auto-generated if empty
originChain: 'ethereum',
symbol: 'CUSTOM',
decimals: 18,
assetType: _AssetType.ERC20,
metadata: {
contractAddress: '0x...'
},
name: 'Custom Token',
priceId: null,
multiChainAsset: null,
hasValue: true,
icon: ''
});
console.log('Token slug:', tokenSlug);
deleteCustomAssets()
Deletes custom tokens.
deleteCustomAssets(tokenSlugs: string[]): void
removeCustomChain()
Removes a custom chain.
removeCustomChain(slug: string): boolean
Connection Status Methods
getChainStatusMap()
Retrieves connection status for all chains.
getChainStatusMap(): Record<string, _ChainApiStatus>
Record<string, _ChainApiStatus>
Map of chain slugs to statusCONNECTED, DISCONNECTED, CONNECTING, or UNSTABLE
Timestamp of last status update
subscribeChainStatusMap()
Subscribes to chain connection status updates.
subscribeChainStatusMap(): BehaviorSubject<Record<string, _ChainApiStatus>>
chainService.subscribeChainStatusMap().subscribe((statusMap) => {
Object.entries(statusMap).forEach(([chain, status]) => {
console.log(`${chain}: ${status.connectionStatus}`);
});
});
XCM Reference Methods
subscribeXcmRefMap()
Subscribes to XCM asset reference map.
subscribeXcmRefMap(): Subject<Record<string, _AssetRef>>
Observable emitting XCM asset references for cross-chain transfers
Example: Complete Chain Management
import { ChainService } from '@subwallet/extension-base';
// Initialize
const chainService = new ChainService(dbService, eventService);
await chainService.init();
// Get all active chains
const activeChains = chainService.getActiveChains();
console.log('Active chains:', activeChains);
// Enable a new chain
await chainService.enableChain('moonbeam');
// Get chain info
const polkadot = chainService.getChainInfoByKey('polkadot');
console.log('Polkadot providers:', Object.keys(polkadot.providers));
// Access API
const api = chainService.getSubstrateApi('polkadot');
if (api) {
await api.isReady;
const blockHash = await api.api.rpc.chain.getBlockHash();
console.log('Latest block:', blockHash.toHex());
}
// Get assets for a chain
const polkadotAssets = chainService.getFungibleTokensByChain('polkadot', true);
console.log('Polkadot assets:', Object.keys(polkadotAssets));
// Monitor connection status
chainService.subscribeChainStatusMap().subscribe((status) => {
if (status['polkadot']?.connectionStatus === 'DISCONNECTED') {
console.warn('Polkadot disconnected!');
}
});
Connection Status Types
enum _ChainConnectionStatus {
CONNECTED = 'CONNECTED',
DISCONNECTED = 'DISCONNECTED',
UNSTABLE = 'UNSTABLE',
CONNECTING = 'CONNECTING'
}