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

package/ai-exported/migration/ai-rules.md

@@ -0,0 +1,139 @@
+# AI Rules — Migration
+
+You are upgrading a user's app from **v1** of `@sodax/wallet-sdk-core` (the legacy `sodax-frontend` codebase) to **v2** (current). The package name did not change. The default expectation is **v1 code drops in unchanged** — there are no mandatory edits at the wallet-sdk-core surface. Follow this protocol exactly.
+
+---
+
+## Workflow (do these in order)
+
+### 1. Survey
+
+Before changing anything, survey the user's project:
+
+```bash
+# 1a. Find every wallet-sdk-core import site
+grep -rn "from '@sodax/wallet-sdk-core'" <user-src>
+
+# 1b. Find every provider construction site
+grep -rnE "new [A-Z][a-zA-Z0-9]*WalletProvider\(" <user-src>
+
+# 1c. Deep imports from src/... — were never supported, now broken
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+
+# 1d. Direct upstream-SDK type imports that library-exports could replace (optional cleanup)
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters|WaitForTransactionReceiptParameters"
+grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+grep -rn "from '@stacks/transactions'" <user-src> | grep -E "PostConditionMode|ClarityValue|PostConditionModeName"
+grep -rn "from '@mysten/wallet-standard'" <user-src>
+grep -rn "from '@solana/web3.js'" <user-src> | grep -E "Commitment|ConnectionConfig|SendOptions"
+
+# 1e. Hand-rolled wrappers around providers (potential candidates for `defaults` adoption)
+grep -rnE "function\s+(make|build|with)[A-Z][a-zA-Z0-9]*Provider" <user-src>
+```
+
+Build a list of every file under each category. Show this list to the user before proceeding.
+
+### 2. Bump the package version
+
+Update `@sodax/wallet-sdk-core` to the v2 target in the user's `package.json`. Run install.
+
+### 3. Type-check the project
+
+```bash
+pnpm checkTs
+```
+
+**Expected outcome: zero errors mentioning `@sodax/wallet-sdk-core` symbols.** v1 code is backwards-compatible with v2.
+
+If errors **do** appear, narrow them:
+
+```bash
+pnpm exec tsc --noEmit 2>&1 | grep -iE "from '@sodax/wallet-sdk-core'|@sodax/wallet-sdk-core/"
+```
+
+For each error:
+
+- **Deep import from `src/...`?** → Replace with barrel import (`from '@sodax/wallet-sdk-core'`). The v2 source layout uses `wallet-providers/<chain>/` folders; old flat paths no longer resolve.
+- **Symbol not found on barrel?** → Look up in [`../integration/reference/public-api.md`](../integration/reference/public-api.md). If genuinely missing, **stop and ask the user** — this is a docs gap or a regression.
+- **Anything else?** → Stop and ask. Do not guess.
+
+### 4. Optional cleanup (only if user requests)
+
+After v3 confirms a green typecheck, the upgrade is **done**. Everything below is optional:
+
+- **Adopt `defaults`** — apply [`recipes/adopt-defaults.md`](./recipes/adopt-defaults.md) only if the user has hand-rolled `make*Provider` / `with*Defaults` wrappers that inject options on every call.
+- **Adopt `library-exports`** — apply [`recipes/adopt-library-exports.md`](./recipes/adopt-library-exports.md) only if the user imports types from upstream chain SDKs and wants to drop those direct deps.
+
+Each is independent. Apply only what the user asked for.
+
+### 5. Verify with the checklist
+
+Loop through every item in [`checklist.md`](./checklist.md). Most items are `grep` commands. Do not skip items. Report results back to the user.
+
+---
+
+## DO
+
+- **DO** read [`breaking-changes/README.md`](./breaking-changes/README.md) once to internalise that v1→v2 is **additive-only**. There is no rename / removal / required-field addition.
+- **DO** start with `pnpm checkTs`. If it passes with zero wallet-sdk-core errors, the upgrade is done.
+- **DO** preserve user comments, formatting, and unrelated code.
+- **DO** treat optional cleanups as **opt-in**, never automatic.
+- **DO** prefer the official `recipes/` over inventing your own structural rewrite.
+
+---
+
+## DO NOT
+
+- **DO NOT** invent breaking changes. If you find yourself rewriting a `*WalletConfig` shape, stop — v1 and v2 shapes are identical. The change is somewhere else (likely `@sodax/sdk` or `@sodax/types`).
+- **DO NOT** rewrite all upstream-SDK imports unprompted. `library-exports` adoption is an optimisation, not a requirement.
+- **DO NOT** rename `PrivateKey<Chain>WalletConfig` → anything else. v1 already used the same names.
+- **DO NOT** rewrite Injective constructions from `{ privateKey }` to `{ secret: { privateKey } }`. v1 already used the `{ secret: { privateKey | mnemonics } }` shape.
+- **DO NOT** "improve" surrounding code (refactor, restyle, add error handling, change variable names).
+- **DO NOT** add `defaults` to existing constructions unless the user explicitly asked for it.
+
+---
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| Any deep import from `@sodax/wallet-sdk-core/src/...` | Never supported. Replace with barrel import; if the symbol is not on the barrel, it is intentionally internal — ask the user what they were doing. |
+| `pnpm checkTs` reports a `@sodax/wallet-sdk-core` symbol that does not exist | Confirm against [`../integration/reference/public-api.md`](../integration/reference/public-api.md). If missing, this is a regression — file an issue. Do not guess a replacement. |
+| User extends `BaseWalletProvider` directly in their code | This class is new in v2 and not intended for consumer subclassing. Confirm scope — maintainer path only. |
+| User imports `shallowMerge` or anything from `@sodax/wallet-sdk-core/utils/...` | Internal in both v1 and v2 (utils didn't even exist in v1). Replace with the `defaults` config or pass merged options at the call site. |
+| `as unknown as` casts around provider construction | Likely a workaround for a previous-RC bug. Investigate — usually safe to remove now. |
+
+When stopping, **quote the file/line** of the offending code and present the user with concrete options.
+
+---
+
+## Verification protocol (after every change)
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. No deep imports from src/
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+
+# 3. No imports of internal utilities
+grep -rn "shallowMerge" <user-src>
+# expect empty
+```
+
+If all three pass and the [`checklist.md`](./checklist.md) is complete, the migration is done.
+
+---
+
+## Done criteria
+
+The migration is complete when:
+
+- [ ] `pnpm checkTs` exits clean.
+- [ ] No deep imports from `@sodax/wallet-sdk-core/src/...`.
+- [ ] No imports of internal utilities (`shallowMerge`).
+- [ ] All items in [`checklist.md`](./checklist.md) are checked.
+- [ ] The user has confirmed at least one signing flow still works in their dev / test environment.
+
+Do not declare the migration done before all five are true.

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

@@ -0,0 +1,14 @@
+# Breaking changes — narrative
+
+One file per change, with the WHY behind it. Use this folder to understand intent; use [`../reference/`](../reference/) for mechanical name lookups; use [`../recipes/`](../recipes/) for paired before/after code.
+
+**Every v1→v2 change at the wallet-sdk-core public surface is additive.** v1 consumer code drops in unchanged.
+
+| File | Change | Action required |
+|---|---|---|
+| [`folder-layout.md`](./folder-layout.md) | Source layout: `wallet-providers/*.ts` (v1, flat) → `wallet-providers/<chain>/*.ts` (v2, folder-per-chain). | Only if user deep-imported `src/...`. Replace with barrel imports. |
+| [`base-wallet-provider.md`](./base-wallet-provider.md) | `BaseWalletProvider<TDefaults>` introduced as shared abstract base. | None — internal. |
+| [`defaults-config.md`](./defaults-config.md) | Every provider accepts an optional `defaults` slice. | None. Optional cleanup: drop hand-rolled default-injection wrappers. |
+| [`library-exports.md`](./library-exports.md) | Upstream chain types re-exported from `@sodax/wallet-sdk-core`. | None. Optional cleanup: drop direct upstream-SDK deps for type-only usage. |
+
+None of these are breaking at the type level. **There are no renames, no removals, no required-field additions.** If you see a v1 `*WalletConfig` symbol that doesn't compile against v2, file an issue — it's a regression, not a documented breaking change.

package/ai-exported/migration/breaking-changes/base-wallet-provider.md

@@ -0,0 +1,52 @@
+# `BaseWalletProvider` introduced
+
+**Additive — no action required.** Older code continues to compile.
+
+---
+
+## What changed
+
+Every provider class now extends a shared abstract base, `BaseWalletProvider<TDefaults>`:
+
+```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 */ }
+}
+```
+
+Older RCs implemented each provider independently — some had ad-hoc default handling, others had none.
+
+## Why
+
+Three reasons to unify:
+
+1. **Predictable merge semantics across chains.** Per-call options now shallow-merge over `defaults` the same way on every provider. No more chain-by-chain surprises.
+2. **One place to add cross-cutting features.** Future helpers (e.g. telemetry hooks, per-call validation) plug in at the base class.
+3. **Single source of truth for `getWalletAddress`.** Subclasses can narrow the return type to a chain-specific brand (`Address`, `IconEoaAddress`, …) without re-declaring the contract.
+
+## Consumer impact
+
+None — the abstract base is a maintainer concern. Consumers continue to:
+
+- Construct `EvmWalletProvider`, `SolanaWalletProvider`, etc. with the same discriminated unions.
+- Pass them via the `IXxxWalletProvider` interface to `@sodax/sdk`.
+
+You should **not** extend `BaseWalletProvider` in user code — see [`../ai-rules.md`](../ai-rules.md) § "Stop conditions".
+
+## How to verify it doesn't affect you
+
+```bash
+pnpm checkTs
+# Should pass without changes if you didn't subclass providers manually.
+```
+
+If a typecheck fails because you previously declared `class Foo extends EvmWalletProvider` and overrode a private method, that override is now invalid — the base class made some helpers `protected`. Ask the user how they want to refactor.

package/ai-exported/migration/breaking-changes/defaults-config.md

@@ -0,0 +1,57 @@
+# `defaults` config added to every provider
+
+**Additive — no action required.** Older code continues to compile.
+
+---
+
+## What changed
+
+Every `*WalletConfig` gained an optional `defaults?: *WalletDefaults` field. Per-call methods accept an `options?: …` parameter that **shallow-merges** over the relevant slice of `defaults`.
+
+```ts
+// Older: explicit options on every call
+const provider = new EvmWalletProvider({ privateKey, chainId });
+await provider.sendTransaction(tx, { gas: 3_000_000n });   // every call needs gas
+
+// Current: encode the default once, override per call when needed
+const provider = new EvmWalletProvider({
+  privateKey,
+  chainId,
+  defaults: { sendTransaction: { gas: 3_000_000n } },
+});
+await provider.sendTransaction(tx);                          // gas applied automatically
+await provider.sendTransaction(tx2, { gas: 5_000_000n });    // override per call
+```
+
+## Why
+
+Three reasons:
+
+1. **Env-level constants belong with construction.** RPC commitment, default gas, default memo are tied to the **environment** (devnet vs mainnet, internal vs public RPC). Embedding them per-call leads to drift.
+2. **Hand-rolled wrappers were the previous workaround.** Older code often had a `makeProvider(opts)` helper that injected defaults at every call site. Now that lives in the provider.
+3. **Type-level safety.** Each chain's `*WalletDefaults` is precisely typed — invalid combinations fail at compile time, not at runtime.
+
+## Merge semantics
+
+| Style | When used | Behavior |
+|---|---|---|
+| `mergePolicy('key', options)` | Defaults grouped per method (EVM, Solana, Sui) | `shallowMerge(defaults.key, options)` |
+| `mergeDefaults(options)` | Defaults are a flat object (Bitcoin, Stellar, ICON, Injective, NEAR, Stacks) | `shallowMerge(defaults, options)` |
+
+Shallow only. Nested objects are **replaced wholesale**, not deep-merged. See [`../../integration/recipes/defaults-and-overrides.md`](../../integration/recipes/defaults-and-overrides.md).
+
+## Consumer impact
+
+| Older pattern | Replacement (optional) |
+|---|---|
+| `await provider.sendTransaction(tx, { gas })` on every call | `defaults: { sendTransaction: { gas } }` once at construction |
+| `function makeEvmProvider(pk) { /* injects gas via closure */ }` | Remove the wrapper; pass `defaults` directly to the constructor |
+| `Object.assign(provider.options, …)` (if hacked into older code) | Mutating internal state is **not** supported. Use `defaults` at construction. |
+
+## How to adopt
+
+Only if you want the cleanup. Apply [`../recipes/adopt-defaults.md`](../recipes/adopt-defaults.md). Skip otherwise — the older per-call style still works.
+
+## Browser-extension caveat
+
+In browser-extension mode the **constructor-time slices** of `defaults` (e.g. EVM's `transport`, `publicClient`, `walletClient`) are **ignored** — the consumer already supplied built clients. A one-time `console.warn` is logged. The method-grouped slices (`sendTransaction`, `waitForTransactionReceipt`, …) still apply.

package/ai-exported/migration/breaking-changes/folder-layout.md

@@ -0,0 +1,99 @@
+# Source folder layout: flat → folder-per-chain
+
+**Affects only deep imports from `src/...`.** Barrel imports (`from '@sodax/wallet-sdk-core'`) are unaffected.
+
+---
+
+## What changed
+
+v1 (`sodax-frontend/packages/wallet-sdk-core`) used a **flat** layout:
+
+```
+src/
+├── index.ts
+└── wallet-providers/
+    ├── index.ts
+    ├── EvmWalletProvider.ts
+    ├── EvmWalletProvider.test.ts
+    ├── BTCWalletProvider.ts
+    ├── SuiWalletProvider.ts
+    ├── IconWalletProvider.ts
+    ├── InjectiveWalletProvider.ts
+    ├── SolanaWalletProvider.ts
+    ├── StellarWalletProvider.ts
+    ├── StacksWalletProvider.ts
+    └── NearWalletProvider.ts
+```
+
+v2 reorganised into a **folder-per-chain** layout, with co-located types and tests:
+
+```
+src/
+├── index.ts
+├── types/                                # NEW — library-exports module
+│   ├── index.ts
+│   └── library-exports.ts
+├── utils/                                # NEW — internal helpers
+│   ├── index.ts
+│   └── merge.ts
+└── wallet-providers/
+    ├── index.ts
+    ├── BaseWalletProvider.ts             # NEW
+    ├── evm/
+    │   ├── index.ts
+    │   ├── EvmWalletProvider.ts
+    │   ├── EvmWalletProvider.test.ts
+    │   └── types.ts
+    ├── bitcoin/                          # new folder; file name kept as BTCWalletProvider.ts
+    │   ├── index.ts
+    │   ├── BTCWalletProvider.ts
+    │   ├── BTCWalletProvider.test.ts
+    │   └── types.ts
+    ├── sui/        { …same shape… }
+    ├── icon/       { …same shape… }
+    ├── injective/  { …same shape… }
+    ├── solana/     { …same shape… }
+    ├── stellar/    { …same shape… }
+    ├── stacks/     { …same shape… }
+    └── near/       { …same shape… }
+```
+
+Class names and barrel exports are **unchanged**. `BitcoinWalletProvider`, `EvmWalletProvider`, etc. live at the same import path:
+
+```ts
+// v1 — works
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+
+// v2 — same, works identically
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+```
+
+## Why
+
+Three reasons to fold each chain into a folder:
+
+1. **Co-located types.** Each chain's `*WalletConfig`, `*WalletDefaults`, `*WalletsKit` types now sit next to the provider that consumes them, in a `types.ts` file — easier to navigate.
+2. **Internal helpers per chain.** Some chains have non-trivial helper functions (ICON's Hana wallet bridge, EVM's chain-key → viem chain map, Bitcoin's PSBT helpers). Folder layout lets those live without polluting a single shared file.
+3. **Future expansion.** Adding a new chain now means dropping a single `src/wallet-providers/<chain>/` folder; the package barrel does not need a corresponding restructure.
+
+## Consumer impact
+
+| User pattern | v1 | v2 |
+|---|---|---|
+| `import { EvmWalletProvider } from '@sodax/wallet-sdk-core'` | ✅ works | ✅ works |
+| `import { BitcoinWalletProvider } from '@sodax/wallet-sdk-core'` | ✅ works | ✅ works |
+| `import … from '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` (deep) | ⚠ never officially supported | ❌ no longer resolves |
+| `import … from '@sodax/wallet-sdk-core/src/wallet-providers/EvmWalletProvider'` (raw src) | ⚠ never officially supported | ❌ no longer resolves |
+
+If user code has deep imports, replace with barrel imports.
+
+## How to verify
+
+```bash
+# No deep imports
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+
+# Type check passes
+pnpm checkTs
+```

package/ai-exported/migration/breaking-changes/library-exports.md

@@ -0,0 +1,58 @@
+# `library-exports` added
+
+**Additive — no action required.** Older code continues to compile.
+
+---
+
+## What changed
+
+`@sodax/wallet-sdk-core` now re-exports a curated set of types (and two runtime values) from each upstream chain SDK:
+
+```ts
+// Now possible
+import type { WalletClient, PublicClient, TransactionReceipt } from '@sodax/wallet-sdk-core';
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+The full list lives at `src/types/library-exports.ts` and in [`../../integration/recipes/library-exports.md`](../../integration/recipes/library-exports.md).
+
+## Why
+
+Consumer apps previously had to list every chain SDK explicitly in `package.json` just to import a few types:
+
+```jsonc
+// Before — direct deps
+{
+  "dependencies": {
+    "@sodax/wallet-sdk-core": "…",
+    "viem": "^2.x",                          // for WalletClient, PublicClient
+    "@stellar/stellar-sdk": "^11.x",          // for Networks
+    "@stacks/transactions": "^6.x",           // for PostConditionMode
+    "@mysten/wallet-standard": "^0.x"         // for WalletAccount, WalletWithFeatures
+  }
+}
+```
+
+Three problems:
+
+1. **Version drift.** Consumer's `viem` could be a different minor than SODAX's, causing type incompatibilities.
+2. **Lockfile churn.** Every chain-SDK bump in SODAX propagated to consumer lockfiles.
+3. **Discoverability.** Consumers had to know which chain SDK each type lived in. The re-export pins types under one familiar namespace.
+
+## Consumer impact
+
+| Older pattern | Replacement (optional) |
+|---|---|
+| `import type { WalletClient } from 'viem'` | `import type { WalletClient } from '@sodax/wallet-sdk-core'` |
+| `import { Networks } from '@stellar/stellar-sdk'` | `import { Networks } from '@sodax/wallet-sdk-core'` |
+| `import { PostConditionMode } from '@stacks/transactions'` | `import { PostConditionMode } from '@sodax/wallet-sdk-core'` |
+
+**If 100% of upstream-SDK usage is covered by `library-exports`**, you can drop the direct chain-SDK dep from `package.json`. Most apps will still need some upstream package (e.g. `viem` for `createPublicClient`, `@solana/web3.js` for `Connection`, …) — adoption is a per-import decision.
+
+## How to adopt
+
+Apply [`../recipes/adopt-library-exports.md`](../recipes/adopt-library-exports.md). Skip if you have no time — the older direct imports still work, just at a small cost in package size and version coupling.
+
+## What is NOT re-exported
+
+The list is curated. Runtime helpers (`createWalletClient`, `Connection`, `Transaction`, `TransactionBuilder`, …) and lesser-used types are **not** included. See [`../../integration/recipes/library-exports.md`](../../integration/recipes/library-exports.md) § "When to NOT use re-exports".

package/ai-exported/migration/checklist.md

@@ -0,0 +1,62 @@
+# Migration checklist
+
+Run through every item before declaring the migration done. Each item is machine-checkable.
+
+---
+
+## Mandatory
+
+- [ ] **No deep imports from `@sodax/wallet-sdk-core/src/…`**
+  ```bash
+  grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+  # expect empty
+  ```
+  v1's flat layout (`wallet-providers/EvmWalletProvider.ts`) no longer resolves under v2's folder-per-chain layout. Only the barrel root is public.
+
+- [ ] **No imports of internal utilities**
+  ```bash
+  grep -rn "shallowMerge" <user-src>
+  # expect empty
+  ```
+  `shallowMerge` is internal in v2 (and didn't exist in v1). Use `defaults` config + per-call options.
+
+- [ ] **`pnpm checkTs` exits clean** with no `@sodax/wallet-sdk-core` symbol errors.
+
+---
+
+## Recommended (optional cleanup)
+
+- [ ] **Drop direct upstream-SDK type imports covered by `library-exports`**
+  ```bash
+  grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters|WaitForTransactionReceiptParameters|HttpTransportConfig|PublicClientConfig|WalletClientConfig"
+  grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+  grep -rn "from '@stacks/transactions'" <user-src> | grep -E "PostConditionMode|ClarityValue|PostConditionModeName"
+  grep -rn "from '@mysten/wallet-standard'" <user-src>
+  grep -rn "from '@solana/web3.js'" <user-src> | grep -E "Commitment|ConnectionConfig|SendOptions"
+  grep -rn "from '@injectivelabs/networks'" <user-src> | grep "Network"
+  grep -rn "from '@injectivelabs/ts-types'" <user-src> | grep -E "ChainId|EvmChainId"
+  grep -rn "from '@injectivelabs/wallet-core'" <user-src> | grep "MsgBroadcaster"
+  grep -rn "from '@hot-labs/near-connect'" <user-src> | grep "NearConnector"
+  grep -rn "from '@stacks/network'" <user-src> | grep "StacksNetwork"
+  grep -rn "from '@stacks/connect'" <user-src> | grep "StacksProvider"
+  # if any matches, decide whether to re-import via @sodax/wallet-sdk-core
+  ```
+
+- [ ] **Direct upstream-SDK deps removed from `package.json`** (only if 100% replaced by library-exports)
+  ```bash
+  cat <user>/package.json | jq -r '.dependencies | keys[]' | grep -E '^(viem|@stellar/stellar-sdk|@stacks/transactions|@mysten/sui|@mysten/wallet-standard|@solana/web3.js|@injectivelabs/networks|@injectivelabs/ts-types|@injectivelabs/wallet-core|@hot-labs/near-connect|@stacks/network|@stacks/connect)$'
+  # confirm each remaining entry is genuinely needed for a runtime symbol library-exports doesn't cover
+  ```
+
+- [ ] **`defaults` adopted in places where wrappers were hand-rolled**
+  Look for ad-hoc wrappers (`makeProvider`, `buildProvider`, `withDefaults`) that injected default gas / commitment / timeout values, and replace them with provider-level `defaults` config.
+
+---
+
+## Verification of behavior
+
+- [ ] **Get-address smoke test** passes for every provider the user constructs.
+- [ ] **One signing flow** runs end-to-end against a testnet (or recorded mock).
+- [ ] **CI passes** (`pnpm lint && pnpm checkTs && pnpm test`).
+
+When all mandatory + behavior items above are checked, the migration is done. Optional items are bonus.

package/ai-exported/migration/recipes/README.md

@@ -0,0 +1,12 @@
+# Migration recipes
+
+Paired before/after for each migration task. Apply only what the user's project triggers.
+
+**There are no mandatory migration recipes for wallet-sdk-core.** v1 consumer code drops in unchanged.
+
+| Recipe | When to apply | Mandatory? |
+|---|---|---|
+| [`adopt-defaults.md`](./adopt-defaults.md) | User has hand-rolled wrappers (`makeProvider`, `buildProvider`, `withDefaults`) that injected default options. | No — additive cleanup. |
+| [`adopt-library-exports.md`](./adopt-library-exports.md) | User imports types directly from upstream chain SDKs that `library-exports` now covers. | No — additive cleanup. |
+
+If the user's only signal is "wallet-sdk-core was bumped to v2", **no recipe is needed**. Run `pnpm checkTs`, verify zero `@sodax/wallet-sdk-core` errors, and stop.

package/ai-exported/migration/recipes/adopt-defaults.md

@@ -0,0 +1,84 @@
+# Recipe: Adopt `defaults` (optional cleanup)
+
+Replace hand-rolled wrappers with provider-level `defaults`. Optional — older per-call style still works.
+
+**Apply when:** the user has a helper like `makeProvider(pk)` or `withDefaults(provider)` that injects fixed options on every call.
+
+---
+
+## Before — hand-rolled wrapper
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import type { EvmRawTransaction } from '@sodax/types';
+import { ChainKeys } from '@sodax/types';
+
+function makeEvmProvider(pk: `0x${string}`) {
+  const provider = new EvmWalletProvider({ privateKey: pk, chainId: ChainKeys.SONIC_MAINNET });
+
+  return {
+    ...provider,
+    sendTransaction(tx: EvmRawTransaction) {
+      // hard-coded gas on every call
+      return provider.sendTransaction(tx, { gas: 3_000_000n });
+    },
+  };
+}
+```
+
+## After — provider-level `defaults`
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const provider = new EvmWalletProvider({
+  privateKey: process.env.EVM_PK as `0x${string}`,
+  chainId: ChainKeys.SONIC_MAINNET,
+  defaults: {
+    sendTransaction: { gas: 3_000_000n },
+  },
+});
+
+// Use directly — defaults apply automatically; per-call override still works.
+await provider.sendTransaction(tx);
+await provider.sendTransaction(tx2, { gas: 5_000_000n });
+```
+
+---
+
+## Steps
+
+1. **Identify the wrapper.** Look for functions that wrap a provider and inject options on every method call.
+2. **Move the injected options into `defaults`.** Pick the right slice — `defaults.sendTransaction` for EVM, `defaults.signAndExecuteTxn` for Sui, flat `defaults` for Bitcoin / Stellar / ICON / Injective / NEAR / Stacks.
+3. **Delete the wrapper.** Replace call sites with direct provider method calls.
+4. **Keep behavior for callers that already pass options.** Per-call options shallow-merge over defaults, so existing call sites that pass `{ gas: 5_000_000n }` still get exactly that gas value.
+
+---
+
+## When NOT to adopt
+
+| Scenario | Why skip |
+|---|---|
+| The wrapper does more than inject defaults (e.g. logging, telemetry, retries) | `defaults` is just a config slice; it can't do behavior wrapping. Keep the wrapper. |
+| The "default" actually changes per call (e.g. dynamic gas estimation) | That's not a default — it's per-call logic. Keep it inline. |
+| The user's code base would gain churn for trivial savings | Migration cost > value. Leave it. |
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Search for remaining hand-rolled wrappers (heuristic)
+grep -rnE "function\s+(make|build|with)(Wallet|Evm|Solana|Sui|Bitcoin|Stellar|Icon|Injective|Near|Stacks)Provider" <user-src>
+# review each — confirm each is justified per the table above
+```
+
+---
+
+## Why
+
+See [`../breaking-changes/defaults-config.md`](../breaking-changes/defaults-config.md) for the model.