@sodax/skills 2.0.0-rc.4

package/knowledge/wallet-sdk-core/integration/recipes/sign-and-broadcast.md

@@ -0,0 +1,201 @@
+# Recipe: Sign and broadcast (per chain)
+
+Minimal raw-tx flows for each chain. Use these as smoke tests after construction, or when integrating outside of `@sodax/sdk`.
+
+**Depends on:** [`setup-private-key.md`](./setup-private-key.md) or [`setup-browser-extension.md`](./setup-browser-extension.md).
+
+For SDK-mediated flows (deposit, swap, bridge, lend, stake) see [`bridge-to-sdk.md`](./bridge-to-sdk.md) instead — this recipe is for chain-native raw transactions.
+
+---
+
+## EVM
+
+```ts
+import type { EvmRawTransaction } from '@sodax/types';
+
+const tx: EvmRawTransaction = {
+  to:    '0x…',
+  value: 1_000_000_000_000_000n,           // 0.001 ETH
+  data:  '0x',
+};
+
+const hash = await provider.sendTransaction(tx);
+// Optional per-call override: { gas: 5_000_000n }
+
+const receipt = await provider.waitForTransactionReceipt(hash);
+// Receipt is bigint-stringified — JSON-safe.  receipt.blockNumber: string.
+console.log(receipt.status, receipt.blockNumber);
+```
+
+---
+
+## Solana
+
+```ts
+import type { SolanaRawTransactionInstruction } from '@sodax/types';
+
+const instructions: SolanaRawTransactionInstruction[] = [/* … */];
+
+const rawTx = await provider.buildV0Txn(instructions);
+const signature = await provider.sendTransactionWithConfirmation(rawTx);
+
+console.log('signature:', signature);
+```
+
+`buildV0Txn` picks the keypair-vs-adapter signing path internally. `sendTransactionWithConfirmation` waits to the `defaults.confirmCommitment` level (default `'finalized'`).
+
+---
+
+## Sui
+
+```ts
+import type { SuiTransaction } from '@sodax/types';
+
+const tx: SuiTransaction = /* build with @mysten/sui Transaction builder */;
+
+const digest = await provider.signAndExecuteTxn(tx);
+// Pre-flight dry-run is on by default.  Disable for a doomed-tx flow:
+//   await provider.signAndExecuteTxn(tx, { dryRun: { enabled: false } });
+```
+
+---
+
+## Bitcoin
+
+```ts
+// 1. Build a PSBT externally (or via your wallet kit) and serialise to base64.
+const psbtBase64 = '/* … */';
+
+// 2. Sign (finalize defaults to defaults.defaultFinalize, default true).
+const signedTxOrPsbt = await provider.signTransaction(psbtBase64);
+
+// 3. Broadcast — either via the wallet kit (browser mode) or your own broadcaster.
+//    PK mode does not implement a broadcaster in this provider — you submit the
+//    finalised tx to your own node or a public API.
+```
+
+For message signing:
+
+```ts
+const sig    = await provider.signEcdsaMessage('hello');
+const sig322 = await provider.signBip322Message('hello');
+```
+
+---
+
+## Stellar
+
+```ts
+import type { XDR } from '@sodax/types';
+
+// 1. Build the XDR externally (TransactionBuilder from @stellar/stellar-sdk).
+const txXdr: XDR = '/* … */';
+
+// 2. Sign.
+const signedXdr = await provider.signTransaction(txXdr);
+
+// 3. Submit to Horizon (the provider's `server` is private; build a Horizon.Server
+//    yourself or use a service layer that wraps submit).
+
+// 4. Wait for inclusion (polls Horizon).
+const receipt = await provider.waitForTransactionReceipt(submittedHash);
+```
+
+---
+
+## ICON
+
+```ts
+import type { IcxCallTransaction } from '@sodax/types';
+
+const tx: IcxCallTransaction = /* build with icon-sdk-js IcxTransactionBuilder */;
+
+const hash = await provider.sendTransaction(tx);
+// Override step limit / version per call: { stepLimit: 5_000_000 }
+
+const result = await provider.waitForTransactionReceipt(hash);
+console.log(result.status);
+```
+
+---
+
+## Injective
+
+```ts
+// Reads the address (and pubkey) from the configured secret / msgBroadcaster.
+const address = await provider.getWalletAddress();
+const pubKey  = await provider.getWalletPubKey();
+
+// Build + execute via the upstream MsgBroadcaster.  See @injectivelabs/sdk-ts
+// docs for the canonical message builders (MsgSend, MsgExecuteContract, …).
+const txResp = await provider.execute(/* params per @sodax/types */);
+```
+
+For inspection-only flows, `getRawTransaction(…)` returns the unsigned tx without broadcasting.
+
+---
+
+## NEAR
+
+```ts
+import type { CallContractParams, NearRawTransaction } from '@sodax/types';
+
+const params: CallContractParams = /* … */;
+const tx: NearRawTransaction = await provider.getRawTransaction(params);
+
+const hash = await provider.signAndSubmitTxn(tx);
+// Override waitUntil per call: { waitUntil: 'EXECUTED' }
+```
+
+---
+
+## Stacks
+
+```ts
+import type { StacksTransactionParams } from '@sodax/types';
+import { PostConditionMode } from '@sodax/wallet-sdk-core';
+
+const params: StacksTransactionParams = {
+  postConditionMode: PostConditionMode.Deny,
+  /* … */
+};
+
+const txResp = await provider.sendTransaction(params);
+
+// Read-only call (no broadcast):
+const clarityValue = await provider.readContract(params);
+```
+
+---
+
+## Verification (any chain)
+
+```bash
+pnpm checkTs
+```
+
+```ts
+// Smoke test: address read
+console.log(await provider.getWalletAddress());
+
+// Then attempt a tiny tx on testnet.  Save the returned hash and inspect it
+// in the chain's explorer.
+```
+
+---
+
+## Patterns to avoid
+
+| Anti-pattern | Why bad | Replacement |
+|---|---|---|
+| Constructing the `Connection` / `SuiClient` / `Horizon.Server` yourself in PK mode | Duplicates work the provider already does | Read it off the provider (`provider.connection`, etc.) when exposed; otherwise just call the method. |
+| Storing the signed tx in localStorage / IndexedDB | Persists secrets in browser storage | Sign + broadcast in one flow; don't persist signed-but-unbroadcast txs. |
+| Catching every error generically and logging "tx failed" | Hides real causes (nonce, insufficient gas, malformed XDR, …) | Surface the upstream error; the provider doesn't wrap them. |
+
+---
+
+## See also
+
+- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — handing off to `@sodax/sdk` for SODAX hub/spoke flows.
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — tuning the defaults slice.
+- [`../features/<chain>.md`](../features/) — chain-specific method signatures and quirks.

package/knowledge/wallet-sdk-core/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/knowledge/wallet-sdk-core/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/knowledge/wallet-sdk-core/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/knowledge/wallet-sdk-core/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/knowledge/wallet-sdk-core/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/knowledge/wallet-sdk-core/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.