@lightconexyz/lightcone-sdk 0.8.1-rc.4 → 0.8.1-rc.40

package/README.md

@@ -69,7 +69,7 @@ async function main() {
     .amount(1_000_000n)
     .buildIx();
 
-  // 4. Build, sign, and submit a limit order
+  // 4. Fetch/cache immutable trading rules, validate exactly, sign, and submit
   const response = await client.orders().limitOrder()
     .maker(keypair.publicKey)
     .bid()
@@ -177,12 +177,137 @@ ws.subscribe({
 });
 ```
 
-Book streams are snapshot-only: every `book_update` frame carries the full top-20 levels per side (~50ms conflation) and replaces the previous book wholesale (`OrderbookState` handles this; never gate on `seq` — the initial snapshot after every (re)subscribe is `seq: 0`). Subscriptions accept an optional Hyperliquid-style aggregation (`nSigFigs` 2–5, `mantissa` 1/2/5 only with `nSigFigs: 5`; validate with `validateAggregation`). Each `(orderbook, aggregation)` pair is a distinct subscription, so one connection can hold the full-precision and a grouped view of the same book simultaneously — incoming frames are tagged with snake_case `n_sig_figs`/`mantissa` (absent = full precision); key state by `aggregationFromFrame(frame.n_sig_figs, frame.mantissa)`. See [`examples/ws_book_and_trades.ts`](examples/ws_book_and_trades.ts).
+Book streams are snapshot-only: every accepted `book_update` replaces the full
+top-20 view. `OrderbookState` discards equal/older `seq` values within a
+subscription generation and accepts forward gaps. Call `beginGeneration()` on
+reconnect/resubscribe; `resync: true` requires unsubscribe/resubscribe with the
+same aggregation. Each `(orderbook, aggregation)` pair needs its own state.
+Truncation flags are preserved and mean that side is not exhaustive. See
+[`examples/ws_book_and_trades.ts`](examples/ws_book_and_trades.ts).
+Each decoded bid and ask level includes exact decimal-string `quote_notional`.
+For grouped books, `price` is a display bucket boundary, so quote liquidity
+and totals must use `quote_notional` rather than `price * size`. The
+price-to-base-size `OrderbookState` maps do not retain quote notional; read it
+from the decoded `OrderBook` levels.
+Ticker consumers should use the supplied `mid`; it is engine-authoritative and
+may use one-sided-book or last-trade fallback.
+REST depth is a coherent projection that may briefly lag a mutation. Use its
+`revision` and `captured_at_ms` metadata, and expect revision gaps.
 
 ```typescript
 ws.subscribe({ type: "book_update", orderbook_ids: [orderbook.orderbookId], nSigFigs: 5, mantissa: 2 });
 ```
 
+Order submission accepts decimal strings and uses exact `bigint` construction.
+`submit()` fetches and caches `/api/orderbooks/{id}/decimals` before invoking a
+signer. Direct `sign()`/`finalize()` calls require the returned `OrderbookRules`.
+Raw amounts, explicit salts, and derived prices are preflighted against the same
+signed-64-bit admission rules; no tick or size normalization is implicit.
+
+### Wallet Balances and SOL Action Planning
+
+`depositTokenBalances()` returns a required exact nine-decimal
+`native_sol_balance` alongside the separate mint-keyed SPL map. Initialize
+`WalletDepositBalancesState` with `applyRestSnapshot(wallet, snapshot)` and feed
+the outer `wallet_deposit_balances` channel's nested snapshot, absolute SPL,
+absolute native-SOL, and status events to `applyEvent()`. Complete snapshots
+replace state even after a higher component slot; status and wrong-wallet events
+do not mutate it, pre-baseline component updates are ignored, and explicit-zero
+SPL updates remove their mint. Matching SPL updates with invalid or negative
+idle balances return `rejected` without mutation. `contextSlot` records the latest accepted
+component observation rather than enforcing global monotonic ordering.
+`combinedSolBalance()` sums native SOL and canonical WSOL with `bigint` precision
+while retaining both stored values. REST response types are trusted rather than
+runtime-decoded; WebSocket frames are validated strictly, while malformed REST
+exact values fail when a state method scales them. The reducer owns its map
+container but retains balance objects by reference, so treat applied payloads as
+immutable.
+
+`planSolSplit`, `planSolMerge`, `planSolRedeem`, and
+`planNativeSolWithdrawal` return unsigned action plans with live fee/rent costs,
+the action-specific reserve and spendable balance, and separate expected native
+and canonical WSOL deltas. Each planner requires complete matching-wallet state,
+checks the canonical account when needed, and fails closed when RPC estimates or
+native reserve are unavailable. Unsponsored actions reserve the greater of live
+costs and the applicable 0.001 SOL or 0.0035 SOL floor. Sponsored planning is
+rejected until a concrete sponsor owns transaction fees and account rent.
+An occupied canonical address is accepted only when it decodes as the wallet's
+initialized, unfrozen Tokenkeg native-mint account.
+
+Split plans consume canonical WSOL first and wrap only a shortfall in the same
+transaction. Merge and redeem plans retain proceeds in the persistent canonical
+account. Native withdrawal transfers directly when possible; otherwise it moves
+only the shortfall through a bounded seeded temporary Tokenkeg account and closes
+that temporary account before sending the exact native amount to the recipient.
+The temporary account's create, initialize, WSOL transfer, close, and native
+transfer instructions share one Solana transaction, so an instruction failure
+rolls the entire conversion back atomically. No planner closes the canonical
+account implicitly.
+
+Native-keypair self-custody users can explicitly call `planWrapSol` with a
+positive exact `bigint` lamport amount or call no-amount `planUnwrapWsolAll`.
+These standalone planners require the authenticated Trading Wallet's local
+native signing strategy; wallet-adapter and Privy strategies are rejected before
+RPC planning. Wrap creates or reuses only that wallet's canonical Tokenkeg ATA,
+transfers the exact amount, and runs `SyncNative`, the Token Program instruction
+that recalculates the WSOL token amount from account lamports. Wrap retains the
+ordinary 0.0035 SOL account-creation or 0.001 SOL existing-account reserve floor
+above lower live costs. Live decoded canonical amounts must match the authoritative
+wallet state. Wrap also requires an existing account's full lamports to equal
+its decoded token amount plus native rent reserve; unsynchronized direct
+donations reject before `SyncNative` can make the projected canonical delta
+inexact. Unwrap-all still accepts such excess and returns it on close.
+
+Unwrap-all accepts no partial amount and closes the entire positive canonical
+account back to the same wallet. Its `SolActionCosts` fields contain the fresh fee, zero
+upfront rent, no account creation, and no sponsorship. Availability reserves
+only that fee rather than the ordinary persistent-account floor;
+`unwrapAllSolBalanceAvailability(components, costs)` validates that complete
+cost tuple before deriving fee-only fields. The
+native delta credits every live account lamport, including refunded rent or
+direct donations, minus the fee and removes the full canonical token amount.
+Closing a pre-existing account returns all of its WSOL and means a future WSOL
+action may need to fund account rent again. Ordinary split, merge, redeem,
+claim, order, and native-withdraw paths never call these conversion planners or
+close canonical WSOL.
+
+For either explicit conversion, rebuild immediately before signing,
+submit with `signAndSubmitPreparedTxConfirmedWithSlot` so the wallet cannot
+replace the fee-estimated message, and refresh a complete snapshot covering its
+slot before restoring action authority. Prepared submission is unavailable for
+Privy because its final signed bytes cannot be verified by the SDK. Atomic
+execution does not resolve uncertain submission or confirmation errors; inspect
+authoritative balances before retrying. See the
+[persistent canonical WSOL ADR](../docs/adr/0001-persistent-canonical-wsol.md).
+
+WebSocket clients are owned independently from `Auth`; logout does not clean them
+up. For each retained client, `clearAuthedSubscriptions()` purges User/wallet
+reconnect tracking and queued authenticated messages. It does not stop an
+already-open server stream; send the matching unsubscribe or disconnect the socket
+for live teardown.
+
+The [`deposit_token_balances`](examples/deposit_token_balances.ts) self-custody
+example is manual-only and runs with `LIGHTCONE_ENV=local` or `staging` only
+when `SDK_API_URL`, `SDK_WS_URL`, `SDK_RPC_URL`, and `SDK_PROGRAM_ID` are all
+unset. It sends 0.001 SOL to the Python SDK wallet configured by
+`LIGHTCONE_WALLET_PATH_PYTHON` from the distinct sender configured by
+`LIGHTCONE_WALLET_PATH_TS`, confirms with a slot, and refreshes a complete
+snapshot at that slot. Running it moves funds. If it fails after submission,
+inspect authoritative balances before retrying because funds may already have moved.
+
+The separate [`wsol_conversion`](examples/wsol_conversion.ts) example runs with
+the TypeScript wallet in local aggregate runs and is included when the globally
+gated stateful example workflow is enabled for staging CI; that workflow
+currently disables all stateful CI jobs. Local runs may use a paid RPC while
+retaining built-in API, WebSocket, and program identity; an enabled staging-CI
+run may supply its managed endpoints. Direct staging runs remain override-free.
+It permits a pre-existing canonical balance, wraps exactly 0.001 SOL, prints the
+exact wallet, costs, full-account return, and future-rent warning, then unwraps
+the complete canonical account without pausing. It retains each frozen
+projection until a complete REST snapshot covers the confirmed slot. Any
+planning, signing, submission, or uncertain-confirmation failure exits without
+automatic retry.
+
 ### Step 5: Cancel an Order
 
 ```typescript
@@ -208,6 +333,8 @@ const txHash = await client.positions().merge()
   .signAndSubmit();
 ```
 
+`market.numOutcomes` is the validated protocol outcome count. Market deposit, merge, and unified withdrawal use it instead of the length of display outcome metadata. The pubkey-only `withdrawFromPosition()` builder requires `.numOutcomes(market.numOutcomes)` before building.
+
 ### Step 7: Withdraw
 
 ```typescript
@@ -222,6 +349,17 @@ const withdrawIx = client.positions().withdraw()
 
 Authentication is only required for user-specific endpoints. Authentication is session-based using ED25519 signed messages. The flow is: request a nonce, sign it with your wallet, and exchange it for a session cookie.
 
+Privy hosts can also authenticate with passwordless Email, Google, X, or Wallet. After every interactive success, call `client.auth().registerPrivy({ attempted_identity })`. The backend validates the exact selector against Privy's verified methods, creates or synchronizes the Account, and changes the Primary Login Identity only for a new Account. `session.user.identity` is that stable primary; `session.user.linked_identities` contains every connected method with primary first.
+
+Use `walletDisplayName(session.user, session.auth_method)` to show a shortened
+label for the wallet the session trades with, regardless of login identity.
+
+`session.user.max_slippage_preference` is an exact decimal string strictly below
+`10`, or `null` until one is stored. Persist a value greater than zero and less
+than 10 using `client.auth().updateMaxSlippagePreference(value)`; the method
+returns the canonical exact decimal string. Values at or above 10% remain valid
+order protection but are not remembered through this API.
+
 ### Cookie handling
 
 After login succeeds, the SDK stores the session token internally and attaches it as `Cookie: lightcone-token=…` on every authenticated request. Behaviour depends on the runtime:
@@ -235,14 +373,17 @@ After login succeeds, the SDK stores the session token internally and attaches i
 
 When the SDK runs on a server (SSR, an Express / Next.js route handler, etc.) and the *user's* `auth_token` cookie arrives on an incoming HTTP request, the SDK's process-wide token store is the wrong place to route it through — the store is shared across all users of that server process.
 
+> **Behavior change.** `getWithCookies` responses no longer capture `Set-Cookie` into the shared token slot (they previously did): a forwarded per-user request rotating its token must not leak that token to every later request from a shared server client. These requests also never consult the credential restorer.
+
 For these cases, authed methods that need per-call forwarding ship a `*WithAuth(authToken)` sibling that injects the cookie just for that one call:
 
 ```typescript
 // Inside a server route, after extracting the auth_token cookie
 // from the incoming request:
-const balances = await client
+const snapshot = await client
   .positions()
-  .depositTokenBalancesWithAuth(authToken);
+  .depositTokenBalancesWithCookies(undefined, authToken);
+console.log(`snapshot slot ${snapshot.context_slot}: ${Object.keys(snapshot.balances).length} balances`);
 
 const positions = await client
   .positions()
@@ -279,6 +420,8 @@ Each environment configures the API URL, WebSocket URL, Solana RPC URL, and on-c
 
 The Solana RPC URL can also be overridden via the `SDK_RPC_URL` environment variable, which takes precedence over the environment default. This is useful for pointing all examples at a private RPC to avoid public devnet rate limits.
 
+Favorite-market add and remove methods are idempotent set operations, so the SDK may safely replay them after supported credential restoration or transient transport failures. Per-call cookie variants used by SSR and route handlers retry transient failures with the supplied cookie but never invoke the process-wide credential restorer.
+
 ## Examples
 
 All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to the production environment and read the wallet keypair from `~/.config/solana/id.json`.
@@ -288,13 +431,13 @@ All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to
 | Example | Description |
 |---------|-------------|
 | [`login`](examples/login.ts) | Full auth lifecycle: sign message, login, check session, logout |
-| [`with_auth`](examples/with_auth.ts) | Per-call auth-token forwarding for SSR / route-handler consumers — logs in, captures the token via `client.authToken()`, clears the SDK's internal store, and exercises every `*WithAuth` variant |
+| [`with_cookies`](examples/with_cookies.ts) | Per-call cookie forwarding for SSR / route-handler consumers, including paginated favorite-market list/add/remove while restoring the original state |
 
 ### Market Discovery & Data
 
 | Example | Description |
 |---------|-------------|
-| [`markets`](examples/markets.ts) | Featured markets, paginated listing, fetch by pubkey, search, platform deposit assets via `globalDepositAssets()` |
+| [`markets`](examples/markets.ts) | Featured markets, paginated listing, fetch by pubkey, search, and platform deposit assets via `globalDepositAssets()`; authenticated favorite-market APIs are demonstrated by `with_cookies` |
 | [`orderbook`](examples/orderbook.ts) | Fetch orderbook depth (bids/asks) and decimal precision metadata |
 | [`trades`](examples/trades.ts) | Recent trade history with cursor-based pagination (per-orderbook and market-wide) |
 | [`price_history`](examples/price_history.ts) | Historical candlestick data (OHLCV) at various resolutions |
@@ -305,7 +448,7 @@ All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to
 
 | Example | Description |
 |---------|-------------|
-| [`submit_order`](examples/submit_order.ts) | Deposit the quote amount into the global pool, then place a limit order via `client.orders().limitOrder()` with human-readable price/size, auto-scaling, and fill tracking. Companion `cancel_order` cancels it and withdraws to stay net-neutral |
+| [`submit_order`](examples/submit_order.ts) | Deposit collateral, then place an exactly validated limit order using cached trading rules. Companion `cancel_order` cancels it and withdraws to stay net-neutral |
 
 ### Cancelling Orders
 
@@ -322,6 +465,16 @@ All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to
 | [`onchain_transactions`](examples/onchain_transactions.ts) | Build, sign, and submit mint/merge complete set and increment nonce on-chain |
 | [`global_deposit_withdrawal`](examples/global_deposit_withdrawal.ts) | Init position tokens, deposit to global pool, move capital into a market, extend an existing ALT, withdraw from global, and merge back to keep the run net-neutral |
 
+### Manual Fund-Moving Operations
+
+These examples refuse production and endpoint overrides and are intentionally
+excluded from routine example runs.
+
+| Example | Description |
+|---------|-------------|
+| [`deposit_token_balances`](examples/deposit_token_balances.ts) | Confirm an exact native withdrawal without closing canonical WSOL, then refresh complete state past the confirmed slot |
+| [`wsol_conversion`](examples/wsol_conversion.ts) | Wrap an exact native amount, warn, close and unwrap the complete canonical account, and hold frozen projections through covering refreshes |
+
 ### WebSocket Streaming
 
 | Example | Description |
@@ -359,6 +512,7 @@ When the backend rejects a request (insufficient balance, expired order, etc.),
 | `errorCode` | `string \| undefined` | API-level error code (for example `"NOT_FOUND"` or `"INVALID_ARGUMENT"`) |
 | `errorLogId` | `string \| undefined` | Backend support correlation ID (`LCERR_*`) |
 | `requestId` | `string \| undefined` | SDK-generated `x-request-id` for cross-service tracing |
+| `existingMethod` | `string \| undefined` | Primary method of the conflicting Account when identity ownership has one deterministic owner |
 
 `ApiRejectedDetails.toString()` formats all present fields as a multi-line report for logs or support tickets.
 
@@ -430,14 +584,29 @@ The SDK generates a UUID v4 `x-request-id` header on every HTTP request. On reje
 | `NotFound` | 404 - resource not found |
 | `BadRequest` | 400 - invalid request |
 | `Timeout` | Request timed out |
-| `MaxRetriesExceeded` | All retry attempts exhausted |
+| `MaxRetriesExceeded` | Never produced by the SDK itself: the HTTP retry loop propagates the final underlying error on exhaustion (structured details intact — see the retry-exhaustion tests). Kept public for consumer-built retry loops |
 
 ## Retry Strategy
 
-- **GET requests**: `RetryPolicy.Idempotent` - retries on transport failures and 502/503/504, backs off on 429 with exponential backoff + jitter.
-- **POST requests** (order submit, cancel, auth): `RetryPolicy.None` - no automatic retry. Non-idempotent actions are never retried to prevent duplicate side effects.
+- **Replay-safe requests**: GETs and idempotent set operations such as favorite-market updates use `RetryPolicy.Idempotent`, which retries transport failures and 502/503/504 and backs off on 429 with exponential backoff + jitter.
+- **Non-idempotent requests** (order submit, cancel, auth): `RetryPolicy.None` - no automatic retry, which prevents duplicate side effects.
 - Customizable per-call with `RetryPolicy.custom(config)`.
 
+### Credential restoration (401 recovery)
+
+Sessions built on short-lived tokens expire mid-run: the backend starts answering 401 even though the app could mint a fresh token (e.g. a browser refreshing its Privy session). Rather than every caller hand-rolling "detect 401 → refresh → retry", the transport accepts a host-supplied hook:
+
+```typescript
+client.setCredentialRestorer(async () => {
+  // e.g. ask the auth provider's SDK to refresh the session
+  return await refreshSession();
+});
+```
+
+When a request to the API origin fails with HTTP 401 and a restorer is registered, the transport consults it **at most once per logical request**, with concurrent 401s sharing one restoration (bounded by a 30-second timeout). A successful restoration replays the request once **only if it declared itself retry-safe** (an idempotent/custom retry policy); `RetryPolicy.None` requests — mutations like orders and cancels — are never auto-replayed: the restoration still heals the session for the caller's next attempt, but the original 401 propagates. Restoration is skipped for credential-management endpoints (login, logout) and for cookie-override/custom-session requests, redirects are never followed on the API transport, and without a registered restorer 401s propagate unchanged. A timed-out restoration has its `AbortSignal` fired — promises cannot be cancelled, so restorers whose work is non-idempotent (refresh-token rotation) must honor the signal or serialize internally.
+
+The SDK stays credential-agnostic: what "restore" means belongs to the host. For classifying auth failures in your own code, use `isUnauthorized(error)` from the error module — it covers both bare 401s and 401s carrying a structured rejection envelope (`ApiRejectedDetails.httpStatus`).
+
 ## Trigger Orders
 
 Trigger orders (stop-limit, take-profit-limit) are under development and not yet available. Internal types exist in the source for internal use only.

package/dist/auth/client.d.ts

@@ -1,5 +1,17 @@
 import { type LightconeHttp } from "../http";
-import type { AuthCredentials, SessionResponse } from "./index";
+import type { AuthCredentials, LinkedIdentityType, RegisterPrivyRequest, SessionResponse } from "./index";
+/** Bounded ownership conflicts safe for client recovery guidance. */
+export type RegisterPrivyConflict = {
+    code: "IDENTITY_OWNED_BY_ANOTHER_ACCOUNT";
+    existingMethod?: LinkedIdentityType;
+} | {
+    code: "IDENTITIES_OWNED_BY_MULTIPLE_ACCOUNTS";
+} | {
+    code: "WALLET_OWNED_BY_ANOTHER_ACCOUNT";
+    existingMethod?: LinkedIdentityType;
+};
+/** Classify only stable register-or-sync ownership rejection codes. */
+export declare function classifyRegisterPrivyConflict(error: unknown): RegisterPrivyConflict | undefined;
 interface AuthState {
     getCredentials(): AuthCredentials | undefined;
     setCredentials(credentials: AuthCredentials | undefined): void;
@@ -15,8 +27,22 @@ export declare class Auth {
     getNonce(): Promise<string>;
     loginWithMessage(message: string, signatureBs58: string, pubkeyBytes: Uint8Array, useEmbeddedWallet?: boolean): Promise<SessionResponse>;
     checkSession(): Promise<SessionResponse>;
+    /**
+     * Logout — clears the server-side cookie, internal token, and credentials.
+     *
+     * Local state is cleared even when the server call fails — the caller asked
+     * to be signed out locally regardless — but the failure is then rethrown:
+     * callers gating security decisions on teardown (e.g. whether an app may
+     * restart an authenticated transport) must be able to see that the
+     * server-side cookie may still be valid. A 401 counts as success: it means
+     * "already logged out".
+     */
     logout(): Promise<void>;
     disconnectX(): Promise<void>;
+    /** Create or synchronize a Privy Account and install the resulting session. */
+    registerPrivy(request: RegisterPrivyRequest): Promise<SessionResponse>;
+    /** Persist an account-wide max-slippage preference strictly below 10%. */
+    updateMaxSlippagePreference(maxSlippagePreference: string): Promise<string>;
     connectXUrl(): string;
     credentials(): AuthCredentials | undefined;
     isAuthenticated(): boolean;

package/dist/auth/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAA+B,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7F,UAAU,SAAS;IACjB,cAAc,IAAI,eAAe,GAAG,SAAS,CAAC;IAC9C,cAAc,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/D,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,IAAI;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAE5C,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAM3B,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,OAAO,GAC1B,OAAO,CAAC,eAAe,CAAC;IAoBrB,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAgBxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAavB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC,WAAW,IAAI,MAAM;IAIrB,WAAW,IAAI,eAAe,GAAG,SAAS;IAI1C,eAAe,IAAI,OAAO;CAO3B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,KAAK,EACV,eAAe,EAIf,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,mCAAmC,CAAC;IAC1C,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC,GACD;IAAE,IAAI,EAAE,uCAAuC,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,iCAAiC,CAAC;IACxC,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACrC,CAAC;AAEN,uEAAuE;AACvE,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,SAAS,CAoBnC;AAED,UAAU,SAAS;IACjB,cAAc,IAAI,eAAe,GAAG,SAAS,CAAC;IAC9C,cAAc,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/D,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,IAAI;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAE5C,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAS3B,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,OAAO,GAC1B,OAAO,CAAC,eAAe,CAAC;IAwBrB,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAoB9C;;;;;;;;;OASG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBvB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IASlC,+EAA+E;IACzE,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAe5E,0EAA0E;IACpE,2BAA2B,CAC/B,qBAAqB,EAAE,MAAM,GAC5B,OAAO,CAAC,MAAM,CAAC;IAuBlB,WAAW,IAAI,MAAM;IAIrB,WAAW,IAAI,eAAe,GAAG,SAAS;IAI1C,eAAe,IAAI,OAAO;CAO3B"}

package/dist/auth/client.js

@@ -1,10 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Auth = void 0;
+exports.classifyRegisterPrivyConflict = classifyRegisterPrivyConflict;
 const error_1 = require("../error");
 const http_1 = require("../http");
 const shared_1 = require("../shared");
 const index_1 = require("./index");
+/** Classify only stable register-or-sync ownership rejection codes. */
+function classifyRegisterPrivyConflict(error) {
+    if (!(error instanceof error_1.SdkError) || error.variant !== "ApiRejected")
+        return undefined;
+    const details = error.apiRejectedDetails;
+    switch (details?.errorCode) {
+        case "IDENTITY_OWNED_BY_ANOTHER_ACCOUNT":
+            return {
+                code: details.errorCode,
+                existingMethod: details.existingMethod,
+            };
+        case "IDENTITIES_OWNED_BY_MULTIPLE_ACCOUNTS":
+            return { code: details.errorCode };
+        case "WALLET_OWNED_BY_ANOTHER_ACCOUNT":
+            return {
+                code: details.errorCode,
+                existingMethod: details.existingMethod,
+            };
+        default:
+            return undefined;
+    }
+}
 class Auth {
     client;
     constructor(client) {
@@ -23,7 +46,12 @@ class Auth {
             pubkey_bytes: Array.from(pubkeyBytes),
             use_embedded_wallet: useEmbeddedWallet,
         };
-        const session = await this.client.http.post(url, body, http_1.RetryPolicy.None);
+        // Credential-management endpoint: opts out of the transport's 401
+        // restore-and-replay. The backend consumes the login nonce before
+        // verifying the signature, so a replayed login deterministically fails —
+        // and restoring credentials in order to log in is circular.
+        const session = await this.client.http.postWithoutCredentialRestore(url, body, http_1.RetryPolicy.None);
+        normalizeSessionMaxSlippagePreference(session);
         this.client.authState.setCredentials(credentialsFromSession(session));
         return session;
     }
@@ -32,6 +60,7 @@ class Auth {
         let session;
         try {
             session = await this.client.http.get(url, http_1.RetryPolicy.Idempotent);
+            normalizeSessionMaxSlippagePreference(session);
         }
         catch (error) {
             this.client.authState.setCredentials(undefined);
@@ -40,22 +69,58 @@ class Auth {
         this.client.authState.setCredentials(credentialsFromSession(session));
         return session;
     }
+    /**
+     * Logout — clears the server-side cookie, internal token, and credentials.
+     *
+     * Local state is cleared even when the server call fails — the caller asked
+     * to be signed out locally regardless — but the failure is then rethrown:
+     * callers gating security decisions on teardown (e.g. whether an app may
+     * restart an authenticated transport) must be able to see that the
+     * server-side cookie may still be valid. A 401 counts as success: it means
+     * "already logged out".
+     */
     async logout() {
         const url = `${this.client.http.baseUrl()}/api/auth/logout`;
+        let logoutError = null;
         try {
-            await this.client.http.post(url, {}, http_1.RetryPolicy.None);
+            // Credential-management endpoint: opts out of the transport's 401
+            // restore-and-replay — a 401 here means "already logged out".
+            await this.client.http.postWithoutCredentialRestore(url, {}, http_1.RetryPolicy.None);
         }
-        catch {
-            // Backend cookie clear can fail in local/dev setups; still clear local state.
+        catch (error) {
+            if (!(0, error_1.isUnauthorized)(error)) {
+                logoutError = error;
+            }
         }
         await this.client.http.clearAuthToken();
         this.client.authState.setCredentials(undefined);
         await this.client.authState.clearCaches();
+        if (logoutError !== null) {
+            throw logoutError;
+        }
     }
     async disconnectX() {
         const url = `${this.client.http.baseUrl()}/api/auth/disconnect_x`;
         await this.client.http.post(url, {}, http_1.RetryPolicy.None);
     }
+    /** Create or synchronize a Privy Account and install the resulting session. */
+    async registerPrivy(request) {
+        const url = `${this.client.http.baseUrl()}/api/auth/register-privy`;
+        const session = await this.client.http.post(url, request, http_1.RetryPolicy.Idempotent);
+        normalizeSessionMaxSlippagePreference(session);
+        this.client.authState.setCredentials(credentialsFromSession(session));
+        return session;
+    }
+    /** Persist an account-wide max-slippage preference strictly below 10%. */
+    async updateMaxSlippagePreference(maxSlippagePreference) {
+        const url = `${this.client.http.baseUrl()}/api/auth/max_slippage_preference`;
+        const response = await this.client.http.post(url, { max_slippage_preference: maxSlippagePreference }, http_1.RetryPolicy.Idempotent);
+        const preference = decodeMaxSlippagePreference(response, false, "update response");
+        if (preference === null) {
+            throw error_1.SdkError.serde("Max-slippage update response must contain a decimal string");
+        }
+        return preference;
+    }
     connectXUrl() {
         return `${this.client.http.baseUrl()}/api/auth/oauth/link/x`;
     }
@@ -71,6 +136,31 @@ class Auth {
     }
 }
 exports.Auth = Auth;
+function normalizeSessionMaxSlippagePreference(session) {
+    const preference = decodeMaxSlippagePreference(session?.user, true, "session user", true);
+    session.user.max_slippage_preference = preference;
+}
+/** Enforces the exact nullable/string JSON contract erased by TypeScript types. */
+function decodeMaxSlippagePreference(payload, allowNull, context, allowMissing = false) {
+    if (typeof payload !== "object" || payload === null) {
+        throw error_1.SdkError.serde(`Max-slippage ${context} is malformed`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(payload, "max_slippage_preference")) {
+        if (allowMissing) {
+            return null;
+        }
+        throw error_1.SdkError.serde(`Max-slippage ${context} is missing max_slippage_preference`);
+    }
+    const preference = payload
+        .max_slippage_preference;
+    if (typeof preference === "string") {
+        return preference;
+    }
+    if (allowNull && preference === null) {
+        return null;
+    }
+    throw error_1.SdkError.serde(`Max-slippage ${context} must contain ${allowNull ? "a string or null" : "a string"}`);
+}
 /**
  * Derive session credentials from the envelope. The trading wallet comes from
  * the identity + auth method.

package/dist/auth/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { SdkError } from \"../error\";\nimport { RetryPolicy, type LightconeHttp } from \"../http\";\nimport { asPubkeyStr } from \"../shared\";\nimport { tradingWallet } from \"./index\";\nimport type { AuthCredentials, LoginRequest, NonceResponse, SessionResponse } from \"./index\";\n\ninterface AuthState {\n  getCredentials(): AuthCredentials | undefined;\n  setCredentials(credentials: AuthCredentials | undefined): void;\n  clearCaches(): Promise<void>;\n}\n\ninterface ClientContext {\n  http: LightconeHttp;\n  authState: AuthState;\n}\n\nexport class Auth {\n  constructor(private readonly client: ClientContext) {}\n\n  async getNonce(): Promise<string> {\n    const url = `${this.client.http.baseUrl()}/api/auth/nonce`;\n    const response = await this.client.http.get<NonceResponse>(url, RetryPolicy.None);\n    return response.nonce;\n  }\n\n  async loginWithMessage(\n    message: string,\n    signatureBs58: string,\n    pubkeyBytes: Uint8Array,\n    useEmbeddedWallet?: boolean\n  ): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/login_or_register_with_message`;\n    const body: LoginRequest = {\n      message,\n      signature_bs58: signatureBs58,\n      pubkey_bytes: Array.from(pubkeyBytes),\n      use_embedded_wallet: useEmbeddedWallet,\n    };\n\n    const session = await this.client.http.post<SessionResponse, LoginRequest>(\n      url,\n      body,\n      RetryPolicy.None\n    );\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  async checkSession(): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/me`;\n\n    let session: SessionResponse;\n    try {\n      session = await this.client.http.get<SessionResponse>(url, RetryPolicy.Idempotent);\n    } catch (error) {\n      this.client.authState.setCredentials(undefined);\n      throw SdkError.from(error);\n    }\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  async logout(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/logout`;\n    try {\n      await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n    } catch {\n      // Backend cookie clear can fail in local/dev setups; still clear local state.\n    }\n\n    await this.client.http.clearAuthToken();\n    this.client.authState.setCredentials(undefined);\n    await this.client.authState.clearCaches();\n  }\n\n  async disconnectX(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/disconnect_x`;\n    await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n  }\n\n  connectXUrl(): string {\n    return `${this.client.http.baseUrl()}/api/auth/oauth/link/x`;\n  }\n\n  credentials(): AuthCredentials | undefined {\n    return this.client.authState.getCredentials();\n  }\n\n  isAuthenticated(): boolean {\n    const credentials = this.credentials();\n    if (!credentials) {\n      return false;\n    }\n    return Date.now() < credentials.expires_at.getTime();\n  }\n}\n\n/**\n * Derive session credentials from the envelope. The trading wallet comes from\n * the identity + auth method.\n */\nfunction credentialsFromSession(session: SessionResponse): AuthCredentials {\n  return {\n    user_id: session.user.user_id,\n    wallet_address: asPubkeyStr(tradingWallet(session.user, session.auth_method)),\n    expires_at: parseExpiry(session.expires_at),\n  };\n}\n\nfunction parseExpiry(timestamp: number): Date {\n  if (timestamp > 1_000_000_000_000) {\n    return new Date(timestamp);\n  }\n  return new Date(timestamp * 1000);\n}\n"]}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { SdkError, isUnauthorized } from \"../error\";\nimport { RetryPolicy, type LightconeHttp } from \"../http\";\nimport { asPubkeyStr } from \"../shared\";\nimport { tradingWallet } from \"./index\";\nimport type {\n  AuthCredentials,\n  LoginRequest,\n  MaxSlippagePreferenceBody,\n  NonceResponse,\n  LinkedIdentityType,\n  RegisterPrivyRequest,\n  SessionResponse,\n} from \"./index\";\n\n/** Bounded ownership conflicts safe for client recovery guidance. */\nexport type RegisterPrivyConflict =\n  | {\n      code: \"IDENTITY_OWNED_BY_ANOTHER_ACCOUNT\";\n      existingMethod?: LinkedIdentityType;\n    }\n  | { code: \"IDENTITIES_OWNED_BY_MULTIPLE_ACCOUNTS\" }\n  | {\n      code: \"WALLET_OWNED_BY_ANOTHER_ACCOUNT\";\n      existingMethod?: LinkedIdentityType;\n    };\n\n/** Classify only stable register-or-sync ownership rejection codes. */\nexport function classifyRegisterPrivyConflict(\n  error: unknown,\n): RegisterPrivyConflict | undefined {\n  if (!(error instanceof SdkError) || error.variant !== \"ApiRejected\")\n    return undefined;\n  const details = error.apiRejectedDetails;\n  switch (details?.errorCode) {\n    case \"IDENTITY_OWNED_BY_ANOTHER_ACCOUNT\":\n      return {\n        code: details.errorCode,\n        existingMethod: details.existingMethod,\n      };\n    case \"IDENTITIES_OWNED_BY_MULTIPLE_ACCOUNTS\":\n      return { code: details.errorCode };\n    case \"WALLET_OWNED_BY_ANOTHER_ACCOUNT\":\n      return {\n        code: details.errorCode,\n        existingMethod: details.existingMethod,\n      };\n    default:\n      return undefined;\n  }\n}\n\ninterface AuthState {\n  getCredentials(): AuthCredentials | undefined;\n  setCredentials(credentials: AuthCredentials | undefined): void;\n  clearCaches(): Promise<void>;\n}\n\ninterface ClientContext {\n  http: LightconeHttp;\n  authState: AuthState;\n}\n\nexport class Auth {\n  constructor(private readonly client: ClientContext) {}\n\n  async getNonce(): Promise<string> {\n    const url = `${this.client.http.baseUrl()}/api/auth/nonce`;\n    const response = await this.client.http.get<NonceResponse>(\n      url,\n      RetryPolicy.None,\n    );\n    return response.nonce;\n  }\n\n  async loginWithMessage(\n    message: string,\n    signatureBs58: string,\n    pubkeyBytes: Uint8Array,\n    useEmbeddedWallet?: boolean,\n  ): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/login_or_register_with_message`;\n    const body: LoginRequest = {\n      message,\n      signature_bs58: signatureBs58,\n      pubkey_bytes: Array.from(pubkeyBytes),\n      use_embedded_wallet: useEmbeddedWallet,\n    };\n\n    // Credential-management endpoint: opts out of the transport's 401\n    // restore-and-replay. The backend consumes the login nonce before\n    // verifying the signature, so a replayed login deterministically fails —\n    // and restoring credentials in order to log in is circular.\n    const session = await this.client.http.postWithoutCredentialRestore<\n      SessionResponse,\n      LoginRequest\n    >(url, body, RetryPolicy.None);\n    normalizeSessionMaxSlippagePreference(session);\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  async checkSession(): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/me`;\n\n    let session: SessionResponse;\n    try {\n      session = await this.client.http.get<SessionResponse>(\n        url,\n        RetryPolicy.Idempotent,\n      );\n      normalizeSessionMaxSlippagePreference(session);\n    } catch (error) {\n      this.client.authState.setCredentials(undefined);\n      throw SdkError.from(error);\n    }\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  /**\n   * Logout — clears the server-side cookie, internal token, and credentials.\n   *\n   * Local state is cleared even when the server call fails — the caller asked\n   * to be signed out locally regardless — but the failure is then rethrown:\n   * callers gating security decisions on teardown (e.g. whether an app may\n   * restart an authenticated transport) must be able to see that the\n   * server-side cookie may still be valid. A 401 counts as success: it means\n   * \"already logged out\".\n   */\n  async logout(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/logout`;\n    let logoutError: unknown = null;\n    try {\n      // Credential-management endpoint: opts out of the transport's 401\n      // restore-and-replay — a 401 here means \"already logged out\".\n      await this.client.http.postWithoutCredentialRestore<\n        { success: boolean },\n        Record<string, never>\n      >(url, {}, RetryPolicy.None);\n    } catch (error) {\n      if (!isUnauthorized(error)) {\n        logoutError = error;\n      }\n    }\n\n    await this.client.http.clearAuthToken();\n    this.client.authState.setCredentials(undefined);\n    await this.client.authState.clearCaches();\n\n    if (logoutError !== null) {\n      throw logoutError;\n    }\n  }\n\n  async disconnectX(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/disconnect_x`;\n    await this.client.http.post<{ success: boolean }, Record<string, never>>(\n      url,\n      {},\n      RetryPolicy.None,\n    );\n  }\n\n  /** Create or synchronize a Privy Account and install the resulting session. */\n  async registerPrivy(request: RegisterPrivyRequest): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/register-privy`;\n    const session = await this.client.http.post<\n      SessionResponse,\n      RegisterPrivyRequest\n    >(\n      url,\n      request,\n      RetryPolicy.Idempotent,\n    );\n    normalizeSessionMaxSlippagePreference(session);\n    this.client.authState.setCredentials(credentialsFromSession(session));\n    return session;\n  }\n\n  /** Persist an account-wide max-slippage preference strictly below 10%. */\n  async updateMaxSlippagePreference(\n    maxSlippagePreference: string,\n  ): Promise<string> {\n    const url = `${this.client.http.baseUrl()}/api/auth/max_slippage_preference`;\n    const response = await this.client.http.post<\n      MaxSlippagePreferenceBody,\n      MaxSlippagePreferenceBody\n    >(\n      url,\n      { max_slippage_preference: maxSlippagePreference },\n      RetryPolicy.Idempotent,\n    );\n    const preference = decodeMaxSlippagePreference(\n      response,\n      false,\n      \"update response\",\n    );\n    if (preference === null) {\n      throw SdkError.serde(\n        \"Max-slippage update response must contain a decimal string\",\n      );\n    }\n    return preference;\n  }\n\n  connectXUrl(): string {\n    return `${this.client.http.baseUrl()}/api/auth/oauth/link/x`;\n  }\n\n  credentials(): AuthCredentials | undefined {\n    return this.client.authState.getCredentials();\n  }\n\n  isAuthenticated(): boolean {\n    const credentials = this.credentials();\n    if (!credentials) {\n      return false;\n    }\n    return Date.now() < credentials.expires_at.getTime();\n  }\n}\n\nfunction normalizeSessionMaxSlippagePreference(session: SessionResponse): void {\n  const preference = decodeMaxSlippagePreference(\n    session?.user,\n    true,\n    \"session user\",\n    true,\n  );\n  session.user.max_slippage_preference = preference;\n}\n\n/** Enforces the exact nullable/string JSON contract erased by TypeScript types. */\nfunction decodeMaxSlippagePreference(\n  payload: unknown,\n  allowNull: boolean,\n  context: string,\n  allowMissing = false,\n): string | null {\n  if (typeof payload !== \"object\" || payload === null) {\n    throw SdkError.serde(`Max-slippage ${context} is malformed`);\n  }\n  if (\n    !Object.prototype.hasOwnProperty.call(payload, \"max_slippage_preference\")\n  ) {\n    if (allowMissing) {\n      return null;\n    }\n    throw SdkError.serde(\n      `Max-slippage ${context} is missing max_slippage_preference`,\n    );\n  }\n\n  const preference = (payload as Record<string, unknown>)\n    .max_slippage_preference;\n  if (typeof preference === \"string\") {\n    return preference;\n  }\n  if (allowNull && preference === null) {\n    return null;\n  }\n  throw SdkError.serde(\n    `Max-slippage ${context} must contain ${allowNull ? \"a string or null\" : \"a string\"}`,\n  );\n}\n\n/**\n * Derive session credentials from the envelope. The trading wallet comes from\n * the identity + auth method.\n */\nfunction credentialsFromSession(session: SessionResponse): AuthCredentials {\n  return {\n    user_id: session.user.user_id,\n    wallet_address: asPubkeyStr(\n      tradingWallet(session.user, session.auth_method),\n    ),\n    expires_at: parseExpiry(session.expires_at),\n  };\n}\n\nfunction parseExpiry(timestamp: number): Date {\n  if (timestamp > 1_000_000_000_000) {\n    return new Date(timestamp);\n  }\n  return new Date(timestamp * 1000);\n}\n"]}

package/dist/auth/index.d.ts

@@ -48,6 +48,46 @@ export interface GoogleAccountData {
     family_name?: string;
     avatar_url?: string;
 }
+/** Canonical address for a passwordless Email login identity. */
+export interface EmailAccountData {
+    email: string;
+}
+/** Public login-method names exposed in profiles and bounded conflicts. */
+export type LinkedIdentityType = "email" | "google" | "x" | "wallet";
+/** Connected Login Identity without repeated Account-level Privy wallet data. */
+export type LinkedIdentity = {
+    type: "email";
+    account: EmailAccountData;
+} | {
+    type: "google";
+    account: GoogleAccountData;
+} | {
+    type: "x";
+    account: XAccountData;
+} | {
+    type: "wallet";
+    address: string;
+    chain: ChainType;
+};
+/** Verified method and canonical identifier that initiated Privy authentication. */
+export type LinkedIdentitySelector = {
+    type: "email";
+    email: string;
+} | {
+    type: "google";
+    email: string;
+} | {
+    type: "x";
+    username: string;
+} | {
+    type: "wallet";
+    address: string;
+    chain: ChainType;
+};
+/** Register-or-sync request naming the verified attempted identity. */
+export interface RegisterPrivyRequest {
+    attempted_identity: LinkedIdentitySelector;
+}
 /**
  * The login identity — how the user authenticates. `type` narrows the variant.
  *
@@ -57,6 +97,10 @@ export interface GoogleAccountData {
  * self-custody.
  */
 export type UserIdentity = {
+    type: "email";
+    account: EmailAccountData;
+    privy: UserPrivyData;
+} | {
     type: "google";
     account: GoogleAccountData;
     privy: UserPrivyData;
@@ -74,6 +118,10 @@ export type UserIdentity = {
 export interface User {
     user_id: string;
     identity: UserIdentity;
+    /** Every verified login identity connected to the Account, primary first. */
+    linked_identities?: LinkedIdentity[];
+    /** Remembered account-wide percentage below 10%; null until one is stored. */
+    max_slippage_preference: string | null;
     /** X account connected by a non-X-identity user; absent when identity is X. */
     connected_x?: XAccountData;
 }
@@ -88,8 +136,12 @@ export interface SessionResponse {
     auth_method: AuthMethod;
     is_beta: boolean;
 }
-/** Human-readable login-method label ("Google" / "X" / "Solana"). */
-export declare function identityText(identity: UserIdentity): "Google" | "X" | "Solana";
+/** Exact decimal-string body used to update and return max slippage. */
+export interface MaxSlippagePreferenceBody {
+    max_slippage_preference: string;
+}
+/** Human-readable login-method label ("Email" / "Google" / "X" / "Solana"). */
+export declare function identityText(identity: UserIdentity): "Email" | "Google" | "X" | "Solana";
 /** Privy account data, regardless of identity type. */
 export declare function userPrivy(user: User): UserPrivyData | undefined;
 /** The X account, whether it is the login identity or a connected account. */
@@ -104,10 +156,12 @@ export declare function userXAccount(user: User): XAccountData | undefined;
  * wallet that signed in.
  */
 export declare function tradingWallet(user: User, authMethod: AuthMethod): string;
+/** Short display label for the wallet a session operates as. */
+export declare function walletDisplayName(user: User, authMethod: AuthMethod): string;
 /**
- * Best display name for the user. Google: `name`, falling back to the email;
- * X: `display_name`, falling back to the username; wallet identities show the
- * shortened address (`FRGk...WcPR`).
+ * Best display name for the user. Email addresses are limited to 20 characters;
+ * Google uses `name` with an email fallback; X uses `display_name` with a
+ * username fallback; wallet identities show the shortened address (`FRGk...WcPR`).
  */
 export declare function displayName(user: User): string;
 /** Avatar URL from the login identity's OAuth provider, if any. */