@sodax/wallet-sdk-core 1.5.7-beta → 2.0.0-rc.2

package/README.md

@@ -2,6 +2,9 @@
 
 The Sodax wallet-sdk-core is a core wallet SDK package containing implementations of wallet providers that enable multi-chain wallet connectivity. This package provides TypeScript implementations of wallet providers for various blockchain networks, making them compatible with the Core Sodax SDK (@sodax/sdk).
 
+> **AI-friendly docs:** see [`ai-exported/AGENTS.md`](./ai-exported/AGENTS.md) for the agent-readable integration & migration guide.
+> Entry points: [`ai-exported/integration/`](./ai-exported/integration/) (new setup), [`ai-exported/migration/`](./ai-exported/migration/) (upgrading from older RCs).
+
 ## Installation
 
 ```bash
@@ -33,4 +36,231 @@ The package includes wallet provider implementations for:
 - Injective ✅
 - Near ✅
 - Stacks ✅
-- Bitcoin ✅
+- Bitcoin ✅
+
+## Public API surface
+
+The package root exports:
+
+- Wallet providers from `src/wallet-providers/*` (e.g. `EvmWalletProvider`, `SolanaWalletProvider`, `BitcoinWalletProvider`)
+- `library-exports` from `src/types/library-exports.ts` (types and a few runtime values re-exported from upstream chain SDKs)
+
+Internal utilities (e.g. `shallowMerge` in `src/utils/merge.ts`) are **not** exported from the package root.
+
+## Config variants (private key vs browser/extension)
+
+All providers support two modes, but **the union discriminant depends on the provider**:
+
+- **Field presence (no `type` field in config)**: EVM, Solana, Sui, Near, Stacks, Icon, Injective
+- **Explicit uppercase `type` field**: Bitcoin, Stellar (`'PRIVATE_KEY' | 'BROWSER_EXTENSION'`)
+
+### EVM
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+// Private key (Node/scripts/CI)
+const evmPk = new EvmWalletProvider({
+  privateKey: '0x...',
+  chainId: ChainKeys.SONIC_MAINNET,
+  rpcUrl: 'https://...',
+  defaults: {
+    sendTransaction: { gas: 3_000_000n },
+  },
+});
+
+// Browser/extension (consumer supplies viem clients)
+const evmBrowser = new EvmWalletProvider({
+  walletClient: myViemWalletClient,
+  publicClient: myViemPublicClient,
+});
+```
+
+### Solana
+
+```ts
+import { SolanaWalletProvider } from '@sodax/wallet-sdk-core';
+
+const solanaPk = new SolanaWalletProvider({
+  privateKey: new Uint8Array([]),
+  endpoint: 'https://api.mainnet-beta.solana.com',
+});
+
+const solanaBrowser = new SolanaWalletProvider({
+  wallet: {
+    publicKey: myPublicKeyOrNull,
+    signTransaction: mySignTransactionOrUndefined,
+  },
+  endpoint: 'https://api.mainnet-beta.solana.com',
+});
+```
+
+### Bitcoin
+
+```ts
+import { BitcoinWalletProvider } from '@sodax/wallet-sdk-core';
+
+const btcPk = new BitcoinWalletProvider({
+  type: 'PRIVATE_KEY',
+  privateKey: '0x...',
+  network: 'TESTNET',
+  defaults: { defaultFinalize: true },
+});
+
+const btcBrowser = new BitcoinWalletProvider({
+  type: 'BROWSER_EXTENSION',
+  walletsKit: myWalletsKit,
+  network: 'TESTNET',
+});
+```
+
+### Sui
+
+Sui uses `mnemonics` (not `privateKey`) for private-key mode. Browser extension requires a pre-constructed `SuiClient`, wallet object, and active `WalletAccount`.
+
+```ts
+import { SuiWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key (Node/scripts/CI) — field presence discriminant
+const suiPk = new SuiWalletProvider({
+  rpcUrl: 'https://...',
+  mnemonics: '...',
+});
+
+// Browser/extension
+const suiBrowser = new SuiWalletProvider({
+  client: mySuiClient,
+  wallet: myWalletWithFeatures,
+  account: myWalletAccount,
+});
+```
+
+### Stellar
+
+Stellar uses an explicit uppercase `type` field (`'PRIVATE_KEY' | 'BROWSER_EXTENSION'`).
+
+```ts
+import { StellarWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key (Node/scripts/CI)
+const stellarPk = new StellarWalletProvider({
+  type: 'PRIVATE_KEY',
+  privateKey: '0x...',
+  network: 'PUBLIC',
+  rpcUrl: 'https://...',
+});
+
+// Browser/extension
+const stellarBrowser = new StellarWalletProvider({
+  type: 'BROWSER_EXTENSION',
+  walletsKit: myStellarWalletsKit,
+  network: 'PUBLIC',
+});
+```
+
+### Stacks
+
+Stacks discriminates by field presence (no `type` field). The private-key config has `privateKey`; the browser-extension config has `address` (and optionally a `StacksProvider`).
+
+```ts
+import { StacksWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key (Node/scripts/CI)
+const stacksPk = new StacksWalletProvider({
+  privateKey: '...',
+  endpoint: 'https://...',
+});
+
+// Browser/extension
+const stacksBrowser = new StacksWalletProvider({
+  address: 'SP...',
+  endpoint: 'https://...',
+  provider: myStacksProvider,
+});
+```
+
+### ICON
+
+ICON discriminates by field presence. The browser-extension config uses an optional `walletAddress` field (not a client object); `rpcUrl` is required in both modes.
+
+```ts
+import { IconWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key (Node/scripts/CI)
+const iconPk = new IconWalletProvider({
+  privateKey: '0x...',
+  rpcUrl: 'https://...',
+});
+
+// Browser/extension (Hana wallet)
+const iconBrowser = new IconWalletProvider({
+  walletAddress: 'hx...',
+  rpcUrl: 'https://...',
+});
+```
+
+### Injective
+
+Injective discriminates by field presence. The private-key config uses a nested `secret` object that accepts either `{ privateKey }` or `{ mnemonics }` — it is named `SecretInjectiveWalletConfig` rather than `PrivateKey*` to reflect this dual credential shape.
+
+```ts
+import { InjectiveWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key path — via secret credential
+const injectivePk = new InjectiveWalletProvider({
+  secret: { privateKey: '...' },
+  chainId: myChainId,
+  network: myNetwork,
+});
+
+// Mnemonics path — same config shape, different secret variant
+const injectiveMnemonic = new InjectiveWalletProvider({
+  secret: { mnemonics: '...' },
+  chainId: myChainId,
+  network: myNetwork,
+});
+
+// Browser/extension
+const injectiveBrowser = new InjectiveWalletProvider({
+  msgBroadcaster: myMsgBroadcaster,
+});
+```
+
+### NEAR
+
+NEAR discriminates by field presence. The private-key config requires `rpcUrl`, `accountId`, and `privateKey`; the browser-extension config wraps a `NearConnector`.
+
+```ts
+import { NearWalletProvider } from '@sodax/wallet-sdk-core';
+
+// Private key (Node/scripts/CI)
+const nearPk = new NearWalletProvider({
+  rpcUrl: 'https://...',
+  accountId: '...',
+  privateKey: '...',
+});
+
+// Browser/extension
+const nearBrowser = new NearWalletProvider({
+  wallet: myNearConnector,
+});
+```
+
+## Defaults and merge semantics
+
+Each provider accepts optional `defaults`, and most methods accept per-call options. The SDK combines layers using a **shallow merge**:
+
+- Only top-level keys are merged; **nested objects are replaced**, not deep-merged.
+- `undefined` layers are skipped.
+- `undefined` values inside a layer are skipped (so `{ field: undefined }` means “don’t override the previous layer”).
+
+## `library-exports`
+
+`library-exports` re-exports types (and a few runtime values) from underlying chain SDKs so consumers can reduce direct dependencies.
+
+Example:
+
+```ts
+import type { WalletClient, PublicClient } from '@sodax/wallet-sdk-core';
+```

package/ai-exported/AGENTS.md

@@ -0,0 +1,139 @@
+# AGENTS.md — `@sodax/wallet-sdk-core` AI Export
+
+You are a coding agent helping a developer **integrate** or **migrate** the `@sodax/wallet-sdk-core` package. This document is your entry point. Read this first, then route to the right sub-folder.
+
+The files in this `ai-exported/` directory are designed for AI consumption: short, table-heavy, self-contained recipes, and machine-checkable checklists. Human-readable narrative lives in each folder's `README.md`.
+
+---
+
+## What this package is
+
+`@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 (CI tests, indexers, bots).
+- Custom browser flows that don't use React.
+- Tests that need to sign with a deterministic key.
+
+---
+
+## Step 1 — Identify the task
+
+| User says... | Path | Start at |
+|---|---|---|
+| "sign a tx from a script", "instantiate `EvmWalletProvider`", "first time using this lib" | **integration** | `integration/ai-rules.md` |
+| "configure default gas", "set up `defaults`", "shallow merge surprised me" | **integration** | `integration/recipes/defaults-and-overrides.md` |
+| "where do I import `WalletClient` / `SuiClient` from", "avoid direct viem dep" | **integration** | `integration/recipes/library-exports.md` |
+| "upgrade from v1 / sodax-frontend", "bump from older RC" | **migration** | `migration/ai-rules.md` |
+| Deep import from `@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider` broke | **migration** | `migration/breaking-changes/folder-layout.md` |
+| Looking up a provider class or its config shape | direct | `integration/reference/provider-classes.md` |
+| Looking up the discriminated union shape per chain | direct | `integration/features/<chain>.md` |
+
+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** — class names, config-type names, and config shapes are identical. The only mechanical migration is replacing deep imports from v1's flat `wallet-providers/*.ts` layout with barrel imports.
+
+If a project does anything more than that at the wallet-sdk-core surface, you are almost certainly looking at an `@sodax/sdk` / `@sodax/types` migration, not this one. Route accordingly.
+
+---
+
+## Step 2 — Load the right context
+
+**For integration tasks:**
+
+1. `integration/ai-rules.md` — DO/DON'T + workflow + stop conditions
+2. `integration/architecture.md` — mental model (BaseWalletProvider, discriminants, defaults merge)
+3. `integration/quickstart.md` — copy-paste minimal example for the chain you need
+4. `integration/features/<chain>.md` — per-chain config table, methods, gotchas
+5. `integration/recipes/<task>.md` — task-specific guide (setup-private-key, bridge-to-sdk, …)
+6. `integration/reference/*.md` — full barrel exports, interfaces, chain support
+
+**For migration tasks:**
+
+1. `migration/ai-rules.md` — DO/DON'T + workflow. The headline: **v1 code drops in unchanged.** No mandatory edits at the wallet-sdk-core surface.
+2. `migration/README.md` — what (additively) changed, read order, TL;DR
+3. `migration/breaking-changes/*.md` — narrative WHY behind each additive shift (folder layout, base-class, defaults, library-exports)
+4. `migration/reference/*.md` — confirm no renames / no deletions exist
+5. `migration/recipes/<task>.md` — paired before/after for **optional** cleanup (adopt-defaults, adopt-library-exports)
+6. `migration/checklist.md` — verification loop
+
+---
+
+## Step 3 — Honor flow-specific stop conditions
+
+Each flow has its own list of conditions that **HARD STOP** code generation and require asking the user:
+
+- Migration stops → [`migration/ai-rules.md`](./migration/ai-rules.md) § "Stop conditions"
+- Integration stops → [`integration/ai-rules.md`](./integration/ai-rules.md) § "Stop conditions"
+
+Read the relevant list **before** applying any change. When stopping, quote the offending file/line and present the user with concrete options. Do **not** guess.
+
+Cross-flow signals (true regardless of flow):
+
+- User asks for a chain family not in [`integration/reference/chain-support.md`](./integration/reference/chain-support.md). Adding a new chain is a maintainer task, not user-app integration.
+- User wants to extend `BaseWalletProvider` directly. That is a maintainer-only path — confirm scope before writing code.
+
+---
+
+## Step 4 — Verification protocol
+
+After **every** code change you make:
+
+1. Run `pnpm checkTs` from the user's app root (or the package the change touched).
+2. If errors mention `@sodax/wallet-sdk-core`, look up the symbol in `integration/reference/` or `migration/reference/`.
+3. If a symbol isn't in any reference file, **stop and ask**. Do not invent migrations.
+4. After all errors resolve, mark the relevant items in `migration/checklist.md` (for migrations) or move to the next recipe.
+
+You are **done** when:
+- `pnpm checkTs` exits clean for the user's project.
+- All items in `migration/checklist.md` are checked (migration only).
+- The user has confirmed the changed flow works in their dev / test environment.
+
+---
+
+## Conventions in this directory
+
+- **Recipes are self-contained.** A recipe file in `recipes/` contains everything needed to apply the change — before/after code, steps, verification. Do not jump between files.
+- **Reference files are tables.** `reference/*.md` contains markdown tables and paired code blocks. Treat them as lookup, not narrative.
+- **Token budget**: Each file is sized to fit comfortably in your context. If you find yourself loading more than 3 files for a single task, you are probably doing it wrong — re-route via the table above.
+- **Single source of truth**: Behavioral / breaking-change *explanations* live only in `migration/breaking-changes/*.md`. Other files reference them but do not duplicate the prose.
+
+---
+
+## Quick symbol lookup
+
+If the user mentions a symbol you don't recognize, grep these files in order:
+
+```
+integration/reference/public-api.md       — every named export from the package
+integration/reference/provider-classes.md — provider class + config + interface mapping
+integration/reference/interfaces.md       — IXxxWalletProvider method signatures
+integration/reference/chain-support.md    — chain family → provider + dependencies
+migration/reference/renamed-symbols.md    — confirms zero renames between v1 and v2
+migration/reference/deleted-exports.md    — confirms zero deletions between v1 and v2
+migration/reference/added-fields.md       — additive `defaults` / `*WalletDefaults` / `*Policy` types
+```
+
+If still not found: the symbol may be **internal** (not exported from the package root) or **removed**. Ask the user to share the source file/line so you can decide.
+
+---
+
+## Package context
+
+- **Name**: `@sodax/wallet-sdk-core`
+- **Version target**: latest RC / stable on npm.
+- **Peer deps**: none — chain SDKs are direct dependencies and consumers can re-import types via `library-exports`.
+- **Install**: `pnpm add @sodax/wallet-sdk-core`
+- **Runtime**: Node ≥ 18 + browser (tsup `platform: 'neutral'`).
+- **Audience**: backend engineers, script authors, and React-layer authors building higher-level wrappers (`@sodax/wallet-sdk-react`).
+
+---
+
+## Pointers
+
+- [`integration/README.md`](./integration/README.md) — start here for new integrations: file index, recommended reading order, install snippet, dual-config overview.
+- [`migration/README.md`](./migration/README.md) — start here for upgrades: file index, reading order, cross-cutting checklist pointer.
+- [`integration/quickstart.md`](./integration/quickstart.md) — minimal end-to-end example per chain.
+- [`integration/architecture.md`](./integration/architecture.md) — mental model: `BaseWalletProvider`, defaults shallow merge, dual-config discriminants, `library-exports`.
+- [`integration/features/`](./integration/features/) — per-chain config table, methods, gotchas (one file per chain).
+- [`integration/reference/`](./integration/reference/) — public API, provider classes, interfaces, chain support, glossary.
+- [`migration/breaking-changes/`](./migration/breaking-changes/) — narrative WHY behind each version-to-version shift.

package/ai-exported/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 ≥ 18, browser, edge runtimes are all supported (tsup `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/ai-exported/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 < 18**, stop and tell the user — this package requires Node ≥ 18.
+
+**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.