@sodax/skills 2.0.0-rc.4

package/knowledge/sdk/migration/reference/sodax-config.md

@@ -0,0 +1,145 @@
+# `SodaxConfig` constructor reshape
+
+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.
+
+## 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
+- // v1 — typical SodaxConfig literal
+- const sodaxConfig = {
+-   hubProviderConfig: { hubRpcUrl: 'https://…', chainConfig: getHubChainConfig() },
+-   moneyMarket: getMoneyMarketConfig(hubChainId),
+-   swaps: {
+-     intentsContract: '0x…',
+-     solverApiEndpoint: 'https://…',
+-     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 */ },
++   },
++   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 */ },
++     // …
++   },
++ });
++ 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 — 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.
+
+---
+
+
+## Cross-references
+
+- [`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/knowledge/wallet-sdk-core/AGENTS.md

@@ -0,0 +1,43 @@
+# Knowledge tree — `@sodax/wallet-sdk-core`
+
+Long-form knowledge supporting the `@sodax/wallet-sdk-core` skills under `@sodax/skills`. The action-oriented entry points are the SKILL.md files in the sibling `skills/` directory:
+
+- New code → `packages/skills/skills/sodax-wallet-sdk-core-integration/SKILL.md`
+- Porting v1 → `packages/skills/skills/sodax-wallet-sdk-core-migration/SKILL.md`
+
+**Don't read this tree top-to-bottom.** Load files from the **Workflow** section of the relevant SKILL.md.
+
+## Package summary
+
+`@sodax/wallet-sdk-core` is the **low-level** wallet layer of the SODAX stack — one provider class per chain family (9 in total: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). Each class accepts either a **private-key** config (server-side scripts, CI, Node) or a **browser-extension** config (consumer dApps with pre-built clients/wallet kits), signs transactions, and broadcasts them.
+
+It is **not** a React layer (that is `@sodax/wallet-sdk-react`) and **not** a hooks layer (that is `@sodax/dapp-kit`). Most React consumers never touch this package directly — they get a typed `IXxxWalletProvider` via `useWalletProvider(...)` and hand it to `@sodax/sdk` calls. Direct usage of `wallet-sdk-core` is the right choice for backend / Node scripts, custom non-React browser flows, and tests that need to sign with a deterministic key.
+
+The package name did **not** change across versions — both v1 and v2 publish as `@sodax/wallet-sdk-core`. All v1 → v2 surface changes are additive (no renames, no deletions). The only mechanical migration is replacing deep imports from v1's flat `wallet-providers/*.ts` layout with barrel imports.
+
+## Layout
+
+```
+knowledge/wallet-sdk-core/
+├── AGENTS.md                  # You are here
+├── integration/               # New code (per-chain provider setup)
+│   ├── README.md
+│   ├── ai-rules.md
+│   ├── architecture.md        # BaseWalletProvider, discriminants, defaults merge
+│   ├── quickstart.md          # Minimal per-chain copy-paste examples
+│   ├── features/              # Per-chain config table, methods, gotchas (9 chains)
+│   ├── recipes/               # setup-private-key, setup-browser-extension, sign-and-broadcast, defaults-and-overrides, library-exports, bridge-to-sdk, testing
+│   └── reference/             # Public API, provider classes, interfaces, chain support, glossary
+└── migration/                 # Additive v1 → v2 (mostly deep-import → barrel cleanup)
+    ├── README.md
+    ├── ai-rules.md
+    ├── checklist.md
+    ├── breaking-changes/      # folder-layout, defaults-config, base-wallet-provider, library-exports
+    ├── recipes/               # adopt-defaults, adopt-library-exports (optional)
+    └── reference/             # added-fields, deleted-exports (empty), renamed-symbols (empty), return-shapes
+```
+
+## Cross-references
+
+- SDK calls: `packages/skills/knowledge/sdk/integration/recipes/raw-tx-flow.md` and `signed-tx-flow.md` show how the wallet provider plugs into `@sodax/sdk` payloads.
+- React equivalent: `packages/skills/knowledge/wallet-sdk-react/` (use `useWalletProvider({ xChainId })` instead of constructing providers directly).

package/knowledge/wallet-sdk-core/integration/README.md

@@ -0,0 +1,108 @@
+# Integration: First-time setup (Human-readable overview)
+
+This folder helps you integrate `@sodax/wallet-sdk-core` into a fresh project — most commonly a Node script, a backend service, or a custom non-React frontend. It is the **human-facing** entry point for new integrations. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first.
+
+If you are upgrading from an older version of the package instead, see `../migration/`.
+
+---
+
+## What this package does
+
+`@sodax/wallet-sdk-core` is a **low-level multi-chain wallet provider layer**. For each of the 9 chain families that SODAX supports it ships **one provider class** that:
+
+- Accepts a **discriminated union config** — `PrivateKey*WalletConfig | BrowserExtension*WalletConfig`.
+- Extends a small `BaseWalletProvider` to merge per-call options over a typed `defaults` shape.
+- Implements the chain-specific `IXxxWalletProvider` interface from `@sodax/types`, so it can be passed straight into `@sodax/sdk` calls.
+
+It is intentionally framework-agnostic — Node ≥ 20.12, browser, edge runtimes are all supported (tsup `esbuildOptions.platform: 'neutral'`).
+
+| Chain family | Provider class | Underlying chain SDK |
+|---|---|---|
+| EVM (12 chains)        | `EvmWalletProvider`       | `viem` |
+| Solana                 | `SolanaWalletProvider`    | `@solana/web3.js` |
+| Sui                    | `SuiWalletProvider`       | `@mysten/sui` + `@mysten/wallet-standard` |
+| Bitcoin                | `BitcoinWalletProvider`   | `bitcoinjs-lib` (+ `ecpair`, `secp256k1`) |
+| Stellar                | `StellarWalletProvider`   | `@stellar/stellar-sdk` |
+| ICON                   | `IconWalletProvider`      | `icon-sdk-js` |
+| Injective              | `InjectiveWalletProvider` | `@injectivelabs/sdk-ts` + `@injectivelabs/wallet-core` |
+| NEAR                   | `NearWalletProvider`      | `near-api-js` + `@hot-labs/near-connect` |
+| Stacks                 | `StacksWalletProvider`    | `@stacks/transactions` + `@stacks/connect` |
+
+---
+
+## Recommended path (in order)
+
+If this is your first time using the package:
+
+1. [`architecture.md`](./architecture.md) — read once before any recipe. Explains `BaseWalletProvider`, the `defaults` shallow-merge model, dual-config discriminants, and the `library-exports` indirection. Picking the wrong config variant is the most common mistake — the mental model prevents it.
+2. [`quickstart.md`](./quickstart.md) — minimal end-to-end example for the chain you need. Copy, edit, run.
+3. [`features/<chain>.md`](./features/) — chain-specific config table, methods, and gotchas (one file per chain).
+4. Pick the right recipes:
+   - [`recipes/setup-private-key.md`](./recipes/setup-private-key.md) — server-side / CI flow.
+   - [`recipes/setup-browser-extension.md`](./recipes/setup-browser-extension.md) — consumer dApp flow.
+   - [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) — hand off the provider to `@sodax/sdk` calls.
+   - [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md) — merge semantics for the `defaults` config.
+   - [`recipes/library-exports.md`](./recipes/library-exports.md) — re-importing upstream chain-SDK types without a direct dep.
+   - [`recipes/sign-and-broadcast.md`](./recipes/sign-and-broadcast.md) — typical send-transaction flow per chain.
+   - [`recipes/testing.md`](./recipes/testing.md) — mocking providers in unit tests.
+5. Reference docs (lookup as needed):
+   - [`reference/public-api.md`](./reference/public-api.md) — every named export from the package root.
+   - [`reference/provider-classes.md`](./reference/provider-classes.md) — provider × config × interface table.
+   - [`reference/interfaces.md`](./reference/interfaces.md) — `IXxxWalletProvider` method signatures.
+   - [`reference/chain-support.md`](./reference/chain-support.md) — chain family → spoke chain keys.
+   - [`reference/glossary.md`](./reference/glossary.md) — terms used across the docs.
+
+---
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-core @sodax/types
+```
+
+Most consumers will also need `@sodax/sdk` (for the hub/spoke services that accept the wallet provider) and one or more chain SDKs (for browser-extension wallet objects). Re-export the types you need via `library-exports` — see [`recipes/library-exports.md`](./recipes/library-exports.md).
+
+---
+
+## Two configuration modes
+
+Every provider class supports **two** construction modes. Picking the wrong one is the most common integration mistake.
+
+| Mode | When to use | Discriminant style |
+|---|---|---|
+| **Private-key** | Node scripts, CI tests, indexers, bots — anywhere you possess the raw key | Either field presence (EVM, Solana, Sui, ICON, Injective, NEAR, Stacks) OR `type: 'PRIVATE_KEY'` (Bitcoin, Stellar) |
+| **Browser-extension** | Consumer dApps where a wallet extension provides a pre-built client / signer | Either field presence (different fields from PK variant) OR `type: 'BROWSER_EXTENSION'` (Bitcoin, Stellar) |
+
+For a chain-by-chain breakdown of the exact discriminant shape, see [`features/`](./features/) and [`architecture.md`](./architecture.md) § "Discriminant variants".
+
+---
+
+## Pair with `@sodax/sdk` and `@sodax/wallet-sdk-react`
+
+The most common stack:
+
+```
+@sodax/sdk              ← business logic (swaps, lending, staking, …)
+@sodax/wallet-sdk-react ← React layer that surfaces a typed IXxxWalletProvider via hooks
+@sodax/wallet-sdk-core  ← this package — concrete provider classes
+@sodax/types            ← shared type definitions
+```
+
+In a React dApp you usually consume this package **indirectly** — `useWalletProvider({ xChainId })` (from `@sodax/wallet-sdk-react`) returns a typed `IXxxWalletProvider` that comes from a `wallet-sdk-core` instance under the hood. You only construct provider classes from `wallet-sdk-core` directly when running scripts, tests, or non-React clients.
+
+---
+
+## Conventions worth knowing
+
+- **`defaults` is optional but powerful.** Every provider accepts a `defaults` config slice; per-call options shallow-merge over it. Use it to encode env-level fixed choices (RPC commitment, default gas, default memo) once.
+- **Shallow merge, not deep.** Nested objects in `defaults` are **replaced wholesale** by per-call options of the same key. See `src/utils/merge.ts` and [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md).
+- **`library-exports` removes upstream deps.** You can `import type { WalletClient } from '@sodax/wallet-sdk-core'` instead of taking a direct dep on `viem`. See [`recipes/library-exports.md`](./recipes/library-exports.md).
+- **The barrel is the source of truth.** Internal utilities (`shallowMerge`, helper functions) are **not** exported. If something isn't on `@sodax/wallet-sdk-core`'s root, do not deep-import it.
+- **No `as unknown as` casts.** The discriminated unions are precise — if TypeScript complains, your config is wrong, not the type.
+
+---
+
+## Getting help
+
+- API surface lookup: [`reference/`](./reference/).
+- Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).

package/knowledge/wallet-sdk-core/integration/ai-rules.md

@@ -0,0 +1,141 @@
+# AI Rules — Fresh Integration
+
+You are integrating `@sodax/wallet-sdk-core` into a user's project for the first time. Follow this protocol exactly.
+
+---
+
+## Workflow (do these in order)
+
+### 1. Survey the project
+
+Before changing anything, gather context:
+
+```bash
+# Runtime — Node script? React dApp? Edge runtime?
+cat <user>/package.json | grep -E '"type|"main|"module'
+
+# Node version — must be >= 18
+cat <user>/.nvmrc 2>/dev/null
+node --version
+
+# Is the user already using @sodax/wallet-sdk-react?
+cat <user>/package.json | grep '"@sodax/wallet-sdk-react'
+
+# Are upstream chain SDKs already direct deps? (may indicate they don't yet know about library-exports)
+cat <user>/package.json | grep -E '"viem"|"@solana/web3.js"|"@mysten/sui"|"@stellar/stellar-sdk"|"@stacks/transactions"|"@injectivelabs"|"near-api-js"|"bitcoinjs-lib"|"icon-sdk-js"'
+```
+
+**If Node < 20.12**, stop and tell the user — this package requires Node ≥ 20.12.
+
+**If the user is already using `@sodax/wallet-sdk-react` in the same project**, ask whether they really need to construct providers directly. In a React app the answer is usually **no**: `useWalletProvider({ xChainId })` returns the typed provider for them. Direct construction is only correct for scripts, tests, or non-React clients.
+
+### 2. Pick the right mode
+
+For **each** chain the user wants to integrate, decide between:
+
+| Mode | When to pick | Stop and ask if... |
+|---|---|---|
+| **Private-key** | A Node script, CI runner, indexer, or test that legitimately possesses a raw key. | The user pastes a real-looking key in a frontend file. Never embed a private key in a browser bundle. |
+| **Browser-extension** | A dApp where a wallet extension (MetaMask, Phantom, Xverse, Hana, Freighter, Leather, …) provides the signing primitives. | The user has neither a key nor a wallet adapter on hand. They probably want `@sodax/wallet-sdk-react` instead. |
+
+Ask the user which mode applies **before** writing code. Default to **private-key** for `apps/node`-style scripts and **browser-extension** for `apps/web`-style dApps.
+
+### 3. Apply the matching recipe
+
+- Private-key flow → [`recipes/setup-private-key.md`](./recipes/setup-private-key.md).
+- Browser-extension flow → [`recipes/setup-browser-extension.md`](./recipes/setup-browser-extension.md).
+
+Each recipe is self-contained — install snippet, config, first method call, verification.
+
+### 4. Hand off to `@sodax/sdk` if needed
+
+If the user wants to swap / bridge / stake / lend / migrate, they need to pass the provider to `@sodax/sdk` calls. Apply [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md). Do not invent your own bridging pattern.
+
+### 5. Add advanced features as separate steps
+
+Only after the basic flow works should you add:
+
+- Default config slices ([`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md))
+- Importing upstream chain types via `library-exports` ([`recipes/library-exports.md`](./recipes/library-exports.md))
+- Sign + broadcast flow for the chain ([`recipes/sign-and-broadcast.md`](./recipes/sign-and-broadcast.md))
+- Mocking providers in tests ([`recipes/testing.md`](./recipes/testing.md))
+
+Each is independent — apply only what the user asked for.
+
+---
+
+## DO
+
+- **DO** use the discriminated union types in your `import` statement so TypeScript narrows the config correctly:
+  ```ts
+  import { EvmWalletProvider, type EvmWalletConfig } from '@sodax/wallet-sdk-core';
+  ```
+- **DO** use chain key constants from `@sodax/types` (`ChainKeys.SONIC_MAINNET`, `ChainKeys.BSC_MAINNET`, …) instead of magic numbers / strings.
+- **DO** re-export upstream chain types via `library-exports` (`import type { WalletClient } from '@sodax/wallet-sdk-core'`) — keeps direct chain-SDK deps out of `package.json`.
+- **DO** pass an `IXxxWalletProvider` (the **interface** from `@sodax/types`), not the concrete class, to SDK calls. Interfaces are how the SDK stays decoupled from this package.
+- **DO** put RPC URLs, network selectors, default gas, etc. in the `defaults` config slice — one place, one source of truth.
+- **DO** consult [`features/<chain>.md`](./features/) for the chain you are integrating before writing the constructor call. Each chain has slightly different field names.
+
+---
+
+## DO NOT
+
+- **DO NOT** embed a private key in a frontend bundle. Browser-extension config exists for a reason.
+- **DO NOT** import from `@sodax/wallet-sdk-core/src/...` deep paths. Only the package root is public.
+- **DO NOT** deep-import the internal `shallowMerge` from `src/utils/merge.ts`. It is intentionally not exported.
+- **DO NOT** extend `BaseWalletProvider` in user code unless you are adding a brand-new chain to this package. That is a maintainer-only path.
+- **DO NOT** widen the discriminated union with a cast (e.g. `as EvmWalletConfig`). If TypeScript complains, your fields are wrong — fix the fields.
+- **DO NOT** mutate `defaults` after construction. Providers freeze the `defaults` reference; later mutations are silently ignored.
+- **DO NOT** mix discriminant styles for a chain. Bitcoin and Stellar **require** an uppercase `type: 'PRIVATE_KEY' | 'BROWSER_EXTENSION'`; every other chain uses **field presence**. See [`architecture.md`](./architecture.md) § "Discriminant variants".
+
+---
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User asks for a chain family not in [chain support](./reference/chain-support.md) | Adding a new chain is a maintainer task, not user-app integration. |
+| User wants to extend `BaseWalletProvider` directly | Maintainer-only path. Confirm scope first. |
+| User wants to deep-merge `defaults` with per-call options | Not supported — merge is **shallow** by design. See [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md). If the user really needs deep merge, they must combine before passing. |
+| User wants to inject a custom `Transport` / `Connection` / `SuiClient` in private-key mode | Some chains expose this via `defaults`; others don't. Check the chain's [feature file](./features/) first. |
+| User wants to use a wallet brand the chain SDK does not support | Out of scope — wallet brand support lives in the upstream chain SDK / kit. |
+| User is in a React app and wants to construct providers in components | Almost always wrong. Direct user to `@sodax/wallet-sdk-react`'s `useWalletProvider` hook. |
+| User asks "how do I sign with X without a key and without an extension" | They probably want a custom signer — this package does not currently model that. Flag as out of scope. |
+
+When stopping, **quote the file/line** of the offending code and present the user with concrete options.
+
+---
+
+## Verification protocol (after every recipe)
+
+```bash
+# 1. Type check passes
+pnpm checkTs
+
+# 2. No deep imports
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty — only barrel imports allowed
+
+# 3. No direct upstream chain-SDK imports for types that library-exports provides
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt"
+# if any match, suggest re-importing via @sodax/wallet-sdk-core
+
+# 4. Sample call works
+# (manual — run a one-shot sign + broadcast on testnet)
+```
+
+If steps 1–3 pass and the user confirms step 4, the recipe is done.
+
+---
+
+## Done criteria
+
+The integration is complete when:
+
+- [ ] `pnpm checkTs` exits clean.
+- [ ] The user has at least one provider instance constructed via the correct discriminated union variant.
+- [ ] Types are imported from `@sodax/wallet-sdk-core` (and `@sodax/types`) only — no deep paths.
+- [ ] If using `@sodax/sdk`: the provider is passed via the `IXxxWalletProvider` interface, not the concrete class.
+- [ ] A sign + broadcast (or get-address) call has succeeded against testnet or a local mock.
+
+Do not declare integration done before all of the above are true.

package/knowledge/wallet-sdk-core/integration/architecture.md

@@ -0,0 +1,212 @@
+# Architecture — Mental Model
+
+This file explains **why** `@sodax/wallet-sdk-core` is shaped the way it is. Read it once before applying recipes — knowing the model lets you handle ambiguous user code without guessing.
+
+If you are looking for "how do I do X", go to [`recipes/`](./recipes/) or [`features/`](./features/). This file is purely conceptual.
+
+---
+
+## The shape of the package
+
+`@sodax/wallet-sdk-core` is a **uniform low-level wallet layer over heterogeneous chain SDKs**. For each of the 9 chain families that SODAX supports, the package ships:
+
+1. A `*WalletProvider` **class** that implements a chain-specific interface (`IEvmWalletProvider`, `ISolanaWalletProvider`, …) imported from `@sodax/types`.
+2. A discriminated-union **config type** (`*WalletConfig = PrivateKey* | BrowserExtension*`).
+3. A `*WalletDefaults` type — the per-method default option shape merged into each call.
+
+Each provider class extends a small abstract `BaseWalletProvider<TDefaults>`. That base holds the `defaults` reference and exposes two helpers:
+
+- `mergePolicy(key, options)` — shallow-merges per-call options over `defaults[key]`. Used when defaults are grouped per method (e.g. `defaults.sendTransaction`).
+- `mergeDefaults(options)` — shallow-merges per-call options over the entire flat `defaults`. Used when defaults are not grouped.
+
+Subclasses do three things on top:
+
+1. Declare a `chainType` literal (`'EVM' as const`, `'BITCOIN' as const`, …).
+2. Discriminate the config and initialize chain-specific state (viem client, Solana `Connection`, `SuiClient`, …).
+3. Implement the chain-specific interface methods (`sendTransaction`, `signTransaction`, …).
+
+Consumers only ever see the public surface: construct the class with one of the union variants, call its methods, and hand the instance to `@sodax/sdk` via its `IXxxWalletProvider` interface.
+
+---
+
+## File-system tour
+
+```
+src/
+├── index.ts                          # Barrel: re-exports wallet-providers + types
+├── types/
+│   ├── index.ts                      # Re-exports library-exports
+│   └── library-exports.ts            # Re-exported types (and a few enums) from upstream chain SDKs
+├── utils/                            # Internal — shallowMerge; NOT re-exported
+│   ├── index.ts
+│   ├── merge.ts
+│   └── merge.test.ts
+└── wallet-providers/
+    ├── index.ts                      # Barrel: re-exports every provider folder
+    ├── BaseWalletProvider.ts         # Abstract base class
+    ├── evm/
+    │   ├── EvmWalletProvider.ts
+    │   ├── EvmWalletProvider.test.ts
+    │   ├── types.ts
+    │   └── index.ts
+    ├── solana/   { …same shape… }
+    ├── sui/      { …same shape… }
+    ├── bitcoin/  { …same shape… }
+    ├── stellar/  { …same shape… }
+    ├── icon/     { …same shape… }
+    ├── injective/{ …same shape… }
+    ├── near/     { …same shape… }
+    └── stacks/   { …same shape… }
+```
+
+Three things to internalize:
+
+1. **The package root is the only public surface.** `src/utils/*` is internal — `shallowMerge` etc. are deliberately not re-exported.
+2. **Each chain is folder-isolated.** Adding a new chain means creating a folder under `src/wallet-providers/<chain>/` and listing it in `wallet-providers/index.ts`. Nothing else changes.
+3. **`types/library-exports.ts` is the indirection point** between upstream chain SDKs and consumers. Re-exporting from here means consumer apps don't need direct deps on `viem`, `@mysten/sui`, etc. for type-only usage.
+
+---
+
+## `BaseWalletProvider` and the `defaults` model
+
+```ts
+abstract class BaseWalletProvider<TDefaults extends object> {
+  protected readonly defaults: TDefaults;
+
+  constructor(defaults: TDefaults | undefined) {
+    this.defaults = (defaults ?? {}) as TDefaults;
+  }
+
+  abstract getWalletAddress(): Promise<string>;
+
+  protected mergePolicy<K extends keyof TDefaults>(key: K, options?: …): … { /* shallowMerge */ }
+  protected mergeDefaults(options?: Partial<TDefaults>): TDefaults { /* shallowMerge */ }
+}
+```
+
+Three rules govern the `defaults` model:
+
+1. **Every field of `TDefaults` is optional.** The constructor falls back to `{}` if the consumer omits `defaults` entirely. Required fields would silently arrive as `undefined` at runtime without TypeScript catching it — see the JSDoc comment in `BaseWalletProvider.ts`.
+2. **Merge is shallow.** Top-level keys merge; nested objects are **replaced wholesale**. If `defaults.sendTransaction = { gas: 3_000_000n, nonce: 0 }` and the caller passes `{ gas: 5_000_000n }`, the merged policy is `{ gas: 5_000_000n }` — `nonce` is dropped. See `src/utils/merge.ts`. The behaviour is intentional: deep merge would silently smuggle stale fields across call sites.
+3. **`undefined` layers and `undefined` values are skipped.** Passing `{ field: undefined }` does **not** override an earlier layer — the merge treats `undefined` as "no opinion".
+
+Two helpers exist because chains group their defaults differently:
+
+- **Per-method grouping** — `mergePolicy('sendTransaction', options)` looks up `defaults.sendTransaction` and merges `options` over it. Used by EVM (`sendTransaction`, `waitForTransactionReceipt`), Sui (`signAndExecuteTxn`, `getCoins`).
+- **Flat grouping** — `mergeDefaults(options)` merges `options` over the whole `defaults` object. Used by chains whose `defaults` is a flat record (Bitcoin's `{ defaultFinalize }`, Stellar's `{ pollInterval, pollTimeout, networkPassphrase }`).
+
+For a concrete worked example see [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md).
+
+---
+
+## Discriminant variants
+
+Every chain supports two construction modes — but the discriminant **looks different per chain**. The rule of thumb:
+
+| Discriminant style | Chains | Example |
+|---|---|---|
+| **Field presence** (no `type` field) | EVM, Solana, Sui, ICON, Injective, NEAR, Stacks | EVM: `privateKey + chainId` → private-key. `walletClient + publicClient` → browser-extension. |
+| **Explicit uppercase `type`** | Bitcoin, Stellar | `{ type: 'PRIVATE_KEY', … }` vs `{ type: 'BROWSER_EXTENSION', … }` |
+
+Why the inconsistency: the field-presence form is shorter for the common case but only works when the two variants share **zero** required-field overlap. Bitcoin and Stellar have shared required fields (`network`, `walletsKit` shapes that overlap with PK fields) that would make field presence ambiguous, so they use explicit `type`.
+
+Two more wrinkles to know about:
+
+- **Sui uses `mnemonics`, not `privateKey`.** The library derives an Ed25519 keypair from the mnemonic phrase. There is no raw-secret-key option.
+- **Injective uses a nested `secret` object.** Because Injective can be constructed from **either** a private key **or** a BIP-39 mnemonic, the private-key variant nests credentials under `secret: { privateKey } | { mnemonics }` instead of placing them at the top level. The type is named `SecretInjectiveWalletConfig` (not `PrivateKey*`) to reflect this.
+
+For chain-by-chain breakdowns see [`features/`](./features/).
+
+---
+
+## `library-exports` — the upstream-SDK indirection
+
+`src/types/library-exports.ts` re-exports a curated set of types (and a few runtime values) from each upstream chain SDK:
+
+```ts
+// viem types
+export type { Account, Address, Chain, Transport, PublicClient, WalletClient,
+              HttpTransportConfig, PublicClientConfig, WalletClientConfig,
+              SendTransactionParameters, WaitForTransactionReceiptParameters,
+              TransactionReceipt } from 'viem';
+
+// Sui types
+export type { SuiTransactionBlockResponseOptions } from '@mysten/sui/client';
+export type { Transaction, TransactionArgument } from '@mysten/sui/transactions';
+export type { SuiWalletFeatures, WalletAccount, WalletWithFeatures } from '@mysten/wallet-standard';
+
+// Solana types
+export type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
+
+// Injective types
+export type { Network } from '@injectivelabs/networks';
+export type { ChainId, EvmChainId } from '@injectivelabs/ts-types';
+export type { MsgBroadcaster } from '@injectivelabs/wallet-core';
+
+// Stellar (also re-exports the `Networks` runtime value)
+export { Networks } from '@stellar/stellar-sdk';
+
+// Stacks (also re-exports the `PostConditionMode` enum)
+export { PostConditionMode } from '@stacks/transactions';
+export type { ClarityValue, PostConditionModeName } from '@stacks/transactions';
+export type { StacksNetwork } from '@stacks/network';
+export type { StacksProvider } from '@stacks/connect';
+
+// Near
+export type { KeyPairString } from 'near-api-js';
+export type { NearConnector } from '@hot-labs/near-connect';
+
+// Bitcoin
+export type { Network as BitcoinJsNetwork } from 'bitcoinjs-lib/src/networks.js';
+```
+
+Consumers can import the types they need directly from `@sodax/wallet-sdk-core` instead of adding `viem`, `@mysten/sui`, etc. to their `package.json`:
+
+```ts
+import type { WalletClient, PublicClient, TransactionReceipt } from '@sodax/wallet-sdk-core';
+```
+
+Note the file name: `library-exports`, not `library-types`. It deliberately re-exports a small number of **runtime** values (`Networks`, `PostConditionMode`) — hence the broader name.
+
+For the typical reasons to use it (and when not to), see [`recipes/library-exports.md`](./recipes/library-exports.md).
+
+---
+
+## The `IXxxWalletProvider` interface — your handoff to `@sodax/sdk`
+
+Each provider class implements a chain-specific interface from `@sodax/types`:
+
+```ts
+class EvmWalletProvider extends BaseWalletProvider<EvmWalletDefaults> implements IEvmWalletProvider { … }
+class BitcoinWalletProvider extends BaseWalletProvider<BitcoinWalletDefaults> implements IBitcoinWalletProvider { … }
+// …and so on
+```
+
+When you call `@sodax/sdk` methods, the SDK expects the **interface**, not the concrete class:
+
+```ts
+import type { IEvmWalletProvider } from '@sodax/types';
+
+async function deposit(evmProvider: IEvmWalletProvider) { /* … */ }
+
+const evm = new EvmWalletProvider({ … });
+await deposit(evm);  // ✅ EvmWalletProvider implements IEvmWalletProvider
+```
+
+This indirection is how the SDK stays decoupled from `wallet-sdk-core`. In a React app, `useWalletProvider({ xChainId })` from `@sodax/wallet-sdk-react` returns the interface directly — the React layer constructs the concrete class internally.
+
+For the full interface signatures, see [`reference/interfaces.md`](./reference/interfaces.md).
+
+---
+
+## Things that look weird until you know why
+
+- **`InjectiveWalletConfig` is `BrowserExtensionInjectiveWalletConfig | SecretInjectiveWalletConfig`** — note the `Secret*` (not `PrivateKey*`) name. It also accepts mnemonics, hence the broader name. See [`features/injective.md`](./features/injective.md).
+- **EVM in browser-extension mode ignores `defaults.transport`, `defaults.publicClient`, and `defaults.walletClient`.** Because the consumer supplied pre-built clients, these defaults are no-ops — the provider logs a one-time `console.warn`. Pass them only in private-key mode. See `EvmWalletProvider.ts`.
+- **HyperEVM is defined inside this package.** `viem/chains` does not ship a HyperEVM config, so `wallet-providers/evm/EvmWalletProvider.ts` exports a `hyper` chain object via `defineChain`. You shouldn't need to import it directly — `getEvmViemChain(ChainKeys.HYPEREVM_MAINNET)` returns it.
+- **`getEvmViemChain(key)` is exhaustively typed.** The default branch is a `never`-assertion — if `@sodax/types` adds a new `EvmChainKey` value, this function fails to typecheck until the case is added. That's by design.
+- **Sui browser-extension mode requires THREE objects** — `client`, `wallet`, and `account`. Many wallet adapters expose the first two but not the third. See [`features/sui.md`](./features/sui.md).
+- **Stellar requires `rpcUrl` in both modes** (technically optional, but defaults to a public RPC). Use a private RPC for production.
+- **Bitcoin in private-key mode also takes an optional `addressType`** (P2WPKH / P2TR / …). Browser-extension mode infers it from the wallet kit.
+
+Everything else is covered by [`features/`](./features/) on a per-chain basis.