@sodax/wallet-sdk-react 1.5.6-beta → 2.0.0-rc.1

package/ai-exported/migration/reference/hooks.md

@@ -0,0 +1,278 @@
+# Reference: Hook Signature Map
+
+Per-hook signature changes for v1 → v2. See [`../breaking-changes.md`](../breaking-changes.md) §3 for the WHY.
+
+---
+
+## Quick rule
+
+| Pattern | v1 (positional) | v2 (options object) |
+|---|---|---|
+| Pass chain family | `useX('EVM')` | `useX({ xChainType: 'EVM' })` |
+| Pass chain id | `useX('0x1.eth')` | `useX({ xChainId: ChainKeys.ETHEREUM_MAINNET })` |
+| Cannot pass both | (runtime detected) | TypeScript-enforced (`xChainType: never` on the chain-id branch and vice versa) |
+
+`xChainId` in v2 is typed as `SpokeChainKey` (the enum from `@sodax/types`), not the raw string id. The narrower type lets v2 hooks return chain-typed providers (e.g. `IEvmWalletProvider | undefined`) instead of the v1 union.
+
+---
+
+## `useXAccount`
+
+```ts
+// v1 ❌
+const { address } = useXAccount('EVM');
+const { address } = useXAccount('0x1.eth');
+
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+
+const { address } = useXAccount({ xChainType: 'EVM' });
+const { address } = useXAccount({ xChainId: ChainKeys.ETHEREUM_MAINNET });
+```
+
+**Decision rule (positional value → field name):** v1 accepted both `ChainType` and `ChainId` and detected at runtime. In v2 you must choose the right field:
+
+- v1 value is a family literal (`'EVM'`, `'SOLANA'`, …) → v2 `xChainType`.
+- v1 value is a chain-key string (`'0x1.eth'`, `XToken.xChainId`, …) → v2 `xChainId` typed as `SpokeChainKey`.
+- v1 value comes from `getXChainType(...)` (returns `ChainType | undefined`) → v2 `xChainType`, but **guard against `undefined`** — see below.
+
+**v2 asserts at runtime that exactly one of `xChainId` / `xChainType` is present.** Both undefined throws `'[useXAccount] pass xChainId or xChainType'`; both present throws `'[useXAccount] pass either xChainId or xChainType, not both'`. v1 was permissive (called with `undefined`, it returned an empty account). v2 is strict.
+
+**Common nullable patterns and their fixes:**
+
+```ts
+// ❌ v1 idiom — returns empty account when nothing selected, runs every render
+const { address } = useXAccount(selectedChainId ?? undefined);
+
+// ✅ v2 fix 1 — index a snapshot from useXAccounts (no per-key hook call)
+const xAccounts = useXAccounts();
+const chainType = selectedChainId ? getXChainType(selectedChainId) : undefined;
+const address = chainType ? xAccounts[chainType]?.address : undefined;
+
+// ✅ v2 fix 2 — supply a sensible default chain key so the hook always has input
+const { address } = useXAccount({
+  xChainId: selectedChainId ?? ChainKeys.SONIC_MAINNET,
+});
+
+// ✅ v2 fix 3 — split into a child component that only mounts when input is known
+{selectedChainId ? <Account xChainId={selectedChainId} /> : null}
+function Account({ xChainId }: { xChainId: SpokeChainKey }) {
+  const { address } = useXAccount({ xChainId });
+  // ...
+}
+```
+
+The other "options-object" hooks (`useXConnection`, `useXConnectors`, `useXService`, `useWalletProvider`) are **lenient** — passing no field returns the empty/undefined value silently. `useXAccount` is the only one that asserts.
+
+**Other notes:**
+- Return shape unchanged: `XAccount = { address, xChainType, publicKey? }`.
+- When a valid chain is supplied but no wallet is connected, `address` is `undefined` while `xChainType` is filled — same as v1's connected-empty state.
+
+---
+
+## `useXConnectors`
+
+```ts
+// v1 ❌
+const connectors = useXConnectors('EVM');
+
+// v2 ✅
+const connectors = useXConnectors({ xChainType: 'EVM' });
+```
+
+**Other notes:**
+- Return type changed from `XConnector[]` to `IXConnector[]` (interface). For most consumers this is invisible — both expose `id`, `name`, `icon`, `xChainType`, `connect()`, `disconnect()`.
+- v2 enriches each connector with `isInstalled`, `installUrl`, `icon` (read at access time from `window.*`).
+- v2 returns `[]` and logs a one-time warning if the chain isn't in `enabledChains`. v1 returned `[]` silently.
+
+---
+
+## `useXConnection`
+
+```ts
+// v1 ❌
+const connection = useXConnection('EVM');
+
+// v2 ✅
+const connection = useXConnection({ xChainType: 'EVM' });
+```
+
+Return shape unchanged: `XConnection | undefined = { xAccount, xConnectorId } | undefined`.
+
+---
+
+## `useXService`
+
+```ts
+// v1 ❌
+const service = useXService('EVM');
+
+// v2 ✅
+const service = useXService({ xChainType: 'EVM' });
+```
+
+Return type unchanged.
+
+---
+
+## `useWalletProvider`
+
+```ts
+// v1 ❌ — positional spokeChainId, returns wide union
+const wp = useWalletProvider('sui');
+
+// v2 ✅ — options object, narrowest type when xChainId is passed
+import { ChainKeys } from '@sodax/types';
+
+const wp = useWalletProvider({ xChainId: ChainKeys.SUI_MAINNET });
+//    ^ inferred as ISuiWalletProvider | undefined
+
+const wp2 = useWalletProvider({ xChainType: 'EVM' });
+//    ^ inferred as IEvmWalletProvider | undefined
+
+const wp3 = useWalletProvider();
+//    ^ inferred as IWalletProvider | undefined (any)
+```
+
+**Other notes:**
+- Pass either `xChainId` (`SpokeChainKey`) or `xChainType` (`ChainType`), never both. Chain key gives narrower TypeScript inference.
+- Returns `undefined` when the chain isn't enabled in `walletConfig` (logs a one-time warning) or when no wallet is connected.
+
+---
+
+## `useXConnect`
+
+```ts
+// v1 ✅ AND v2 ✅ — same signature
+const { mutateAsync: connect } = useXConnect();
+await connect(connector);
+```
+
+No change in shape. The `connector` argument type is `IXConnector` in v2 (was `XConnector` abstract class in v1) — runtime behavior identical for any connector returned by `useXConnectors`.
+
+---
+
+## `useXDisconnect`
+
+```ts
+// v1 ❌ — returned function takes positional ChainType
+const disconnect = useXDisconnect();
+await disconnect('EVM');
+
+// v2 ✅ — returned function takes options object
+const disconnect = useXDisconnect();
+await disconnect({ xChainType: 'EVM' });
+```
+
+The hook itself takes no args in both versions. The **returned function** changed: v1 was positional `(xChainType: ChainType) => Promise<void>`; v2 is `(args: UseXDisconnectArgs) => Promise<void>` where `UseXDisconnectArgs = { xChainType: ChainType }`. Same forward-compat reason as the other hooks — see [`../breaking-changes.md`](../breaking-changes.md) §3.
+
+**Common breakage:** `await disconnect(xChainType)` raises `TS2345: Argument of type 'string' is not assignable to parameter of type 'UseXDisconnectArgs'`. Wrap in an object.
+
+---
+
+## `useXSignMessage`
+
+```ts
+// v1 ✅ AND v2 ✅ — same signature
+const { mutateAsync: signMessage } = useXSignMessage();
+const sig = await signMessage({ xChainType: 'EVM', message: 'hello' });
+```
+
+No change.
+
+---
+
+## `useXAccounts`
+
+```ts
+// v1
+const accounts = useXAccounts();
+
+// v2 — return type is now strictly typed
+const accounts = useXAccounts();
+// → Partial<Record<ChainType, XAccount>>
+```
+
+Call signature unchanged. **Indexing tightened**: `accounts[chainType]` returns `XAccount | undefined`. The index variable must be typed as `ChainType` (not `string` or `any`) — otherwise you'll see `TS7053: Element implicitly has an 'any' type`.
+
+```ts
+// ❌ FAILS — chainType is `string`, can't index Partial<Record<ChainType, ...>>
+const chainType = someStringFromConfig;
+const account = accounts[chainType];
+
+// ✅ FIX 1 — narrow with getXChainType (returns ChainType | undefined)
+import { getXChainType } from '@sodax/wallet-sdk-react';
+const chainType = getXChainType(chainId);
+const account = chainType ? accounts[chainType] : undefined;
+
+// ✅ FIX 2 — call useXAccount per-chain instead of indexing
+const account = useXAccount({ xChainType: 'EVM' });
+```
+
+---
+
+## `useEvmSwitchChain`
+
+```ts
+// v1 ❌ — positional `expectedXChainId: ChainId`
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain(chainId);
+
+// v2 ✅ — options object; `xChainId: SpokeChainKey`
+import { ChainKeys } from '@sodax/types';
+
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+  xChainId: ChainKeys.ETHEREUM_MAINNET,
+});
+
+if (isWrongChain) handleSwitchChain();
+```
+
+**Breaking changes:**
+
+- **Call shape**: positional → options object. Same forward-compat reason as the other hooks.
+- **Parameter type**: `ChainId` → `SpokeChainKey` (rename in `@sodax/types`). If the chain key value comes from `XToken.chainKey` (v2) or any `ChainKeys.*` constant, no value change is needed — the rename is type-only.
+
+**Return shape is unchanged** — both v1 and v2 return `{ isWrongChain: boolean, handleSwitchChain: () => void }`. The hook compares the connected EVM chain to the chain expected by `xChainId` and exposes `isWrongChain` so UI can render a "switch network" CTA without recomputing.
+
+**Behavior added in v2:**
+
+- **Injective + MetaMask auto-switch.** When the user connects to Injective via MetaMask, v2 automatically targets Ethereum mainnet underneath. v1 had no Injective awareness.
+- **Safe when EVM is disabled.** v2 returns no-op values (`isWrongChain: false`, `handleSwitchChain: () => {}`) if `walletConfig.EVM` is absent, so UI doesn't need to branch.
+
+---
+
+## `useEthereumChainId`
+
+**Removed from the public barrel in v2.** Despite the generic-sounding name, the v1 hook was **Injective + MetaMask specific** — it read the underlying Ethereum chain ID exposed by Injective's wallet strategy and was almost always used to drive the "switch back to Ethereum mainnet" UX. v2 makes the hook internal because `useEvmSwitchChain` now handles that Injective auto-switch case directly.
+
+Migration:
+
+```diff
+- // v1 ❌ — manual chain-ID comparison for Injective + MetaMask UX
+- import { useEthereumChainId } from '@sodax/wallet-sdk-react';
+- const chainId = useEthereumChainId();
+- if (chainId !== 1) /* prompt user to switch to Ethereum mainnet */;
++ // v2 ✅ — useEvmSwitchChain auto-handles Injective + MetaMask underneath
++ import { useEvmSwitchChain } from '@sodax/wallet-sdk-react';
++ import { ChainKeys } from '@sodax/types';
++ const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
++   xChainId: ChainKeys.INJECTIVE_MAINNET,
++ });
++ if (isWrongChain) handleSwitchChain();
+```
+
+If you genuinely need the raw EVM chain ID (rare — almost no usage outside the Injective case), wagmi's `useAccount().chainId` is the underlying source. Prefer staying inside `@sodax/wallet-sdk-react` hooks where possible.
+
+---
+
+## Removed in v2
+
+| Hook | Replacement |
+|---|---|
+| `useXBalances` | Moved to `@sodax/dapp-kit`. See [`../breaking-changes.md`](../breaking-changes.md) §10. |
+
+---
+
+## Added in v2 (no v1 equivalent)
+
+See [`imports.md`](./imports.md) § "Added in v2" for the full list (`useWalletModal`, `useChainGroups`, `useBatchConnect`, etc.). These are not migration items — they are new capabilities you may opt into.

package/ai-exported/migration/reference/imports.md

@@ -0,0 +1,157 @@
+# Reference: Import Path Map
+
+Mechanical import-path replacements for v1 → v2. The package name (`@sodax/wallet-sdk-react`) is unchanged. See [`../breaking-changes.md`](../breaking-changes.md) §5 for the WHY behind concrete-class sub-path imports.
+
+---
+
+## Store hook removed from the public API
+
+v1 exported the Zustand store hook (`useXWagmiStore`) from the package barrel. **v2 does not export the store hook at all** — direct store access is no longer supported. The localStorage key (`xwagmi-store`) is unchanged, so user connections survive the upgrade.
+
+For each `useXWagmiStore(state => state.X)` selector, replace with the equivalent public hook below. **Do not rename to `useXWalletStore`** — the v2 barrel does not export it.
+
+### Field-to-hook map
+
+| v1 selector | v2 replacement |
+|---|---|
+| `state.xServices` (whole map) | `useXServices()` |
+| `state.xServices[chainType]` (per chain) | `useXService({ xChainType })` |
+| `state.xConnections` (whole map) | `useXConnections()` |
+| `state.xConnections[chainType]` (per chain) | `useXConnection({ xChainType })` |
+| `state.setXConnection` | not a public mutation — use `useXConnect()` (mutation hook) |
+| `state.unsetXConnection` | not a public mutation — use `useXDisconnect()` |
+
+```diff
+- // v1 ❌
+- import { useXWagmiStore } from '@sodax/wallet-sdk-react';
+- const xServices = useXWagmiStore(state => state.xServices);
++ // v2 ✅ — public hook, no store access
++ import { useXServices } from '@sodax/wallet-sdk-react';
++ const xServices = useXServices();
+```
+
+### Decision tree — `useXWagmiStore` selector handling
+
+For each occurrence of `useXWagmiStore(state => state.X)`:
+
+1. **Is `X` a public-hook-equivalent read** (`xServices`, `xConnections`, or per-chain access of either)?
+   → Replace with the public hook from the table. Drop the `useXWagmiStore` import.
+2. **Is `X` a mutation** (`setXConnection`, `unsetXConnection`) **or a v2-internal field** (`enabledChains`, `chainActions`, `walletProviders`, `xConnectorsByChain`)?
+   → STOP. The user's code is poking at internal API or was hand-edited mid-migration. Ask the user before changing.
+3. **Anything else** (typo, removed v1 field)?
+   → STOP. Ask user.
+
+### Worked example
+
+```ts
+// v1 ❌ — direct store read
+const xServices = useXWagmiStore(state => state.xServices);
+
+// v2 ✅ — public hook (no store access)
+const xServices = useXServices();
+
+// 🛑 STOP — mutation through store; v2 does not expose this on a hook
+const setConn = useXWagmiStore(state => state.setXConnection);
+// → Ask user. Likely they want useXConnect()'s mutation instead.
+```
+
+Always prefer public hooks (`useXService`, `useXServices`, `useXConnection`, `useXConnections`, `useEnabledChains`, `useWalletProvider`) over store reads — see [`../../integration/reference/hooks.md`](../../integration/reference/hooks.md).
+
+---
+
+## Concrete chain classes — moved behind sub-path imports
+
+v1 re-exported every concrete `XService` / `XConnector` subclass from the package barrel. v2's barrel exports only types, hooks, abstractions, and `SodaxWalletProvider`.
+
+| Concrete class | v1 import path | v2 import path |
+|---|---|---|
+| `EvmXService`, `EvmXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/evm` |
+| `SolanaXService`, `SolanaXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/solana` |
+| `SuiXService`, `SuiXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/sui` |
+| `BitcoinXService`, `UnisatXConnector`, `XverseXConnector`, `OKXXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/bitcoin` |
+| `StellarXService`, `StellarWalletsKitXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/stellar` |
+| `InjectiveXService`, `InjectiveXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/injective` |
+| `IconXService`, `IconHanaXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/icon` |
+| `NearXService`, `NearXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/near` |
+| `StacksXService`, `StacksXConnector`, `STACKS_PROVIDERS` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/stacks` |
+
+### Examples
+
+```diff
+- // v1 ❌ — all concrete classes from barrel
+- import {
+-   EvmXService,
+-   XverseXConnector,
+-   IconHanaXConnector,
+- } from '@sodax/wallet-sdk-react';
++ // v2 ✅ — sub-path per chain
++ import { EvmXService } from '@sodax/wallet-sdk-react/xchains/evm';
++ import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
++ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
+```
+
+### Type imports also use sub-path
+
+Even when you only need a **type** (not the runtime class), the v2 barrel does not re-export concrete chain types. Use the sub-path import with `import type`:
+
+```diff
+- // v1 ❌
+- import { type StellarXService, useXService } from '@sodax/wallet-sdk-react';
++ // v2 ✅ — sub-path import for both type and runtime
++ import type { StellarXService } from '@sodax/wallet-sdk-react/xchains/stellar';
++ import type { XverseXConnector, BtcWalletAddressType } from '@sodax/wallet-sdk-react/xchains/bitcoin';
++ import { useXService } from '@sodax/wallet-sdk-react';
+```
+
+`import type` from sub-paths is **erased at build time** — no runtime cost. Use it freely for type annotations, `as`, generics, etc.
+
+---
+
+## Hooks — same package, same names (signatures changed)
+
+| Hook | v1 path | v2 path | Signature changed? |
+|---|---|---|---|
+| `useXAccount` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — see [`hooks.md`](./hooks.md) |
+| `useXAccounts` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useXConnect` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useXConnection` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXConnectors` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXDisconnect` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — returned function now takes `{ xChainType }` object (was positional) |
+| `useXService` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useWalletProvider` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXSignMessage` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useEvmSwitchChain` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — now takes `{ xChainId }`, returns `{ isWrongChain, handleSwitchChain }` |
+
+For signature changes see [`hooks.md`](./hooks.md).
+
+---
+
+## Removed in v2
+
+| Symbol | v1 path | Replacement |
+|---|---|---|
+| `useXBalances` | `@sodax/wallet-sdk-react` | Moved to `@sodax/dapp-kit` with a new signature (`{ params: { xService, xChainId, xTokens, address } }`). See [`../breaking-changes.md`](../breaking-changes.md) §10. |
+| `useEthereumChainId` | `@sodax/wallet-sdk-react` | Internal in v2. Use `useAccount().chainId` from `wagmi` for the raw EVM chain ID, or `useEvmSwitchChain({ xChainId })` if you only needed it for "wrong network" UX. See [`hooks.md`](./hooks.md) § `useEthereumChainId`. |
+
+---
+
+## Added in v2 (informational — no v1 to migrate from)
+
+These are new exports — no v1 import to replace, but knowing they exist may let you simplify hand-rolled v1 code during migration:
+
+| New hook / utility | Path | Purpose |
+|---|---|---|
+| `useWalletModal` | `@sodax/wallet-sdk-react` | Headless modal state machine |
+| `useConnectionFlow` | `@sodax/wallet-sdk-react` | `connect + status + retry` without modal |
+| `useBatchConnect` | `@sodax/wallet-sdk-react` | Sequential connect across multiple connectors |
+| `useBatchDisconnect` | `@sodax/wallet-sdk-react` | Mirror of `useBatchConnect` |
+| `useChainGroups` | `@sodax/wallet-sdk-react` | One row per enabled chain (EVM collapses) |
+| `useConnectedChains` | `@sodax/wallet-sdk-react` | Aggregate connected view + hydration `status` |
+| `useEnabledChains` | `@sodax/wallet-sdk-react` | List of chain types enabled in config |
+| `useIsWalletInstalled` | `@sodax/wallet-sdk-react` | Cross-chain install check |
+| `useXConnections` | `@sodax/wallet-sdk-react` | All connections (plural) |
+| `useXConnectorsByChain` | `@sodax/wallet-sdk-react` | Multi-chain connector list (no per-chain warnings) |
+| `useXServices` | `@sodax/wallet-sdk-react` | All services (plural) |
+| `sortConnectors` | `@sodax/wallet-sdk-react` | Helper: preferred → installed → original |
+| `getXChainType` | `@sodax/wallet-sdk-react` | Imperative: map a `SpokeChainKey` to its `ChainType` family. Common pattern: `useXService({ xChainType: getXChainType(srcChainKey) })` when you only have a chain key on hand. |
+| `getXService` | `@sodax/wallet-sdk-react` | Imperative variant of `useXService` for non-React call sites (e.g. inside event handlers that don't re-render). Prefer `useXService` in component bodies. |

package/dist/XConnector-B9YQTVJ4.d.ts

@@ -0,0 +1,146 @@
+import { ChainType, IXServiceBase, XToken } from '@sodax/types';
+
+type XAccount = {
+    address: string | undefined;
+    xChainType: ChainType | undefined;
+    publicKey?: string;
+};
+type XConnection = {
+    xAccount: XAccount;
+    xConnectorId: string;
+};
+
+/**
+ * Public interface for chain service implementations.
+ *
+ * Consumer code should depend on this interface instead of the concrete XService class.
+ * Extends the shared `IXServiceBase` from `@sodax/types` with wallet-sdk-react
+ * specific connector methods.
+ */
+interface IXService extends IXServiceBase {
+    getXConnectors(): IXConnector[];
+    getXConnectorById(xConnectorId: string): IXConnector | undefined;
+}
+/**
+ * Public interface for wallet connector implementations.
+ *
+ * `isInstalled` reads `window.*` at getter-call time (render time); no extra
+ * subscription is installed. Components get fresh values through normal React
+ * render triggers (store updates, parent rerenders).
+ */
+interface IXConnector {
+    readonly xChainType: ChainType;
+    readonly name: string;
+    /** Unique identifier for the connector */
+    readonly _id: string;
+    /** Optional icon URL for the wallet provider */
+    readonly _icon?: string;
+    readonly id: string;
+    readonly icon: string | undefined;
+    /** True when the wallet extension backing this connector is installed. */
+    readonly isInstalled: boolean;
+    /** URL where users can install the wallet extension if missing. */
+    readonly installUrl: string | undefined;
+    connect(): Promise<XAccount | undefined>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Abstract base class for blockchain service implementations.
+ *
+ * The XService class serves as a foundation for implementing blockchain-specific services
+ * in a multi-chain environment. It provides a standardized interface for:
+ * 1. Managing wallet connectors for different blockchain types
+ * 2. Querying token balances across different chains
+ *
+ * Each blockchain implementation (e.g., Solana, EVM chains) extends this class
+ * to provide chain-specific functionality while maintaining a consistent interface.
+ *
+ * @abstract
+ * @class XService
+ * @property {ChainType} xChainType - The blockchain type this service handles (e.g., 'SOLANA', 'EVM')
+ * @property {XConnector[]} xConnectors - Available wallet connectors for this chain
+ *
+ */
+declare abstract class XService implements IXServiceBase {
+    /** The blockchain type this service handles */
+    readonly xChainType: ChainType;
+    /** Available wallet connectors for this chain */
+    private xConnectors;
+    constructor(xChainType: ChainType);
+    /**
+     * Gets the balance of a specific token for an address
+     * @param address The wallet address to check
+     * @param xToken The token to get the balance for
+     * @returns Promise resolving to the token balance as a bigint
+     */
+    getBalance(address: string | undefined, xToken: XToken): Promise<bigint>;
+    /**
+     * Gets balances for multiple tokens for an address
+     * @param address The wallet address to check
+     * @param xTokens Array of tokens to get balances for
+     * @returns Promise resolving to object mapping token addresses to balances
+     */
+    getBalances(address: string | undefined, xTokens: readonly XToken[]): Promise<Record<string, bigint>>;
+    /**
+     * Gets all available connectors for this chain
+     */
+    getXConnectors(): IXConnector[];
+    /**
+     * Sets the available connectors for this chain
+     */
+    setXConnectors(xConnectors: IXConnector[]): void;
+    /**
+     * Gets a specific connector by its ID
+     * @param xConnectorId The connector ID to look up
+     * @returns The matching connector or undefined if not found
+     */
+    getXConnectorById(xConnectorId: string): IXConnector | undefined;
+}
+
+/**
+ * Base class for wallet provider connectors that handles connection management and wallet interactions
+ *
+ * @abstract
+ * @class XConnector
+ * @property {ChainType} xChainType - The blockchain type this connector supports
+ * @property {string} name - Display name of the wallet provider
+ * @property {string} _id - Unique identifier for the connector
+ * @property {string | undefined} _icon - Optional icon URL for the wallet provider
+ */
+declare abstract class XConnector implements IXConnector {
+    /** The blockchain type this connector supports */
+    readonly xChainType: ChainType;
+    /** Display name of the wallet provider */
+    readonly name: string;
+    /** Unique identifier for the connector */
+    readonly _id: string;
+    /** Optional icon URL for the wallet provider */
+    readonly _icon?: string;
+    constructor(xChainType: ChainType, name: string, id: string);
+    /**
+     * Connects to the wallet provider
+     * @returns Promise resolving to the connected account, or undefined if connection fails
+     */
+    abstract connect(): Promise<XAccount | undefined>;
+    /**
+     * Disconnects from the wallet provider
+     */
+    abstract disconnect(): Promise<void>;
+    /** Get the unique identifier for this connector */
+    get id(): string;
+    /** Get the optional icon URL for this wallet provider */
+    get icon(): string | undefined;
+    /**
+     * True when the wallet extension backing this connector is installed.
+     * Default: true (for provider-managed chains where connector presence already
+     * implies install — EVM via EIP-6963, Solana/Sui via adapter discovery).
+     * Subclasses backed by extension injection (Bitcoin, ICON, Stacks) override
+     * this with a window probe.
+     */
+    get isInstalled(): boolean;
+    /** URL to install the wallet extension when missing. Subclasses override. */
+    get installUrl(): string | undefined;
+}
+
+export { type IXConnector as I, type XAccount as X, type XConnection as a, XService as b, XConnector as c, type IXService as d };