@sodax/sdk 2.0.0-rc.2 → 2.0.0-rc.3

package/ai-exported/AGENTS.md

@@ -63,7 +63,7 @@ ai-exported/
 2. **Every async public method returns `Result<T>`.** Branch on `result.ok`. No throws across service boundaries. Sub-Result forwarding is the default: `if (!sub.ok) return sub`.
 3. **Errors are `SodaxError<C>`.** A single class with a closed 13-code reason vocabulary (`VALIDATION_FAILED`, `RELAY_TIMEOUT`, `EXECUTION_FAILED`, …) plus a `feature` field (`'swap' | 'moneyMarket' | …`). The pair `(feature, code)` is your discriminator. Use `isSodaxError(e)` (not bare `instanceof`).
 4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider: <chain-narrowed> }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
-5. **Config is dynamic.** `await sodax.config.initialize()` fetches current chain/token config from the backend, with a safe fallback to packaged defaults. Lookups go through `sodax.config.*` — there is no `hubAssets`, no `moneyMarketSupportedTokens` global map, no static registry to import.
+5. **Config is dynamic; overrides only land on `sodax.config`.** Once a `Sodax` instance exists, always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`) — direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides. Full instance-scope-reader table + module-scope rules: [`integration/recipes/initialize-sodax.md`](integration/recipes/initialize-sodax.md) § *Module-scope reads*. Per-symbol status of v1 globals: [`migration/breaking-changes/architecture.md`](migration/breaking-changes/architecture.md) § 2.
 
 ## Top 5 v1 → v2 traps
 

package/ai-exported/integration/architecture.md

@@ -132,14 +132,20 @@ import { Sodax, type SodaxConfig, type DeepPartial } from '@sodax/sdk';
 new Sodax(config?: DeepPartial<SodaxConfig>): Sodax;
 ```
 
-`SodaxConfig` carries (all optional via `DeepPartial`):
+`SodaxConfig` has exactly **10 fields** (all required at the type level, but `DeepPartial` makes every leaf optional):
 
-- `solver` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }` (endpoints).
-- `swaps` — `SwapsConfig` (supported solver tokens per chain).
-- `moneyMarket`, `bridge`, `staking`, `dex`, `migration`, `partner`, `recovery` — feature-specific config (contract addresses, etc.).
-- `rpcConfig` — mapped type keyed by `ChainKey` values; `BitcoinRpcConfig` for `BITCOIN_MAINNET`, `StellarRpcConfig` for `STELLAR_MAINNET`, RPC URL strings for everything else.
-- `hubConfig` — hub provider config (consumed by `EvmHubProvider`).
-- `backendApi` — `{ url, api?: IConfigApi }` for custom backend / sandbox endpoints.
+- `fee: PartnerFee | undefined` — global partner fee, applied unless a feature-level config overrides.
+- `chains: Record<SpokeChainKey, SpokeChainConfig>` — per-spoke-chain config. Each entry carries `rpcUrl`, polling config, and chain-family-specific extras (`BitcoinSpokeChainConfig`, `StellarSpokeChainConfig`, etc.).
+- `swaps: SwapsConfig` — supported solver tokens per chain.
+- `moneyMarket: MoneyMarketConfig` — money market contracts + supported tokens.
+- `bridge: BridgeConfig` — bridge `{ partnerFee }` override.
+- `dex: DexConfig` — DEX pool/asset config.
+- `hub: HubConfig` — hub-chain (Sonic) full address map + RPC URL + polling config.
+- `api: ApiConfig` — backend API endpoint (`{ baseURL, timeout, headers }`).
+- `solver: SolverConfig` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }`.
+- `relay: RelayConfig` — intent relay endpoint + chain-id map.
+
+> **Not config slots** — `staking`, `migration`, `partner`/`partners`, `recovery` are services on the `Sodax` instance (`sodax.staking`, etc.) but they are **not** configurable via `SodaxConfig`. They run on packaged defaults; per-call params handle customization.
 
 In production, the packaged defaults are sufficient — pass nothing and call `await sodax.config.initialize()` to load fresh data from the backend.
 
@@ -174,7 +180,15 @@ Chain configs (vault addresses, supported tokens, fee parameters) change between
 
 ### Custom backend
 
-Inject a custom `IConfigApi` for testing or sandbox via `SodaxConfig.backendApi.api`. The contract: every method on `IConfigApi` returns `Promise<Result<T>>`.
+Point at a custom backend URL via `SodaxConfig.api.baseURL`:
+
+```ts
+const sodax = new Sodax({
+  api: { baseURL: 'https://sandbox-api.example.com' },
+});
+```
+
+`SodaxConfig.api` is `ApiConfig` (`{ baseURL, timeout, headers }`) — pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApi` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server, or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
 
 ---
 

package/ai-exported/integration/quickstart.md

@@ -196,7 +196,7 @@ The errors most likely to hit on a fresh install or first port.
 
 ### `sodax.config.initialize()` hangs / errors
 
-- The backend API is unreachable. The SDK should fall back to packaged defaults silently — check your network, then check that `SodaxConfig.backendApi.url` is correct (or omit it for the default).
+- The backend API is unreachable. The SDK should fall back to packaged defaults silently — check your network, then check that `SodaxConfig.api.baseURL` is correct (or omit it for the default).
 
 ### Stellar bridge / swap fails with `'Trustline missing'`
 

package/ai-exported/integration/recipes/initialize-sodax.md

@@ -45,6 +45,31 @@ await sodax.config.initialize();
 
 `initialize()` is the only initialization step. Don't `await` it inside every feature call — call it once at app startup. If you skip it entirely, feature services fall back to packaged defaults, which may be stale relative to the latest backend config (new tokens, new chains, fee parameter changes).
 
+## Module-scope reads (no Sodax instance needed)
+
+Some code runs at **module-load time** — constants files, utility modules, framework-provider configs — before any `Sodax` instance exists. For those, import the packaged-default constants directly from `@sodax/sdk` (re-exported from `@sodax/types`):
+
+```ts
+import { sodaxConfig, hubConfig } from '@sodax/sdk';
+
+// Hub address constants
+export const HUB_WALLET = hubConfig.addresses.hubWallet;
+export const STAKING_ROUTER = hubConfig.addresses.stakingRouter;
+
+// Full default config (every SodaxConfig field with packaged defaults)
+export const DEFAULT_SOLVER_ENDPOINT = sodaxConfig.solver.solverApiEndpoint;
+export const SUPPORTED_TOKENS_PER_CHAIN = sodaxConfig.swaps.supportedTokens;
+```
+
+| Need | Module-scope import (defaults only) | Instance-scope read (with overrides) |
+|---|---|---|
+| Hub contract addresses (assetManager, hubWallet, stakingRouter, etc.) | `hubConfig.addresses.*` | `sodax.config.getHubChainConfig().addresses.*` |
+| Full default SodaxConfig (read-only snapshot) | `sodaxConfig.*` (e.g. `sodaxConfig.hub`, `sodaxConfig.moneyMarket`) | `sodax.config.sodaxConfig` |
+| Per-chain spoke config (rpcUrl, nativeToken, addresses, supportedTokens, polling) | `spokeChainConfig[ChainKeys.X_MAINNET]` (from `@sodax/types` / `@sodax/sdk`) | `sodax.config.spokeChainConfig[ChainKeys.X_MAINNET]` *or* `sodax.config.getChainConfig(ChainKeys.X_MAINNET)` |
+| Money market reserve assets | `sodaxConfig.moneyMarket.supportedReserveAssets` | `sodax.config.getMoneyMarketReserveAssets()` |
+
+> **Static vs dynamic — and the override-gap consequence.** `sodaxConfig` / `hubConfig` / `spokeChainConfig` are **packaged-default snapshots** frozen at SDK release time. They are safe at module scope but: (a) won't reflect backend-driven config updates loaded by `sodax.config.initialize()`, and (b) **won't reflect overrides passed to `new Sodax(config)`** — those merge into `sodax.config` (the `ConfigService`) but never mutate the static imports. So once a `Sodax` instance exists, prefer the instance-scope readers in the right column above — particularly `sodax.config.spokeChainConfig` over the same-named static import — or you will silently fall back to the packaged defaults for any chain you customized.
+
 
 ## Cross-references
 

package/ai-exported/migration/README.md

@@ -10,7 +10,7 @@ v2 was a deep architectural reshape, not a feature release. Five orthogonal chan
 2. **`Result<T>` everywhere.** Every async public method on every service returns `Promise<Result<T, SodaxError<C>>>`. v1 throw-on-error patterns are gone.
 3. **One canonical error class.** `SodaxError<C>` with a closed 13-code vocabulary plus `feature: 'swap' | 'moneyMarket' | …`. The per-module typed error unions (`MoneyMarketError<Code>`, `IntentError<Code>`, `StakingError<Code>`, `BridgeError<Code>`, `MigrationError<Code>`, `AssetServiceError<Code>`, `ConcentratedLiquidityError<Code>`, partner errors, …) are deleted.
 4. **`WalletProviderSlot<K, Raw>` is the discriminated union.** Every signed-execution method takes `{ raw: false, walletProvider }` (chain-narrowed via `GetWalletProviderType<K>`); every raw-tx-building method takes `{ raw: true }` (no wallet provider). Compile-time enforced.
-5. **`ConfigService` replaces static lookups.** Globals like `hubAssets`, `moneyMarketSupportedTokens`, `SodaTokens`, and the `*_MAINNET_CHAIN_ID` constants are gone. Lookups go through `sodax.config.*` (which loads from the backend API with a packaged-defaults fallback).
+5. **`ConfigService` is the preferred lookup surface.** `hubAssets` and `*_MAINNET_CHAIN_ID` constants **are deleted** (won't compile). `moneyMarketSupportedTokens`, `SodaTokens`, `supportedSpokeChains` **are still exported** as packaged-default constants (so v1 imports keep compiling), but prefer `sodax.config.*` / `sodax.moneyMarket.getSupportedTokens*()` — those reflect backend-driven runtime updates after `await sodax.config.initialize()`. See [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § 2 for the per-symbol table.
 
 The remainder is per-feature (return shape diffs, field renames, new required params like `srcAddress`).
 
@@ -40,7 +40,7 @@ Same word, different concept across versions. Skim before reading the breaking-c
 | **raw tx** | An ad-hoc method on each spoke provider, sometimes named `executeXxx`, returning a chain-specific payload. | The discriminator `{ raw: true }` on the standard SDK call shape. Return type narrows via `TxReturnType<K, true>` (`EvmRawTransaction`, `SolanaRawTransaction`, …). |
 | **config** | A `SodaxConfig` object passed at construction with hard-coded chain/token tables. Solver endpoints lived under `SodaxConfig.swaps`. | A `Sodax` instance owns a `ConfigService` that loads from the backend API, with packaged defaults as fallback. `sodax.config.*` is the lookup surface. **Solver endpoints moved to `SodaxConfig.solver`** (not `swaps`); `swaps` is `SwapsConfig` (supported tokens). |
 | **`xChainId` field on tokens** | Field name on the `Token` type. | Renamed: `XToken.chainKey`. Type also renamed: `Token` → `XToken`. |
-| **`hubAssets` / `moneyMarketSupportedTokens`** | Static `Record` global maps imported and walked. | Gone. Use `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()`. Each `XToken` now carries `vault` and `hubAsset` directly. |
+| **`hubAssets` / `moneyMarketSupportedTokens`** | Static `Record` global maps imported and walked. | `hubAssets` **deleted** — won't compile. `moneyMarketSupportedTokens` **still exported** as a packaged default, but prefer `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()` so backend updates take effect. Each `XToken` now carries `vault` and `hubAsset` directly. |
 | **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the backend submit-swap request. | Renamed: `srcChainKey: SpokeChainKey`. |
 | **`Intent.srcChain` / `Intent.dstChain`** | Read shape: `IntentRelayChainId` (bigint). | **Unchanged.** This is the relay chain id, not a spoke chain key. A blanket grep-replace `srcChain`→`srcChainKey` will break this. |
 | **`AddressType`** | Bitcoin-specific address-type union. | Renamed: `BtcAddressType`. (Generic name freed up.) |

package/ai-exported/migration/breaking-changes/architecture.md

@@ -5,7 +5,7 @@ The structural changes that reshaped the SDK at the service / runtime layer. Rea
 The four load-bearing shifts:
 
 1. **Per-chain `*SpokeProvider` classes are deleted.** Routing is by chain key, dispatched internally by `SpokeService`.
-2. **Static lookup tables (`hubAssets`, `moneyMarketSupportedTokens`, `SodaTokens`) are deleted.** Lookups go through `sodax.config.*`.
+2. **Static lookup tables — `hubAssets` deleted; `moneyMarketSupportedTokens`, `SodaTokens`, `supportedSpokeChains` still exported as packaged defaults but should yield to `sodax.config.*` so backend updates take effect.** See § 2 below for the per-symbol status table.
 3. **Relay flow is centralised.** Two functions (`relayTxAndWaitPacket`, `submitTransaction`) and one mapper (`mapRelayFailure`) replace per-feature relay helpers.
 4. **Invariants and guards are unified.** `sodaxInvariant` + per-feature aliases (`swapInvariant`, `mmInvariant`, etc.) and `isSodaxError` / `isFeatureError` replace ad-hoc throws and module-specific type guards.
 
@@ -115,6 +115,8 @@ These v1 names still ship through `@sodax/sdk` (re-exported from `@sodax/types`)
 | `Object.entries(moneyMarketSupportedTokens)` (walk pattern) | Const still exported | `sodax.moneyMarket.getSupportedTokens()` (returns `Record<SpokeChainKey, XToken[]>`) |
 | `SodaTokens` registry (vault-validation) | Still exported (`packages/types/src/chains/tokens.ts`) | `sodax.config.getMoneyMarketReserveAssets()` or `sodax.moneyMarket.getSupportedReserves()` |
 | `swapSupportedTokens[chainId]` (v1 had no `solverSupportedTokens`) | Still exported (`packages/types/src/swap/swap.ts`) | `sodax.config.getSupportedSwapTokensByChainId(chainKey)` |
+| `getSupportedSolverTokens(chainId)` (free function) | Still exported (`packages/types/src/swap/swap.ts`) | `sodax.config.getSupportedSwapTokensByChainId(chainKey)` |
+| `supportedSpokeChains` (`SpokeChainKey[]`) | Still exported (`packages/types/src/chains/chains.ts`) | `sodax.config.isValidSpokeChainKey(chainKey)` for validation, or read `sodaxConfig.chains` at module scope |
 
 ### What replaces them
 

package/ai-exported/migration/breaking-changes/type-system.md

@@ -194,6 +194,26 @@ v1 consumers reached into a global `hubAssets[chainId][address]` map to get the
 
 Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitSwapTxRequest`) gained the `*ChainKey` field names.
 
+### Exception — partner module read shapes DID rename
+
+The above "read shapes keep `srcChain`/`dstChain`" rule has one exception: **partner module** read shapes also renamed `dstChain` → `dstChainKey`. Specifically:
+
+- `AutoSwapPreferences` (returned by `sodax.partners.getAutoSwapPreferences(queryAddress)`) — field `dstChain` → **`dstChainKey: SpokeChainKey | 'not configured'`**.
+- `SetSwapPreferenceParams` (request type for `setSwapPreference`) — `dstChain` → `dstChainKey: SpokeChainKey`.
+
+```diff
+- // v1
+- const prefs = await partnerFeeClaimService.getAutoSwapPreferences(addr);
+- const destChain: SpokeChainId = prefs.dstChain;
+
++ // v2
++ const result = await sodax.partners.getAutoSwapPreferences(addr);
++ if (!result.ok) return;
++ const destChain: SpokeChainKey | 'not configured' = result.value.dstChainKey;
+```
+
+A blanket grep `dstChain` → `dstChainKey` is safe in the partner module **but** still unsafe in `Intent` / `IntentResponse` reads. Scope grep replacements per file or per import. The general rule for `srcChain` (Intent read field) is unchanged: it remains the relay chain id.
+
 ---
 
 ## 5. `RpcConfig` reshape

package/ai-exported/migration/checklist.md

@@ -20,6 +20,11 @@ Work this top-down. Each step is independent enough to land as its own commit; t
 [ ] 7.  Add { raw: false } discriminator to every signed call shape that
         previously took a positional spoke provider:
             { intentParams, spokeProvider }   →   { params, raw: false, walletProvider }
+[ ] 7b. Cross-cutting rename: every payload field named `spokeProvider:` (incl.
+        approve/allowance/utility methods that aren't signed-execution shapes)
+        → `walletProvider:`. Mechanical for the OBJECT-LITERAL field key; don't
+        blindly rename variable names of the same spelling. See
+        [`recipes.md`](recipes.md) § 1 "What's not safe to grep-replace".
 [ ] 8.  Add srcChainKey + srcAddress to every action params object that didn't
         carry them in v1 (most MM, staking, dex, bridge, migration param shapes).
 [ ] 9.  Convert every await sodax.<service>.<method>(...) call site that previously
@@ -28,9 +33,10 @@ Work this top-down. Each step is independent enough to land as its own commit; t
 [ ] 10. Delete imports of MoneyMarketError, IntentError, StakingError, BridgeError,
         MigrationError, AssetServiceError, ConcentratedLiquidityError, RelayError,
         plus the five Partner error types and their type-guard helpers.
-[ ] 11. Replace any walked global lookup (hubAssets[chainId][address],
-        moneyMarketSupportedTokens[chainId], SodaTokens[...]) with the equivalent
-        sodax.config.* / sodax.moneyMarket.getSupportedTokens*() calls.
+[ ] 11. Replace any walked global lookup (hubAssets, moneyMarketSupportedTokens,
+        SodaTokens, supportedSpokeChains) with the equivalent sodax.config.* /
+        sodax.moneyMarket.getSupportedTokens*() call. Per-symbol deleted-vs-
+        still-exported status: see breaking-changes/architecture.md § 2.
 [ ] 12. Initialize ConfigService at app startup: await sodax.config.initialize().
         Falls back to packaged defaults if the backend is unreachable.
 [ ] 13. Add { raw: true } to any read-only allowance check that previously took

package/ai-exported/migration/features/bridge.md

@@ -19,7 +19,7 @@ Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge
 
 | Type | v1 shape | v2 shape | Notes |
 |---|---|---|---|
-| `CreateBridgeParams` | `{ srcAsset, amount, dstChainId, dstAddress, dstAsset }` | `{ srcChainKey, srcAddress, srcAsset, amount, dstChainKey, dstAddress, dstAsset }` | Now generic `<K>`. `srcChainId`/`dstChainId` (where they appeared) → `srcChainKey`/`dstChainKey`. |
+| `CreateBridgeIntentParams` | `{ srcChainId, srcAsset, amount, dstChainId, dstAsset, recipient }` | `{ srcChainKey, srcAddress, srcToken, amount, dstChainKey, dstToken, recipient }` | Now generic `<K>`. Renames: `srcChainId`/`dstChainId` → `srcChainKey`/`dstChainKey`; `srcAsset`/`dstAsset` → `srcToken`/`dstToken`. `recipient` is **unchanged**. NEW required: `srcAddress` (user's spoke-side sender, distinct from `recipient` which is the destination receiver). |
 | Bridge action wrapper | `{ params, spokeProvider }` | `{ params, raw: false, walletProvider }` | Same as every feature. |
 | `bridge` return | `Promise<string>` (tx hash, throws on error) | `Promise<Result<TxHashPair, SodaxError>>` | Tx-pair + Result. |
 | `getBridgeableAmount` | `Promise<bigint>` | `Promise<Result<BridgeLimit, SodaxError>>` where `BridgeLimit = { amount, decimals, type }` | Result-wrapped + richer return shape. Now takes `(from: XToken, to: XToken)` (was `(srcChainId, srcToken, dstChainId, dstToken)`). |
@@ -44,21 +44,24 @@ Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge
 
 ```diff
 - const txHash: string = await sodax.bridge.bridge({
--   params: { srcAsset, amount, dstChainId, dstAddress, dstAsset },
+-   params: { srcAsset, amount, dstChainId, dstAsset, recipient },
 -   spokeProvider,
 - });
 + const result = await sodax.bridge.bridge({
 +   params: {
 +     srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-+     srcAddress: '0x…',
-+     srcAsset, amount,
++     srcAddress: '0x…',                          // NEW: required (your spoke-side sender)
++     srcToken,                                    // RENAMED from `srcAsset`
++     amount,
 +     dstChainKey: ChainKeys.STELLAR_MAINNET,
-+     dstAddress: 'G…',
-+     dstAsset,
++     dstToken,                                    // RENAMED from `dstAsset`
++     recipient: 'G…',                             // UNCHANGED — destination receiver
 +   },
 +   raw: false,
 +   walletProvider,
 + });
++ // Type: Result<TxHashPair, BridgeOrchestrationError>
++ //       where TxHashPair = { srcChainTxHash: string; dstChainTxHash: string }
 + if (!result.ok) return;
 + const { srcChainTxHash, dstChainTxHash } = result.value;
 ```

package/ai-exported/migration/recipes.md

@@ -1,13 +1,16 @@
 # Migration recipes — v1 → v2
 
-Practical patterns for porting consumer code without rewriting everything in one pass. Three recipes:
+Practical patterns for porting consumer code without rewriting everything in one pass.
 
 1. [Codemod patterns](#1-codemod-patterns) — regex find/replace + a small `ts-morph` script for the renames that grep can't safely handle.
-2. [Error-shape adapter](#2-error-shape-adapter) — adapt v2 `SodaxError` onto v1 `{ code, data }` branches so existing error-formatting helpers keep working.
-3. [Result adapter](#3-result-adapter) — wrap v2 `Result<T>` in a v1-style throw shim for incremental conversion of call sites.
+2. [Free-function lookups at module scope](#2-free-function-lookups-at-module-scope) — `getHubChainConfig()` / `getMoneyMarketConfig()` migration for constants/util files where no `Sodax` instance exists yet.
+3. [Error-shape adapter](#3-error-shape-adapter) — adapt v2 `SodaxError` onto v1 `{ code, data }` branches so existing error-formatting helpers keep working.
+4. [Result adapter](#4-result-adapter) — wrap v2 `Result<T>` in a v1-style throw shim for incremental conversion of call sites.
 
 These are migration-only — once the port is complete, delete them. They're not patterns for new code.
 
+The patterns below describe **what** the rewrite needs to do; pick whichever codemod tool fits your project (regex, `ts-morph`, `jscodeshift`, IDE refactor). The example scripts use `ts-morph` for AST-level rewrites where regex is unsafe.
+
 ---
 
 ## 1. Codemod patterns
@@ -16,12 +19,27 @@ These are migration-only — once the port is complete, delete them. They're not
 
 | Change | Find | Replace | Notes |
 |---|---|---|---|
-| Chain-id constants | `(\w+)_MAINNET_CHAIN_ID` | `ChainKeys.$1_MAINNET` | Mechanical. After: fix `import` statements. |
+| Chain-id constants | `(\w+)_MAINNET_CHAIN_ID` | `ChainKeys.$1_MAINNET` | Mechanical. **Two-pass — see below.** First-pass rewrites usages; second-pass fixes the broken `import { ... }` statements. |
 | `xChainId` field on `XToken` | `\.xChainId\b` | `.chainKey` | Token field rename. Audit first — some non-token types may use `xChainId` differently. |
 | `Token` type rename | `\bimport(.*)\bToken\b(.*)\bfrom 'sodax/types'` | `import$1XToken$2from '@sodax/sdk'` | Best done with `ts-morph` to avoid touching unrelated `Token` identifiers. |
 | `SpokeChainId` → `SpokeChainKey` | `\b(SpokeChainId\|ChainId)\b` (in type positions) | `SpokeChainKey` | Audit — `ChainId` is also used by 3rd-party libs (viem, etc.). Limit to `@sodax/types` imports. |
 | `AddressType` → `BtcAddressType` | `\bAddressType\b` (in `@sodax/types` import positions) | `BtcAddressType` | |
 
+### Two-pass codemod for chain-id constants
+
+A one-pass `_MAINNET_CHAIN_ID` → `ChainKeys.*_MAINNET` rewrite produces invalid syntax inside `import { ... }` blocks — `ChainKeys.SONIC_MAINNET` is a member-access expression, not a bare identifier, and cannot live inside a named-import list (TS1109).
+
+Split the rewrite into two passes:
+
+1. **Pass 1 — rewrite usages.** Every `<X>_MAINNET_CHAIN_ID` → `ChainKeys.<X>_MAINNET`. Touches expression positions and (incorrectly) named-import positions; the broken imports get fixed in pass 2.
+2. **Pass 2 — sweep imports.** For each `import { … } from '@sodax/{types,sdk}'`, drop the now-broken `ChainKeys.<X>_MAINNET` entries from the named-imports list and ensure `ChainKeys` itself is imported once.
+
+Use the `ts-morph` script from the chain-id section above as a starting point for an AST-aware version, or build the two passes with whatever tooling fits your repo. After pass 2, every chain-id reference compiles.
+
+### Pitfall — duplicate `ChainKeys` imports
+
+If a file imports `<X>_MAINNET_CHAIN_ID` from BOTH `@sodax/types` and `@sodax/sdk` (some legacy code split imports across the two), pass 2 may add `ChainKeys` to both import statements → `TS2300 Duplicate identifier 'ChainKeys'`. Either keep `ChainKeys` only in the first import block, or consolidate to one import — `@sodax/sdk` re-exports the entire `@sodax/types` surface, so a single `import … from '@sodax/sdk'` is sufficient.
+
 ### What's not safe to grep-replace
 
 - `srcChain` → `srcChainKey` on **request** types only. Read shapes (`Intent.srcChain`, `IntentResponse.srcChain`) keep `srcChain` as the relay chain id. Use a `ts-morph` script keyed by parameter type.
@@ -95,7 +113,51 @@ The `ts-morph` script above edits in-place. Commit your tree before running.
 
 ---
 
-## 2. Error-shape adapter
+## 2. Free-function lookups at module scope
+
+v1 exported free functions like `getHubChainConfig()` and `getMoneyMarketConfig(chainId)` that consumers called at **module-load time** inside constants/util files — *before* any `Sodax` instance exists. The v2 replacement on `Sodax.config.*` is unusable in that context (chicken-and-egg).
+
+The real v2 answer: read directly from the packaged-default const `sodaxConfig`, re-exported from `@sodax/sdk` (and from `@sodax/types`):
+
+| v1 free function | v2 module-scope equivalent |
+|---|---|
+| `getHubChainConfig()` | `sodaxConfig.hub` |
+| `getMoneyMarketConfig(hubChainId)` | `sodaxConfig.moneyMarket` |
+| `getMoneyMarketConfig(hubChainId).supportedTokens` | `sodaxConfig.moneyMarket.supportedTokens` |
+| `getSolverConfig(SONIC_MAINNET_CHAIN_ID)` (read solver endpoints) | `sodaxConfig.solver` |
+| (none — v1 had no module-scope-safe accessor for full hub object) | `sodaxConfig.hub.addresses.hubWallet`, `.assetManager`, etc. |
+
+```diff
+- // v1 — module-scope constants file (no Sodax instance available yet)
+- import { getHubChainConfig, getMoneyMarketConfig } from '@sodax/sdk';
+- import { SONIC_MAINNET_CHAIN_ID } from '@sodax/types';
+-
+- const hubConfig = { hubRpcUrl, chainConfig: getHubChainConfig() };
+- const moneyMarketConfig = getMoneyMarketConfig(SONIC_MAINNET_CHAIN_ID);
+
++ // v2 — read from packaged defaults; no Sodax instance needed
++ import { sodaxConfig } from '@sodax/sdk';
++
++ const hubAddresses = sodaxConfig.hub.addresses;
++ const moneyMarketTokens = sodaxConfig.moneyMarket.supportedTokens;
+```
+
+> **Once you have a `Sodax` instance**, prefer `sodax.config.*` (`sodax.config.getHubChainConfig()`, `sodax.config.getMoneyMarketReserveAssets()`, etc.). The service-API path reflects backend-driven runtime updates after `await sodax.config.initialize()`; `sodaxConfig` is a packaged-default snapshot frozen at SDK release time.
+
+For hub-only module-scope reads, `hubConfig` is also exported directly:
+
+```ts
+import { hubConfig } from '@sodax/sdk';
+
+const HUB_WALLET = hubConfig.addresses.hubWallet;
+const STAKING_ROUTER = hubConfig.addresses.stakingRouter;
+```
+
+See [`reference/sodax-config.md`](reference/sodax-config.md) § "Pitfall — module-scope reads" for the same guidance in the SodaxConfig reshape doc.
+
+---
+
+## 3. Error-shape adapter
 
 If your consumer code has `getMmErrorText`, `getSwapErrorText`, or similar helpers that branch on a v1 error object's `.code` and `.data.error`, the minimal-change migration is to wrap incoming v2 `SodaxError` instances at the entry point of each helper:
 
@@ -191,7 +253,7 @@ See [`reference/error-code-crosswalk.md`](reference/error-code-crosswalk.md) for
 
 ---
 
-## 3. Result adapter
+## 4. Result adapter
 
 If converting every call site to branch on `result.ok` in one pass isn't realistic, use a `throwIfError` shim during migration. Then convert call sites at your own pace.
 

package/ai-exported/migration/reference/deleted-exports.md

@@ -30,8 +30,9 @@ Two categories worth distinguishing:
 | v1 export | v2 replacement |
 |---|---|
 | `hubAssets` | `XToken.vault` / `XToken.hubAsset` baked in; or `sodax.config.getOriginalAssetAddress(...)`. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 2. |
-| `getHubChainConfig()` (free function) | `sodax.config.getHubChainConfig()` (now a method on `ConfigService`, accessed via the `Sodax` instance). |
+| `getHubChainConfig()` (free function) | `sodax.config.getHubChainConfig()` (now a method on `ConfigService`, accessed via the `Sodax` instance). For module-scope reads (before a `Sodax` instance exists), see [`sodax-config.md`](sodax-config.md) § "Pitfall — module-scope reads". |
 | `EvmWalletAbstraction` (class) | `sodax.hubProvider.getUserHubWalletAddress(...)` (the equivalent functionality lives on `EvmHubProvider`, accessed via the `Sodax` instance). |
+| `HubService` (class) + `HubService.getUserHubWalletAddress(spokeAddress, spokeChainId, hubProvider)` (static method) | `sodax.hubProvider.getUserHubWalletAddress(spokeAddress, spokeChainKey)` (instance method on `EvmHubProvider`; doesn't take `hubProvider` arg — `this` is the hub provider). v1 callers in `dex/AssetService.ts`, `mm/useATokensBalances.ts`, `shared/useGetUserHubWalletAddress.ts` all flatten to this single shape. |
 
 ### Type aliases
 
@@ -41,7 +42,7 @@ Two categories worth distinguishing:
 | `SpokeChainId` (type) | `SpokeChainKey`. |
 | `EvmChainId` (type) | `EvmChainKey` (subset of `SpokeChainKey`). |
 | `HubChainId` (type) | `HubChainKey` (literal `'sonic'`). |
-| `Token` (type) | `XToken`. See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 4. |
+| `Token` (type) | `XToken`. **Fully removed — no legacy alias.** `import type { Token } from '@sodax/types'` fails with `TS2305: '"@sodax/types"' has no exported member named 'Token'. Did you mean 'XToken'?`. The shape also changed (added `vault`, `hubAsset`; renamed `xChainId` → `chainKey`) — see [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 4. |
 | `AddressType` (type — `'P2PKH' \| 'P2SH' \| 'P2WPKH' \| 'P2TR'`) | `BtcAddressType` (renamed; same shape). See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 7. |
 
 > Note: `BtcWalletAddressType` (`'taproot' | 'segwit'`, wallet-UI choice) is preserved in v2 with the same shape — it is **not** the same thing as `BtcAddressType` (on-chain address format). They coexist; do not blindly rename one to the other.
@@ -56,7 +57,7 @@ Two categories worth distinguishing:
 
 | v1 export | v2 replacement |
 |---|---|
-| `CustomProvider` (Hana-wallet window typedecl) | None. Window declaration becomes `unknown` or imports directly from the wallet vendor. Low-level Hana-extension helper functions (`requestAddress`, `requestSigning`, `requestJsonRpc`) ship from `@sodax/sdk` for consumers building their own Hana-based `IIconWalletProvider`. |
+| `CustomProvider` (Hana-wallet window typedecl) | **Pick by what you actually use:** (a) **You only declared `window.hanaWallet.ethereum: CustomProvider` for typedecl quietness, never called methods on it** → replace the type with `unknown` (`declare global { interface Window { hanaWallet: { ethereum: unknown } } }`). 1-line fix. (b) **You called `window.hanaWallet.ethereum.request(...)` or built a custom Hana wallet** → import the named helpers `requestAddress`, `requestSigning`, `requestJsonRpc` from `@sodax/sdk` and use them in place of the raw provider calls. These are the same low-level Hana-extension helpers v1 wrapped, now first-class exports. |
 
 ### Error types and guards
 

package/ai-exported/migration/reference/sodax-config.md

@@ -1,46 +1,137 @@
 # `SodaxConfig` constructor reshape
 
-The v2 `Sodax` constructor accepts a `DeepPartial<SodaxConfig>`. Several config fields renamed or moved between v1 and v2; if your project passed a custom config, check these:
+The v2 `Sodax` constructor accepts a `DeepPartial<SodaxConfig>`. Several config fields renamed, moved, or were added between v1 and v2; if your project passed a custom config, check these.
 
-| v1 location | v2 location |
-|---|---|
-| `SodaxConfig.swaps` (held solver endpoints AND supported tokens) | Split into two: `SodaxConfig.swaps` (now `SwapsConfig` — supported tokens per chain) and `SodaxConfig.solver` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`). |
-| `SodaxConfig.rpcConfig` (flat object: one URL per chain field) | `SodaxConfig.rpcConfig` (mapped type keyed by `ChainKey` values; chain-family-specific shapes — see [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 5). |
-| `SodaxConfig.hubProviderConfig` | Renamed: `SodaxConfig.hubConfig`. |
-| `SodaxConfig.configService` (raw `IConfigApi` instance you injected) | Pass via `new Sodax({ configService: <your impl> })` is gone — `ConfigService` is constructed internally. To inject a custom `IConfigApi`, override via `SodaxConfig.backendApi`. |
+## v2 `SodaxConfig` shape (source of truth)
+
+Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`):
+
+```ts
+type SodaxConfig = {
+  fee: PartnerFee | undefined;                       // global partner fee (overridable per-feature)
+  chains: Record<SpokeChainKey, SpokeChainConfig>;   // per-spoke-chain config (rpcUrl + tx polling + chain-specific shape)
+  swaps: SwapsConfig;                                // supported swap tokens per chain
+  moneyMarket: MoneyMarketConfig;                    // money market service config
+  bridge: BridgeConfig;                              // bridge partner-fee override
+  dex: DexConfig;                                    // DEX service config
+  hub: HubConfig;                                    // hub-chain (Sonic) provider config
+  api: ApiConfig;                                    // backend API endpoint
+  solver: SolverConfig;                              // intent solver endpoint + contracts
+  relay: RelayConfig;                                // intent-relay endpoint
+};
+```
+
+A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<SodaxConfig>` over it.
+
+## v1 shape (for reference)
+
+```ts
+// v1 — packages/sdk/src/shared/entities/Sodax.ts
+type SodaxConfig = {
+  swaps?: SolverConfigParams;                    // { intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }
+  moneyMarket?: MoneyMarketConfigParams;
+  migration?: MigrationServiceConfig;
+  bridge?: BridgeServiceConfig;
+  dex?: DexServiceConfig;
+  hubProviderConfig?: EvmHubProviderConfig;      // { hubRpcUrl, chainConfig }
+  relayerApiEndpoint?: HttpUrl;                  // single URL string
+  backendApiConfig?: BackendApiConfig;
+  partners?: PartnerServiceConfig;
+  sharedConfig?: typeof defaultSharedConfig;
+};
+```
+
+All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxConfig` — RPC URLs were a separate prop accepted by the framework-layer `SodaxProvider` (alongside the `config` prop carrying `SodaxConfig`); the `Sodax` class constructor itself never received `rpcConfig`.
+
+## v1 → v2 field map
+
+| v1 location | v2 location | Notes |
+|---|---|---|
+| `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxConfig.fee` slot or per-feature configs. |
+| `SodaxConfig.hubProviderConfig` (`EvmHubProviderConfig` — `{ hubRpcUrl, chainConfig }`) | **`SodaxConfig.hub`** (`HubConfig` — full hub addresses + native token + bnUSD + polling + RPC URL). | Field renamed `hubProviderConfig` → `hub`. Shape expanded: v1 just had RPC URL + chain config; v2 ships the full hub-contract address map. |
+| `SodaxConfig.moneyMarket` (`MoneyMarketConfigParams`) | `SodaxConfig.moneyMarket` (`MoneyMarketConfig` — required, shape changed). | Reshape, see `@sodax/types/src/common/common.ts` MoneyMarketConfig. |
+| `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. |
+| `SodaxConfig.dex` (`DexServiceConfig`) | `SodaxConfig.dex` (`DexConfig`). | Reshape. |
+| `SodaxConfig.relayerApiEndpoint: HttpUrl` (string) | **`SodaxConfig.relay`** (`RelayConfig` — object with relayer URL + chain-id map). | Renamed + reshaped from string to object. |
+| `SodaxConfig.backendApiConfig` (`BackendApiConfig`) | **`SodaxConfig.api`** (`ApiConfig`). | Renamed. |
+| (Separate `rpcConfig` prop on the framework-layer SodaxProvider, NOT a `SodaxConfig` field) | **`SodaxConfig.chains`** (`Record<SpokeChainKey, SpokeChainConfig>`). | v2 absorbs RPC URLs + polling + chain-specific extras into the `SodaxConfig.chains` mapped type. v1's separate `rpcConfig` provider prop is gone. The standalone `RpcConfig` type still ships from `@sodax/types` for utility use (e.g. the demo's `providers.tsx` declares a local `RpcConfig` then maps values into `chains`), but it is not a `SodaxConfig` field. |
+| `SodaxConfig.migration` (`MigrationServiceConfig`) | **Removed.** Migration service runs with hard-coded defaults. | No replacement on `SodaxConfig`. v2 surfaces customization via per-method params on `sodax.migration.*`, not constructor config — see [`../features/icx-bnusd-baln.md`](../features/icx-bnusd-baln.md). |
+| `SodaxConfig.partners` (`PartnerServiceConfig`) | **Removed.** Partner service runs with defaults. | Per-claim partner-fee config now flows via call-level params on `sodax.partners.*` methods. |
+| `SodaxConfig.sharedConfig` (`typeof defaultSharedConfig`) | **Removed.** | Absorbed into `ConfigService` + per-chain `SpokeChainConfig`. Override individual chains via `SodaxConfig.chains[key]`. |
+| (none in v1) | **`SodaxConfig.fee: PartnerFee \| undefined`** (new). | Global partner-fee, applies to all features unless overridden by feature-level config (`bridge.partnerFee`, money market, etc.). |
+| (v1 had no top-level `configService` injection slot on `SodaxConfig` — `ConfigService` was always constructed internally from `backendApiConfig` + `sharedConfig`.) | Same — `ConfigService` is internal. v2 does **not** expose a typed slot to inject a custom `IConfigApi` either. To swap the backend in tests, point `SodaxConfig.api.baseURL` at a mock server. | See Pitfall below. |
 
 Migration:
 
 ```diff
-  const sodax = new Sodax({
+- // v1 — typical SodaxConfig literal
+- const sodaxConfig = {
+-   hubProviderConfig: { hubRpcUrl: 'https://…', chainConfig: getHubChainConfig() },
+-   moneyMarket: getMoneyMarketConfig(hubChainId),
 -   swaps: {
 -     intentsContract: '0x…',
 -     solverApiEndpoint: 'https://…',
--     supportedTokens: { /* … */ },
+-     protocolIntentsContract: '0x…',
+-     partnerFee: { address: '0x…', percentage: 10 },
 -   },
+-   relayerApiEndpoint: 'https://relay.example.com',
+- } satisfies SodaxConfig;
+- // RPC URLs were passed as a SEPARATE prop on the framework-layer SodaxProvider
+- // (alongside the sodaxConfig). The Sodax constructor itself never saw rpcConfig.
+
++ // v2 — DeepPartial<SodaxConfig> passed directly to new Sodax(...)
++ const sodax = new Sodax({
++   hub: { /* HubConfig — usually omit, default ships full hub addresses */ },
 +   solver: {
 +     intentsContract: '0x…',
 +     solverApiEndpoint: 'https://…',
++     protocolIntentsContract: '0x…',
 +   },
 +   swaps: {
 +     supportedTokens: { /* per-chain table */ },
 +   },
--   rpcConfig: { sonic: 'https://…', arbitrum: 'https://…' },
-+   rpcConfig: {
-+     [ChainKeys.SONIC_MAINNET]: 'https://…',
-+     [ChainKeys.ARBITRUM_MAINNET]: 'https://…',
-+     [ChainKeys.BITCOIN_MAINNET]: { /* BitcoinRpcConfig shape */ },
++   relay: { /* RelayConfig — relayer URL + chain-id map */ },
++   fee: { address: '0x…', percentage: 10 },  // global partner fee (moved out of swaps)
++   chains: {
++     [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://…' },
++     [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://…' },
++     [ChainKeys.BITCOIN_MAINNET]: { /* BitcoinSpokeChainConfig shape */ },
 +     // …
 +   },
--   hubProviderConfig: { /* … */ },
-+   hubConfig: { /* … */ },
-  });
-  await sodax.config.initialize();
++ });
++ await sodax.config.initialize();
 ```
 
+## Per-chain `SpokeChainConfig` shape
+
+`SodaxConfig.chains` is keyed by `SpokeChainKey`; each entry's value type varies by chain family. The user-overridable surface (`rpcUrl`, polling config, chain-specific extras) is the same set of fields `RpcConfig` covers in v1, but nested inside `SpokeChainConfig` rather than flat. Inspect the type at:
+
+- `packages/types/src/chains/chains.ts` — `SpokeChainConfig` discriminated union
+- `packages/types/src/common/common.ts` — `BitcoinRpcConfig`, `StellarRpcConfig`, `InjectiveRpcConfig` (used inside the EVM-non-EVM branches)
+
+See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 5 for the chain-family-specific entry shapes.
+
 ### Pitfall
 
-If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level. Inject a custom `IConfigApi` via `SodaxConfig.backendApi.api` instead — `ConfigService` consumes it internally on `initialize()`.
+If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `IConfigApi`**. The realistic options:
+
+- Point `SodaxConfig.api.baseURL` at a local mock backend server.
+- Construct your own `BackendApiService`-compatible object in your app/test bootstrap and swap it in where you control the `Sodax` instance.
+
+The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for IConfigApi injection.
+
+### Pitfall — module-scope reads
+
+If your code reads hub addresses or default configs **before** the `Sodax` instance exists (module-scope constants), use the re-exported defaults from `@sodax/types` (also flow through `@sodax/sdk` since it re-exports the entire types surface):
+
+```ts
+import { hubConfig, sodaxConfig } from '@sodax/sdk';
+
+const HUB_WALLET = hubConfig.addresses.hubWallet;     // module-scope OK
+const DEFAULT_RELAY = sodaxConfig.relay;              // module-scope OK
+```
+
+`hubConfig` / `sodaxConfig` are the **packaged defaults** — the same values `ConfigService` falls back to if the backend is unreachable. Once you have a `Sodax` instance, prefer `sodax.config.getHubChainConfig()` / `sodax.config.*` so backend-driven updates take effect.
 
 ---
 
@@ -50,3 +141,5 @@ If you previously injected a custom `ConfigService` for testing (a v1 escape hat
 - [`README.md`](README.md) — migration reference index.
 - [`../README.md`](../README.md) — migration overview.
 - [`../checklist.md`](../checklist.md) — top-level migration checklist.
+- [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 5 — per-chain config entry shapes.
+- [`deleted-exports.md`](deleted-exports.md) — `getHubChainConfig()` and other deleted symbols.

package/dist/index.cjs

@@ -3899,7 +3899,7 @@ function isValidWalletProviderForChainKey(chainKey, walletProvider) {
 }
 
 // ../types/dist/index.js
-var CONFIG_VERSION = 200;
+var CONFIG_VERSION = 201;
 function isEvmSpokeChainConfig(value) {
   return typeof value === "object" && value !== null && value.chain.type === "EVM" && value.chain.key !== HUB_CHAIN_KEY;
 }