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

package/ai-exported/integration/recipes/library-exports.md

@@ -0,0 +1,129 @@
+# Recipe: `library-exports` — re-import upstream chain types
+
+Avoid adding `viem`, `@mysten/sui`, `@solana/web3.js`, etc. as direct `package.json` deps. `@sodax/wallet-sdk-core` re-exports a curated set of types (and a handful of runtime enums) from each upstream chain SDK.
+
+**Depends on:** none — pure type-level optimisation.
+
+---
+
+## What's re-exported
+
+Source file: `src/types/library-exports.ts`. The export name is the same as upstream — only the source module changes.
+
+### Types (no runtime cost)
+
+| Chain SDK | Re-exported types |
+|---|---|
+| `viem` | `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt` |
+| `@mysten/sui/client` | `SuiTransactionBlockResponseOptions` |
+| `@mysten/sui/transactions` | `Transaction`, `TransactionArgument` |
+| `@mysten/wallet-standard` | `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures` |
+| `@solana/web3.js` | `Commitment`, `ConnectionConfig`, `SendOptions` |
+| `@injectivelabs/networks` | `Network` |
+| `@injectivelabs/ts-types` | `ChainId`, `EvmChainId` |
+| `@injectivelabs/wallet-core` | `MsgBroadcaster` |
+| `@stacks/transactions` | `ClarityValue`, `PostConditionModeName` |
+| `@stacks/network` | `StacksNetwork` |
+| `@stacks/connect` | `StacksProvider` |
+| `near-api-js` | `KeyPairString` |
+| `@hot-labs/near-connect` | `NearConnector` |
+| `bitcoinjs-lib/src/networks.js` | `Network as BitcoinJsNetwork` |
+
+### Runtime values (also re-exported)
+
+| Source | Value | Why include the runtime |
+|---|---|---|
+| `@stellar/stellar-sdk` | `Networks` (object) | Consumers commonly read `Networks.PUBLIC` / `Networks.TESTNET` |
+| `@stacks/transactions` | `PostConditionMode` (enum) | Used as a value when building Stacks tx params |
+
+Note the file name: `library-exports` (not `library-types`). It exists precisely because the file mixes type and runtime re-exports.
+
+---
+
+## Usage
+
+```ts
+// ✅ DO — types and the two runtime enums via wallet-sdk-core
+import type {
+  WalletClient,
+  PublicClient,
+  TransactionReceipt,
+  SuiWalletFeatures,
+  WalletAccount,
+  WalletWithFeatures,
+  ConnectionConfig,
+  Network,
+  ChainId,
+  StacksNetwork,
+  StacksProvider,
+  NearConnector,
+} from '@sodax/wallet-sdk-core';
+
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+```ts
+// ❌ DON'T — direct upstream imports for these names if you only need them as types
+import type { WalletClient } from 'viem';
+import { Networks } from '@stellar/stellar-sdk';
+```
+
+---
+
+## When to NOT use re-exports
+
+The re-export list is **curated** — only the types most consumers need. Use the upstream package directly when:
+
+- You need a type not in the re-export list (e.g. viem's `TransactionRequest`, Solana's `Keypair` value).
+- You need a **runtime value** other than `Networks` / `PostConditionMode` (e.g. viem's `createPublicClient`, `@solana/web3.js`'s `Connection`).
+- You are building a polyfill, mock, or shim around the underlying SDK.
+
+In those cases, add the upstream package to `package.json` and import normally. The re-export is an optimisation, not a hard wall.
+
+---
+
+## Why `library-exports` exists
+
+| Without it | With it |
+|---|---|
+| Consumer `package.json` lists 8+ chain SDKs explicitly | Consumer lists only `@sodax/wallet-sdk-core` + `@sodax/types` |
+| Upgrading a chain SDK touches consumer lockfiles | SODAX bumps the SDK; consumers re-install |
+| Type drift between SODAX and consumer (different `viem` minor versions) | Single source of truth — same `viem` version as SODAX uses internally |
+
+The trade-off is the curated list — uncommon types need a direct dep.
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Confirm no direct upstream imports for re-exported types
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters"
+grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+grep -rn "from '@stacks/transactions'" <user-src> | grep "PostConditionMode"
+# expect empty for all three
+
+# 3. Confirm the chain SDKs are NOT direct deps in consumer's package.json
+cat <user>/package.json | grep -E '"viem"|"@stellar/stellar-sdk"|"@stacks/transactions"|"@mysten/sui"|"@solana/web3.js"|"@injectivelabs"|"near-api-js"|"bitcoinjs-lib"'
+# expect empty unless the consumer legitimately uses a non-re-exported symbol
+```
+
+---
+
+## Common pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Importing `Networks` from `@stellar/stellar-sdk` after install | Works, but adds a direct dep | Switch to `import { Networks } from '@sodax/wallet-sdk-core'` |
+| Mixing type-only and value imports in one statement | Build size grows | `import type { … }` for types; separate value imports |
+| Expecting all viem helpers to be re-exported | `createPublicClient` is missing | Only types + 2 enums are re-exported. Other runtime helpers require direct install. |
+
+---
+
+## See also
+
+- [`../architecture.md`](../architecture.md) § `library-exports` — the upstream-SDK indirection.
+- [`../reference/public-api.md`](../reference/public-api.md) — full barrel export list.

package/ai-exported/integration/recipes/setup-browser-extension.md

@@ -0,0 +1,137 @@
+# Recipe: Setup — browser-extension mode
+
+Construct a `*WalletProvider` from a wallet adapter that the user has already connected (MetaMask via wagmi, Phantom via wallet-adapter, Xverse via a kit, …).
+
+**Depends on:** the consumer app already obtains a chain-specific signer / client from the extension. Inside a React app, prefer `useWalletProvider` from `@sodax/wallet-sdk-react` — see § "When to skip this recipe" below.
+
+---
+
+## Pick the right chain
+
+Each chain has its own browser-extension variant. See [`../features/<chain>.md`](../features/) for exact field shapes.
+
+| Chain | Required inputs |
+|---|---|
+| EVM       | `walletClient` (viem `WalletClient<Transport, Chain, Account>`) + `publicClient` (viem `PublicClient`) |
+| Solana    | `wallet: { publicKey, signTransaction }` + `endpoint` |
+| Sui       | `client` (`SuiClient`) + `wallet` (`WalletWithFeatures<Partial<SuiWalletFeatures>>`) + `account` (`WalletAccount`) |
+| Bitcoin   | `type: 'BROWSER_EXTENSION'`, `walletsKit` (consumer-supplied adapter), `network` |
+| Stellar   | `type: 'BROWSER_EXTENSION'`, `walletsKit`, `network` |
+| ICON      | `walletAddress` (optional `hx…`) + `rpcUrl` |
+| Injective | `msgBroadcaster` |
+| NEAR      | `wallet` (`NearConnector` from `@hot-labs/near-connect`) |
+| Stacks    | `address` + optional `provider` (StacksProvider) |
+
+---
+
+## Pattern: EVM (with wagmi clients)
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import type { WalletClient, PublicClient } from '@sodax/wallet-sdk-core';
+import { useWalletClient, usePublicClient } from 'wagmi';
+// …or wherever your app sources the viem clients
+
+function buildProvider(walletClient: WalletClient, publicClient: PublicClient) {
+  return new EvmWalletProvider({
+    walletClient,
+    publicClient,
+    // Optional — `defaults.sendTransaction` and `defaults.waitForTransactionReceipt`
+    // are honored. `defaults.transport / publicClient / walletClient` are IGNORED
+    // in browser-extension mode (the provider logs a one-time warning).
+    defaults: {
+      sendTransaction: { gas: 1_000_000n },
+    },
+  });
+}
+```
+
+---
+
+## Pattern: Solana (with `@solana/wallet-adapter-react`)
+
+```ts
+import { SolanaWalletProvider } from '@sodax/wallet-sdk-core';
+import { useWallet } from '@solana/wallet-adapter-react';
+
+function buildProvider() {
+  const { publicKey, signTransaction } = useWallet();
+  return new SolanaWalletProvider({
+    wallet: { publicKey, signTransaction },          // both may be null/undefined until connected
+    endpoint: 'https://api.mainnet-beta.solana.com',
+    defaults: { sendOptions: { skipPreflight: false } },
+  });
+}
+```
+
+---
+
+## Pattern: Bitcoin / Stellar (explicit `type`)
+
+```ts
+import { BitcoinWalletProvider } from '@sodax/wallet-sdk-core';
+
+const provider = new BitcoinWalletProvider({
+  type: 'BROWSER_EXTENSION',
+  walletsKit: myBitcoinAdapter,                       // implements BitcoinWalletsKit
+  network: 'MAINNET',
+});
+```
+
+The `walletsKit` is a consumer-provided adapter (Xverse / Unisat / OKX) that conforms to the `BitcoinWalletsKit` interface — see [`../features/bitcoin.md`](../features/bitcoin.md).
+
+---
+
+## When to skip this recipe
+
+You almost never construct browser-extension providers **manually** inside a React component. The right path is:
+
+```tsx
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const evm = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
+// evm: IEvmWalletProvider | undefined  ← already typed, already wired
+```
+
+`@sodax/wallet-sdk-react` handles the construction internally — see its `ai-exported/integration/recipes/setup.md`. Skip this recipe (the manual path) unless you are:
+
+- Building a custom non-React frontend that talks to a wallet extension directly.
+- Writing a thin wrapper around the package for a framework that doesn't have a SODAX integration yet.
+- Migrating a legacy non-React app.
+
+---
+
+## Verification
+
+```ts
+console.log(await provider.getWalletAddress());      // smoke test
+```
+
+```bash
+# Type check
+pnpm checkTs
+
+# Confirm no deep imports
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+```
+
+---
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `signTransaction is not a function` (Solana) | Wallet adapter didn't provide a signer for the connected wallet | Gate construction on `signTransaction != null`. |
+| `WalletAccount is undefined` (Sui) | Adapter exposes `wallet` but not the active `account` | Read `wallet.accounts[0]` or your adapter's "current account" API before constructing. |
+| `[EvmWalletProvider] defaults.{transport,publicClient,walletClient} ignored…` | Mixed PK-mode defaults with browser-extension config | Move those defaults out — they only apply in private-key mode. |
+| Mode picked the wrong variant (TypeScript narrowing fails) | Mixed PK and browser fields | Pick **one** discriminated union variant. Don't pass both. |
+
+---
+
+## Next steps
+
+- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — hand off the provider to `@sodax/sdk` calls.
+- [`library-exports.md`](./library-exports.md) — avoid taking `viem` / `@mysten/sui` / etc. as direct deps when importing types.
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — tune `defaults`.

package/ai-exported/integration/recipes/setup-private-key.md

@@ -0,0 +1,115 @@
+# Recipe: Setup — private-key mode
+
+Construct a `*WalletProvider` from a raw key. Use this in Node scripts, CI, tests, indexers, bots — anywhere the runtime legitimately possesses a secret.
+
+**Depends on:** none. **Do NOT** use this in a browser bundle.
+
+---
+
+## Pick the right chain
+
+Each chain has its own discriminated union. See [`../features/<chain>.md`](../features/) for exact field names.
+
+| Chain | Field that triggers PK mode | Credential shape |
+|---|---|---|
+| EVM       | `privateKey: '0x…'`                       | hex string |
+| Solana    | `privateKey: Uint8Array`                  | 64-byte secret key |
+| Sui       | `mnemonics: '…'`                          | BIP-39 phrase (no raw key option) |
+| Bitcoin   | `type: 'PRIVATE_KEY'`, `privateKey: '0x…'`| hex string + uppercase `type` |
+| Stellar   | `type: 'PRIVATE_KEY'`, `privateKey: '0x…'`| hex string + uppercase `type` |
+| ICON      | `privateKey: '0x…'`                       | hex string |
+| Injective | `secret: { privateKey } \| { mnemonics }` | nested credential object |
+| NEAR      | `privateKey: 'ed25519:…'`, `accountId`    | algorithm-prefixed string + accountId |
+| Stacks    | `privateKey: '…'`                         | string |
+
+---
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-core @sodax/types
+```
+
+If you'll hand off to `@sodax/sdk`, add it too:
+
+```bash
+pnpm add @sodax/sdk
+```
+
+---
+
+## Pattern: EVM (representative)
+
+```ts
+import 'dotenv/config';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY as `0x${string}`;
+if (!PRIVATE_KEY) throw new Error('EVM_PRIVATE_KEY is required');
+
+const provider = new EvmWalletProvider({
+  privateKey: PRIVATE_KEY,
+  chainId: ChainKeys.SONIC_MAINNET,                 // pick any EvmChainKey
+  rpcUrl: process.env.EVM_RPC_URL,                  // optional — defaults to viem chain's public RPC
+  defaults: {
+    sendTransaction: { gas: 3_000_000n },           // env-level fixed default
+  },
+});
+
+const address = await provider.getWalletAddress();
+console.log('Signing as:', address);
+```
+
+For other chains, swap the import and follow the field table above. Full snippets per chain live in [`../quickstart.md`](../quickstart.md).
+
+---
+
+## Keep the secret out of code
+
+| Anti-pattern | Why bad | Replacement |
+|---|---|---|
+| `privateKey: '0xabc…'` inline | Key in version control | `process.env.EVM_PRIVATE_KEY` |
+| `.env` committed to git | Same as above | `.env` in `.gitignore`, only `.env.example` committed |
+| Key in a frontend bundle | Browser users can read it | Use `setup-browser-extension.md` |
+| Key passed via CLI argv | Shows up in shell history | `dotenv-cli` + `.env` file |
+
+---
+
+## Verification
+
+```ts
+// Get-address smoke test
+console.log(await provider.getWalletAddress());
+
+// Optional: dry-run a balance read
+// (chain-specific — see ../features/<chain>.md)
+```
+
+```bash
+# 1. Type check passes
+pnpm checkTs
+
+# 2. Confirm only one provider import — barrel only
+grep -rn "from '@sodax/wallet-sdk-core" <script-dir>
+# expect zero deep paths like @sodax/wallet-sdk-core/src/...
+```
+
+---
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Invalid EVM wallet config` | Mixed PK and browser-extension fields in one object | Pick **one** variant. Don't pass both `privateKey` and `walletClient`. |
+| TS2322: `'string'` is not assignable to `` `0x${string}` `` | Missing hex prefix or wrong type | Read from env with `as \`0x${string}\`` after a runtime check. |
+| TS: `Property 'secret' is missing` (Injective) | Used `privateKey` at top level | Wrap in `{ secret: { privateKey } }` or `{ secret: { mnemonics } }`. See [`../features/injective.md`](../features/injective.md). |
+| `Cannot find module 'viem/chains'` for unknown chain | Passed an EVM chain key not in `getEvmViemChain` | Use a `ChainKeys.*_MAINNET` constant — the function is exhaustive. |
+
+---
+
+## Next steps
+
+- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — pass the provider to `@sodax/sdk` for swap / lend / bridge / stake.
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — tune the `defaults` slice.
+- [`sign-and-broadcast.md`](./sign-and-broadcast.md) — chain-by-chain raw-tx flow.

package/ai-exported/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.