@domfi/sdk 0.1.0

package/README.md

@@ -0,0 +1,786 @@
+# @domfi/sdk
+
+TypeScript SDK for the Domination Finance onchain perpetual futures exchange.
+
+The SDK gives applications one typed client for Domination Finance REST reads, viem-backed RPC reads, wallet-signed trading transactions, token approvals, position valuation, and private vault flows. Wallets remain application-owned; the SDK never takes custody of private keys or relays transactions.
+
+## Capabilities
+
+| What you need | Where it lives |
+|---|---|
+| Typed REST reads — markets, account, prices, trades | [`domfi.api`](#read-the-api) |
+| Raw, schema-shaped REST + generic `request()` | [`domfi.raw`](#read-the-api) |
+| High-level trade & vault actions with lifecycle handles | [`domfi.actions`](#high-level-actions) |
+| Explicit trading — prepare → simulate → send → track | [`domfi.trading`](#trading) |
+| ERC-20 collateral allowance checks & approvals | [`domfi.token`](#token-approval) |
+| Position snapshots — PnL, mark value, liquidation, `watch()` | [`domfi.valuation`](#valuation) |
+| Vault LP flows — deposit, withdraw, redeem, locked deposits | [`domfi.vault`](#vault) |
+| Delegated trading — EIP-712 grants, `delegatedAction` | [`domfi.delegation`](#delegated-trading) |
+| Referral code lookups & eligibility | [`domfi.referrals`](#referrals) |
+| API/protocol status & SDK compatibility | `domfi.system` |
+| Resolved chain config — addresses, collateral, chain id | `domfi.chain` |
+| Pure bigint protocol math (no network) | [`@domfi/sdk/math`](#math-helpers) |
+
+The SDK is one typed client over DomFi REST reads, viem RPC reads, and wallet-signed writes. Wallets stay application-owned — it never holds keys or relays. Both REST and RPC are optional; see [Client Modes](#client-modes).
+
+## Install
+
+Use the DomFi workspace, a packed artifact, or a configured private package source. `viem` is a peer dependency supplied by the application.
+
+```bash
+# pnpm
+pnpm add @domfi/sdk viem
+
+# yarn
+yarn add @domfi/sdk viem
+
+# bun
+bun add @domfi/sdk viem
+
+# npm
+npm install @domfi/sdk viem
+```
+
+## Requirements
+
+- **Node.js** >= 20 (or any modern runtime with a global `fetch`).
+- **viem** >= 2.21 — a peer dependency your application supplies.
+- **TypeScript** 5.6+ recommended.
+
+`@domfi/sdk` ships **dual ESM + CJS** builds with type declarations for both, is side-effect-free (tree-shakeable), and pulls in no Node-only APIs — so it runs in Node and in modern browsers. Its only bundled dependency is `valibot`; `viem` is the peer dependency you supply.
+
+## Quick Start
+
+Create an API-enabled client for read-only REST calls:
+
+```ts
+import { createDomfiClient } from "@domfi/sdk";
+
+const domfi = createDomfiClient({
+  chain: "testnet",
+  // Built-in `testnet`/`mainnet` chains ship a default API base URL
+  // (https://testnet-api.domination.finance / https://api.domination.finance),
+  // so `api.baseUrl` is optional. Pass `api: { baseUrl }` only to override it.
+  transport: {
+    maxConcurrentRest: 8,
+    retryBudget: 2,
+  },
+});
+
+const status = await domfi.system.apiStatus();
+const markets = await domfi.api.markets.list();
+const headPrices = await domfi.api.prices.head();
+
+console.log(status.data.ok, markets.data.length, headPrices.data.length);
+```
+
+Add viem clients when you need RPC reads or wallet-signed writes:
+
+```ts
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+import { createDomfiClient } from "@domfi/sdk";
+
+const account = privateKeyToAccount(process.env.DOMFI_TEST_PRIVATE_KEY as `0x${string}`);
+
+const publicClient = createPublicClient({
+  chain: baseSepolia,
+  transport: http(process.env.BASE_SEPOLIA_RPC_URL),
+});
+
+const walletClient = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(process.env.BASE_SEPOLIA_RPC_URL),
+});
+
+const domfi = createDomfiClient({
+  chain: "testnet",
+  publicClient,
+  walletClient,
+  account: account.address,
+  // `testnet` supplies its API base URL by default; override only if needed:
+  // api: { baseUrl: process.env.DOMFI_API_BASE_URL },
+  transport: {
+    maxConcurrentRest: 8,
+    maxConcurrentRpc: 4,
+    retryBudget: 2,
+  },
+});
+```
+
+> **API base URL.** Built-in `testnet`/`mainnet` target the hosted DomFi API and need no `api.baseUrl`. The SDK appends each route's path (e.g. `/markets`) to your base URL — trailing slashes are trimmed, but it does **not** add a version segment — so to point at a custom or self-hosted deployment, pass the full API base **including** any version path it serves under, e.g. `api: { baseUrl: "https://your-host/api/v2" }`. (The referral read routes are served from the unversioned `/api` root, so a trailing `/v2` is stripped for those.)
+
+> **Wallets.** `privateKeyToAccount` above is for server-side scripts and tests. In browser/frontend apps, build the wallet client from the user's wallet connector or provider (injected, WalletConnect, …) — never load private keys into frontend code.
+
+## Client Modes
+
+API-enabled clients expose typed REST reads under `api` (and schema-shaped reads under `raw`), plus `actions`, `trading`, `token`, `valuation`, `vault`, `delegation`, `referrals`, `system`, and `chain`:
+
+```ts
+domfi.api.markets.list;
+domfi.api.account.positions;
+domfi.api.prices.ticksIterator;
+domfi.api.status.get;
+domfi.raw.request;
+domfi.trading.prepareOpenTrade;
+domfi.token.approvalNeed;
+domfi.valuation.positionSnapshot;
+domfi.vault.stats;
+domfi.actions.openMarket;
+domfi.actions.closePosition;
+domfi.actions.updateTakeProfit;
+domfi.delegation.setDelegateWithSignature;
+domfi.referrals.checkEligibility;
+domfi.system.apiStatus;
+domfi.chain.chainId;
+```
+
+With `api: false`, the `api`, `raw`, `actions`, `vault`, and `referrals` namespaces are intentionally absent at the type level. `chain`, `token`, `delegation`, `trading` (receipt-only — no REST-backed order tracking), `valuation` (`unverifiedSlotSnapshot` only), and `system` remain.
+
+```ts
+import { PairIndex, TradeIndex } from "@domfi/sdk";
+
+const offlineDomfi = createDomfiClient({
+  chain: "testnet",
+  publicClient,
+  walletClient,
+  account: account.address,
+  api: false,
+});
+
+await offlineDomfi.valuation.unverifiedSlotSnapshot({
+  wallet: account.address,
+  pairIndex: PairIndex.from(7),
+  index: TradeIndex.from(0),
+});
+```
+
+## Core Concepts
+
+A handful of ideas show up throughout the SDK. Learn them once here.
+
+### Branded units
+
+Money, prices, leverage, and percentages are **branded fixed-point values**, not raw numbers — so you can't accidentally pass a price where collateral is expected, and there is never a floating-point rounding surprise. Build them from decimal strings; convert to the raw `bigint` the contracts use when you need it:
+
+```ts
+import { Collateral, Leverage, Price } from "@domfi/sdk";
+
+const collateral = Collateral.fromDecimal("25"); // 25 USDC (6dp)
+const leverage = Leverage.fromDecimal("4"); // 4x (2dp)
+const price = Price.fromDecimal("58.5"); // $58.50 (18dp)
+
+Collateral.toRaw(collateral); // 25000000n — on-chain scale
+Collateral.toRawString(collateral); // "25000000"
+```
+
+Most units share `fromDecimal` / `fromRaw` / `toRaw` / `toRawString` / `format`. A few add purpose-built constructors: `SlippagePercent.fromBps("50")` (0.50%), `ClosePercent.full()` (100%), `UsdP6.fromDollar(...)`. Number-like brands (`PairIndex`, `TradeIndex`) use `.from(n)`; id brands (`TradeId`, `OrderId`) use `.parse(s)`. Import codecs from the root or `@domfi/sdk/units`.
+
+### Result envelopes, freshness & readiness
+
+REST reads return an envelope: `result.data` is the mapped value and `result.freshness` describes block lag/staleness. Each read accepts a `readinessPolicy` of `"strict" | "warn" | "ignore"` that decides what happens when the API read model is behind the chain — throw, emit a warning via [`onEvent`](#errors-and-diagnostics), or pass through. Use `"strict"` before writes; `"warn"` is a sensible default for UI reads. (Paginated iterators yield page items whose mapped value is on `.item`, not `.data`.)
+
+### Verified position refs
+
+Position mutations (close, take-profit, collateral, …) require a `VerifiedPositionRef` — a provenance-tagged handle to one open position slot (wallet + pair + slot index + tradeId + chainId). Obtain one from:
+
+- an account position — `verifiedPositionRefFromAccountPosition(position, domfi.chain.chainId)`;
+- a tracked/recovered order — `domfi.trading.track()` / `recoverTransaction()`, and the `closePosition` / `removeCollateral` action outcomes expose `.positionRef`;
+- explicit input — `verifiedPositionRef({ wallet, pairIndex, index, tradeId, chainId })`.
+
+This stops the SDK from acting on an unverified slot index.
+
+### Approval & simulation policies
+
+High-level `domfi.actions.*` writes take two policies (imported from `@domfi/sdk/actions`):
+
+- **Approval** — `ActionApprovalPolicy.RequireExisting` (default; never sends an approval), `AutoExact` (approve exactly what's needed), or `UnsafeMaxUint256` (approve max — convenient, higher risk).
+- **Simulation** — `ActionSimulationPolicy.Required` (default; simulate before send) or `Skip`.
+
+Delegated actions must use `RequireExisting` — a delegate cannot approve the trader's collateral.
+
+### Handles
+
+- **Action handles** (`domfi.actions.*`) are synchronous and non-thenable: calling the method *starts* the write, and `txHash()`, `approval()`, `waitReceipt()`, `outcome()`, and `watch()` observe that same started action.
+- **Prepared transactions** (`domfi.trading.prepare*`, `domfi.vault.prepare*`) are explicit: `summary()` → `simulate()` → `send()`, where `send()` returns a tx handle for receipt and lifecycle tracking.
+
+## Read The API
+
+Domain clients map raw API responses into branded SDK values. Use them for application code:
+
+```ts
+import { PairIndex, TradeId } from "@domfi/sdk";
+
+const pairIndex = PairIndex.from(7);
+const wallet = account.address;
+
+const market = await domfi.api.markets.get(pairIndex);
+const state = await domfi.api.markets.state(pairIndex);
+const positions = await domfi.api.account.positions(wallet, { limit: 25 });
+const orders = await domfi.api.account.orders(wallet, { limit: 25 });
+
+for await (const entry of domfi.api.account.tradesIterator(wallet, { limit: 100 })) {
+  // Iterators yield page items: the mapped value is on `.item` (not `.data`).
+  console.log(entry.item.tradeId, entry.item.notional);
+}
+
+const events = await domfi.api.trades.events(TradeId.parse("12345"), { wallet }, { limit: 50 });
+
+console.log(market.data.symbol, state.data.longOpenInterest, positions.data.length, orders.data.length);
+console.log(events.data.events.length);
+```
+
+Use `domfi.raw.*` or `domfi.raw.request(...)` only when you need schema-shaped API payloads or route-level debugging.
+
+```ts
+const rawStatus = await domfi.raw.status.get();
+const rawMarket = await domfi.raw.request("markets.get", { pairIndex: 7 });
+
+console.log(rawStatus.data, rawMarket.data);
+```
+
+## Token Approval
+
+Trading and vault writes use ERC-20 collateral allowances. Check the required allowance first, then approve only when needed.
+
+```ts
+import { Collateral } from "@domfi/sdk";
+
+const amount = Collateral.fromDecimal("25");
+const spender = domfi.chain.collateral.tradingStorageSpender;
+
+const need = await domfi.token.approvalNeed(account.address, spender, amount);
+
+if (need.action === "approve") {
+  const approval = await domfi.token.approve(spender, need.requiredAllowance, {
+    account: account.address,
+  });
+  await approval.waitReceipt({ confirmations: 1, pollingIntervalMs: 1_000 });
+}
+```
+
+## Delegated Trading
+
+Delegated trading uses DomFi Trading's `delegatedAction(trader, callData)` flow. The trader signs EIP-712 delegation typed data, the delegate signs delegated trading transactions, and `delegation.trader` is the affected wallet for positions, orders, collateral allowance, and receipts. `setDelegateWithSignature` can be submitted by the delegate or any relayer; this example uses the delegate as submitter.
+
+```ts
+import {
+  Collateral,
+  Leverage,
+  PairIndex,
+  SlippagePercent,
+  type Address,
+  type DomfiClient,
+} from "@domfi/sdk";
+import { ActionApprovalPolicy } from "@domfi/sdk/actions";
+import type { WalletClient } from "@domfi/sdk/trading";
+
+declare const domfi: DomfiClient; // created with the delegate wallet client
+declare const traderAccount: { address: Address };
+declare const traderWalletClient: WalletClient; // wallet client for traderAccount
+declare const delegate: Address; // delegate transaction signer and example submitter
+
+const trader = traderAccount.address;
+const expiry = BigInt(Math.floor(Date.now() / 1000) + 60 * 60);
+
+const signed = await domfi.delegation.sign(
+  { delegator: trader, delegate, expiry },
+  traderWalletClient,
+);
+
+await (await domfi.delegation.setDelegateWithSignature(signed, { account: delegate })).waitReceipt();
+
+const opened = domfi.actions.openMarket(
+  {
+    pairIndex: PairIndex.from(7),
+    direction: "long",
+    collateral: Collateral.fromDecimal("25"),
+    leverage: Leverage.fromDecimal("4"),
+    slippage: SlippagePercent.fromBps("50"),
+  },
+  {
+    account: delegate,
+    delegation: { trader },
+    approval: ActionApprovalPolicy.RequireExisting,
+  },
+);
+
+const hash = await opened.txHash();
+console.log(hash);
+```
+
+Delegated high-level actions require the trader to have pre-approved collateral allowance to the trading storage spender. Auto-approval policies are rejected because a delegate cannot approve ERC-20 collateral for the trader.
+
+## Trading
+
+The low-level trading flow is explicit: prepare, optionally simulate, send, wait for the transaction receipt, then track the protocol lifecycle through the API.
+
+```ts
+import { PairIndex, SlippagePercent } from "@domfi/sdk";
+import { TradeDirection } from "@domfi/sdk/trading";
+
+const prepared = await domfi.trading.prepareOpenTrade(
+  {
+    orderKind: "market",
+    pairIndex: PairIndex.from(7),
+    direction: TradeDirection.Long,
+    collateral: "10",
+    leverage: "4",
+    slippage: SlippagePercent.fromBps("50"),
+  },
+  { account: account.address },
+);
+
+const summary = await prepared.summary();
+console.log(summary.approvals, prepared.estimatedOracleFeeWei);
+
+await prepared.simulate({ account: account.address });
+
+const maxOracleFeeWei = prepared.estimatedOracleFeeWei ?? 1_000_000_000_000_000n;
+const handle = await prepared.send({
+  account: account.address,
+  maxOracleFeeWei,
+});
+
+const receipt = await handle.waitReceipt({ confirmations: 1 });
+const current = await handle.track({ maxDurationMs: 60_000 });
+const terminal = await handle.waitTerminal({ maxDurationMs: 180_000, intervalMs: 3_000 });
+
+console.log(receipt.status, current.status, terminal.status);
+```
+
+Use verified refs for position and trigger mutations. A verified position ref can come from account state, receipt recovery, or explicit caller input (see [Core Concepts](#core-concepts)).
+
+```ts
+import { ClosePercent, SlippagePercent } from "@domfi/sdk";
+import { verifiedPositionRefFromAccountPosition } from "@domfi/sdk/trading";
+
+const page = await domfi.api.account.positions(account.address, { limit: 25 });
+const openPosition = page.data.find((position) => position.kind === "open_position");
+
+if (openPosition !== undefined) {
+  const positionRef = verifiedPositionRefFromAccountPosition(openPosition, domfi.chain.chainId);
+
+  const updateTakeProfit = await domfi.trading.prepareUpdateTakeProfit(positionRef, {
+    takeProfit: "1.25",
+  });
+  await (await updateTakeProfit.send({ account: account.address })).waitReceipt();
+
+  const close = await domfi.trading.prepareClosePosition(positionRef, {
+    closePercent: ClosePercent.full(),
+    slippage: SlippagePercent.fromBps("50"),
+  });
+  await (await close.send({ account: account.address })).waitTerminal({
+    maxDurationMs: 180_000,
+  });
+}
+```
+
+### High-Level Actions
+
+API-enabled clients expose `domfi.actions` for the ten trading write flows:
+
+- `openMarket`, `openLimit`, `openStop`
+- `closePosition`
+- `updateTakeProfit`, `updateStopLoss`
+- `topUpCollateral`, `removeCollateral`
+- `updateTriggerOrder`, `cancelTriggerOrder`
+
+Each method returns a synchronous, non-thenable `ActionHandle`. Calling an action method starts/stages the write pipeline immediately; `txHash()`, `approval()`, `waitReceipt()`, `outcome()`, and `watch()` observe that started action. Do not create an action handle for preview-only flows; use math helpers or low-level prepare/preflight APIs instead.
+
+Open trigger placement actions resolve to `status: "placed"` with a receipt-verified trigger order ref. Receipt-only mutations resolve to `status: "confirmed"` with matched event evidence. Market-style actions resolve protocol terminal outcomes such as `executed`, `canceled`, `timed_out`, `identity_mismatch`, `timeout_available`, or `unknown`.
+
+For most app writes, start with a high-level action and choose explicit approval and simulation policies:
+
+~~~ts
+import {
+  Collateral,
+  Leverage,
+  PairIndex,
+  SlippagePercent,
+} from "@domfi/sdk";
+import { ActionApprovalPolicy, ActionSimulationPolicy } from "@domfi/sdk/actions";
+
+const opened = domfi.actions.openMarket(
+  {
+    pairIndex: PairIndex.from(7),
+    direction: "long",
+    collateral: Collateral.fromDecimal("25"),
+    leverage: Leverage.fromDecimal("4"),
+    slippage: SlippagePercent.fromBps("50"),
+  },
+  {
+    account: account.address,
+    approval: ActionApprovalPolicy.AutoExact,
+    simulation: ActionSimulationPolicy.Required,
+    maxOracleFeeWei: 1_000_000_000_000_000n,
+  },
+);
+
+// The action pipeline has already started/staged; these observe the same action.
+const hash = await opened.txHash();
+const receipt = await opened.waitReceipt({ confirmations: 1 });
+const outcome = await opened.outcome({ maxDurationMs: 180_000, intervalMs: 3_000 });
+
+console.log(hash, receipt.status, outcome.status);
+~~~
+
+Example outcome handling:
+
+~~~ts
+import {
+  Collateral,
+  Leverage,
+  PairIndex,
+  Price,
+  SlippagePercent,
+  type DomfiClient,
+} from "@domfi/sdk";
+import type { VerifiedPositionRef } from "@domfi/sdk/trading";
+
+declare const domfi: DomfiClient;
+declare const positionRef: VerifiedPositionRef;
+
+const placed = await domfi.actions.openLimit({
+  pairIndex: PairIndex.from(7),
+  direction: "long",
+  collateral: Collateral.fromDecimal("10"),
+  leverage: Leverage.fromDecimal("5"),
+  entryPrice: Price.fromDecimal("58"),
+}).outcome();
+if (placed.status === "placed") {
+  console.log("trigger order", placed.ref);
+  const canceled = await domfi.actions.cancelTriggerOrder(placed.ref).outcome();
+  console.log("matched cancel event", canceled.eventEvidence);
+}
+
+const closed = await domfi.actions.closePosition(positionRef, {
+  slippage: SlippagePercent.fromBps("50"),
+}).outcome();
+switch (closed.status) {
+  case "executed":
+    console.log("closed", closed.positionRef, closed.result);
+    break;
+  case "timeout_available":
+    console.log("timeout can be handled", closed.result.order);
+    break;
+  default:
+    console.log("terminal or unknown close outcome", closed.status);
+}
+~~~
+
+Use `ActionHandle.watch()` when you need a streaming lifecycle instead of only the final `outcome()`. Market-style actions can emit `submitted`, `mined`, `indexed`, `tracking`, `terminal`, or `unknown` phases; receipt-only actions emit the phases that apply to receipt confirmation.
+
+~~~ts
+const closeAction = domfi.actions.closePosition(positionRef, {
+  slippage: SlippagePercent.fromBps("50"),
+});
+
+for await (const state of closeAction.watch({ maxDurationMs: 180_000, intervalMs: 3_000 })) {
+  if (state.phase === "indexed") console.log("indexed order", state.orderId);
+  if (state.phase === "tracking") console.log("tracking", state.result.status);
+  if (state.phase === "terminal") console.log("terminal", state.outcome.status);
+}
+~~~
+
+## Valuation
+
+Verified valuation combines API discovery with block-pinned onchain reads. Use it for UI position snapshots, actionability, PnL, mark value, and liquidation data.
+
+```ts
+const snapshot = await domfi.valuation.positionSnapshot(positionRef, {
+  readinessPolicy: "warn",
+});
+
+if (snapshot.status === "live") {
+  console.log(snapshot.actionability, snapshot.markValue, snapshot.unrealizedPnl);
+}
+
+const bulk = await domfi.valuation.positionSnapshots([positionRef], {
+  chunkSize: 25,
+});
+
+const watcher = domfi.valuation.watchPositionSnapshot(
+  positionRef,
+  { intervalMs: 3_000, emitImmediately: true },
+  (event) => {
+    if (event.type === "snapshot") console.log(event.data.status);
+    if (event.type === "error") console.warn(event.error.message);
+  },
+);
+
+watcher.stop();
+domfi.valuation.clearConfigCache();
+console.log(bulk.length);
+```
+
+`api:false` clients expose `unverifiedSlotSnapshot` (display-only slot inspection — it does not prove API identity) plus `clearConfigCache`. Verified snapshots, bulk reads, and watching require an API-enabled client.
+
+## Math Helpers
+
+Use `@domfi/sdk/math` for pure, bigint-based protocol math in local previews and preflight UI. Math helpers do not perform REST or RPC calls.
+
+```ts
+import { Collateral, FeePercent, Leverage, Price } from "@domfi/sdk";
+import { currentPercentProfit, tradeFee } from "@domfi/sdk/math";
+
+const percentProfitRaw = currentPercentProfit({
+  openPriceRaw: Price.toRaw(Price.fromDecimal("58")),
+  markPriceRaw: Price.toRaw(Price.fromDecimal("60")),
+  buy: true,
+  leverageRaw: Leverage.toRaw(Leverage.fromDecimal("4")),
+  initialLeverageRaw: Leverage.toRaw(Leverage.fromDecimal("4")),
+});
+
+const flatFee = tradeFee({
+  collateral: Collateral.fromDecimal("25"),
+  leverage: Leverage.fromDecimal("4"),
+  feeP: FeePercent.fromDecimal("0.08"),
+});
+
+console.log(percentProfitRaw, Collateral.toRawString(flatFee));
+```
+
+Use `tradeFee` only when you already know the single flat fee rate to apply. For the protocol's
+real opening cost use `openingFee` (the maker/taker model) below.
+
+Target-leverage helpers compute the collateral adjustment to reach a leverage. Submit
+`requestedAmount` on-chain (via `domfi.actions.topUpCollateral` / `removeCollateral`);
+`effectiveAmount` is the collateral that actually lands after the contract's rounding, and
+`newLeverage` previews the result (always at or below `targetLeverage`).
+
+```ts
+import { Collateral, Leverage } from "@domfi/sdk";
+import { topUpToReachLeverage, unrealizedPnlPercentFromMarkValue } from "@domfi/sdk/math";
+
+const adjustment = topUpToReachLeverage({
+  collateral: Collateral.fromDecimal("100"),
+  leverage: Leverage.fromDecimal("4"),
+  targetLeverage: Leverage.fromDecimal("2"),
+});
+// Collateral.toRawString(adjustment.requestedAmount) -> amount to submit to topUpCollateral.
+
+// Net PnL as a signed percent in P6 scale: 100% === 100_000_000n, floored at -100%.
+const pnlPercentP6 = unrealizedPnlPercentFromMarkValue({
+  collateralRaw: Collateral.toRaw(Collateral.fromDecimal("100")),
+  markValueRaw: Collateral.toRaw(Collateral.fromDecimal("150")),
+});
+
+console.log(Leverage.toRawString(adjustment.newLeverage), pnlPercentP6);
+```
+
+`openingFee` is the full maker/taker model (the imbalance-reducing portion of a trade is charged
+the maker rate, the rest taker); it returns the total base fee the trader pays. `priceImpact`
+mirrors the contract's execution-price function: `priceAfterImpact` is the spread-adjusted price
+(for opens it becomes your stored `openPrice`; for closes it's the close execution price), and
+`priceImpactP` is the raw guard-scale magnitude (`1% == 1e18`). Note that at the current contract
+commit the OI-skew scaling is inert, so the spread is a flat 0.001% against the trader regardless
+of open interest. Feed real OI from `marketState.data.rawState?.oiLong` / `oiShort` (both `UnsignedP18`,
+and note `rawState` is optional), not the display `longOpenInterest` / `shortOpenInterest`.
+
+```ts
+import { FeePercent, Leverage, Price, SignedP6, UnsignedP18, Collateral } from "@domfi/sdk";
+import { openingFee, priceImpact } from "@domfi/sdk/math";
+
+const fee = openingFee({
+  tradeSize: SignedP6.fromDecimal("500"), // +$500 notional (long); negative for short
+  oiDelta: SignedP6.fromDecimal("1000"), // oiLong - oiShort, in USD
+  leverage: Leverage.fromDecimal("10"),
+  makerFeeP: FeePercent.fromDecimal("0.1"),
+  takerFeeP: FeePercent.fromDecimal("0.2"),
+  makerMaxLeverage: Leverage.fromDecimal("50"),
+});
+
+const { priceAfterImpact } = priceImpact({
+  price: Price.fromDecimal("58"),
+  oiLong: UnsignedP18.fromDecimal("100"),
+  oiShort: UnsignedP18.fromDecimal("50"),
+  collateral: Collateral.fromDecimal("1000"),
+  leverage: Leverage.fromDecimal("10"),
+  isOpen: true,
+  isLong: true,
+});
+
+console.log(Collateral.toRawString(fee), Price.toRawString(priceAfterImpact));
+```
+
+## Vault
+
+The SDK includes a first-class private vault client. Read flows can run with an API-only client; prepare and write flows need public and wallet clients for approval checks, simulation, receipt parsing, and indexing.
+
+```ts
+import { VaultAsset, VaultShare } from "@domfi/sdk";
+
+const stats = await domfi.vault.stats();
+const vaultAccount = await domfi.vault.account(account.address);
+
+const preparedDeposit = await domfi.vault.prepareDeposit(
+  {
+    assets: VaultAsset.fromDecimal("10"),
+    receiver: account.address,
+    minShares: VaultShare.fromDecimal("9.95"),
+  },
+  { account: account.address },
+);
+
+const vaultSummary = await preparedDeposit.summary();
+await preparedDeposit.simulate({ account: account.address });
+
+const vaultHandle = await preparedDeposit.send({ account: account.address });
+const outcome = await vaultHandle.outcome();
+const indexed = await vaultHandle.waitIndexed({ maxDurationMs: 60_000 });
+const tracked = await vaultHandle.track({ maxDurationMs: 60_000 });
+
+console.log(stats.data.currentEpoch, vaultAccount.data.totalShares, vaultSummary.approvals);
+console.log(outcome.eventName, indexed.event.opType, tracked.receipt.status);
+```
+
+### High-Level Vault Actions
+
+Direct send helpers mirror prepared methods for user-facing vault writes. They return `Promise<VaultTxHandle>` and are useful when you prefer an explicit async send call:
+
+```ts
+const directDeposit = await domfi.vault.deposit(
+  { assets: VaultAsset.fromDecimal("10"), receiver: account.address },
+  { account: account.address },
+);
+
+await directDeposit.track({ maxDurationMs: 60_000 });
+```
+
+The user-facing vault direct-send methods are `deposit`, `mint`, `makeWithdrawRequest`, `cancelWithdrawRequest`, `withdraw`, `redeem`, `depositWithDiscountAndLock`, `mintWithDiscountAndLock`, and `unlockDeposit`. Admin, governance, callback, `openPnl`, and `distributeReward` contract methods are not SDK user-facing methods.
+
+For synchronous action handles with `approval()`, `txHash()`, `waitReceipt()`, `outcome()`, and `watch()`, use `domfi.actions.vaultDeposit`, `vaultMint`, `vaultMakeWithdrawRequest`, `vaultCancelWithdrawRequest`, `vaultWithdraw`, `vaultRedeem`, `vaultDepositWithDiscountAndLock`, `vaultMintWithDiscountAndLock`, and `vaultUnlockDeposit`.
+
+## Referrals
+
+API-enabled clients expose referral lookup helpers. Import referral-specific types from the stable `@domfi/sdk/referrals` subpath when annotating wrappers or application state.
+
+```ts
+import { ReferralEligibilityStatus, type ReferralEligibility } from "@domfi/sdk/referrals";
+
+const eligibility: ReferralEligibility = await domfi.referrals.checkEligibility({
+  account: account.address,
+  code: "ALPHA123",
+});
+
+if (eligibility.status === ReferralEligibilityStatus.Usable) {
+  console.log("referral code id", eligibility.referral.codeId);
+}
+```
+
+## Errors And Diagnostics
+
+SDK errors have stable public fields: `code`, `kind`, `transient`, required `diagnostics`, optional `hint`, optional `hash`, and original `cause` when available.
+Use `isDomfiError()` instead of `instanceof` so error handling remains stable across package subpaths and test/bundler module boundaries.
+
+```ts
+import { isDomfiError } from "@domfi/sdk/errors";
+
+try {
+  await domfi.system.apiStatus({ timeoutMs: 5_000 });
+} catch (error) {
+  if (isDomfiError(error)) {
+    console.error(error.code, error.kind, error.transient, error.hint);
+  }
+  throw error;
+}
+```
+
+Pass `onEvent` when creating a client to observe REST diagnostics and readiness warnings:
+
+```ts
+const observed = createDomfiClient({
+  chain: "testnet",
+  api: { baseUrl: "https://api.example.com/api/v2" },
+  onEvent(event) {
+    if (event.type === "warning") console.warn(event.code, event.message);
+  },
+});
+
+await observed.system.apiStatus({ readinessPolicy: "warn" });
+```
+
+### Common Errors
+
+Every SDK error exposes a stable `code` and a `kind`; `transient: true` marks a retryable condition. Branch on `code` (stable) rather than the class. Narrow with `isDomfiError(err)` first.
+
+| `code` | `kind` | Typical cause & fix |
+|---|---|---|
+| `MISSING_API_CLIENT` | config | Used an `api`/`actions`/`vault`/`referrals` namespace on an `api: false` client. Recreate with `api`. |
+| `MISSING_PUBLIC_CLIENT` | config | A read/prepare needs RPC. Pass a viem `publicClient`. |
+| `MISSING_WALLET_CLIENT` | wallet | A write needs signing. Pass a viem `walletClient`. |
+| `MISSING_ACCOUNT` | wallet | No account for the write. Pass `account` (client option or per-call). |
+| `WALLET_CHAIN_MISMATCH` | wallet | Wallet client is on a different chain than the configured `chain`. |
+| `WALLET_ACCOUNT_MISMATCH` | wallet | The wallet's account differs from the `account` you passed. |
+| `WALLET_DISCONNECTED` | wallet | _(transient)_ Wallet/transport dropped. Reconnect and retry. |
+| `READ_MODEL_NOT_READY` | api | _(transient)_ API read model is behind the chain. Retry, or relax `readinessPolicy`. |
+| `PROTOCOL_COMPATIBILITY_MISMATCH` | compatibility | On-chain contracts don't match the SDK's expected protocol. Align SDK/chain versions. |
+| `IDENTITY_MISMATCH` | identity | A tracked tx resolved to a different trader/trade than expected (often a delegation mixup). |
+| `VALIDATION_ERROR` | validation | Bad input, or an API response that failed schema validation. |
+| `ORACLE_FEE_CAP_EXCEEDED` | validation | Required oracle fee exceeded your `maxOracleFeeWei`. Raise the cap or retry when fees drop. |
+| `API_ERROR` / `API_*` | api | REST call returned an error; inspect `httpStatus` / `details`. |
+| `CONTRACT_REVERT` / `REVERT_*` | contract | The contract reverted; `REVERT_*` is the decoded reason. |
+| `TRANSPORT_ERROR` | transport | _(transient by default)_ Network/HTTP failure. |
+| `TIMEOUT` | timeout | _(transient)_ Operation exceeded `timeoutMs` / `maxDurationMs`. |
+| `ABORTED` | abort | _(transient)_ An `AbortSignal` you passed fired. |
+
+## Package Subpaths
+
+The root export is the normal application entry point. Stable subpaths are available for focused imports:
+
+```ts
+import { createDomfiClient } from "@domfi/sdk";
+import { currentPercentProfit, tradeFee } from "@domfi/sdk/math";
+import type { DomfiRawClient } from "@domfi/sdk/api";
+import { domfiChains } from "@domfi/sdk/config";
+import { abis } from "@domfi/sdk/contracts";
+import { ApiError } from "@domfi/sdk/errors";
+import { ReferralEligibilityStatus, type ReferralClient } from "@domfi/sdk/referrals";
+import { coerceBigInt } from "@domfi/sdk/serde";
+import type { TokenClient } from "@domfi/sdk/token";
+import { verifiedPositionRef } from "@domfi/sdk/trading";
+import { Collateral, PairIndex } from "@domfi/sdk/units";
+import type { ValuationClient } from "@domfi/sdk/valuation";
+import { VaultAsset } from "@domfi/sdk/vault";
+
+declare const raw: DomfiRawClient;
+declare const referrals: ReferralClient;
+declare const token: TokenClient;
+declare const valuation: ValuationClient;
+
+console.log(createDomfiClient, raw, referrals, token, valuation, domfiChains.testnet.chainId);
+console.log(
+  abis,
+  ApiError,
+  ReferralEligibilityStatus,
+  coerceBigInt,
+  currentPercentProfit,
+  tradeFee,
+  verifiedPositionRef,
+  Collateral,
+  PairIndex,
+  VaultAsset,
+);
+```
+
+## Examples & Further Reading
+
+Runnable, type-checked examples live in [`examples/`](./examples) (run via `pnpm test:examples`):
+
+- [`examples/quickstart.ts`](./examples/quickstart.ts) — create a client and read API status.
+- [`examples/trading-lifecycle.ts`](./examples/trading-lifecycle.ts) — high-level actions plus the low-level prepare/send flow.
+- [`examples/valuation.ts`](./examples/valuation.ts) — position snapshots and watching.
+- [`examples/vault.ts`](./examples/vault.ts) — vault reads and the deposit prepare flow.
+
+For a feature-oriented tour of the SDK, see [`docs/sdk-showcase.md`](./docs/sdk-showcase.md).
+
+Jump to a domain: [Core Concepts](#core-concepts) · [Read The API](#read-the-api) · [Token Approval](#token-approval) · [Delegated Trading](#delegated-trading) · [Trading](#trading) · [High-Level Actions](#high-level-actions) · [Valuation](#valuation) · [Math Helpers](#math-helpers) · [Vault](#vault) · [Referrals](#referrals) · [Errors](#errors-and-diagnostics).
+
+## License
+
+Copyright (c) 2026 Domination Finance Ltd. All rights reserved.
+
+This package is proprietary and confidential — it is **not** open source. No license is granted to use, copy, modify, or distribute it except under a separate written agreement. See [`LICENSE`](./LICENSE) for the full terms.