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

package/ai-exported/integration/features/near.md

@@ -0,0 +1,92 @@
+# NEAR — `NearWalletProvider`
+
+Backed by `near-api-js` (PK signing) and `@hot-labs/near-connect` (browser-extension `NearConnector`).
+
+| | |
+|---|---|
+| Class | `NearWalletProvider` |
+| Interface | `INearWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) |
+| Underlying SDK | `near-api-js`, `@hot-labs/near-connect` |
+
+---
+
+## Config
+
+```ts
+type NearWalletConfig = PrivateKeyNearWalletConfig | BrowserExtensionNearWalletConfig;
+
+type PrivateKeyNearWalletConfig = {
+  rpcUrl: string;
+  accountId: string;                   // e.g. 'alice.near'
+  privateKey: string;                  // 'ed25519:…' format
+  defaults?: NearWalletDefaults;
+};
+
+type BrowserExtensionNearWalletConfig = {
+  wallet: NearConnector;               // from @hot-labs/near-connect
+  defaults?: NearWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'privateKey' in config` (also `accountId`, `rpcUrl`) |
+| Browser-extension | `'wallet' in config` |
+
+---
+
+## `NearWalletDefaults`
+
+```ts
+type NearWalletDefaults = {
+  throwOnFailure?: boolean;            // default true — PK path only
+  waitUntil?: NearTxExecutionStatus;   // default 'FINAL'
+  gasDefault?: bigint;                 // applied if tx omits gas
+  depositDefault?: bigint;             // applied if tx omits deposit
+};
+
+type NearTxExecutionStatus =
+  | 'NONE' | 'INCLUDED' | 'EXECUTED_OPTIMISTIC' | 'INCLUDED_FINAL' | 'EXECUTED' | 'FINAL';
+```
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | accountId (e.g. `alice.near`) |
+| `getRawTransaction` | `(params: CallContractParams) => Promise<NearRawTransaction>` | unsigned tx — useful for inspection |
+| `signAndSubmitTxn` | `(transaction: NearRawTransaction, options?: NearWalletDefaults) => Promise<string>` | tx hash |
+
+`signAndSubmitTxn` merges `defaults` (flat) over per-call `options`.
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'NEAR'` (literal) | Discriminant. |
+| `account` | `Account \| undefined` | PK mode only — `near-api-js` `Account`. |
+| `rpcProvider` | `JsonRpcProvider \| undefined` | PK mode only. |
+
+`wallet` (`NearConnector`) is private. Browser-extension mode exposes neither `account` nor `rpcProvider`.
+
+---
+
+## Gotchas
+
+- **`privateKey` is the full `ed25519:…` string**, not just the bytes. NEAR stores keys with the algorithm prefix.
+- **`accountId` is mandatory in PK mode.** NEAR keys don't determine the account — accounts can hold multiple keys. The provider needs both.
+- **`waitUntil` defaults to `'FINAL'`.** Slowest but safest. Lower (`'EXECUTED'`) for faster scripts, with the usual caveats about reverts.
+- **Browser-extension mode uses `@hot-labs/near-connect`'s `NearConnector`.** It already abstracts over multiple NEAR wallets (Meteor, MyNearWallet, …) — pass the connector instance, not a lower-level wallet object.
+
+---
+
+## 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/ai-exported/integration/features/solana.md

@@ -0,0 +1,104 @@
+# Solana — `SolanaWalletProvider`
+
+Backed by `@solana/web3.js` and `@solana/wallet-adapter-base` interfaces.
+
+| | |
+|---|---|
+| Class | `SolanaWalletProvider` |
+| Interface | `ISolanaWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) |
+| Underlying SDK | `@solana/web3.js` |
+
+---
+
+## Config
+
+```ts
+type SolanaWalletConfig = PrivateKeySolanaWalletConfig | BrowserExtensionSolanaWalletConfig;
+
+type PrivateKeySolanaWalletConfig = {
+  privateKey: Uint8Array;              // secret key bytes — usually length 64
+  endpoint: string;                    // RPC URL
+  defaults?: SolanaWalletDefaults;
+};
+
+type BrowserExtensionSolanaWalletConfig = {
+  wallet: WalletContextState;          // { publicKey, signTransaction }
+  endpoint: string;
+  defaults?: SolanaWalletDefaults;
+};
+
+interface WalletContextState {
+  publicKey: PublicKey | null;
+  signTransaction: SignerWalletAdapterProps['signTransaction'] | undefined;
+}
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'privateKey' in config` |
+| Browser-extension | `'wallet' in config` |
+
+---
+
+## `SolanaWalletDefaults`
+
+```ts
+type SolanaWalletDefaults = {
+  connectionCommitment?: Commitment;      // for Connection ctor — default 'confirmed'
+  connectionConfig?: ConnectionConfig;    // overrides connectionCommitment if present
+  sendOptions?: SendOptions;              // default for sendRawTransaction
+  confirmCommitment?: Commitment;         // for confirmation polling — default 'finalized'
+};
+```
+
+`connectionConfig` is the full ConnectionConfig — if you set it, `connectionCommitment` is ignored.
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | base58 public key |
+| `getWalletBase58PublicKey` | `() => SolanaBase58PublicKey` | synchronous public key |
+| `sendTransaction` | `(rawTx: SolanaSerializedTransaction, options?: SendOptions) => Promise<string>` | signature |
+| `sendTransactionWithConfirmation` | `(rawTx, sendOptions?, confirmCommitment?) => Promise<string>` | signature, after confirmation |
+| `waitForConfirmation` | `(signature, commitment?) => Promise<…>` | confirmation status |
+| `buildV0Txn` | `(rawInstructions: SolanaRawTransactionInstruction[]) => Promise<SolanaSerializedTransaction>` | serialised v0 transaction |
+| `getAssociatedTokenAddress` | `(mint) => Promise<SolanaBase58PublicKey>` | derived ATA |
+| `getBalance` | `(publicKey) => Promise<number>` | lamports |
+| `getTokenAccountBalance` | `(publicKey) => Promise<RpcResponseAndContext<TokenAmount>>` | SPL balance |
+
+Default slice merging:
+- `defaults.sendOptions` → merged into `sendTransaction(_, options)`.
+- `defaults.confirmCommitment` → falls back when `sendTransactionWithConfirmation(_, _, commit)` is undefined.
+- `defaults.connectionCommitment` / `defaults.connectionConfig` → used at construction time only.
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'SOLANA'` (literal) | Discriminant. |
+| `connection` | `Connection` | The web3.js Connection, derived from `endpoint` + defaults. |
+
+`wallet` (Keypair or `WalletContextState`) is private — call provider methods instead.
+
+---
+
+## Gotchas
+
+- **`buildV0Txn` is the canonical path for building transactions.** It picks the keypair-vs-adapter signing path internally based on construction mode. Don't construct transactions yourself.
+- **`WalletContextState.signTransaction` is allowed to be `undefined`.** This mirrors `@solana/wallet-adapter-base` — the adapter may not implement signing for all flows. The provider throws at signing time if `signTransaction` is missing.
+- **`confirmCommitment` defaults to `'finalized'`.** Slow but safe. Lower (`'confirmed'`) for faster UX, with the usual finality caveats.
+- **`endpoint` is a required field.** There is no public-RPC fallback like EVM has.
+
+---
+
+## 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/ai-exported/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/ai-exported/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/ai-exported/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)