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

package/ai-exported/integration/recipes/chain-key-narrowing.md

@@ -0,0 +1,65 @@
+# Chain-key narrowing (cast-at-boundary)
+
+When you have a runtime chain key (e.g. user-selected from a UI) and need a chain-narrowed wallet provider, narrow once at the boundary and let the narrowed binding flow downstream.
+
+### Narrowing inside a feature flow
+
+```ts
+import { ChainKeys, type GetWalletProviderType } from '@sodax/sdk';
+
+function isStellar(chainKey: SpokeChainKey): chainKey is typeof ChainKeys.STELLAR_MAINNET {
+  return chainKey === ChainKeys.STELLAR_MAINNET;
+}
+
+const stellarWp = isStellar(srcChainKey)
+  ? (walletProvider as GetWalletProviderType<typeof ChainKeys.STELLAR_MAINNET> | undefined)
+  : undefined;
+
+if (stellarWp) {
+  await checkStellarTrustline({ token, amount, walletProvider: stellarWp });
+}
+```
+
+The cast is local — the `isStellar` guard proves correctness at runtime. **Don't propagate the cast** beyond the narrowed binding; downstream code reads `stellarWp` as the chain-specific type without further casts.
+
+### The `chainType` runtime alternative
+
+Every `I*WalletProvider` has a `readonly chainType: '<CHAIN>'` literal. Use it when you don't have the chain key in scope but do have a wallet provider:
+
+```ts
+if (walletProvider.chainType === 'BITCOIN') {
+  // walletProvider: IBitcoinWalletProvider
+  await checkBitcoinPSBT(walletProvider);
+}
+```
+
+No `as` cast needed — `chainType` is part of the interface.
+
+### Pitfall
+
+Do **not** chain a cast through every helper. The cast belongs at the chain-key guard. Anywhere downstream of the guard, the binding is already typed correctly:
+
+```ts
+// Bad — chained casts:
+async function approveSomething(wp: IWalletProvider) {
+  await sodax.swaps.approve({
+    params,
+    walletProvider: wp as GetWalletProviderType<typeof ChainKeys.BITCOIN_MAINNET>,
+    raw: false,
+  });
+}
+
+// Good — one cast at the boundary, narrowed binding flows:
+const btcWp = isBitcoin(srcChainKey)
+  ? (walletProvider as GetWalletProviderType<typeof ChainKeys.BITCOIN_MAINNET>)
+  : null;
+if (btcWp) await sodax.swaps.approve({ params, walletProvider: btcWp, raw: false });
+```
+
+---
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/gas-estimation.md

@@ -0,0 +1,33 @@
+# Gas estimation
+
+Pre-flight gas estimation for raw-tx flows. Most signed flows include gas estimation internally; you only need this when building unsigned payloads.
+
+```ts
+const result = await sodax.swaps.estimateGas({
+  params: { /* same as createIntent params */ },
+});
+
+if (!result.ok) {
+  // result.error: SodaxError<'VALIDATION_FAILED' | 'GAS_ESTIMATION_FAILED' | 'UNKNOWN'>
+  if (result.error.code === 'GAS_ESTIMATION_FAILED') {
+    // Retry — gas estimation failures are usually transient.
+  }
+  return;
+}
+
+const { gasLimit, gasPrice } = result.value;
+```
+
+`estimateGas` returns chain-family-specific shapes — EVM gas params, Solana compute units, etc. See per-feature docs in [`../features/`](../features/) for specifics.
+
+### Distinct from `LOOKUP_FAILED`
+
+The SDK keeps `GAS_ESTIMATION_FAILED` as its own code (rather than folding into `LOOKUP_FAILED`) because retry semantics differ. Re-estimation is cheap and almost always the right move on transient failure. Generic `LOOKUP_FAILED` errors typically need user intervention.
+
+---
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/initialize-sodax.md

@@ -0,0 +1,53 @@
+# Initialize Sodax
+
+The minimal init — packaged defaults, no config override:
+
+```ts
+import { Sodax } from '@sodax/sdk';
+
+const sodax = new Sodax();
+await sodax.config.initialize();   // load fresh config from backend; falls back to packaged defaults
+
+// All feature services are wired and ready:
+const result = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET);   // returns boolean (sync)
+```
+
+### With config override
+
+```ts
+import { Sodax, ChainKeys, type SodaxConfig, type DeepPartial } from '@sodax/sdk';
+
+const config: DeepPartial<SodaxConfig> = {
+  // Per-chain overrides — merged with packaged defaults at the field level.
+  chains: {
+    [ChainKeys.SONIC_MAINNET]: { rpcUrl: process.env.SONIC_RPC_URL },
+    [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: process.env.ARBITRUM_RPC_URL },
+  },
+  // Backend API override (default: https://api.sodax.com/v1/be).
+  api: {
+    baseURL: 'https://my-sandbox-backend.example.com',
+  },
+  // Solver endpoints (default: https://api.sodax.com/v1/intent + production contracts).
+  solver: {
+    solverApiEndpoint: 'https://my-solver.example.com',
+  },
+};
+
+const sodax = new Sodax(config);
+await sodax.config.initialize();
+```
+
+### Lazy initialization
+
+`config.initialize()` is idempotent — calling it twice is a no-op. The first call fetches; subsequent calls return cached data. Treat it as "make sure config is loaded before any feature method".
+
+### Pitfall
+
+`initialize()` is the only initialization step. Don't `await` it inside every feature call — call it once at app startup. If you skip it entirely, feature services fall back to packaged defaults, which may be stale relative to the latest backend config (new tokens, new chains, fee parameter changes).
+
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/raw-tx-flow.md

@@ -0,0 +1,71 @@
+# Raw-tx flow
+
+`raw: true`. The SDK builds the unsigned payload; you sign it elsewhere (gnosis safe, hardware wallet, multi-sig, etc.).
+
+```ts
+const result = await sodax.swaps.createIntent({
+  params: { /* same as signed flow */ },
+  raw: true,
+  // walletProvider is FORBIDDEN — TypeScript rejects it.
+});
+
+if (!result.ok) return;
+const { tx, intent, relayData } = result.value;
+// tx is now a chain-specific raw-tx payload:
+//   - EVM: EvmRawTransaction { to, data, value, chainId }
+//   - Solana: SolanaRawTransaction
+//   - Stellar: StellarRawTransaction
+//   - …
+```
+
+Submit the raw tx via your own signing infrastructure. Once you have the spoke tx hash, you'll typically need to manually call the relay to complete the cross-chain flow:
+
+```ts
+import { relayTxAndWaitPacket, type RelayExtraData } from '@sodax/sdk';
+
+// After your custom signer broadcasts and you have the spoke tx hash:
+const spokeTxHash = await mySigningInfra.signAndBroadcast(tx);
+
+// `relayTxAndWaitPacket` is a top-level function (not a class). Pass your
+// relayer endpoint (same one you'd configure on the `Sodax` instance) and
+// the relay payload returned by `createIntent`.
+const relayResult = await relayTxAndWaitPacket({
+  relayerApiEndpoint,
+  srcChainKey: params.srcChainKey,
+  dstChainKey: params.dstChainKey,
+  txHash: spokeTxHash,
+  payload: relayData.payload,
+  timeout: 60_000,
+});
+```
+
+This pattern is rare. Prefer signed flow unless you have a specific reason to defer signing.
+
+### Type narrowing
+
+```ts
+// Discriminate raw return shapes by chain family at runtime:
+if (getChainType(srcChainKey) === 'EVM') {
+  const evmTx = result.value.tx as EvmRawTransaction;
+  // …
+}
+```
+
+Or use the chain-key generic to narrow at the type level (most useful when `srcChainKey` is a literal):
+
+```ts
+const result = await sodax.swaps.createIntent({
+  params: { ...params, srcChainKey: ChainKeys.ETHEREUM_MAINNET as const },
+  raw: true,
+});
+// result.value.tx is statically narrowed to EvmRawTransaction
+```
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/result-and-errors.md

@@ -0,0 +1,104 @@
+# Result handling and error discrimination
+
+Every async public method on every feature service returns `Promise<Result<T, SodaxError<C>>>`.
+
+### Branching pattern
+
+```ts
+import { isSodaxError } from '@sodax/sdk';
+
+const result = await sodax.swaps.createIntent({ params, raw: false, walletProvider });
+
+if (!result.ok) {
+  // Always isSodaxError-narrow before reading .feature / .code
+  if (isSodaxError(result.error)) {
+    if (result.error.code === 'RELAY_TIMEOUT') {
+      // retry strategy
+    } else if (result.error.feature === 'swap' && result.error.code === 'INTENT_CREATION_FAILED') {
+      // input-error UX
+    } else if (result.error.code === 'EXTERNAL_API_ERROR' && result.error.context?.api === 'solver') {
+      // solver-side problem; surface error.context.solverDetail to the user
+    }
+  }
+  return;
+}
+
+const { tx, intent, relayData } = result.value;
+```
+
+### Switch-style with narrow code unions
+
+When you know the method, the narrow code union from its declaration enables an exhaustive switch:
+
+```ts
+type CreateSupplyIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
+
+const result = await sodax.moneyMarket.createSupplyIntent({ params, raw: true });
+if (!result.ok) {
+  switch (result.error.code as CreateSupplyIntentErrorCode) {
+    case 'VALIDATION_FAILED':      return setError('Invalid input');
+    case 'INTENT_CREATION_FAILED': return setError('Could not build supply');
+    case 'UNKNOWN':                return setError('Unexpected error');
+  }
+}
+```
+
+### Per-feature guard factory
+
+```ts
+import { isFeatureError } from '@sodax/sdk';
+
+const isSwapError = isFeatureError('swap');
+const isMmError = isFeatureError('moneyMarket');
+
+if (!result.ok) {
+  if (isSwapError(result.error)) /* … */;
+  else if (isMmError(result.error)) /* … */;
+}
+```
+
+### Sub-Result propagation
+
+For wrapper methods you write yourself:
+
+```ts
+async function myWorkflow(): Promise<Result<MyOutput, SodaxError>> {
+  const sub = await sodax.swaps.createIntent({ params, raw: false, walletProvider });
+  if (!sub.ok) return sub;   // forward as-is
+
+  const { tx, intent } = sub.value;
+  return { ok: true, value: { tx, intent, ts: Date.now() } };
+}
+```
+
+### Logging
+
+```ts
+import { isSodaxError } from '@sodax/sdk';
+
+if (!result.ok) {
+  if (isSodaxError(result.error)) {
+    Sentry.captureException(result.error, {
+      tags: {
+        feature: result.error.feature,
+        code: result.error.code,
+        action: result.error.context?.action ?? null,
+        relayCode: result.error.context?.relayCode ?? null,
+      },
+    });
+  } else {
+    Sentry.captureException(result.error);
+  }
+}
+```
+
+`SodaxError.toJSON()` is invoked automatically by `JSON.stringify(error)` — Pino, Datadog, and Winston pick it up without configuration.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/signed-tx-flow.md

@@ -0,0 +1,46 @@
+# Signed-tx flow
+
+`raw: false` + a chain-narrowed `walletProvider`. The SDK signs and broadcasts; returns a tx hash (or tx-pair for cross-chain methods).
+
+```ts
+const result = await sodax.swaps.createIntent({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    dstChainKey: ChainKeys.STELLAR_MAINNET,
+    srcAddress: '0x…',
+    dstAddress: 'G…',
+    inputToken,    // XToken
+    outputToken,   // XToken
+    inputAmount: 1_000_000n,
+    minOutputAmount: 998_000n,
+    deadline: BigInt(Math.floor(Date.now() / 1000) + 300),
+    allowPartialFill: false,
+    solver: '0x0000000000000000000000000000000000000000',
+    data: '0x',
+  },
+  raw: false,
+  walletProvider: evmWallet,    // IEvmWalletProvider — narrowed by srcChainKey
+});
+
+if (!result.ok) return;
+const { tx, intent, relayData } = result.value;
+// tx: the spoke tx hash (string for EVM, base58 for Solana, …)
+```
+
+For cross-chain mutations (`bridge.bridge`, `staking.stake`, `moneyMarket.supply/borrow/withdraw/repay`, `dex.deposit/withdraw/supplyLiquidity/…`, `migration.migratebnUSD/…`) the success value is `TxHashPair = { srcChainTxHash, dstChainTxHash }` — the spoke transaction hash on the source chain plus the relayed hub transaction hash:
+
+```ts
+const result = await sodax.bridge.bridge({ params, raw: false, walletProvider });
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+The same shape is used by every cross-chain mutation in v2 — there is no array-form variant. When the user is already on the hub, both fields hold the same hash.
+
+---
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

package/ai-exported/integration/recipes/testing.md

@@ -0,0 +1,101 @@
+# Testing (mocks and stubs)
+
+### Mock the entire `Sodax` instance
+
+For unit tests where you want to verify your code calls the SDK correctly without hitting network:
+
+```ts
+import type { Sodax } from '@sodax/sdk';
+import { vi } from 'vitest';
+
+const mockSodax = {
+  swaps: {
+    createIntent: vi.fn(),
+    swap: vi.fn(),
+  },
+  config: {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    isValidSpokeChainKey: vi.fn().mockReturnValue(true),
+  },
+} as unknown as Sodax;
+
+mockSodax.swaps.createIntent.mockResolvedValue({
+  ok: true,
+  value: {
+    tx: '0xabc' as `0x${string}`,
+    intent: { /* … */ },
+    relayData: { payload: '0x…' },
+  },
+});
+
+// Use mockSodax in your code under test
+```
+
+The cast `as unknown as Sodax` is the **only** place where `as unknown as` is acceptable per the project conventions — test mocks intentionally defeat types.
+
+### Stub the relay layer for E2E tests
+
+When you want real spoke txs but stubbed relay coordination, mock at the **feature service** boundary — `relayTxAndWaitPacket` is consumed by feature-service implementations internally, and is not exposed on the `Sodax` instance.
+
+```ts
+import { Sodax } from '@sodax/sdk';
+import { vi } from 'vitest';
+
+const sodax = new Sodax({ /* … */ });
+
+// Stub the full feature method (it wraps relay coordination internally):
+vi.spyOn(sodax.swaps, 'swap').mockResolvedValue({
+  ok: true,
+  value: {
+    solverExecutionResponse: { /* … */ },
+    intent: { /* … */ },
+    intentDeliveryInfo: { /* … */ },
+  },
+});
+
+// Or stub just the relay portion of an end-to-end flow by mocking
+// `sodax.swaps.postExecution` after `createIntent` returns.
+```
+
+### Result-style assertions
+
+```ts
+const result = await sodax.swaps.createIntent({ params, raw: false, walletProvider });
+expect(result.ok).toBe(true);
+if (result.ok) {
+  expect(result.value.tx).toMatch(/^0x[0-9a-f]{64}$/);
+}
+// or for failures:
+expect(result.ok).toBe(false);
+if (!result.ok) {
+  expect(result.error).toBeInstanceOf(Error);
+  expect(result.error.code).toBe('VALIDATION_FAILED');
+}
+```
+
+### Custom `IConfigApi` for sandbox
+
+```ts
+import { Sodax, type IConfigApi } from '@sodax/sdk';
+
+const sandboxApi: IConfigApi = {
+  async getChains() { return { ok: true, value: [/* fixture */] }; },
+  async getSwapTokens() { return { ok: true, value: { /* … */ } }; },
+  async getSwapTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
+  async getMoneyMarketTokens() { return { ok: true, value: { /* … */ } }; },
+  async getMoneyMarketTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
+};
+
+const sodax = new Sodax({
+  backendApi: { url: 'unused', api: sandboxApi },
+});
+await sodax.config.initialize();
+```
+
+---
+
+## Cross-references
+
+- [`README.md`](README.md) — recipe index.
+- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
+- [`../reference/`](../reference/) — chain keys, error codes, public API surface.

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

@@ -0,0 +1,18 @@
+# Reference — `@sodax/sdk` v2
+
+Lookup tables and inventories. Each file is focused on one domain — token-cheap retrieval.
+
+| File | Contents |
+|---|---|
+| [`chain-keys.md`](chain-keys.md) | All 20 `ChainKeys.*` values × chain family × address-type mapping. Chain-family helper functions. Type aliases (`ChainKey`, `SpokeChainKey`, `EvmChainKey`, `HubChainKey`). |
+| [`wallet-providers.md`](wallet-providers.md) | `I*WalletProvider` interfaces per chain family. `chainType` discriminant. `GetWalletProviderType<K>`. `IWalletProvider` broad union. Implementation source (consumer's own, or `@sodax/wallet-sdk-core` separate package). |
+| [`error-codes.md`](error-codes.md) | The 13 unified `SodaxErrorCode` values + meanings + retry guidance + common context fields. The 8 `SodaxFeature` tags. The `SodaxPhase` orchestration tags. Per-method narrow code unions for every public method on every service. |
+| [`public-api.md`](public-api.md) | What `@sodax/sdk` barrel exports. Import-rule contract (root-only, no deep imports, types re-exported from `@sodax/types`). |
+| [`glossary.md`](glossary.md) | Domain terms (hub, spoke, intent, relay, vault, hub-wallet abstraction, etc.) used throughout the docs. |
+
+## Cross-references
+
+- v2 architectural concepts (the prose behind these tables): [`../architecture.md`](../architecture.md).
+- Recipes that use these lookups: [`../recipes/`](../recipes/).
+- DO / DO NOT / workflow: [`../ai-rules.md`](../ai-rules.md).
+- v1 → v2 migration: [`../../migration/`](../../migration/).

package/ai-exported/integration/reference/chain-keys.md

@@ -0,0 +1,67 @@
+# Chain keys
+
+20 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. `SpokeChainKey` is the same minus `ChainKeys.SONIC_MAINNET` (the hub).
+
+| `ChainKeys.*` | String value | Family | Hub vs spoke | Address type |
+|---|---|---|---|---|
+| `SONIC_MAINNET` | `'sonic'` | EVM | **Hub** | `0x${string}` |
+| `ETHEREUM_MAINNET` | `'ethereum'` | EVM | spoke | `0x${string}` |
+| `ARBITRUM_MAINNET` | `'0xa4b1.arbitrum'` | EVM | spoke | `0x${string}` |
+| `BASE_MAINNET` | `'0x2105.base'` | EVM | spoke | `0x${string}` |
+| `BSC_MAINNET` | `'0x38.bsc'` | EVM | spoke | `0x${string}` |
+| `OPTIMISM_MAINNET` | `'0xa.optimism'` | EVM | spoke | `0x${string}` |
+| `POLYGON_MAINNET` | `'0x89.polygon'` | EVM | spoke | `0x${string}` |
+| `AVALANCHE_MAINNET` | `'0xa86a.avax'` | EVM | spoke | `0x${string}` |
+| `HYPEREVM_MAINNET` | `'hyper'` | EVM | spoke | `0x${string}` |
+| `LIGHTLINK_MAINNET` | `'lightlink'` | EVM | spoke | `0x${string}` |
+| `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
+| `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
+| `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
+| `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
+| `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
+| `ICON_MAINNET` | `'0x1.icon'` | ICON | spoke | `hx…` / `cx…` |
+| `INJECTIVE_MAINNET` | `'injective-1'` | INJECTIVE | spoke | `inj1…` |
+| `NEAR_MAINNET` | `'near'` | NEAR | spoke | `<account>.near` / `<hex>` |
+| `STACKS_MAINNET` | `'stacks'` | STACKS | spoke | `SP…` / `ST…` |
+| `BITCOIN_MAINNET` | `'bitcoin'` | BITCOIN | spoke | `bc1…` / `1…` / `3…` |
+
+### Notes
+
+- `ChainKeys.ICON_MAINNET` is the **string** `'0x1.icon'`, not the legacy numeric chain id. `Number(chainKey)` returns `NaN` for ICON.
+- `SONIC_MAINNET` is special-cased — it's `'sonic'` (a simple string) and is the hub chain. `getChainType(ChainKeys.SONIC_MAINNET)` returns `'EVM'` (since Sonic is EVM-compatible) and `'SONIC'` is also a valid family in some contexts.
+- Relay chain IDs (used internally for cross-chain coordination) are different from `ChainKey` strings. Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(relayId))`.
+
+### Type aliases
+
+| Type | What it is |
+|---|---|
+| `ChainKey` | Union of all `ChainKeys.*` values (20 chains). |
+| `SpokeChainKey` | `ChainKey` minus `'sonic'` (19 spoke chains). |
+| `EvmChainKey` | Subset of `ChainKey` for the 12 EVM chains. |
+| `HubChainKey` | The literal `'sonic'`. |
+
+### Chain-family helpers
+
+```ts
+import {
+  getChainType,           // (chainKey) => 'EVM' | 'BITCOIN' | ...
+  isEvmChainKeyType,
+  isSolanaChainKeyType,
+  isStellarChainKeyType,
+  isSuiChainKeyType,
+  isIconChainKeyType,
+  isInjectiveChainKeyType,
+  isStacksChainKeyType,
+  isNearChainKeyType,
+  isBitcoinChainKeyType,
+  isHubChainKeyType,
+} from '@sodax/sdk';
+```
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) — concepts behind these tables.