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

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

@@ -0,0 +1,103 @@
+# Bitcoin — `BitcoinWalletProvider`
+
+Backed by `bitcoinjs-lib` (PSBT signing), `ecpair`, and `@bitcoinerlab/secp256k1`.
+
+| | |
+|---|---|
+| Class | `BitcoinWalletProvider` |
+| Interface | `IBitcoinWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Explicit uppercase `type`** (`'PRIVATE_KEY' \| 'BROWSER_EXTENSION'`) |
+| Underlying SDK | `bitcoinjs-lib`, `ecpair`, `bip322-js` |
+
+---
+
+## Config
+
+```ts
+type BitcoinWalletConfig = PrivateKeyBitcoinWalletConfig | BrowserExtensionBitcoinWalletConfig;
+
+type PrivateKeyBitcoinWalletConfig = {
+  type: 'PRIVATE_KEY';
+  privateKey: Hex;                     // `0x…` from @sodax/types
+  network: 'TESTNET' | 'MAINNET';
+  addressType?: BtcAddressType;        // P2WPKH / P2TR / P2SH / P2PKH — default chosen by lib
+  defaults?: BitcoinWalletDefaults;
+};
+
+type BrowserExtensionBitcoinWalletConfig = {
+  type: 'BROWSER_EXTENSION';
+  walletsKit: BitcoinWalletsKit;       // consumer-provided adapter
+  network: 'TESTNET' | 'MAINNET';
+  defaults?: BitcoinWalletDefaults;
+};
+
+interface BitcoinWalletsKit {
+  getAccounts(): Promise<string[]>;
+  signPsbt(psbtHex: string): Promise<{ psbtHex: string }>;
+  signMessage(message: string): Promise<string>;
+  signEcdsaMessage(message: string): Promise<string>;
+  signBip322Message(message: string): Promise<string>;
+  getPublicKey(): Promise<string>;
+  sendBitcoin?(toAddress: string, satoshis: number): Promise<string>;
+}
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `config.type === 'PRIVATE_KEY'` |
+| Browser-extension | `config.type === 'BROWSER_EXTENSION'` |
+
+---
+
+## `BitcoinWalletDefaults`
+
+```ts
+type BitcoinWalletDefaults = {
+  defaultFinalize?: boolean;           // default true — finalise after signing
+};
+```
+
+Read directly via `this.defaults.defaultFinalize` — no `mergePolicy` / `mergeDefaults` call. Per-call `finalize` argument on `signTransaction` overrides the default; if both are omitted the implementation falls back to `true`.
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<string>` | BTC address (per address type) |
+| `getPublicKey` | `() => Promise<string>` | hex public key |
+| `getAddressType` | `(address: string) => Promise<BtcAddressType>` | inferred type |
+| `signTransaction` | `(psbtBase64: string, finalize?: boolean) => Promise<string>` | signed PSBT (or finalised tx hex) |
+| `signEcdsaMessage` | `(message: string) => Promise<string>` | ECDSA signature |
+| `signBip322Message` | `(message: string) => Promise<string>` | BIP-322 signature |
+| `getPayment` | `(keyPair, addressType) => bitcoin.Payment` | bitcoinjs `Payment` (PK mode helper) |
+| `sendBitcoin` | `(toAddress: string, satoshis: bigint) => Promise<string>` | tx hash — only available in browser-extension mode if `walletsKit.sendBitcoin` is implemented |
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'BITCOIN'` (literal) | Discriminant. |
+
+`wallet`, `network` are private. Read the network via the constructor argument.
+
+---
+
+## Gotchas
+
+- **The discriminant is `type`, uppercase.** Bitcoin and Stellar use this style — every other chain uses field presence. Easy to confuse.
+- **`addressType` is optional in PK mode.** If you omit it, bitcoinjs picks a default (typically P2WPKH on mainnet). Browser-extension mode infers it from the wallet kit.
+- **PSBT inputs are base64-encoded** when passed to `signTransaction`. In browser-extension mode the same base64 string is forwarded to `walletsKit.signPsbt`; the kit's parameter is misleadingly named `psbtHex` but receives base64. The kit returns a signed PSBT which the provider parses as hex when finalising.
+- **`sendBitcoin` is optional on the wallet kit.** Some browser-extension wallets (Xverse / Unisat) implement it; others don't. Guard on its presence.
+- **`signEcdsaMessage` vs `signBip322Message`** — choose based on what your verifier expects. BIP-322 is the more modern, structured signature spec; ECDSA is the legacy `signmessage` RPC behavior.
+
+---
+
+## 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/evm.md

@@ -0,0 +1,102 @@
+# EVM — `EvmWalletProvider`
+
+Backed by [viem](https://viem.sh). One class covers all **12** SODAX EVM spoke chains via `getEvmViemChain()`.
+
+| | |
+|---|---|
+| Class | `EvmWalletProvider` |
+| Interface | `IEvmWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) |
+| Underlying SDK | `viem` |
+| Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia |
+
+---
+
+## Config
+
+```ts
+type EvmWalletConfig = PrivateKeyEvmWalletConfig | BrowserExtensionEvmWalletConfig;
+
+type PrivateKeyEvmWalletConfig = {
+  privateKey: `0x${string}`;
+  chainId: EvmChainKey;                // ChainKeys.SONIC_MAINNET, …
+  rpcUrl?: `http${string}`;            // defaults to viem chain's first public RPC
+  defaults?: EvmWalletDefaults;
+};
+
+type BrowserExtensionEvmWalletConfig = {
+  walletClient: WalletClient<Transport, Chain, Account>; // pre-built by wagmi / consumer
+  publicClient: PublicClient;
+  defaults?: EvmWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'privateKey' in config` AND `config.privateKey.startsWith('0x')` |
+| Browser-extension | `'walletClient' in config` AND `'publicClient' in config` |
+
+Helper predicates `isPrivateKeyEvmWalletConfig` and `isBrowserExtensionEvmWalletConfig` are exported.
+
+---
+
+## `EvmWalletDefaults`
+
+```ts
+type EvmWalletDefaults = {
+  publicClient?: Partial<Omit<PublicClientConfig, 'transport' | 'chain'>>;
+  walletClient?: Partial<Omit<WalletClientConfig, 'transport' | 'chain' | 'account'>>;
+  transport?: HttpTransportConfig;
+  sendTransaction?: EvmSendTransactionPolicy;      // Omit<Partial<SendTransactionParameters>, keyof EvmRawTransaction>
+  waitForTransactionReceipt?: EvmWaitForTransactionReceiptPolicy; // Partial<Omit<WaitForTransactionReceiptParameters, 'hash'>>
+};
+```
+
+| Default slice | Used by | Effective only in |
+|---|---|---|
+| `publicClient`, `walletClient`, `transport` | constructor | Private-key mode |
+| `sendTransaction` | `sendTransaction()` | Both modes |
+| `waitForTransactionReceipt` | `waitForTransactionReceipt()` | Both modes |
+
+> In browser-extension mode, `publicClient` / `walletClient` / `transport` defaults are **ignored** — the provider logs a one-time `console.warn`. Pass them only in private-key mode.
+
+---
+
+## Methods
+
+| Method | Signature | Returns | Default slice merged |
+|---|---|---|---|
+| `getWalletAddress` | `() => Promise<Address>` | viem `Address` (`` `0x${string}` ``) | — |
+| `sendTransaction` | `(txData: EvmRawTransaction, options?: EvmSendTransactionPolicy) => Promise<Hash>` | viem `Hash` | `defaults.sendTransaction` |
+| `waitForTransactionReceipt` | `(txHash: Hash, options?: EvmWaitForTransactionReceiptPolicy) => Promise<EvmRawTransactionReceipt>` | bigint-stringified receipt | `defaults.waitForTransactionReceipt` |
+
+The serialised receipt converts all `bigint` fields to `string` so it can be `JSON.stringify`'d safely. This is enforced at the type level — `EvmRawTransactionReceipt` (from `@sodax/types`) is the stringified shape.
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'EVM'` (literal) | Discriminant for `IXxxWalletProvider` unions. |
+| `publicClient` | `PublicClient` | Either built from `rpcUrl` (PK mode) or the caller's instance (browser mode). |
+
+`walletClient` is private — call `sendTransaction()` instead of touching it directly.
+
+---
+
+## Gotchas
+
+- **`getEvmViemChain` is exhaustive.** If `@sodax/types` adds a new `EvmChainKey`, this function fails to typecheck until the case is added — by design.
+- **HyperEVM is defined inside this package.** `viem/chains` does not ship a HyperEVM config; `wallet-providers/evm/EvmWalletProvider.ts` exports `hyper` via `defineChain`. You shouldn't need it directly — `getEvmViemChain(ChainKeys.HYPEREVM_MAINNET)` returns it.
+- **`rpcUrl` falls back to the viem chain's first public RPC.** Fine for testing — replace with a private RPC for production.
+- **No nonce management.** The provider does not auto-increment / serialise sends. If you fire multiple txs in parallel from the same account, manage nonces yourself via `defaults.sendTransaction.nonce` or per-call `options.nonce`.
+
+---
+
+## 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/defaults-and-overrides.md`](../recipes/defaults-and-overrides.md)

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

@@ -0,0 +1,88 @@
+# ICON — `IconWalletProvider`
+
+Backed by `icon-sdk-js`. Browser-extension mode targets the Hana wallet's `postMessage` JSON-RPC bridge.
+
+| | |
+|---|---|
+| Class | `IconWalletProvider` |
+| Interface | `IIconWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** (no `type` field) |
+| Underlying SDK | `icon-sdk-js` |
+
+---
+
+## Config
+
+```ts
+type IconWalletConfig = PrivateKeyIconWalletConfig | BrowserExtensionIconWalletConfig;
+
+type PrivateKeyIconWalletConfig = {
+  privateKey: `0x${string}`;
+  rpcUrl: `http${string}`;
+  defaults?: IconWalletDefaults;
+};
+
+type BrowserExtensionIconWalletConfig = {
+  walletAddress?: IconEoaAddress;      // `hx…` — optional; resolved at first sign call if omitted
+  rpcUrl: `http${string}`;
+  defaults?: IconWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Private-key | `'privateKey' in config` |
+| Browser-extension | `'walletAddress' in config` OR `!('privateKey' in config)` (defaults to browser-extension when key absent) |
+
+> `rpcUrl` is **required in both modes** — ICON has no public-RPC fallback in the provider.
+
+---
+
+## `IconWalletDefaults`
+
+```ts
+type IconWalletDefaults = {
+  stepLimit?: number;                  // default 3_000_000
+  version?: string;                    // default '0x3'
+  timestampProvider?: () => number;    // default Date.now() * 1000 (microseconds)
+  jsonRpcId?: number;                  // default 99999 (browser-extension event ID)
+};
+```
+
+---
+
+## Methods
+
+| Method | Signature | Returns | Default slice merged |
+|---|---|---|---|
+| `getWalletAddress` | `() => Promise<IconEoaAddress>` | `hx…` address | — |
+| `sendTransaction` | `(tx: IcxCallTransaction, options?: IconWalletDefaults) => Promise<Hash>` | tx hash | `defaults` (flat merge via `mergeDefaults`) |
+| `waitForTransactionReceipt` | `(txHash: Hash) => Promise<IconTransactionResult>` | tx result | — |
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'ICON'` (literal) | Discriminant. |
+| `iconService` | `IconService` | Underlying SDK service — exposed for advanced use. |
+
+`wallet` is private.
+
+---
+
+## Gotchas
+
+- **Browser-extension mode talks to Hana via `window.postMessage`.** Events use a request-ID — collisions can occur if you fire many parallel calls; tune `defaults.jsonRpcId` if you control the consumer.
+- **`walletAddress` is optional in browser-extension mode.** When omitted, the provider issues a `REQUEST_ADDRESS` event on first use to resolve it. For deterministic behavior in scripts, pass it explicitly.
+- **Address type is branded — `IconEoaAddress` (`hx…`) vs `IconAddress` (`hx… | cx…`).** EOA only at the wallet level; contracts (`cx…`) appear inside tx params, not as the signer.
+- **Timestamps are microseconds.** `timestampProvider` returns microseconds, not milliseconds — the default is `Date.now() * 1000`.
+
+---
+
+## 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/injective.md

@@ -0,0 +1,92 @@
+# Injective — `InjectiveWalletProvider`
+
+Backed by `@injectivelabs/sdk-ts` (signing / msg construction) and `@injectivelabs/wallet-core` (`MsgBroadcaster` for browser flows).
+
+| | |
+|---|---|
+| Class | `InjectiveWalletProvider` |
+| Interface | `IInjectiveWalletProvider` (from `@sodax/types`) |
+| Discriminant style | **Field presence** — but PK variant uses a nested `secret` wrapper |
+| Underlying SDK | `@injectivelabs/sdk-ts`, `@injectivelabs/wallet-core`, `@injectivelabs/networks`, `@injectivelabs/ts-types` |
+
+---
+
+## Config
+
+```ts
+type InjectiveWalletConfig = BrowserExtensionInjectiveWalletConfig | SecretInjectiveWalletConfig;
+
+type BrowserExtensionInjectiveWalletConfig = {
+  msgBroadcaster: MsgBroadcaster;           // pre-configured by consumer
+  defaults?: InjectiveWalletDefaults;
+};
+
+type SecretInjectiveWalletConfig = {
+  secret: { privateKey: string } | { mnemonics: string };
+  chainId: ChainId;                          // from @injectivelabs/ts-types
+  network: Network;                          // from @injectivelabs/networks
+  evmOptions?: { evmChainId: EvmChainId; rpcUrl: `http${string}` };  // reserved — currently unused
+  defaults?: InjectiveWalletDefaults;
+};
+```
+
+| Mode discriminant | How to detect |
+|---|---|
+| Browser-extension | `'msgBroadcaster' in config` |
+| Secret (private-key OR mnemonics) | `'secret' in config` |
+
+> Note the naming: the second variant is `SecretInjectiveWalletConfig` (not `PrivateKey…`) because it accepts **either** a private key **or** a BIP-39 mnemonic at the `secret` slot. The dual credential shape mirrors `PrivateKey.fromPrivateKey` / `PrivateKey.fromMnemonic` in `@injectivelabs/sdk-ts`.
+
+---
+
+## `InjectiveWalletDefaults`
+
+```ts
+type InjectiveWalletDefaults = {
+  defaultFunds?: InjectiveCoin[];      // attached to getRawTransaction/execute if caller omits
+  defaultMemo?: string;                // default tx memo
+  sequence?: number;                   // createTransaction override — default 0
+  accountNumber?: number;              // createTransaction override — default 0
+};
+```
+
+> `MsgBroadcaster` options apply at **construction time only** (private-key path). The upstream `MsgBroadcasterWithPk` does not support post-construction reconfig.
+
+---
+
+## Methods
+
+| Method | Signature | Returns |
+|---|---|---|
+| `getWalletAddress` | `() => Promise<InjectiveEoaAddress>` | `inj1…` address |
+| `getWalletPubKey` | `() => Promise<string>` | hex pubkey |
+| `getRawTransaction` | `(…) => Promise<…>` | unsigned tx — useful for inspection / external signing |
+| `execute` | `(…) => Promise<…>` | broadcast result |
+
+`getRawTransaction` and `execute` merge `defaults.defaultFunds`, `defaults.defaultMemo`, `defaults.sequence`, `defaults.accountNumber` into the produced tx where the caller omits them.
+
+---
+
+## Public fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `chainType` | `'INJECTIVE'` (literal) | Discriminant. |
+| `wallet` | `InjectiveWallet` | `{ msgBroadcaster: MsgBroadcaster \| MsgBroadcasterWithPk }` — exposed for advanced consumers. |
+
+---
+
+## Gotchas
+
+- **`secret` is mandatory in the PK variant.** A top-level `privateKey` field is **not** accepted — wrap in `{ secret: { privateKey } }`. Same shape in v1 and v2; if you see top-level `privateKey` in user code, it was always wrong.
+- **`evmOptions` is reserved.** It is declared in the type but **not currently read** by the provider. It exists to keep the config shape stable while EVM sidecar support on Injective is in development.
+- **`chainId` and `network` must agree.** Pass `Mainnet` + `injective-1` for mainnet, `Testnet` + `injective-888` for testnet. Mismatched pairs cause broadcasting errors that look like RPC failures.
+- **`sequence` / `accountNumber` defaults are zero.** Override via `defaults` or per call when the on-chain account state differs (otherwise broadcasting fails with "incorrect account sequence").
+
+---
+
+## 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/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