@sodax/skills 2.0.0-rc.4

package/knowledge/wallet-sdk-core/integration/features/stacks.md

@@ -0,0 +1,91 @@
+# Stacks — `StacksWalletProvider`
+
+Backed by `@stacks/transactions` and `@stacks/connect` (browser-extension `StacksProvider`).
+
+| | |
+|---|---|
+| Class | `StacksWalletProvider` |
+| Interface | `IStacksWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) |
+| Underlying SDK | `@stacks/transactions`, `@stacks/connect`, `@stacks/network` |
+
+---
+
+## Config
+
+```ts
+type StacksWalletConfig = PrivateKeyStacksWalletConfig | BrowserExtensionStacksWalletConfig;
+
+type PrivateKeyStacksWalletConfig = {
+  privateKey: string;
+  endpoint?: string;                   // Stacks API endpoint
+  defaults?: StacksWalletDefaults;
+};
+
+type BrowserExtensionStacksWalletConfig = {
+  address: string;                     // 'SP…' (mainnet) or 'ST…' (testnet)
+  endpoint?: string;
+  provider?: StacksProvider;           // from @stacks/connect — optional
+  defaults?: StacksWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'privateKey' in config` |
+| Browser-extension | `'address' in config` (no `privateKey`) |
+
+---
+
+## `StacksWalletDefaults`
+
+```ts
+type StacksWalletDefaults = {
+  network?: 'mainnet' | 'testnet';     // default 'mainnet'
+  postConditionMode?: PostConditionMode;
+};
+```
+
+`PostConditionMode` is re-exported as a runtime value from this package — see [`recipes/library-exports.md`](../recipes/library-exports.md).
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | Stacks address (`SP…` / `ST…`) |
+| `getPublicKey` | `() => Promise<string>` | hex pubkey |
+| `sendTransaction` | `(params: StacksTransactionParams) => Promise<…>` | tx response |
+| `readContract` | `(txParams: StacksTransactionParams) => Promise<ClarityValue>` | read-only call result |
+| `getBalance` | `(address: string) => Promise<bigint>` | STX micro-balance |
+
+Internally `sendTransaction` dispatches to `sendTransactionWithPrivateKey` or `sendTransactionWithAdapter` based on construction mode.
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'STACKS'` (literal) | Discriminant. |
+
+`network` (`StacksNetwork`) and `wallet` are private.
+
+---
+
+## Gotchas
+
+- **`endpoint` is optional.** Defaults to the Hiro mainnet/testnet API URL depending on `network`. Override for private RPCs.
+- **`provider` (StacksProvider) is optional in browser-extension mode.** When omitted, the provider falls back to the globally-injected `window`-level provider (Leather, Xverse, Asigna). Pass it explicitly for tests or non-injected environments.
+- **`postConditionMode` is a runtime enum.** Import from `@sodax/wallet-sdk-core` (re-exported via `library-exports`) — no need to add `@stacks/transactions` as a direct dep.
+- **Mainnet vs testnet split.** `network: 'mainnet'` resolves to `STACKS_MAINNET`; `'testnet'` to `STACKS_TESTNET`. Cross-environment addresses will reject.
+
+---
+
+## See also
+
+- [`recipes/setup-private-key.md`](../recipes/setup-private-key.md)
+- [`recipes/setup-browser-extension.md`](../recipes/setup-browser-extension.md)
+- [`recipes/sign-and-broadcast.md`](../recipes/sign-and-broadcast.md)
+- [`recipes/library-exports.md`](../recipes/library-exports.md) — `PostConditionMode` enum

package/knowledge/wallet-sdk-core/integration/features/stellar.md

@@ -0,0 +1,95 @@
+# Stellar — `StellarWalletProvider`
+
+Backed by `@stellar/stellar-sdk` (`Horizon.Server` + Soroban primitives).
+
+| | |
+|---|---|
+| Class | `StellarWalletProvider` |
+| Interface | `IStellarWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Explicit uppercase `type`** (`'PRIVATE_KEY' \| 'BROWSER_EXTENSION'`) |
+| Underlying SDK | `@stellar/stellar-sdk` |
+
+---
+
+## Config
+
+```ts
+type StellarWalletConfig = PrivateKeyStellarWalletConfig | BrowserExtensionStellarWalletConfig;
+
+type PrivateKeyStellarWalletConfig = {
+  type: 'PRIVATE_KEY';
+  privateKey: Hex;                     // `0x…`
+  network: 'TESTNET' | 'PUBLIC';
+  rpcUrl?: string;                     // defaults to a public Horizon URL per network
+  defaults?: StellarWalletDefaults;
+};
+
+type BrowserExtensionStellarWalletConfig = {
+  type: 'BROWSER_EXTENSION';
+  walletsKit: StellarWalletsKit;       // Freighter / xBull / Lobstr adapter
+  network: 'TESTNET' | 'PUBLIC';
+  rpcUrl?: string;
+  defaults?: StellarWalletDefaults;
+};
+
+interface StellarWalletsKit {
+  getAddress(): Promise<{ address: string }>;
+  signTransaction(tx: XDR, options: { networkPassphrase: string }): Promise<{ signedTxXdr: XDR }>;
+}
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `config.type === 'PRIVATE_KEY'` |
+| Browser-extension | `config.type === 'BROWSER_EXTENSION'` |
+
+---
+
+## `StellarWalletDefaults`
+
+```ts
+type StellarWalletDefaults = {
+  pollInterval?: number;               // ms — default 2_000
+  pollTimeout?: number;                // ms — default 60_000 (≥ 30_000 recommended on mainnet)
+  networkPassphrase?: string;          // override for FUTURENET / private networks
+};
+```
+
+Merge strategy: flat (`mergeDefaults`).
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | Stellar address |
+| `signTransaction` | `(tx: XDR) => Promise<XDR>` | signed XDR |
+| `waitForTransactionReceipt` | `(hash: string, options?: Partial<StellarWalletDefaults>) => Promise<…>` | tx result; respects `pollInterval` / `pollTimeout` |
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'STELLAR'` (literal) | Discriminant. |
+
+`wallet`, `server` (`Horizon.Server`), and `networkPassphrase` are private. Pass overrides via `defaults` instead of mutating fields.
+
+---
+
+## Gotchas
+
+- **`networkPassphrase` is derived from `network`.** Override via `defaults.networkPassphrase` only for FUTURENET or private networks.
+- **`rpcUrl` defaults to a public Horizon endpoint.** Replace with a private RPC for production.
+- **`pollTimeout` floor of 30_000 ms is a strong recommendation, not enforced.** Mainnet confirmation typically takes 5–30 s. Setting it too low surfaces false negatives.
+- **Stellar uses XDR strings** for both transaction input and signed output — the type alias `XDR` is from `@sodax/types`.
+
+---
+
+## See also
+
+- [`recipes/setup-private-key.md`](../recipes/setup-private-key.md)
+- [`recipes/setup-browser-extension.md`](../recipes/setup-browser-extension.md)
+- [`recipes/sign-and-broadcast.md`](../recipes/sign-and-broadcast.md)

package/knowledge/wallet-sdk-core/integration/features/sui.md

@@ -0,0 +1,96 @@
+# Sui — `SuiWalletProvider`
+
+Backed by `@mysten/sui` and `@mysten/wallet-standard`.
+
+| | |
+|---|---|
+| Class | `SuiWalletProvider` |
+| Interface | `ISuiWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) — but uses `mnemonics`, not `privateKey` |
+| Underlying SDK | `@mysten/sui`, `@mysten/wallet-standard` |
+
+---
+
+## Config
+
+```ts
+type SuiWalletConfig = PrivateKeySuiWalletConfig | BrowserExtensionSuiWalletConfig;
+
+type PrivateKeySuiWalletConfig = {
+  rpcUrl: string;
+  mnemonics: string;                   // BIP-39 mnemonic — NOT a raw private key
+  defaults?: SuiWalletDefaults;
+};
+
+type BrowserExtensionSuiWalletConfig = {
+  client: SuiClient;                                    // pre-built by consumer
+  wallet: WalletWithFeatures<Partial<SuiWalletFeatures>>;
+  account: WalletAccount;                               // active account from wallet
+  defaults?: SuiWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'mnemonics' in config` |
+| Browser-extension | `'client' in config` (also requires `wallet` + `account`) |
+
+Note the name — `PrivateKeySuiWalletConfig` is still called "PrivateKey" for consistency, even though the credential is a mnemonic. The library derives an Ed25519 keypair from the mnemonic phrase.
+
+---
+
+## `SuiWalletDefaults`
+
+```ts
+type SuiWalletDefaults = {
+  signAndExecuteTxn?: {
+    dryRun?: { enabled?: boolean };           // default: enabled = true
+    response?: SuiTransactionBlockResponseOptions;
+  };
+  getCoins?: { limit?: number };
+};
+```
+
+---
+
+## Methods
+
+| Method | Signature | Returns | Default slice merged |
+|---|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | Sui address | — |
+| `signAndExecuteTxn` | `(txn: SuiTransaction, options?: SuiSignAndExecutePolicy) => Promise<string>` | digest | `defaults.signAndExecuteTxn` |
+| `viewContract` | `(txn: SuiTransaction, …) => Promise<…>` | dry-run result | — |
+| `getCoins` | `(address: string, token: string, options?: SuiGetCoinsPolicy) => Promise<SuiPaginatedCoins>` | coin pagination | `defaults.getCoins` |
+
+`signAndExecuteTxn` runs a **pre-flight dry-run by default**. Disable only when paying gas for a doomed tx is acceptable:
+
+```ts
+await provider.signAndExecuteTxn(tx, { dryRun: { enabled: false } });
+```
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'SUI'` (literal) | Discriminant. |
+
+The internal `client: SuiClient` and `wallet: SuiWallet` are private.
+
+---
+
+## Gotchas
+
+- **Browser-extension mode requires THREE objects.** Many wallet adapters expose `client` + `wallet` but not the active `account`. Fetch it via `wallet.accounts[0]` or your adapter's "current account" API before constructing the provider.
+- **Mnemonic is the only private-key option.** There is no raw-secret-key constructor. If you have a 32-byte key bytes you must convert it to a mnemonic upstream (or fork the provider).
+- **Dry-run is on by default for safety.** Production scripts almost never want to disable it.
+- **`response` options forward to the underlying SuiClient call.** In PK mode that's `signAndExecuteTransaction`; in browser-extension mode it's `executeTransactionBlock`. Same option shape (`SuiTransactionBlockResponseOptions`).
+
+---
+
+## See also
+
+- [`recipes/setup-private-key.md`](../recipes/setup-private-key.md)
+- [`recipes/setup-browser-extension.md`](../recipes/setup-browser-extension.md)
+- [`recipes/sign-and-broadcast.md`](../recipes/sign-and-broadcast.md)

package/knowledge/wallet-sdk-core/integration/quickstart.md

@@ -0,0 +1,259 @@
+# 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/knowledge/wallet-sdk-core/integration/recipes/README.md

@@ -0,0 +1,15 @@
+# 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.