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

package/ai-exported/integration/quickstart.md

@@ -1,259 +0,0 @@
-# Quickstart — Copy/paste examples
-
-Minimal end-to-end snippets per chain family. Pick the chain you need, copy the snippet, and run it. Each snippet covers **both** modes (private-key + browser-extension).
-
-For chain-specific gotchas (Sui's mnemonics, Injective's `secret` wrapper, …) see [`features/<chain>.md`](./features/). For the mental model see [`architecture.md`](./architecture.md).
-
----
-
-## Install
-
-```bash
-pnpm add @sodax/wallet-sdk-core @sodax/types
-```
-
-If you plan to call `@sodax/sdk` after constructing the provider, also add it:
-
-```bash
-pnpm add @sodax/sdk
-```
-
----
-
-## EVM (12 chains)
-
-```ts
-import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
-import { ChainKeys } from '@sodax/types';
-
-// Private-key (Node / scripts / CI)
-const evmPk = new EvmWalletProvider({
-  privateKey: '0x…',
-  chainId: ChainKeys.SONIC_MAINNET,
-  rpcUrl: 'https://rpc.soniclabs.com',
-  defaults: {
-    sendTransaction: { gas: 3_000_000n },
-  },
-});
-console.log(await evmPk.getWalletAddress());
-
-// Browser-extension (consumer supplies viem clients)
-const evmBrowser = new EvmWalletProvider({
-  walletClient: myViemWalletClient,   // from wagmi / viem
-  publicClient: myViemPublicClient,
-});
-```
-
-See [`features/evm.md`](./features/evm.md).
-
----
-
-## Solana
-
-```ts
-import { SolanaWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key — secret key bytes (Uint8Array length 64)
-const solanaPk = new SolanaWalletProvider({
-  privateKey: new Uint8Array(64),
-  endpoint: 'https://api.mainnet-beta.solana.com',
-  defaults: {
-    connectionCommitment: 'confirmed',
-    sendOptions: { skipPreflight: false },
-  },
-});
-
-// Browser-extension — wallet adapter context
-const solanaBrowser = new SolanaWalletProvider({
-  wallet: {
-    publicKey: myPublicKey,           // PublicKey | null
-    signTransaction: mySignTransaction, // SignerWalletAdapterProps['signTransaction'] | undefined
-  },
-  endpoint: 'https://api.mainnet-beta.solana.com',
-});
-```
-
-See [`features/solana.md`](./features/solana.md).
-
----
-
-## Sui
-
-```ts
-import { SuiWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key — DERIVED FROM MNEMONIC, not a raw key
-const suiPk = new SuiWalletProvider({
-  rpcUrl: 'https://fullnode.mainnet.sui.io:443',
-  mnemonics: 'word1 word2 … word12',
-});
-
-// Browser-extension — wallet-standard wallet
-const suiBrowser = new SuiWalletProvider({
-  client: mySuiClient,                          // SuiClient
-  wallet: myWalletWithSuiFeatures,              // WalletWithFeatures<Partial<SuiWalletFeatures>>
-  account: myActiveWalletAccount,               // WalletAccount
-});
-```
-
-See [`features/sui.md`](./features/sui.md).
-
----
-
-## Bitcoin
-
-```ts
-import { BitcoinWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key — uses explicit uppercase `type`
-const btcPk = new BitcoinWalletProvider({
-  type: 'PRIVATE_KEY',
-  privateKey: '0x…',
-  network: 'TESTNET',
-  addressType: 'P2WPKH',                         // optional
-  defaults: { defaultFinalize: true },
-});
-
-// Browser-extension — uses explicit uppercase `type`
-const btcBrowser = new BitcoinWalletProvider({
-  type: 'BROWSER_EXTENSION',
-  walletsKit: myBitcoinWalletsKit,               // Xverse / Unisat / OKX adapter
-  network: 'TESTNET',
-});
-```
-
-See [`features/bitcoin.md`](./features/bitcoin.md).
-
----
-
-## Stellar
-
-```ts
-import { StellarWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key — explicit uppercase `type`
-const stellarPk = new StellarWalletProvider({
-  type: 'PRIVATE_KEY',
-  privateKey: '0x…',
-  network: 'PUBLIC',                              // 'PUBLIC' | 'TESTNET'
-  rpcUrl: 'https://horizon.stellar.org',
-});
-
-// Browser-extension — explicit uppercase `type`
-const stellarBrowser = new StellarWalletProvider({
-  type: 'BROWSER_EXTENSION',
-  walletsKit: myStellarWalletsKit,                // Freighter / xBull / Lobstr kit
-  network: 'PUBLIC',
-});
-```
-
-See [`features/stellar.md`](./features/stellar.md).
-
----
-
-## ICON
-
-```ts
-import { IconWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key (Node / scripts / CI)
-const iconPk = new IconWalletProvider({
-  privateKey: '0x…',
-  rpcUrl: 'https://ctz.solidwallet.io/api/v3',
-});
-
-// Browser-extension — Hana wallet
-const iconBrowser = new IconWalletProvider({
-  walletAddress: 'hx…',                            // optional; resolved at first signing call if omitted
-  rpcUrl: 'https://ctz.solidwallet.io/api/v3',
-});
-```
-
-See [`features/icon.md`](./features/icon.md).
-
----
-
-## Injective
-
-```ts
-import { InjectiveWalletProvider } from '@sodax/wallet-sdk-core';
-import type { ChainId, Network } from '@sodax/wallet-sdk-core';
-
-// Secret-credential variant: private key
-const injectivePk = new InjectiveWalletProvider({
-  secret: { privateKey: '…' },
-  chainId: 'injective-1' as ChainId,
-  network: 'Mainnet' as Network,
-});
-
-// Secret-credential variant: mnemonic
-const injectiveMnemonic = new InjectiveWalletProvider({
-  secret: { mnemonics: 'word1 word2 …' },
-  chainId: 'injective-1' as ChainId,
-  network: 'Mainnet' as Network,
-});
-
-// Browser-extension — caller supplies a configured MsgBroadcaster
-const injectiveBrowser = new InjectiveWalletProvider({
-  msgBroadcaster: myMsgBroadcaster,
-});
-```
-
-> Note: the private-key variant uses a nested `secret` wrapper instead of a top-level `privateKey`. See [`features/injective.md`](./features/injective.md).
-
----
-
-## NEAR
-
-```ts
-import { NearWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key — accountId + raw key
-const nearPk = new NearWalletProvider({
-  rpcUrl: 'https://rpc.mainnet.near.org',
-  accountId: 'alice.near',
-  privateKey: 'ed25519:…',
-});
-
-// Browser-extension — NearConnector
-const nearBrowser = new NearWalletProvider({
-  wallet: myNearConnector,                          // from @hot-labs/near-connect
-});
-```
-
-See [`features/near.md`](./features/near.md).
-
----
-
-## Stacks
-
-```ts
-import { StacksWalletProvider } from '@sodax/wallet-sdk-core';
-
-// Private-key (Node / scripts / CI)
-const stacksPk = new StacksWalletProvider({
-  privateKey: '…',
-  endpoint: 'https://api.mainnet.hiro.so',
-});
-
-// Browser-extension — Leather / Xverse / Asigna
-const stacksBrowser = new StacksWalletProvider({
-  address: 'SP…',
-  endpoint: 'https://api.mainnet.hiro.so',
-  provider: myStacksProvider,                       // StacksProvider from @stacks/connect
-});
-```
-
-See [`features/stacks.md`](./features/stacks.md).
-
----
-
-## Next steps
-
-After construction:
-
-- **Get the wallet address** — every provider exposes `getWalletAddress(): Promise<string>` (narrowed to a chain-specific brand by subclasses).
-- **Sign and broadcast** — see [`recipes/sign-and-broadcast.md`](./recipes/sign-and-broadcast.md) for the per-chain flow.
-- **Hand off to `@sodax/sdk`** — see [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md).
-- **Tune defaults** — see [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md).
-- **Avoid direct chain-SDK deps** — see [`recipes/library-exports.md`](./recipes/library-exports.md).

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

@@ -1,15 +0,0 @@
-# Recipes
-
-Self-contained, task-oriented guides. Each recipe has paired before/after code, prerequisites, and verification steps.
-
-| Recipe | When to use | Depends on |
-|---|---|---|
-| [`setup-private-key.md`](./setup-private-key.md) | Construct a provider from a raw key (Node scripts, CI, tests). | none |
-| [`setup-browser-extension.md`](./setup-browser-extension.md) | Construct a provider from a wallet-extension adapter (consumer dApps). | none |
-| [`bridge-to-sdk.md`](./bridge-to-sdk.md) | Pass the provider to `@sodax/sdk` calls. | a setup recipe |
-| [`defaults-and-overrides.md`](./defaults-and-overrides.md) | Configure the `defaults` slice and understand shallow-merge semantics. | a setup recipe |
-| [`library-exports.md`](./library-exports.md) | Avoid direct deps on `viem`, `@mysten/sui`, etc. by re-importing types from `@sodax/wallet-sdk-core`. | none |
-| [`sign-and-broadcast.md`](./sign-and-broadcast.md) | Typical raw-tx flow per chain. | a setup recipe |
-| [`testing.md`](./testing.md) | Mock providers in unit tests. | none |
-
-Pick the recipe that matches the user's task. Recipes are intentionally short and self-contained — do **not** chain more than 2 in one apply.

package/ai-exported/integration/recipes/bridge-to-sdk.md

@@ -1,145 +0,0 @@
-# Recipe: Bridge to `@sodax/sdk`
-
-Pass the constructed provider to `@sodax/sdk` so the SDK can sign and submit hub/spoke transactions on the user's behalf.
-
-**Depends on:** a constructed provider (see [`setup-private-key.md`](./setup-private-key.md) or [`setup-browser-extension.md`](./setup-browser-extension.md)).
-
----
-
-## The contract: `IXxxWalletProvider`
-
-`@sodax/sdk` consumes the chain-specific **interfaces** from `@sodax/types`, not the concrete classes. This is the indirection that keeps the SDK decoupled from `wallet-sdk-core`:
-
-```ts
-import type {
-  IEvmWalletProvider,
-  ISolanaWalletProvider,
-  ISuiWalletProvider,
-  IBitcoinWalletProvider,
-  IStellarWalletProvider,
-  IIconWalletProvider,
-  IInjectiveWalletProvider,
-  INearWalletProvider,
-  IStacksWalletProvider,
-} from '@sodax/types';
-```
-
-Each `*WalletProvider` class from `wallet-sdk-core` `implements` the matching interface. So:
-
-```ts
-import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
-import type { IEvmWalletProvider } from '@sodax/types';
-
-const evm: IEvmWalletProvider = new EvmWalletProvider({ /* … */ });
-```
-
-In your SDK call signatures, take the **interface**, not the class:
-
-```ts
-// ✅ DO
-async function deposit(wallet: IEvmWalletProvider) { /* … */ }
-
-// ❌ DON'T — couples the function to the implementation
-async function deposit(wallet: EvmWalletProvider) { /* … */ }
-```
-
----
-
-## Pattern: pass the provider to a `Sodax` feature service
-
-Construct the wallet provider once, instantiate the `Sodax` facade, and pass the provider as `walletProvider` to the feature method you want (swap, bridge, money market, staking, …). The `Sodax` facade owns the per-chain spoke services internally — you do **not** construct `*SpokeService` yourself.
-
-```ts
-import { Sodax } from '@sodax/sdk';
-import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
-import { ChainKeys } from '@sodax/types';
-
-const walletProvider = new EvmWalletProvider({
-  privateKey: process.env.EVM_PK as `0x${string}`,
-  chainId: ChainKeys.SONIC_MAINNET,
-  rpcUrl: process.env.EVM_RPC,
-});
-
-const sodax = new Sodax(/* optional SodaxConfig — see @sodax/sdk docs */);
-
-// Example: supply to the money market on BSC. The wallet provider goes in
-// at the feature-method call, not at facade construction.
-const result = await sodax.moneyMarket.supply({
-  params: {
-    srcChainKey: ChainKeys.BSC_MAINNET,
-    srcAddress:  await walletProvider.getWalletAddress(),
-    token:       '0x…',
-    amount:      1_000n,
-    action:      'supply',
-  },
-  walletProvider,                           // ← the IEvmWalletProvider
-});
-```
-
-The same shape applies to `sodax.swaps.*`, `sodax.bridge.*`, `sodax.staking.*`, `sodax.migration.*`, etc. — each feature service method that needs signing takes a `walletProvider` argument typed to the chain-specific interface.
-
-> If you need the underlying spoke service for advanced read-only operations, get it via `sodax.spoke.getSpokeService(chainKey)` — but never `new EvmSpokeService(...)` yourself.
-
-For SDK-level recipes (initialise the `Sodax` facade, configure hub provider, raw-tx flows, error handling) see `@sodax/sdk`'s `ai-exported/`.
-
----
-
-## Pattern: React layer (typical)
-
-In a React dApp you almost never construct providers manually. `@sodax/wallet-sdk-react` returns the typed interface for you, and `@sodax/dapp-kit` wraps SDK calls into hooks:
-
-```tsx
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { useSwap } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/types';
-
-function SwapButton() {
-  const evm = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
-  // evm: IEvmWalletProvider | undefined
-
-  const swap = useSwap();
-
-  return (
-    <button
-      disabled={!evm}
-      onClick={() => evm && swap.mutateAsync({ /* params */, walletProvider: evm })}
-    >
-      Swap
-    </button>
-  );
-}
-```
-
-The hook narrows on `xChainId`, returns the chain-specific interface, and is `undefined` until the user is connected on that family. Refer to `@sodax/wallet-sdk-react`'s own docs for the full pattern.
-
----
-
-## Patterns to avoid
-
-| Anti-pattern | Why bad | Replacement |
-|---|---|---|
-| Re-constructing the provider in every call site | Wastes work, can drop default config | Construct once, pass the instance around |
-| Typing functions on the concrete class (`EvmWalletProvider`) | Couples to `wallet-sdk-core` | Use the `IXxxWalletProvider` interface |
-| Casting between provider classes (`as ISolanaWalletProvider`) | Hides a chain-type mismatch | Pick the right provider for the chain at the call site |
-| Storing the provider in a long-lived Zustand / Redux store | Provider holds live SDK clients / network connections | Store the **config** (e.g. PK + chainId), construct on demand |
-
----
-
-## Verification
-
-```bash
-# 1. Type check passes
-pnpm checkTs
-
-# 2. SDK calls type-check against the interface, not the class
-grep -rn "IEvmWalletProvider\|ISolanaWalletProvider\|IBitcoinWalletProvider" <user-src>
-# expect at least one match in your function signatures
-```
-
----
-
-## Next steps
-
-- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — fine-tune the `defaults` slice for tx options.
-- [`library-exports.md`](./library-exports.md) — type-only re-exports to avoid upstream chain-SDK deps.
-- [`testing.md`](./testing.md) — mocking providers in tests.

package/ai-exported/integration/recipes/defaults-and-overrides.md

@@ -1,159 +0,0 @@
-# Recipe: Defaults and per-call overrides
-
-Configure the `defaults` slice and understand the shallow-merge semantics shared by every provider.
-
-**Depends on:** [`setup-private-key.md`](./setup-private-key.md) or [`setup-browser-extension.md`](./setup-browser-extension.md).
-
----
-
-## Mental model
-
-Every provider class extends `BaseWalletProvider<TDefaults>`. `defaults` is captured at construction time; per-call `options` are shallow-merged over the relevant slice at call time:
-
-```
-final  = shallowMerge(defaults[key], options)        // mergePolicy('key', options)
-       OR
-       = shallowMerge(defaults, options)              // mergeDefaults(options)
-```
-
-Two helpers, two shapes:
-
-| Helper | When the chain uses it | Example |
-|---|---|---|
-| `mergePolicy('foo', opts)` | `defaults` is **grouped per method** | EVM: `defaults.sendTransaction`, `defaults.waitForTransactionReceipt` |
-| `mergeDefaults(opts)` | `defaults` is **flat** | Bitcoin: `defaultFinalize`; Stellar: `pollInterval`, `pollTimeout` |
-
-For the helper each chain uses, see [`../features/<chain>.md`](../features/).
-
----
-
-## Shallow, not deep
-
-Top-level keys merge; **nested objects are replaced wholesale**.
-
-```ts
-const provider = new EvmWalletProvider({
-  // …
-  defaults: {
-    sendTransaction: { gas: 3_000_000n, nonce: 0 },
-  },
-});
-
-await provider.sendTransaction(txData, { gas: 5_000_000n });
-//                                       ^^^^^^^^^^^^^^^^
-// Final policy: { gas: 5_000_000n }     ← nonce is DROPPED
-```
-
-If you need `nonce` to persist, include it in the per-call options:
-
-```ts
-await provider.sendTransaction(txData, { gas: 5_000_000n, nonce: 0 });
-```
-
-Or split the default so each tunable lives at the top level — see `src/utils/merge.ts` for the implementation. The behavior is intentional: deep merge would silently smuggle stale fields across call sites.
-
----
-
-## `undefined` is "no opinion"
-
-The merge skips:
-
-- `undefined` **layers** entirely (no options object → use defaults verbatim).
-- `undefined` **values** inside a layer (`{ gas: undefined }` does **not** override the previous layer).
-
-```ts
-const policy: Partial<EvmSendTransactionPolicy> = { gas: undefined };
-await provider.sendTransaction(txData, policy);
-// gas falls back to defaults.sendTransaction.gas
-```
-
-This is useful when threading options through optional parameters — `undefined` reads as "use the default".
-
----
-
-## Where to put what
-
-| Tunable | Goes where | Why |
-|---|---|---|
-| Env-level constants (RPC URL, default gas, default commitment) | `defaults` at construction | One place, captured at startup |
-| Per-call tweaks (this tx needs more gas) | per-call `options` argument | Localized, doesn't leak into other calls |
-| Anything that changes after construction (active network in PK mode) | re-construct the provider | `defaults` is frozen at startup |
-
-You **cannot** mutate `defaults` after construction — `BaseWalletProvider` captures the reference into a `protected readonly` field. Later mutations have no effect.
-
----
-
-## Worked example: EVM with two default slices
-
-```ts
-import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
-import { ChainKeys } from '@sodax/types';
-
-const provider = new EvmWalletProvider({
-  privateKey: process.env.PK as `0x${string}`,
-  chainId: ChainKeys.SONIC_MAINNET,
-  defaults: {
-    // Slice grouped by method — merged via mergePolicy('sendTransaction', …)
-    sendTransaction: { gas: 3_000_000n },
-
-    // Another method-grouped slice
-    waitForTransactionReceipt: { confirmations: 1, timeout: 60_000 },
-
-    // Constructor-time slices (private-key mode only — ignored in browser-extension mode)
-    transport: { batch: { batchSize: 10 } },
-  },
-});
-
-// Default gas: 3M.  This call bumps to 5M.
-const hash = await provider.sendTransaction(tx, { gas: 5_000_000n });
-
-// Default 1 confirmation, 60s timeout.  This call overrides both.
-const receipt = await provider.waitForTransactionReceipt(hash, {
-  confirmations: 2,
-  timeout: 30_000,
-});
-```
-
----
-
-## Browser-extension warning
-
-In **browser-extension** mode the constructor-time slices (`transport`, `publicClient`, `walletClient` on EVM; analogous on other chains) are **ignored** — the consumer already supplied built clients, so there is nothing for the provider to configure. A one-time `console.warn` is logged.
-
-```
-[EvmWalletProvider] defaults.{transport,publicClient,walletClient} ignored in browser-extension mode.
-```
-
-This is informational, not a bug. The method-grouped slices (`sendTransaction`, `waitForTransactionReceipt`, …) still apply in both modes.
-
----
-
-## Verification
-
-```ts
-// Assert that defaults applied — run on a testnet
-const hash = await provider.sendTransaction(tx);  // no per-call options
-// Then read the receipt and confirm gas matches your default
-```
-
-```bash
-pnpm checkTs
-```
-
----
-
-## Common pitfalls
-
-| Pitfall | Symptom | Fix |
-|---|---|---|
-| Expecting deep merge | A nested field was "dropped" | The whole object was replaced. Include both fields in the per-call options. |
-| Mutating `defaults` after construction | Tunable doesn't take effect | Reconstruct the provider, or pass the new value per call. |
-| Setting transport defaults in browser-extension mode | Warning logged, no effect | Move them out — they only apply in PK mode. |
-| Putting RPC URL in `defaults` | RPC URL is a top-level config field on every chain, not a `defaults` slice | Use `rpcUrl: '…'` at the config root (PK mode), or pass `publicClient` / `client` directly (browser-extension mode). |
-
----
-
-## See also
-
-- [`../architecture.md`](../architecture.md) § `BaseWalletProvider` and the `defaults` model.
-- [`../features/`](../features/) — per-chain `*Defaults` shape and which helper each chain uses.