@pulsepairs/sdk 0.2.0

package/README.md

@@ -0,0 +1,264 @@
+# @pulsepairs/sdk
+
+Standalone SDK for the **UpDown** (PulsePairs) up/down prediction markets —
+BTC-USD / ETH-USD, UP or DOWN, on 5-minute / 15-minute / 1-hour cycles.
+
+This is the package [rain.trade](https://rain.trade) integrates to surface
+UpDown markets alongside Rain's own markets ("satellite" integration, Option A).
+It is deliberately **segregated** from `rain-sdk-v2`: bump this package's version
+independently, no release coupling.
+
+It gives you three things:
+
+1. **Matcher client** — typed REST + WebSocket client for the off-chain
+   order book (`UpDownHttpClient`, `UpDownWsClient`).
+2. **EIP-712 + trade-math** — `buildOrderTypedData` / `buildCancelTypedData` /
+   `buildWsAuthTypedData`, plus fee/stake/price helpers that mirror the backend
+   and contract exactly.
+3. **Account Kit signing** — `UpDownAccountKitSigner`: sign orders with an
+   Alchemy smart-contract account (the SAME wallet rain.trade uses), plus
+   gasless onboarding / approve / withdraw.
+
+> **Live integration environment:** a public demo of the full stack (markets
+> cycling 24/7 on Arbitrum One, mock oracle, mintable test USDT) runs at
+> **https://demo-pulsepairs.rainwins.com** with the matcher API/WS at
+> **`https://api.demo-pulsepairs.rainwins.com`** (`wss://…/stream`). Every
+> example below targets it by default. Test funds: `POST /test/devmint`
+> (10k cap, 1 mint per address per 5 min — mint to the **smart-account**
+> address, not the owner EOA; it also seeds a little gas ETH).
+
+---
+
+## Install
+
+```bash
+npm install @pulsepairs/sdk viem
+# For Account Kit (smart-account) signing, also install the peer deps rain.trade
+# already ships (skip if you only use the EOA / private-key path):
+npm install @account-kit/wallet-client@^4.88 @account-kit/infra@^4.88 \
+            @account-kit/smart-contracts@^4.88 @aa-sdk/core@^4.88
+```
+
+`viem` is a required peer. The four `@account-kit/*`/`@aa-sdk/*` packages are
+**optional** peers — they are lazy-imported and only needed if you construct
+`UpDownAccountKitSigner` (`smart-contracts` specifically backs the popup-less
+order-session signing below). A pure-EOA bot never pulls any of them.
+
+---
+
+## Two signing paths
+
+The matcher and contract are signer-agnostic (on-chain verification is OZ
+`SignatureChecker`, which accepts EOAs **and** ERC-1271 smart accounts). Pick:
+
+| Path | `order.maker` | Sign with | Use for |
+|---|---|---|---|
+| **EOA** (`examples/simple-*`) | your EOA | `viem` `account.signTypedData` | bots, scripts, testing |
+| **Account Kit** (`examples/account-kit-taker.ts`) | your **SCA** | `UpDownAccountKitSigner` | rain.trade / any smart-wallet UX |
+
+---
+
+## Quickstart — EOA (bots)
+
+```ts
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { arbitrum } from "viem/chains";
+import {
+  UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance,
+  parseCompositeMarketKey, parseStake, OrderType, OrderSide, Option,
+} from "@pulsepairs/sdk";
+
+const api = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+const cfg = await api.getConfig();                    // never hardcode addresses
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
+  .filter((m) => m.status === "ACTIVE");
+const { settlementAddress, marketId } = parseCompositeMarketKey(live.address)!;
+
+const amount = parseStake("5");
+const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n; // peak fee
+const nonce = BigInt(Math.floor(Math.random() * 1e12));
+const typedData = buildOrderTypedData({
+  cfg, settlementAddress,
+  message: { maker: account.address, market: BigInt(marketId), option: BigInt(Option.UP),
+    side: OrderSide.BUY, type: OrderType.MARKET, price: 0n, amount, maxFee, nonce,
+    expiry: BigInt(live.endTime) },
+});
+const signature = await account.signTypedData(typedData);
+await api.postOrder({ maker: account.address, market: live.address, option: Option.UP,
+  side: OrderSide.BUY, type: OrderType.MARKET, price: 0, amount: amount.toString(),
+  maxFee: maxFee.toString(), nonce: Number(nonce), expiry: live.endTime, signature });
+```
+
+Full runnable scripts: `examples/simple-taker.ts` (MARKET), `examples/simple-maker.ts`
+(LIMIT + authed WS), `examples/full-dmm-bot.ts` (two-sided quoting).
+
+---
+
+## Quickstart — Account Kit (rain.trade / smart wallets)
+
+`UpDownAccountKitSigner` builds its own Alchemy smart-wallet client using the
+**same config rain.trade's `RainAA` uses**, so the same owner EOA resolves to
+the **same SCA address** → one wallet across both products.
+
+```ts
+import { arbitrum } from "viem/chains";
+import { UpDownAccountKitSigner, buildOrderTypedData, UpDownHttpClient } from "@pulsepairs/sdk";
+
+const ak = new UpDownAccountKitSigner({
+  walletClient: window.ethereum,                 // owner EOA provider (or connector.getProvider())
+  alchemyApiKey: import.meta.env.VITE_ALCHEMY_API_KEY,       // SAME as rain.trade
+  paymasterPolicyId: import.meta.env.VITE_PAYMASTER_POLICY_ID, // SAME as rain.trade
+  chain: arbitrum,                               // SAME as rain.trade (42161)
+});
+const sca = await ak.connect();                  // deterministic; == rain.trade's SCA
+
+// Deploy-before-fill: ONE UserOp deploys the SCA + approves USDT + installs
+// the popup-less order-session key (see "Popup-less order signing" below).
+await ak.onboard({ usdt: cfg.usdtAddress, settlement });
+
+// Owner-key ERC-1271 order signature (6492 wrapper stripped automatically).
+const signature = await ak.signTypedDataBare(buildOrderTypedData({ cfg, settlementAddress, message }));
+
+// WS auth for orders:/balance: channels (keyed by the SCA):
+ws.connectAuthed({ channels: [`orders:${sca.toLowerCase()}`], signAuth: () => ak.signWsAuth(cfg.chainId) });
+```
+
+See `examples/account-kit-taker.ts` for the end-to-end flow.
+
+### Already have rain.trade's smart-wallet client?
+
+If the host app owns an Alchemy client (e.g. rain.trade's shared session), skip
+`UpDownAccountKitSigner` and just make its output UpDown-correct:
+
+```ts
+import { bareErc1271Signer } from "@pulsepairs/sdk";
+const signOrder = bareErc1271Signer((td) => rainSmartWalletClient.signTypedData(td));
+const signature = await signOrder(buildOrderTypedData({ cfg, settlementAddress, message }));
+```
+
+---
+
+## Account Kit: the two rules you cannot break
+
+Both come from the on-chain verifier (OZ `SignatureChecker` v5.6.1, no EIP-6492):
+
+1. **Deploy the SCA before its first fill.** A counterfactual (undeployed)
+   account cannot be verified via ERC-1271 → the fill reverts. `onboard()` does
+   this (deploy + approve in one UserOp); `isDeployed(publicClient)` checks it.
+2. **Bare ERC-1271, not 6492.** `signTypedData` on an undeployed account can
+   return a 6492-wrapped blob the settlement can't parse. Every signature this
+   SDK produces is run through `stripErc6492Wrapper(...)`, so a wrapped blob
+   never reaches the matcher. (Exposed standalone too, for the callback path.)
+
+> **Confirmed live on Arbitrum One (2026-07-05/06).** A real SCA was deployed,
+> `isValidSignature` over the full Order typed-data returned the `0x1626ba7e`
+> magic on-chain, a real `enterPosition` fill settled with `maker = SCA`, and
+> the negative control (undeployed SCA) reverted as expected. The MA-v2 /
+> ERC-7739 question is resolved: sign the FULL typed-data through the account
+> client (which this SDK does); a bare-`bytes32` flow does not validate.
+
+---
+
+## Popup-less order signing (order sessions) — ON by default
+
+`UpDownAccountKitSigner` distinguishes **two different session-key mechanisms**
+— do not conflate them:
+
+1. **Send session** (`grantSession()`, Alchemy `grantPermissions` root) —
+   authorizes gasless UserOp *execution* (`onboard`/`approve`/`withdraw`).
+   Its signatures pack the OWNER validation entity, so it is verified
+   **incapable** of ERC-1271 order signing.
+2. **Order session** (default ON) — a locally-generated key installed on the
+   MA-v2 SCA as a **signature-validation-ONLY** entity
+   (`isSignatureValidation: true`, `isUserOpValidation: false`). It can only
+   answer `isValidSignature` for orders / cancels / WS-auth — it can **never
+   move funds or execute a UserOp**. `onboard()` batches the install into the
+   same single UserOp as deploy + approve (still exactly one owner signature),
+   after which orders sign with zero wallet popups.
+
+Behavior and knobs:
+
+- `signTypedDataBare` prefers the order-session key when one is active and
+  **falls back to the owner key automatically** on any failure — enabling this
+  feature can never break signing.
+- `ensureOrderSession()` installs a session for already-onboarded accounts
+  (one owner-signed UserOp); `revokeOrderSession()` drops the local key;
+  `hasOrderSession` inspects state.
+- Opt out entirely with `orderSessions: false` in the constructor — every
+  order then prompts the owner wallet (the pre-session behavior).
+- Storage: browser `localStorage` (`updown:oskey:<sca>`) by default, an
+  in-memory map in Node, or bring your own via `orderSessionStorage`.
+- **Known limitations** (fine for integration/demo, review before launch):
+  expiry is client-side only (24 h — not enforced on-chain), and
+  `revokeOrderSession()` does not uninstall the validation entity on-chain.
+
+Validated in 4 live PoC stages before shipping (on-chain `0x1626ba7e` +
+negative controls, live matcher order 201 + cancel 200, batched-install flow).
+
+---
+
+## `maxFee` (F-2026-17731) — REQUIRED on every order
+
+The signed `Order` includes `maxFee` (between `amount` and `nonce`). The
+contract's `ORDER_TYPEHASH` includes it, so **omitting it produces a signature
+the on-chain `SignatureChecker` rejects** — the fill reverts. Compute the peak
+fee and pass the same value into both the typed-data and the POST body:
+
+```ts
+const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n;
+```
+
+Signing the peak means legitimate (probability-weighted) fills never revert with
+`FeeExceedsTakerCap`; the contract enforces the *actual* cumulative fee under
+this cap across partial fills.
+
+---
+
+## API surface
+
+```
+Clients          UpDownHttpClient, UpDownWsClient, wsUrlFromHttpBase
+EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
+                 buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData,
+                 freshSessionId, domainForSettlement, findPairBySettlement,
+                 parseCompositeMarketKey
+Trade-math       centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic,
+                 MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC
+Approve (EOA)    ensureSettlementAllowance, MAX_UINT256
+Account Kit      UpDownAccountKitSigner (connect, onboard, approve, withdraw,
+                 signTypedDataBare, signWsAuth, isDeployed, grantSession,
+                 ensureOrderSession, revokeOrderSession, hasOrderSession),
+                 bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature
+L2 HMAC auth     CLOB_AUTH_TYPES, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS
+Enums/types      OrderType, OrderSide, Option, ApiConfig, PairConfig, PostOrderBody, …
+```
+
+---
+
+## Field-name gotchas (live with them)
+
+- `OrderRow.nonce` / `OrderRow.expiry` are JSON **strings** (uint256 precision).
+- WS `order_update` uses `orderType`; REST `OrderRow` uses `type`. Same value.
+- `Option` is `1 = UP`, `2 = DOWN` — not `0/1`.
+- Market addresses are composite `<settlementAddress>-<marketId>`. The signed
+  `Order.market` is the **bare uint256 marketId**; the composite goes in the
+  POST body's `market` field for routing only.
+- EIP-712 domain name is **`"UpDown Exchange"`**, `verifyingContract` = the
+  settlement contract, price in **bps** (not 1e18). WS-auth uses a distinct
+  domain (`"PulsePairs WebSocket Auth"`, `verifyingContract` = zero) so an order
+  signature can never replay as a WS-auth signature.
+
+---
+
+## Reference
+
+- **Wire shapes / REST / WS**: `docs/api.md` in the `updown-backend` repo
+  (branch `audit/hacken-remediation-v2`) — auth model, WS handshake, all
+  endpoints, error strings, rate limits.
+- **On-chain spec**: `src/UpDownSettlement.sol` in the `updown-contracts` repo
+  (same branch) — `ORDER_TYPEHASH`, `enterPosition`, fee cap enforcement.
+- **Schema drift guard**: `npm test` runs an EIP-712 golden-vector test whose
+  expected digest/signature were derived independently from the backend and
+  contract definitions.

package/dist/accountKit.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Account Kit (Alchemy smart-account) signing for the UpDown satellite.
+ *
+ * ─── Why this exists ─────────────────────────────────────────────────────
+ * rain.trade custody is Alchemy Account Kit (a smart-contract account, "SCA").
+ * The UpDown settlement verifies order signatures on-chain with OpenZeppelin
+ * `SignatureChecker.isValidSignatureNow(maker, digest, sig)` (OZ 5.6.1). When
+ * `maker` is an SCA, that routes to `IERC1271(maker).isValidSignature(...)`.
+ *
+ * To make one wallet span BOTH products, this module builds its own Alchemy
+ * smart-wallet client using the EXACT same config rain.trade's `RainAA` uses
+ * (same `chain` + `alchemyApiKey` + `paymasterPolicyId` + owner EOA). Account
+ * Kit derives the SCA address deterministically from (owner, factory), so the
+ * same owner + same config ⇒ the SAME account address ⇒ one shared wallet.
+ * We deliberately do NOT import `RainAA` — it is a published, unpatchable
+ * package that exposes no `signTypedData`, and the meeting locked UpDown as a
+ * *segregated* package. We mirror its config, not its code.
+ *
+ * ─── The two hard constraints (see UPDOWN_SDK_MEETING_PREP_OPTION_A) ─────
+ *  1. BARE ERC-1271, not EIP-6492. OZ `SignatureChecker` v5.6.1 is NOT
+ *     6492-aware. `signTypedData` on an *undeployed* SCA can return a
+ *     6492-wrapped blob that the settlement cannot parse → `enterPosition`
+ *     reverts. We therefore (a) enforce deploy-before-fill and (b) defensively
+ *     `stripErc6492Wrapper(...)` every signature so a wrapped blob never
+ *     reaches the matcher.
+ *  2. Two DIFFERENT session-key mechanisms — don't conflate them:
+ *     a. RainAA-style "send session" (`grantSession`, Alchemy
+ *        `grantPermissions({type:'root'})`): authorizes UserOp EXECUTION only.
+ *        Its signatures pack the OWNER validation entity, so it is verified
+ *        INCAPABLE of ERC-1271 order signing (isValidSignature → 0xffffffff;
+ *        see updown-demo/POC_SESSION_KEY_ORDERS_2026-07-06.md). Used only for
+ *        gasless *sends* (onboard / approve / withdraw), mirroring RainAA.
+ *     b. "ORDER session" (2026-07-06, PoC-validated on-chain + live API): a
+ *        locally-generated key installed on the MA-v2 SCA as a
+ *        SingleSignerValidationModule entity with isSignatureValidation=true
+ *        and isUserOpValidation=false — it can ONLY answer `isValidSignature`
+ *        (orders / cancels / ws-auth, popup-less) and can never execute a
+ *        UserOp. Installed inside the onboarding UserOp (one owner popup
+ *        total) or via `ensureOrderSession()`. Orders sign with it when
+ *        active; the OWNER client is the automatic fallback. Client-side 24h
+ *        expiry only (on-chain expiry needs a time-range hook — follow-up);
+ *        `revokeOrderSession()` drops the local key.
+ *
+ * ─── MUST be confirmed with a fork test before trusting on mainnet ───────
+ *   deploy a real Alchemy SCA on the target chain → `approve(settlement,USDT)`
+ *   → sign a real `Order` via `signTypedDataBare(...)` → call `enterPosition`
+ *   as the relayer → assert NO revert. Negative control: an *undeployed* SCA
+ *   and/or a 6492-wrapped signature MUST revert. This resolves the open
+ *   Light-Account-v2-vs-Modular-Account-v2 (ERC-7739) question: for MA v2 only
+ *   the account-level `signTypedData` over the FULL typed-data validates 1271
+ *   (handing the SCA a bare `bytes32` silently fails). `signTypedDataBare`
+ *   below signs the full typed-data, which is the correct path for both.
+ */
+import { type Address, type Chain, type Hex, type PublicClient, type TypedDataDefinition } from "viem";
+import type { WsAuthCredentials } from "./ws.js";
+/** True if `signature` is an EIP-6492-wrapped blob (ends with the magic suffix). */
+export declare function isErc6492Signature(signature: Hex): boolean;
+/**
+ * Return the BARE inner signature from an EIP-6492-wrapped blob, or the input
+ * unchanged if it is not wrapped. The 6492 layout is
+ * `abi.encode(address factory, bytes factoryCalldata, bytes signature)` with
+ * the 32-byte magic suffix appended. Once the SCA is deployed the bare inner
+ * signature is exactly what OZ `SignatureChecker` needs.
+ */
+export declare function stripErc6492Wrapper(signature: Hex): Hex;
+export type RawTypedDataSigner = (typedData: TypedDataDefinition) => Promise<Hex>;
+/**
+ * Wrap ANY raw typed-data signer so its output is a BARE ERC-1271 signature
+ * the UpDown settlement can verify. Use this when the host app already owns an
+ * Alchemy smart-wallet client (e.g. rain.trade's shared session) and just
+ * wants UpDown-correct order signatures without a second signer:
+ *
+ *   const signOrder = bareErc1271Signer((td) => rainSmartWalletClient.signTypedData(td));
+ *   const sig = await signOrder(buildOrderTypedData({ cfg, settlementAddress, message }));
+ *
+ * The SCA MUST be deployed on-chain before the signature is used in a fill.
+ */
+export declare function bareErc1271Signer(raw: RawTypedDataSigner): RawTypedDataSigner;
+/** EIP-1193 provider for the OWNER EOA (e.g. `window.ethereum`, or the
+ *  provider from a wagmi connector via `connector.getProvider()`). */
+export type Eip1193Provider = {
+    request: (args: {
+        method: string;
+        params?: unknown[] | object;
+    }) => Promise<unknown>;
+};
+export type UpDownAccountKitConfig = {
+    /** Provider for the owner EOA. Signs the owner ERC-1271 order signatures and
+     *  the one-time `grantSession` permission. */
+    walletClient: Eip1193Provider;
+    /** Alchemy API key (same one rain.trade uses — `VITE_ALCHEMY_API_KEY`). */
+    alchemyApiKey: string;
+    /**
+     * Alchemy Gas Manager policy id (`VITE_PAYMASTER_POLICY_ID`).
+     * - **Sponsorship-type** policy: pass the id alone — sends are app-sponsored.
+     * - **ERC-20-type** policy: also pass `gasToken` (the token the USER pays gas
+     *   in; must be on the policy's allowlist and held by the SCA).
+     * - **Omitted**: UserOps are SELF-PAID — the SCA must hold ETH for gas.
+     */
+    paymasterPolicyId?: string;
+    /** Gas token for an ERC-20-type Gas Manager policy (e.g. USDC). Ignored when
+     *  `paymasterPolicyId` is unset. */
+    gasToken?: {
+        tokenAddress: Address;
+    };
+    /** viem `Chain`. MUST equal rain.trade's RainAA chain (Arbitrum One, 42161)
+     *  to derive the SAME SCA address and share one wallet. */
+    chain: Chain;
+    /** Optional node RPC override; defaults to Alchemy's RPC for `chain`. */
+    rpcUrl?: string;
+    /** Popup-less ORDER-session signing (header §2b). Default true; set false to
+     *  force owner-key signing per order (the pre-2026-07-06 behavior). */
+    orderSessions?: boolean;
+    /** Where the order-session key persists. Defaults to `globalThis.localStorage`
+     *  when available (browser), else an in-memory map (Node — session lives for
+     *  the process). Keys are namespaced `updown:oskey:<sca>`. */
+    orderSessionStorage?: {
+        getItem: (k: string) => string | null;
+        setItem: (k: string, v: string) => void;
+        removeItem: (k: string) => void;
+    };
+};
+export type GrantSessionResult = {
+    privateKey: Hex;
+    sessionKeyAddress: Address;
+    context: Hex;
+    expirySec: number;
+};
+/**
+ * Owner-key ERC-1271 order signer + gasless custody sends on an Alchemy SCA.
+ *
+ * Lifecycle:
+ *   const ak = new UpDownAccountKitSigner({ walletClient, alchemyApiKey, paymasterPolicyId, chain });
+ *   const sca = await ak.connect();                    // SCA address (order.maker)
+ *   await ak.onboard({ usdt, settlement });            // deploy SCA + approve USDT (one UserOp)
+ *   const sig = await ak.signTypedDataBare(orderTypedData);   // owner ERC-1271, bare
+ *
+ * All Account Kit packages are lazy-imported peer deps (mirrors RainAA), so
+ * importing this module never pulls `@account-kit/*` unless you call `connect`.
+ */
+export declare class UpDownAccountKitSigner {
+    private readonly config;
+    private _client;
+    private _sessionClient;
+    private _account;
+    private _address;
+    private _ownerEoa;
+    private _sessionContext;
+    private _sessionKeyAddress;
+    private _sessionPrivateKey;
+    private _sessionExpirySec;
+    private _orderSession;
+    private _orderSessionClient;
+    private _mods;
+    constructor(config: UpDownAccountKitConfig);
+    /**
+     * Create the owner smart-wallet client and resolve the SCA address. Does NOT
+     * prompt for a session — call `grantSession()` (or `onboard`, which grants
+     * as needed) before gasless sends. Order signing works immediately (owner key).
+     */
+    connect(): Promise<Address>;
+    /** The SCA address — this is `order.maker`, the deposit address, and the
+     *  ERC-1271 signer. Identical to rain.trade's SCA for the same owner. */
+    get address(): Address;
+    /** Owner EOA address (signs the ERC-1271 order signatures under the hood). */
+    get ownerEoa(): Address;
+    /** The owner smart-wallet client. Exposes `signTypedData`, `sendCalls`, etc. */
+    get ownerClient(): any;
+    get hasActiveSession(): boolean;
+    /**
+     * EIP-712 typed data as a BARE ERC-1271 signature — the ONLY signing path
+     * for orders, cancels, and ws-auth. ORDER-session-signed (popup-less) when
+     * an order session is active (header §2b); owner-signed with the 6492
+     * wrapper stripped otherwise. Requires `connect()`; the SCA should be
+     * deployed (`onboard`) before the signature is used in a fill.
+     */
+    signTypedDataBare(typedData: TypedDataDefinition): Promise<Hex>;
+    private get orderSessionsEnabled();
+    private get orderSessionStore();
+    /** True iff an unexpired order session exists for the connected SCA. */
+    get hasOrderSession(): boolean;
+    private readOrderSession;
+    private persistOrderSession;
+    /** Drop the local order-session key (no on-chain uninstall — follow-up). */
+    revokeOrderSession(): void;
+    /**
+     * Sign typed data with the order-session key (MA-v2 entity signature, bare
+     * by construction). Returns null when no session is active or anything
+     * fails — `signTypedDataBare` falls back to the owner path.
+     */
+    private orderSessionSign;
+    /** Lazily build the MA-v2 client bound to the order-session key's entity. */
+    private orderSessionAccount;
+    /**
+     * Make sure an order session exists: no-op when one is active (or the
+     * feature is off), otherwise install a fresh session key via a one-time
+     * owner UserOp. Fresh users get the install batched into `onboard()` and
+     * never hit the UserOp here. Throws if the owner rejects; callers should
+     * treat that as non-fatal (owner-key signing keeps working).
+     */
+    ensureOrderSession(): Promise<"disabled" | "active" | "installed">;
+    /**
+     * Build the `installValidation` self-call that registers a fresh session
+     * key on the SCA as a signature-validation-ONLY entity (validated flow:
+     * updown-frontend/scripts/poc-session-key-fe-flow.mjs).
+     */
+    private buildOrderSessionInstallCall;
+    /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
+    private infraChain;
+    /**
+     * Build + owner-sign a WS-auth handshake and package it as `WsAuthCredentials`
+     * for `UpDownWsClient.connectAuthed({ signAuth })`. `wallet` is the SCA
+     * address (private channels are keyed by the SCA, the trading identity).
+     */
+    signWsAuth(chainId: number): Promise<WsAuthCredentials>;
+    /** True iff the SCA has bytecode on-chain (deploy-before-fill precondition). */
+    isDeployed(publicClient: PublicClient): Promise<boolean>;
+    /**
+     * Grant a 24h session key (one MetaMask popup) so subsequent sends are
+     * gasless + popup-less. Mirrors RainAA's `grantSession`; safe to call when a
+     * session is already active (returns the existing one without prompting).
+     */
+    grantSession(): Promise<GrantSessionResult>;
+    /**
+     * One-time onboarding: DEPLOY the SCA, `approve(settlement, USDT, MAX)` AND
+     * install the order-session key (header §2b), all in a single UserOp —
+     * still exactly one owner signature. Satisfies deploy-before-fill + the
+     * allowance `enterPosition` needs, and makes subsequent order signatures
+     * popup-less. Order-session prep failures degrade to plain deploy+approve
+     * (owner-key signing per order). Uses the owner client so it works before
+     * any session exists; deployment is carried by the account init-code.
+     */
+    onboard(args: {
+        usdt: Address;
+        settlement: Address;
+    }): Promise<Hex>;
+    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    approve(args: {
+        usdt: Address;
+        settlement: Address;
+    }): Promise<Hex>;
+    /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
+    withdraw(args: {
+        usdt: Address;
+        to: Address;
+        amount: bigint;
+    }): Promise<Hex>;
+    /**
+     * Send a single call from the SCA as a UserOp. Gas is paid per the config:
+     * sponsorship policy → app-sponsored; ERC-20 policy + `gasToken` → user pays
+     * in that token; no policy → SELF-PAID (SCA must hold ETH). Prefers the
+     * session client (no popup) when a session is active; otherwise falls back
+     * to the owner client (one signature). Returns the on-chain tx hash.
+     */
+    sendCall(call: {
+        to: Address;
+        data: Hex;
+        value?: bigint;
+    }): Promise<Hex>;
+    /** Send one UserOp batching `calls` in order (same gas/session semantics as
+     *  `sendCall`); returns the on-chain tx hash. */
+    private sendCalls;
+    /** Clear in-memory state (persisted sessions, if any, are left intact). */
+    disconnect(): void;
+}