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

package/ai-exported/integration/recipes/testing.md

@@ -0,0 +1,163 @@
+# Recipe: Testing — mocking providers
+
+Patterns for unit-testing code that consumes `IXxxWalletProvider` interfaces. The same approach scales to integration tests against testnets.
+
+**Depends on:** [`bridge-to-sdk.md`](./bridge-to-sdk.md) — your code should already type its functions against the interface, not the class.
+
+---
+
+## Pattern 1 — Type the function signature on the interface
+
+Make the function under test accept the interface, not the concrete class:
+
+```ts
+// ✅ Testable — accept the interface
+import type { IEvmWalletProvider } from '@sodax/types';
+
+export async function depositFlow(wallet: IEvmWalletProvider, amount: bigint) {
+  const addr = await wallet.getWalletAddress();
+  // …
+}
+```
+
+Mock the interface in the test:
+
+```ts
+import { describe, it, expect, vi } from 'vitest';
+import type { IEvmWalletProvider } from '@sodax/types';
+import { depositFlow } from '../depositFlow';
+
+describe('depositFlow', () => {
+  it('uses the address from the provider', async () => {
+    const mockProvider: IEvmWalletProvider = {
+      chainType: 'EVM',
+      getWalletAddress: vi.fn(async () => '0xabc' as const),
+      sendTransaction:  vi.fn(async () => '0xdeadbeef'),
+      waitForTransactionReceipt: vi.fn(async () => ({ /* … */ } as any)),
+      publicClient: undefined as never,                           // not used in this test
+    };
+
+    await depositFlow(mockProvider, 100n);
+    expect(mockProvider.getWalletAddress).toHaveBeenCalled();
+  });
+});
+```
+
+> Test files are the **only** place where `as any` / `as unknown as` casts should be tolerated — production code paths should rely on the discriminated unions instead.
+
+---
+
+## Pattern 2 — Use the real provider against a local key
+
+For end-to-end logic tests, construct a real provider with a deterministic key — no mocking, no network calls:
+
+```ts
+import { describe, it } from 'vitest';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const TEST_PK = '0x' + 'ab'.repeat(32) as `0x${string}`;          // dev-only key
+
+describe('EvmWalletProvider', () => {
+  it('derives the address from the private key', async () => {
+    const provider = new EvmWalletProvider({
+      privateKey: TEST_PK,
+      chainId: ChainKeys.SONIC_MAINNET,
+    });
+    const addr = await provider.getWalletAddress();
+    expect(addr).toMatch(/^0x[a-fA-F0-9]{40}$/);
+  });
+});
+```
+
+`getWalletAddress` doesn't hit the network — viem derives the EOA from the key in-process.
+
+---
+
+## Pattern 3 — Stub the upstream chain SDK with `vi.mock`
+
+When you can't avoid testing the bits that **do** hit the network (sending, polling), stub the upstream chain SDK:
+
+```ts
+import { vi } from 'vitest';
+
+vi.mock('viem', async (importActual) => {
+  const actual = await importActual<typeof import('viem')>();
+  return {
+    ...actual,
+    createWalletClient: vi.fn(() => ({
+      sendTransaction: vi.fn(async () => '0xfakehash'),
+      account: { address: '0xabc' as const },
+      // …
+    })),
+    createPublicClient: vi.fn(() => ({
+      waitForTransactionReceipt: vi.fn(async () => mockReceipt),
+    })),
+  };
+});
+```
+
+This isolates the test from the network without rewriting the provider. The downside is that you're now testing your mock; reserve this pattern for cases where pattern 1 isn't enough.
+
+---
+
+## Pattern 4 — Run against a testnet (true integration)
+
+For real end-to-end coverage, use a testnet (Sonic Testnet, Solana Devnet, BTC Testnet, etc.) and a CI-managed key:
+
+```ts
+// vitest.config.ts — gate behind an env flag so devs don't accidentally run it
+test: {
+  exclude: process.env.RUN_E2E ? [] : ['**/*.e2e.test.ts'],
+},
+```
+
+```ts
+// foo.e2e.test.ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const PK = process.env.E2E_EVM_PK as `0x${string}`;
+const RPC = process.env.E2E_EVM_RPC;
+
+describe.skipIf(!PK)('e2e — EVM testnet', () => {
+  it('sends a 0-value tx', async () => {
+    const provider = new EvmWalletProvider({ privateKey: PK, chainId: ChainKeys.SONIC_MAINNET, rpcUrl: RPC });
+    const hash = await provider.sendTransaction({ to: '0x…', value: 0n, data: '0x' });
+    expect(hash).toMatch(/^0x[a-fA-F0-9]{64}$/);
+  }, 60_000);
+});
+```
+
+`apps/node/src/tests/` in this repo follows this pattern — see those test files for live examples.
+
+---
+
+## What NOT to test
+
+| Test idea | Why skip | Alternative |
+|---|---|---|
+| The merge semantics of `defaults` | Already covered by `src/utils/merge.test.ts` in this package | Trust the merge; test your **policy** values are right |
+| viem's `sendTransaction` semantics | Not your code | Mock at pattern 3 if you need to assert your provider passes args through |
+| Wallet-extension UI flows in unit tests | Browser-only | Use Playwright / Cypress against a real extension build |
+
+---
+
+## Verification
+
+```bash
+pnpm test
+pnpm checkTs
+```
+
+```bash
+# Confirm test files use the interface, not the class, for type annotations
+grep -rn "IEvmWalletProvider\|ISolanaWalletProvider\|IBitcoinWalletProvider" <user-src>/**/*.test.ts
+```
+
+---
+
+## See also
+
+- `src/utils/merge.test.ts` — reference test style for utility-level tests in this package.
+- Every `src/wallet-providers/*/`*`WalletProvider.test.ts` file — provider-level test patterns.

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

@@ -0,0 +1,13 @@
+# Reference
+
+Lookup tables. Use these to answer "what does X look like" without reading source.
+
+| File | Use for |
+|---|---|
+| [`public-api.md`](./public-api.md) | Every named export from `@sodax/wallet-sdk-core`. |
+| [`provider-classes.md`](./provider-classes.md) | Class × config × interface × default-merge-helper matrix. |
+| [`interfaces.md`](./interfaces.md) | `IXxxWalletProvider` method signatures (sourced from `@sodax/types`). |
+| [`chain-support.md`](./chain-support.md) | Chain family → spoke chain keys + provider. |
+| [`glossary.md`](./glossary.md) | Terms used across the docs. |
+
+All files in this directory are intentionally **terse and table-heavy** — for narrative explanations see [`../architecture.md`](../architecture.md) and the per-chain [`../features/`](../features/) files.

package/ai-exported/integration/reference/chain-support.md

@@ -0,0 +1,65 @@
+# Chain support
+
+Chain families and spoke chain keys this package can sign for. Keys live in `@sodax/types`.
+
+---
+
+## EVM (one provider, 12 chains)
+
+`EvmWalletProvider` covers every EVM spoke chain via `getEvmViemChain()`. The provider is exhaustive — adding a new `EvmChainKey` to `@sodax/types` requires updating `getEvmViemChain` (caught at compile time via a `never` assertion in the default branch).
+
+| Spoke chain key | viem chain |
+|---|---|
+| `ChainKeys.SONIC_MAINNET` (hub) | `sonic` |
+| `ChainKeys.ETHEREUM_MAINNET` | `mainnet` |
+| `ChainKeys.ARBITRUM_MAINNET` | `arbitrum` |
+| `ChainKeys.BASE_MAINNET` | `base` |
+| `ChainKeys.BSC_MAINNET` | `bsc` |
+| `ChainKeys.OPTIMISM_MAINNET` | `optimism` |
+| `ChainKeys.POLYGON_MAINNET` | `polygon` |
+| `ChainKeys.AVALANCHE_MAINNET` | `avalanche` |
+| `ChainKeys.HYPEREVM_MAINNET` | `hyper` (defined inside this package) |
+| `ChainKeys.LIGHTLINK_MAINNET` | `lightlinkPhoenix` |
+| `ChainKeys.REDBELLY_MAINNET` | `redbellyMainnet` |
+| `ChainKeys.KAIA_MAINNET` | `kaia` |
+
+---
+
+## Non-EVM (one provider per chain family)
+
+| Chain family | Provider | Spoke chain key(s) |
+|---|---|---|
+| Solana    | `SolanaWalletProvider`    | `ChainKeys.SOLANA_MAINNET` |
+| Sui       | `SuiWalletProvider`       | `ChainKeys.SUI_MAINNET` |
+| Bitcoin   | `BitcoinWalletProvider`   | `ChainKeys.BITCOIN_MAINNET` |
+| Stellar   | `StellarWalletProvider`   | `ChainKeys.STELLAR_MAINNET` |
+| ICON      | `IconWalletProvider`      | `ChainKeys.ICON_MAINNET` |
+| Injective | `InjectiveWalletProvider` | `ChainKeys.INJECTIVE_MAINNET` |
+| NEAR      | `NearWalletProvider`      | `ChainKeys.NEAR_MAINNET` |
+| Stacks    | `StacksWalletProvider`    | `ChainKeys.STACKS_MAINNET` |
+
+> 20 spoke chains total = 12 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
+
+---
+
+## Upstream chain-SDK matrix
+
+Run-time deps each provider pulls in. See [`../recipes/library-exports.md`](../recipes/library-exports.md) for how to re-import their **types** without a direct dep.
+
+| Provider | Upstream SDKs |
+|---|---|
+| `EvmWalletProvider`       | `viem` |
+| `SolanaWalletProvider`    | `@solana/web3.js`, `@solana/spl-token`, `@solana/wallet-adapter-base` |
+| `SuiWalletProvider`       | `@mysten/sui`, `@mysten/wallet-standard` |
+| `BitcoinWalletProvider`   | `bitcoinjs-lib`, `ecpair`, `secp256k1`, `@bitcoinerlab/secp256k1`, `bip322-js` |
+| `StellarWalletProvider`   | `@stellar/stellar-sdk` |
+| `IconWalletProvider`      | `icon-sdk-js` |
+| `InjectiveWalletProvider` | `@injectivelabs/sdk-ts`, `@injectivelabs/wallet-core`, `@injectivelabs/networks`, `@injectivelabs/ts-types` |
+| `NearWalletProvider`      | `near-api-js`, `@hot-labs/near-connect` |
+| `StacksWalletProvider`    | `@stacks/transactions`, `@stacks/connect`, `@stacks/network` |
+
+---
+
+## When to NOT use this package
+
+If your chain is not in the table above, this package does not yet support it. Adding a new chain is a **maintainer task** — open an issue if your chain is missing.

package/ai-exported/integration/reference/glossary.md

@@ -0,0 +1,28 @@
+# Glossary
+
+Terms used across the `wallet-sdk-core` docs.
+
+| Term | Meaning |
+|---|---|
+| **`BaseWalletProvider`** | Abstract base class every provider extends. Holds `defaults` and exposes `mergePolicy` / `mergeDefaults`. |
+| **Browser-extension mode** | Construction mode where the caller supplies pre-built chain clients / wallet kits from a wallet extension (MetaMask, Phantom, Xverse, Hana, Freighter, Leather, …). |
+| **`chainType`** | Literal string identifier on each provider class (`'EVM'`, `'SOLANA'`, …). Mirrors `ChainType` in `@sodax/types`. |
+| **Discriminant style** | How the union narrows. Either **field presence** (most chains) or an explicit **`type` field** (Bitcoin, Stellar). |
+| **`defaults`** | Optional config slice merged into every method call. Shape per chain is `*WalletDefaults`. |
+| **EOA** | Externally Owned Account — a wallet derived from a key, as opposed to a contract account. Some chains brand it (`IconEoaAddress`, `InjectiveEoaAddress`). |
+| **Field presence** | A discriminated union narrowed by which fields exist (`'privateKey' in config` vs `'walletClient' in config`). |
+| **Flat merge** (`mergeDefaults`) | Defaults are a flat object; per-call options shallow-merge over the entire object. |
+| **Hub / Spoke** | SODAX architecture term. Sonic is the hub; all other 19 chains are spokes. `wallet-sdk-core` provides spoke-side wallet primitives. |
+| **`IXxxWalletProvider`** | Chain-specific interface from `@sodax/types`. The class implements it; the SDK consumes it. |
+| **`library-exports`** | `src/types/library-exports.ts` — curated re-exports of upstream chain-SDK types (and 2 runtime enums). |
+| **Mnemonics** | BIP-39 phrase. Used as the private-key credential on Sui (no raw-key option) and as one option on Injective via the `secret` wrapper. |
+| **Per-method merge** (`mergePolicy`) | Defaults are grouped per method (`defaults.sendTransaction`, …); per-call options shallow-merge over the matching slice. |
+| **Private-key mode** | Construction mode where the caller supplies a raw secret (or mnemonic / nested `secret` for some chains). Server / script / CI flows only. |
+| **PSBT** | Partially Signed Bitcoin Transaction. Bitcoin `signTransaction` accepts a base64-encoded PSBT. |
+| **`secret`** (Injective only) | Nested credential wrapper accepting `{ privateKey }` or `{ mnemonics }` in `SecretInjectiveWalletConfig`. |
+| **Shallow merge** | Top-level keys are merged; nested objects are replaced wholesale. See `src/utils/merge.ts`. |
+| **Spoke chain key** | Branded string from `@sodax/types` identifying a chain (`ChainKeys.SONIC_MAINNET`, `ChainKeys.BSC_MAINNET`, …). |
+| **`type` discriminant** | Explicit uppercase `type: 'PRIVATE_KEY' \| 'BROWSER_EXTENSION'` field. Used by Bitcoin and Stellar only. |
+| **`WalletAddressProvider`** | Base interface in `@sodax/types` — exposes `getWalletAddress(): Promise<string>`. Every `IXxxWalletProvider` extends it. |
+| **`walletsKit`** | Consumer-supplied adapter in Bitcoin / Stellar browser-extension mode. Conforms to `BitcoinWalletsKit` / `StellarWalletsKit`. |
+| **XDR** | Stellar's binary transaction format, encoded as a string. Type alias `XDR` from `@sodax/types`. |

package/ai-exported/integration/reference/interfaces.md

@@ -0,0 +1,131 @@
+# `IXxxWalletProvider` interfaces
+
+The signatures `@sodax/sdk` consumes. Sourced from `@sodax/types`; one interface per chain. Pass the **interface**, not the class, in function signatures — see [`../recipes/bridge-to-sdk.md`](../recipes/bridge-to-sdk.md).
+
+The tables below summarise the methods each provider exposes. For full type-level signatures (including the chain-specific param/return types) consult `@sodax/types`'s package — these tables intentionally elide deep generics.
+
+---
+
+## `IEvmWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<Address>` |
+| `sendTransaction` | `(tx: EvmRawTransaction, opts?: EvmSendTransactionPolicy) => Promise<Hash>` |
+| `waitForTransactionReceipt` | `(hash: Hash, opts?: EvmWaitForTransactionReceiptPolicy) => Promise<EvmRawTransactionReceipt>` |
+
+Plus public field: `publicClient: PublicClient`.
+
+---
+
+## `ISolanaWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `getWalletBase58PublicKey` | `() => SolanaBase58PublicKey` |
+| `sendTransaction` | `(rawTx, opts?: SendOptions) => Promise<string>` |
+| `sendTransactionWithConfirmation` | `(rawTx, sendOpts?, confirmCommitment?) => Promise<string>` |
+| `waitForConfirmation` | `(signature, commitment?) => Promise<…>` |
+| `buildV0Txn` | `(rawInstructions) => Promise<SolanaSerializedTransaction>` |
+| `getAssociatedTokenAddress` | `(mint) => Promise<SolanaBase58PublicKey>` |
+| `getBalance` | `(publicKey) => Promise<number>` |
+| `getTokenAccountBalance` | `(publicKey) => Promise<RpcResponseAndContext<TokenAmount>>` |
+
+Plus public field: `connection: Connection`.
+
+---
+
+## `ISuiWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `signAndExecuteTxn` | `(txn: SuiTransaction, opts?: SuiSignAndExecutePolicy) => Promise<string>` |
+| `viewContract` | `(txn, …) => Promise<…>` |
+| `getCoins` | `(address, token, opts?: SuiGetCoinsPolicy) => Promise<SuiPaginatedCoins>` |
+
+---
+
+## `IBitcoinWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `getPublicKey` | `() => Promise<string>` |
+| `getAddressType` | `(address: string) => Promise<BtcAddressType>` |
+| `signTransaction` | `(psbtBase64: string, finalize?: boolean) => Promise<string>` |
+| `signEcdsaMessage` | `(message: string) => Promise<string>` |
+| `signBip322Message` | `(message: string) => Promise<string>` |
+| `getPayment` | `(keyPair, addressType) => bitcoin.Payment` (PK mode helper) |
+| `sendBitcoin` | `(toAddress: string, satoshis: bigint) => Promise<string>` (only if wallet kit implements it) |
+
+---
+
+## `IStellarWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `signTransaction` | `(tx: XDR) => Promise<XDR>` |
+| `waitForTransactionReceipt` | `(hash: string, opts?: Partial<StellarWalletDefaults>) => Promise<…>` |
+
+---
+
+## `IIconWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<IconEoaAddress>` |
+| `sendTransaction` | `(tx: IcxCallTransaction, opts?: IconWalletDefaults) => Promise<Hash>` |
+| `waitForTransactionReceipt` | `(txHash: Hash) => Promise<IconTransactionResult>` |
+
+Plus public field: `iconService: IconService`.
+
+---
+
+## `IInjectiveWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<InjectiveEoaAddress>` |
+| `getWalletPubKey` | `() => Promise<string>` |
+| `getRawTransaction` | `(…) => Promise<…>` |
+| `execute` | `(…) => Promise<…>` |
+
+Plus public field: `wallet: InjectiveWallet`.
+
+---
+
+## `INearWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `getRawTransaction` | `(params: CallContractParams) => Promise<NearRawTransaction>` |
+| `signAndSubmitTxn` | `(tx: NearRawTransaction, opts?: NearWalletDefaults) => Promise<string>` |
+
+Plus public fields (PK mode only): `account?: Account`, `rpcProvider?: JsonRpcProvider`.
+
+---
+
+## `IStacksWalletProvider`
+
+| Method | Signature (abridged) |
+|---|---|
+| `getWalletAddress` | `() => Promise<string>` |
+| `getPublicKey` | `() => Promise<string>` |
+| `sendTransaction` | `(params: StacksTransactionParams) => Promise<…>` |
+| `readContract` | `(params: StacksTransactionParams) => Promise<ClarityValue>` |
+| `getBalance` | `(address: string) => Promise<bigint>` |
+
+---
+
+## Authoritative source
+
+These tables are summarised. For the full, current type-level signatures (including generics, branded types, and union narrowings) read:
+
+- `@sodax/types/src/wallet-providers/*.ts` (each interface lives here)
+- The implementing class in `packages/wallet-sdk-core/src/wallet-providers/<chain>/`.
+
+If a method exists on the class but not on the interface, it is an **implementation detail** — do not depend on it from outside the package.

package/ai-exported/integration/reference/provider-classes.md

@@ -0,0 +1,54 @@
+# Provider classes — class × config × interface × merge helper
+
+One row per chain. Use this when you know the chain and need to look up everything else.
+
+| Chain | Class | Config union | Interface (`@sodax/types`) | Default merge helper | Discriminant |
+|---|---|---|---|---|---|
+| EVM       | `EvmWalletProvider`       | `EvmWalletConfig`       | `IEvmWalletProvider`       | `mergePolicy` (per-method)   | Field presence (no `type`) |
+| Solana    | `SolanaWalletProvider`    | `SolanaWalletConfig`    | `ISolanaWalletProvider`    | `mergePolicy` (per-method)   | Field presence (no `type`) |
+| Sui       | `SuiWalletProvider`       | `SuiWalletConfig`       | `ISuiWalletProvider`       | `mergePolicy` (per-method)   | Field presence — uses `mnemonics` |
+| Bitcoin   | `BitcoinWalletProvider`   | `BitcoinWalletConfig`   | `IBitcoinWalletProvider`   | `mergeDefaults` (flat)       | **`type` field** (`'PRIVATE_KEY' \| 'BROWSER_EXTENSION'`) |
+| Stellar   | `StellarWalletProvider`   | `StellarWalletConfig`   | `IStellarWalletProvider`   | `mergeDefaults` (flat)       | **`type` field** |
+| ICON      | `IconWalletProvider`      | `IconWalletConfig`      | `IIconWalletProvider`      | `mergeDefaults` (flat)       | Field presence (no `type`) |
+| Injective | `InjectiveWalletProvider` | `InjectiveWalletConfig` | `IInjectiveWalletProvider` | `mergeDefaults` (flat)       | Field presence — PK variant uses `secret` wrapper |
+| NEAR      | `NearWalletProvider`      | `NearWalletConfig`      | `INearWalletProvider`      | `mergeDefaults` (flat)       | Field presence (no `type`) |
+| Stacks    | `StacksWalletProvider`    | `StacksWalletConfig`    | `IStacksWalletProvider`    | `mergeDefaults` (flat)       | Field presence (no `type`) |
+
+> EVM, Solana, and Sui group their `defaults` per method (e.g. `defaults.sendTransaction`, `defaults.signAndExecuteTxn`). Every other chain has a flat `defaults` object. See [`../architecture.md`](../architecture.md) § `BaseWalletProvider`.
+
+---
+
+## All exported `chainType` literals
+
+| Provider | `chainType` |
+|---|---|
+| `EvmWalletProvider` | `'EVM'` |
+| `SolanaWalletProvider` | `'SOLANA'` |
+| `SuiWalletProvider` | `'SUI'` |
+| `BitcoinWalletProvider` | `'BITCOIN'` |
+| `StellarWalletProvider` | `'STELLAR'` |
+| `IconWalletProvider` | `'ICON'` |
+| `InjectiveWalletProvider` | `'INJECTIVE'` |
+| `NearWalletProvider` | `'NEAR'` |
+| `StacksWalletProvider` | `'STACKS'` |
+
+These match `ChainType` values in `@sodax/types`. Useful for runtime discrimination of a generic `IXxxWalletProvider`.
+
+---
+
+## Class hierarchy
+
+```
+BaseWalletProvider<TDefaults>           ← abstract base from this package
+├── EvmWalletProvider       implements IEvmWalletProvider
+├── SolanaWalletProvider    implements ISolanaWalletProvider
+├── SuiWalletProvider       implements ISuiWalletProvider
+├── BitcoinWalletProvider   implements IBitcoinWalletProvider
+├── StellarWalletProvider   implements IStellarWalletProvider
+├── IconWalletProvider      implements IIconWalletProvider
+├── InjectiveWalletProvider implements IInjectiveWalletProvider
+├── NearWalletProvider      implements INearWalletProvider
+└── StacksWalletProvider    implements IStacksWalletProvider
+```
+
+Subclassing `BaseWalletProvider` is **maintainer-only** — it implies adding a new chain to the package.

package/ai-exported/integration/reference/public-api.md

@@ -0,0 +1,128 @@
+# Public API surface
+
+Every named export from `@sodax/wallet-sdk-core`. The package root is the **only** public surface — deep imports from `src/...` are unsupported.
+
+```ts
+// Single entry point
+import { /* … */ } from '@sodax/wallet-sdk-core';
+```
+
+---
+
+## Provider classes (9)
+
+| Export | Chain family | File |
+|---|---|---|
+| `EvmWalletProvider` | EVM | `wallet-providers/evm/EvmWalletProvider.ts` |
+| `SolanaWalletProvider` | Solana | `wallet-providers/solana/SolanaWalletProvider.ts` |
+| `SuiWalletProvider` | Sui | `wallet-providers/sui/SuiWalletProvider.ts` |
+| `BitcoinWalletProvider` | Bitcoin | `wallet-providers/bitcoin/BTCWalletProvider.ts` |
+| `StellarWalletProvider` | Stellar | `wallet-providers/stellar/StellarWalletProvider.ts` |
+| `IconWalletProvider` | ICON | `wallet-providers/icon/IconWalletProvider.ts` |
+| `InjectiveWalletProvider` | Injective | `wallet-providers/injective/InjectiveWalletProvider.ts` |
+| `NearWalletProvider` | NEAR | `wallet-providers/near/NearWalletProvider.ts` |
+| `StacksWalletProvider` | Stacks | `wallet-providers/stacks/StacksWalletProvider.ts` |
+
+Plus the abstract base:
+
+| Export | Purpose |
+|---|---|
+| `BaseWalletProvider<TDefaults>` | Abstract base class. Exposes `getWalletAddress`, `mergePolicy`, `mergeDefaults`. **Subclass only for new chains.** |
+
+---
+
+## Config types (per chain)
+
+Each chain ships **three** config-related exports:
+
+| Pattern | Example | Purpose |
+|---|---|---|
+| `PrivateKey<Chain>WalletConfig` *or* `Secret<Chain>WalletConfig` (Injective) | `PrivateKeyEvmWalletConfig` | Private-key mode config |
+| `BrowserExtension<Chain>WalletConfig` | `BrowserExtensionEvmWalletConfig` | Browser-extension mode config |
+| `<Chain>WalletConfig` | `EvmWalletConfig` | Discriminated union — accept this in function signatures |
+| `<Chain>WalletDefaults` | `EvmWalletDefaults` | Optional `defaults` slice |
+
+Full list:
+
+| Chain | Discriminated union | PK variant | Browser variant | Defaults |
+|---|---|---|---|---|
+| EVM       | `EvmWalletConfig`       | `PrivateKeyEvmWalletConfig`         | `BrowserExtensionEvmWalletConfig`       | `EvmWalletDefaults` |
+| Solana    | `SolanaWalletConfig`    | `PrivateKeySolanaWalletConfig`      | `BrowserExtensionSolanaWalletConfig`    | `SolanaWalletDefaults` |
+| Sui       | `SuiWalletConfig`       | `PrivateKeySuiWalletConfig`         | `BrowserExtensionSuiWalletConfig`       | `SuiWalletDefaults` |
+| Bitcoin   | `BitcoinWalletConfig`   | `PrivateKeyBitcoinWalletConfig`     | `BrowserExtensionBitcoinWalletConfig`   | `BitcoinWalletDefaults` |
+| Stellar   | `StellarWalletConfig`   | `PrivateKeyStellarWalletConfig`     | `BrowserExtensionStellarWalletConfig`   | `StellarWalletDefaults` |
+| ICON      | `IconWalletConfig`      | `PrivateKeyIconWalletConfig`        | `BrowserExtensionIconWalletConfig`      | `IconWalletDefaults` |
+| Injective | `InjectiveWalletConfig` | `SecretInjectiveWalletConfig` ⚠     | `BrowserExtensionInjectiveWalletConfig` | `InjectiveWalletDefaults` |
+| NEAR      | `NearWalletConfig`      | `PrivateKeyNearWalletConfig`        | `BrowserExtensionNearWalletConfig`      | `NearWalletDefaults` |
+| Stacks    | `StacksWalletConfig`    | `PrivateKeyStacksWalletConfig`      | `BrowserExtensionStacksWalletConfig`    | `StacksWalletDefaults` |
+
+⚠ **Injective uses `Secret*`, not `PrivateKey*`** — see [`../features/injective.md`](../features/injective.md).
+
+---
+
+## Per-chain helpers and supporting types
+
+| Export | Chain | Purpose |
+|---|---|---|
+| `getEvmViemChain(key: EvmChainKey)` | EVM | Maps a chain key to its viem `Chain` config. Exhaustive — adding a new key fails typecheck until handled. |
+| `hyper` (viem `Chain`) | EVM | Locally-defined HyperEVM chain config (not in `viem/chains`). |
+| `isPrivateKeyEvmWalletConfig` | EVM | Predicate for narrowing `EvmWalletConfig`. |
+| `isBrowserExtensionEvmWalletConfig` | EVM | Predicate for narrowing `EvmWalletConfig`. |
+| `EvmSendTransactionPolicy` | EVM | Per-call options shape for `sendTransaction`. |
+| `EvmWaitForTransactionReceiptPolicy` | EVM | Per-call options shape for `waitForTransactionReceipt`. |
+| `WalletContextState` | Solana | Subset of `@solana/wallet-adapter-react` context — used by browser-extension config. |
+| `SuiSignAndExecutePolicy` | Sui | Per-call options for `signAndExecuteTxn`. |
+| `SuiGetCoinsPolicy` | Sui | Per-call options for `getCoins`. |
+| `BitcoinNetwork` | Bitcoin | `'TESTNET' \| 'MAINNET'` |
+| `BitcoinWalletsKit` (interface) | Bitcoin | Adapter contract for browser-extension mode. |
+| `BitcoinPkWallet` / `BitcoinBrowserWallet` / `BitcoinWallet` | Bitcoin | Internal runtime-wallet union (exported for type assertions in tests). |
+| `StellarNetwork` | Stellar | `'TESTNET' \| 'PUBLIC'` |
+| `StellarAddress` | Stellar | `string` brand. |
+| `StellarWalletsKit` (interface) | Stellar | Adapter contract for browser-extension mode. |
+| `StellarPkWallet` / `StellarBrowserExtensionWallet` / `StellarWallet` | Stellar | Internal runtime-wallet union (exported for tests). |
+| `IconJsonRpcVersion` / `Hex` / `Hash` / `IconAddress` / `IconEoaAddress` | ICON | Address & hex brands. |
+| `IconPkWallet` / `IconBrowserExtensionWallet` / `IconWallet` | ICON | Internal runtime-wallet union. |
+| `HanaWalletRequestEvent` / `HanaWalletResponseEvent` | ICON | Event names for the Hana wallet `postMessage` bridge. |
+| `ResponseAddressType` / `ResponseSigningType` / `RelayRequestDetail` / `RelayRequestSigning` / `JsonRpcPayloadResponse` | ICON | Hana wallet message shapes. |
+| `InjectiveWallet` | Injective | Internal runtime-wallet shape. |
+| `NearTxExecutionStatus` | NEAR | `'NONE' \| 'INCLUDED' \| 'EXECUTED_OPTIMISTIC' \| 'INCLUDED_FINAL' \| 'EXECUTED' \| 'FINAL'` |
+| `StacksPkWallet` / `StacksBrowserExtensionWallet` / `StacksWallet` | Stacks | Internal runtime-wallet union. |
+
+---
+
+## `library-exports` (types + a few runtime values)
+
+Re-exports from upstream chain SDKs. See [`../recipes/library-exports.md`](../recipes/library-exports.md) for the full table and intended usage.
+
+Type-only (selected examples):
+
+```ts
+import type {
+  WalletClient, PublicClient, TransactionReceipt,   // from viem
+  SuiTransactionBlockResponseOptions,                // from @mysten/sui
+  Commitment, ConnectionConfig, SendOptions,         // from @solana/web3.js
+  Network, ChainId, EvmChainId, MsgBroadcaster,      // from @injectivelabs/*
+  ClarityValue, PostConditionModeName,               // from @stacks/transactions
+  StacksNetwork, StacksProvider,                     // from @stacks/network, @stacks/connect
+  KeyPairString, NearConnector,                      // from near-api-js, @hot-labs/near-connect
+  BitcoinJsNetwork,                                  // from bitcoinjs-lib
+} from '@sodax/wallet-sdk-core';
+```
+
+Runtime values:
+
+```ts
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+---
+
+## NOT exported (intentional)
+
+| Symbol | Where it lives | Why hidden |
+|---|---|---|
+| `shallowMerge` | `src/utils/merge.ts` | Internal merge helper — semantics may change. |
+| Anything under `src/utils/` | — | All internal. |
+| `EvmWalletProvider.serializeReceipt` | private static method | Implementation detail of `waitForTransactionReceipt`. |
+
+If you need one of these, the corresponding **behavior** is exposed via a method — call that instead.

package/ai-exported/migration/README.md

@@ -0,0 +1,84 @@
+# Migration: v1 → v2 (Human-readable overview)
+
+This folder documents how to upgrade an app from **v1** of `@sodax/wallet-sdk-core` (the legacy `sodax-frontend` codebase) to **v2** (this repo). The package name did not change — and **the public surface is intentionally backwards-compatible**. v1 consumer code drops in unchanged.
+
+This folder is the **human-facing** entry point for the upgrade. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first. If you are integrating for the first time, see `../integration/` instead.
+
+---
+
+## Scope
+
+v1 (`sodax-frontend/packages/wallet-sdk-core`) and v2 (current) share:
+
+- **Identical class names**: `EvmWalletProvider`, `InjectiveWalletProvider`, `BitcoinWalletProvider`, … (all 9).
+- **Identical config-type names**: `PrivateKeyEvmWalletConfig`, `SecretInjectiveWalletConfig`, `BrowserExtension*WalletConfig`, …
+- **Identical config shapes**: same required fields, same discriminants, same Injective `secret: { privateKey | mnemonics }` nesting.
+- **Identical public method signatures**: `getWalletAddress`, `sendTransaction`, `signAndExecuteTxn`, …
+
+What v2 **added** (all optional, all additive):
+
+1. **`defaults` config** — every `*WalletConfig` gained an optional `defaults?: *WalletDefaults` field. Used to encode env-level constants (default gas, default commitment, …) once at construction.
+2. **`library-exports`** — types and a few runtime enums re-exported from `@sodax/wallet-sdk-core`. Lets consumers drop direct deps on `viem`, `@mysten/sui`, `@stellar/stellar-sdk`, etc. for type-only usage.
+3. **`BaseWalletProvider<TDefaults>`** — abstract base class shared by every provider. Holds `defaults` and exposes shallow-merge helpers. Internal — consumer code does not extend it.
+4. **`*WalletDefaults` and `*Policy` types** — exported alongside each chain's config types.
+5. **Folder-per-chain source layout** — `wallet-providers/evm/EvmWalletProvider.ts` (v2) replaced `wallet-providers/EvmWalletProvider.ts` (v1). Only matters if you deep-imported from `src/`.
+
+What was **removed** or **renamed**: **nothing**. There is no mandatory edit.
+
+---
+
+## Read order
+
+If you are upgrading by hand, read in this order:
+
+1. [`ai-rules.md`](./ai-rules.md) — workflow + stop conditions. **Drop-in upgrade is the default**; only adopt new features if you want them.
+2. [`breaking-changes/README.md`](./breaking-changes/README.md) — every additive change, with a `Why:` line each.
+3. [`recipes/`](./recipes/) — paired before/after **only** for optional cleanup tasks (adopt `defaults`, adopt `library-exports`).
+4. [`checklist.md`](./checklist.md) — verification pass.
+
+If you are letting a coding agent drive the upgrade, point it at [`ai-rules.md`](./ai-rules.md) — that file gives the agent its workflow and verification protocol.
+
+---
+
+## TL;DR for the impatient
+
+```bash
+# 1. Update version in package.json
+pnpm add @sodax/wallet-sdk-core@latest
+
+# 2. Type-check — expect zero errors from wallet-sdk-core surface
+pnpm exec tsc --noEmit | grep -iE "wallet-sdk-core|WalletProvider|WalletConfig"
+# (errors here indicate either v1 deep imports or a real bug — file an issue)
+
+# 3. Done.  Optional cleanups in recipes/ when you have time.
+```
+
+---
+
+## What is NOT covered here
+
+- **Other SODAX packages** (`@sodax/sdk`, `@sodax/types`, `@sodax/wallet-sdk-react`, `@sodax/dapp-kit`). They each have their own migration docs and **real** v1→v2 breaks.
+- **Upstream chain-SDK upgrades** (viem 2.x → 3.x, etc.) — out of scope.
+- **App framework upgrades** (Node, Vite, Next.js) — out of scope.
+
+---
+
+## Tip: typecheck-driven verification
+
+The repo includes `apps/node/` (Node scripts) and `apps/demo_v1/` (React demo). Running `pnpm exec tsc --noEmit` from either reveals breaking changes — but for wallet-sdk-core specifically, **none of those errors come from this package**. If you see `wallet-sdk-core` in the error output, it's most likely:
+
+- A deep import from `src/...` (never supported; the v2 source layout differs).
+- Indirect — a broken `@sodax/sdk` / `@sodax/types` signature that includes a wallet-provider type.
+
+```bash
+# Filter to wallet-sdk-core specifically
+pnpm exec tsc --noEmit | grep -iE "from '@sodax/wallet-sdk-core'|@sodax/wallet-sdk-core/"
+```
+
+That filtered output is your work list. In a typical project the list is empty.
+
+---
+
+## Getting help
+
+If you do hit a v1 pattern that doesn't compile against v2, [open an issue](https://github.com/icon-project/sodax-sdks/issues) with the source snippet — that means we missed a backwards-compat case and the migration scope needs to grow.