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

package/ai-exported/migration/recipes/adopt-library-exports.md

@@ -0,0 +1,99 @@
+# Recipe: Adopt `library-exports` (optional cleanup)
+
+Re-import types from `@sodax/wallet-sdk-core` instead of upstream chain SDKs. Optionally drop direct chain-SDK deps from `package.json`.
+
+**Apply when:** the user imports type names like `WalletClient`, `PublicClient`, `Networks`, `PostConditionMode`, `NearConnector`, etc. directly from their upstream packages.
+
+For the full list of re-exported types, see [`../../integration/recipes/library-exports.md`](../../integration/recipes/library-exports.md).
+
+---
+
+## Before
+
+```ts
+import type { WalletClient, PublicClient, TransactionReceipt } from 'viem';
+import { Networks } from '@stellar/stellar-sdk';
+import { PostConditionMode } from '@stacks/transactions';
+import type { WalletAccount, WalletWithFeatures, SuiWalletFeatures } from '@mysten/wallet-standard';
+import type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
+```
+
+## After
+
+```ts
+import type {
+  WalletClient,
+  PublicClient,
+  TransactionReceipt,
+  WalletAccount,
+  WalletWithFeatures,
+  SuiWalletFeatures,
+  Commitment,
+  ConnectionConfig,
+  SendOptions,
+} from '@sodax/wallet-sdk-core';
+
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+---
+
+## Steps
+
+1. **Identify candidate imports.** Run the grep below to find type imports from upstream chain SDKs:
+   ```bash
+   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"
+   # …see ../../integration/recipes/library-exports.md for the full grep list
+   ```
+
+2. **Replace one import statement at a time.** Switch the `from` clause to `@sodax/wallet-sdk-core`. Re-run `pnpm checkTs` after each file.
+
+3. **Check whether the upstream package is still needed for runtime.** If the consumer's only remaining import from `viem` (etc.) is one of the re-exported types, you can drop the dep from `package.json`. If they also import `createPublicClient`, `Connection`, `Transaction`, etc. — keep the dep.
+
+   ```bash
+   grep -rn "from 'viem'" <user-src>   # confirm nothing remains
+   ```
+
+---
+
+## Trade-offs
+
+| Switch | Trade-off |
+|---|---|
+| Type imports | Lossless. Same symbol, different module. |
+| Dep removal (after switching all imports) | Smaller `node_modules`, faster installs. But you re-add the dep if you later need a runtime helper. |
+| Version pinning | After dep removal, you no longer control the chain-SDK version directly — it's locked to whatever SODAX uses. Acceptable for most apps. |
+
+---
+
+## When NOT to adopt
+
+| Scenario | Why skip |
+|---|---|
+| The user is pinned to a specific chain-SDK version different from SODAX's | Adopting library-exports forces SODAX's version. Keep direct imports. |
+| The user imports many runtime symbols (`createPublicClient`, etc.) not in library-exports | Migration churn for limited benefit — they still need the dep. |
+| The user is mid-migration to another chain SDK and library-exports doesn't cover the new one | Wait until library-exports catches up, or just keep the direct dep. |
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. No remaining direct upstream-SDK type imports
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt"
+# expect empty (or kept on purpose with justification)
+
+# 3. Optional: confirm the upstream dep was actually removed
+cat <user>/package.json | jq -r '.dependencies | keys[]'
+```
+
+---
+
+## Why
+
+See [`../breaking-changes/library-exports.md`](../breaking-changes/library-exports.md) for the motivation.

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

@@ -0,0 +1,12 @@
+# Migration reference
+
+Lookup tables. Use these to answer "what was renamed / added / removed" without reading the breaking-change narratives.
+
+| File | Use for |
+|---|---|
+| [`renamed-symbols.md`](./renamed-symbols.md) | Old name → new name. |
+| [`deleted-exports.md`](./deleted-exports.md) | Symbols removed; what to use instead. |
+| [`added-fields.md`](./added-fields.md) | New optional fields you can adopt. |
+| [`return-shapes.md`](./return-shapes.md) | Method return shapes that changed (none currently — placeholder for future). |
+
+For narrative WHY behind each change, see [`../breaking-changes/`](../breaking-changes/).

package/ai-exported/migration/reference/added-fields.md

@@ -0,0 +1,71 @@
+# Added fields and types
+
+Additive changes that older code does not use. All optional — no migration required.
+
+---
+
+## New types
+
+| Type | Chain(s) | Purpose |
+|---|---|---|
+| `EvmWalletDefaults` | EVM | `defaults` slice shape |
+| `EvmSendTransactionPolicy` | EVM | Per-call options shape for `sendTransaction` |
+| `EvmWaitForTransactionReceiptPolicy` | EVM | Per-call options shape for `waitForTransactionReceipt` |
+| `SolanaWalletDefaults` | Solana | `defaults` slice shape |
+| `SuiWalletDefaults` | Sui | `defaults` slice shape |
+| `SuiSignAndExecutePolicy` | Sui | Per-call options for `signAndExecuteTxn` |
+| `SuiGetCoinsPolicy` | Sui | Per-call options for `getCoins` |
+| `BitcoinWalletDefaults` | Bitcoin | `defaults` slice shape |
+| `StellarWalletDefaults` | Stellar | `defaults` slice shape |
+| `IconWalletDefaults` | ICON | `defaults` slice shape |
+| `InjectiveWalletDefaults` | Injective | `defaults` slice shape |
+| `NearWalletDefaults` | NEAR | `defaults` slice shape |
+| `NearTxExecutionStatus` | NEAR | Status union for `waitUntil` default |
+| `StacksWalletDefaults` | Stacks | `defaults` slice shape |
+| `BaseWalletProvider<TDefaults>` | all | Abstract base class (consumers do not subclass) |
+
+---
+
+## New optional fields on existing configs
+
+| Config | Field | Default if omitted |
+|---|---|---|
+| `PrivateKeyEvmWalletConfig` | `defaults?: EvmWalletDefaults` | `{}` |
+| `BrowserExtensionEvmWalletConfig` | `defaults?: EvmWalletDefaults` | `{}` (note: transport/clients in defaults are no-ops here) |
+| `PrivateKeySolanaWalletConfig` | `defaults?: SolanaWalletDefaults` | `{}` |
+| `BrowserExtensionSolanaWalletConfig` | `defaults?: SolanaWalletDefaults` | `{}` |
+| `PrivateKeySuiWalletConfig` | `defaults?: SuiWalletDefaults` | `{}` |
+| `BrowserExtensionSuiWalletConfig` | `defaults?: SuiWalletDefaults` | `{}` |
+| `PrivateKeyBitcoinWalletConfig` | `defaults?: BitcoinWalletDefaults` | `{}` |
+| `BrowserExtensionBitcoinWalletConfig` | `defaults?: BitcoinWalletDefaults` | `{}` |
+| `PrivateKeyStellarWalletConfig` | `defaults?: StellarWalletDefaults` | `{}` |
+| `BrowserExtensionStellarWalletConfig` | `defaults?: StellarWalletDefaults` | `{}` |
+| `PrivateKeyIconWalletConfig` | `defaults?: IconWalletDefaults` | `{}` |
+| `BrowserExtensionIconWalletConfig` | `defaults?: IconWalletDefaults` | `{}` |
+| `SecretInjectiveWalletConfig` | `defaults?: InjectiveWalletDefaults` | `{}` |
+| `BrowserExtensionInjectiveWalletConfig` | `defaults?: InjectiveWalletDefaults` | `{}` |
+| `PrivateKeyNearWalletConfig` | `defaults?: NearWalletDefaults` | `{}` |
+| `BrowserExtensionNearWalletConfig` | `defaults?: NearWalletDefaults` | `{}` |
+| `PrivateKeyStacksWalletConfig` | `defaults?: StacksWalletDefaults` | `{}` |
+| `BrowserExtensionStacksWalletConfig` | `defaults?: StacksWalletDefaults` | `{}` |
+
+---
+
+## New library-exports re-exports
+
+See [`../../integration/recipes/library-exports.md`](../../integration/recipes/library-exports.md) for the full table. Re-exporting these means consumers can drop direct deps on upstream chain SDKs for type-only usage.
+
+Summary:
+
+- **viem** — `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt`
+- **@mysten/sui** — `SuiTransactionBlockResponseOptions`, `Transaction`, `TransactionArgument`
+- **@mysten/wallet-standard** — `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures`
+- **@solana/web3.js** — `Commitment`, `ConnectionConfig`, `SendOptions`
+- **@injectivelabs/*** — `Network`, `ChainId`, `EvmChainId`, `MsgBroadcaster`
+- **@stellar/stellar-sdk** — `Networks` (runtime value)
+- **@stacks/transactions** — `PostConditionMode` (runtime enum), `ClarityValue`, `PostConditionModeName`
+- **@stacks/network** — `StacksNetwork`
+- **@stacks/connect** — `StacksProvider`
+- **near-api-js** — `KeyPairString`
+- **@hot-labs/near-connect** — `NearConnector`
+- **bitcoinjs-lib** — `Network as BitcoinJsNetwork`

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

@@ -0,0 +1,35 @@
+# Deleted exports
+
+**No symbols were deleted from the public surface between v1 and v2.** Every v1 named export is still available on v2's barrel.
+
+If a v1 import does not compile against v2, the cause is most likely:
+
+| Symptom | Likely cause |
+|---|---|
+| `Cannot find module '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` | Deep import from v1's flat layout. Replace with barrel: `from '@sodax/wallet-sdk-core'`. See [`../breaking-changes/folder-layout.md`](../breaking-changes/folder-layout.md). |
+| `'X' has no exported member 'Y'` against `@sodax/sdk` or `@sodax/types` | Not this package. See the corresponding package's migration docs. |
+| Symbol `shallowMerge` not found | Internal in both v1 and v2 (v1 didn't even have it). Use `defaults` config + per-call options. |
+
+---
+
+## Internal symbols (never publicly exported, in any version)
+
+| Symbol | Where it lives | Replacement |
+|---|---|---|
+| `shallowMerge` | `src/utils/merge.ts` (v2 only — did not exist in v1) | Use the `defaults` config + per-call options. Merge is automatic. |
+| `serializeReceipt` | private static on `EvmWalletProvider` | `waitForTransactionReceipt` already returns the serialised shape. |
+| Anything under `src/utils/` | — | Internal. |
+
+If user code deep-imports one of these, it must be replaced with a public API call.
+
+---
+
+## How to verify
+
+```bash
+grep -rn "shallowMerge" <user-src>
+# expect empty
+
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+```

package/ai-exported/migration/reference/renamed-symbols.md

@@ -0,0 +1,31 @@
+# Renamed symbols
+
+**None.** No symbol exported from `@sodax/wallet-sdk-core` was renamed between v1 and v2.
+
+This file exists so AI agents and humans can look up "what was renamed" and get a definitive **nothing**. If you suspect a rename, you are almost certainly looking at the wrong package:
+
+- `@sodax/sdk` — has real v1→v2 renames (e.g. `EvmSpokeProvider` → `EvmSpokeService`).
+- `@sodax/types` — has real v1→v2 renames (e.g. `SONIC_MAINNET_CHAIN_ID` removed in favor of `ChainKeys.SONIC_MAINNET`).
+- `@sodax/wallet-sdk-react` — has real v1→v2 renames (e.g. `useXWagmiStore` removed; `rpcConfig` prop → `config`).
+
+For wallet-sdk-core itself, v1 and v2 share **identical** public type names:
+
+- `EvmWalletConfig`, `PrivateKeyEvmWalletConfig`, `BrowserExtensionEvmWalletConfig`
+- `SolanaWalletConfig`, `PrivateKeySolanaWalletConfig`, `BrowserExtensionSolanaWalletConfig`
+- `SuiWalletConfig`, `PrivateKeySuiWalletConfig`, `BrowserExtensionSuiWalletConfig`
+- `BitcoinWalletConfig`, `PrivateKeyBitcoinWalletConfig`, `BrowserExtensionBitcoinWalletConfig`
+- `StellarWalletConfig`, `PrivateKeyStellarWalletConfig`, `BrowserExtensionStellarWalletConfig`
+- `IconWalletConfig`, `PrivateKeyIconWalletConfig`, `BrowserExtensionIconWalletConfig`
+- `InjectiveWalletConfig`, **`SecretInjectiveWalletConfig`** (note: not `PrivateKey*` — same in v1), `BrowserExtensionInjectiveWalletConfig`
+- `NearWalletConfig`, `PrivateKeyNearWalletConfig`, `BrowserExtensionNearWalletConfig`
+- `StacksWalletConfig`, `PrivateKeyStacksWalletConfig`, `BrowserExtensionStacksWalletConfig`
+
+…and the corresponding provider class names (`EvmWalletProvider`, …).
+
+If a v1 codebase compiles against v2 with no symbol-not-found errors, that is the expected outcome.
+
+---
+
+## What WAS added
+
+See [`added-fields.md`](./added-fields.md) for new types (`*WalletDefaults`, `*Policy` types, `BaseWalletProvider`) and new optional fields (`defaults?`, Stellar's `rpcUrl?`).

package/ai-exported/migration/reference/return-shapes.md

@@ -0,0 +1,23 @@
+# Return shapes
+
+Method return shapes that changed between RC versions.
+
+---
+
+## Currently: no breaking return-shape changes
+
+All provider method return types are stable across the RC series. This file is a placeholder — future return-shape changes will be documented here in the same format used by `@sodax/sdk`'s migration docs (paired before/after shapes per method).
+
+---
+
+## What to check anyway
+
+If you suspect a return shape issue:
+
+```bash
+pnpm checkTs
+```
+
+Any TypeScript error mentioning a `@sodax/wallet-sdk-core` method's return type is most likely (a) propagated from `@sodax/sdk` / `@sodax/types` (which **did** change between v1 and v2), or (b) the consumer is reading a method that **never had** the shape they expect.
+
+For (a), open an issue with the version delta — we'll add it to this file. For (b), see [`../../integration/reference/interfaces.md`](../../integration/reference/interfaces.md) for the authoritative current shape.