@lifi/perps-types 0.2.0-alpha.0 → 1.0.0

package/dist/types/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,YAAY,EACb,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAE9C,cAAc;AACd,MAAM,MAAM,kBAAkB,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AACnE,cAAc;AACd,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AACD,cAAc;AACd,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,QAAQ,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,aAAa,CAAA;CACxB,CAAA;AACD,cAAc;AACd,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,cAAc,CAAA;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AACD,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AACD,cAAc;AACd,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,WAAW,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AACD,cAAc;AACd,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,cAAc,CAAA;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,cAAc;AACd,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,qBAAqB,GACrB,kBAAkB,GAClB,wBAAwB,GACxB,iBAAiB,GACjB,qBAAqB,GACrB,wBAAwB,CAAA;AAE5B,cAAc;AACd,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAC7E,cAAc;AACd,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,CAAA;AAC9E,cAAc;AACd,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAC7D,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE;QACJ,4CAA4C;QAC5C,UAAU,EAAE,SAAS,EAAE,CAAA;QACvB,8DAA8D;QAC9D,aAAa,EAAE,YAAY,EAAE,CAAA;QAC7B;;;WAGG;QACH,UAAU,EAAE,MAAM,EAAE,CAAA;KACrB,CAAA;CACF,CAAA;AACD,cAAc;AACd,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,IAAI,EAAE,CAAA;CAAE,CAAA;AAC3D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAA;AACvE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,cAAc,CAAA;IACvB,IAAI,EAAE,CAAC,OAAO,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAA;CACvC,CAAA;AAED,cAAc;AACd,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,cAAc,GACd,WAAW,GACX,iBAAiB,GACjB,UAAU,GACV,cAAc,GACd,iBAAiB,CAAA"}

package/dist/types/typedData.d.ts

@@ -0,0 +1,28 @@
+import type { Address, Hex } from './primitives.js';
+/** @public */
+export interface TypedDataDomain {
+    name?: string;
+    version?: string;
+    chainId?: number;
+    verifyingContract?: Address;
+    salt?: Hex;
+}
+/** @public */
+export interface TypedDataParameter {
+    name: string;
+    type: string;
+}
+/** @public */
+export type PerpsPrimaryType = string;
+/** @public */
+export type PerpsTypedData = {
+    domain: TypedDataDomain;
+    types: Record<string, readonly TypedDataParameter[]>;
+    primaryType: PerpsPrimaryType;
+    message: Record<string, any>;
+};
+/** @public */
+export type PerpsSignedTypedData = PerpsTypedData & {
+    signature: Hex;
+};
+//# sourceMappingURL=typedData.d.ts.map

package/dist/types/typedData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedData.d.ts","sourceRoot":"","sources":["../../src/typedData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAEnD,cAAc;AACd,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,IAAI,CAAC,EAAE,GAAG,CAAA;CACX;AAED,cAAc;AACd,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,cAAc;AACd,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAErC,cAAc;AACd,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,eAAe,CAAA;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,CAAA;IACpD,WAAW,EAAE,gBAAgB,CAAA;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC7B,CAAA;AAED,cAAc;AACd,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG;IAClD,SAAS,EAAE,GAAG,CAAA;CACf,CAAA"}

package/dist/types/vote.d.ts

@@ -0,0 +1,68 @@
+import type { Address } from './primitives.js';
+import type { PerpsTypedData, TypedDataParameter } from './typedData.js';
+/**
+ * Sentinel sent in the `provider` field for provider-independent actions
+ * (e.g. {@link "./enums.js".ActionType.META_VOTE}). The backend dispatches
+ * on this value instead of resolving a real provider plugin.
+ * @public
+ */
+export declare const META_PROVIDER = "meta";
+/** @public */
+export type MetaProvider = typeof META_PROVIDER;
+/**
+ * Vote direction. `up` endorses the subject; `down` opposes it.
+ * @public
+ */
+export type VoteDirection = 'up' | 'down';
+/**
+ * Discriminates what a vote is about, leaving room for future product-level
+ * vote subjects without changing the EIP-712 `primaryType`.
+ * @public
+ */
+export type VoteType = 'provider';
+/**
+ * Params for an {@link "./enums.js".ActionType.META_VOTE} action.
+ *
+ * `targetProvider` is the voted-on subject — kept distinct from the transport
+ * `provider` field, which carries the {@link META_PROVIDER} sentinel for this
+ * provider-independent action.
+ * @public
+ */
+export interface VoteParams {
+    /** Key of the inactive provider being voted on (the voted-on subject). */
+    targetProvider: string;
+    direction: VoteDirection;
+    voteType: VoteType;
+}
+/**
+ * EIP-712 message body for a `Vote`. Field order matches {@link voteTypeFields}.
+ * @public
+ */
+export interface VoteMessage {
+    /** Key of the inactive provider being voted on. */
+    targetProvider: string;
+    direction: VoteDirection;
+    voteType: VoteType;
+    voter: Address;
+    /** Unix timestamp in milliseconds. */
+    timestamp: number;
+}
+/**
+ * EIP-712 type member list for the `Vote` primary type. Field order is part of
+ * the signed digest and must match the backend's encoder.
+ * @public
+ */
+export declare const voteTypeFields: readonly TypedDataParameter[];
+/**
+ * EIP-712 typed data for a vote, as returned by `createAction` and signed
+ * client-side. `primaryType` is always `'Vote'`.
+ * @public
+ */
+export interface VoteTypedData extends PerpsTypedData {
+    primaryType: 'Vote';
+    types: {
+        Vote: readonly TypedDataParameter[];
+    } & PerpsTypedData['types'];
+    message: VoteMessage;
+}
+//# sourceMappingURL=vote.d.ts.map

package/dist/types/vote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vote.d.ts","sourceRoot":"","sources":["../../src/vote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC,cAAc;AACd,MAAM,MAAM,YAAY,GAAG,OAAO,aAAa,CAAA;AAE/C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,MAAM,CAAA;AAEzC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,aAAa,CAAA;IACxB,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,aAAa,CAAA;IACxB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,kBAAkB,EAMvD,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAA;KAAE,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IACxE,OAAO,EAAE,WAAW,CAAA;CACrB"}

package/package.json

@@ -1,70 +1,7 @@
 {
   "name": "@lifi/perps-types",
+  "version": "1.0.0",
   "description": "Shared types for the LI.FI perps stack",
-  "dependencies": {
-    "viem": "2.48.8"
-  },
-  "version": "0.2.0-alpha.0",
-  "files": [
-    "src",
-    "!src/**/*.tsbuildinfo",
-    "!src/**/*.unit.spec.ts",
-    "providers/hyperliquid",
-    "providers/lighter"
-  ],
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./src/_types/index.d.ts",
-        "default": "./src/_esm/index.js"
-      },
-      "require": {
-        "types": "./src/_types/index.d.ts",
-        "default": "./src/_cjs/index.js"
-      }
-    },
-    "./providers/hyperliquid": {
-      "import": {
-        "types": "./src/_types/providers/hyperliquid/index.d.ts",
-        "default": "./src/_esm/providers/hyperliquid/index.js"
-      },
-      "require": {
-        "types": "./src/_types/providers/hyperliquid/index.d.ts",
-        "default": "./src/_cjs/providers/hyperliquid/index.js"
-      }
-    },
-    "./providers/lighter": {
-      "import": {
-        "types": "./src/_types/providers/lighter/index.d.ts",
-        "default": "./src/_esm/providers/lighter/index.js"
-      },
-      "require": {
-        "types": "./src/_types/providers/lighter/index.d.ts",
-        "default": "./src/_cjs/providers/lighter/index.js"
-      }
-    },
-    "./package.json": "./package.json"
-  },
-  "main": "./src/_cjs/index.js",
-  "module": "./src/_esm/index.js",
-  "types": "./src/_types/index.d.ts",
-  "typings": "./src/_types/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "providers/hyperliquid": [
-        "./src/_types/providers/hyperliquid/index.d.ts"
-      ],
-      "providers/lighter": [
-        "./src/_types/providers/lighter/index.d.ts"
-      ]
-    }
-  },
-  "sideEffects": false,
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/lifinance/perps-types.git"
-  },
   "keywords": [
     "lifi",
     "perps",
@@ -73,5 +10,40 @@
     "defi",
     "trading",
     "cross-chain"
-  ]
+  ],
+  "homepage": "https://github.com/lifinance/perps-sdk",
+  "bugs": {
+    "url": "https://github.com/lifinance/perps-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lifinance/perps-sdk.git"
+  },
+  "license": "Apache-2.0",
+  "author": "LI.FI <dev@li.fi>",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "!dist/**/*.tsbuildinfo",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/acceptTerms.ts

@@ -0,0 +1,53 @@
+import type { Address } from './primitives.js'
+import type { PerpsTypedData, TypedDataParameter } from './typedData.js'
+
+/**
+ * Params for an {@link "./enums.js".ActionType.META_ACCEPT_TERMS} action.
+ *
+ * Provider-independent: cast with the {@link "./vote.js".META_PROVIDER}
+ * sentinel in the transport `provider` field.
+ * @public
+ */
+export interface AcceptTermsParams {
+  /** Terms-of-Service version being accepted; backend-owned, relayed verbatim. */
+  termsVersion: string
+}
+
+/**
+ * EIP-712 message body for an `AcceptTerms`. Field order matches
+ * {@link acceptTermsTypeFields}.
+ * @public
+ */
+export interface AcceptTermsMessage {
+  /** Human-readable action, e.g. `"Accept LI.FI Perps Terms of Service v3"`. */
+  action: string
+  acceptor: Address
+  termsVersion: string
+  /** Unix timestamp in milliseconds. */
+  timestamp: number
+}
+
+/**
+ * EIP-712 type member list for the `AcceptTerms` primary type. Field order is
+ * part of the signed digest and must match the backend's encoder.
+ * @public
+ */
+export const acceptTermsTypeFields: readonly TypedDataParameter[] = [
+  { name: 'action', type: 'string' },
+  { name: 'acceptor', type: 'address' },
+  { name: 'termsVersion', type: 'string' },
+  { name: 'timestamp', type: 'uint256' },
+]
+
+/**
+ * EIP-712 typed data for a terms acceptance, as returned by `createAction` and
+ * signed client-side. `primaryType` is always `'AcceptTerms'`.
+ * @public
+ */
+export interface AcceptTermsTypedData extends PerpsTypedData {
+  primaryType: 'AcceptTerms'
+  types: {
+    AcceptTerms: readonly TypedDataParameter[]
+  } & PerpsTypedData['types']
+  message: AcceptTermsMessage
+}

package/src/account.ts

@@ -1,5 +1,4 @@
-import type { Address } from './typedData.js'
-import type { AssetDisplay } from './asset.js'
+import type { Asset } from './asset.js'
 import type {
   ActionType,
   ActivityType,
@@ -11,14 +10,18 @@ import type {
   OrderType,
   PositionSide,
 } from './enums.js'
+import type { MarketDisplay } from './market.js'
+import type { Address } from './primitives.js'
 
+/** @public */
 export interface FeeTier {
   maker: string
   taker: string
 }
 
+/** @public */
 export interface Position {
-  asset: AssetDisplay
+  market: MarketDisplay
   side: PositionSide
   size: string
   entryPrice: string
@@ -30,9 +33,10 @@ export interface Position {
   marginMode: MarginMode
 }
 
+/** @public */
 export interface OpenOrder {
-  id: string
-  asset: AssetDisplay
+  orderId: string
+  market: MarketDisplay
   side: OrderSide
   type: OrderType
   size: string
@@ -43,31 +47,42 @@ export interface OpenOrder {
   createdAt: string
 }
 
+/** @public */
 export interface Balance {
-  currency: string
-  amount: string
+  /** Which category/venue this balance sits in — references a {@link ProviderCategory}. */
+  categoryId: string
+  asset: Asset
+  units: string
+  /** USD value the SDK fills from the prices map; consumers render with zero math. */
+  valueUsd: string
 }
 
+/** @public */
 export interface AccountResponse {
   provider: string
   address: Address
-  balances: Record<string, Balance[]>
+  /** Flat, NON-collateral holdings. */
+  balances: Balance[]
+  /** SDK-determined collateral subset: spot balances in a category's quote asset. */
+  collateralBalances: Balance[]
   marginUsed: string
   unrealizedPnl: string
   feeTier: FeeTier
-  /**
-   * Per-provider account state, strongly typed and discriminated on
-   * `config.provider`. Consumers narrow with `config.provider === 'hyperliquid'`
-   * etc. to get access to the provider-specific fields. There is no untyped
-   * escape hatch — fields specific to a future provider belong on a new
-   * variant of `AccountConfig`, not on a generic `Record<string, unknown>`.
-   */
   config: AccountConfig
 }
 
+/** @public */
+export interface AccountSummary {
+  portfolioValue: string
+  availableMargin: string
+  marginUsed: string
+  unrealizedPnl: string
+}
+
+/** @public */
 export interface TriggerOrder {
-  id: string
-  asset: AssetDisplay
+  orderId: string
+  market: MarketDisplay
   type: OrderType
   size: string
   triggerPrice: string
@@ -76,12 +91,14 @@ export interface TriggerOrder {
   createdAt: string
 }
 
+/** @public */
 export interface PositionsResponse {
   provider: string
   positions: Position[]
   pagination: Pagination
 }
 
+/** @public */
 export interface OrdersResponse {
   provider: string
   openOrders: OpenOrder[]
@@ -89,10 +106,11 @@ export interface OrdersResponse {
   pagination: Pagination
 }
 
+/** @public */
 export interface Fill {
   id: string
   orderId: string
-  asset: AssetDisplay
+  market: MarketDisplay
   side: OrderSide
   type: OrderType
   size: string
@@ -105,8 +123,12 @@ export interface Fill {
   startPosition?: string
   classification: FillClassification
   createdAt: string
+  // Fully-resolved block-explorer URL for the settling on-chain tx. Absent when
+  // the fill has no on-chain settlement tx.
+  explorerLink?: string
 }
 
+/** @public */
 export interface Pagination {
   limit: number
   hasMore: boolean
@@ -114,38 +136,44 @@ export interface Pagination {
   nextUrl?: string
 }
 
+/** @public */
 export interface FillsResponse {
   provider: string
   items: Fill[]
   pagination: Pagination
 }
 
-// ---------------------------------------------------------------------------
-// Activities
-// ---------------------------------------------------------------------------
-
+/** @public */
 export interface BaseActivity {
   id: string
   provider: string
   timestamp: string
 }
 
+/** @public */
 export interface DepositActivity extends BaseActivity {
   type: ActivityType.DEPOSIT
   amount: string
+  // Fully-resolved block-explorer URL for the on-chain deposit tx.
+  explorerLink?: string
 }
 
+/** @public */
 export interface WithdrawalActivity extends BaseActivity {
   type: ActivityType.WITHDRAWAL
   amount: string
   fee: string
+  // Fully-resolved block-explorer URL for the on-chain withdrawal tx.
+  explorerLink?: string
 }
 
+/** @public */
 export interface LiquidatedPosition {
-  asset: AssetDisplay
+  market: MarketDisplay
   size: string
 }
 
+/** @public */
 export interface LiquidationActivity extends BaseActivity {
   type: ActivityType.LIQUIDATION
   liquidatedNotionalPosition: string
@@ -154,40 +182,32 @@ export interface LiquidationActivity extends BaseActivity {
   liquidatedPositions: LiquidatedPosition[]
 }
 
+/** @public */
 export interface FundingActivity extends BaseActivity {
   type: ActivityType.FUNDING
-  asset: AssetDisplay
+  market: MarketDisplay
   amount: string
   positionSize: string
   fundingRate: string
 }
 
-/**
- * Internal transfer between two accounts on the same provider (e.g. Lighter
- * `/api/v1/transfer/history`, Hyperliquid `spotTransfer` ledger entry).
- * Direction is relative to the queried account.
- *
- * The counterparty is identified by either an account index (integer L2
- * account identifier — Lighter) or a wallet address (Hyperliquid, where
- * accounts ARE addresses). The type is a discriminated union over these two
- * shapes: at least one of `counterpartyAccountIndex` / `counterpartyAddress`
- * MUST be present, and either may appear alone or alongside the other.
- *
- * Consumers that render counterparties should prefer `counterpartyAccountIndex`
- * when present (it's the canonical handle on index-based providers) and fall
- * back to a truncated `counterpartyAddress` otherwise.
- */
+// At least one of `counterpartyAccountIndex` / `counterpartyAddress` is always
+// present; both may appear together.
+/** @public */
 export type TransferActivity = BaseActivity & {
   type: ActivityType.TRANSFER
   direction: 'IN' | 'OUT'
   asset: string
   amount: string
   meta?: Record<string, unknown>
+  // Fully-resolved block-explorer URL for the on-chain transfer tx.
+  explorerLink?: string
 } & (
     | { counterpartyAccountIndex: number; counterpartyAddress?: string }
     | { counterpartyAccountIndex?: number; counterpartyAddress: string }
   )
 
+/** @public */
 export type ActivityItem =
   | DepositActivity
   | WithdrawalActivity
@@ -195,73 +215,36 @@ export type ActivityItem =
   | FundingActivity
   | TransferActivity
 
+/** @public */
 export interface ActivitiesResponse {
   provider: string
   items: ActivityItem[]
   pagination: Pagination
 }
 
-// ---------------------------------------------------------------------------
-// Account configuration state — typed `AccountResponse.config`
-// ---------------------------------------------------------------------------
+// Account configuration state — typed `AccountResponse.config`.
 
-/**
- * Hyperliquid record describing one authorised agent wallet on the
- * `userExtraAgents` response. Shape mirrors what the Hyperliquid info API
- * returns; the backend forwards the entries verbatim. The widget renders the
- * count / expiry on the `APPROVE_AGENT` setup descriptor.
- */
+/** @public */
 export type HyperliquidAgent = Record<string, unknown>
 
-/**
- * Hyperliquid builder-fee approval state. Surfaced by the backend after
- * comparing the user's `maxBuilderFee` against the configured LI.FI builder
- * fee for this dex. The widget uses `approved: false` to badge
- * `APPROVE_BUILDER_FEE` as outstanding.
- */
+/** @public */
 export interface HyperliquidBuilderFeeApproval {
   builderAddress: string
-  /** Maximum fee rate the user must approve, in basis points as a string. */
+  /** Basis points as a string. */
   maxFeeRate: string
   approved: boolean
 }
 
-/**
- * Hyperliquid-specific account configuration state.
- *
- * `abstractionMode: null` means abstraction has never been set; consumers
- * should fall back to the descriptor's `default` `ParamOption`.
- *
- * `builderFeeApproval` is absent when no builder is configured for this
- * provider; when present, `approved` reports whether the user has signed the
- * maximum builder fee.
- */
+/** @public */
 export interface HyperliquidAccountConfig {
   provider: 'hyperliquid'
+  /** `null` means abstraction has never been set. */
   abstractionMode: string | null
   agents: HyperliquidAgent[]
   builderFeeApproval?: HyperliquidBuilderFeeApproval
 }
 
-/**
- * Lighter-specific account configuration state.
- *
- * `accountIndex` is the L2 integer account identifier.
- *
- * `apiKeyRegistered` reports whether a key is currently live in the
- * `apiKeyIndex` slot; the `REGISTER_API_KEY` setup descriptor gates trading
- * on this.
- *
- * `accountType` is the raw integer fee/latency tier from Lighter's
- * `/api/v1/account.account_type` — decoding to a human label is left to the
- * consumer.
- *
- * `readOnlyTokenApproved` mirrors `apiKeyRegistered`'s shape but for the
- * long-lived read-only token. When `true`, `readOnlyTokenExpiry` and
- * `readOnlyTokenScope` MUST be present; when `false`, both MUST be absent.
- * The `APPROVE_READ_ONLY_TOKEN` setup descriptor gates query-only access on
- * this flag.
- */
+/** @public */
 export interface LighterAccountConfig {
   provider: 'lighter'
   accountIndex: number
@@ -271,44 +254,24 @@ export interface LighterAccountConfig {
   readOnlyTokenApproved: boolean
   /** Unix seconds. Present iff `readOnlyTokenApproved === true`. */
   readOnlyTokenExpiry?: number
-  /** Lighter's documented `single | all` scope. Present iff `readOnlyTokenApproved === true`. */
+  /** Present iff `readOnlyTokenApproved === true`. */
   readOnlyTokenScope?: 'single' | 'all'
 }
 
-/**
- * Discriminated union of per-provider account configuration state.
- * Narrow with `config.provider === '<key>'` to access provider-specific
- * fields. Adding a new provider means adding a new variant, NOT widening
- * to a record-keyed shape.
- */
+/** @public */
 export type AccountConfig = HyperliquidAccountConfig | LighterAccountConfig
 
-/**
- * The current value of a single descriptor parameter, as projected by the
- * SDK from the typed `AccountConfig` for widget consumption.
- *
- * `name` matches `Param.name` on the descriptor that produced it; `value`
- * is the current state in the primitive shape the descriptor declared.
- * `null` indicates "no current value" (the user has not made a selection
- * yet, or the provider has not surfaced one), and the widget should fall
- * back to the descriptor's `default` `ParamOption` (when present) or
- * render the control with no highlight.
- */
+/** @public */
 export interface AccountConfigValue {
   name: string
+  /** `null` means no current value — consumers fall back to the descriptor default. */
   value: string | number | boolean | null
 }
 
-/**
- * SDK projection of `AccountConfig` against a single descriptor — one
- * `AccountConfigSetting` per descriptor on `Provider.setup` /
- * `Provider.options`. `values` carries the current state for each `Param`
- * the descriptor declared.
- *
- * Consumers must NOT read `AccountConfig` directly — narrow through this
- * projection so a new provider variant doesn't require widget changes.
- */
+/** @public */
 export interface AccountConfigSetting {
   type: ActionType
   values: AccountConfigValue[]
+  /** `undefined` means satisfaction is tracked outside `AccountConfig` (e.g. backend `checkSetup`). */
+  satisfied?: boolean
 }