@pulsepairs/sdk 0.2.0

package/dist/accountKit.js

@@ -0,0 +1,638 @@
+/**
+ * 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 { decodeAbiParameters, } from "viem";
+import { buildWsAuthTypedData, freshSessionId } from "./eip712.js";
+/* ───────────────────────── EIP-6492 unwrap ───────────────────────── */
+/** The 32-byte EIP-6492 magic suffix (hex, no `0x`). */
+const ERC6492_MAGIC = "6492649264926492649264926492649264926492649264926492649264926492";
+/** True if `signature` is an EIP-6492-wrapped blob (ends with the magic suffix). */
+export function isErc6492Signature(signature) {
+    return signature.length >= 66 && signature.slice(-64).toLowerCase() === ERC6492_MAGIC;
+}
+/**
+ * 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 function stripErc6492Wrapper(signature) {
+    if (!isErc6492Signature(signature))
+        return signature;
+    const body = ("0x" + signature.slice(2, signature.length - 64));
+    const [, , inner] = decodeAbiParameters([{ type: "address" }, { type: "bytes" }, { type: "bytes" }], body);
+    return inner;
+}
+/**
+ * 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 function bareErc1271Signer(raw) {
+    return async (typedData) => stripErc6492Wrapper(await raw(typedData));
+}
+const SESSION_DURATION_SEC = 60 * 60 * 24; // 24h — matches RainAA
+/* ─────────────── ORDER-session (header §2b) storage ─────────────── */
+const ORDER_SESSION_TTL_SEC = 60 * 60 * 24; // 24h, client-side only
+function orderSessionKey(sca) {
+    return `updown:oskey:${sca.toLowerCase()}`;
+}
+const memoryStore = new Map();
+function defaultOrderSessionStorage() {
+    const ls = globalThis.localStorage;
+    if (ls) {
+        return {
+            getItem: (k) => {
+                try {
+                    return ls.getItem(k);
+                }
+                catch {
+                    return null;
+                }
+            },
+            setItem: (k, v) => {
+                try {
+                    ls.setItem(k, v);
+                }
+                catch { /* private mode — session lives this tab only */ }
+            },
+            removeItem: (k) => {
+                try {
+                    ls.removeItem(k);
+                }
+                catch { /* best effort */ }
+            },
+        };
+    }
+    return {
+        getItem: (k) => memoryStore.get(k) ?? null,
+        setItem: (k, v) => void memoryStore.set(k, v),
+        removeItem: (k) => void memoryStore.delete(k),
+    };
+}
+/** Shared SCA-address cache key (identical to rain.trade's `useRain`). */
+function saCacheKey(eoa) {
+    return `rain:sa:${eoa.toLowerCase()}`;
+}
+function readCachedSA(eoa) {
+    try {
+        const ls = globalThis.localStorage;
+        const v = ls?.getItem(saCacheKey(eoa)) ?? null;
+        return v && /^0x[0-9a-fA-F]{40}$/.test(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedSA(eoa, addr) {
+    try {
+        globalThis.localStorage?.setItem(saCacheKey(eoa), addr);
+    }
+    catch {
+        /* private mode / SSR — best effort */
+    }
+}
+/**
+ * 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 class UpDownAccountKitSigner {
+    config;
+    _client = null; // owner smart-wallet client
+    _sessionClient = null; // session-key smart-wallet client
+    _account = null;
+    _address = null;
+    _ownerEoa = null;
+    _sessionContext = null;
+    _sessionKeyAddress = null;
+    _sessionPrivateKey = null;
+    _sessionExpirySec = null;
+    // ORDER session (header §2b) — distinct from the RainAA send-session above.
+    _orderSession = null;
+    _orderSessionClient = null;
+    _mods = null;
+    constructor(config) {
+        if (!config.walletClient)
+            throw new Error("walletClient (owner EIP-1193 provider) is required");
+        if (!config.alchemyApiKey)
+            throw new Error("alchemyApiKey is required");
+        if (!config.chain)
+            throw new Error("chain is required");
+        this.config = config;
+    }
+    /**
+     * 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).
+     */
+    async connect() {
+        if (this._address && this._client)
+            return this._address;
+        const [aaCore, infraMod, walletClientLib, viemAccounts] = await Promise.all([
+            // @ts-ignore peer dep, provided by the host app (rain.trade already ships it)
+            import("@aa-sdk/core"),
+            // @ts-ignore peer dep
+            import("@account-kit/infra"),
+            // @ts-ignore peer dep
+            import("@account-kit/wallet-client"),
+            // @ts-ignore viem subpath
+            import("viem/accounts"),
+        ]);
+        const { WalletClientSigner, LocalAccountSigner } = aaCore;
+        const { alchemy, defineAlchemyChain } = infraMod;
+        const { createSmartWalletClient } = walletClientLib;
+        // @ts-ignore viem subpath
+        const { createWalletClient, custom } = await import("viem");
+        const alchemyChain = defineAlchemyChain({
+            chain: this.config.chain,
+            rpcBaseUrl: `https://${this.config.chain.id === 42161 ? "arb-mainnet" : "arb-sepolia"}.g.alchemy.com/v2`,
+        });
+        const eoaSigner = new WalletClientSigner(createWalletClient({ transport: custom(this.config.walletClient) }), "wallet");
+        const eoaClient = createSmartWalletClient({
+            chain: alchemyChain,
+            signer: eoaSigner,
+            ...(this.config.paymasterPolicyId ? { policyId: this.config.paymasterPolicyId } : {}),
+            transport: alchemy({ apiKey: this.config.alchemyApiKey, nodeRpcUrl: this.config.rpcUrl }),
+        });
+        const account = await eoaClient.requestAccount();
+        if (!account?.address)
+            throw new Error("Failed to resolve Alchemy smart account");
+        this._client = eoaClient;
+        this._account = account;
+        this._address = account.address;
+        this._ownerEoa = (await eoaSigner.getAddress());
+        this._mods = {
+            createSmartWalletClient,
+            alchemy,
+            defineAlchemyChain,
+            WalletClientSigner,
+            LocalAccountSigner,
+            viemAccounts,
+            alchemyChain,
+        };
+        writeCachedSA(this._ownerEoa, this._address);
+        return this._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() {
+        if (!this._address)
+            throw new Error("Not connected. Call connect() first.");
+        return this._address;
+    }
+    /** Owner EOA address (signs the ERC-1271 order signatures under the hood). */
+    get ownerEoa() {
+        if (!this._ownerEoa)
+            throw new Error("Not connected. Call connect() first.");
+        return this._ownerEoa;
+    }
+    /** The owner smart-wallet client. Exposes `signTypedData`, `sendCalls`, etc. */
+    get ownerClient() {
+        if (!this._client)
+            throw new Error("Not connected. Call connect() first.");
+        return this._client;
+    }
+    get hasActiveSession() {
+        return !!this._sessionExpirySec && this._sessionExpirySec > Math.floor(Date.now() / 1000);
+    }
+    /**
+     * 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.
+     */
+    async signTypedDataBare(typedData) {
+        if (!this._client || !this._address)
+            throw new Error("Not connected. Call connect() first.");
+        const session = await this.orderSessionSign(typedData);
+        if (session)
+            return session;
+        const raw = (await this._client.signTypedData({
+            ...typedData,
+            account: this._address,
+        }));
+        return stripErc6492Wrapper(raw);
+    }
+    /* ─────────────── ORDER session (header §2b) ─────────────── */
+    get orderSessionsEnabled() {
+        return this.config.orderSessions !== false;
+    }
+    get orderSessionStore() {
+        return this.config.orderSessionStorage ?? defaultOrderSessionStorage();
+    }
+    /** True iff an unexpired order session exists for the connected SCA. */
+    get hasOrderSession() {
+        if (!this.orderSessionsEnabled || !this._address)
+            return false;
+        return !!(this._orderSession ?? this.readOrderSession());
+    }
+    readOrderSession() {
+        if (!this._address)
+            return null;
+        try {
+            const raw = this.orderSessionStore.getItem(orderSessionKey(this._address));
+            if (!raw)
+                return null;
+            const rec = JSON.parse(raw);
+            if (rec?.v !== 1 || typeof rec.privateKey !== "string" || !rec.entityId)
+                return null;
+            if (rec.expirySec <= Math.floor(Date.now() / 1000)) {
+                this.orderSessionStore.removeItem(orderSessionKey(this._address));
+                return null;
+            }
+            return rec;
+        }
+        catch {
+            return null;
+        }
+    }
+    persistOrderSession(record) {
+        if (!this._address)
+            return;
+        this.orderSessionStore.setItem(orderSessionKey(this._address), JSON.stringify(record));
+        this._orderSession = record;
+        this._orderSessionClient = null; // built lazily on first sign
+    }
+    /** Drop the local order-session key (no on-chain uninstall — follow-up). */
+    revokeOrderSession() {
+        if (this._address)
+            this.orderSessionStore.removeItem(orderSessionKey(this._address));
+        this._orderSession = null;
+        this._orderSessionClient = null;
+    }
+    /**
+     * 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.
+     */
+    async orderSessionSign(typedData) {
+        try {
+            const account = await this.orderSessionAccount();
+            if (!account)
+                return null;
+            return (await account.signTypedData(typedData));
+        }
+        catch {
+            this._orderSessionClient = null; // rebuild lazily; don't wedge signing
+            return null;
+        }
+    }
+    /** Lazily build the MA-v2 client bound to the order-session key's entity. */
+    async orderSessionAccount() {
+        if (!this.orderSessionsEnabled || !this._address)
+            return null;
+        const rec = this._orderSession ?? this.readOrderSession();
+        if (!rec)
+            return null;
+        if (rec.expirySec <= Math.floor(Date.now() / 1000)) {
+            this.revokeOrderSession();
+            return null;
+        }
+        this._orderSession = rec;
+        if (!this._orderSessionClient) {
+            const [aaCore, scMod, infraMod] = await Promise.all([
+                // @ts-ignore peer dep
+                import("@aa-sdk/core"),
+                // @ts-ignore peer dep
+                import("@account-kit/smart-contracts"),
+                // @ts-ignore peer dep
+                import("@account-kit/infra"),
+            ]);
+            const { LocalAccountSigner } = aaCore;
+            const { createModularAccountV2Client } = scMod;
+            const { alchemy } = infraMod;
+            this._orderSessionClient = await createModularAccountV2Client({
+                mode: "default",
+                chain: await this.infraChain(),
+                transport: alchemy({ apiKey: this.config.alchemyApiKey }),
+                signer: LocalAccountSigner.privateKeyToAccountSigner(rec.privateKey),
+                accountAddress: this._address,
+                signerEntity: { entityId: rec.entityId, isGlobalValidation: false },
+            });
+        }
+        return this._orderSessionClient.account;
+    }
+    /**
+     * 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).
+     */
+    async ensureOrderSession() {
+        if (!this.orderSessionsEnabled)
+            return "disabled";
+        if (!this._client || !this._address)
+            throw new Error("Not connected. Call connect() first.");
+        if (await this.orderSessionAccount())
+            return "active";
+        const { call, record } = await this.buildOrderSessionInstallCall();
+        await this.sendCalls([call]);
+        this.persistOrderSession(record);
+        return "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).
+     */
+    async buildOrderSessionInstallCall() {
+        const [viemAccounts, expMod, viemMod] = await Promise.all([
+            // @ts-ignore viem subpath
+            import("viem/accounts"),
+            // @ts-ignore peer dep
+            import("@account-kit/smart-contracts/experimental"),
+            // @ts-ignore viem
+            import("viem"),
+        ]);
+        const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
+        const { getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule, serializeValidationConfig, semiModularAccountBytecodeAbi, } = expMod;
+        const privateKey = generatePrivateKey();
+        const sessionAddress = privateKeyToAccount(privateKey).address;
+        // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
+        // id that already exists on the account reverts — random keeps collisions
+        // with prior sessions (lost storage, other hosts) vanishingly unlikely.
+        const entityId = 2 + Math.floor(Math.random() * 0x7ffffff0);
+        const data = viemMod.encodeFunctionData({
+            abi: semiModularAccountBytecodeAbi,
+            functionName: "installValidation",
+            args: [
+                serializeValidationConfig({
+                    moduleAddress: getDefaultSingleSignerValidationModuleAddress(await this.infraChain()),
+                    entityId,
+                    isGlobal: false,
+                    isSignatureValidation: true, // can answer ERC-1271…
+                    isUserOpValidation: false, // …but can never execute a UserOp
+                }),
+                [],
+                SingleSignerValidationModule.encodeOnInstallData({ entityId, signer: sessionAddress }),
+                [],
+            ],
+        });
+        return {
+            call: { to: this.address, data },
+            record: { v: 1, privateKey, entityId, expirySec: Math.floor(Date.now() / 1000) + ORDER_SESSION_TTL_SEC },
+        };
+    }
+    /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
+    async infraChain() {
+        // @ts-ignore peer dep
+        const infra = (await import("@account-kit/infra"));
+        return this.config.chain.id === 421614 ? infra.arbitrumSepolia : infra.arbitrum;
+    }
+    /**
+     * 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).
+     */
+    async signWsAuth(chainId) {
+        if (!this._address)
+            throw new Error("Not connected. Call connect() first.");
+        const timestamp = BigInt(Math.floor(Date.now() / 1000));
+        const sessionId = freshSessionId();
+        const typedData = buildWsAuthTypedData({
+            cfg: { chainId },
+            wallet: this._address,
+            timestamp,
+            sessionId,
+        });
+        const signature = await this.signTypedDataBare(typedData);
+        return { wallet: this._address, timestamp, sessionId, signature };
+    }
+    /** True iff the SCA has bytecode on-chain (deploy-before-fill precondition). */
+    async isDeployed(publicClient) {
+        if (!this._address)
+            throw new Error("Not connected. Call connect() first.");
+        const code = await publicClient.getBytecode({ address: this._address });
+        return !!code && code !== "0x";
+    }
+    /**
+     * 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).
+     */
+    async grantSession() {
+        if (!this._client || !this._address || !this._mods) {
+            throw new Error("Not connected. Call connect() first.");
+        }
+        if (this.hasActiveSession &&
+            this._sessionPrivateKey &&
+            this._sessionKeyAddress &&
+            this._sessionContext &&
+            this._sessionExpirySec) {
+            return {
+                privateKey: this._sessionPrivateKey,
+                sessionKeyAddress: this._sessionKeyAddress,
+                context: this._sessionContext,
+                expirySec: this._sessionExpirySec,
+            };
+        }
+        const { createSmartWalletClient, alchemy, alchemyChain, LocalAccountSigner, viemAccounts } = this._mods;
+        const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
+        const privateKey = generatePrivateKey();
+        const sessionAccount = privateKeyToAccount(privateKey);
+        const expirySec = Math.floor(Date.now() / 1000) + SESSION_DURATION_SEC;
+        const result = await this._client.grantPermissions({
+            account: this._address,
+            expirySec,
+            key: { publicKey: sessionAccount.address, type: "secp256k1" },
+            permissions: [{ type: "root" }],
+        });
+        this._sessionPrivateKey = privateKey;
+        this._sessionKeyAddress = sessionAccount.address;
+        this._sessionExpirySec = expirySec;
+        this._sessionContext = result.context;
+        this._sessionClient = createSmartWalletClient({
+            chain: alchemyChain,
+            signer: new LocalAccountSigner(sessionAccount),
+            ...(this.config.paymasterPolicyId ? { policyId: this.config.paymasterPolicyId } : {}),
+            transport: alchemy({ apiKey: this.config.alchemyApiKey, nodeRpcUrl: this.config.rpcUrl }),
+        });
+        return {
+            privateKey,
+            sessionKeyAddress: this._sessionKeyAddress,
+            context: this._sessionContext,
+            expirySec,
+        };
+    }
+    /**
+     * 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.
+     */
+    async onboard(args) {
+        const calls = [
+            { to: args.usdt, data: encodeApprove(args.settlement) },
+        ];
+        let record = null;
+        if (this.orderSessionsEnabled && !(await this.orderSessionAccount().catch(() => null))) {
+            try {
+                const built = await this.buildOrderSessionInstallCall();
+                calls.push(built.call);
+                record = built.record;
+            }
+            catch {
+                /* onboarding proceeds without a session — owner-key signing stays */
+            }
+        }
+        const txHash = await this.sendCalls(calls);
+        if (record)
+            this.persistOrderSession(record);
+        return txHash;
+    }
+    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    async approve(args) {
+        return this.sendCall({ to: args.usdt, data: encodeApprove(args.settlement) });
+    }
+    /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
+    async withdraw(args) {
+        return this.sendCall({ to: args.usdt, data: encodeTransfer(args.to, args.amount) });
+    }
+    /**
+     * 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.
+     */
+    async sendCall(call) {
+        return this.sendCalls([call]);
+    }
+    /** Send one UserOp batching `calls` in order (same gas/session semantics as
+     *  `sendCall`); returns the on-chain tx hash. */
+    async sendCalls(calls) {
+        if (!this._client || !this._account || !this._address) {
+            throw new Error("Not connected. Call connect() first.");
+        }
+        // @ts-ignore viem subpath
+        const { toHex } = await import("viem");
+        const useSession = this.hasActiveSession && this._sessionClient && this._sessionContext;
+        const client = useSession ? this._sessionClient : this._client;
+        const capabilities = {};
+        if (useSession)
+            capabilities.permissions = { context: this._sessionContext };
+        if (this.config.paymasterPolicyId && this.config.gasToken) {
+            // ERC-20-type Gas Manager policy: the request must carry the erc20
+            // capability naming the token the SCA pays gas in, else Alchemy rejects
+            // with "erc20 capability is missing". autoApprove injects the exact
+            // paymaster approval into the batch.
+            capabilities.paymasterService = {
+                policyId: this.config.paymasterPolicyId,
+                erc20: {
+                    tokenAddress: this.config.gasToken.tokenAddress,
+                    postOpSettings: { autoApprove: true },
+                },
+            };
+        }
+        const { id } = await client.sendCalls({
+            from: this._address,
+            calls: calls.map((c) => ({ to: c.to, data: c.data, value: toHex(c.value ?? 0n) })),
+            ...(Object.keys(capabilities).length ? { capabilities } : {}),
+        });
+        const status = await client.waitForCallsStatus({ id });
+        const txHash = status.receipts?.[0]?.transactionHash;
+        if (!txHash)
+            throw new Error(`UserOp ${id} returned no transaction hash`);
+        return txHash;
+    }
+    /** Clear in-memory state (persisted sessions, if any, are left intact). */
+    disconnect() {
+        this._client = null;
+        this._sessionClient = null;
+        this._account = null;
+        this._address = null;
+        this._ownerEoa = null;
+        this._sessionContext = null;
+        this._sessionKeyAddress = null;
+        this._sessionPrivateKey = null;
+        this._sessionExpirySec = null;
+        this._orderSession = null;
+        this._orderSessionClient = null;
+        this._mods = null;
+    }
+}
+/* ───────────────────────── calldata encoders ───────────────────────── */
+const MAX_UINT256 = (1n << 256n) - 1n;
+function encodeApprove(spender) {
+    // approve(address,uint256) selector 0x095ea7b3
+    return ("0x095ea7b3" + pad(spender) + pad(MAX_UINT256));
+}
+function encodeTransfer(to, amount) {
+    // transfer(address,uint256) selector 0xa9059cbb
+    return ("0xa9059cbb" + pad(to) + pad(amount));
+}
+/** Left-pad an address or bigint to a 32-byte (64-hex) ABI word. */
+function pad(v) {
+    const hex = typeof v === "bigint" ? v.toString(16) : v.toLowerCase().replace(/^0x/, "");
+    return hex.padStart(64, "0");
+}

package/dist/approve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One-time USDT.approve(settlement, MaxUint256) helper.
+ *
+ * Path-1 settlement pulls USDT directly from the maker via `transferFrom`
+ * inside `enterPosition`. Without this approval the first BUY reverts
+ * with `ERC20: insufficient allowance`. Idempotent: reads current
+ * allowance and only submits a tx when below threshold.
+ *
+ * `viem` is a peer dependency — pass in the public + wallet clients you
+ * already have so this helper doesn't bake in a transport choice.
+ */
+import type { Address, PublicClient, WalletClient } from "viem";
+export declare const MAX_UINT256: bigint;
+export type EnsureAllowanceResult = {
+    status: "already_ok";
+    allowance: bigint;
+} | {
+    status: "approved";
+    txHash: `0x${string}`;
+    allowance: bigint;
+};
+/**
+ * Ensure the maker has enough USDT allowance on the settlement contract.
+ *
+ * @param args.publicClient — viem `createPublicClient(...)` for reads.
+ * @param args.walletClient — viem `createWalletClient({ account, ... })`
+ *                            with the maker's account (must have ETH for gas).
+ * @param args.usdt — USDT token address (from `cfg.usdtAddress`).
+ * @param args.settlement — Settlement contract address (from
+ *                          `cfg.pairs[0].settlementAddress` for today's
+ *                          single-settlement deploy).
+ * @param args.threshold — Re-approve when current allowance is below this
+ *                         atomic-USDT amount. Default 10,000 USDT.
+ *
+ * Returns `already_ok` if nothing needed to be done, `approved` with the
+ * tx hash if a new approval was sent. Caller can `await
+ * publicClient.waitForTransactionReceipt({ hash })` if it wants to confirm
+ * before placing orders.
+ */
+export declare function ensureSettlementAllowance(args: {
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    usdt: Address;
+    settlement: Address;
+    threshold?: bigint;
+}): Promise<EnsureAllowanceResult>;