@sodax/skills 2.0.0-rc.10

package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md

@@ -0,0 +1,78 @@
+# 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).
+
+## Module-scope reads (no Sodax instance needed)
+
+Some code runs at **module-load time** — constants files, utility modules, framework-provider configs — before any `Sodax` instance exists. For those, import the packaged-default constants directly from `@sodax/sdk` (re-exported from `@sodax/types`):
+
+```ts
+import { sodaxConfig, hubConfig } from '@sodax/sdk';
+
+// Hub address constants
+export const HUB_WALLET = hubConfig.addresses.hubWallet;
+export const STAKING_ROUTER = hubConfig.addresses.stakingRouter;
+
+// Full default config (every SodaxConfig field with packaged defaults)
+export const DEFAULT_SOLVER_ENDPOINT = sodaxConfig.solver.solverApiEndpoint;
+export const SUPPORTED_TOKENS_PER_CHAIN = sodaxConfig.swaps.supportedTokens;
+```
+
+| Need | Module-scope import (defaults only) | Instance-scope read (with overrides) |
+|---|---|---|
+| Hub contract addresses (assetManager, hubWallet, stakingRouter, etc.) | `hubConfig.addresses.*` | `sodax.config.getHubChainConfig().addresses.*` |
+| Full default SodaxConfig (read-only snapshot) | `sodaxConfig.*` (e.g. `sodaxConfig.hub`, `sodaxConfig.moneyMarket`) | `sodax.config.sodaxConfig` |
+| Per-chain spoke config (rpcUrl, nativeToken, addresses, supportedTokens, polling) | `spokeChainConfig[ChainKeys.X_MAINNET]` (from `@sodax/types` / `@sodax/sdk`) | `sodax.config.spokeChainConfig[ChainKeys.X_MAINNET]` *or* `sodax.config.getChainConfig(ChainKeys.X_MAINNET)` |
+| Money market reserve assets | `sodaxConfig.moneyMarket.supportedReserveAssets` | `sodax.config.getMoneyMarketReserveAssets()` |
+
+> **Static vs dynamic — and the override-gap consequence.** `sodaxConfig` / `hubConfig` / `spokeChainConfig` are **packaged-default snapshots** frozen at SDK release time. They are safe at module scope but: (a) won't reflect backend-driven config updates loaded by `sodax.config.initialize()`, and (b) **won't reflect overrides passed to `new Sodax(config)`** — those merge into `sodax.config` (the `ConfigService`) but never mutate the static imports. So once a `Sodax` instance exists, prefer the instance-scope readers in the right column above — particularly `sodax.config.spokeChainConfig` over the same-named static import — or you will silently fall back to the packaged defaults for any chain you customized.
+
+
+## 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/skills/sodax-sdk/integration/knowledge/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/skills/sodax-sdk/integration/knowledge/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/skills/sodax-sdk/integration/knowledge/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/skills/sodax-sdk/integration/knowledge/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/skills/sodax-sdk/integration/knowledge/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: [`sodax-sdk` (migration mode)](../../../migration-v1-to-v2/knowledge/).

package/skills/sodax-sdk/integration/knowledge/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 union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
+
+| `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.

package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md

@@ -0,0 +1,165 @@
+# Error codes
+
+All 13 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
+
+| Code | Meaning | Common `error.context` fields | Retry advice |
+|---|---|---|---|
+| `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
+| `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
+| `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
+| `TX_VERIFICATION_FAILED` | Spoke `verifyTxHash` returned false / threw. | `phase: 'verify'`, `srcChainKey` | Sometimes — RPC / indexer issue is transient. |
+| `TX_SUBMIT_FAILED` | Spoke tx landed; relay POST submit failed. | `phase: 'submit'`, `relayCode: 'SUBMIT_TX_FAILED'` | Yes — relay submit is retryable; backoff and re-run with the same payload. |
+| `RELAY_TIMEOUT` | Destination packet didn't reach `executed` within timeout. | `phase: 'relay'`, `srcChainKey`, `dstChainKey`, `relayCode: 'RELAY_TIMEOUT'` | Yes — increase timeout or re-poll; the spoke tx already landed. |
+| `RELAY_FAILED` | Relay polling outage / unrecognised relay error. | `phase: 'relay'`, `relayCode` | Yes — exponential backoff. |
+| `APPROVE_FAILED` | Token approval call failed. | `phase: 'approve'` | Sometimes — gas / RPC issues are retryable. |
+| `ALLOWANCE_CHECK_FAILED` | Reading on-chain allowance failed. | `phase: 'allowanceCheck'` | Yes — read-only retry is cheap. |
+| `GAS_ESTIMATION_FAILED` | Gas estimation returned an error. | `phase: 'gasEstimation'` | Yes — re-estimate is the norm. |
+| `LOOKUP_FAILED` | Read-only on-chain query / off-chain config fetch. | `method`, `phase: 'lookup'` | Yes — read-only retry is cheap. |
+| `EXTERNAL_API_ERROR` | Upstream API call failed (solver, backend). | `api: 'solver' \| 'backend'`; for solver: `solverCode`, `solverDetail` | Sometimes — depends on `solverCode`. |
+| `UNKNOWN` | Last-resort catch in an outer `try`. | (none guaranteed) | Treat as unrecoverable; surface the underlying cause. |
+
+### Features
+
+```ts
+type SodaxFeature =
+  | 'swap'
+  | 'moneyMarket'
+  | 'bridge'
+  | 'staking'
+  | 'migration'
+  | 'dex'
+  | 'partner'
+  | 'recovery';
+```
+
+The `(feature, code)` pair is the canonical discriminator. Loggers tag both fields; switch statements branch on both.
+
+### Phase tags (`error.context.phase`)
+
+```ts
+type SodaxPhase =
+  | 'validate'           // pre-flight invariant
+  | 'intentCreation'     // building intent / payload
+  | 'verify'             // spoke verifyTxHash
+  | 'submit'             // spoke→relay submit
+  | 'relay'              // primary relayTxAndWaitPacket wait
+  | 'destinationExecution' // secondary watcher (migration's bnUSD waitUntilIntentExecuted)
+  | 'execution'          // orchestrator-level catch
+  | 'postExecution'      // swap-only post-relay solver step
+  | 'approve'            // ERC20 approval call
+  | 'allowanceCheck'     // on-chain allowance read
+  | 'gasEstimation'      // gas-estimation read
+  | 'lookup';            // generic read-only query
+```
+
+### `RelayCode` (`error.context.relayCode`)
+
+```ts
+type RelayCode =
+  | 'SUBMIT_TX_FAILED'
+  | 'RELAY_TIMEOUT'
+  | 'RELAY_POLLING_FAILED'
+  | 'UNKNOWN';
+```
+
+This is the lower-level relay-layer code that `mapRelayFailure` maps from. Surfaces on `error.context.relayCode` when the error originated in `IntentRelayApiService`.
+
+---
+
+
+## Per-method error codes
+
+Narrow code unions per public method. Use these for exhaustive `switch` discrimination.
+
+### Common helper unions (used across features)
+
+```ts
+// 'create*Intent' methods
+type CreateIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
+
+// 'approve' methods
+type ApproveErrorCode = 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
+
+// 'isAllowanceValid' methods
+type AllowanceCheckErrorCode = 'VALIDATION_FAILED' | 'ALLOWANCE_CHECK_FAILED' | 'UNKNOWN';
+
+// 'estimateGas' methods
+type GasEstimationErrorCode = 'VALIDATION_FAILED' | 'GAS_ESTIMATION_FAILED' | 'UNKNOWN';
+
+// All read-only lookups
+type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
+```
+
+### Swap (`feature: 'swap'`)
+
+| Method | Narrow code union |
+|---|---|
+| `createIntent` | `CreateIntentErrorCode` |
+| `swap` | All of {`VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
+| `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
+| `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
+| `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
+
+### Money Market (`feature: 'moneyMarket'`)
+
+| Method | Narrow code union |
+|---|---|
+| `supply`, `borrow`, `withdraw`, `repay` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
+| `createSupplyIntent`, `createBorrowIntent`, `createWithdrawIntent`, `createRepayIntent` | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `estimateGas` | `GasEstimationErrorCode` |
+| Read-only methods (reserves, user data, etc.) | `LookupErrorCode` |
+
+### Staking (`feature: 'staking'`)
+
+| Method | Narrow code union |
+|---|---|
+| `stake` | All exec codes including `TX_VERIFICATION_FAILED` (only stake calls verifyTxHash). |
+| `unstake`, `instantUnstake`, `claim`, `cancelUnstake` | All exec codes minus `TX_VERIFICATION_FAILED`. |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getStakingInfo`, `getUnstakingInfo`, `getStakingConfig`, `getStakeRatio`, `getInstantUnstakeRatio`, `getConvertedAssets`, `getUnstakingInfoWithPenalty`, `getStakingInfoFromSpoke` | `LookupErrorCode` (with `method` discriminator) |
+
+### Bridge (`feature: 'bridge'`)
+
+| Method | Narrow code union |
+|---|---|
+| `bridge` | All exec codes. |
+| `createBridgeIntent` | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getBridgeableAmount`, `getBridgeableTokens` | `LookupErrorCode` (with `method` discriminator) |
+
+### DEX (`feature: 'dex'`)
+
+| Method | Narrow code union |
+|---|---|
+| `assetService.deposit`, `assetService.withdraw` | All exec codes. |
+| `clService.supplyLiquidity`, `clService.increaseLiquidity`, `clService.decreaseLiquidity`, `clService.claimRewards` | All exec codes. |
+| `assetService.approve` | `ApproveErrorCode` |
+| `assetService.isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `clService.getPoolData`, `clService.getPositionInfo`, `assetService.getDeposit` | `LookupErrorCode` |
+
+### Migration (`feature: 'migration'`)
+
+| Method | Narrow code union |
+|---|---|
+| `migratebnUSD` | All exec codes; `direction: 'forward' \| 'reverse'` on context. |
+| `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln` | All exec codes. |
+| `createXxxIntent` (4 of these) | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getAvailableAmount` | `LookupErrorCode` |
+
+### Partner (`feature: 'partner'`) and Recovery (`feature: 'recovery'`)
+
+Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode`.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) § 7–8 — error model concepts.