feat(sdk): construct raw spoke provider util (#903)

Author: R0bi7

packages/sdk/docs/HOW_TO_CREATE_A_SPOKE_PROVIDER.md

@@ -43,6 +43,44 @@ Raw spoke providers are ideal for:
 
 **Note**: When using raw spoke providers with Sodax features, you must pass the `raw: true` flag to methods like `createIntent()`, `supply()`, etc. This ensures the methods return raw transaction data instead of attempting to execute transactions.
 
+### Constructing a Raw Spoke Provider from Config
+
+When you have a generic config object (e.g. from API or runtime) and want a single entry point to build the correct raw spoke provider for any supported chain, use the **`constructRawSpokeProvider`** helper. It dispatches on `config.chainConfig.chain.type` and returns the appropriate raw spoke provider instance.
+
+**Signature**
+
+```typescript
+function constructRawSpokeProvider(config: RawSpokeProviderConfig): RawSpokeProvider
+```
+
+- **Parameter**: `config` — A chain-specific raw spoke provider config (`EvmRawSpokeProviderConfig`, `SonicRawSpokeProviderConfig`, `StellarRawSpokeProviderConfig`, `SolanaRawSpokeProviderConfig`, `IconRawSpokeProviderConfig`, `InjectiveRawSpokeProviderConfig`, or `SuiRawSpokeProviderConfig`). The config must include `chainConfig` with `chain.type` set to one of: `EVM`, `STELLAR`, `SOLANA`, `ICON`, `INJECTIVE`, `SUI`. For Sonic, use EVM config with `chain.id === SONIC_MAINNET_CHAIN_ID`.
+- **Returns**: A `RawSpokeProvider` instance (e.g. `EvmRawSpokeProvider`, `StellarRawSpokeProvider`, `SolanaRawSpokeProvider`, etc.).
+- **Throws**: `Error` with message `Unsupported chain type: ${chainType}` if `chain.type` is not supported.
+
+**Example**
+
+```typescript
+import {
+  constructRawSpokeProvider,
+  spokeChainConfig,
+  ARBITRUM_MAINNET_CHAIN_ID,
+  type RawSpokeProviderConfig,
+  type EvmRawSpokeProviderConfig,
+} from "@sodax/sdk";
+
+// Config might come from API or be built at runtime
+const config: EvmRawSpokeProviderConfig = {
+  walletAddress: "0x...",
+  chainConfig: spokeChainConfig[ARBITRUM_MAINNET_CHAIN_ID],
+  rpcUrl: "https://arb1.arbitrum.io/rpc",
+};
+
+const rawSpokeProvider = constructRawSpokeProvider(config);
+// rawSpokeProvider is EvmRawSpokeProvider — use with Sodax features and raw: true
+```
+
+Use `constructRawSpokeProvider` when the chain type is determined at runtime or when you want one code path that works for all supported chains. For a known chain type, you can still instantiate the specific raw spoke provider class directly (e.g. `new EvmRawSpokeProvider(...)`) as shown in the chain-specific sections below.
+
 ## Prerequisites
 
 Before creating a spoke provider, ensure you have:
@@ -1073,6 +1111,7 @@ For detailed staking documentation, see [STAKING.md](./STAKING.md).
   - `InjectiveRawSpokeProvider` for Injective blockchain
   - `IconRawSpokeProvider` for ICON blockchain
   - `SolanaRawSpokeProvider` for Solana blockchain
+  - **`constructRawSpokeProvider(config)`** — builds the correct raw spoke provider from a `RawSpokeProviderConfig` based on `chainConfig.chain.type` (use when chain is chosen at runtime).
 
 - **When to use Raw Spoke Providers:**
   - Backend services creating transaction payloads

packages/sdk/src/shared/entities/Providers.ts

@@ -11,10 +11,18 @@ import {
   createPublicClient,
 } from 'viem';
 import { getEvmViemChain } from '../constants.js';
-import type { InjectiveRawSpokeProvider, InjectiveSpokeProvider } from './injective/InjectiveSpokeProvider.js';
-import type { IconRawSpokeProvider, IconSpokeProvider } from './icon/IconSpokeProvider.js';
-import type { SolanaRawSpokeProvider, SolanaSpokeProvider } from './solana/SolanaSpokeProvider.js';
-import type { SuiRawSpokeProvider, SuiSpokeProvider } from './sui/SuiSpokeProvider.js';
+import type {
+  InjectiveRawSpokeProvider,
+  InjectiveRawSpokeProviderConfig,
+  InjectiveSpokeProvider,
+} from './injective/InjectiveSpokeProvider.js';
+import type { IconRawSpokeProvider, IconRawSpokeProviderConfig, IconSpokeProvider } from './icon/IconSpokeProvider.js';
+import type {
+  SolanaRawSpokeProvider,
+  SolanaRawSpokeProviderConfig,
+  SolanaSpokeProvider,
+} from './solana/SolanaSpokeProvider.js';
+import type { SuiRawSpokeProvider, SuiRawSpokeProviderConfig, SuiSpokeProvider } from './sui/SuiSpokeProvider.js';
 import {
   SONIC_MAINNET_CHAIN_ID,
   type IEvmWalletProvider,
@@ -32,7 +40,11 @@ import {
 } from '@sodax/types';
 import type { ConfigService } from '../config/ConfigService.js';
 import { getHubChainConfig } from '../config/ConfigService.js';
-import type { StellarRawSpokeProvider, StellarSpokeProvider } from './stellar/StellarSpokeProvider.js';
+import type {
+  StellarRawSpokeProvider,
+  StellarRawSpokeProviderConfig,
+  StellarSpokeProvider,
+} from './stellar/StellarSpokeProvider.js';
 
 export type CustomProvider = { request(...args: unknown[]): Promise<unknown> };
 
@@ -129,6 +141,12 @@ export class SonicSpokeProvider extends SonicBaseSpokeProvider implements ISpoke
   }
 }
 
+export type SonicRawSpokeProviderConfig = {
+  walletAddress: Address;
+  chainConfig: SonicSpokeChainConfig;
+  rpcUrl?: string;
+};
+
 export class SonicRawSpokeProvider extends SonicBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;
@@ -170,6 +188,12 @@ export class EvmSpokeProvider extends EvmBaseSpokeProvider implements ISpokeProv
   }
 }
 
+export type EvmRawSpokeProviderConfig = {
+  walletAddress: Address;
+  chainConfig: EvmSpokeChainConfig;
+  rpcUrl?: string;
+};
+
 export class EvmRawSpokeProvider extends EvmBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;
@@ -188,7 +212,6 @@ export type IWalletProvider =
   | IStellarWalletProvider
   | ISuiWalletProvider
   | IIconWalletProvider
-  | IInjectiveWalletProvider
   | ISolanaWalletProvider;
 
 export type SpokeProvider = (
@@ -213,4 +236,16 @@ export type RawSpokeProvider = (
 ) &
   IRawSpokeProvider;
 
+export type RawSpokeProviderConfig = (
+  | EvmRawSpokeProviderConfig
+  | InjectiveRawSpokeProviderConfig
+  | IconRawSpokeProviderConfig
+  | SuiRawSpokeProviderConfig
+  | StellarRawSpokeProviderConfig
+  | SolanaRawSpokeProviderConfig
+  | SonicRawSpokeProviderConfig
+) & {
+  chainConfig: SpokeChainConfig;
+};
+
 export type SpokeProviderType = SpokeProvider | RawSpokeProvider;

packages/sdk/src/shared/entities/icon/IconSpokeProvider.ts

@@ -35,6 +35,11 @@ export class IconSpokeProvider extends IconBaseSpokeProvider implements ISpokePr
   }
 }
 
+export type IconRawSpokeProviderConfig = {
+  chainConfig: IconSpokeChainConfig;
+  walletAddress: string;
+};
+
 export class IconRawSpokeProvider extends IconBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;

packages/sdk/src/shared/entities/injective/InjectiveSpokeProvider.ts

@@ -174,6 +174,11 @@ export class InjectiveBaseSpokeProvider {
   }
 }
 
+export type InjectiveRawSpokeProviderConfig = {
+  chainConfig: InjectiveSpokeChainConfig;
+  walletAddress: string;
+};
+
 export class InjectiveRawSpokeProvider extends InjectiveBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;

packages/sdk/src/shared/entities/stellar/StellarSpokeProvider.ts

@@ -316,6 +316,12 @@ export class StellarBaseSpokeProvider {
   }
 }
 
+export type StellarRawSpokeProviderConfig = {
+  walletAddress: string;
+  chainConfig: StellarSpokeChainConfig;
+  rpcConfig?: StellarRpcConfig;
+};
+
 export class StellarRawSpokeProvider extends StellarBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;

packages/sdk/src/shared/entities/sui/SuiSpokeProvider.ts

@@ -244,6 +244,11 @@ export class SuiBaseSpokeProvider {
   }
 }
 
+export type SuiRawSpokeProviderConfig = {
+  chainConfig: SuiSpokeChainConfig;
+  walletAddress: string;
+};
+
 export class SuiRawSpokeProvider extends SuiBaseSpokeProvider implements IRawSpokeProvider {
   public readonly walletProvider: WalletAddressProvider;
   public readonly raw = true;

packages/sdk/src/shared/guards.ts

@@ -14,12 +14,15 @@ import {
   type SonicRawSpokeProvider,
   type RawSpokeProvider,
   type SpokeProviderType,
+  type EvmRawSpokeProviderConfig,
+  type SonicRawSpokeProviderConfig,
+  type RawSpokeProviderConfig,
 } from './entities/Providers.js';
 import { InjectiveSpokeProvider, type InjectiveRawSpokeProvider } from './entities/injective/InjectiveSpokeProvider.js';
 import { IconSpokeProvider, type IconRawSpokeProvider } from './entities/icon/IconSpokeProvider.js';
-import { SolanaSpokeProvider, type SolanaRawSpokeProvider } from './entities/solana/SolanaSpokeProvider.js';
+import { SolanaSpokeProvider, type SolanaRawSpokeProvider, type SolanaRawSpokeProviderConfig } from './entities/solana/SolanaSpokeProvider.js';
 import { SuiSpokeProvider, type SuiRawSpokeProvider } from './entities/sui/SuiSpokeProvider.js';
-import { StellarSpokeProvider, type StellarRawSpokeProvider } from './entities/stellar/StellarSpokeProvider.js';
+import { StellarSpokeProvider, type StellarRawSpokeProvider, type StellarRawSpokeProviderConfig } from './entities/stellar/StellarSpokeProvider.js';
 import type {
   EvmSpokeProviderType,
   IconSpokeProviderType,
@@ -466,3 +469,45 @@ export function isSonicRawSpokeProvider(value: unknown): value is SonicRawSpokeP
 export function isAddressString(value: unknown): value is string {
   return typeof value === 'string';
 }
+
+export function isEvmRawSpokeProviderConfig(value: RawSpokeProviderConfig): value is EvmRawSpokeProviderConfig {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'walletAddress' in value &&
+    'chainConfig' in value &&
+    value.chainConfig.chain.type === 'EVM'
+  );
+}
+
+export function isSonicRawSpokeProviderConfig(value: RawSpokeProviderConfig): value is SonicRawSpokeProviderConfig {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'walletAddress' in value &&
+    'chainConfig' in value &&
+    value.chainConfig.chain.type === 'EVM' &&
+    value.chainConfig.chain.id === SONIC_MAINNET_CHAIN_ID
+  );
+}
+
+export function isStellarRawSpokeProviderConfig(value: RawSpokeProviderConfig): value is StellarRawSpokeProviderConfig {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'walletAddress' in value &&
+    'chainConfig' in value &&
+    value.chainConfig.chain.type === 'STELLAR'
+  );
+}
+
+export function isSolanaRawSpokeProviderConfig(value: RawSpokeProviderConfig): value is SolanaRawSpokeProviderConfig {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'walletAddress' in value &&
+    'chainConfig' in value &&
+    'connection' in value &&
+    value.chainConfig.chain.type === 'SOLANA'
+  );
+}