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

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

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

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

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

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

@@ -1,96 +0,0 @@
-# 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)