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

package/ai-exported/integration/architecture.md

@@ -1,212 +0,0 @@
-# Architecture — Mental Model
-
-This file explains **why** `@sodax/wallet-sdk-core` is shaped the way it is. Read it once before applying recipes — knowing the model lets you handle ambiguous user code without guessing.
-
-If you are looking for "how do I do X", go to [`recipes/`](./recipes/) or [`features/`](./features/). This file is purely conceptual.
-
----
-
-## The shape of the package
-
-`@sodax/wallet-sdk-core` is a **uniform low-level wallet layer over heterogeneous chain SDKs**. For each of the 9 chain families that SODAX supports, the package ships:
-
-1. A `*WalletProvider` **class** that implements a chain-specific interface (`IEvmWalletProvider`, `ISolanaWalletProvider`, …) imported from `@sodax/types`.
-2. A discriminated-union **config type** (`*WalletConfig = PrivateKey* | BrowserExtension*`).
-3. A `*WalletDefaults` type — the per-method default option shape merged into each call.
-
-Each provider class extends a small abstract `BaseWalletProvider<TDefaults>`. That base holds the `defaults` reference and exposes two helpers:
-
-- `mergePolicy(key, options)` — shallow-merges per-call options over `defaults[key]`. Used when defaults are grouped per method (e.g. `defaults.sendTransaction`).
-- `mergeDefaults(options)` — shallow-merges per-call options over the entire flat `defaults`. Used when defaults are not grouped.
-
-Subclasses do three things on top:
-
-1. Declare a `chainType` literal (`'EVM' as const`, `'BITCOIN' as const`, …).
-2. Discriminate the config and initialize chain-specific state (viem client, Solana `Connection`, `SuiClient`, …).
-3. Implement the chain-specific interface methods (`sendTransaction`, `signTransaction`, …).
-
-Consumers only ever see the public surface: construct the class with one of the union variants, call its methods, and hand the instance to `@sodax/sdk` via its `IXxxWalletProvider` interface.
-
----
-
-## File-system tour
-
-```
-src/
-├── index.ts                          # Barrel: re-exports wallet-providers + types
-├── types/
-│   ├── index.ts                      # Re-exports library-exports
-│   └── library-exports.ts            # Re-exported types (and a few enums) from upstream chain SDKs
-├── utils/                            # Internal — shallowMerge; NOT re-exported
-│   ├── index.ts
-│   ├── merge.ts
-│   └── merge.test.ts
-└── wallet-providers/
-    ├── index.ts                      # Barrel: re-exports every provider folder
-    ├── BaseWalletProvider.ts         # Abstract base class
-    ├── evm/
-    │   ├── EvmWalletProvider.ts
-    │   ├── EvmWalletProvider.test.ts
-    │   ├── types.ts
-    │   └── index.ts
-    ├── solana/   { …same shape… }
-    ├── sui/      { …same shape… }
-    ├── bitcoin/  { …same shape… }
-    ├── stellar/  { …same shape… }
-    ├── icon/     { …same shape… }
-    ├── injective/{ …same shape… }
-    ├── near/     { …same shape… }
-    └── stacks/   { …same shape… }
-```
-
-Three things to internalize:
-
-1. **The package root is the only public surface.** `src/utils/*` is internal — `shallowMerge` etc. are deliberately not re-exported.
-2. **Each chain is folder-isolated.** Adding a new chain means creating a folder under `src/wallet-providers/<chain>/` and listing it in `wallet-providers/index.ts`. Nothing else changes.
-3. **`types/library-exports.ts` is the indirection point** between upstream chain SDKs and consumers. Re-exporting from here means consumer apps don't need direct deps on `viem`, `@mysten/sui`, etc. for type-only usage.
-
----
-
-## `BaseWalletProvider` and the `defaults` model
-
-```ts
-abstract class BaseWalletProvider<TDefaults extends object> {
-  protected readonly defaults: TDefaults;
-
-  constructor(defaults: TDefaults | undefined) {
-    this.defaults = (defaults ?? {}) as TDefaults;
-  }
-
-  abstract getWalletAddress(): Promise<string>;
-
-  protected mergePolicy<K extends keyof TDefaults>(key: K, options?: …): … { /* shallowMerge */ }
-  protected mergeDefaults(options?: Partial<TDefaults>): TDefaults { /* shallowMerge */ }
-}
-```
-
-Three rules govern the `defaults` model:
-
-1. **Every field of `TDefaults` is optional.** The constructor falls back to `{}` if the consumer omits `defaults` entirely. Required fields would silently arrive as `undefined` at runtime without TypeScript catching it — see the JSDoc comment in `BaseWalletProvider.ts`.
-2. **Merge is shallow.** Top-level keys merge; nested objects are **replaced wholesale**. If `defaults.sendTransaction = { gas: 3_000_000n, nonce: 0 }` and the caller passes `{ gas: 5_000_000n }`, the merged policy is `{ gas: 5_000_000n }` — `nonce` is dropped. See `src/utils/merge.ts`. The behaviour is intentional: deep merge would silently smuggle stale fields across call sites.
-3. **`undefined` layers and `undefined` values are skipped.** Passing `{ field: undefined }` does **not** override an earlier layer — the merge treats `undefined` as "no opinion".
-
-Two helpers exist because chains group their defaults differently:
-
-- **Per-method grouping** — `mergePolicy('sendTransaction', options)` looks up `defaults.sendTransaction` and merges `options` over it. Used by EVM (`sendTransaction`, `waitForTransactionReceipt`), Sui (`signAndExecuteTxn`, `getCoins`).
-- **Flat grouping** — `mergeDefaults(options)` merges `options` over the whole `defaults` object. Used by chains whose `defaults` is a flat record (Bitcoin's `{ defaultFinalize }`, Stellar's `{ pollInterval, pollTimeout, networkPassphrase }`).
-
-For a concrete worked example see [`recipes/defaults-and-overrides.md`](./recipes/defaults-and-overrides.md).
-
----
-
-## Discriminant variants
-
-Every chain supports two construction modes — but the discriminant **looks different per chain**. The rule of thumb:
-
-| Discriminant style | Chains | Example |
-|---|---|---|
-| **Field presence** (no `type` field) | EVM, Solana, Sui, ICON, Injective, NEAR, Stacks | EVM: `privateKey + chainId` → private-key. `walletClient + publicClient` → browser-extension. |
-| **Explicit uppercase `type`** | Bitcoin, Stellar | `{ type: 'PRIVATE_KEY', … }` vs `{ type: 'BROWSER_EXTENSION', … }` |
-
-Why the inconsistency: the field-presence form is shorter for the common case but only works when the two variants share **zero** required-field overlap. Bitcoin and Stellar have shared required fields (`network`, `walletsKit` shapes that overlap with PK fields) that would make field presence ambiguous, so they use explicit `type`.
-
-Two more wrinkles to know about:
-
-- **Sui uses `mnemonics`, not `privateKey`.** The library derives an Ed25519 keypair from the mnemonic phrase. There is no raw-secret-key option.
-- **Injective uses a nested `secret` object.** Because Injective can be constructed from **either** a private key **or** a BIP-39 mnemonic, the private-key variant nests credentials under `secret: { privateKey } | { mnemonics }` instead of placing them at the top level. The type is named `SecretInjectiveWalletConfig` (not `PrivateKey*`) to reflect this.
-
-For chain-by-chain breakdowns see [`features/`](./features/).
-
----
-
-## `library-exports` — the upstream-SDK indirection
-
-`src/types/library-exports.ts` re-exports a curated set of types (and a few runtime values) from each upstream chain SDK:
-
-```ts
-// viem types
-export type { Account, Address, Chain, Transport, PublicClient, WalletClient,
-              HttpTransportConfig, PublicClientConfig, WalletClientConfig,
-              SendTransactionParameters, WaitForTransactionReceiptParameters,
-              TransactionReceipt } from 'viem';
-
-// Sui types
-export type { SuiTransactionBlockResponseOptions } from '@mysten/sui/client';
-export type { Transaction, TransactionArgument } from '@mysten/sui/transactions';
-export type { SuiWalletFeatures, WalletAccount, WalletWithFeatures } from '@mysten/wallet-standard';
-
-// Solana types
-export type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
-
-// Injective types
-export type { Network } from '@injectivelabs/networks';
-export type { ChainId, EvmChainId } from '@injectivelabs/ts-types';
-export type { MsgBroadcaster } from '@injectivelabs/wallet-core';
-
-// Stellar (also re-exports the `Networks` runtime value)
-export { Networks } from '@stellar/stellar-sdk';
-
-// Stacks (also re-exports the `PostConditionMode` enum)
-export { PostConditionMode } from '@stacks/transactions';
-export type { ClarityValue, PostConditionModeName } from '@stacks/transactions';
-export type { StacksNetwork } from '@stacks/network';
-export type { StacksProvider } from '@stacks/connect';
-
-// Near
-export type { KeyPairString } from 'near-api-js';
-export type { NearConnector } from '@hot-labs/near-connect';
-
-// Bitcoin
-export type { Network as BitcoinJsNetwork } from 'bitcoinjs-lib/src/networks.js';
-```
-
-Consumers can import the types they need directly from `@sodax/wallet-sdk-core` instead of adding `viem`, `@mysten/sui`, etc. to their `package.json`:
-
-```ts
-import type { WalletClient, PublicClient, TransactionReceipt } from '@sodax/wallet-sdk-core';
-```
-
-Note the file name: `library-exports`, not `library-types`. It deliberately re-exports a small number of **runtime** values (`Networks`, `PostConditionMode`) — hence the broader name.
-
-For the typical reasons to use it (and when not to), see [`recipes/library-exports.md`](./recipes/library-exports.md).
-
----
-
-## The `IXxxWalletProvider` interface — your handoff to `@sodax/sdk`
-
-Each provider class implements a chain-specific interface from `@sodax/types`:
-
-```ts
-class EvmWalletProvider extends BaseWalletProvider<EvmWalletDefaults> implements IEvmWalletProvider { … }
-class BitcoinWalletProvider extends BaseWalletProvider<BitcoinWalletDefaults> implements IBitcoinWalletProvider { … }
-// …and so on
-```
-
-When you call `@sodax/sdk` methods, the SDK expects the **interface**, not the concrete class:
-
-```ts
-import type { IEvmWalletProvider } from '@sodax/types';
-
-async function deposit(evmProvider: IEvmWalletProvider) { /* … */ }
-
-const evm = new EvmWalletProvider({ … });
-await deposit(evm);  // ✅ EvmWalletProvider implements IEvmWalletProvider
-```
-
-This indirection is how the SDK stays decoupled from `wallet-sdk-core`. In a React app, `useWalletProvider({ xChainId })` from `@sodax/wallet-sdk-react` returns the interface directly — the React layer constructs the concrete class internally.
-
-For the full interface signatures, see [`reference/interfaces.md`](./reference/interfaces.md).
-
----
-
-## Things that look weird until you know why
-
-- **`InjectiveWalletConfig` is `BrowserExtensionInjectiveWalletConfig | SecretInjectiveWalletConfig`** — note the `Secret*` (not `PrivateKey*`) name. It also accepts mnemonics, hence the broader name. See [`features/injective.md`](./features/injective.md).
-- **EVM in browser-extension mode ignores `defaults.transport`, `defaults.publicClient`, and `defaults.walletClient`.** Because the consumer supplied pre-built clients, these defaults are no-ops — the provider logs a one-time `console.warn`. Pass them only in private-key mode. See `EvmWalletProvider.ts`.
-- **HyperEVM is defined inside this package.** `viem/chains` does not ship a HyperEVM config, so `wallet-providers/evm/EvmWalletProvider.ts` exports a `hyper` chain object via `defineChain`. You shouldn't need to import it directly — `getEvmViemChain(ChainKeys.HYPEREVM_MAINNET)` returns it.
-- **`getEvmViemChain(key)` is exhaustively typed.** The default branch is a `never`-assertion — if `@sodax/types` adds a new `EvmChainKey` value, this function fails to typecheck until the case is added. That's by design.
-- **Sui browser-extension mode requires THREE objects** — `client`, `wallet`, and `account`. Many wallet adapters expose the first two but not the third. See [`features/sui.md`](./features/sui.md).
-- **Stellar requires `rpcUrl` in both modes** (technically optional, but defaults to a public RPC). Use a private RPC for production.
-- **Bitcoin in private-key mode also takes an optional `addressType`** (P2WPKH / P2TR / …). Browser-extension mode infers it from the wallet kit.
-
-Everything else is covered by [`features/`](./features/) on a per-chain basis.

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

@@ -1,22 +0,0 @@
-# Per-chain feature docs
-
-One file per chain family. Each file documents:
-
-- The provider class and the discriminated union of accepted configs.
-- The `*Defaults` shape.
-- The methods exposed on the provider (and how they merge defaults).
-- Common gotchas specific to the chain.
-
-| Chain family | Provider | Discriminant style | Underlying SDK |
-|---|---|---|---|
-| [EVM](./evm.md)           | `EvmWalletProvider`       | Field presence (no `type`) | `viem` |
-| [Solana](./solana.md)     | `SolanaWalletProvider`    | Field presence | `@solana/web3.js` |
-| [Sui](./sui.md)           | `SuiWalletProvider`       | Field presence (uses `mnemonics`) | `@mysten/sui` + `@mysten/wallet-standard` |
-| [Bitcoin](./bitcoin.md)   | `BitcoinWalletProvider`   | Explicit `type` | `bitcoinjs-lib`, `ecpair`, `secp256k1` |
-| [Stellar](./stellar.md)   | `StellarWalletProvider`   | Explicit `type` | `@stellar/stellar-sdk` |
-| [ICON](./icon.md)         | `IconWalletProvider`      | Field presence | `icon-sdk-js` |
-| [Injective](./injective.md)| `InjectiveWalletProvider` | Field presence (uses `secret` wrapper) | `@injectivelabs/sdk-ts`, `@injectivelabs/wallet-core` |
-| [NEAR](./near.md)         | `NearWalletProvider`      | Field presence | `near-api-js` + `@hot-labs/near-connect` |
-| [Stacks](./stacks.md)     | `StacksWalletProvider`    | Field presence | `@stacks/transactions`, `@stacks/connect` |
-
-For the mental model behind these tables — why discriminants differ, how `defaults` merges, what `library-exports` re-exports — see [`../architecture.md`](../architecture.md).

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

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

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

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

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